iso-ucan 0.4.2 → 0.5.1

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]))
+  )
+}

package/src/rpc/server.js

@@ -0,0 +1,155 @@
+import { u8 } from 'iso-base/utils'
+import { Invocation } from '../invocation.js'
+
+/**
+ * @import {
+ *   CommandsRecord,
+ *   DefineServerOptions,
+ *   ServerRequestHandler,
+ * } from './types.js'
+ * @import {ReceiptServerError} from './receipt.js'
+ */
+
+/**
+ * Build a {@link ReceiptServerError} payload.
+ *
+ * @param {string} message
+ * @param {{
+ *   cid?: import('multiformats').CID,
+ *   cmd?: string,
+ *   issues?: readonly import('@standard-schema/spec').StandardSchemaV1.Issue[],
+ * }} [extra]
+ * @returns {ReceiptServerError}
+ */
+function buildServerError(message, extra) {
+  /** @type {Record<string, unknown> | undefined} */
+  let data
+  if (extra?.cmd !== undefined || extra?.issues !== undefined) {
+    data = {}
+    if (extra.cmd !== undefined) data.cmd = extra.cmd
+    if (extra.issues !== undefined) data.issues = extra.issues
+  }
+
+  /** @type {ReceiptServerError['error']} */
+  const error = { code: 'SERVER_ERROR', message }
+  if (data !== undefined) error.data = data
+  if (extra?.cid !== undefined) error.cid = extra.cid
+  return { error }
+}
+
+/**
+ * Build a JSON {@link Response} for a server error.
+ *
+ * @param {number} status
+ * @param {string} message
+ * @param {Parameters<typeof buildServerError>[1]} [extra]
+ */
+function serverErrorResponse(status, message, extra) {
+  return Response.json(buildServerError(message, extra), { status })
+}
+
+/**
+ * Define a type-safe server from a record of commands.
+ *
+ * The returned function accepts a standard `Request`, decodes its body as a
+ * UCAN {@link Invocation}, validates the args against the matching command's
+ * schema, and dispatches to the corresponding handler in `options.handlers`.
+ * The handler's return value is serialized to JSON.
+ *
+ * @template {CommandsRecord} Commands
+ * @param {Commands} commands
+ * @param {DefineServerOptions<Commands>} options
+ * @returns {ServerRequestHandler}
+ */
+export function defineServer(commands, options) {
+  /** @type {Record<string, CommandsRecord[string]>} */
+  const commandMap = {}
+  for (const command of Object.values(commands)) {
+    commandMap[command.capability.cmd] = command
+  }
+
+  /** @type {Record<string, (opts: any) => unknown>} */
+  const handlers = options.handlers
+
+  return async (request) => {
+    /** @type {Invocation | undefined} */
+    let invocation
+
+    try {
+      const bytes = u8(await request.arrayBuffer())
+
+      invocation = await Invocation.from({
+        bytes,
+        audience: options.signer,
+        verifierResolver: options.verifierResolver,
+        resolveProof: options.store.resolveProof.bind(options.store),
+      })
+    } catch (error) {
+      return serverErrorResponse(
+        400,
+        `Invalid invocation: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      )
+    }
+
+    const cid = invocation.cid
+    const cmd = invocation.payload.cmd
+    const command = commandMap[cmd]
+    if (!command) {
+      return serverErrorResponse(404, `Command not found: ${cmd}`, {
+        cid,
+        cmd,
+      })
+    }
+
+    const handler = handlers[cmd]
+    if (!handler) {
+      return serverErrorResponse(404, `Handler not found: ${cmd}`, {
+        cid,
+        cmd,
+      })
+    }
+
+    const validated = await command.capability.validate(
+      /** @type {any} */ (invocation.payload.args)
+    )
+    if (validated.issues) {
+      return serverErrorResponse(400, `Invalid args for ${cmd}`, {
+        cid,
+        cmd,
+        issues: validated.issues,
+      })
+    }
+
+    /** @type {unknown} */
+    let receipt
+    try {
+      receipt = await handler({
+        args: validated.value,
+        invocation,
+        signer: options.signer,
+        store: options.store,
+      })
+    } catch (error) {
+      return serverErrorResponse(
+        500,
+        error instanceof Error ? error.message : String(error),
+        { cid, cmd }
+      )
+    }
+
+    const validatedReceipt = await command.receipt['~standard'].validate(
+      /** @type {any} */ (receipt)
+    )
+    if (validatedReceipt.issues) {
+      return serverErrorResponse(500, `Invalid receipt for ${cmd}`, {
+        cid,
+        cmd,
+        issues: validatedReceipt.issues,
+      })
+    }
+
+    return Response.json(receipt)
+  }
+}

package/src/rpc/types.js

@@ -0,0 +1,9 @@
+/**
+ * Runtime stub for the type-only `./types.ts` module so that
+ * `export * from './types.js'` in `index.js` resolves under plain Node
+ * (e.g. when consumers run `.ts` files via `--experimental-strip-types`).
+ *
+ * All real declarations live in `./types.ts`; TypeScript's bundler
+ * resolution prefers the `.ts` file at type-check time.
+ */
+export {}

package/src/rpc/types.ts

@@ -0,0 +1,153 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { ISigner } from 'iso-signatures/types'
+import type { Capability } from '../capability.js'
+import type { Invocation } from '../invocation.js'
+import type { Store } from '../store.js'
+import type { ClientOptions, Promisable, VerifierResolver } from '../types.js'
+
+export interface CommandOptions<
+  Args extends StandardSchemaV1,
+  Cmd extends string = string,
+  ReceiptSchema extends StandardSchemaV1 = StandardSchemaV1,
+> {
+  cmd: Cmd
+  args: Args
+  receipt: ReceiptSchema
+}
+
+export interface CommandOutput<
+  Args extends StandardSchemaV1,
+  Cmd extends string = string,
+  ReceiptSchema extends StandardSchemaV1 = StandardSchemaV1,
+> {
+  capability: Capability<Args, Cmd>
+  receipt: ReceiptSchema
+}
+
+export type AnyCommand = CommandOutput<
+  StandardSchemaV1,
+  string,
+  StandardSchemaV1
+>
+
+export type CommandsRecord = Record<string, AnyCommand>
+
+/**
+ * Union of `{cmd, args, receipt}` shapes derived from a commands record.
+ * Used to discriminate `request` calls by `cmd`.
+ *
+ * `args` is the schema's input type (what the caller provides) and `receipt`
+ * is the schema's output type (what the caller receives back).
+ */
+export type CommandUnion<Commands extends CommandsRecord> = {
+  [K in keyof Commands]: Commands[K] extends CommandOutput<
+    infer Args,
+    infer Cmd,
+    infer ReceiptSchema
+  >
+    ? {
+        cmd: Cmd
+        args: StandardSchemaV1.InferInput<Args>
+        receipt: StandardSchemaV1.InferOutput<ReceiptSchema>
+      }
+    : never
+}[keyof Commands]
+
+/**
+ * Server-side counterpart to {@link CommandUnion}: `args` is the schema's
+ * output (validated value passed to the handler) and `receipt` is the
+ * schema's input — the full receipt object, including `cid`, that the
+ * handler is responsible for constructing (typically using `invocation.cid`).
+ */
+export type ServerCommandUnion<Commands extends CommandsRecord> = {
+  [K in keyof Commands]: Commands[K] extends CommandOutput<
+    infer Args,
+    infer Cmd,
+    infer ReceiptSchema
+  >
+    ? {
+        cmd: Cmd
+        args: StandardSchemaV1.InferOutput<Args>
+        receipt: StandardSchemaV1.InferInput<ReceiptSchema>
+      }
+    : never
+}[keyof Commands]
+
+/**
+ * Options for {@link defineClient}.
+ *
+ * Same as {@link ClientOptions} but the `capabilities` are derived from the
+ * commands record passed as the first argument.
+ */
+export type DefineClientOptions = Omit<ClientOptions, 'capabilities'>
+
+/**
+ * Options for {@link CommandClient.request}.
+ */
+export type RequestOptions<
+  Commands extends CommandsRecord,
+  Cmd extends CommandUnion<Commands>['cmd'] = CommandUnion<Commands>['cmd'],
+> = {
+  cmd: Cmd
+  args: Extract<CommandUnion<Commands>, { cmd: Cmd }>['args']
+}
+
+/**
+ * Type-safe client built from a record of commands.
+ */
+export interface CommandClient<Commands extends CommandsRecord> {
+  request<Cmd extends CommandUnion<Commands>['cmd']>(
+    options: RequestOptions<Commands, Cmd>
+  ): Promise<Extract<CommandUnion<Commands>, { cmd: Cmd }>['receipt']>
+  invoke<Cmd extends CommandUnion<Commands>['cmd']>(
+    options: RequestOptions<Commands, Cmd>
+  ): Promise<Invocation>
+}
+
+/**
+ * Options passed to a server handler.
+ *
+ * `args` is the validated/decoded args from the command's schema.
+ */
+export interface ServerHandlerOptions<Args> {
+  args: Args
+  invocation: Invocation
+  signer: ISigner
+  store: Store
+}
+
+/**
+ * Map of server handlers keyed by `cmd`, derived from a commands record.
+ *
+ * Each handler receives args typed as the command's args schema output and
+ * must return a value matching the command's receipt schema input.
+ */
+export type ServerHandlers<Commands extends CommandsRecord> = {
+  [Cmd in ServerCommandUnion<Commands>['cmd']]: (
+    options: ServerHandlerOptions<
+      Extract<ServerCommandUnion<Commands>, { cmd: Cmd }>['args']
+    >
+  ) => Promisable<
+    Extract<ServerCommandUnion<Commands>, { cmd: Cmd }>['receipt']
+  >
+}
+
+/**
+ * Options for {@link defineServer}.
+ */
+export interface DefineServerOptions<Commands extends CommandsRecord> {
+  handlers: ServerHandlers<Commands>
+  /**
+   * The server's signer. Used as the audience when decoding the incoming
+   * invocation and passed through to handlers as `signer` so they can issue
+   * receipts or further invocations.
+   */
+  signer: ISigner
+  store: Store
+  verifierResolver: VerifierResolver
+}
+
+/**
+ * Handler for an incoming HTTP request, returned by {@link defineServer}.
+ */
+export type ServerRequestHandler = (request: Request) => Promise<Response>

package/src/store.js

@@ -128,14 +128,28 @@ export class Store {
   }
 
   /**
-   * Resolve a single chain of proofs ending with a root (subject === issuer).
-   * Returns the first such chain found (depth-first).
+   * Resolve the first such chain found (depth-first), ordered from root to leaf.
+   *
+   * Cycles are detected via a per-path visited set of delegation CIDs so that
+   * self-delegations or other loops can be skipped without recursing forever.
    *
    * @param {import('./types.js').StoreProofsOptions} options
    * @returns {Promise<Delegation[]>}
    */
   async chain({ aud, sub, cmd, args }) {
-    // console.log('🚀 ~ aud', aud, 'sub', sub, 'cmd', cmd)
+    const path = await this.#chain({ aud, sub, cmd, args }, new Set())
+    return path ? path.reverse() : []
+  }
+
+  /**
+   * Internal depth-first search for a delegation chain. Returns the path in
+   * leaf-to-root order, or `null` if no path exists.
+   *
+   * @param {import('./types.js').StoreProofsOptions} options
+   * @param {Set<string>} visited - delegation CIDs already on the current path
+   * @returns {Promise<Delegation[] | null>}
+   */
+  async #chain({ aud, sub, cmd, args }, visited) {
     const parents = parentCmds(cmd)
 
     const sources = merge(
@@ -147,28 +161,39 @@ export class Store {
       if (!parents.includes(proof.cmd)) continue
       if (!validate(args, proof.pol)) continue
 
+      const cidStr = proof.cid.toString()
+      if (visited.has(cidStr)) continue
+
+      const issDid = didParse(proof.iss).did
+
       // If root, return this proof as the end of the path
-      if (proof.sub === didParse(proof.iss).did) {
-        // console.log('🚀 ~ found root:', proof.iss, proof.sub, proof.cmd)
+      if (proof.sub === issDid) {
         return [proof]
       }
 
-      // Otherwise, go deeper and prepend this proof if a path is found
-      // console.log('🚀 ~ trying deeper:', proof.iss, proof.sub, proof.cmd)
-      const nextPath = await this.chain({
-        aud: didParse(proof.iss).did,
-        sub: proof.sub ? proof.sub : sub,
-        cmd: proof.cmd,
-        args,
-      })
+      // Skip non-root self-delegations (iss === aud). They never add
+      // capabilities a chain wouldn't already have through the predecessor
+      // delegation, and following them only lengthens the resulting chain.
+      if (issDid === proof.aud) continue
+
+      visited.add(cidStr)
+      const nextPath = await this.#chain(
+        {
+          aud: issDid,
+          sub: proof.sub ? proof.sub : sub,
+          cmd: proof.cmd,
+          args,
+        },
+        visited
+      )
+      visited.delete(cidStr)
+
       if (nextPath?.length) {
         return [proof, ...nextPath]
       }
-      // console.log('🚀 ~ no path found')
     }
 
-    // No path found
-    return []
+    return null
   }
 }
 

package/src/types.ts

@@ -13,6 +13,7 @@ import type { Policy } from './types/policy'
 export type { StandardSchemaV1 } from '@standard-schema/spec'
 export type { DID, DIDURL, DIDURLObject } from 'iso-did/types'
 export type { ISigner } from 'iso-signatures/types'
+export * from './rpc/types'
 export * from './types/envelope'
 export * from './types/policy'
 export * from './types/varsig'
@@ -63,12 +64,22 @@ export interface DelegationOptions<Schema extends StandardSchemaV1> {
   nonce?: Uint8Array
   cmd: string
   meta?: CborObject
+  /**
+   * The current time in seconds. Mostly used for testing.
+   * @default Math.floor(Date.now() / 1000)
+   */
+  now?: number
 }
 
 export interface DelegationValidateOptions {
   isRevoked?: IsRevoked
   didResolver?: DidResolver
   verifierResolver: VerifierResolver
+  /**
+   * The current time in seconds. Mostly used for testing.
+   * @default Math.floor(Date.now() / 1000)
+   */
+  now?: number
 }
 
 export interface DelegationFromOptions extends DelegationValidateOptions {
@@ -113,7 +124,7 @@ export interface InvocationOptions extends DelegationValidateOptions {
 
 export interface InvocationFromOptions extends DelegationValidateOptions {
   bytes: Uint8Array
-  audience: VerifiableDID
+  audience?: VerifiableDID
   resolveProof: ResolveProof
 }
 
@@ -127,7 +138,7 @@ export interface InvocationFromOptions extends DelegationValidateOptions {
 export interface CapabilityOptions<
   Schema extends StandardSchemaV1,
   Cmd extends string = string,
-> extends DelegationValidateOptions {
+> {
   schema: Schema
   cmd: Cmd
 }
@@ -147,10 +158,7 @@ export interface CapabilityDelegateOptions<Schema extends StandardSchemaV1>
  * Invoke a capability
  */
 export interface CapabilityInvokeOptions<Schema extends StandardSchemaV1>
-  extends Omit<
-    InvocationOptions,
-    'cmd' | 'args' | 'prf' | 'verifierResolver' | 'didResolver' | 'isRevoked'
-  > {
+  extends Omit<InvocationOptions, 'cmd' | 'args' | 'prf'> {
   args: StandardSchemaV1.InferOutput<Schema>
   /**
    * Store to resolve proofs from
@@ -267,4 +275,5 @@ export type ClientOptions = {
   audience: DIDURLObject
   store: Store
   capabilities: Capability<StandardSchemaV1, string>[]
+  verifierResolver: VerifierResolver
 }

package/src/utils.js

@@ -42,7 +42,7 @@ export function nowInSeconds() {
 export async function cid(envelope) {
   const bytes = Envelope.encode({
     signature: envelope.signature,
-    // @ts-ignore
+    // @ts-expect-error
     signaturePayload: signaturePayload(envelope),
   })
   const hash = await sha256.digest(bytes)
@@ -91,9 +91,9 @@ export function isSigAndDidCompatible(did, sigType) {
  * Validate the expiration of a UCAN
  *
  * @param {number | null} exp
+ * @param {number} [now]
  */
-export function assertExpiration(exp) {
-  const now = nowInSeconds()
+export function assertExpiration(exp, now = nowInSeconds()) {
   if (exp !== null && !Number.isSafeInteger(exp)) {
     throw new TypeError(
       `UCAN expiration must be null or a safe integer. Received: ${exp}`
@@ -111,9 +111,10 @@ export function assertExpiration(exp) {
  * Validate the not before time of a UCAN
  *
  * @param {number} [nbf]
+ * @param {number} [now]
  */
-export function assertNotBefore(nbf) {
-  if (nbf && nbf > nowInSeconds()) {
+export function assertNotBefore(nbf, now = nowInSeconds()) {
+  if (nbf && nbf > now) {
     throw new Error('UCAN not valid yet')
   }
 }
@@ -149,20 +150,43 @@ export async function verifySignature(
   didResolver
 ) {
   const issuer = await validateIssuerAndSignature(envelope, didResolver)
-  const isVerified = await signatureVerifierResolver.verify({
-    signature: envelope.signature,
-    message: dagCbor.encode(signaturePayload(envelope)),
-    did: issuer,
-    type: envelope.alg,
-  })
-
-  if (!isVerified) {
-    throw new Error('UCAN signature verification failed')
+  try {
+    const isVerified = await signatureVerifierResolver.verify({
+      signature: envelope.signature,
+      message: dagCbor.encode(signaturePayload(envelope)),
+      did: issuer,
+      type: envelope.alg,
+    })
+
+    if (!isVerified) {
+      throw new Error('UCAN signature verification failed')
+    }
+  } catch (error) {
+    throw new Error('UCAN signature verification failed', { cause: error })
   }
 
   return true
 }
 
+/**
+ * Check if a command is covered by (equal to or a segment-wise child of) another command.
+ *
+ * Commands are compared by path segment, not by string prefix: `/crypto` covers
+ * `/crypto` and `/crypto/sign` but not `/cryptocurrency`. The command `/` covers
+ * every command.
+ *
+ * Both commands are expected to be valid per {@link assertIsValidCommand}, so
+ * `${parent}/` is always a real segment boundary.
+ *
+ * @param {string} parent - The broader command, e.g. from a delegation.
+ * @param {string} child - The command that must be attenuated from `parent`.
+ * @returns {boolean}
+ */
+export function commandCovers(parent, child) {
+  if (parent === '/') return child.startsWith('/')
+  return child === parent || child.startsWith(`${parent}/`)
+}
+
 /**
  * Asserts that a UCAN command string is syntactically valid.
  * If the command is invalid, it throws a descriptive error.
@@ -333,7 +357,7 @@ export const selector = z.union([
 export const statement =
   /** @type {typeof z.lazy<z.ZodType<import('../src/types.js').Statement<unknown>>>} */ (
     z.lazy
-    // @ts-ignore
+    // @ts-expect-error
   )(() => {
     return z.union([
       z.tuple([