iso-ucan 0.0.1

package/src/store.js

@@ -0,0 +1,187 @@
+import { parse as didParse } from 'iso-did'
+import { KV } from 'iso-kv'
+import merge from 'it-merge'
+
+/**
+ * @import {Delegation} from './delegation.js'
+ * @import {Driver} from 'iso-kv'
+ * @import {CID} from 'multiformats'
+ */
+
+const POWERLINE = '$pwrl'
+
+/**
+ * Store
+ */
+export class Store {
+  /** @type {Driver} */
+  driver
+
+  /** @type {KV} */
+  kv
+
+  /**
+   * @param {Driver} driver
+   */
+  constructor(driver) {
+    this.driver = driver
+
+    this.kv = new KV({
+      driver,
+    })
+  }
+
+  /**
+   * Set a delegation in the store by CID and index it by cmd and aud
+   *
+   * @param {Delegation} delegation
+   */
+  async #set(delegation) {
+    const options = {
+      expiration: delegation.envelope.payload.exp,
+    }
+    const cid = delegation.cid.toString()
+
+    // Index by CID
+    await this.kv.set([cid], delegation, options)
+
+    // Index by subject and audience
+    /** @type {string | null} */
+    let sub = delegation.sub ? delegation.sub : null
+    if (sub === null) {
+      sub = POWERLINE
+    }
+    await this.kv.set([sub, delegation.aud, cid], cid, options)
+  }
+
+  /**
+   * @param {Delegation[]} delegations
+   */
+  async add(delegations) {
+    for (const delegation of delegations) {
+      await this.#set(delegation)
+    }
+  }
+
+  /**
+   * Get a delegation by cid
+   *
+   * @param {string} cid
+   */
+  get(cid) {
+    return /** @type {typeof this.kv.get<Delegation>} */ (this.kv.get)([cid])
+  }
+
+  /**
+   * Resolve a proof by CID
+   *
+   * @param {CID} cid
+   */
+  async resolveProof(cid) {
+    const delegation = await this.get(cid.toString())
+    if (!delegation) {
+      throw new Error(`Delegation not found: ${cid.toString()}`)
+    }
+    return delegation
+  }
+
+  /**
+   * List proofs by sub and aud
+   *
+   * @param {import('./types.js').StoreProofsOptions} options
+   */
+  async *proofs(options) {
+    /**@type {string | null} */
+    let sub = options.sub ? options.sub.toString() : null
+    /**@type {string | undefined} */
+    let aud = options.aud ? options.aud.toString() : undefined
+
+    if (!aud && !sub) {
+      throw new Error('No audience or subject provided')
+    }
+    if (!aud && sub) {
+      aud = sub
+    }
+    if (sub === null) {
+      sub = POWERLINE
+    }
+    if (!aud) {
+      throw new Error('No audience provided')
+    }
+
+    for await (const element of this.kv.list({
+      prefix: [sub, aud],
+    })) {
+      const value = await this.get(element.value)
+
+      if (value) {
+        yield value
+      }
+    }
+  }
+
+  /**
+   * Resolve a single chain of proofs ending with a root (subject === issuer).
+   * Returns the first such chain found (depth-first).
+   *
+   * @param {import('./types.js').StoreProofsOptions} options
+   * @returns {Promise<Delegation[]>}
+   */
+  async chain({ aud, sub, cmd }) {
+    // console.log('🚀 ~ aud', aud, 'sub', sub, 'cmd', cmd)
+    const parents = parentCmds(cmd)
+
+    const sources = merge(
+      this.proofs({ sub, aud, cmd }),
+      this.proofs({ sub: null, aud, cmd })
+    )
+
+    for await (const proof of sources) {
+      if (!parents.includes(proof.cmd)) continue
+
+      // 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)
+        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,
+      })
+      if (nextPath?.length) {
+        return [proof, ...nextPath]
+      }
+      // console.log('🚀 ~ no path found')
+    }
+
+    // No path found
+    return []
+  }
+}
+
+/**
+ * Returns all parent commands for a given command string.
+ *
+ * @param {string} cmd
+ * @returns {string[]}
+ * @example
+ * ```ts twoslash
+ * import { parentCmds } from 'iso-ucan/store'
+ * parentCmds('/foo/bar/baz') // ["/", "/foo", "/foo/bar", "/foo/bar/baz"]
+ * ```
+ */
+function parentCmds(cmd) {
+  if (!cmd || cmd === '/') return ['/']
+  const parts = cmd.split('/').filter(Boolean)
+  const result = ['/']
+  let current = ''
+  for (const part of parts) {
+    current += `/${part}`
+    result.push(current)
+  }
+  return result
+}

package/src/types/envelope.ts

@@ -0,0 +1,131 @@
+import type { DID, DIDURL } from 'iso-did/types'
+import type { ISigner } from 'iso-signatures/types'
+import type { CID } from 'multiformats'
+import type { Policy } from './policy'
+import type { VarsigAlgorithm, VarsigEncoding } from './varsig'
+
+/**
+ * Envelope types
+ */
+
+export type PayloadSpec = 'dlg' | 'inv'
+export type PayloadTag = `ucan/${PayloadSpec}@${string}`
+export interface PayloadBase {
+  /**
+   * Issuer DID (sender)
+   */
+  iss: DIDURL
+  /**
+   * Audience DID (receiver)
+   */
+  aud?: DID
+  /**
+   * Principal that the chain is about (the [Subject])
+   */
+  sub?: DID | null
+  /**
+   * The Command to eventually invoke
+   * @see https://github.com/ucan-wg/spec#command
+   */
+  cmd: string
+  /**
+   * The nonce of the UCAN
+   * @see https://github.com/ucan-wg/spec#nonce
+   */
+  nonce: Uint8Array
+  /**
+   * Meta (asserted, signed data) — is not delegated authority
+   */
+  meta?: Record<string, unknown>
+  /**
+   * Expiration UTC Unix Timestamp in seconds (valid until)
+   */
+  exp: number | null
+  /**
+   * "Not before" UTC Unix Timestamp in seconds (valid from)
+   */
+  nbf?: number
+}
+
+/**
+ * @see https://github.com/ucan-wg/invocation#invocation-payload
+ */
+export interface InvocationPayload extends PayloadBase {
+  sub: DID
+  /**
+   * Optional if equal to subject
+   */
+  aud?: DID
+
+  /**
+   * Any [Arguments] that MUST be present in the Invocation
+   */
+  args: Record<string, unknown>
+  /**
+   * Delegations that prove the chain of authority
+   */
+  prf: CID[]
+  /**
+   * Issued at time
+   */
+  iat?: number
+  /**
+   * An OPTIONAL CID of the Receipt that enqueued the Task
+   */
+  cause?: CID
+}
+
+export interface DelegationPayload<Args = unknown> extends PayloadBase {
+  aud: DID
+  /**
+   * Subject can be null here for Powerline
+   * @see https://github.com/ucan-wg/delegation/#powerline
+   */
+  sub: DID | null
+  pol: Policy<Args>
+}
+
+export type Payload<Args = unknown> =
+  | InvocationPayload
+  | DelegationPayload<Args>
+export type SignaturePayload<Args = unknown> = {
+  h: Uint8Array
+  [payloadTag: PayloadTag]: Payload<Args>
+}
+
+export type Envelope<Args = unknown> = [Uint8Array, SignaturePayload<Args>]
+
+/**
+ * @see https://github.com/ucan-wg/spec#envelope
+ */
+export type EnvelopeEncodeOptions = {
+  signature: Uint8Array
+  signaturePayload: SignaturePayload
+}
+
+export interface EnvelopeSignOptions {
+  /**
+   * @default '1.0.0'
+   */
+  version?: string
+  /**
+   * @default 'DAG-CBOR'
+   */
+  enc?: VarsigEncoding
+  spec: PayloadSpec
+  payload: Payload
+  signer: ISigner
+}
+
+export interface EnvelopeDecodeOptions {
+  envelope: Uint8Array
+}
+
+export type DecodedEnvelope<Spec extends PayloadSpec> = {
+  alg: VarsigAlgorithm
+  enc: VarsigEncoding
+  signature: Uint8Array
+  payload: Spec extends 'dlg' ? DelegationPayload : InvocationPayload
+  spec: Spec
+  version: string
+}

package/src/types/policy.ts

@@ -0,0 +1,100 @@
+/**
+ * Policy types
+ * @see https://github.com/ucan-wg/delegation/#policy
+ */
+
+/**
+ * Type-safe selector utilities
+ */
+
+/**
+ * Extracts all possible paths from a data structure as string literals
+ */
+type PathsToStringProps<T> = T extends
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  ? never
+  : T extends Array<infer U>
+    ?
+        | `[]`
+        | `[${number}]`
+        | `[${number}:${number}]`
+        | `[${number}:]`
+        | `[:${number}]`
+        | `[:]`
+        | PathsToStringProps<U>
+    : T extends object
+      ? {
+          [K in keyof T & (string | number)]: K extends string
+            ? `.${K}` | `.${K}?` | `.${K}${PathsToStringProps<T[K]>}`
+            : `[${K}]` | `[${K}]?` | `[${K}]${PathsToStringProps<T[K]>}`
+        }[keyof T & (string | number)]
+      : never
+
+/**
+ * Flattens nested path strings into a union of all possible selectors
+ */
+type FlattenPaths<T> = T extends string
+  ? T
+  : T extends object
+    ? {
+        [K in keyof T]: T[K] extends string
+          ? T[K]
+          : T[K] extends object
+            ? FlattenPaths<T[K]>
+            : never
+      }[keyof T]
+    : never
+
+/**
+ * Type-safe selector that only allows valid paths for the given data structure
+ */
+export type Selector<Args = unknown> = Args extends unknown
+  ? FlattenPaths<PathsToStringProps<Args>> | '.'
+  : string
+
+/**
+ * Extracts the type of the value at a given selector path (minimal version)
+ */
+type SelectorValue<T, S extends string> = S extends `.${infer K}`
+  ? K extends keyof T
+    ? T[K]
+    : never
+  : S extends `[${infer I}]`
+    ? T extends Array<infer U>
+      ? U
+      : never
+    : never
+
+/** Connectives */
+export type EqualityOp = '==' | '!='
+export type Equality<Args = unknown> = [EqualityOp, Selector<Args>, unknown]
+export type InequalityOp = '<' | '<=' | '>' | '>='
+export type Inequality<Args = unknown> = [InequalityOp, Selector<Args>, number]
+
+export type NegateOp = 'not'
+export type Negate<Args = unknown> = [NegateOp, Statement<Args>]
+
+export type ConnectiveOp = 'and' | 'or'
+export type Connective<Args = unknown> = [ConnectiveOp, Statement<Args>[]]
+
+export type QuantifierOp = 'all' | 'any'
+export type Quantifier<
+  Args = unknown,
+  Sel extends Selector<Args> = Selector<Args>,
+> = [QuantifierOp, Sel, Statement<SelectorValue<Args, Sel>>]
+export type LikeOp = 'like'
+export type Like<Args = unknown> = [LikeOp, Selector<Args>, string]
+
+export type Statement<Args = unknown> =
+  | Equality<Args>
+  | Inequality<Args>
+  | Negate<Args>
+  | Connective<Args>
+  | Quantifier<Args>
+  | Like<Args>
+
+export type Policy<Args = unknown> = Statement<Args>[]

package/src/types/varsig.ts

@@ -0,0 +1,22 @@
+import type { SignatureType } from 'iso-signatures/types'
+
+/**
+ * Varsig types
+ */
+
+/**
+ * Supported encoding types for data to be signed or verified
+ */
+export type VarsigEncoding = 'RAW' | 'DAG-CBOR'
+
+/**
+ * Supported signature types
+ */
+export type VarsigAlgorithm = SignatureType
+
+export interface VarsigOptions {
+  enc: VarsigEncoding
+  alg: VarsigAlgorithm
+}
+
+export type DecodeOutput = VarsigOptions

package/src/types.ts

@@ -0,0 +1,243 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { Resolver as _DidResolver } from 'iso-did'
+import type { DID, DIDURLObject, VerifiableDID } from 'iso-did/types'
+import type { ISigner } from 'iso-signatures/types'
+import type { Resolver } from 'iso-signatures/verifiers/resolver.js'
+import type { CID } from 'multiformats'
+import type { Capability } from './capability'
+import type { Delegation } from './delegation'
+import type { Invocation } from './invocation'
+import type { Store } from './store'
+import type { Policy } from './types/policy'
+
+export type { StandardSchemaV1 } from '@standard-schema/spec'
+export type { DID, DIDURL, DIDURLObject } from 'iso-did/types'
+export * from './types/envelope'
+export * from './types/policy'
+export * from './types/varsig'
+
+export type ResolveProof = (proof: CID) => Promise<Delegation>
+export type IsRevoked = (cid: CID) => Promise<boolean>
+export type VerifierResolver = Resolver
+export type DidResolver = _DidResolver
+
+export type CborPrimitive =
+  | string
+  | number
+  | boolean
+  | null
+  | bigint
+  | Uint8Array
+  | ArrayBuffer
+export type CborArray = CborValue[] | readonly CborValue[]
+export type CborObject =
+  | { [Key in string]: CborValue }
+  | { [Key in string]?: CborValue | undefined }
+
+export type CborValue = CborPrimitive | CborArray | CborObject
+
+/**
+ * Delegation
+ */
+
+export interface DelegationOptions<Args = unknown> {
+  iss: ISigner
+  aud: DID
+  sub: DID | null
+  pol: Policy<Args>
+  /**
+   * Expiration time in seconds or null for no expiration
+   */
+  exp?: number | null
+  /**
+   * Time to live in seconds, expiration thats precedence over ttl
+   * @default 300
+   */
+  ttl?: number
+  /**
+   * Not before time in seconds
+   * Delegation is not valid before this time
+   */
+  nbf?: number
+  nonce?: Uint8Array
+  cmd: string
+  meta?: CborObject
+}
+
+export interface DelegationFromOptions {
+  bytes: Uint8Array
+  isRevoked?: IsRevoked
+  didResolver?: DidResolver
+  verifierResolver: VerifierResolver
+}
+
+export interface DelegationValidateOptions {
+  isRevoked?: IsRevoked
+  didResolver?: DidResolver
+  verifierResolver: VerifierResolver
+}
+
+export type CapabilityDelegateOptions<Args = unknown> = Omit<
+  DelegationOptions<Args>,
+  'cmd'
+>
+/**
+ * Invocation
+ */
+
+/**
+ * Invocation options
+ */
+export interface InvocationOptions {
+  iss: ISigner
+  aud?: DID
+  sub: DID
+  cmd: string
+  args: CborObject
+  /**
+   * Proofs of the chain of authority
+   */
+  prf: Delegation[]
+  /**
+   * Expiration time in seconds or null for no expiration
+   */
+  exp?: number | null
+  /**
+   * Time to live in seconds, expiration thats precedence over ttl
+   * @default 300
+   */
+  ttl?: number
+  /**
+   * Issued at time in seconds
+   */
+  iat?: number
+  nbf?: number
+  nonce?: Uint8Array
+  cause?: CID
+  meta?: CborObject
+}
+
+export interface InvocationFromOptions {
+  bytes: Uint8Array
+  audience: VerifiableDID
+  didResolver?: DidResolver
+  verifierResolver: VerifierResolver
+  isRevoked?: IsRevoked
+  resolveProof: ResolveProof
+}
+
+export interface CapabilityInvokeOptions<Schema extends StandardSchemaV1>
+  extends Omit<InvocationOptions, 'cmd' | 'args' | 'prf'> {
+  args: StandardSchemaV1.InferOutput<Schema>
+  store: Store
+}
+
+/**
+ * Store types
+ */
+
+/**
+ * Resolve proofs options
+ */
+export interface StoreProofsOptions {
+  aud?: DID
+  sub: DID | null
+  cmd: string
+}
+
+/**
+ * Server types
+ */
+export type Promisable<T> = T | PromiseLike<T>
+
+export interface HandlerOptions<Schema extends StandardSchemaV1> {
+  args: StandardSchemaV1.InferOutput<Schema>
+  store: Store
+}
+
+export type Handler<Schema extends StandardSchemaV1, Output> = (
+  options: HandlerOptions<Schema>
+) => Promisable<Output>
+
+export interface RouteOptions<
+  Cap extends Capability<StandardSchemaV1>,
+  Output,
+> {
+  capability: Cap
+  handler: Handler<Cap['schema'], Output>
+}
+
+export type RouteOutput<Cap extends Capability<StandardSchemaV1>, Output> = {
+  cap: Cap
+  fn: (options: RouteHandlerOptions) => Promisable<Output>
+}
+
+/**
+ * Infer the protocol from a router
+ */
+export type InferProtocol<
+  Routes extends Record<
+    string,
+    RouteOutput<Capability<StandardSchemaV1>, unknown>
+  >,
+> = {
+  [K in keyof Routes]: Routes[K] extends RouteOutput<infer Cap, infer Output>
+    ? {
+        cmd: Cap['cmd'] extends K ? Cap['cmd'] : never
+        in: StandardSchemaV1.InferOutput<Cap['schema']>
+        out: Output
+      }
+    : never
+}[keyof Routes]
+
+export type Protocol<
+  Cap extends Capability<StandardSchemaV1> = Capability<StandardSchemaV1>,
+> = {
+  cmd: Cap['cmd']
+  in: StandardSchemaV1.InferOutput<Cap['schema']>
+  out: unknown
+}[]
+
+/**
+ * Creates a router type that validates:
+ * 1. Router keys match capability commands
+ * 2. Router values are RouteOutput types that match the capability
+ */
+export type Router<Caps extends readonly Capability<StandardSchemaV1>[]> = {
+  [K in Caps[number]['cmd']]: Caps extends readonly (infer Cap)[]
+    ? Cap extends Capability<StandardSchemaV1>
+      ? Cap['cmd'] extends K
+        ? RouteOutput<Cap, unknown>
+        : never
+      : never
+    : never
+}
+
+export interface RouteHandlerOptions {
+  request: Request
+  issuer: ISigner
+  invocation: Invocation
+  store: Store
+}
+
+/**
+ * Client type that provides type-safe request methods based on router inference
+ */
+export type RouterClient<
+  Router extends InferProtocol<
+    Record<string, RouteOutput<Capability<StandardSchemaV1>, unknown>>
+  >,
+> = {
+  request<Cmd extends Router['cmd']>(
+    cmd: Cmd,
+    args: Extract<Router, { cmd: Cmd }>['in']
+  ): Promise<Extract<Router, { cmd: Cmd }>['out']>
+}
+
+export type ClientOptions = {
+  url: string
+  issuer: ISigner
+  audience: DIDURLObject
+  store: Store
+  capabilities: Capability<StandardSchemaV1, string>[]
+}