feat: Attested Signatures + UCAN Principal Clarification by Peeja · Pull Request #30 · fil-forge/ucantone

Peeja · 2026-06-07T01:39:18Z

This is part of a set of PRs across the fil-forge repos. They all work together using a go.work. ~~I'm not sure how to make CI do anything useful, though.~~ Figured it out. I put the solution in its own set of PRs, but I've rebased these on top of them anyhow.

Attested Signatures + UCAN Principal Clarification

This PR (along with coordinated changes in sibling repos) reimplements attested signatures. This was written less thoroughly in sprue#15, but it needed to be more central for everything in the network to use it.

Pulling on that thread unraveled a whole bunch of latent issues with the domain model in UCAN. Nothing fundamentally wrong, just some things that were conflated that are now teased apart to reflect some subtle but important distinctions.

Attested Signatures

To recap: did:mailto: DIDs have no native key material. Rather than signing directly, a mailto DID delegates to a trusted authority (the signing service), which issues a /ucan/attest/proof invocation over a SHA2-256 hash of the message. That invocation is the signature. On the verify side, the signature is decoded as an invocation, the hash is checked against the message, and the invocation is validated against the authority.

DID Documents as First-Class Objects

Previously, we "resolved" DIDs directly to verifiers. Now DID documents are a first-class concept in the did package, rather than being reimplemented in multiple codebases.

The previous code assumed that there was a one-to-one mapping between DIDs and signers/verifiers. That's a natural asssumption when most things are did:key:s, where that's true. But in general, a DID document can have multiple verificationMethods, and that's what actually maps to a signer/verifier pair.

Now we can resolve a DID to a document, and turn a verification method within it into a verifier. We can also make a "multi-verifier" (which succeeds if any of them succeed) out of all of the verification methods in the document, or out of just those with a particular verification relationship (notably CapabilityInvocation and CapabilityDelegation).

did.Document is now a real typed struct with verification relationships. Resolvers return documents; verifier derivation is a separate step via a pluggable factory registry. This is what makes custom verification method types (like AuthorityAttestation) possible.

For did:mailto:, didmailto.Resolver generates synthetic DID documents on-the-fly. Each document contains an AuthorityAttestation verification method naming the authority, and the registered factory for that type produces an AttestedVerifier.

UCAN 1.0 Terminology

The refactor also tightens up the principal/signing model:

Principal remains "something with a DID()".
Signer and Verifier are no longer Principals. They only deal in signatures. A verification method exists independently of a DID, and a signer or verifier exists independently for the same reason. But they're often tied together, so…
Issuer is now the noun for "a Signer tied to a Principal". In many cases, Issuer simply replaces the existing use of Signer. Notably, there are lot of variables already named issuer which were ucan.Signer and are now ucan.Issuer, which gives me some confidence that this is correct.
multikey is now a specific family of Signers and Verifiers which are based on cryptographic keys which the DID document represents as Multikey-type verification methods, specifically Ed25519 and secp256k1 currently. There's a set of enhanced multikey.Issuer, multikey.Signer, and multikey.Verifier types which know about the keys they represent.
did:key:s are not keys and vice versa. Because of the conflation of signers/verifiers and identities, keys were often represented as the corresponding did:key:s. But these are different things: a key is a method of signing and verification, while a DID is something that identifies a subject. The subject of a did:key: is, generally speaking, the entity which holds the private key—which is different from being the key itself! Now that's clearer.
Thus we no longer "wrap" keys. Previously, you'd accomplish a did:web: signer by creating a did:key: signer and wrapping it with a did:web: so that it reported that as its DID. Now they're separate concerns. The equivalent of "wrapping" is multikey.NewIssuer(did.DID, multikey.Signer) multikey.Issuer. The equivalent of unwrapping is anIssuer.PrivateKey()—which returns an actual key, not a principal.
We also have identity.Identity. This was promoted from sprue to solve the same problem in other modules. Identity simply wraps an Issuer to provide a DIDDocument() factory, which can then be used both to serve the DID document on the web and to resolve one's own DID. Identity is intended to be used for "our" identity in any given service. The fact that it's such a simple wrapper seems like a smell to me, but it's useful and I didn't want to mess with it too much. It might want a little massaging in the future.

Questions for Reviewers

For attested, the verification needs a context, because it needs to recursively validate the invocation that is the attestation signature. But Verify() doesn't take a context right now, so the verifier holds a context given at creation. That's a bit odd. Should Verify() change to take a context, or should we keep doing this?

alanshaw

Not finished review - just submitting what I have :)

alanshaw · 2026-06-08T16:40:30Z

+		Material:   did.GenericMap{did.MultikeyPublicKeyMultibaseProp: d.Identifier()},
+	}
+
+	if err := doc.VerificationMethods.Add(vm); err != nil {


nit: we're Adding here to a pluralised VerificationMethods but the others below are singular.

Well, not exactly. The others aren't nouns, they're verbs. "CapabilityDelegation" doesn't contain capability delegations, it contains verification methods which can be used for the delegation of capabilities. I have pluralized VerificationMethods where the actual JSON key is verificationMethod, because…it just felt really weird not to. So we're already messing with the names a bit here, and we could mess with them more, but pluralizing the others wouldn't make sense. WDYT? What would read best to you?

alanshaw · 2026-06-08T18:20:35Z

+// error if it cannot resolve the DID so the next tier can be tried. If all
+// tiers fail, the error from each tier is aggregated and returned in a single
+// error.
+type Chain []did.Resolver


IMO "tiered" is a better description of what this is...

Tier sounded like it carried a lot of semantic baggage to me; I was going for the Chain-of-responsibility pattern here. But I'm not against changing it back. Do you have other examples of "tier" being used this way? It seemed novel to me, but that might just be my own experience.

Can we at least remove "tier" from the description above?

alanshaw · 2026-06-09T11:34:58Z

+)
+
+// WellKnown is a simple resolver that looks up DIDs in a local mapping.
+type WellKnown map[did.DID]did.Document


👏 but this is a better name than "map" resolver

alanshaw · 2026-06-10T18:06:34Z

+	}
+}
+
+func WithInsecure() Option {


FWIW, I find it easier to pass a bool here than have to conditionally add the option.

Ooh, yes, that's much better.

Ah, I think I must have done that because I remembered it from the otel code. That has a WithInsecure() option. But I agree, passing the explicit boolean (and being able to override it back with another option) is better.

alanshaw · 2026-06-10T18:09:46Z


 // Method returns the DID method name (e.g. "key", "web") parsed from the
-// scheme. Returns "" for an undefined DID.
+// scheme. Returns "" for an undefined


? does not make sense

…I have no explanation. 😅 revert

alanshaw · 2026-06-10T18:24:22Z

+	return f(ctx, d)
+}
+
+type ResolverMap map[string]Resolver


Is this a duplicate of the ByMethod resolver?

Oh, dang, it is. That was supposed to go away. It's only used in tests. Lemme get that…

alanshaw · 2026-06-10T18:24:58Z

+	return resolver.Resolve(ctx, d)
+}
+
+type MethodNotSupportedError struct {


This is repeated in errors.go

alanshaw · 2026-06-10T18:26:09Z

Do you think we should put the code related to DID documents in a document package?

I had one for a bit, but it was clunky. There were some dependency issues, and a document was a document.Document instead of a did.Document. Fundamentally, I realized that DID documents are pretty core to what DIDs are, so it made sense to put them in the same package. We could split them out if it's just too crowded and alias things for the outside world to use from the main did package, but I don't think it actually makes it any easier to work with.

Call libforge's reusable go-workspace-test workflow so PRs that share a branch name with sibling repos are tested against those siblings' branches. When no sibling has a matching branch, the job is skipped and the normal go-test.yml remains the signal. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

alanshaw

I don't have any major issues here - it'll be great to get this in. I would like to rename the import for multikeys - it's often used for generating keypairs and I think that it just very weird to be importing from a verification package to do that. Also if you ever need to import from the ed25519 verifier package you end up with verification AND verifier in the import path e.g. github.com/fil-forge/ucantone/verification/multikey/ed25519/verifier

alanshaw · 2026-06-17T16:41:47Z

+// error if it cannot resolve the DID so the next tier can be tried. If all
+// tiers fail, the error from each tier is aggregated and returned in a single
+// error.
+type Chain []did.Resolver


Can we at least remove "tier" from the description above?

alanshaw · 2026-06-17T16:47:45Z

 type ResponseOption func(r *ExecResponse) error

-func WithSigner(signer ucan.Signer) ResponseOption {
+func WithSigner(issuer ucan.Issuer) ResponseOption {


Should be renamed WithIssuer?

alanshaw · 2026-06-17T17:27:12Z

 	"github.com/fil-forge/ucantone/server"
 	"github.com/fil-forge/ucantone/ucan/command"
 	"github.com/fil-forge/ucantone/ucan/invocation"
+	"github.com/fil-forge/ucantone/verification/multikey/ed25519"


This change from principal/ed25519 to verification/multikey/ed25519 is particularly jarring. I think it's unexpected to have to import from a verification package to generate a crypto key pair and use it to issue UCANs.

Suggestions:

Remove "multikey" and rename "verification" to "crypto" e.g. github.com/fil-forge/ucantone/crypto/ed25519. We only use multikey keys here - do we need it in the import path? Using crypto echos Golang crypto from standard lib.

Move multikey to top level e.g. github.com/fil-forge/ucantone/multikey/ed25519. Double down on it being "multikey". The verification package can stay, although perhaps it belongs in existing did package?

Keep "principal", importing ed25519 provides a Generate function that returns an ucan.Issuer e.g. github.com/fil-forge/ucantone/principal/ed25519. The new verification/multikey/ed25519 stays as is, except without GenerateIssuer function. Most backwards compatible, least churn.

I think I'm leaning towards 2 the most...

I agree, I like 2 also. 👍🏻

The verification package itself dissolved nicely: NewIssuer() was redundant with multikey.NewIssuer(), and the verifier factory types really belonged in validator all along.

This makes it practical to use on its own, outside of `ValidateInvocation` (for validating a delegation, for instance).

…tory

No reason to have a registry to parse different verification method types when they're just bags of fields. It's the verifier that uses it that's interesting.

They weren't really being used outside of one pair of tests.

No need to filter them up front, just try them all. It's safe, and there's rarely more than one anyway.

- did/web: new did:web resolver - did/utilresolvers: ByMethod, Chain, Cached, WellKnown resolver combinators - verification: replace global init()-based registry with explicit Factory/Registry types; validator now takes verifierFactories via DefaultFactories() + WithVerifierFactory() - multikey: add NewIssuer, richer Signer/Verifier interfaces (Code, PublicKey, Raw, PrivateKey) - did: add New(), MustParse(), ValidateMethod(), UnsupportedMethodError

* `multikey` and `absentee` go up a level to the root. * `verification.NewIssuer()` is gone; we can use `multikey.NewIssuer()` in every case we have. * The verifier factory types move `validator`. They're not inherent to *validation*, they're just used to configure the validator.

See fil-forge/ucantone#30

Peeja mentioned this pull request Jun 7, 2026

feat: Attested Signatures + UCAN Principal Clarification fil-forge/libforge#37

Merged

Peeja marked this pull request as ready for review June 7, 2026 01:46

alanshaw reviewed Jun 10, 2026

View reviewed changes

alanshaw approved these changes Jun 17, 2026

View reviewed changes

Peeja added 19 commits June 17, 2026 17:31

feat: ValidateToken takes options, too

35ce799

This makes it practical to use on its own, outside of `ValidateInvocation` (for validating a delegation, for instance).

feat: DID Document parser

a95e20f

feat: Easier to add verification methods to a document

b35609f

refactor: Add Unmarshal tests for VerificationMethod

7458d1d

feat: Can add a verification method to a relationship

da3b8a0

refactor: Merge did/document into did pkg

c1e6d80

fix: publicKeyMultibase is technically optional

82fe273

refactor: VerificationMaterial alone determines type

4eeb443

refactor: RegisterVerificationMethodType() finds type name from fac…

e1ba089

…tory

refactor: Validator resolves DIDs and verifiers separately

b79af53

WIP: Rework principal -> verification

61ce354

refactor: DID VM types don't need Go types

a9e5fd6

No reason to have a registry to parse different verification method types when they're just bags of fields. It's the verifier that uses it that's interesting.

feat: Validation error explains reasons for each method

00cee24

refactor: Varsig doesn't use type parameters

9bb76c9

They weren't really being used outside of one pair of tests.

refactor: Clarify and simplify varsig

b0fc9ae

feat: Validator works with any sig algorithm

4ca1af1

No need to filter them up front, just try them all. It's safe, and there's rarely more than one anyway.

refactor: ErrorModel supports causes

d94a2d3

doc: Update README

ffc616b

Peeja added 7 commits June 17, 2026 17:31

fix: WithSigner -> WithIssuer

0e90a0c

refactor: web.WithInsecure() takes a boolean

4acd74d

refactor: Restore cut-off doc comments

5579739

refactor: utilresolvers → resolver

afc872b

refactor: Single error for unsupported methods

f1ce65b

fix: Update go.sum

a6a94ed

refactor: Change resolver.Chain back to resolver.Tiered

0fc2ef3

Peeja force-pushed the petra/feat/attested-signatures branch from a8b9ef2 to 0fc2ef3 Compare June 17, 2026 21:38

Peeja added 2 commits June 17, 2026 17:39

refactor: WithSigner() should be WithIssuer()

1cb231f

Peeja merged commit 7985ec0 into main Jun 19, 2026
1 check passed

Peeja added a commit to fil-forge/libforge that referenced this pull request Jun 19, 2026

feat: Attested Signatures + UCAN Principal Clarification (#37)

4144e65

See fil-forge/ucantone#30

Peeja added a commit to fil-forge/piri that referenced this pull request Jun 19, 2026

feat: Attested Signatures + UCAN Principal Clarification (#18)

5afd85f

See fil-forge/ucantone#30

Peeja added a commit to fil-forge/sprue that referenced this pull request Jun 19, 2026

feat: Attested Signatures + UCAN Principal Clarification (#20)

56a55dc

See fil-forge/ucantone#30

Conversation

Peeja commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Attested Signatures + UCAN Principal Clarification

Attested Signatures

DID Documents as First-Class Objects

UCAN 1.0 Terminology

Questions for Reviewers

Uh oh!

alanshaw left a comment

Choose a reason for hiding this comment

Uh oh!

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!

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!

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 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Peeja commented Jun 7, 2026 •

edited

Loading