# 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
```
{"metaMigratedAt":"2023-06-16T22:52:26.658Z","metaMigratedFrom":"YAML","title":"DAG-UCAN","breaks":true,"description":"View the slide with \"Slide Mode\".","contributors":"[{\"id\":\"fff58d5d-df29-4dd3-93ef-42fd0194a26f\",\"add\":3285,\"del\":977}]"}