feat(receiptspec): extract public stdlib-only receipt protocol package

[shreyanshjain7174]

What

Extract the receipt protocol into pkg/receiptspec (stdlib only). internal/receipt forwards to it via type aliases. One implementation. Wire format unchanged.

Why

The Clawdlinux operator needs the same receipt format and verifier. A second producer must not reimplement chaining or verification.

Changes

• pkg/receiptspec: Receipt, Validate, canonical hashing, Chain builder, JSONL, trust root, chain and manifest verification.
• HashRecord and VerifyRecordBinding bind an arbitrary decision record to a receipt through params_sha256. No enum change. See pkg/receiptspec/DECISION.md.
• cmd/agentgate-verify reads and verifies through receiptspec.
• Gateway ledger builds receipts with receiptspec.Chain.

Verification

• go build, go vet, gofmt clean.
• go test ./...: 19 ok packages, 0 FAIL. Golden vectors and external tests unchanged and passing.
• go list -deps ./pkg/receiptspec: standard library only.
• Fuzz run on canonical JSON: no failures.

Follow-up

Tag v0.1.4 after merge so the operator can drop its local replace.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Protocol safety and compatibility need human review, and blocking correctness issues remain.

Review effort: Balanced
Findings: 1 · 3

Open (4)

• Seal returns receipts backed by a mutable input slice · New
• Manifest and bundle verification can panic on invalid key length · New
• Canonicalization builds oversized output before enforcing the limit · New
• TrustedKey with invalid key length can panic ed25519.Verify · New

What changed in this PR

Extracts AgentGate’s receipt protocol into a public, standard-library-only package so other producers can share the gateway’s implementation.

Changes:

• Adds public receipt production, verification, and decision-record binding without changing the v1 wire format.
• Moves gateway and CLI protocol operations to the shared package, with compatibility tests and documentation.

File	Description
README.md	Documents other receipt producers.
pkg/​receiptspec/​verifier.go	Adds public chain and bundle verification.
pkg/​receiptspec/​sign.go	Adds signing and individual receipt verification.
pkg/​receiptspec/​record.go	Adds canonical decision-record hashing and binding.
pkg/​receiptspec/​record_test.go	Tests record canonicalization and binding.
pkg/​receiptspec/​receipt.go	Defines public receipt types and validation.
pkg/​receiptspec/​manifest.go	Provides signed export-manifest operations.
pkg/​receiptspec/​jsonl.go	Provides JSONL parsing and writing.
pkg/​receiptspec/​encoding.go	Implements canonical receipt hashing.
pkg/​receiptspec/​DECISION.md	Documents decision-record conventions.
pkg/​receiptspec/​chain.go	Adds the reusable chain builder.
pkg/​receiptspec/​chain_test.go	Tests chain construction and compatibility.
internal/​signer/​signer.go	Delegates key-ID computation.
internal/​receipt/​verifier.go	Forwards verification APIs.
internal/​receipt/​record_jcs_test.go	Checks hashing against gateway canonicalization.
internal/​receipt/​receipt.go	Aliases public receipt types and validation.
internal/​receipt/​ledger.go	Builds ledger receipts through the shared chain.
internal/​receipt/​jsonl.go	Forwards JSONL encoding APIs.
internal/​receipt/​export.go	Forwards manifest and key-line APIs.
internal/​receipt/​encoding.go	Forwards canonical hashing APIs.
cmd/​agentgate-verify/​receiptspec_test.go	Tests verification of another producer’s receipts.
cmd/​agentgate-verify/​main.go	Uses shared JSONL and bundle verification.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Public protocol APIs need human review, with unresolved trust handling and signing-key ownership issues.

Review effort: Balanced
Findings: 1

Open (1)

• Empty trust roots allow unauthenticated self-signed bundles · New

Resolved since last review (4)

• Seal returns receipts backed by a mutable input slice
• TrustedKey with invalid key length can panic ed25519.Verify
• Canonicalization builds oversized output before enforcing the limit
• Manifest and bundle verification can panic on invalid key length

Previously missed (1)

In code that hasn't changed since last review

Mutable private key slice invalidates cached signer identity

pkg/​receiptspec/​sign.go:47

The constructor retains the caller's mutable key slice but caches its KID. Reusing or clearing that buffer changes later signatures while the signer still reports the original KID. Receipts then fail verification against the original public key. Clone priv before computing the KID and storing the key.