DOCSEARCHbyAlgolia
Submit Docs

UCAN (User Controlled Authorization Network) Specification

repository·main·Indexed 42 days ago

https://github.com/ucan-wg/spec

A distributed, local-first authorization framework using cryptographically verifiable certificate chains to manage permissions without a central authority. The specification defines a capability model using Decentralized Identifiers (DIDs), DAG-CBOR encoding, and a hierarchical command system for delegable, public-key verifiable authority.

Tokens
6.1K
Snippets
7
Records
31
Agent score
55%

What's inside UCAN

  1. What is User Controlled Authorization Network (UCAN)?

    main

    UCAN is a trustless, secure, local-first, user-originated, and distributed authorization scheme. It provides public-key verifiable, delegable, and expressive capabilities.

    Key characteristics include:

    • Public Verifiability: Achieved through late-bound certificate chains.
    • Decentralized Identity: Principals are represented by Decentralized Identifiers (DIDs).
    • Inversion of Control: Unlike traditional systems that use a central Authorization Server (AS), UCAN allows the resource owner to grant authority over the resource directly to agents. This makes the system fully distributed, scalable, and partition-tolerant.
    • Capability Model: It uses a certificate capability model (similar to SPKI) where authority is passed via cryptographically verifiable chains rather than centralized Access Control Lists (ACLs).

  2. Implement Attenuation in Delegation Chains

    main
    Attenuation is the process of constraining capabilities within a delegation chain. Every direct delegation must either restate its existing capabilities or attenuate (diminish) them to ensure the delegate has strictly fewer or equal rights than the delegator.

  3. Compare Access Control Lists (ACLs) and Certificate Capabilities

    main

    UCAN uses a Certificate Capability model, which differs significantly from traditional Access Control Lists (ACLs):

    Access Control Lists (ACLs)

    • Mechanism: A central list (maintained by a bouncer/resource) tracks which identities are allowed access.
    • Drawbacks: Requires synchronization between distributed nodes, creates high maintenance burdens as systems grow, and is susceptible to 'confused deputy' problems. It relies on identity verification (e.g., checking an ID).

    Certificate Capabilities (UCAN)

    • Mechanism: Authority is held in a transferable token (like a movie ticket). Possession of the valid certificate proves the right to access.
    • Advantages: No central coordination is required for delegation (you can hand a ticket to a friend). It is highly suitable for distributed, offline, or partition-tolerant systems where identity is less important than the proof of authority.

  4. Supported signature algorithms in the UCAN cryptosuite

    main

    The UCAN cryptosuite is designed for broad interoperability by supporting multiple signature algorithms. This allows UCAN to leverage existing Public Key Infrastructure (PKI) such as the WebCrypto API and various cryptocurrency wallets.

    Supported algorithms include:

    • Ed25519: The ideal single-algorithm choice.
    • P-256: Supported for compatibility with the WebCrypto API and other standard PKI.
    • secp256k1: Supported for compatibility with many cryptocurrency wallets.

    This multi-algorithm approach is similar to the design of JWT (JSON Web Tokens).

  5. Using UCAN with CRDTs and RSMs

    main

    UCAN is designed for location-independent, offline, and leaderless systems. When applying UCAN to Replicated State Machines (RSM) or Conflict-free Replicated Data Types (CRDT), you can model the requirement by lifting the requirement that the Executor be the Subject.

    In a 'Pull' model, an Invoker doesn't require a specific replica to apply its state. Applying a change to a local CRDT replica and maintaining a UCAN invocation log is a valid update to the CRDT. Gossiping these changes allows agents to apply changes they become aware of, with the invocation log providing transparent provenance of authority.

  6. Format and Structure of Commands

    main

    Commands (or "verbs") are messages that must be unambiguously interpretable by the Subject of a UCAN. They define the specific actions allowed.

    Syntax Rules:

    • Must be lowercase.
    • Must begin with a forward slash (/).
    • Segments must be separated by a slash.
    • A trailing slash MUST NOT be present.

    Hierarchical Logic: Shorter commands prove longer paths. For example, /crypto can prove /crypto/sign, but it cannot prove /stack/pop.

    Examples of valid commands:

    • / (The wildcard/top command)
    • /crud
    • /crud/create
    • /stack/pop
    • /foo/bar/baz/qux/quux

  7. Compare UCAN with related authorization protocols

    main

    UCAN is a capability-based authorization system. When choosing or integrating UCAN, it is helpful to understand how it differs from other models:

    • SPKI/SDSI: Very similar core ideas and usage patterns, but UCAN uses a different encoding format and includes modern features like Content IDs (CIDs).
    • ZCAP-LD: Similar, but UCAN differs in formatting, uses CIDs instead of URLs for addressing, and has a different mechanism for separating invocation from authorization.
    • CACAO: A cross-blockchain delegated bearer token model. Unlike UCAN, CACAO is aimed at small messages/identities rooted in mutable blockchain documents and lacks sub-delegation capabilities.
    • Local-First Auth: A non-certificate approach using CRDTs to manage members and roles. It uses an invitation mechanism based on Seitan token exchange.
    • Macaroon: A MAC-based system for trusted networks (typically Cloud). It relies on symmetric signatures for performance/space savings and is rooted in an originating server rather than an end-user.
    • Biscuit: Uses Datalog to describe capabilities; otherwise similar to UCAN.
    • Verifiable Credentials: Focused on asserting attributes about a DID holder (e.g., age, work history) rather than capability delegation.

  8. Use SHA-256 for CID Hashing

    main
    UCAN specifies the use of the SHA-2 family (specifically SHA-256) for CID hashing. While other algorithms like BLAKE3 may offer higher software performance, SHA-2 is chosen because it is already a requirement for the signature algorithms within UCAN's cryptosuite and enjoys near-universal availability across different environments.

  9. Use `base58btc` for Canonical CID Encoding

    main

    UCAN utilizes base58btc encoding for CIDs to ensure canonical encoding and compatibility with common CID tools.

    Why base58btc is used instead of base32: While base32 is common in web technologies (like browser subdomains) due to its case-insensitivity, case-insensitivity is problematic for CID canonicalization because multiple different CIDs could map to the same underlying hash. base58btc avoids this collision risk by being case-sensitive and providing a unique mapping.

  10. Define a Capability

    main

    A capability is the association of an ability to a subject, modeled as subject x command x policy.

    • Subject: The DID of the agent the capability is for (REQUIRED).
    • Command: The action being permitted (REQUIRED).
    • Policy: The conditions under which the command is allowed (OPTIONAL/Extensions).
    {
  "Subject": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "Command": "/msg/send",
  "Policy": ["or", ["==", ".from", "mailto:me@example.com"], ["match", ".cc", "mailto:*@example.com"]]
}

  11. Hashing requirements in the UCAN cryptosuite

    main
    The UCAN cryptosuite relies on the SHA-2 family of hash functions, specifically SHA-256, as a requirement for its signature algorithms. While faster alternatives like BLAKE3 exist, SHA-256 is used because it is effectively available in almost all environments without requiring additional packages, which helps minimize implementation complexity and bundle size.

  12. Define a Subject and Resource

    main

    In UCAN, a Subject is the Agent for whom a capability is intended. A Subject MUST be referenced by a DID (Decentralized Identifier) to ensure unforgeability and prevent namespace collisions.

    A Resource is the 'noun' of a capability—the specific data or process being accessed (e.g., a database row, a user account, or a storage quota).

    • Resources MUST be provided in URI format.
    • Finer-grained resources are recommended to follow the Principle of Least Authority (PoLA).
    • Unless explicitly stated, the Resource of a UCAN is assumed to be the Subject.