keysource

Documentation

Overview

Package keysource defines the interface the daemon uses to sign receipts. The shape (Sign / PublicKey / Rotate / Init / Teardown) matches ADR-0015 so PKCS#11 and cloud-KMS adapters land later as new types implementing this interface, not as a redesign of the daemon's signing path.

Phase 1 ships only the file-backed adapter (file.go).

Index

• Constants
• Variables
• type File
  • func NewFile(path, verificationMethodID string) *File
  • func (f *File) Init() error
  • func (f *File) PublicKey() (string, error)
  • func (f *File) Rotate() error
  • func (f *File) Sign(message []byte) ([]byte, error)
  • func (f *File) Teardown() error
  • func (f *File) VerificationMethod() string
• type KeySource

Constants

const MaxKeyFileBytes int64 = 16 * 1024

MaxKeyFileBytes is the upper bound on the PEM file size File.Init will read. Generous: a PKCS#8-wrapped Ed25519 private key is ~120 bytes and the PEM envelope adds <100 bytes; 16 KiB tolerates wrapped or commented keys while still capping memory pressure on a misconfigured path.

Variables

var ErrNotImplemented = errors.New("keysource: operation not implemented")

ErrNotImplemented is returned by adapters that do not yet support an optional operation (typically Rotate on the file-backed adapter).

Types

type File

type File struct {
	// Path is the PEM private-key path (PKCS#8). Required.
	Path string

	// VerificationMethodID is the DID URL embedded in proof.verificationMethod.
	// Required: receipts with an empty verification method aren't independently
	// verifiable.
	VerificationMethodID string

	// RequireOwnerOnly, when true, refuses to load a key whose file mode allows
	// group or world access. Defaults to true; tests can disable for tmpfile
	// fixtures whose perms are platform-controlled.
	RequireOwnerOnly bool
	// contains filtered or unexported fields
}

File is a KeySource backed by a PEM-encoded Ed25519 private key on disk. Phase 1 uses this exclusively. Future ADR-0015 adapters (PKCS#11, cloud KMS) implement KeySource alongside this type.

func NewFile

func NewFile(path, verificationMethodID string) *File

NewFile returns an unloaded File. Call Init to read the key from disk.

func (*File) Init

func (f *File) Init() error

Init reads the PEM private key from f.Path and caches it.

func (*File) PublicKey

func (f *File) PublicKey() (string, error)

PublicKey returns the PEM-encoded SPKI public key.

func (*File) Rotate

func (f *File) Rotate() error

Rotate is a stub. ADR-0015 specifies the rotation contract; Phase 1 does not implement it.

func (*File) Sign

func (f *File) Sign(message []byte) ([]byte, error)

Sign returns the raw 64-byte Ed25519 signature over message.

func (*File) Teardown

func (f *File) Teardown() error

Teardown wipes the in-memory key.

func (*File) VerificationMethod

func (f *File) VerificationMethod() string

VerificationMethod returns the configured verification-method ID.

type KeySource

type KeySource interface {
	// Init loads or wires up key material. Called once at daemon startup.
	// Implementations MUST fail loudly when keys are missing or malformed —
	// silently signing with a default-generated key would defeat the audit
	// property.
	Init() error

	// Sign returns the Ed25519 signature over message. The signature is the
	// raw 64-byte form; the caller multibase-encodes it.
	Sign(message []byte) ([]byte, error)

	// PublicKey returns the PEM-encoded SPKI public key for verifiers.
	PublicKey() (string, error)

	// VerificationMethod returns the DID URL or other reference verifiers use
	// to look up the public key. Daemon embeds this in proof.verificationMethod.
	VerificationMethod() string

	// Rotate generates or installs a new key, retaining the public-key
	// receipts pre-rotation can still be verified against. ADR-0015 owns the
	// detailed semantics; Phase 1 returns ErrNotImplemented.
	Rotate() error

	// Teardown wipes any in-memory key material. Called on graceful daemon
	// shutdown.
	Teardown() error
}

KeySource signs canonical receipt bytes and exposes the matching public key. Implementations MUST be safe for concurrent use; the daemon signs from many goroutines.