refactor(receipt): disentangle Receipt from Invocation (#12)

## Summary

`Receipt` becomes its own Go type, distinct from `Invocation` —
**without changing the wire format**. On the wire a receipt is still a
`/ucan/assert/receipt` invocation; that encoding tracks the UCAN WG
draft ([ucan-wg/receipt#1](ucan-wg/receipt#1))
and is unchanged here. The change is entirely in the Go API surface.

## Motivation

A receipt has always been encoded as a `/ucan/assert/receipt`
invocation, and the Go `Receipt` type embedded `invocation.Invocation`
to reuse the envelope / sigPayload / varsig plumbing. That reuse was a
sensible starting point. As more code was built on the API, a few rough
edges emerged — all on the Go side, none on the wire — that this PR
smooths out:

1. **Clearer type boundaries.** Because `*Receipt` embedded
`invocation.Invocation`, it satisfied `ucan.Invocation` — so anything
declared `func(inv ucan.Invocation)` would quietly accept a receipt.
That has worked in practice, but it makes call-site review harder and
pushes helpers like `validator.VerifyInvocationSignature` toward being
defensively written. With `Receipt` as its own type, signatures say what
they mean.

2. **Tighter discoverability.** Autocomplete on a receipt previously
surfaced the full invocation method set — `Subject`, `Audience`,
`Command`, `Proofs`, `Cause`, `Task`, … — most of which don't carry
receipt-specific information (`Command()` is always the constant,
`Subject()`/`Audience()` are always the executor). The type now exposes
only the receipt-meaningful accessors: `Issuer`, `Ran`, `Out`,
`IssuedAt`, `Nonce`, `MetadataBytes`, `SignedBytes`, `Signature`, plus
`Link`/`Bytes`.

3. **A receipt-specific options surface.** `receipt.Option` was a
re-export of `invocation.Option`, so options like `WithProofs` /
`WithCause` appeared on the receipt API without a defined meaning for a
receipt today. `receipt.Option` is now its own type that translates to
invocation options internally, exposing just `WithNonce` / `WithNoNonce`
/ `WithIssuedAt` / `WithMetadata`.

## What changed

- `Receipt` holds an `invocation.Invocation` as an **unexported field**
instead of embedding it. `*Receipt` no longer satisfies
`ucan.Invocation`.
- `ucan.Receipt` is a standalone interface — it no longer embeds
`ucan.Invocation`.
- `receipt.Option` is its own type with a receipt-only option set.
- Adds `receipt.VerifySignature`, mirroring the `invocation` /
`delegation` helpers.
- Construction (`issue` → `invocation.Invoke`) and decoding (via
`invocation.Invocation`) are unchanged, so encoded receipts are
byte-identical to `main`.

## Intentionally deferred

`prf` (proofs) and `exp` (expiration) are load-bearing receipt fields in
the WG draft — proofs for delegated receipt issuance, expiration for
assertion TTL. They are physically present on the wire today (a receipt
is an invocation), but their receipt-level semantics are still under
discussion upstream. Rather than ship half-defined accessors, the API
stays minimal now and will grow `Proofs` / `Expiration` accessors and
options once the spec settles.

## Wire compatibility

**Unchanged.** Encoded receipts are byte-identical to `main`. Two tests
pin the boundary in both directions:

- `TestWireFormatIsInvocation` — a receipt's exact bytes decode via
`invocation.Decode`, re-encode verbatim, verify through
`invocation.VerifySignature`, and carry the executor as
`iss`/`sub`/`aud`.
- `TestNotAReceipt` (invocation package) — a non-receipt invocation is
rejected by `receipt.Decode`.

## Test plan

- [x] `go build ./...` and `go vet ./...`
- [x] `go test ./...` — full suite green
- [x] `TestWireFormatIsInvocation` — receipt bytes are a valid,
verifiable invocation
- [x] `TestNotAReceipt` — non-receipt invocations don't decode as
receipts
- [x] `TestNotInvocation` — `*Receipt` does not satisfy
`ucan.Invocation`
- [x] `TestVerifySignature`, `TestOptions`, `TestIssueOK` /
`TestIssueErr`

Author: frrist

ucan/invocation/invocation_test.go

@@ -11,6 +11,7 @@ import (
 	"github.com/fil-forge/ucantone/ucan"
 	"github.com/fil-forge/ucantone/ucan/command"
 	"github.com/fil-forge/ucantone/ucan/invocation"
+	"github.com/fil-forge/ucantone/ucan/receipt"
 	"github.com/stretchr/testify/require"
 	cbg "github.com/whyrusleeping/cbor-gen"
 )
@@ -257,3 +258,30 @@ func TestInvokeRejectsNonMapArgs(t *testing.T) {
 	require.Error(t, err)
 	require.Contains(t, err.Error(), "args must encode as a CBOR map")
 }
+
+// TestNotAReceipt is the mirror of receipt.TestWireFormatIsInvocation. A
+// receipt is wire-identical to a /ucan/assert/receipt invocation, but the
+// discrimination must hold in the other direction too: a plain invocation
+// with any other command MUST NOT decode as a receipt. This pins the
+// boundary so receipt.Decode can't silently accept arbitrary invocations.
+func TestNotAReceipt(t *testing.T) {
+	issuer := testutil.RandomSigner(t)
+	subject := testutil.RandomDID(t)
+	command := testutil.Must(command.Parse("/test/invoke"))(t)
+
+	inv, err := invocation.Invoke(issuer, subject, command, datamodel.Map{})
+	require.NoError(t, err)
+
+	encoded, err := invocation.Encode(inv)
+	require.NoError(t, err)
+
+	// The invocation decodes fine as an invocation...
+	_, err = invocation.Decode(encoded)
+	require.NoError(t, err)
+
+	// ...but must be rejected as a receipt: its command isn't the receipt
+	// command, so there are no Ran/Out fields to recover.
+	_, err = receipt.Decode(encoded)
+	require.Error(t, err, "a non-receipt invocation must not decode as a receipt")
+	require.Contains(t, err.Error(), "invalid receipt command")
+}

ucan/receipt/options.go

@@ -1,15 +1,49 @@
 package receipt
 
-import "github.com/fil-forge/ucantone/ucan/invocation"
-
-type Option = invocation.Option
-
-var (
-	WithExpiration   = invocation.WithExpiration
-	WithNoExpiration = invocation.WithNoExpiration
-	WithNonce        = invocation.WithNonce
-	WithNoNonce      = invocation.WithNoNonce
-	WithMetadata     = invocation.WithMetadata
-	WithProofs       = invocation.WithProofs
-	WithCause        = invocation.WithCause
+import (
+	"github.com/fil-forge/ucantone/ipld"
+	"github.com/fil-forge/ucantone/ucan"
+	"github.com/fil-forge/ucantone/ucan/invocation"
 )
+
+// Option configures a UCAN receipt.
+//
+// A receipt is encoded on the wire as a /ucan/assert/receipt invocation (see
+// ucan-wg/receipt#1), so each receipt Option translates to an invocation
+// Option internally. Only the options that are meaningful for a receipt are
+// exposed here; proof/expiration options will be added once their semantics
+// are settled in the spec.
+type Option func(cfg *receiptConfig)
+
+type receiptConfig struct {
+	invOpts []invocation.Option
+}
+
+// WithNonce configures the nonce value for the receipt.
+func WithNonce(nnc []byte) Option {
+	return func(cfg *receiptConfig) {
+		cfg.invOpts = append(cfg.invOpts, invocation.WithNonce(nnc))
+	}
+}
+
+// WithNoNonce configures an empty nonce value for the receipt.
+func WithNoNonce() Option {
+	return func(cfg *receiptConfig) {
+		cfg.invOpts = append(cfg.invOpts, invocation.WithNoNonce())
+	}
+}
+
+// WithIssuedAt sets the time at which the receipt was issued, in seconds
+// since the Unix epoch.
+func WithIssuedAt(iat ucan.UnixTimestamp) Option {
+	return func(cfg *receiptConfig) {
+		cfg.invOpts = append(cfg.invOpts, invocation.WithIssuedAt(iat))
+	}
+}
+
+// WithMetadata configures arbitrary metadata for the receipt.
+func WithMetadata(meta ipld.Map) Option {
+	return func(cfg *receiptConfig) {
+		cfg.invOpts = append(cfg.invOpts, invocation.WithMetadata(meta))
+	}
+}

ucan/receipt/receipt.go

@@ -6,29 +6,50 @@ import (
 	"fmt"
 	"io"
 
+	cid "github.com/ipfs/go-cid"
+	cbg "github.com/whyrusleeping/cbor-gen"
+
+	"github.com/fil-forge/ucantone/did"
 	"github.com/fil-forge/ucantone/ipld/datamodel"
 	"github.com/fil-forge/ucantone/result"
 	rsdm "github.com/fil-forge/ucantone/result/datamodel"
 	"github.com/fil-forge/ucantone/ucan"
 	"github.com/fil-forge/ucantone/ucan/command"
 	"github.com/fil-forge/ucantone/ucan/invocation"
 	rdm "github.com/fil-forge/ucantone/ucan/receipt/datamodel"
-	cid "github.com/ipfs/go-cid"
-	cbg "github.com/whyrusleeping/cbor-gen"
 )
 
 const Command = command.Command("/ucan/assert/receipt")
 
 // Receipt is a signed attestation that a task was executed and produced a
-// particular result. The result is held as raw CBOR bytes — typed callers
-// decode via [Receipt.Out] and UnmarshalCBOR into the schema expected for
-// the receipt's task.
+// particular result.
+//
+// On the wire a receipt is a /ucan/assert/receipt invocation (per the UCAN WG
+// draft, ucan-wg/receipt#1): the executor is issuer/subject/audience and the
+// Ran/Out fields travel in the invocation's args. That wire shape is
+// deliberate and is not changed here.
+//
+// At the Go level, Receipt wraps the underlying invocation as an unexported
+// field rather than embedding it, so a *Receipt does not satisfy
+// ucan.Invocation and only exposes accessors that are meaningful for a
+// receipt. The result is held as raw CBOR bytes — typed callers decode via
+// [Receipt.Out] into the schema expected for the receipt's task.
 type Receipt struct {
-	invocation.Invocation
+	inv invocation.Invocation
 	ran cid.Cid
 	out result.Result[[]byte, []byte]
 }
 
+// Issuer is the DID of the executor that signed this attestation.
+func (rcpt *Receipt) Issuer() did.DID {
+	return rcpt.inv.Issuer()
+}
+
+// Ran is the CID of the executed task this receipt is for.
+func (rcpt *Receipt) Ran() cid.Cid {
+	return rcpt.ran
+}
+
 // Out is the attested result of the execution of the task. The Result's
 // Ok and Err branches hold raw CBOR bytes; decode into the typed cborgen
 // struct that matches the executed task's expected output:
@@ -46,23 +67,72 @@ func (rcpt *Receipt) Out() result.Result[[]byte, []byte] {
 	return rcpt.out
 }
 
-// Ran is the CID of the executed task this receipt is for.
-func (rcpt *Receipt) Ran() cid.Cid {
-	return rcpt.ran
+// IssuedAt is the timestamp at which the executor signed this receipt, or nil
+// if unset.
+func (rcpt *Receipt) IssuedAt() *ucan.UnixTimestamp {
+	return rcpt.inv.IssuedAt()
+}
+
+// Nonce returns the receipt's nonce.
+func (rcpt *Receipt) Nonce() []byte {
+	return rcpt.inv.Nonce()
+}
+
+// MetadataBytes returns the raw CBOR bytes of the meta field, or nil if
+// metadata is not set.
+func (rcpt *Receipt) MetadataBytes() []byte {
+	return rcpt.inv.MetadataBytes()
+}
+
+// SignedBytes returns the raw CBOR bytes of the SigPayload — the bytes the
+// issuer signed over. Verification operates on these directly.
+func (rcpt *Receipt) SignedBytes() []byte {
+	return rcpt.inv.SignedBytes()
+}
+
+// Signature returns the executor's signature over the SignedBytes.
+func (rcpt *Receipt) Signature() ucan.Signature {
+	return rcpt.inv.Signature()
+}
+
+// Link returns the IPLD link that corresponds to the encoded bytes.
+func (rcpt *Receipt) Link() cid.Cid {
+	return rcpt.inv.Link()
+}
+
+// Bytes returns the dag-cbor encoded bytes of this receipt.
+func (rcpt *Receipt) Bytes() []byte {
+	return rcpt.inv.Bytes()
 }
 
 func (rcpt *Receipt) MarshalCBOR(w io.Writer) error {
-	_, err := w.Write(rcpt.Bytes())
-	return err
+	return rcpt.inv.MarshalCBOR(w)
 }
 
 func (rcpt *Receipt) UnmarshalCBOR(r io.Reader) error {
-	*rcpt = Receipt{}
-
 	inv := invocation.Invocation{}
 	if err := inv.UnmarshalCBOR(r); err != nil {
 		return err
 	}
+	return rcpt.fromInvocation(inv)
+}
+
+func (rcpt *Receipt) MarshalDagJSON(w io.Writer) error {
+	return rcpt.inv.MarshalDagJSON(w)
+}
+
+func (rcpt *Receipt) UnmarshalDagJSON(r io.Reader) error {
+	inv := invocation.Invocation{}
+	if err := inv.UnmarshalDagJSON(r); err != nil {
+		return err
+	}
+	return rcpt.fromInvocation(inv)
+}
+
+// fromInvocation validates that inv is a well-formed receipt invocation and
+// populates rcpt from it.
+func (rcpt *Receipt) fromInvocation(inv invocation.Invocation) error {
+	*rcpt = Receipt{}
 
 	if inv.Command() != Command {
 		return fmt.Errorf("invalid receipt command %s, expected %s", inv.Command().String(), Command.String())
@@ -83,7 +153,7 @@ func (rcpt *Receipt) UnmarshalCBOR(r io.Reader) error {
 		return errors.New("invalid result, neither ok nor error")
 	}
 
-	rcpt.Invocation = inv
+	rcpt.inv = inv
 	rcpt.ran = receiptArgs.Ran
 	rcpt.out = out
 	return nil
@@ -121,6 +191,11 @@ func issue(executor ucan.Signer, ran cid.Cid, ok, errVal cbg.CBORMarshaler, opti
 		return nil, errors.New("issue requires exactly one of ok or err to be non-nil")
 	}
 
+	cfg := receiptConfig{}
+	for _, opt := range options {
+		opt(&cfg)
+	}
+
 	var outModel rsdm.ResultModel
 	var outBytes []byte
 	if ok != nil {
@@ -139,12 +214,12 @@ func issue(executor ucan.Signer, ran cid.Cid, ok, errVal cbg.CBORMarshaler, opti
 		outBytes = raw.Bytes()
 	}
 
-	options = append(options, invocation.WithAudience(executor.DID()))
+	invOpts := append(cfg.invOpts, invocation.WithAudience(executor.DID()))
 
 	inv, err := invocation.Invoke(executor, executor.DID(), Command, &rdm.ArgsModel{
 		Ran: ran,
 		Out: outModel,
-	}, options...)
+	}, invOpts...)
 	if err != nil {
 		return nil, err
 	}
@@ -157,12 +232,21 @@ func issue(executor ucan.Signer, ran cid.Cid, ok, errVal cbg.CBORMarshaler, opti
 	}
 
 	return &Receipt{
-		Invocation: *inv,
-		ran:        ran,
-		out:        out,
+		inv: *inv,
+		ran: ran,
+		out: out,
 	}, nil
 }
 
+// VerifySignature verifies the receipt's signature against the literal
+// signed-payload bytes preserved on decode.
+func VerifySignature(rcpt ucan.Receipt, verifier ucan.Verifier) (bool, error) {
+	if rcpt.Issuer() != verifier.DID() {
+		return false, nil
+	}
+	return verifier.Verify(rcpt.SignedBytes(), rcpt.Signature().Bytes()), nil
+}
+
 func marshalToRaw(m cbg.CBORMarshaler) (datamodel.Raw, error) {
 	var buf bytes.Buffer
 	if err := m.MarshalCBOR(&buf); err != nil {