# @didtools/cacao

> Typescript library for Ceramic OCAP

Latest version **3.0.1** (published 2024-01-04) · (Apache-2.0 OR MIT) license · 0 weekly downloads

## Install

```sh
npm install @didtools/cacao
pnpm add @didtools/cacao
yarn add @didtools/cacao
bun add @didtools/cacao
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.1 |
| Published | 2024-01-04 |
| First published | 2022-09-22 |
| Weekly downloads | 0 |
| License | (Apache-2.0 OR MIT) |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14.14 |
| Dependencies | 7 |
| Unpacked size | 32.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 103 |
| Author | Haardik |
| Maintainers | dav1do, dbcfd, cb3box, ukstv, jpham2023, oed, paul_lecam |
| Keywords | DID, identity, OCAP, capabilities |

## Links

- npm: https://www.npmjs.com/package/@didtools/cacao
- Repository: https://github.com/ceramicnetwork/js-did
- Homepage: https://github.com/ceramicnetwork/js-did#readme
- Issues: https://github.com/ceramicnetwork/js-did/issues
- npm.io page: https://npm.io/package/@didtools/cacao

## Dependencies (7)

- [caip](https://npm.io/package/caip.md) ^1.1.0
- [viem](https://npm.io/package/viem.md) ^1.21.4
- [uint8arrays](https://npm.io/package/uint8arrays.md) ^5.0.1
- [multiformats](https://npm.io/package/multiformats.md) ^13.0.0
- [@didtools/siwx](https://npm.io/package/@didtools/siwx.md) 2.0.0
- [@ipld/dag-cbor](https://npm.io/package/@ipld/dag-cbor.md) ^9.0.7
- [@didtools/codecs](https://npm.io/package/@didtools/codecs.md) ^3.0.0

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 3.0.1 (latest) — 2024-01-04
- 3.0.1-a.0 (experimental) — 2024-07-06
- 2.1.1-next.0 (next) — 2023-10-27
- 3.0.0 — 2024-01-04
- 2.1.0 — 2023-06-20
- 2.0.0 — 2023-02-24
- 1.2.0 — 2023-02-07
- 1.1.0 — 2022-12-27
- 1.0.0 — 2022-09-22

## README

# CACAO

A library to represent chain-agnostic Object Capabilities (OCAP), created using [EIP-4361](https://github.com/ethereum/EIPs/blob/5e9b0fe0728e160f56dd1e4cbf7dc0a0b1772f82/EIPS/eip-4361.md) (or similar for other blockchains), as an [IPLD](https://ipld.io/) object.

## Examples

### Convert between CACAO and SIWE (EIP-4361)

```typescript
const siweMessage = new SiweMessage({
  domain: 'service.org',
  address: address,
  statement: 'I accept the ServiceOrg Terms of Service: https://service.org/tos',
  uri: 'did:key:z6MkrBdNdwUPnXDVD1DCxedzVVBpaGi8aSmoXFAeKNgtAer8',
  version: '1',
  nonce: '32891757',
  issuedAt: '2021-09-30T16:25:24.000Z',
  chainId: '1',
  resources: [
    'ipfs://Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu',
    'https://example.com/my-web2-claim.json',
    'ceramic://k2t6wyfsu4pg040dpjpbla1ybxof65baldb7fvmeam4m3n71q0w1nslz609u2d',
  ],
})

const cacao = Cacao.fromSiweMessage(siweMessage)
const siweMessage2 = SiweMessage.fromCacao(cacao)
```

### Creating and signing a CACAO with private-key Wallet

```typescript
import { Wallet } from '@ethersproject/wallet'
import { Cacao, CacaoBlock, SiweMessage } from '@didtools/cacao'

const wallet = Wallet.createRandom()
const address = wallet.address

const siweMessage = new SiweMessage({
  domain: 'service.org',
  address: address,
  statement: 'I accept the ServiceOrg Terms of Service: https://service.org/tos',
  uri: 'did:key:z6MkrBdNdwUPnXDVD1DCxedzVVBpaGi8aSmoXFAeKNgtAer8',
  version: '1',
  nonce: '32891757',
  issuedAt: '2021-09-30T16:25:24.000Z',
  chainId: '1',
  resources: [
    'ipfs://Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu',
    'https://example.com/my-web2-claim.json',
    'ceramic://k2t6wyfsu4pg040dpjpbla1ybxof65baldb7fvmeam4m3n71q0w1nslz609u2d',
  ],
})
const signature = await wallet.signMessage(siweMessage.toMessage())
siweMessage.signature = signature

const cacao = Cacao.fromSiweMessage(siweMessage)
```

### Usage with `EthereumAuthProvider` `requestCapability` to update a `TileDocument`

```typescript
import { Web3Provider } from "@ethersproject/providers"
import { EthereumAuthProvider } from "@ceramicnetwork/blockchain-utils-linking";
import { Ed25519Provider } from "key-did-provider-ed25519"
import { DID } from "dids"
import * as KeyDidResolver from "key-did-resolver";
import { TileDocument } from "@ceramicnetwork/stream-tile";
import { CeramicClient } from "@ceramicnetwork/http-client";
import type { Cacao } from "@didtools/cacao"

// Create the EthereumAuthProvider
const web3Provider = new Web3Provider(...) // connect to a provider
const address = "0xAB..." // get the signer address
const ethereumAuthProvider = new EthereumAuthProvider(web3Provider.provider, address) // Note: we pass the underlying RPC provider, not the ethers.js wrapped version

// Create a determinstic document for the user
const ceramic = new CeramicClient(CERAMIC_API_URL) // Ceramic HTTP Client
const deterministicDocument = await TileDocument.deterministic(ceramic, {
    deterministic: true,
    family: 'randomFamily',
    controllers: [`did:pkh:eip155:1:${address}`]
})

// Create a session key for the dApp
const seed = ... // 32 bytes of entropy
const didProvider = new Ed25519Provider(seed)
const didKey = new DID({
    provider: didProvider,
    resolver: KeyDidResolver.getResolver()
})
await didKey.authenticate()

// Request capability from user
const cacao = await ethereumAuthProvider.requestCapability(didKey.id, [deterministicDocument.id.toUrl()])

// Attach capability to session key
const didKeyWithCap = didKey.withCapability(cacao);
await didKeyWithCap.authenticate()

// Update user's TileDocument using session key that has the capability
await deterministicDocument.update({ foo: 'bar' }, {}, {
    asDid: didKeyWithCap
})
```

## License

Dual licensed with APACHE and MIT

---
_Source: https://npm.io/package/@didtools/cacao · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._