4.26.1 UCAN Types And Context

Principals And Keys

Adding a principal makes its private key available for signing. Public keys are encoded in their DIDs and may be cached to avoid repeated decoding. The interface does not prescribe whether returned native key objects are shared or freshly allocated; callers must follow the implementation’s ownership policy rather than release possibly cached keys themselves.

normalize-did(did: string) -> string strictly validates an Ed25519 did:key and returns its canonical unpadded base64url (u) spelling. Valid base58btc (z) aliases denote the same identity; malformed or unsupported DIDs raise a contract violation. The result is borrowed and read-only, and may be the input string or a shared cached string. Inputs retained by the context must also be treated as immutable. Normalization never rewrites fields inside signed tokens.

Tokens

Signing requires the issuer’s private key to be available in the context. Saving retains a token for future revocation support; it is distinct from signing and does not revoke tokens.

A context’s verify policy must establish valid signatures, unexpired tokens, delegation narrowing, and trust through a root or input anchor. The standalone verify-token helper performs chain validation only; its success is not sufficient to establish authorization.

The keystore-backed context also treats principal DIDs present at opening as implicit roots. These are separate from explicit database roots; see Signing And Trust for snapshot semantics.

Trust

Output anchors are parent tokens used to authorize outgoing operations, such as sending a message or opening a stream. Input anchors confer partial trust for particular audiences and capabilities. A root is fully trusted as an issuer anywhere in a valid chain, so roots should be reserved for entities such as the owner of the host or organization.

The concrete context stores explicit roots canonically: adding either accepted spelling deduplicates the identity, and removing either spelling removes it. Root listings return borrowed, read-only canonical strings.

Both anchor insertion methods require valid signatures, unexpired tokens and valid delegation chains. Reject invalid anchors before changing policy. This is credential verification, not a requirement for an already configured root/input trust path: installing an anchor is an explicit application policy decision.

Inherited close releases implementation resources. Persistence, caching, ordering, and duplicate-handling details are implementation-specific. The internal database backend supplies storage, while the keystore supplies private-key storage; neither is itself a complete CapabilityContext.