Authorization

Cocoon replaces traditional role-based access control (RBAC) with UCAN (User Controlled Authorization Networks), a capability-based delegation system where permissions are cryptographically chained rather than assigned by a central authority.

UCAN inverts the access control model. Instead of asking "does this user have the admin role?", the system asks "does this token prove the holder can perform this specific action?" Permissions travel with the token, not the identity.

Why UCAN Instead of RBAC

In a role-based system, a central authority decides what each role can do, and users are assigned roles. This requires a trusted registry and creates a single point of control — and failure.

UCAN works differently. Every capability is a statement: "I can do X." Delegation is: "I grant you the ability to do X, subject to restrictions Y." The chain of grants from the original resource owner to the final invoker is verifiable without contacting any central authority.

Concept	RBAC	UCAN
Permission storage	Central database	Token payload
Trust anchor	Identity provider	Cryptographic signature
Delegation	Role assignment	Token issuance with attenuation
Revocation	Delete from DB	On-chain revocation registry
Offline verification	Not possible	Yes, via signature chain

Delegation Model

A UCAN token is a signed JWT-style structure containing: the issuer DID, the audience DID, an expiry timestamp, and a set of capabilities the audience may exercise. Attenuation means a delegatee can never grant more than the delegator holds.

Each hop in the chain must be verifiable independently. The external auditor's token embeds references (CIDs) to all parent tokens in the chain, so the verifier can reconstruct the full proof without any external calls to a directory service.

EIP-8141 Integration

EIP-8141 defines native account abstraction for Cocoon's execution layer. UCAN tokens are embedded directly in frame transactions — the Cocoon equivalent of EIP-4337 UserOperations.

When a frame transaction arrives at the node, the UCAN verifier contract is called before execution proceeds:

1. The frame payload includes a ucanProof field containing the full delegation chain (or CIDs pointing to tokens stored via torrent-ccip).

2. The node's RPC middleware extracts and validates: signature validity, capability match, expiry, and revocation status.

3. On-chain, the UCAN verifier contract performs final verification for any action that mutates state.

4. The revocation registry is checked — a token CID appearing in the registry is immediately rejected regardless of signature validity.

UCAN tokens have expiry timestamps. Tokens issued with very short expiry windows improve security but require more frequent re-delegation. Tokens issued without expiry rely entirely on the revocation registry for invalidation — ensure your revocation registry is up to date.

DID Bridging

Cocoon supports multiple DID methods to accommodate different key types and contexts:

DID Method	Key Material	Use Case
did:pkh	Ethereum address (secp256k1)	Standard EOA accounts
did:key	ML-KEM-768 post-quantum key	Post-quantum secure delegation
did:key	Ed25519	Lightweight service identities

The DID bridge resolves between these namespaces, allowing a single UCAN chain to span an Ethereum address (fund manager), a contract wallet (portfolio manager), and a post-quantum key (automated agent).

Signing Backends

UCAN tokens must be signed. Cocoon supports the full spectrum of Ethereum signing mechanisms:

Backend	Standard	Description
EOA	ERC-191 / ERC-712	Standard private key signing
Contract wallet	ERC-1271	isValidSignature on-chain
Account abstraction	ERC-4337	Bundled UserOperation signing
Delegated signing	EIP-7702	EOA delegates to contract logic
Native AA	EIP-8141	Frame-native account abstraction

This means any Ethereum account — hardware wallet, multisig, smart contract wallet, or AA account — can be the root authority or a delegate in a UCAN chain.

Capability Namespaces

Capabilities are structured as hierarchical namespaces. A capability at /token/owner/* implies all capabilities nested beneath it. Attenuation means a delegatee can hold /token/investor/view but never escalate to /token/owner/* even if they issue tokens to themselves.

Namespace	Scope
/token/owner/*	Full token ownership actions (transfer, burn, configure)
/token/agent/*	Automated agent actions on behalf of token holder
/token/investor/*	Investor-facing actions (subscribe, redeem, view holdings)
/storage/*	Read/write access to torrent-ccip stored data
/id/*	Identity management (issue credentials, update DID document)
/webf/*	Web hosting management (publish, update, delete sites)
/auth/*	Authorization management (delegate, revoke, inspect)

Example delegation: a fund manager holds /token/owner/* and delegates /token/investor/subscribe to an investor relations system, which further delegates /token/investor/subscribe (no further attenuation possible — the leaf capability) to a specific investor's DID.

On-Chain Verification

Two contracts handle UCAN lifecycle on-chain:

UCAN Verifier — stateless contract that validates a proof chain. Given a UCAN token and its parent chain, it: verifies each signature using the appropriate backend (EOA, ERC-1271, etc.), checks capability containment at each delegation step, and confirms no token has expired.

Revocation Registry — stores CIDs of revoked tokens. Any party in the delegation chain can revoke a token they issued. Checking revocation requires a single mapping(bytes32 => bool) lookup per token in the chain.

Token Distribution

UCAN tokens can be large (a deep delegation chain may contain several parent tokens). Rather than embedding full token payloads in every transaction, Cocoon stores tokens via torrent-ccip and references them by CID. The verifier resolves CIDs to content via the BitTorrent layer at verification time.

This means delegation chains are:

• Content-addressed (CID is a cryptographic commitment to the token content)

• Decentrally distributed (no single token registry)

• Accessible offline if the node has cached the torrent segments

Key APIs

Method	Description
auth_createDelegation	Issue a new UCAN token delegating a subset of the caller's capabilities to a target DID
auth_verify	Verify a UCAN proof chain for a given capability without executing any action
auth_inspect	Decode and display the full delegation chain for a given UCAN token CID
auth_revoke	Add a token CID to the on-chain revocation registry

// auth_createDelegation example
{
  "method": "auth_createDelegation",
  "params": {
    "audience": "did:pkh:eip155:1:0xAbC123...",
    "capabilities": ["/token/investor/subscribe", "/token/investor/view"],
    "expiry": 1780000000,
    "restrictions": {
      "maxAmount": "100000000000000000000"
    }
  }
}