iso-ucan 0.4.2 → 0.5.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "iso-ucan",
   "type": "module",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Isomorphic UCAN",
   "author": "Hugo Dias <hugomrdias@gmail.com> (hugodias.me)",
   "license": "MIT",
@@ -44,17 +44,13 @@
       "types": "./dist/src/varsig.d.ts",
       "default": "./src/varsig.js"
     },
-    "./server": {
-      "types": "./dist/src/server.d.ts",
-      "default": "./src/server.js"
-    },
     "./policy": {
       "types": "./dist/src/policy.d.ts",
       "default": "./src/policy.js"
     },
-    "./client": {
-      "types": "./dist/src/client.d.ts",
-      "default": "./src/client.js"
+    "./rpc": {
+      "types": "./dist/src/rpc/index.d.ts",
+      "default": "./src/rpc/index.js"
     },
     "./types": {
       "types": "./dist/src/types.d.ts"
@@ -82,14 +78,11 @@
       "store": [
         "dist/src/store"
       ],
-      "server": [
-        "dist/src/server"
-      ],
       "policy": [
         "dist/src/policy"
       ],
-      "client": [
-        "dist/src/client"
+      "rpc": [
+        "dist/src/rpc/index"
       ],
       "types": [
         "dist/src/types"
@@ -102,24 +95,24 @@
     "dist/src/**/*.d.ts.map"
   ],
   "dependencies": {
-    "@ipld/dag-cbor": "^9.2.5",
-    "@standard-schema/spec": "^1.0.0",
+    "@ipld/dag-cbor": "^10.0.2",
+    "@standard-schema/spec": "^1.1.0",
     "@standard-schema/utils": "^0.3.0",
     "iobuffer": "^6.0.1",
-    "iso-kv": "^3.1.0",
-    "iso-web": "^1.4.2",
-    "it-merge": "^3.0.12",
-    "multiformats": "^13.4.1",
-    "zod": "^4.1.12",
-    "iso-did": "^2.1.1",
-    "iso-base": "^4.2.1",
-    "iso-signatures": "^0.5.1"
+    "iso-base": "^4.4.0",
+    "iso-did": "^3.0.0",
+    "iso-kv": "^3.2.0",
+    "iso-signatures": "^0.5.2",
+    "iso-web": "^4.0.0",
+    "it-merge": "^3.0.15",
+    "multiformats": "^14.0.5",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^24.10.1",
+    "@types/node": "^26.6.2",
     "delay": "^7.0.0",
-    "playwright-test": "^14.1.12",
-    "typescript": "5.9.3"
+    "playwright-test": "^15.0.1",
+    "typescript": "^6.0.3"
   },
   "publishConfig": {
     "provenance": true

package/readme.md

@@ -1,6 +1,23 @@
 # iso-ucan [![NPM Version](https://img.shields.io/npm/v/iso-ucan.svg)](https://www.npmjs.com/package/iso-ucan) [![License](https://img.shields.io/npm/l/iso-ucan.svg)](https://github.com/hugomrdias/iso-repo/blob/main/license) [![iso-ucan](https://github.com/hugomrdias/iso-repo/actions/workflows/iso-ucan.yml/badge.svg)](https://github.com/hugomrdias/iso-repo/actions/workflows/iso-ucan.yml)
 
-> Isomorphic UCAN
+> Isomorphic UCAN primitives for delegations, invocations, proof storage, and
+> typed RPC.
+
+## Overview
+
+UCAN is a local-first authorization model where permissions are
+cryptographically signed, delegated, and verified without relying on a central
+authority. See [ucan.xyz](https://ucan.xyz/) for more background.
+
+`iso-ucan` provides:
+
+- Typed capabilities backed by schema validation.
+- Delegation and invocation builders for UCAN authorization flows.
+- Proof storage with pluggable `iso-kv` drivers.
+- Signer and verifier support through `iso-signatures`.
+- EIP-191 wallet signing support through `iso-signatures` `EIP191Signer`.
+- Filsnap-powered UCAN signature insights in MetaMask signature popups.
+- A typed RPC layer for request/response APIs built on UCAN invocations.
 
 ## Install
 
@@ -43,39 +60,189 @@ const invoker = await EdDSASigner.generate()
 const nowInSeconds = Math.floor(Date.now() / 1000)
 
 const ownerDelegation = await AccountCap.delegate({
-iss: owner,
-aud: bob,
-sub: owner,
-pol: [],
-exp: nowInSeconds + 1000,
+  iss: owner,
+  aud: bob,
+  sub: owner,
+  pol: [],
+  exp: nowInSeconds + 1000,
 })
 
 await store.set(ownerDelegation)
 
 const bobDelegation = await AccountCap.delegate({
-iss: bob,
-aud: invoker,
-sub: owner,
-pol: [],
-exp: nowInSeconds + 1000,
+  iss: bob,
+  aud: invoker,
+  sub: owner,
+  pol: [],
+  exp: nowInSeconds + 1000,
 })
 
 await store.set(bobDelegation)
 
 const invocation = await AccountCreateCap.invoke({
-iss: invoker,
-sub: owner,
-args: {
+  iss: invoker,
+  sub: owner,
+  args: {
     type: 'account',
     properties: {
-    name: 'John Doe',
+      name: 'John Doe',
     },
-},
-store,
-exp: nowInSeconds + 1000,
+  },
+  store,
+  exp: nowInSeconds + 1000,
 })
 ```
 
+## EIP-191 wallet signing
+
+`iso-ucan` can use EIP-191 wallet signatures through `EIP191Signer` from
+`iso-signatures`. That lets UCAN delegations and invocations be issued by an
+Ethereum account exposed through an EIP-1193 provider, such as an injected
+MetaMask wallet, while verification is handled by the matching EIP-191 verifier
+from `iso-signatures`.
+
+[`examples/eip191`](../../examples/eip191) shows this flow in a browser web
+app. It uses `wagmi` to connect the wallet, wraps the provider in
+`EIP191Signer`, then creates and verifies UCAN delegations and invocations
+directly in the browser.
+
+The example uses `filsnap-adapter` to install or enable
+[Filsnap](https://github.com/filecoin-project/filsnap), the Filecoin Wallet
+MetaMask Snap. Filsnap supports UCAN signature insights for EIP-191 signers, so
+when the app asks MetaMask to sign a UCAN delegation, the MetaMask signature
+popup can show a readable summary of the issuer, audience, subject, command,
+expiration, and raw payload.
+
+## RPC
+
+`iso-ucan/rpc` is a small request/response layer on top of UCAN
+invocations. You declare a protocol once as a record of commands
+(`defineCommand`), then build matching client and server pairs from it
+(`defineClient` / `defineServer`). Every command's success and error shapes
+are described by a single receipt schema (`receipt`, `receiptResult`,
+`receiptError`) which is shared by both ends, so the call sites are fully
+type-safe and discriminated unions just work on the client.
+
+Internal server failures (invalid invocation, unknown command, handler
+threw, …) are surfaced as a generic `SERVER_ERROR` variant that
+`receipt(...)` adds implicitly, so clients can always handle them with one
+narrow.
+
+### Define a shared protocol
+
+```ts
+import {
+  defineCommand,
+  receipt,
+  receiptError,
+  receiptResult,
+} from 'iso-ucan/rpc'
+import { z } from 'zod'
+
+const TodoSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  done: z.boolean(),
+})
+
+export const Protocol = {
+  TodoList: defineCommand({
+    cmd: '/todo/list',
+    args: z.object({}),
+    receipt: receipt(receiptResult(z.object({ todos: z.array(TodoSchema) }))),
+  }),
+  TodoAdd: defineCommand({
+    cmd: '/todo/add',
+    args: z.object({ text: z.string().min(1) }),
+    receipt: receipt(receiptResult(z.object({ todo: TodoSchema }))),
+  }),
+  TodoComplete: defineCommand({
+    cmd: '/todo/complete',
+    args: z.object({ id: z.string() }),
+    receipt: receipt(
+      receiptResult(z.object({ todo: TodoSchema })),
+      receiptError('NOT_FOUND', 'Todo not found.', z.object({ id: z.string() }))
+    ),
+  }),
+} as const
+```
+
+### Server (e.g. Hono + `@hono/node-server`)
+
+```ts
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+import { MemoryDriver } from 'iso-kv/drivers/memory.js'
+import { defineServer, type ServerHandlers } from 'iso-ucan/rpc'
+import { Store } from 'iso-ucan/store'
+import { Protocol } from './protocol.ts'
+
+const store = new Store(new MemoryDriver())
+// ...seed `store` with the delegations that authorise your clients...
+
+const handlers: ServerHandlers<typeof Protocol> = {
+  '/todo/list': ({ invocation }) => ({
+    cid: invocation.cid,
+    result: { todos: [/* ... */] },
+  }),
+  '/todo/add': ({ args, invocation }) => ({
+    cid: invocation.cid,
+    result: { todo: { id: '1', text: args.text, done: false } },
+  }),
+  '/todo/complete': ({ args, invocation }) => {
+    // return either { cid, result: ... } or { cid, error: { code, message, data } }
+    return {
+      cid: invocation.cid,
+      error: {
+        code: 'NOT_FOUND',
+        message: 'Todo not found.',
+        data: { id: args.id },
+      },
+    }
+  },
+}
+
+const rpc = defineServer(Protocol, {
+  signer: serverSigner,
+  store,
+  verifierResolver,
+  handlers,
+})
+
+const app = new Hono()
+app.post('/rpc', (c) => rpc(c.req.raw))
+serve({ fetch: app.fetch, port: 3000 })
+```
+
+### Client
+
+```ts
+import { defineClient } from 'iso-ucan/rpc'
+
+const client = defineClient(Protocol, {
+  url: 'http://localhost:3000/rpc',
+  issuer: cliSigner,
+  audience: serverSigner.didObject,
+  store,
+  verifierResolver,
+})
+
+// `args` and the returned receipt are typed from the protocol entry for `cmd`.
+const r = await client.request({ cmd: '/todo/complete', args: { id: '42' } })
+
+if ('result' in r) {
+  console.log(r.result.todo)
+} else if (r.error.code === 'NOT_FOUND') {
+  console.error(r.error.message, r.error.data) // data: { id: string }
+} else {
+  // r.error.code === 'SERVER_ERROR' — always present in every receipt union.
+  console.error('server error:', r.error.message)
+}
+```
+
+A complete runnable example (Hono server + a small CLI client) lives in
+[`examples/rpc-todo`](../../examples/rpc-todo).
+
 ## License
 
 MIT © [Hugo Dias](http://hugodias.me)

package/src/capability.js

@@ -19,9 +19,6 @@ export class Capability {
   constructor(options) {
     this.schema = options.schema
     this.cmd = options.cmd
-    this.isRevoked = options.isRevoked
-    this.didResolver = options.didResolver
-    this.verifierResolver = options.verifierResolver
   }
 
   /**
@@ -64,14 +61,12 @@ export class Capability {
         args: result.value,
       })
     }
+
     return await Invocation.create({
       ...options,
       args: result.value,
       cmd: this.cmd,
       prf: proofs,
-      verifierResolver: this.verifierResolver,
-      didResolver: this.didResolver,
-      isRevoked: this.isRevoked,
     })
   }
 

package/src/delegation.js

@@ -1,4 +1,4 @@
-import { base64pad } from 'iso-base/rfc4648'
+import { base64 } from 'iso-base/rfc4648'
 import { parse as didParse } from 'iso-did'
 import { randomBytes } from 'iso-web/crypto'
 import * as Envelope from './envelope.js'
@@ -84,7 +84,7 @@ export class Delegation {
       )
     }
 
-    assertStructure(envelope.payload)
+    assertStructure(envelope.payload, options.now)
 
     await verifySignature(envelope, verifierResolver, didResolveOptions)
 
@@ -98,9 +98,10 @@ export class Delegation {
    * Create a delegation from a base64 encoded string
    *
    * @param {string} token
+   * @param { {now?: number}} [options]
    */
-  static async fromString(token) {
-    const bytes = base64pad.decode(token)
+  static async fromString(token, options = {}) {
+    const bytes = base64.decode(token)
     const envelope = /** @type {typeof Envelope.decode<"dlg">} */ (
       Envelope.decode
     )({ envelope: bytes })
@@ -111,7 +112,7 @@ export class Delegation {
       )
     }
 
-    assertStructure(envelope.payload)
+    assertStructure(envelope.payload, options.now)
     const _cid = await cid(envelope)
     return new Delegation(envelope, bytes, _cid)
   }
@@ -143,7 +144,7 @@ export class Delegation {
       payload.meta = options.meta
     }
 
-    assertStructure(payload)
+    assertStructure(payload, options.now)
 
     const { signature, signaturePayload } = await Envelope.sign({
       spec: 'dlg',
@@ -174,8 +175,8 @@ export class Delegation {
    * @param {DelegationValidateOptions} options
    */
   async validate(options) {
-    assertStructure(this.envelope.payload)
-    assertNotBefore(this.envelope.payload.nbf)
+    assertStructure(this.envelope.payload, options.now)
+    assertNotBefore(this.envelope.payload.nbf, options.now)
     await verifySignature(
       this.envelope,
       options.verifierResolver,
@@ -187,7 +188,7 @@ export class Delegation {
   }
 
   toString() {
-    return base64pad.encode(this.bytes)
+    return base64.encode(this.bytes)
   }
 
   toJSON() {
@@ -203,10 +204,10 @@ export class Delegation {
           pol: this.pol,
           exp: this.exp,
           nbf: this.nbf,
-          nonce: base64pad.encode(this.nonce),
+          nonce: base64.encode(this.nonce),
           meta: this.meta,
         },
-        signature: base64pad.encode(this.envelope.signature),
+        signature: base64.encode(this.envelope.signature),
         alg: this.envelope.alg,
         enc: this.envelope.enc,
         spec: this.envelope.spec,
@@ -219,8 +220,9 @@ export class Delegation {
 /**
  *
  * @param {import('./types.js').DelegationPayload} payload
+ * @param {number} [now]
  */
-function assertStructure(payload) {
+function assertStructure(payload, now) {
   didParse(payload.iss)
   didParse(payload.aud)
 
@@ -229,7 +231,7 @@ function assertStructure(payload) {
   }
 
   assertIsValidCommand(payload.cmd)
-  assertExpiration(payload.exp)
+  assertExpiration(payload.exp, now)
   assertNonce(payload.nonce)
 
   // assertPolicy(payload.pol)

package/src/invocation.js

@@ -9,6 +9,7 @@ import {
   assertMeta,
   assertNonce,
   cid,
+  commandCovers,
   expOrTtl,
   verifySignature,
 } from './utils.js'
@@ -65,6 +66,7 @@ export class Invocation {
     }
     // Audience or subject must match receiver
     if (
+      audience &&
       envelope.payload.aud !== audience.did &&
       envelope.payload.sub !== audience.did
     ) {
@@ -192,14 +194,15 @@ export function assertProofs(payload, proofs) {
     throw new Error("UCAN Invocation couldn't resolve all proofs CIDs")
   }
 
-  const lastProof = proofs[proofs.length - 1]
-  const issuerDid = didParse(lastProof.envelope.payload.iss).did
-  if (issuerDid !== lastProof.envelope.payload.sub) {
+  const rootProof = proofs[0]
+  const issuerDid = didParse(rootProof.iss).did
+  if (issuerDid !== rootProof.sub) {
     throw new Error('UCAN Invocation root proof is not self-signed')
   }
 
   for (let index = 0; index < proofs.length; index++) {
     const current = proofs[index].envelope.payload
+
     const currentAudience = didParse(current.aud)
     const currentSubject = didParse(current.sub ?? payload.sub)
 
@@ -210,12 +213,13 @@ export function assertProofs(payload, proofs) {
     }
 
     const nextProof = proofs[index + 1]
+
     /** @type {import("./types.js").Payload} */
     let next
     if (nextProof) {
       next = nextProof.envelope.payload
     } else {
-      next = payload
+      next = payload // checks against the invocation payload
     }
 
     const nextIssuer = didParse(next.iss)
@@ -232,9 +236,9 @@ export function assertProofs(payload, proofs) {
       )
     }
 
-    if (!next.cmd.startsWith(current.cmd)) {
+    if (!commandCovers(current.cmd, next.cmd)) {
       throw new Error(
-        `UCAN Invocation command mismatch, expected ${current.cmd} to be a broader than ${next.cmd}`
+        `UCAN Invocation command mismatch, expected ${current.cmd} to cover ${next.cmd}`
       )
     }
   }

package/src/rpc/client.js

@@ -0,0 +1,85 @@
+import { SchemaError } from '@standard-schema/utils'
+
+/**
+ * @import {
+ *   CommandsRecord,
+ *   DefineClientOptions,
+ *   CommandClient,
+ * } from './types.js'
+ */
+
+/**
+ * Define a type-safe client from a record of commands.
+ *
+ * The returned client exposes a `request(cmd, args)` method whose `cmd`
+ * parameter is constrained to the union of `cmd` values declared by
+ * `commands`, and whose `args` parameter is typed accordingly.
+ *
+ * @template {CommandsRecord} Commands
+ * @param {Commands} commands
+ * @param {DefineClientOptions} options
+ * @returns {CommandClient<Commands>}
+ */
+export function defineClient(commands, options) {
+  /** @type {Record<string, CommandsRecord[string]>} */
+  const commandMap = {}
+  for (const command of Object.values(commands)) {
+    commandMap[command.capability.cmd] = command
+  }
+
+  return {
+    request: async ({ cmd, args }) => {
+      const command = commandMap[cmd]
+      if (!command) {
+        throw new Error(`Command not found: ${cmd}`)
+      }
+
+      const inv = await command.capability.invoke({
+        args,
+        iss: options.issuer,
+        sub: options.audience.did,
+        store: options.store,
+        exp: null,
+        verifierResolver: options.verifierResolver,
+      })
+
+      const response = await fetch(options.url, {
+        method: 'POST',
+        body: /** @type {BufferSource} */ (inv.bytes),
+      })
+
+      const data = await response.json()
+      if (
+        typeof data !== 'object' ||
+        data === null ||
+        (!('result' in data) && !('error' in data))
+      ) {
+        throw new Error(
+          'Invalid receipt: response must include a `result` or `error` field'
+        )
+      }
+
+      const validated = await command.receipt['~standard'].validate(data)
+      if (validated.issues) {
+        throw new SchemaError(validated.issues)
+      }
+      return validated.value
+    },
+
+    invoke: async ({ cmd, args }) => {
+      const command = commandMap[cmd]
+      if (!command) {
+        throw new Error(`Command not found: ${cmd}`)
+      }
+
+      return await command.capability.invoke({
+        args,
+        iss: options.issuer,
+        sub: options.audience.did,
+        store: options.store,
+        exp: null,
+        verifierResolver: options.verifierResolver,
+      })
+    },
+  }
+}

package/src/rpc/command.js

@@ -0,0 +1,28 @@
+import { Capability } from '../capability.js'
+
+/**
+ * @import {
+ *   CommandOptions,
+ *   CommandOutput,
+ * } from './types.js'
+ * @import {StandardSchemaV1} from '@standard-schema/spec'
+ */
+
+/**
+ * @template {StandardSchemaV1} Args
+ * @template {string} Cmd
+ * @template {StandardSchemaV1} ReceiptSchema
+ * @param {CommandOptions<Args, Cmd, ReceiptSchema>} options
+ * @returns {CommandOutput<Args, Cmd, ReceiptSchema>}
+ */
+export function defineCommand(options) {
+  return {
+    capability: /** @type {Capability<Args, Cmd>} */ (
+      Capability.from({
+        schema: options.args,
+        cmd: options.cmd,
+      })
+    ),
+    receipt: options.receipt,
+  }
+}

package/src/rpc/index.js

@@ -0,0 +1,10 @@
+export { defineClient } from './client.js'
+export { defineCommand } from './command.js'
+export {
+  cidSchema,
+  receipt,
+  receiptError,
+  receiptResult,
+  receiptServerError,
+} from './receipt.js'
+export { defineServer } from './server.js'