audit

type Absence ¶

type Absence struct {
	Key   string    `json:"key"`             // the key claimed absent from the committed set
	Size  int       `json:"size"`            // number of committed keys the proof is against
	Left  *Neighbor `json:"left,omitempty"`  // committed key just below Key in sort order; nil if Key sorts before all
	Right *Neighbor `json:"right,omitempty"` // committed key just above Key in sort order; nil if Key sorts after all
}

Absence is a non-membership proof: Key is not among the Size committed keys, shown by the adjacent committed keys that bracket it. Left is nil when Key sorts before all keys; Right is nil when it sorts after all; both nil only for the empty key set.

func ProveAbsent(records []agent.Record, keyFn KeyFunc, key string) (Absence, error)

type AbsenceBundle ¶

type AbsenceBundle struct {
	RunID   string         `json:"run_id"`  // the run whose key set the proof is against
	Absence Absence        `json:"absence"` // the non-membership proof
	STH     SignedTreeHead `json:"sth"`     // the signed commitment to the key set the proof is proven against
}

AbsenceBundle is the portable, anchorable form of an absence proof, mirroring ProofBundle: the proof plus the signed tree head committing the key set it is proven against. Verify with an out-of-band public key; it checks the STH signature, binds the proof to the signed size, and verifies non-membership against the signed root.

func ProveAbsentBundle(records []agent.Record, keyFn KeyFunc, key string, runID string, sth SignedTreeHead) (AbsenceBundle, error)

func (b AbsenceBundle) Verify(pub ed25519.PublicKey) (bool, error)

func (b AbsenceBundle) VerifyWith(v Verifier) (bool, error)

type Anchor ¶

type Anchor interface {
	Publish(ctx context.Context, runID string, sth SignedTreeHead) error
}

Anchor is the bring-your-own port for out-of-band anchoring: publish a SignedTreeHead to a trust domain separate from the app (a Certificate-Transparency-style log, a notary / timestamping service, another account's WORM store, a public ledger). Bide ships MemAnchorLog as a reference; you implement Publish against the external log you trust.

type AnchorEntry ¶

type AnchorEntry struct {
	Seq   int            `json:"seq"`    // the entry's position in the anchor log
	RunID string         `json:"run_id"` // the run whose commitment was published
	STH   SignedTreeHead `json:"sth"`    // the published signed tree head
}

AnchorEntry is one published commitment recorded by a transparency log: the run it commits to, its signed tree head, and the entry's position in the anchor log.

type ApprovalVerdict ¶ added in v0.4.0

type ApprovalVerdict struct {
	// Need is the expected policy's k.
	Need int `json:"need"`
	// ToolName and Args are the call the approvers decided on, from the proven request.
	ToolName string          `json:"tool_name"`
	Args     json.RawMessage `json:"args,omitempty"`
	// Counted lists the approvers whose approval counted in the recount, in journal order.
	Counted []string `json:"counted"`
	// DeniedBy lists the approvers whose counted decision was a denial.
	DeniedBy []string `json:"denied_by,omitempty"`
	// Ignored lists every other disclosed decision, with the reason it did not count.
	Ignored []IgnoredDecision `json:"ignored,omitempty"`
	// Problems lists every way the evidence is inconsistent with itself or with the expected
	// policy: an omitted decision the gate read, a recount that disagrees with the gate's
	// journaled tally, a different enforced policy, or records out of order. Any problem fails
	// the verdict.
	Problems []string `json:"problems,omitempty"`
	// OK reports no Problems and at least Need approvals counted.
	OK bool `json:"ok"`
}

ApprovalVerdict is the offline result of checking an m-of-n approval gate from evidence.

func VerifyApprovals(actions []EvidenceAction, toolUseID string, policy agent.ApprovalPolicy, verifierFor agent.ApproverVerifierFor, logPub ed25519.PublicKey) (ApprovalVerdict, error)

type AttenuateFunc ¶

type AttenuateFunc func(parent Grant, subAgent string) Grant

AttenuateFunc derives a child grant from the parent grant and the delegating sub-agent's name. It sets the narrower Scope (and may set Subject); AttenuatingSubAgent fills in ParentRef and, if empty, Issuer (the parent's Subject) and Subject (the sub-agent name), then signs it. The func must produce a STRICTLY narrower grant: a widening delegation is a caller bug and is rejected by VerifyDelegationChain, so a broadened chain cannot pass verification even if one is minted.

type Attenuator ¶

type Attenuator func(parent, child Grant) bool

Attenuator reports whether child's authority is within parent's (domain-specific "narrower").

func AttenuatesNumericScope(key string) Attenuator

type AuditedStore ¶

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

AuditedStore wraps a Durable so every durable step is continuously anchored: whenever a run's journal grows, it commits an RFC 6962 Merkle root over the run, signs a Signed Tree Head, and publishes it to an Anchor (an external transparency log). The caller writes the agent loop exactly as before — audit.NewAuditedStore(store, priv, anchor) is a drop-in Durable — and gets a stream of signed, out-of-band commitments for free.

Anchoring is a SIDE CHANNEL: a publish failure NEVER fails the durable step. Failing Do because an STH could not be published would be dangerous — the underlying write already succeeded, and the caller could wrongly retry a non-idempotent step. Publish errors go to the optional OnError hook instead; the journal remains the source of truth.

func NewAuditedStore(inner agent.Durable, priv ed25519.PrivateKey, anchor Anchor) *AuditedStore

func (a *AuditedStore) Do(ctx context.Context, runID, name string, fn func(context.Context) (agent.Record, error)) (agent.Record, error)

func (a *AuditedStore) History(ctx context.Context, runID string) ([]agent.Record, error)

func (a *AuditedStore) OnError(fn func(runID string, err error)) *AuditedStore

func (a *AuditedStore) WithClock(now func() int64) *AuditedStore

type Consistency ¶

type Consistency struct {
	First int      // m — the earlier tree size
	Size  int      // n — the current tree size
	Path  [][]byte // proof hashes
}

Consistency is an RFC 6962 consistency proof: the first First records are an append-only prefix of the Size-record tree.

func ProveConsistency(ctx context.Context, store agent.Durable, runID string, first int) (Consistency, error)

type ConvergenceContent ¶

type ConvergenceContent struct {
	Digest      string          `json:"digest"`      // the policy digest this certificate certifies (treated as opaque here)
	Certificate json.RawMessage `json:"certificate"` // the opaque, serialized convergence certificate bytes
}

ConvergenceContent is the payload of a convergence leaf: an opaque, serialized convergence certificate and the policy digest it certifies. Committing it as a journal leaf puts the convergence evidence under the same signed tree head and inclusion proofs as the policy and the actions taken under it, so an auditor can prove not merely that a policy was anchored but that the anchored policy was certified convergent in the same committed tree.

audit treats the certificate as opaque bytes and the digest as an opaque identifier, exactly as it does for a policy leaf: it does not import gsm and does not recompute either. The producer of the certificate is govern.CertifyConvergence; a rigorous verifier re-derives the certificate from the disclosed policy bytes (by rebuilding the gsm machine) and compares, so a leaf that overstates convergence is caught outside audit, not trusted here.

type EarnedAuthority ¶

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

EarnedAuthority is a control loop that adjusts an agent's delegated limit from its provable track record. Authority starts at the ladder's baseline rung and is promoted one rung after promoteEvery compliant actions, capped at the top rung; an anomaly resets it to baseline at once. Each change re-issues a signed grant that is a CHILD of the root grant (ParentRef to root, scope limit = the current rung), so the earned limit provably never exceeds the root ceiling: every earned grant passes VerifyDelegationChain against the root under AttenuatesNumericScope, even a buggy or compromised controller cannot widen past what the root principal authorized.

It is deliberately a sequential controller, not a convergent gsm machine. Earning is temporal: how many compliant actions preceded a promotion, and whether an anomaly interleaved, is order-dependent, so it belongs to the durable/saga tier, not the order-independent governance tier (a promote event and a record event do not commute, so no convergent machine expresses it). The ENFORCEMENT of the current limit stays a convergent gsm invariant on the work machine (see examples/earned-authority); the controller only decides the limit and re-issues the grant.

The asymmetry is the safety property: promotion is slow, capped, and evidence-gated; attenuation is immediate and needs no gate, because shrinking authority is always safe.

func NewEarnedAuthority(ladder []int, promoteEvery int, root SignedGrant, signer Signer, subject string) (*EarnedAuthority, error)

func (e *EarnedAuthority) FlagAnomaly() (changed bool, err error)

func (e *EarnedAuthority) Grant() SignedGrant

func (e *EarnedAuthority) Limit() int

func (e *EarnedAuthority) RecordCompliant() (promoted bool, err error)

func (e *EarnedAuthority) Tier() int

type Ed25519Signer ¶

type Ed25519Signer struct {
	Priv ed25519.PrivateKey // the Ed25519 private key that signs
}

Ed25519Signer signs with an Ed25519 private key.

func (Ed25519Signer) Alg() string

func (s Ed25519Signer) Sign(m []byte) ([]byte, error)

type Ed25519Verifier ¶

type Ed25519Verifier struct {
	Pub ed25519.PublicKey // the Ed25519 public key that verifies
}

Ed25519Verifier verifies with an Ed25519 public key.

func (Ed25519Verifier) Alg() string

func (v Ed25519Verifier) Verify(m, sig []byte) bool

type EventLog ¶

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

EventLog is an append-only, tamper-evident log of one run's AgentEvents. Build it by Add-ing events in emission order (Agent.Stream emits them ordered from a single goroutine); then Root/Head to commit, Prove for selective disclosure, and audit.Sign to anchor. Not safe for concurrent Add — feed it from the one goroutine ranging Events.

func EventLogFromJournal(ctx context.Context, store agent.Durable, runID string) (*EventLog, error)

func LoadEventLog(ctx context.Context, evStore EventStore, runID string) (*EventLog, error)

func NewEventLog() *EventLog

func (l *EventLog) Add(e agent.AgentEvent) error

func (l *EventLog) Head() []byte

func (l *EventLog) Len() int

func (l *EventLog) Prove(index int) (Inclusion, error)

func (l *EventLog) ProveConsistency(first int) (Consistency, error)

func (l *EventLog) Root() []byte

func (l *EventLog) TreeHead(timestamp int64) TreeHead

type EventStore ¶

type EventStore interface {
	// Append durably records leaf at position seq (0-based, contiguous) for runID. It MUST be
	// append-only and idempotent on (runID, seq): re-appending an already-stored seq with the
	// SAME bytes is a no-op (so a retried mirror is safe), while a DIFFERENT leaf at an
	// existing seq must error (a fork / tamper attempt). A seq beyond the next position is a
	// gap and must error.
	Append(ctx context.Context, runID string, seq int, leaf []byte) error
	// Load returns every leaf for runID in seq order (0..n-1), or nil if the run is unknown.
	Load(ctx context.Context, runID string) ([][]byte, error)
}

EventStore is the bring-your-own port: append canonical event leaves to your append-only backend (a Postgres table with UNIQUE(run_id, seq) and insert-only grants, object storage with object-lock/WORM, or a log) and read them back. Bide ships MemEventStore as the in-memory default; you implement Append/Load against infrastructure you already run.

type EvidenceAction ¶

type EvidenceAction struct {
	// Label is a short human description of the action (e.g. the tool name, or a step name).
	Label string `json:"label"`
	// Kind is the action category, one of "tool", "step", "grant", "call", "approval", or "approval-tally", used only to phrase the report.
	Kind string `json:"kind"`
	// Ref is the identifier the action was selected by (the tool-use id, step name, or grant digest),
	// surfaced in the report so a reader can trace it back.
	Ref string `json:"ref,omitempty"`
	// Bundle is the inclusion proof that this action is a committed leaf under the package's STH.
	Bundle ProofBundle `json:"bundle"`
}

EvidenceAction is one proven action inside an EvidencePackage: a ProofBundle plus a human-readable label and kind, so the verification report can name what was proven ("tool \"charge\"") without re-deriving it from the record.

func ApprovalEvidence(ctx context.Context, store agent.Durable, runID, toolUseID string, sth SignedTreeHead) ([]EvidenceAction, error)

type EvidenceGrants ¶

type EvidenceGrants struct {
	// Chain is the delegation chain, root-first to leaf-last, as signed grants (may be a single grant).
	Chain []SignedGrant `json:"chain"`
	// Anchored is one ProofBundle per grant in Chain (same order), proving the grant leaf is committed
	// in the signed log. It may be shorter than Chain if some grants were not anchored in this run.
	Anchored []EvidenceAction `json:"anchored,omitempty"`
}

EvidenceGrants carries the run's authority: the delegation chain as signed grants (root-first) and, per grant, a ProofBundle proving the grant leaf is anchored in the same signed log as the actions.

Note the trust boundary: the anchoring bundles verify under the package's log key, but a grant's own issuer signature is made with the ISSUER's key, which is distinct from the log key and is not carried here. EvidencePackage.Verify therefore checks that each grant is anchored in the signed log; verifying the issuer signatures and the attenuation chain (VerifyDelegationChain) requires the issuers' public keys, which a caller supplies from their own PKI.

type EvidenceItem ¶

type EvidenceItem struct {
	Kind     string `json:"kind"`  // "tool", "step", "grant", "call", "approval", "approval-tally", "run-certificate", or "consistency"
	Label    string `json:"label"` // the human label for the item
	Ref      string `json:"ref,omitempty"`
	Verified bool   `json:"verified"` // whether this item verified under the key
	Note     string `json:"note"`     // plain-English detail, on success or failure
}

EvidenceItem is one line of an EvidenceReport: what was checked, whether it verified, and a short human note (the reason on failure, or a one-line description on success).

type EvidenceOption ¶

type EvidenceOption func(*evidenceOptions)

An EvidenceOption selects what an EvidencePackage includes. With no action option (WithToolCall, WithStep, or WithAllToolCalls), Evidence defaults to proving every completed tool call, so the zero-configuration package is "prove every action this run took".

func WithAllToolCalls() EvidenceOption

func WithConsistency(first int) EvidenceOption

func WithGrants() EvidenceOption

func WithLabel(label string) EvidenceOption

func WithRunCertificate(spec RunCertSpec) EvidenceOption

func WithStep(name string) EvidenceOption

func WithToolCall(toolUseID string) EvidenceOption

type EvidencePackage ¶

type EvidencePackage struct {
	// Format is the domain-separated format/version tag (EvidenceFormat). A verifier that does not
	// recognize it should refuse to interpret the rest rather than guess.
	Format string `json:"format"`
	// RunID is the run this evidence is about.
	RunID string `json:"run_id"`
	// Label is an optional caller-supplied description of what this evidence establishes (e.g.
	// "Q3 refund approvals"). It is metadata for a human reader and is not part of any proof.
	Label string `json:"label,omitempty"`
	// ProducedAt is a caller-supplied unix timestamp (seconds) recording when the package was
	// assembled. It is informational; the authoritative time commitment is inside the STH.
	ProducedAt int64 `json:"produced_at"`
	// PublicKeyHex is the hex-encoded ed25519 public key that produced the STH, carried so a reader
	// knows which key to obtain out of band. Verify does not trust it: it takes the key separately.
	PublicKeyHex string `json:"public_key_hex"`

	// STH is the run's signed tree head: the {Size, Root, Timestamp} commitment every action proof
	// below is checked against. One STH is built for the whole package so all proofs share one root.
	STH SignedTreeHead `json:"sth"`

	// Actions are the material tool calls / steps proven included in the signed log. Each carries a
	// human label and the ProofBundle proving that one action is a leaf under the STH's root.
	Actions []EvidenceAction `json:"actions"`

	// Grants optionally carries the authority behind the run: the delegation chain (root-first) as
	// signed grants, plus a ProofBundle per grant proving the grant leaf is anchored in the signed
	// log. It is nil when the caller did not request grants (WithGrants).
	Grants *EvidenceGrants `json:"grants,omitempty"`

	// RunCertificate optionally carries the proof-carrying run certificate (only-approved-policies +
	// policies-convergence-certified) for the whole run. It is nil unless WithRunCertificate was set.
	RunCertificate *RunCertificate `json:"run_certificate,omitempty"`

	// Consistency optionally carries an append-only consistency proof showing the first N records are
	// an unmodified prefix of the tree the STH commits to. It is nil unless WithConsistency was set.
	Consistency *Consistency `json:"consistency,omitempty"`
}

An EvidencePackage is the portable, offline-verifiable evidence artifact for one run: a single self-contained bundle that PACKAGES a run's already-produced cryptographic proofs (a signed tree head, per-action inclusion proofs, and optionally the run certificate, the authority grant chain, and an append-only consistency proof) into one JSON document you can store, email, or hand to an auditor. It introduces no new cryptography: every field is an existing audit primitive, and Verify re-checks each one against the out-of-band public key.

It is deliberately PURE DATA: no funcs, no ed25519 keys, no unexported state, so it round-trips losslessly through JSON. The PublicKeyHex it carries is a convenience for a reader to know which key produced it; it is NOT the trust root. As with a bare ProofBundle, the verifying key must be obtained out of band (the anchor / transparency log), and Verify takes that key as an argument rather than trusting the one embedded here.

func Evidence(ctx context.Context, store agent.Durable, runID string, priv ed25519.PrivateKey, timestamp int64, opts ...EvidenceOption) (EvidencePackage, error)

func (e EvidencePackage) Verify(pub ed25519.PublicKey) (EvidenceReport, error)

type EvidenceReport ¶

type EvidenceReport struct {
	// OK is the overall verdict: true only when the STH is authentic and every item verified.
	OK bool `json:"ok"`
	// RunID echoes the package's run id for a self-describing report.
	RunID string `json:"run_id"`
	// Label echoes the package's optional label.
	Label string `json:"label,omitempty"`
	// STHVerified is true when the signed tree head's signature is authentic under the verifying key.
	// Every action proof is checked against this same root, so a false STH fails the whole package.
	STHVerified bool `json:"sth_verified"`
	// Items is one verdict per proven item (each action, each anchored grant, the run certificate, and
	// the consistency proof), in report order.
	Items []EvidenceItem `json:"items"`
}

EvidenceReport is the structured outcome of EvidencePackage.Verify: an overall verdict plus a per-item verdict list, so a caller (or the CLI) can print exactly which proven item held and which did not. It is the machine-readable form behind the plain-English CLI report.

type Grant ¶

type Grant struct {
	ID        string            `json:"id"`                   // unique identifier for this grant
	Issuer    string            `json:"issuer"`               // principal that authorized the grant (resolves to the signing key)
	Subject   string            `json:"subject"`              // actor the grant authorizes to act
	Scope     map[string]string `json:"scope,omitempty"`      // domain-defined authority bounds (e.g. limits) the chain verifier attenuates over
	NotAfter  int64             `json:"not_after,omitempty"`  // unix-seconds expiry; zero never expires
	ParentRef string            `json:"parent_ref,omitempty"` // Digest of the grant this was attenuated from; empty for a root grant
}

Grant is a signed statement by a principal (Issuer) authorizing an actor (Subject) to act within Scope until NotAfter. It is the non-repudiable authority behind a governed action: the action's agent.Identity.AuthorityRef is a grant's Digest, and the grant is signed by the issuer's own key (distinct from the log's tree-head key), so an auditor attributes the authorization to the principal, not merely to the operator that runs the log.

ParentRef links a grant to the one it was attenuated from (empty for a root grant), forming a hash-linked delegation chain: a holder of a grant may mint a strictly narrower sub-grant for a sub-agent without returning to the root issuer (capability attenuation), and the chain back to the root is provable. Scope semantics are domain-defined; the chain verifier takes an Attenuator that decides what "narrower" means (a helper for numeric limits is provided).

func (g Grant) Bytes() []byte

func (g Grant) Digest() string

func (g Grant) Expired(now int64) bool

type HybridSigner ¶

type HybridSigner struct {
	Ed Ed25519Signer // the Ed25519 component signer
	ML MLDSASigner   // the ML-DSA-65 component signer
}

HybridSigner signs with both schemes; the signature is only accepted if BOTH verify, so the anchor is safe as long as either scheme remains unbroken.

func (HybridSigner) Alg() string

func (s HybridSigner) Sign(m []byte) ([]byte, error)

type HybridVerifier ¶

type HybridVerifier struct {
	Ed Ed25519Verifier // the Ed25519 component verifier
	ML MLDSAVerifier   // the ML-DSA-65 component verifier
}

HybridVerifier requires both component signatures to verify.

func (HybridVerifier) Alg() string

func (v HybridVerifier) Verify(m, sig []byte) bool

type IgnoredDecision ¶ added in v0.4.0

type IgnoredDecision struct {
	Approver string `json:"approver"`
	Step     string `json:"step"`
	Reason   string `json:"reason"`
}

IgnoredDecision is one disclosed approver decision that did not count toward the gate.

type Inclusion ¶

type Inclusion struct {
	Index int      // the record's position in the journal
	Size  int      // the journal length the root committed to
	Path  [][]byte // sibling hashes, leaf-to-root
}

Inclusion is an RFC 6962 audit path proving one record's membership in a committed run.

func Prove(ctx context.Context, store agent.Durable, runID string, index int) (Inclusion, error)

type KeyFunc ¶

type KeyFunc func(agent.Record) (string, bool)

KeyFunc extracts an absence key from a record, returning false to exclude the record from the key set. Absence is proven over the sorted set of distinct keys the KeyFunc yields.

type MLDSASigner ¶

type MLDSASigner struct {
	Priv *mldsa.PrivateKey // the ML-DSA-65 private key that signs
}

MLDSASigner signs with an ML-DSA-65 private key. Signing is deterministic, so replaying the same tree head reproduces the same signature.

func (MLDSASigner) Alg() string

func (s MLDSASigner) Sign(m []byte) ([]byte, error)

type MLDSAVerifier ¶

type MLDSAVerifier struct {
	Pub *mldsa.PublicKey // the ML-DSA-65 public key that verifies
}

MLDSAVerifier verifies with an ML-DSA-65 public key.

func (MLDSAVerifier) Alg() string

func (v MLDSAVerifier) Verify(m, sig []byte) bool

type MemAnchorLog ¶

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

MemAnchorLog is a reference external transparency log: an append-only, independently Merkle-committed record of published STHs. In a real deployment the anchor lives in a DIFFERENT trust domain than the journal (a separate service / account / public log); this in-memory version is for tests and local dev. Because it keeps its OWN RFC 6962 tree over the entries, a third party can verify that the anchor log itself only grew (ProveConsistency) and that a specific STH was anchored (Prove) — the properties that make anchoring meaningful.

func NewMemAnchorLog() *MemAnchorLog

func (l *MemAnchorLog) Entries() []AnchorEntry

func (l *MemAnchorLog) Len() int

func (l *MemAnchorLog) Prove(seq int) (Inclusion, error)

func (l *MemAnchorLog) ProveConsistency(first int) (Consistency, error)

func (l *MemAnchorLog) Publish(_ context.Context, runID string, sth SignedTreeHead) error

func (l *MemAnchorLog) Root() ([]byte, error)

type MemEventStore ¶

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

MemEventStore is the in-memory reference EventStore for tests and local dev. A real backend (Postgres, object storage) enforces the same append-only/idempotent contract with a unique constraint and insert-only permissions.

func NewMemEventStore() *MemEventStore

func (s *MemEventStore) Append(_ context.Context, runID string, seq int, leaf []byte) error

func (s *MemEventStore) Load(_ context.Context, runID string) ([][]byte, error)

type Neighbor ¶

type Neighbor struct {
	Key   string    `json:"key"`   // the committed key adjacent to the absent key
	Proof Inclusion `json:"proof"` // inclusion proof placing Key at its index in the committed key set
}

Neighbor is one committed key adjacent to an absent key, with its inclusion proof.

type PolicyContent ¶

type PolicyContent struct {
	Digest string `json:"digest"` // the policy owner's stable identifier (treated as opaque here)
	Policy string `json:"policy"` // the serialized governed policy bytes
}

PolicyContent is the payload of a policy leaf: the serialized governed policy and its digest. Committing it as a journal leaf puts the policy itself under the same signed tree head and inclusion proofs as the actions taken under it, so an auditor can prove not merely that an action happened but that the exact policy admitting it was anchored in the same committed tree.

type PolicyConvergence ¶

type PolicyConvergence struct {
	Digest      string      `json:"digest"`      // the used policy digest this evidence is for
	PolicyLeaf  ProofBundle `json:"policy_leaf"` // proof the policy leaf is anchored in the run STH
	Certificate ProofBundle `json:"certificate"` // proof the convergence-certificate leaf is anchored in the same tree
}

PolicyConvergence bundles the anchored evidence for one used policy: its anchored policy leaf and its anchored convergence-certificate leaf, both proven against the run STH. The verifier confirms both bundles are authentic and in the same tree, the convergence certificate certifies the policy leaf's digest, and the policy leaf's bytes hash to that digest (done in the CLI, independent of gsm), then optionally runs the oracle on the disclosed policy bytes.

type ProofBundle ¶

type ProofBundle struct {
	RunID     string         `json:"run_id"`    // the run whose journal the record and STH belong to
	Record    agent.Record   `json:"record"`    // the single disclosed action
	Inclusion Inclusion      `json:"inclusion"` // its RFC 6962 audit path
	STH       SignedTreeHead `json:"sth"`       // the signed commitment it is proven against
}

A ProofBundle is a single, portable, self-describing artifact that proves ONE action happened inside a signed, committed run, disclosing nothing else. It is what "produce a proof" returns: hand it (plus the signer's public key, obtained out-of-band) to an auditor and they verify it offline. This turns the audit package's separate pieces (a record, its inclusion path, a signed tree head) into one thing you can marshal to JSON, store, email, or publish.

The trust model, stated precisely: the public key must come from OUT OF BAND (the anchor / transparency log), NOT from the bundle. Given a trusted key, Verify checks (1) the STH's signature, so the {Size, Root, Timestamp} commitment is authentic; (2) that the inclusion proof is against that same signed size; and (3) that the disclosed record is the leaf at its index under the signed root. "Proofs you verify, not logs you trust": nothing here asks the verifier to trust the producer, its database, or its logs. For full tamper-evidence the auditor also confirms the STH itself appears in the anchor log (MemAnchorLog.Prove).

func ProveApproval(ctx context.Context, store agent.Durable, runID, step string, sth SignedTreeHead) (ProofBundle, error)

func ProveConvergence(ctx context.Context, store agent.Durable, runID, digest string, sth SignedTreeHead) (ProofBundle, error)

func ProveGrant(ctx context.Context, store agent.Durable, runID, digest string, sth SignedTreeHead) (ProofBundle, error)

func ProvePolicy(ctx context.Context, store agent.Durable, runID, digest string, sth SignedTreeHead) (ProofBundle, error)

func ProveRecord(ctx context.Context, store agent.Durable, runID string, index int, sth SignedTreeHead) (ProofBundle, error)

func ProveRunCertificate(ctx context.Context, store agent.Durable, runID string, sth SignedTreeHead) (ProofBundle, error)

func ProveStep(ctx context.Context, store agent.Durable, runID, name string, sth SignedTreeHead) (ProofBundle, error)

func ProveToolCall(ctx context.Context, store agent.Durable, runID, toolUseID string, sth SignedTreeHead) (ProofBundle, error)

func (b ProofBundle) Verify(pub ed25519.PublicKey) (bool, error)

func (b ProofBundle) VerifyWith(v Verifier) (bool, error)

type RunCertSpec ¶

type RunCertSpec struct {
	// ApprovedPolicies is the allowlist of policy digests the run was permitted to exercise. Every
	// policy the run actually used must be a member, or CertifyRun fails: a certificate cannot be
	// issued for a run that exercised a disallowed policy.
	ApprovedPolicies []string
}

RunCertSpec carries the caller's assertion inputs to CertifyRun. v1 needs only the approved allowlist; it is a struct so future properties (authority roots, quorum thresholds) can be added without changing the signature.

type RunCertificate ¶

type RunCertificate struct {
	// RunID is the run this certificate is about.
	RunID string `json:"run_id"`

	// Properties names the asserted properties, so a reader sees the scope without decoding the
	// bindings. v1: "only-approved-policies", "policies-convergence-certified".
	Properties []string `json:"properties"`

	// ApprovedPolicies is the caller-supplied allowlist of policy digests the run was permitted to
	// exercise. The certificate binds to it so an auditor sees exactly which allowlist was asserted.
	ApprovedPolicies []string `json:"approved_policies"`

	// UsedPolicies is the sorted, distinct set of policy digests exercised by governed actions in the
	// run, recomputed from the committed leaves (PoliciesUsed). It is disclosed in full because the
	// only-approved-policies property is completeness-bearing: the verifier recomputes the absence
	// root over this set and confirms UsedPolicyAbsence.STH commits to it, so the set cannot omit a
	// policy that was in fact used.
	UsedPolicies []string `json:"used_policies"`

	// UsedPolicyAbsence is the signed commitment to the run's used-policy key set: an STH over
	// AbsenceRoot(records, PolicyUsedKey). Its Size is the number of distinct used policies and its
	// Root is the RFC 6962 root over their sorted keys, so recomputing that root from UsedPolicies and
	// comparing binds the disclosed set to what the run actually committed. See SignAbsenceRoot.
	UsedPolicyAbsence SignedTreeHead `json:"used_policy_absence"`

	// Convergence carries, per used policy digest, the anchored evidence that the policy is certified
	// convergent: the policy-leaf ProofBundle and the convergence-leaf ProofBundle, both bound to the
	// run STH below. The oracle cross-check (does the policy actually converge) is performed by the
	// verifier with a checker, as verify-convergence does; these bundles establish the cryptographic
	// root (anchored, digest-linked, same tree) that the oracle check hangs off.
	Convergence []PolicyConvergence `json:"convergence"`

	// STH is the run's signed tree head: the {Size, Root, Timestamp} commitment the policy and
	// convergence bundles are proven against. It is the same tree the whole run's journal commits.
	STH SignedTreeHead `json:"sth"`
}

A RunCertificate is a proof-carrying run: one portable, offline-checkable artifact asserting behavioral-property compliance over a WHOLE run, discharged from the audit package's existing primitives rather than from new cryptography. It composes what already exists (RFC 6962 inclusion proofs, signed tree heads, the policy-used absence commitment, anchored policy and convergence leaves) into one per-run statement plus a verifier, so a compliance reviewer checks a single bundle against one out-of-band public key instead of assembling the proofs by hand.

v1 asserts these properties, each dischargeable from a committed leaf:

• only-approved-policies: every policy digest exercised by a governed action in the run is a member of a caller-supplied approved allowlist. This is the COMPLETENESS-bearing property: it commits WHICH policies were used, via the policy-used absence commitment (AbsenceRoot over PolicyUsedKey). The used set is exactly the sorted distinct keys the absence tree commits to, so a verifier recomputes that root from the disclosed set and confirms the signed absence STH commits to it; that closes the "some other policy was quietly used" gap that disclosing only positive leaves would leave open.
• policies-convergence-certified: for each used policy digest, an anchored convergence certificate leaf exists in the same signed tree as the policy leaf and links to its digest. The certificate is a producer claim; a rigorous verifier cross-checks it against the external oracle (bide-audit verify-run -checker), exactly as verify-convergence does, so a certificate that overstates convergence is caught outside this package.

What the certificate proves, stated precisely: it proves properties of the GOVERNED, COMMITTED boundary of the run: which policies ran, that each is on the approved allowlist, and that each has an anchored convergence certificate that (with the oracle) is confirmed convergent. Composing the two properties yields "every governed state in the run was produced by an approved, oracle-certified-convergent policy," so the enforced invariant held throughout the governed boundary. It does NOT prove the model's judgment was correct, that ungoverned side effects were appropriate, or the runtime-refinement claim (the replay differential check covers the events this run took, not all inputs). The used-policy completeness rests entirely on the absence-root key-set commitment described above.

func CertifyRun(ctx context.Context, store agent.Durable, runID string, sth SignedTreeHead, spec RunCertSpec, priv ed25519.PrivateKey, timestamp int64) (RunCertificate, error)

type RunVerification ¶

type RunVerification struct {
	// OK is the overall verdict: true only when every asserted property held.
	OK bool
	// OnlyApprovedPolicies is true when every used policy is in the allowlist AND the disclosed
	// used-policy set is bound to the run's absence commitment (completeness).
	OnlyApprovedPolicies bool
	// ConvergenceCertified is true when every used policy has an anchored policy leaf and convergence
	// leaf, authentic and in the same signed tree, with linking digests. It does NOT include the
	// oracle cross-check, which the caller performs separately (the CLI does, with -checker).
	ConvergenceCertified bool
	// Reasons carries human-readable detail for any property that failed (empty on full success).
	Reasons []string
}

RunVerification is the structured outcome of VerifyRun: the overall verdict plus per-property results, so a caller (or the CLI) can report exactly which property held and which failed.

func VerifyRun(cert RunCertificate, pub ed25519.PublicKey) (RunVerification, error)

type SignedGrant ¶

type SignedGrant struct {
	Grant Grant  `json:"grant"` // the grant whose canonical bytes are signed
	Alg   string `json:"alg"`   // signature scheme the issuer used (see signing.go)
	Sig   []byte `json:"sig"`   // issuer's signature over Grant.Bytes()
}

SignedGrant is a Grant plus the issuer's signature over its canonical bytes.

func SignGrant(g Grant, s Signer) (SignedGrant, error)

func (sg SignedGrant) Verify(v Verifier) (bool, error)

type SignedTreeHead ¶

type SignedTreeHead struct {
	TreeHead         // the {Size, Root, Timestamp} commitment being signed
	Signature []byte // signature over TreeHead.canonical() under the scheme named by Alg
	// Alg names the signature scheme (see signing.go). Empty means "ed25519", so bundles
	// produced by the ed25519-only SignTreeHead / Verify path are unchanged on the wire and
	// keep verifying. Agility-aware producers set it explicitly (SignTreeHeadWith).
	Alg string `json:"alg,omitempty"`
}

SignedTreeHead is a TreeHead with an Ed25519 signature over its canonical encoding.

func SignAbsenceRoot(records []agent.Record, keyFn KeyFunc, priv ed25519.PrivateKey, timestamp int64) SignedTreeHead

func SignTreeHead(th TreeHead, priv ed25519.PrivateKey) SignedTreeHead

func SignTreeHeadWith(th TreeHead, s Signer) (SignedTreeHead, error)

func (sth SignedTreeHead) Verify(pub ed25519.PublicKey) bool

func (sth SignedTreeHead) VerifyWith(v Verifier) bool

type Signer ¶

type Signer interface {
	Alg() string
	Sign(message []byte) ([]byte, error)
}

Signer produces a signature over a message under a named algorithm.

type TreeHead ¶

type TreeHead struct {
	Size      int    // number of records committed
	Root      []byte // RFC 6962 Merkle root over those records (see Root)
	Timestamp int64  // caller-supplied (e.g. time.Now().UnixNano())
}

TreeHead is a commitment to a run's journal at a point in time.

func NewTreeHead(ctx context.Context, store agent.Durable, runID string, timestamp int64) (TreeHead, error)

type Verifier ¶

type Verifier interface {
	Alg() string
	Verify(message, signature []byte) bool
}

Verifier checks a signature over a message under a named algorithm.