reference

Documentation

Overview

Package reference defines the named-pointer record: a global name pointing at a store key, with creator, creation time, and an optional opaque signature. Encoding is RFC 8949 §4.2 core-deterministic CBOR, matching the fstree object convention (canonical map, integer keys).

Index

• Constants
• func ValidateName(name string) error
• func ValidateUser(user string) error
• type Reference
  • func Decode(b []byte) (Reference, error)
  • func (r Reference) Encode() ([]byte, error)
  • func (r Reference) SignaturePayload() ([]byte, error)

Constants

const MaxNameLen = 1024

MaxNameLen is the maximum reference name length in bytes.

const MaxPublicKeyLen = 16 << 10

MaxPublicKeyLen is the maximum PublicKey field length in bytes (16 KiB).

const MaxSignatureLen = 64 << 10

MaxSignatureLen is the maximum Signature field length in bytes (64 KiB).

const MaxUserLen = 1024

MaxUserLen is the maximum User field length in bytes.

Functions

func ValidateName

func ValidateName(name string) error

ValidateName checks the reference-name rules: 1..MaxNameLen bytes of valid UTF-8, no '@' (the ref/path separator) and no control characters. '/' is allowed; names are opaque strings with no structural meaning.

func ValidateUser

func ValidateUser(user string) error

ValidateUser checks the user-identity rules used both by config-user and by Reference records: 1..MaxUserLen bytes of valid UTF-8 with no control characters. '@' is explicitly allowed so that e-mail addresses are valid.

Note: an empty User in a Reference record remains valid at the record level (ValidateUser is only called from validate() when r.User != ""). ValidateUser itself rejects empty so that config-user always stores a usable identity.

Types

type Reference

type Reference struct {
	Name      string `cbor:"0,keyasint"`
	Key       []byte `cbor:"1,keyasint"` // 32-byte canonical store key
	User      string `cbor:"2,keyasint"`
	CreatedAt int64  `cbor:"3,keyasint"` // ns since the Unix epoch
	Signature []byte `cbor:"4,keyasint,omitempty"`
	PublicKey []byte `cbor:"5,keyasint,omitempty"` // signer's key, SSH wire format
}

Reference is the record stored under a name. Fields are encoded as a canonical CBOR map with integer keys 0-5; Signature (key 4) and PublicKey (key 5) are omitted when absent. The signature payload is the encoding without key 4 only, so a signature covers the public key it was made with.

func Decode

func Decode(b []byte) (Reference, error)

Decode parses and validates a record. It rejects non-canonical encodings: the input must be byte-for-byte identical to what encMode would produce for the same record (extra map keys, indefinite-length items, and non-minimal integer/length encodings are all rejected).

func (Reference) Encode

func (r Reference) Encode() ([]byte, error)

Encode returns the deterministic CBOR encoding of a validated record.

func (Reference) SignaturePayload

func (r Reference) SignaturePayload() ([]byte, error)

SignaturePayload returns the bytes a signature runs over: the deterministic encoding of the record without its Signature field. PublicKey stays in, so the payload binds the signer's key; set it before computing the payload.