iso-ucan 0.0.1

package/src/envelope.js

@@ -0,0 +1,88 @@
+import * as cbor from '@ipld/dag-cbor'
+import * as varsig from './varsig.js'
+
+/**
+ * @import { Envelope, PayloadTag, EnvelopeDecodeOptions, EnvelopeEncodeOptions, EnvelopeSignOptions, SignaturePayload, PayloadSpec, DecodedEnvelope, DelegationPayload, InvocationPayload} from './types.js'
+ * @import { ByteView } from 'multiformats'
+ */
+
+/** Version */
+export const VERSION = '1.0.0-rc.1'
+
+/**
+ *
+ * @param {EnvelopeSignOptions} options
+ */
+export async function sign(options) {
+  const { spec, version, enc, signer, payload } = options
+
+  const payloadTag = /** @type {PayloadTag} */ (
+    `ucan/${spec}@${version ?? VERSION}`
+  )
+  const h = varsig.encode({ enc: enc ?? 'DAG-CBOR', alg: signer.signatureType })
+
+  const signaturePayload = /** @type {SignaturePayload} */ ({
+    h,
+    [payloadTag]: payload,
+  })
+  const signature = await signer.sign(cbor.encode(signaturePayload))
+  return {
+    signature,
+    signaturePayload,
+  }
+}
+
+/**
+ * Encode a UCAN envelope
+ *
+ * @see https://github.com/ucan-wg/spec#envelope
+ * @param {EnvelopeEncodeOptions} options
+ *
+ */
+export function encode(options) {
+  const { signature, signaturePayload } = options
+
+  const envelope = [signature, signaturePayload]
+
+  return cbor.encode(envelope)
+}
+
+/**
+ * Decode a UCAN envelope
+ *
+ * @template {PayloadSpec} Spec
+ * @see https://github.com/ucan-wg/spec#envelope
+ * @param {EnvelopeDecodeOptions} options
+ * @returns {DecodedEnvelope<Spec>}
+ */
+export function decode(options) {
+  const { envelope } = options
+
+  const decoded = /** @type typeof cbor.decode<Envelope> **/ (cbor.decode)(
+    /** @type {ByteView<Envelope>} */ (envelope)
+  )
+
+  const [signature, sigPayload] = decoded
+  const [_h, payloadTag] = Object.keys(sigPayload)
+  const header = sigPayload.h
+  /** @type {DelegationPayload | InvocationPayload} */
+  const payload = sigPayload[/** @type {PayloadTag} */ (payloadTag)]
+
+  const [_ucan, specVersion] = payloadTag.split('/')
+  const [spec, version] = specVersion.split('@')
+
+  const { alg, enc } = varsig.decode(header)
+
+  return {
+    alg,
+    enc,
+    signature,
+    // Narrow payload type based on Spec
+    payload:
+      /** @type {Spec extends "dlg" ? DelegationPayload : InvocationPayload} */ (
+        payload
+      ),
+    spec: /** @type {Spec} */ (spec),
+    version,
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export * as Varsig from './varsig.js'

package/src/invocation.js

@@ -0,0 +1,227 @@
+import { parse as didParse } from 'iso-did'
+import { randomBytes } from 'iso-web/crypto'
+import * as Envelope from './envelope.js'
+import {
+  assertArgs,
+  assertExpiration,
+  assertIsValidCommand,
+  assertMeta,
+  assertNonce,
+  cid,
+  expOrTtl,
+  verifySignature,
+} from './utils.js'
+
+/**
+ * @import {Delegation} from './delegation.js'
+ * @import {CID} from 'multiformats'
+ */
+
+/**
+ * UCAN Invocation
+ */
+export class Invocation {
+  /**
+   * @type {Delegation[]}
+   */
+  delegations
+
+  /**
+   * @type {CID}
+   */
+  cid
+
+  /**
+   *
+   * @param {import("./types.js").DecodedEnvelope<'inv'>} envelope
+   * @param {Uint8Array} bytes
+   * @param {CID} cid
+   * @param {Delegation[]} delegations
+   */
+  constructor(envelope, bytes, cid, delegations) {
+    this.envelope = envelope
+    this.payload = envelope.payload
+    this.bytes = bytes
+    this.cid = cid
+    this.delegations = delegations
+  }
+
+  /**
+   *
+   * @param {import("./types.js").InvocationFromOptions} options
+   */
+  static async from(options) {
+    const { bytes, audience } = options
+
+    const envelope = /** @type {typeof Envelope.decode<"inv">} */ (
+      Envelope.decode
+    )({ envelope: bytes })
+
+    if (envelope.spec !== 'inv') {
+      throw new Error(
+        `Invalid envelope type. Expected: Invocation but got: ${envelope.spec}`
+      )
+    }
+    assertStructure(envelope.payload)
+    await verifySignature(
+      envelope,
+      options.verifierResolver,
+      options.didResolver
+    )
+
+    // Audience or subject must match receiver
+    if (
+      envelope.payload.aud !== audience.did &&
+      envelope.payload.sub !== audience.did
+    ) {
+      throw new Error(
+        `UCAN Invocation audience or subject does not match receiver. Expected: ${audience.did} but got: ${envelope.payload.aud ?? envelope.payload.sub ?? 'null'}`
+      )
+    }
+
+    // Resolve and validate proofs
+
+    /** @type {Delegation[]} */
+    const proofs = []
+    for (const proof of envelope.payload.prf) {
+      const delegation = await options.resolveProof(proof)
+      await delegation.validate(options)
+      proofs.push(delegation)
+    }
+
+    assertProofs(envelope.payload, proofs)
+
+    const _cid = await cid(envelope)
+    return new Invocation(envelope, bytes, _cid, proofs)
+  }
+
+  /**
+   * @param {import("./types.js").InvocationOptions} options
+   */
+  static async create(options) {
+    const nonce = options.nonce || randomBytes(12)
+
+    /** @type {import("./types.js").InvocationPayload} */
+    const payload = {
+      iss: options.iss.toString(),
+      aud: options.aud ? options.aud : options.sub,
+      sub: options.sub,
+      cmd: options.cmd,
+      nonce,
+      exp: expOrTtl(options),
+      args: options.args,
+      prf: options.prf.map((p) => p.cid),
+    }
+    if (options.cause) {
+      payload.cause = options.cause
+    }
+    if (options.meta) {
+      payload.meta = options.meta
+    }
+    if (options.iat) {
+      payload.iat = options.iat
+    }
+    if (options.nbf) {
+      payload.nbf = options.nbf
+    }
+
+    assertStructure(payload)
+    assertProofs(payload, options.prf)
+
+    const { signature, signaturePayload } = await Envelope.sign({
+      spec: 'inv',
+      signer: options.iss,
+      payload,
+    })
+
+    const bytes = Envelope.encode({ signature, signaturePayload })
+
+    /** @type {import("./types.js").DecodedEnvelope<'inv'>} */
+    const envelope = {
+      alg: options.iss.signatureType,
+      enc: 'DAG-CBOR',
+      signature,
+      payload,
+      spec: 'inv',
+      version: Envelope.VERSION,
+    }
+
+    return new Invocation(envelope, bytes, await cid(envelope), options.prf)
+  }
+}
+
+/**
+ * @param {import('./types.js').InvocationPayload} payload
+ */
+function assertStructure(payload) {
+  didParse(payload.iss)
+  didParse(payload.sub)
+
+  if (payload.aud) {
+    didParse(payload.aud)
+  }
+
+  assertIsValidCommand(payload.cmd)
+  assertArgs(payload.args)
+  assertMeta(payload.meta)
+  assertNonce(payload.nonce)
+  assertExpiration(payload.exp)
+}
+
+/**
+ *
+ * @param {import("./types.js").InvocationPayload} payload
+ * @param {Delegation[]} proofs
+ */
+export function assertProofs(payload, proofs) {
+  if (payload.prf.length <= 0) {
+    throw new Error('UCAN Invocation proofs are required')
+  }
+
+  if (proofs.length !== payload.prf.length) {
+    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) {
+    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)
+
+    const nextProof = proofs[index + 1]
+    /** @type {import("./types.js").Payload} */
+    let next
+    if (nextProof) {
+      next = nextProof.envelope.payload
+    } else {
+      next = payload
+    }
+
+    const nextIssuer = didParse(next.iss)
+    const nextSubject = didParse(next.sub ?? payload.sub)
+    if (nextIssuer.did !== currentAudience.did) {
+      throw new Error(
+        `UCAN Invocation principal alignment mismatch, expected ${currentAudience.toString()} but got ${nextIssuer.toString()}`
+      )
+    }
+
+    if (nextSubject.did !== currentSubject.did) {
+      throw new Error(
+        `UCAN Invocation subject alignment mismatch, expected ${currentSubject.toString()} but got ${nextSubject.toString()}`
+      )
+    }
+
+    if (!next.cmd.startsWith(current.cmd)) {
+      throw new Error(
+        `UCAN Invocation command mismatch, expected ${current.cmd} to be a broader than ${next.cmd}`
+      )
+    }
+  }
+
+  return true
+}

package/src/policy.js

@@ -0,0 +1,272 @@
+/**
+ * Resolves a selector string against a data object, inspired by jq.
+ *
+ * @param {any} data The data to select from.
+ * @param {string} selector The selector string (e.g., ".foo[0].bar").
+ * @returns {any} The selected value, or null if the selection fails at an optional part.
+ * @throws {Error} If the selection fails at a non-optional part.
+ */
+function resolveSelector(data, selector) {
+  if (selector === '.') {
+    return data
+  }
+
+  // This regex is a simplified parser for the selector syntax.
+  const partsRegex = /(\.[\w_]+|\[-?\d*:-?\d*\]|\[-?\d+\]|\[\]|\?)/g
+  const parts = selector.match(partsRegex) || []
+
+  let currentData = data
+
+  for (let part of parts) {
+    let isOptional = false
+    if (part.endsWith('?')) {
+      isOptional = true
+      part = part.slice(0, -1)
+    }
+
+    try {
+      if (currentData === undefined || currentData === null) {
+        throw new Error(
+          `Cannot process part "${part}" on null or undefined value.`
+        )
+      }
+
+      if (part.startsWith('.')) {
+        const key = part.substring(1)
+        if (typeof currentData !== 'object' || Array.isArray(currentData)) {
+          throw new Error(`Cannot access key "${key}" on non-object.`)
+        }
+        currentData = currentData[key]
+      } else if (part === '[]') {
+        if (Array.isArray(currentData)) {
+          // No-op for arrays, the quantifier will iterate over it.
+        } else if (typeof currentData === 'object') {
+          currentData = Object.values(currentData)
+        } else {
+          throw new Error('Cannot extract values from non-collection.')
+        }
+      } else if (part.startsWith('[') && part.includes(':')) {
+        // Slice
+        if (!Array.isArray(currentData)) {
+          throw new Error('Slice can only be applied to arrays.')
+        }
+        const [start, end] = part
+          .substring(1, part.length - 1)
+          .split(':')
+          .map((s) => (s ? Number.parseInt(s, 10) : undefined))
+        currentData = currentData.slice(start, end)
+      } else if (part.startsWith('[')) {
+        // Index
+        if (!Array.isArray(currentData)) {
+          throw new Error('Index can only be applied to arrays.')
+        }
+        const index = Number.parseInt(part.substring(1, part.length - 1), 10)
+        currentData =
+          currentData[index < 0 ? currentData.length + index : index]
+      }
+
+      if (currentData === undefined) {
+        throw new Error(`Path segment returned undefined: ${part}`)
+      }
+    } catch (e) {
+      if (isOptional) {
+        return null
+      }
+      // Re-throw if not optional, to be caught by evaluateStatement
+      throw e
+    }
+  }
+
+  return currentData
+}
+
+/**
+ * Performs a deep equality check between two values.
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean}
+ */
+function deepEqual(a, b) {
+  if (a === b) return true
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    if (a.constructor !== b.constructor) return false
+    if (Array.isArray(a)) {
+      if (a.length !== b.length) return false
+      for (let i = 0; i < a.length; i++) {
+        if (!deepEqual(a[i], b[i])) return false
+      }
+      return true
+    }
+    const keys = Object.keys(a)
+    if (keys.length !== Object.keys(b).length) return false
+    for (const key of keys) {
+      // biome-ignore lint/suspicious/noPrototypeBuiltins: needed
+      if (!b.hasOwnProperty(key) || !deepEqual(a[key], b[key])) return false
+    }
+    return true
+  }
+  return false
+}
+
+/**
+ * Converts a UCAN glob pattern to a regular expression.
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+function likeRegex(pattern) {
+  // Convert UCAN glob pattern to a regular expression.
+  // The glob pattern has `*` as a wildcard (zero or more chars)
+  // and `\*` as an escape for a literal asterisk.
+  let regexString = '^'
+  let i = 0
+  while (i < pattern.length) {
+    const char = pattern[i]
+
+    if (char === '\\') {
+      // Handle escape sequence
+      if (i + 1 < pattern.length) {
+        const nextChar = pattern[i + 1]
+        if (nextChar === '*') {
+          // This is an escaped asterisk `\*`. Match a literal `*`.
+          regexString += '\\*'
+          i += 2 // Move past both `\` and `*`
+        } else {
+          // This is another escape, like `\\`. Treat the `\` as a literal character.
+          regexString += '\\\\'
+          i++
+        }
+      } else {
+        // Trailing backslash. Treat as a literal `\`.
+        regexString += '\\\\'
+        i++
+      }
+    } else if (char === '*') {
+      // This is a wildcard `*`. Match zero or more characters.
+      regexString += '.*'
+      i++
+    } else {
+      // This is a regular character. Escape it if it's a special regex metacharacter.
+      regexString += char.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+      i++
+    }
+  }
+  regexString += '$'
+
+  return new RegExp(regexString)
+}
+
+/**
+ * Evaluates a single policy statement against the invocation args.
+ *
+ * @template Args
+ * @param {Args} args The invocation arguments.
+ * @param {import("./types.js").Statement<Args>} statement The policy statement.
+ * @returns {boolean} The result of the evaluation.
+ */
+function evaluateStatement(args, statement) {
+  const [op, ...params] = statement
+
+  try {
+    switch (op) {
+      // Comparisons
+      case '==': {
+        const [selector, value] = /** @type {[string, unknown]} */ (params)
+
+        return deepEqual(resolveSelector(args, selector), value)
+      }
+      case '!=': {
+        const [selector, value] = /** @type {[string, unknown]} */ (params)
+        return !deepEqual(resolveSelector(args, selector), value)
+      }
+      case '>':
+      case '>=':
+      case '<':
+      case '<=': {
+        const [selector, value] = /** @type {[string, number]} */ (params)
+        const selected = resolveSelector(args, selector)
+        if (typeof selected !== 'number' || typeof value !== 'number')
+          return false
+        if (op === '>') return selected > value
+        if (op === '>=') return selected >= value
+        if (op === '<') return selected < value
+        if (op === '<=') return selected <= value
+        break
+      }
+      // Glob Matching
+      case 'like': {
+        const [selector, pattern] = /** @type {[string, string]} */ (params)
+        const selected = resolveSelector(args, selector)
+        if (typeof selected !== 'string') return false
+        const regex = likeRegex(pattern)
+        return regex.test(selected)
+      }
+      // Connectives
+      case 'and': {
+        const [statements] = /** @type {[import("./types.js").Statement[]]} */ (
+          params
+        )
+        return statements.every((stmt) => evaluateStatement(args, stmt))
+      }
+      case 'or': {
+        const [statements] = /** @type {[import("./types.js").Statement[]]} */ (
+          params
+        )
+        if (statements.length === 0) return true
+        return statements.some((stmt) => evaluateStatement(args, stmt))
+      }
+      case 'not': {
+        const [statement] = /** @type {[import("./types.js").Statement]} */ (
+          params
+        )
+        return !evaluateStatement(args, statement)
+      }
+      // Quantification
+      case 'all':
+      case 'any': {
+        const [selector, innerStmt] =
+          /** @type {[string, import("./types.js").Statement]} */ (params)
+        let collection = resolveSelector(args, selector)
+
+        if (innerStmt[0] === 'any' || innerStmt[0] === 'all') {
+          return evaluateStatement(collection, innerStmt)
+        }
+
+        if (
+          collection &&
+          typeof collection === 'object' &&
+          !Array.isArray(collection)
+        ) {
+          collection = Object.values(collection)
+        }
+        if (!Array.isArray(collection)) return false
+        if (collection.length === 0) return true
+        if (op === 'all') {
+          return collection.every((item) => {
+            return evaluateStatement(item, innerStmt)
+          })
+        }
+        // any
+        return collection.some((item) => evaluateStatement(item, innerStmt))
+      }
+      default:
+        return false // Unknown operator
+    }
+  } catch {
+    // As per the spec, if a selector cannot be resolved, the statement MUST return false.
+    return false
+  }
+  return false
+}
+
+/**
+ * Validates invocation arguments against a UCAN policy.
+ *
+ * @template {Record<string, unknown>} Args
+ * @param {Args} args The arguments of the eventual invocation.
+ * @param {import("./types.js").Policy<Args>} policy An array of policy statements.
+ * @returns {boolean} True if the args are valid according to the policy, false otherwise.
+ */
+export function validate(args, policy) {
+  // The top-level policy is an implicit 'and'.
+  return policy.every((statement) => evaluateStatement(args, statement))
+}

package/src/server.ts

@@ -0,0 +1,24 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { Capability } from './capability.js'
+import type { RouteHandlerOptions, RouteOptions, RouteOutput } from './types.js'
+
+export function route<Cap extends Capability<StandardSchemaV1>, Output>(
+  options: RouteOptions<Cap, Output>
+): RouteOutput<Cap, Output> {
+  return {
+    cap: options.capability,
+    fn: async ({ request, issuer, invocation, store }: RouteHandlerOptions) => {
+      const { capability, handler } = options
+
+      const args = await capability.validate(invocation.payload.args)
+      if (args.issues) {
+        throw new Error(args.issues.map((issue) => issue.message).join(', '))
+      }
+
+      // TODO: handle failure
+      const result = await handler({ args: args.value, store })
+
+      return result
+    },
+  }
+}