# DAG UCAN Library ```ts import * as UCAN from '@ipld/dag-ucan' ``` - issue / derive UCANs - encode / decode UCANs in IPLD - parse / format UCANs in JWT --- ### Issue token Alice grants Bob `store/add` capability allowing him to add CARs to her account linked with her did ```ts const root = await UCAN.issue({ issuer: alice, // keypair thingy audience: bob.did(), capabilities: [{ can: "store/add", with: alice.did() }] }) ``` --- ### Derive token Bob invokes capability by deriving UCAN for service from UCAN he got from Alice ```ts const ucan = await UCAN.issue({ issuer: bob, // keypair audience: service.did(), capabilities: [{ can: "store/add", with: alice.did() link: cid // CAR cid bob wishes to upload }] proof: [await UCAN.link(root)] }) ``` --- ### encode UCAN can be encoded into an IPLD block, that is DAG-CBOR with some schema constraints ```ts const bytes = UCAN.encode(ucan) ``` --- ### decode UCAN can be decoded on the the other end of the piepe ```ts const request = UCAN.decode(bytes) ``` --- ### format Every UCAN issued by DAG-UCAN can be formatted into a valid UCAN JWT string that spec compliant implementations can consume ```ts const jwt = UCAN.format(request) ``` --- ### Secondary RAW encoding Not all UCANs can be encoded encoded in CBOR as loss of key order and whitespaces would lead to mismatched signatures. ```ts UCAN.format(UCAN.parse(jwt)) === jwt // true ``` ## How do we ensure above ? --- ### Secondary RAW encoding When parsing UCANs that can not have valid CBOR representation, secondary RAW representation is used ```ts const ucan = UCAN.parse(jwt) ucan.code // => 0x78c0 UCAN multicodec const raw = UCAN.parse(fissionJWT) raw.code // => 0x55 RAW multicodec const ucanLink = await UCAN.link(UCAN.encode(ucan)) ucanLink.code // => 0x78c0 UCAN multicodec const rawLink = await UCAN.link(UCAN.encode(raw)) rawLink.code // => 0x55 Raw multicodec ``` --- ### Secondary RAW encoding UCANs in both CBOR and RAW implementation can be encoded and decoded just the same. ```ts UCAN.decode(UCAN.encode(ucan)).code // 0x78c0 UCAN multicodec UCAN.decode(UCAN.encode(raw)).code // 0x55 Raw multicodec ```