feat: clients can find proof chains as servers do by volmedo · Pull Request #85 · storacha/go-ucanto

volmedo · 2026-02-25T10:25:23Z

This PR adds validator.PruneProofs and validator.SelectProofs. They are for clients what validator.Access and validator.Claim are for servers:

SelectProofs walks a successful Claim authorization tree and returns the minimal flat set of delegation.Delegations needed to prove the claimed capability, including any ucan/attest delegations used along the way.
PruneProofs is the client-side counterpart to Access: given a draft delegation carrying the full candidate proof pool, returns only the delegation.Proofs actually needed to form a valid chain. Each returned proof is re-exported into a fresh blockstore (via Export()) so it carries only its own chain blocks rather than the entire inherited pool.

These functions enable a client to confirm the proof chain is correct before sending it to the server and also reduce the amount of data sent. The latter is especially interesting when these delegations need to travel in HTTP headers.

Implementation details

Changes to existing functions have the goal of surfacing ucan/attest delegations as part of the chain. The current implementation checks them (VerifySession) but doesn't add them to the returned Authorization object. This works because servers only use Access to confirm the chain is valid, but rarely use the actual proofs in the chain. The client, however, needs all the relevant proofs in the chain if it wants an invocation to succeed.

To do so, Validate and VerifyAuthorization now return the ucan/attest authorization used when verifying a non-did:key issuer. This is threaded through ResolveSources, ResolveMatch, Authorize, and Claim, and exposed via a new Attestations() []Authorization[any] method on the Authorization interface. Authorize uses an attestationsFor helper to filter attestations down to only those whose nb.proof link matches delegations that match.

alanshaw

Urgh, I cannot wait for us to get to UCAN 1.0.

alanshaw · 2026-02-25T10:41:31Z

 	Proofs() []Authorization[Caveats]
+	// Attestations returns ucan/attest delegations that were used to authorize
+	// non-did:key issuers (e.g. did:mailto accounts) in this authorization.
+	Attestations() []Authorization[any]


Why not?

Suggested change

Attestations() []Authorization[any]

Attestations() []Authorization[Caveats]

it's not Caveats because these are ucan/attest delegations, as opposed to the other ones, which refer to the claimed capability.

alanshaw · 2026-02-25T12:33:25Z

+// delegation being built by a client to send over a size-constrained channel
+// (e.g. an HTTP header).
+//
+// dlg must be built with the full candidate proof pool — all proof blocks


This is a little odd - why would you go through the process of creating and signing a delegation that will subsequently be thrown away?

I'd perhaps frame this as pruning proofs from a delegation whose proof set may contain additional delegations that are not necessary to prove the delegation is valid.

I changed the wording in the comment in an attempt to clarify and cover what I explained in my comment below, let me know if that works better.

alanshaw · 2026-02-25T12:41:04Z

+			walk(attest)
+		}
+		for _, prf := range a.Proofs() {
+			walk(prf)


This will hoist all proofs in the chain and they will end up listed as proofs of the root delegation, even if they do not directly prove it.

i.e. this shouldn't be necessary.

ah, yeah, good catch, thanks!

alanshaw · 2026-02-25T12:50:20Z

+// Note: the capability in vctx must match the capability in dlg, or
+// PruneProofs will return [Unauthorized]. If dlg contains multiple
+// capabilities, only the chain for the first matching one is discovered.
+func PruneProofs[Caveats any](ctx context.Context, dlg delegation.Delegation, vctx ValidationContext[Caveats]) ([]delegation.Proof, Unauthorized) {


I think it's okay for this to exist, but ideally you want to create a delegation with only the proofs that are necessary. If you have the ability to prune, then you have the ability to select the minimal set of proofs for your delegation in the first place.

This is perhaps useful when you are given a random delegation and want to send it somewhere for storage, and you want to minimise the amount of data stored/transferred. In the case where you use said delegation (in an invocation) then you can select the relevant proofs and you wouldn't use this function...right?

yeah, I admit is a bit awkward. The thing is that principal alignment is checked per "level". If there is a root delegation, Claim will attempt to find a valid chain that aligns with the issuer of the delegation. However, if given a list of delegations at the same level, the first one that is self-issued (such as one from the space to the account) would work as a valid chain.

This is really an artefact of me trying to re-use Claim, and Claim being tailored towards verifying proof chains in the server, where everything emanates from a single invocation. In the client, we need a way to tell Claim what's the intended principal we want to build a chain for. Encapsulating that in a delegation is what allows re-using Claim as is. We could also modify it to get that target principal, but I'd rather touching that code as little as possible. Besides, Claim is called recursively in a bunch of places where an additional target principal doesn't really make sense.

I do see building delegations from scratch as a main use case of this function. You can also prune random delegations, but you'll only be able to properly sign the pruned version if you were the original issuer. Alternatively, you can use the output of PruneProofs to filter blocks from the delegation's blockstore without actually rebuilding it. It will still link to proofs whose blocks are not attached anymore, but that shouldn't break anything, I think.

Maybe having SelectProofs take a single delegation instead of a list would make this more clear. I used a list to mirror the Access+Claims pattern, but it might just be confusing.

alanshaw · 2026-02-25T12:52:50Z

+
+		// Re-export the delegation into a fresh blockstore so it only carries
+		// the blocks from its own proof chain, not the full candidate pool that
+		// was inherited from the draft's blockstore.


Right, but Export() doesn't prune proofs of proofs. i.e. what if the proof has a bunch of candidates?

...I guess you can't really do this since you can't re-sign a proof....

yeah, if they contain unnecessary proofs themselves there's not much we can do

codecov · 2026-03-10T09:17:07Z

Codecov Report

❌ Patch coverage is 55.55556% with 56 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
core/delegation/delegate.go	0.00%	26 Missing and 1 partial ⚠️
validator/proof_pruning.go	50.94%	22 Missing and 4 partials ⚠️
validator/lib.go	92.50%	3 Missing ⚠️

Files with missing lines	Coverage Δ
validator/authorization.go	`87.50% <100.00%> (+37.50%)`	⬆️
validator/lib.go	`87.14% <92.50%> (+0.94%)`	⬆️
validator/proof_pruning.go	`50.94% <50.94%> (ø)`
core/delegation/delegate.go	`21.68% <0.00%> (-10.46%)`	⬇️

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

alanshaw

I think this can merge after #86 merges in here.

Offer proof chain optimization (proof pruning) as an option when creating delegations. Removes the need of callers having to roll their own logic to implement the `draft delegation -> proof pruning -> final delegation` pattern and encapsulates it in a single place so that it's easier to refactor in the future. The `ProofChainOptimizer` type is required to prevent an import cycle issue, because the `validator` package imports `delegation`, so we cannot use `validator` directly here. Callers will need to call `validator.NewProofChainOptimizer` themselves and pass the result in the option. Not the most straightforward API, but it's a good trade-off. An alternative would be to extract the shared types into a third package, but that would require a larger refactor (we might consider doing it in the future).

volmedo added 4 commits February 24, 2026 20:54

add SelectProofs for clients to find optimized proof chains

c257e02

add PruneProofs for convenient pruning of proofs from a root delegation

79b119e

only return relevant attestations

5827032

export proofs to remove irrelevant blocks

58bbc71

volmedo requested a review from a team February 25, 2026 10:25

volmedo self-assigned this Feb 25, 2026

volmedo requested a review from alanshaw as a code owner February 25, 2026 10:25

volmedo mentioned this pull request Feb 25, 2026

fix: only send necessary proofs in retrieval auth delegation storacha/guppy#357

Closed

alanshaw requested changes Feb 25, 2026

View reviewed changes

volmedo added 2 commits February 26, 2026 14:57

review feedback

357b117

SelectProofs collects proofs too

3178735

alanshaw approved these changes Mar 16, 2026

View reviewed changes

volmedo merged commit cfa6420 into main Mar 17, 2026
2 checks passed

volmedo deleted the vic/feat/prune-proofs branch March 17, 2026 08:59

	Attestations() []Authorization[any]
	Attestations() []Authorization[Caveats]

Uh oh!

Conversation

volmedo commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Implementation details

Uh oh!

alanshaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alanshaw Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

alanshaw left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

volmedo commented Feb 25, 2026 •

edited

Loading

alanshaw Feb 25, 2026 •

edited

Loading

codecov Bot commented Mar 10, 2026 •

edited

Loading