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.

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?

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

alanshaw

Not finished review - just submitting what I have :)

alanshaw · 2026-06-08T16:34:48Z

-	client, _ := ed25519.Generate()
-	service, _ := ed25519.Generate()
+	client, _ := ed25519.GenerateIssuer()
+	service, _ := ed25519.GenerateIssuer()


Is there a Generate... function that does not create an issuer? I wonder if this should be Generate() and reduce churn to just a import change?

Generate() generates a signer, since that's more fundamental. GenerateIssuer() is a convenience wrapper that makes a multikey.KeyIssuer() out of it.

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.

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:17:28Z

Can we just call this package resolver?

Oh, yeah, that does sound nice. 👍🏻

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.

Peeja added 20 commits June 6, 2026 21:23

feat: ValidateToken takes options, too

e2a2387

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

feat: DID Document parser

3c95155

feat: Easier to add verification methods to a document

864a4c4

refactor: Add Unmarshal tests for VerificationMethod

563a402

feat: Can add a verification method to a relationship

0a1ba31

refactor: Merge did/document into did pkg

c9163ee

fix: publicKeyMultibase is technically optional

f866884

refactor: VerificationMaterial alone determines type

9e42d63

refactor: RegisterVerificationMethodType() finds type name from fac…

2399ad0

…tory

refactor: Validator resolves DIDs and verifiers separately

8477c71

WIP: Rework principal -> verification

3caddad

refactor: DID VM types don't need Go types

483bea9

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

a6433dc

refactor: Varsig doesn't use type parameters

2412ae6

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

refactor: Clarify and simplify varsig

f1bfe2f

feat: Validator works with any sig algorithm

9df6815

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

044b820

doc: Update README

b1c20ae

fix: WithSigner -> WithIssuer

d6f7369

Peeja mentioned this pull request Jun 7, 2026

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

Open

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

alanshaw reviewed Jun 10, 2026

View reviewed changes

refactor: web.WithInsecure() takes a boolean

c7817ae

Peeja added 4 commits June 16, 2026 14:42

refactor: Restore cut-off doc comments

1ca27f7

refactor: utilresolvers → resolver

6d7f063

refactor: Single error for unsupported methods

21e2238

fix: Update go.sum

a8b9ef2

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Peeja commented Jun 7, 2026 •

edited

Loading