UCANs are simply JWTs that contain special keys. At a high level, UCANs (“User Controlled Authorization Network”) are a way of doing authorization ("what you can do") where users are fully in control. There's no all-powerful authorization server, or server of any kind required. Everything that a users is allowed to do is captured directly in a key or token, and can be sent to anyone that knows how to interpret this format. This works server -> server, client -> server, or p2p.

OAuth is designed for a centralized world, UCAN is the distributed user controlled version.

Read more in the whitepaper: https://whitepaper.fission.codes/access-control/ucan

alg, Algorithm, the type of signature.

typ, Type, the type of this data structure, JWT.

uav, UCAN version.

att, Attenuation, a list of resources and capabilities that the ucan grants.

aud, Audience, the ID of who it's intended for.

exp, Expiry, unix timestamp of when the jwt is no longer valid.

fct, Facts, an array of extra facts or information to attach to the jwt.

iss, Issuer, the ID of who sent this.

nbf, Not Before, unix timestamp of when the jwt becomes valid.

prf, Proof, an optional nested token with equal or greater privileges.

A signature (using alg) of the base64 encoded header and payloaded concatenated together and delimited by .

Use ucan.build to help in formatting and signing a ucan. It takes the following parameters

export type BuildParams = {
  // to/from
  audience: string
  issuer: Keypair

  // capabilities
  capabilities: Array<Capability>

  // time bounds
  lifetimeInSeconds?: number // expiration overrides lifetimeInSeconds
  expiration?: number
  notBefore?: number

  // proof / other info
  facts?: Array<Fact>
  proof?: string

  // in the weeds
  ucanVersion?: string
}

capabilities is an array of resources and permission level formatted as:

{
  $TYPE: $IDENTIFIER,
  "cap": $CAPABILITY
}

import * as ucan from 'ucans'

// in-memory keypair
const keypair = await ucan.EdKeypair.create()
const u = await ucan.build({
  audience: "did:key:zabcde...", //recipient DID
  issuer: keypair, //signing key
  capabilities: [ // permissions for ucan
    {
      "wnfs": "boris.fission.name/public/photos/",
      "cap": "OVERWRITE"
    },
    {
      "wnfs": "boris.fission.name/private/4tZA6S61BSXygmJGGW885odfQwpnR2UgmCaS5CfCuWtEKQdtkRnvKVdZ4q6wBXYTjhewomJWPL2ui3hJqaSodFnKyWiPZWLwzp1h7wLtaVBQqSW4ZFgyYaJScVkBs32BThn6BZBJTmayeoA9hm8XrhTX4CGX5CVCwqvEUvHTSzAwdaR",
      "cap": "APPEND"
    },
    {
      "email": "[email protected]",
      "cap": "SEND"
    }
  ]
})
const token = ucan.encode(u) // base64 jwt-formatted auth token

// You can also use your own signing function if you're bringing your own key management solution
const { header, payload } = await ucan.buildParts(...)
const u = await ucan.addSignature(header, payload, signingFn)