bundlesig

package
v0.72.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package bundlesig implements the detached-signature sidecar format and the Ed25519 verification rules of Spec 101 (contracts/sidecar-format.md).

It is a pure leaf package: no file I/O, no globals, stdlib only, and it must not import internal/security/scanner. The scanner decides what to do with a verification outcome (which authority is active, rollback, activation); this package only answers "is this sidecar well-formed" and "did this key sign exactly these bytes", and does so with a stable machine-readable code for every refusal so two implementations can be shown to reject identically.

Index

Constants

View Source
const (
	CodeSidecarTooLarge             = "sidecar_too_large"             // row 1
	CodeSidecarMalformed            = "sidecar_malformed"             // row 2
	CodeSidecarMissingField         = "sidecar_missing_field"         // row 3
	CodeSidecarUnknownField         = "sidecar_unknown_field"         // row 4
	CodeSidecarDuplicateField       = "sidecar_duplicate_field"       // row 5
	CodeSidecarType                 = "sidecar_type"                  // row 6
	CodeSidecarVersionUnsupported   = "sidecar_version_unsupported"   // row 7
	CodeSidecarAlgorithmUnsupported = "sidecar_algorithm_unsupported" // row 8
	CodeSidecarKeyIDMalformed       = "sidecar_key_id_malformed"      // row 9
	CodeSidecarSignatureMalformed   = "sidecar_signature_malformed"   // row 10
	CodeKeyNotTrusted               = "key_not_trusted"               // row 11
	CodeSignatureInvalid            = "signature_invalid"             // row 12
	CodeKeyIDMismatch               = "key_id_mismatch"               // row 13
)

Rejection codes, one per contract row 1..13. They are part of the wire contract (surfaced as LastRejection reasons) and must not be renamed.

View Source
const MaxSidecarBytes = 4096

MaxSidecarBytes is the FR-011 cap on a sidecar. It is checked before any parsing because the sidecar is read before anything is authenticated.

Variables

This section is empty.

Functions

func CheckKeyIDAgreement

func CheckKeyIDAgreement(manifestKeyID string, sc *Sidecar, verified Key) error

CheckKeyIDAgreement enforces row 13: the manifest's key_id, the sidecar's key_id and the verifying key's id must all be identical. An empty manifest key id is a mismatch, never "unspecified".

func CodeOf

func CodeOf(err error) string

CodeOf returns the contract reason code carried by err (looking through wrapping), or "" when err is nil or not a bundlesig rejection.

func KeyID

func KeyID(pub ed25519.PublicKey) string

KeyID returns the fingerprint of an Ed25519 public key: the lowercase hex SHA-256 of its 32 raw bytes. It is a property of the key itself, never an operator-chosen label, which is what makes "manifest names one publisher, bytes signed by another" detectable.

func ParsePublicKey

func ParsePublicKey(s string) (ed25519.PublicKey, error)

ParsePublicKey decodes a configured signer: standard padded base64 of exactly 32 bytes. Like the sidecar signature it must be strict and canonical, so a trust anchor cannot be spelled two ways.

func SignSidecar

func SignSidecar(priv ed25519.PrivateKey, bundle []byte) []byte

SignSidecar returns the canonical sidecar for bundle: one line, keys in the order sidecar_version, algorithm, key_id, signature, no trailing newline. It exists for publishers and tests; the loader never signs anything.

Types

type Error

type Error struct {
	Code   string
	Detail string
}

Error is a contract rejection carrying its stable reason code. Detail is human-oriented context and never part of the contract.

func (*Error) Error

func (e *Error) Error() string

type Key

type Key struct {
	ID        string
	Public    ed25519.PublicKey
	Authority string
}

Key is one trusted signer. Authority names the root it belongs to; this package stores it and hands it back but attaches no meaning to it.

type Sidecar

type Sidecar struct {
	Version   string
	Algorithm string
	KeyID     string
	Signature []byte
}

Sidecar is a parsed, grammar-valid sidecar. Parsing proves only that the sidecar is well-formed; nothing here is authenticated until TrustSet.Verify succeeds.

func ParseSidecar

func ParseSidecar(b []byte) (*Sidecar, error)

ParseSidecar parses sidecar bytes under the contract's total grammar, evaluating rows 1..10 in numerical order; the first matching row wins so overlapping conditions (e.g. {"foo":1} is both missing-a-field and has-an-unknown-key) always report the same reason.

JSON whitespace around the object is tolerated (a trailing newline is normal); any other trailing byte is sidecar_malformed.

type TrustSet

type TrustSet struct {
	// contains filtered or unexported fields
}

TrustSet is an immutable set of trusted keys indexed by key id.

func NewTrustSet

func NewTrustSet(keys ...Key) (*TrustSet, error)

NewTrustSet validates and indexes keys. It refuses a wrong-length key, a key whose ID is not the fingerprint of its Public bytes, and a duplicate id even across authorities: a single key must not be able to satisfy whichever root happens to be active. It copies the key bytes, so later mutation of the caller's slices cannot change what verifies.

func (*TrustSet) Lookup

func (t *TrustSet) Lookup(id string) (Key, bool)

Lookup returns the key with the given id. The returned Public is a copy.

func (*TrustSet) Verify

func (t *TrustSet) Verify(bundle []byte, sc *Sidecar) (Key, error)

Verify checks sc against bundle: row 11 (the sidecar's key id must be known to the WHOLE set) then row 12 (Ed25519 over the exact raw bundle bytes). On success it returns the verifying key.

Verify deliberately does not decide which authority is active. A genuine key of the non-active root must verify here so the caller can report authority_not_active rather than a misleading key_not_trusted.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL