iso-ucan 0.4.2 → 0.5.0

package/readme.md

@@ -76,6 +76,136 @@ exp: nowInSeconds + 1000,
 })
 ```
 
+## 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

@@ -65,6 +65,7 @@ export class Invocation {
     }
     // Audience or subject must match receiver
     if (
+      audience &&
       envelope.payload.aud !== audience.did &&
       envelope.payload.sub !== audience.did
     ) {
@@ -192,14 +193,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 +212,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)

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'

package/src/rpc/receipt.js

@@ -0,0 +1,136 @@
+import { CID } from 'multiformats/cid'
+import { z } from 'zod/v4'
+
+/**
+ * @import {z as zType} from 'zod/v4'
+ */
+
+/**
+ * Schema for an Invocation CID.
+ *
+ * Accepts a {@link CID} instance (server-side construction), a CID string,
+ * or the dag-json `{ "/": "<cid>" }` form (which is what `CID.toJSON()`
+ * produces when serialized through `JSON.stringify`) and normalizes to a
+ * {@link CID}.
+ */
+export const cidSchema = z.union([
+  z.instanceof(CID),
+  z
+    .union([z.string(), z.object({ '/': z.string() }).transform((v) => v['/'])])
+    .transform((value, ctx) => {
+      try {
+        return CID.parse(value)
+      } catch (error) {
+        ctx.addIssue({
+          code: 'custom',
+          message: `Invalid CID: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        })
+        return z.NEVER
+      }
+    }),
+])
+
+/**
+ * Schema for a successful receipt: `{ cid, result }`.
+ *
+ * @template {zType.ZodType} ResultSchema
+ * @param {ResultSchema} result Schema for the `result` payload.
+ * @returns {zType.ZodObject<{ cid: typeof cidSchema, result: ResultSchema }>}
+ */
+export function receiptResult(result) {
+  return z.object({
+    cid: cidSchema,
+    result,
+  })
+}
+
+/**
+ * Schema for an error receipt: `{ cid, error: { code, message, data } }`.
+ *
+ * `code` and `message` are encoded as Zod literals so each error variant is
+ * distinguishable in the resulting union.
+ *
+ * @template {string} Code
+ * @template {string} Message
+ * @template {zType.ZodType} DataSchema
+ * @param {Code} code
+ * @param {Message} message
+ * @param {DataSchema} data Schema for the structured error `data` payload.
+ * @returns {zType.ZodObject<{
+ *   cid: typeof cidSchema,
+ *   error: zType.ZodObject<{
+ *     code: zType.ZodLiteral<Code>,
+ *     message: zType.ZodLiteral<Message>,
+ *     data: DataSchema,
+ *   }>,
+ * }>}
+ */
+export function receiptError(code, message, data) {
+  return z.object({
+    cid: cidSchema,
+    error: z.object({
+      code: z.literal(code),
+      message: z.literal(message),
+      data,
+    }),
+  })
+}
+
+/**
+ * Generic schema for server-emitted internal errors.
+ *
+ * Unlike {@link receiptError} (which is part of the per-command receipt
+ * schema with literal `code`/`message`), this schema is emitted by the
+ * server for any error that happens outside of normal handler execution
+ * (invalid invocation, command not found, args validation failure, handler
+ * threw, etc.).
+ *
+ * `cid` is optional because some errors happen before the invocation can
+ * be decoded.
+ *
+ * Automatically included as a variant in every command receipt produced by
+ * {@link receipt}, so the client always knows how to validate and discriminate
+ * a server error from a normal receipt.
+ */
+export const receiptServerError = z.object({
+  error: z.object({
+    code: z.literal('SERVER_ERROR'),
+    message: z.string(),
+    cid: cidSchema.optional(),
+    data: z.unknown().optional(),
+  }),
+})
+
+/**
+ * @typedef {zType.infer<typeof receiptServerError>} ReceiptServerError
+ */
+
+/**
+ * Combine one {@link receiptResult} schema and zero or more
+ * {@link receiptError} schemas into a single discriminated receipt schema.
+ *
+ * The {@link receiptServerError} schema is always appended as the last
+ * variant of the union so every command receipt accepts a server-emitted
+ * internal error in addition to its declared result/error variants.
+ *
+ * The resulting schema validates one of:
+ *   - `{ cid, result }`
+ *   - `{ cid, error: { code, message, data } }` (one of the declared command errors)
+ *   - `{ error: { code, message, cid?, data? } }` (a generic server error)
+ *
+ * Consumers discriminate via `'result' in receipt` / `'error' in receipt`,
+ * and within the error branch via the `code` field.
+ *
+ * @template {zType.ZodType} Result
+ * @template {zType.ZodType} Error
+ * @param {Result} result
+ * @param {...Error} errors
+ * @returns {zType.ZodUnion<readonly [Result, ...Error[], typeof receiptServerError]>}
+ */
+export function receipt(result, ...errors) {
+  return /** @type {any} */ (
+    z.union(/** @type {any} */ ([result, ...errors, receiptServerError]))
+  )
+}