UCAN Authorization

Most authorization systems decide whether a user may do something by consulting a database of permissions. That database is a central point of trust, a central point of failure, and the reason sharing anything needs an administrator. UCAN, User Controlled Authorization Network, turns the model around. The permission is the token. A signed delegation says who granted what to whom, on which subject, for how long. Anyone holding the issuer's public key can verify it offline.

Ekayana implements UCAN 1.0 through two crates it publishes. pq-ucan is the token format, policy language and chain validator. pq-space lets a did:bio identity sign and verify those tokens and can carry a content key inside a grant. Tokens are signed by the researcher's wallet. The service prepares the bytes and validates the result. It never signs in anyone's name.

The token on the wire

A UCAN 1.0 token is a DAG-CBOR array of two elements, a signature and the map it signs.

The encoder produces strict canonical DAG-CBOR and the decoder refuses anything else, including indefinite lengths, nonminimal integers, unsorted or duplicate keys and trailing bytes. Canonicalization attacks are the reason varsig exists, and refusing a second encoding is cheaper than reasoning about it. A decoded token also keeps the bytes it came from. The CID is checked over the received envelope and the signature over the received payload bytes. The one exception is a token whose header says it was signed as DAG-JSON, which is how wallets sign, and its signature is checked over the canonical DAG-JSON text of the payload. Both encodings are canonical, so what a signer held is still exactly what a verifier sees.

The varsig header names the algorithm. The three the specification requires are there, and ML-DSA is added at the same table as an ordinary entry.

A delegation's payload carries iss, aud, sub, cmd, pol, nonce, exp, and optionally meta and nbf. An invocation carries iss, sub, cmd, args, prf, which is the list of proof CIDs with the root first, nonce, exp, and optionally aud, the executor. A token's identifier is the CID of its bytes, which is what the platform calls a token_hash.

Delegation and invocation

A delegation is a grant. Its sub is the principal whose authority is being passed on, its aud the principal receiving it, and its cmd a /-separated path that names what may be done. sub: null is a powerline delegation. Whatever authority the audience later proves it has, this token passes along. The platform uses one for the browser session key.

An invocation is the act. It names the subject, the command, the arguments, and the chain of delegations in prf that connect the invoker back to the subject. The executor, aud, is who is being asked to act. In Ekayana that is always the service's own did:bio.

Commands only narrow

A command covers another when it is /, equals it, or is a prefix of it on a segment boundary. /file covers /file/read and does not cover /filesystem. Every hop in a chain must be covered by the hop above it, and the invocation by the last hop. There is no way to hold /file/read and mint /file.

Policy

A delegation can further constrain the invocation's arguments with a policy, a list of statements that all have to hold.

Selectors are jq style paths into args, such as .cid, .tags[0] or .meta?. A selector that fails to resolve makes its statement false rather than raising. A share of one file with two actions is, in the platform, the command /file with the policy [["==", ".cid", "bafy..."], ["or", [["==", ".action", "read"], ["==", ".action", "write"]]]].

Validation

Validator::validate runs a fixed sequence of checks over an invocation and its proof chain and stops at the first failure, naming the hop and the rule. The error reads like "proof 2: audience did:key:z6Mk... is not the next issuer did:key:z6Mk..." rather than "invalid token".

The order matters. Structural checks are cheap and give the best diagnostics, so they go first. Signatures are the expensive step and run before policy, so no policy is ever evaluated for a token nobody signed. The replay guard is last, so a rejected invocation never spends a nonce.

The validator leaves three things unchecked on purpose. It does not check whether the subject controls the resource, because the executor is the resource, or asks it. It does not check semantic conditions like quotas, which belong in execution. It does not check revocation, because the crate has no store for it yet, so the service keeps a revoked_at column and consults it before the validator runs.

Detached signing

A wallet will sign bytes you hand it, and it will not hand you its key. The builders therefore have two endings. sign(&signer) produces the token in one step. prepare(issuer, algorithm) returns the exact bytes to sign, and assemble(bytes, signature) builds the token from them. The result is byte for byte what sign would have produced, and the service verifies it under the issuer's key once assembled, so a wallet cannot be talked into signing one thing and the service recording another. The platform itself calls prepare_with with a header that says the wallet signs DAG-JSON, because Solana wallets sign only text.

let unsigned = Delegation::builder(recipient, Subject::Did(owner.clone()), Command::parse("/file/read")?)
    .policy(policy)
    .nonce(Nonce::random(&mut rng))
    .expires_at(now.plus_seconds(7 * 24 * 3600))
    .prepare(owner, Algorithm::Ed25519)?;
// ... the wallet signs unsigned.signing_bytes() ...
let grant = Delegation::assemble(unsigned.signing_bytes(), signature.as_bytes())?;

A builder takes no issuer. The signer's DID is the issuer, so a token whose iss does not match its key cannot exist. It also will not sign until an expiry and a nonce have been chosen. Both are decisions rather than defaults.

How the platform uses it

Every share is one delegation the owner's wallet signs. Every read is one invocation a browser key signs. The service is the executor in the middle.

Issuing

POST /api/ucan/issue/prepare takes an audience, capabilities and an expiration in seconds, 24 hours by default and at most ten years, and returns the bytes to sign and when the token will expire. POST /api/ucan/issue takes the same request plus signing_bytes and signature, assembles the token, checks that it says what was asked and verifies under the issuer's key, and records it.

curl -X POST https://api.ekayana.io/api/ucan/issue/prepare \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "audience": "did:bio:devnet:HP3Hj9en...",
    "capabilities": [{ "with": "ipfs://bafybeigdyrexample", "can": "read" }],
    "expiration": 604800
  }'
# -> { "signing_bytes": "<base64url>", "expires_at": 1753833600 }

curl -X POST https://api.ekayana.io/api/ucan/issue \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "audience": "did:bio:devnet:HP3Hj9en...",
    "capabilities": [{ "with": "ipfs://bafybeigdyrexample", "can": "read" }],
    "expiration": 604800,
    "signing_bytes": "<base64url>",
    "signature": "<base64url, from the wallet>"
  }'
# -> { "token": "<base64url of the DAG-CBOR bytes>", "token_hash": "<CID>", "expires_at": 1753833600 }

Capabilities map onto commands and policy. One action is the command /file/<action>. Several actions are /file with a policy on .action. A specific CID adds a policy on .cid. * as the resource means every file the issuer owns. A token covers one resource. The sharing tutorial wraps these two calls in /api/share/file/prepare and /api/share/file.

Presenting

A recipient never presents a bare delegation. They present it together with an invocation their own key signed, in two headers.

curl https://api.ekayana.io/api/download/bafybeigdyrexample \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-ucan-token: <delegation>" \
  -H "x-ucan-invocation: <invocation>"

POST /api/ucan/invoke/prepare builds the invocation bytes for a token, a CID and an action. The invocation lives 60 seconds. For read, the issuer is the session's browser key and the proof chain is two hops, the wallet's 24 hour powerline grant of /file/read to that key and then the share. For write and delete the wallet itself signs. The service checks the delegation's signature, time window and revocation, decodes the invocation, confirms its cid and action match the request, and runs the validator with itself as executor.

Endpoints

Only the issuer may revoke, and revocation is immediate. The next presentation fails before the validator runs. Anything delegated beneath a revoked token fails with it, because the chain no longer resolves.

Private spaces

For a sealed blob, a capability alone is not enough, because the recipient also needs the content key. pq-space wraps that key to the recipient's ML-KEM-1024 encapsulation key and carries it inside the delegation, in the meta map under space/key.

The wrap is ML-KEM-1024 -> HKDF-SHA256 -> AES-256-GCM, with associated data subject|command, so a wrapped key lifted into another grant will not open. The recipient publishes its encapsulation key as a DID service entry of type SpaceEncapsulationKey, and both did:bio and did:key resolve from the identifier itself, so checking a chain costs no round trip. There is no custody service and no KMS in the path. Whoever holds the delegation and the decapsulation key can read, and nobody else.

See Privacy Controls for the storage side view of the same envelope.

Post quantum principals

pq-ucan treats ML-DSA, FIPS 204, as an ordinary algorithm rather than a fork. It has a did:key prefix, the registered multicodec mldsa-87-pub with code 0x1212, a varsig header, a signer and a verifier, and nothing else in the crate knows it is post quantum. A chain may mix principals freely. A did:bio researcher can delegate to an ML-DSA-87 device key that redelegates to an Ed25519 colleague.

Two caveats apply. The ML-DSA varsig headers are provisional until the varsig registry assigns tags. They are self describing and intended for deployments that control both ends, which this one does. What the platform signs with today is Ed25519, because that is what wallets sign with. The post quantum path is there for the keys that need it.

Best practices

• Issue one narrow token per share. Revoking it affects exactly one recipient. A * resource with * actions grants everything the issuer owns until it expires.
• Keep invocations short and delegations longer. An invocation is a single act and lives a minute. A delegation is a standing grant. A week is plenty for a collaborator, and it can always be reissued.
• Keep tokens out of URLs. A delegation is a few hundred bytes with an Ed25519 issuer and several kilobytes with an ML-DSA one. Put it in headers or a request body, never in a query string.

Resources

• UCAN specification, with the delegation and invocation documents
• pq-ucan, with design notes, the wire format and the validation rules
• pq-space
• Varsig
• FIPS 204, ML-DSA and FIPS 203, ML-KEM