UCAN (User Controlled Authorization Networks)

UCAN enables user-centric access control for services like IPFS or Filecoin. Instead of a central server holding API keys, a user holds a UCAN token that grants an app permission to read/write to their specific storage space. The user can revoke this token at any time, and the app can further delegate limited capabilities (e.g., read-only) to a background service without involving the original storage provider.

• Example: A photo gallery app requests a UCAN from the user to upload images to their personal IPFS node.

UCAN tokens can be used to orchestrate workflows across different decentralized services. A user can grant a dashboard app a token to perform specific actions, which the app can then decompose into subtasks and delegate to specialized microservices.

• Example: A user authorizes a "data backup" task. The main app uses its UCAN to delegate a "fetch emails" capability to one service and a "store on Arweave" capability to another, without ever handling the user's raw credentials for either service.

UCAN facilitates secure, credential-less communication between client applications and serverless functions. A client can embed a UCAN token in an HTTP request to a cloudflare worker or AWS Lambda, proving its right to invoke the function and access specific resources. This eliminates the need for the edge function to manage API keys or session states, enabling truly stateless, scalable backends.

UCAN provides a standardized model for fine-grained, revocable API access. A user can grant a third-party SaaS tool a token with precise permissions (e.g., "read repo A, write to issue tracker B"). This token is cryptographically signed and can be invalidated by the user instantly, providing better security and auditability than traditional OAuth tokens or static API keys stored in a database.

UCAN can underpin DID (Decentralized Identifier) interactions by allowing users to issue attestations. A user could sign a UCAN token stating "App X may assert that I am over 18" or "Service Y may post to my social feed." These capability-based attestations are more granular and context-specific than broad OAuth scopes, enabling richer, user-controlled social graphs and identity proofs.

UCAN is an implementation of capability-based security, a paradigm where access rights are unforgeable tokens (capabilities) passed between entities. Key principles include:

• Principle of Least Authority: Tokens grant the minimum permission needed.
• Delegation: Capabilities can be passed on, creating an audit trail.
• Object-Capability Model: The token itself is the authority; no separate access control list (ACL) is required for verification.

This contrasts with identity-based systems where access is checked against a central list of permissions.

A UCAN is a JWT-like token that encodes a user's capabilities (permissions). The token is self-contained, signed by the user's private key, and can be delegated. Key components include:

• iss (Issuer): The user who created the token.
• aud (Audience): The service or resource being accessed.
• att (Attenuation): The specific permissions granted.
• exp (Expiration): A mandatory, short-lived validity period.
• prf (Proof): A chain of previous UCANs proving the delegation path.

UCAN's defining feature is delegation without a central authority. A user can create a new UCAN token that grants a subset of their own permissions to another agent (e.g., a bot or service). This creates a verifiable chain of authorization where:

• Each link in the chain is cryptographically signed.
• Permissions can only be reduced (attenuated), never expanded.
• The final resource server can validate the entire chain back to the root user without contacting an auth server.

UCAN eliminates the traditional OAuth-style authorization server. Instead of a service checking permissions with a central database (e.g., "Does Alice have write access?"), it cryptographically verifies the UCAN token's signature chain and attenuation. This enables:

• Offline-first application design.
• Reduced latency and single points of failure.
• User sovereignty over identity and access credentials.

UCANs are often used in conjunction with DIDs. The iss and aud fields in a UCAN are typically DIDs, not traditional usernames. This pairing creates a fully decentralized identity and access stack:

• DID: Provides the persistent, verifiable identifier (the "who").
• UCAN: Provides the revocable, delegatable authorization (the "what they can do").
• Together, they enable trust without centralized registries.

UCAN is a specification with implementations in multiple languages, promoting interoperability. Key technical notes:

• Token Format: Based on CBOR or JSON, signed with Ed25519 or secp256k1.
• Validation: A resource server must check the signature chain, expiration, and that the att permissions satisfy the requested action.
• Libraries: Official implementations include TypeScript/JavaScript (ucans) and Rust, with community ports for other languages.

UCAN implements a capability-based security model, where authorization is a transferable token representing a specific right (e.g., 'write to this file') rather than an identity check. This enforces the principle of least privilege by default.

• Tokens are bearer instruments: Possession of the token is proof of the capability.
• Delegation is explicit: A user can delegate a subset of their rights by issuing a new, scoped token without involving the original service.
• Revocation is resource-specific: Since capabilities are resource-scoped, revoking one does not affect others.

Authorization in UCAN is verified through cryptographic proof-of-possession, not a centralized authority. A UCAN token (a JWT) is signed by the issuer's private key, and any service can validate it using the corresponding public key.

• No central auth server: Services do not need to call a central OAuth server to validate tokens.
• Offline verification: Tokens can be verified as long as the service has the issuer's public key, enabling offline-first applications.
• Auditability: The chain of signatures from the root user to the final token provides a verifiable delegation trail.

A core feature is attenuation, the ability to create new tokens with equal or fewer permissions than the parent token. This creates a delegation chain rooted in the user's initial key.

• Scoping: A token granting 'write access to folder A' can be attenuated to grant 'write access to file A1'.
• Expiry reduction: A delegated token must have an expiry time less than or equal to its parent, preventing indefinite delegation.
• Chain validation: Services validate the entire signature chain to ensure every delegation was authorized and properly attenuated.

UCAN handles revocation differently than session-based systems. Since tokens are bearer instruments, the primary revocation mechanism is key rotation at the root.

• Revoke by rotating keys: If a user's root private key is compromised, they generate a new key pair. All tokens signed by the old key become invalid.
• Short-lived tokens: Encouraging short expiry (ttl) limits the blast radius of a compromised token.
• Resource-led revocation: Some implementations use revocation lists stored with the resource provider for more granular, immediate control.

Adopting UCAN requires specific architectural patterns from service developers.

• Stateless validation: Services must be designed to validate tokens without shared state, relying on embedded signatures and public key resolution (e.g., via DID).
• Public key infrastructure: Requires a reliable way to resolve the issuer's public key, often using Decentralized Identifiers (DIDs).
• Capability discovery: Users and services need methods to discover what capabilities are available and how to request them, often through capability manifests.

UCAN addresses several limitations of the dominant OAuth 2.0 standard in decentralized contexts.

• User Control: OAuth relies on centralized authorization servers; UCAN is user-issued.
• Offline Access: OAuth requires online validation; UCAN tokens can be verified offline.
• Delegation Granularity: OAuth scopes are coarse and app-defined; UCAN enables fine-grained, user-defined capability delegation.
• Architecture: OAuth is designed for client-server web models; UCAN is designed for peer-to-peer and local-first applications.

UCAN implements a capability-based security model, a paradigm where authority is held by unforgeable tokens (capabilities). This contrasts with identity-based access control (e.g., ACLs). Key principles include:

• Principle of Least Authority: Delegation is scoped and attenuated.
• Object-Capability Model: Capabilities are both a reference to a resource and the permission to use it.
• Delegation as a First-Class Operation: Rights can be passed along a chain of trust.