UCAN Capability Tokens

JWT-based User-Controlled Authorization Network tokens signed by an MPC enclave — capabilities, attenuation, delegation chains, templates, and the authorization checks that are not implemented.

github.com/sonr-io/crypto/ucan implements UCAN — capability tokens where authority flows from a key rather than from a server-side ACL. A token is a JWT whose issuer (iss) is a did:key, whose audience (aud) is the recipient’s DID, and whose att claim is a list of attenuations: (capability, resource) pairs. The holder of a token can mint a new token that grants a subset of its own authority to someone else, attaching the parent token as a proof in prf. Verification walks that chain back to a root the verifier trusts.

Tokens carry the UCAN version in a ucv JWT header. In this package that value is the literal "0.9.0", written inline in ucan/source.go; the only exported constant naming it is spec.UCANVersion in mpc/spec.

Reach for this when you need offline-verifiable, expiring, narrowable authorization derived from a key you control.

Read this first

The capability model

Two interfaces carry the whole model.

type Capability interface {
	GetActions() []string          // the actions this capability grants
	Grants(abilities []string) bool // does it grant all of these?
	Contains(other Capability) bool // does it subsume another capability?
	String() string
}

type Resource interface {
	GetScheme() string          // "ipfs", "did", "dwn", "service", ...
	GetValue() string           // the path/identifier
	GetURI() string             // the full "scheme://value"
	Matches(other Resource) bool // equivalence, by URI
}

type Attenuation struct {
	Capability Capability `json:"can"`
	Resource   Resource   `json:"with"`
}

AttenuationList is []Attenuation with query helpers:

Attenuation

Attenuation is the invariant that makes UCAN safe to hand around: a delegated token may only narrow its parent’s authority, never widen it. IsSubsetOf is the check:

parent := ucan.AttenuationList{
	ucan.CreateMultiAttenuation([]string{"read", "write", "delete"}, "service://api"),
}
child := ucan.AttenuationList{
	ucan.CreateSimpleAttenuation("read", "service://api"),
}

child.IsSubsetOf(parent) // true  — narrower
parent.IsSubsetOf(child) // false — wider

The rule composes: for every attenuation in the child list there must exist a parent attenuation whose Resource.Matches is true and whose Capability.Contains is true. Resource matching is plain URI string equality (SimpleResource.Matches), so there is no prefix or wildcard matching at the resource level — only at the action level, via "*".

Capability types

Every type below implements Capability. The module-specific ones exist so that a verifier can pick the right caveat and serialization path from the resource scheme.

GetActions() on the module types returns Actions when non-empty and []string{Action} otherwise; Grants short-circuits to true when Action == "*".

Resources mirror them, each embedding SimpleResource: VaultResource (VaultAddress, EnclaveDataCID), VaultResourceExt, DIDResource (DIDMethod, DIDSubject), DWNResource (RecordType, Protocol, Owner), DEXResource (PoolID, AssetPair, OrderID), and ServiceResource (ServiceID, Domain, plus SupportsDelegate()).

Constructors

The Token type

type Token struct {
	Raw          string        `json:"raw"`
	Issuer       string        `json:"iss"`
	Audience     string        `json:"aud"`
	ExpiresAt    int64         `json:"exp,omitempty"`
	NotBefore    int64         `json:"nbf,omitempty"`
	Attenuations []Attenuation `json:"att"`
	Proofs       []Proof       `json:"prf,omitempty"`
	Facts        []Fact        `json:"fct,omitempty"`
}

type Proof string             // a JWT string or a CID
type Fact struct{ Data json.RawMessage `json:"data"` }

Raw is the encoded JWT when the token came from a verifier or a signing builder, and "" when it came from TokenBuilder, which does not sign.

TokenBuilder

TokenBuilder and TokenBuilderInterface (CreateOriginToken, CreateDelegatedToken) live in ucan/stubs.go and are exactly what the filename says: they assemble a *Token struct with Raw: "" and no signature. CreateDelegatedToken copies parentToken.Raw into Proofs if it is non-empty and sets Audience: parentToken.Issuer.

They exist because NewVaultAdminToken(builder TokenBuilderInterface, vaultOwnerDID, vaultAddress, enclaveDataCID string, exp time.Time) takes the interface. Pass an MPCTokenBuilder-backed implementation if you need a signed result; &TokenBuilder{} gives you an unsigned struct.

MPC signing and verification

This is the path with real cryptography. MPCSigningMethod plugs an mpc.Enclave into golang-jwt/jwt/v5:

func NewMPCSigningMethod(name string, enclave mpc.Enclave) *MPCSigningMethod
func (m *MPCSigningMethod) Alg() string  // returns m.Name; "MPC256" everywhere in this package
func (m *MPCSigningMethod) Sign(signingString string, key any) ([]byte, error)
func (m *MPCSigningMethod) Verify(signingString string, signature []byte, key any) error

Sign computes sha256.Sum256(signingString) and passes that digest to enclave.Sign, which hashes again with SHA3-256 internally. Verify does the mirror image via enclave.Verify.

Builders and validators

KeyshareSource bundles identity and token minting over one enclave:

type KeyshareSource interface {
	Address() string
	Issuer() string
	ChainCode() ([]byte, error)
	OriginToken() (*Token, error)
	SignData(data []byte) ([]byte, error)
	VerifyData(data []byte, sig []byte) (bool, error)
	Enclave() mpc.Enclave

	NewOriginToken(audienceDID string, att []Attenuation, fct []Fact, notBefore, expires time.Time) (*Token, error)
	NewAttenuatedToken(parent *Token, audienceDID string, att []Attenuation, fct []Fact, nbf, exp time.Time) (*Token, error)
}

ChainCode() signs the address string with the enclave. Because DKLs18 ECDSA signing is randomized, ChainCode() returns different 32 bytes on every call despite the doc comment calling it deterministic — measured directly: two successive calls on the same source disagree. Treat it as a fresh signature, not a derivation.

Verification plumbing

type DIDResolver interface {
	ResolveDIDKey(ctx context.Context, did string) (keys.DID, error)
}

Verifier is the general path:

MPCVerifier and MPCTokenValidator layer on top:

func NewMPCVerifier(enclave mpc.Enclave) *MPCVerifier
func (v *MPCVerifier) VerifyMPCToken(ctx context.Context, tokenString string) (*Token, error)

func NewMPCTokenValidator(enclave mpc.Enclave, enableEnclaveValidation bool) *MPCTokenValidator
func (v *MPCTokenValidator) ValidateTokenForResource(ctx, tokenString, resourceURI string, requiredAbilities []string) (*Token, error)
func (v *MPCTokenValidator) ValidateTokenForVaultOperation(ctx, tokenString, enclaveDataCID, requiredAction, vaultAddress string) (*Token, error)

ValidateTokenForVaultOperation is the most complete check in the package, in five ordered steps: verify the token, ValidateVaultTokenCapability, optionally match the enclave-data CID, optionally match the vault address, and finally VerifyDelegationChain if Proofs is non-empty. The two “optionally” steps run only when enableEnclaveValidation was true at construction — pass true unless you know why not.

Signature helpers

SecurityConfig

RestrictiveSecurityConfig() narrows those to {RS256, EdDSA}, MinRSAKeySize: 3072, MaxRSAKeySize: 4096, RequireSecureAlgs: true. ValidateSecurityConfig(config) enforces the bounds noted above.

Templates and policy

CapabilityTemplate is an allow-list of actions per resource scheme, plus lifetime bounds.

tpl := ucan.NewCapabilityTemplate()
tpl.AddAllowedActions("service", []string{"read", "write"})

err := tpl.ValidateAttenuation(ucan.CreateSimpleAttenuation("delete", "service://api"))
// -> "action delete not allowed for resource type service"

err = tpl.ValidateExpiration(tpl.GetDefaultExpirationTime()) // nil

ValidateExpiration treats expiresAt == 0 as “no expiration” and returns nil; a past timestamp errors, and one beyond MaxExpiration errors. "*" in an attenuation is only accepted if "*" is itself in the allow-list for that scheme.

Prebuilt templates, each a NewCapabilityTemplate() with one or two schemes populated:

StandardTemplate is a package-level var populated in ucan/jwt.go’s init() with actions for vault, service, did, dwn, dex, pool and svc. It is the template that VerifyJWTToken and VerifyModuleJWTToken validate against.

Vault and IPFS integration

Vault capabilities address an enclave backup stored in IPFS, so the resource URI is ipfs://<CID>.

VaultAdminAction is the constant "vault/admin". Note that the vault schema’s can set uses slash-prefixed values (vault/read, vault/sign, …) while ValidateVaultTokenCapability and the templates use bare ones (read, sign, …); they are different vocabularies applied at different layers.

TestValidateEnclaveDataCIDIntegrity in ucan/ucan_test.go is the one genuinely end-to-end test in the package, covering empty-CID, empty-data, malformed-CID, matching and mismatching cases.

End-to-end example

Enclave → issuer DID → signed origin token → narrowed delegated token → manual signature check. This uses KeyshareSource, the delegation API that actually enforces attenuation. Every line was run against this package; the printed values below are the observed output.

package main

import (
	"crypto/sha256"
	"fmt"
	"time"

	"github.com/sonr-io/crypto/keys"
	"github.com/sonr-io/crypto/mpc"
	"github.com/sonr-io/crypto/ucan"
)

func main() {
	enclave, err := mpc.NewEnclave()
	if err != nil {
		panic(err)
	}

	// KeyshareSource enforces the subset property on delegation.
	src, err := ucan.NewMPCKeyshareSource(enclave)
	if err != nil {
		panic(err)
	}
	fmt.Println("issuer:", src.Issuer()) // did:key:z...

	// The delegate's identity — here just another enclave's DID.
	delegateEnclave, err := mpc.NewEnclave()
	if err != nil {
		panic(err)
	}
	delegateDID, err := keys.NewFromMPCPubKey(delegateEnclave.PubKeyBytes())
	if err != nil {
		panic(err)
	}

	now := time.Now()

	// Origin token: broad authority over one service resource.
	origin, err := src.NewOriginToken(
		delegateDID.String(),
		[]ucan.Attenuation{
			ucan.CreateMultiAttenuation([]string{"read", "write", "delete"}, "service://api"),
		},
		nil, now, now.Add(time.Hour),
	)
	if err != nil {
		panic(err)
	}

	// Widening is rejected at issuance.
	_, err = src.NewAttenuatedToken(origin, delegateDID.String(),
		[]ucan.Attenuation{
			ucan.CreateMultiAttenuation([]string{"read", "write", "delete", "admin"}, "service://api"),
		},
		nil, now, now.Add(time.Hour))
	fmt.Println("widening rejected:", err)
	// -> "scope of ucan attenuations must be less than its parent"

	// Narrowing is accepted: read only, half the lifetime.
	delegated, err := src.NewAttenuatedToken(origin, delegateDID.String(),
		[]ucan.Attenuation{ucan.CreateSimpleAttenuation("read", "service://api")},
		nil, now, now.Add(30*time.Minute))
	if err != nil {
		panic(err)
	}
	fmt.Println("proofs:", len(delegated.Proofs)) // 1 — the origin token

	// The attenuation invariant, checked locally.
	child := ucan.AttenuationList(delegated.Attenuations)
	parent := ucan.AttenuationList(origin.Attenuations)
	fmt.Println("narrows:", child.IsSubsetOf(parent)) // true
	fmt.Println("widens:", parent.IsSubsetOf(child))  // false
	fmt.Println("can read:", child.CanPerform("service://api", []string{"read"}))     // true
	fmt.Println("can delete:", child.CanPerform("service://api", []string{"delete"})) // false

	// Signature verification, done directly against the public key.
	unsigned, err := ucan.ExtractUnsignedToken(delegated.Raw)
	if err != nil {
		panic(err)
	}
	sig, err := ucan.ExtractSignature(delegated.Raw)
	if err != nil {
		panic(err)
	}
	digest := sha256.Sum256([]byte(unsigned))
	ok, err := mpc.VerifyWithPubKey(enclave.PubKeyBytes(), digest[:], sig)
	fmt.Println("signature valid:", ok, err) // true <nil>
}

Not actually implemented

Each item below was verified by reading the named source file and then confirmed by running it. Delegation enforcement is covered separately, under Only KeyshareSource enforces attenuation at issuance.

Measured against this package:

Next