iso-ucan 1.0.0 → 3.0.0

package/src/types/envelope.ts

@@ -41,10 +41,6 @@ export interface PayloadBase {
    * Expiration UTC Unix Timestamp in seconds (valid until)
    */
   exp: number | null
-  /**
-   * "Not before" UTC Unix Timestamp in seconds (valid from)
-   */
-  nbf?: number
 }
 
 /**
@@ -83,6 +79,10 @@ export interface DelegationPayload<Args = unknown> extends PayloadBase {
    */
   sub: DID | null
   pol: Policy<Args>
+  /**
+   * "Not before" UTC Unix Timestamp in seconds (valid from)
+   */
+  nbf?: number
 }
 
 export type Payload<Args = unknown> =

package/src/types/policy.ts

@@ -24,7 +24,6 @@ type PathsToStringProps<T> = T extends
         | `[${number}:${number}]`
         | `[${number}:]`
         | `[:${number}]`
-        | `[:]`
         | PathsToStringProps<U>
     : T extends object
       ? {
@@ -73,7 +72,11 @@ type SelectorValue<T, S extends string> = S extends `.${infer K}`
 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 Inequality<Args = unknown> = [
+  InequalityOp,
+  Selector<Args>,
+  number | bigint,
+]
 
 export type NegateOp = 'not'
 export type Negate<Args = unknown> = [NegateOp, Statement<Args>]

package/src/types/varsig.ts

@@ -11,12 +11,23 @@ export type VarsigEncoding = 'RAW' | 'DAG-CBOR'
 
 /**
  * Supported signature types
+ *
+ * RSA (`RS256`) is not supported.
  */
-export type VarsigAlgorithm = SignatureType
+export type VarsigAlgorithm = Exclude<SignatureType, 'RS256'>
 
 export interface VarsigOptions {
   enc: VarsigEncoding
   alg: VarsigAlgorithm
 }
 
+/**
+ * Options for varsig `encode`. Accepts any signer type so unsupported
+ * algorithms (e.g. `RS256`) fail at runtime with a clear error.
+ */
+export interface VarsigEncodeOptions {
+  enc: VarsigEncoding
+  alg: SignatureType
+}
+
 export type DecodeOutput = VarsigOptions

package/src/types.ts

@@ -19,13 +19,6 @@ export * from './types/policy'
 export * from './types/varsig'
 
 export type ResolveProof = (proof: CID) => Promise<Delegation>
-/**
- * Check whether a delegation CID is revoked.
- *
- * Called once for each CID the delegation could have been issued under
- * (up to 2 for ECDSA and 4 for EIP-191 signatures), since those signatures
- * can be re-encoded into another valid signature with a different CID.
- */
 export type IsRevoked = (cid: CID) => Promise<boolean>
 export type VerifierResolver = Resolver
 export type DidResolver = _DidResolver
@@ -123,14 +116,22 @@ export interface InvocationOptions extends DelegationValidateOptions {
    * Issued at time in seconds
    */
   iat?: number
-  nbf?: number
   nonce?: Uint8Array
   cause?: CID
+  /**
+   * Metadata, omitted from the payload when empty
+   */
   meta?: CborObject
 }
 
 export interface InvocationFromOptions extends DelegationValidateOptions {
   bytes: Uint8Array
+  /**
+   * The current time in seconds, used for the invocation's own `exp`, the time
+   * bounds of its proofs and `maxTtl`. Mostly used for testing.
+   * @default Math.floor(Date.now() / 1000)
+   */
+  now?: number
   audience?: VerifiableDID
   resolveProof: ResolveProof
   /**
@@ -156,7 +157,7 @@ export interface ReplayStore {
    * Atomically record `key` and resolve `true`, or resolve `false` if `key`
    * was already recorded and has not expired.
    *
-   * @param key - Replay key of the invocation, see {@link Invocation.replayKey}
+   * @param key - CID of the invocation, see {@link Invocation.cid}
    * @param expiration - Unix time in seconds after which the key can be forgotten, or `null` to keep it forever
    */
   checkAndSet(key: string, expiration: number | null): Promise<boolean>

package/src/utils.js

@@ -6,6 +6,7 @@ import { sha256 } from 'multiformats/hashes/sha2'
 import { z } from 'zod/v4'
 
 import * as Envelope from './envelope.js'
+import { parseSelector } from './policy.js'
 import * as varsig from './varsig.js'
 
 /**
@@ -52,19 +53,26 @@ export async function cid(envelope) {
 }
 
 /**
- * Replay key of a UCAN: the CID of its signature payload, the exact bytes the
- * signature covers.
+ * Assert that `bytes` is the canonical DAG-CBOR encoding of `envelope`.
  *
- * Unlike {@link cid}, it does not depend on the signature bytes, so a second
- * valid signature over the same payload (for example a malleated ECDSA
- * signature) gets the same key.
+ * {@link cid} hashes the re-encoded envelope, and the DAG-CBOR decoder accepts
+ * some non-canonical input (e.g. unsorted map keys or short floats). Without
+ * this check, different byte strings would share a CID.
  *
  * @param {import('./types.js').DecodedEnvelope<PayloadSpec>} envelope
+ * @param {Uint8Array} bytes
  */
-export async function replayKey(envelope) {
-  const hash = await sha256.digest(dagCbor.encode(signaturePayload(envelope)))
-
-  return CID.create(1, dagCbor.code, hash).toString()
+export function assertCanonical(envelope, bytes) {
+  const encoded = Envelope.encode({
+    signature: envelope.signature,
+    // @ts-expect-error
+    signaturePayload: signaturePayload(envelope),
+  })
+  if (!equals(encoded, bytes)) {
+    throw new TypeError(
+      'UCAN envelope is not canonical DAG-CBOR, re-encoding does not match the received bytes'
+    )
+  }
 }
 
 /**
@@ -94,9 +102,6 @@ export function isSigAndDidCompatible(did, sigType) {
     return true
   }
 
-  if (did.verifiableDid.type === 'RSA' && sigType === 'RS256') {
-    return true
-  }
   if (did.verifiableDid.type === 'secp256k1' && sigType === 'EIP191') {
     return true
   }
@@ -124,6 +129,21 @@ export function assertExpiration(exp, now = nowInSeconds()) {
   }
 }
 
+/**
+ * Validate an optional UCAN timestamp (e.g. `nbf` or `iat`): when present it
+ * must be an integer number of seconds within ±(2^53 − 1).
+ *
+ * @param {unknown} value
+ * @param {string} name - Field name used in the error message
+ */
+export function assertTimestamp(value, name) {
+  if (value !== undefined && !Number.isSafeInteger(value)) {
+    throw new TypeError(
+      `UCAN ${name} must be a safe integer. Received: ${value}`
+    )
+  }
+}
+
 /**
  * Validate the not before time of a UCAN
  *
@@ -131,7 +151,7 @@ export function assertExpiration(exp, now = nowInSeconds()) {
  * @param {number} [now]
  */
 export function assertNotBefore(nbf, now = nowInSeconds()) {
-  if (nbf && nbf > now) {
+  if (nbf !== undefined && nbf > now) {
     throw new Error('UCAN not valid yet')
   }
 }
@@ -173,6 +193,9 @@ export async function verifySignature(
       message: dagCbor.encode(signaturePayload(envelope)),
       did: issuer,
       type: envelope.alg,
+      // Accept only canonical signatures, such as low-S ECDSA, so each UCAN
+      // has one CID for replay and revocation checks
+      strict: true,
     })
 
     if (!isVerified) {
@@ -310,146 +333,15 @@ export function assertMeta(meta) {
   }
 }
 
-/**
- * ECDSA curve orders by signature algorithm, with the byte length of each
- * signature component.
- *
- * @type {Record<string, {n: bigint, size: number}>}
- */
-const ECDSA_CURVES = {
-  ES256: {
-    n: 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n,
-    size: 32,
-  },
-  ES384: {
-    n: 0xffffffffffffffffffffffffffffffffffffffffffffffffc7634d81f4372ddf581a0db248b0a77aecec196accc52973n,
-    size: 48,
-  },
-  ES512: {
-    n: 0x01fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffa51868783bf2f966b7fcc0148f709a5d03bb5c9b8899c47aebb6fb71e91386409n,
-    size: 66,
-  },
-  ES256K: {
-    n: 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n,
-    size: 32,
-  },
-  EIP191: {
-    n: 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n,
-    size: 32,
-  },
-}
-
-/**
- * @param {Uint8Array} bytes
- */
-function bytesToBigInt(bytes) {
-  let n = 0n
-  for (const b of bytes) n = (n << 8n) | BigInt(b)
-  return n
-}
-
-/**
- * @param {bigint} n
- * @param {number} size
- */
-function bigIntToBytes(n, size) {
-  const out = new Uint8Array(size)
-  for (let i = size - 1; i >= 0; i--) {
-    out[i] = Number(n & 0xffn)
-    n >>= 8n
-  }
-  return out
-}
-
-/**
- * Signatures a signer could have issued that verify the same as `signature`.
- *
- * ECDSA signatures are malleable: `(r, s)` and `(r, n - s)` are both valid.
- * EIP-191 signatures additionally carry a recovery byte `v` that wallets
- * return as 27/28 or 0/1. Verifiers also accept EIP-155 style `v >= 35`,
- * but no signer issues those for `personal_sign`, so they are not listed.
- *
- * The result always includes `signature` itself. Other algorithms (Ed25519,
- * RSA) have a single valid signature.
- *
- * @param {import('iso-signatures/types').SignatureType} alg
- * @param {Uint8Array} signature
- * @returns {Uint8Array[]}
- */
-export function equivalentSignatures(alg, signature) {
-  const curve = ECDSA_CURVES[alg]
-  if (!curve) {
-    return [signature]
-  }
-
-  const { n, size } = curve
-  const isEip191 = alg === 'EIP191'
-  if (signature.length !== size * 2 + (isEip191 ? 1 : 0)) {
-    return [signature]
-  }
-
-  const r = signature.subarray(0, size)
-  const s = bytesToBigInt(signature.subarray(size, size * 2))
-  if (s === 0n || s >= n) {
-    return [signature]
-  }
-  const sFlipped = bigIntToBytes(n - s, size)
-
-  if (!isEip191) {
-    return [signature, new Uint8Array([...r, ...sFlipped])]
-  }
-
-  const v = signature[size * 2]
-  /** @type {number} */
-  let parity
-  if (v === 0 || v === 27) parity = 0
-  else if (v === 1 || v === 28) parity = 1
-  else if (v >= 35) parity = v % 2 === 0 ? 1 : 0
-  else return [signature]
-
-  const sBytes = signature.subarray(size, size * 2)
-  const candidates = [
-    new Uint8Array([...r, ...sBytes, parity]),
-    new Uint8Array([...r, ...sBytes, parity + 27]),
-    new Uint8Array([...r, ...sFlipped, 1 - parity]),
-    new Uint8Array([...r, ...sFlipped, 28 - parity]),
-  ]
-  return [signature, ...candidates.filter((c) => !equals(c, signature))]
-}
-
-/**
- * CIDs of every envelope that verifies the same as `envelope`: one per
- * signature in {@link equivalentSignatures}, starting with the CID of
- * `envelope` itself.
- *
- * @param {import('./types.js').DecodedEnvelope<PayloadSpec>} envelope
- */
-export async function equivalentCids(envelope) {
-  return await Promise.all(
-    equivalentSignatures(envelope.alg, envelope.signature).map((signature) =>
-      cid({ ...envelope, signature })
-    )
-  )
-}
-
 /**
  * Assert that the input is not revoked.
  *
- * Checks every equivalent CID of the envelope (see {@link equivalentCids}),
- * so re-encoding a revoked UCAN with another valid signature does not get it
- * past a CID-based revocation list.
- *
- * @param {import('./types.js').DecodedEnvelope<PayloadSpec>} envelope
+ * @param {CID} cid
  * @param {(cid: CID) => Promise<boolean>} [isRevokedFn]
  */
-export async function assertNotRevoked(envelope, isRevokedFn) {
-  if (!isRevokedFn) {
-    return
-  }
-  for (const c of await equivalentCids(envelope)) {
-    if (await isRevokedFn(c)) {
-      throw new Error('UCAN revoked')
-    }
+export async function assertNotRevoked(cid, isRevokedFn) {
+  if (isRevokedFn && (await isRevokedFn(cid))) {
+    throw new Error('UCAN revoked')
   }
 }
 
@@ -488,17 +380,32 @@ export const cborValue =
   })
 export const cborObject = z.record(z.string(), cborValue)
 
-export const selector = z.union([
-  z.literal('.'),
-  z.templateLiteral([z.literal('.'), z.string()]),
-])
+/**
+ * Policy selector, validated with {@link parseSelector}.
+ *
+ * @see https://github.com/ucan-wg/delegation#selectors
+ */
+export const selector = z.string().superRefine((value, ctx) => {
+  try {
+    parseSelector(value)
+  } catch (error) {
+    ctx.addIssue({
+      code: 'custom',
+      message: /** @type {Error} */ (error).message,
+    })
+  }
+})
 
 /**
  * @typedef {z.infer<typeof selector>} Selector
  */
 
 /**
- * Statement
+ * Statement, as defined by the spec's IPLD schema. Every statement is a tuple
+ * of exact arity. Inequality values are integers or floats; large integers
+ * decode from dag-cbor as `bigint`.
+ *
+ * @see https://github.com/ucan-wg/delegation#policy
  */
 export const statement =
   /** @type {typeof z.lazy<z.ZodType<import('../src/types.js').Statement<unknown>>>} */ (
@@ -509,7 +416,7 @@ export const statement =
       z.tuple([
         z.union([z.literal('=='), z.literal('!=')]),
         selector,
-        z.unknown(),
+        cborValue,
       ]), // Equality
       z.tuple([
         z.union([
@@ -519,14 +426,14 @@ export const statement =
           z.literal('>='),
         ]),
         selector,
-        z.number(),
+        z.union([z.number(), z.bigint()]),
       ]), // Inequality
       z.tuple([z.literal('like'), selector, z.string()]), // Like
       z.tuple([z.literal('not'), statement]),
       z.tuple([z.literal('and'), z.array(statement)]),
       z.tuple([z.literal('or'), z.array(statement)]),
-      z.tuple([z.literal('all'), z.string(), statement]),
-      z.tuple([z.literal('any'), z.string(), statement]),
+      z.tuple([z.literal('all'), selector, statement]),
+      z.tuple([z.literal('any'), selector, statement]),
     ])
   })
 

package/src/varsig.js

@@ -19,7 +19,6 @@ export const CODE_ENCODING = /** @types  {const} */ {
  * @type {Record<number, string>}
  */
 export const SIG_PREFIX = /** @type {const} */ ({
-  0x12_05: 'RSA',
   0xed: 'EdDSA',
   0xec: 'ECDSA',
 })
@@ -37,8 +36,6 @@ const VARINT = {
   'DAG-CBOR': [113],
 
   /** Presets */
-  // rsa(2b)+SHA2-256(1b)+256(1b)
-  RS256: [133, 36, 18, 128, 2],
   // eddsa(2b)+edwards25519(2b)+SHA2-512(1b)
   Ed25519: [237, 1, 237, 1, 19],
   // ECDSA(2b) + p256(2b)   + SHA2-256(1b)
@@ -54,7 +51,7 @@ const VARINT = {
 }
 
 /**
- * @param {import('./types.js').VarsigOptions} options
+ * @param {import('./types.js').VarsigEncodeOptions} options
  */
 export function encode(options) {
   const enc = VARINT[options.enc]
@@ -62,7 +59,9 @@ export function encode(options) {
     throw new TypeError(`Unsupported encoding ${options.enc}`)
   }
 
-  const alg = VARINT[options.alg]
+  const alg = /** @type {Partial<Record<string, number[]>>} */ (VARINT)[
+    options.alg
+  ]
   if (!alg) {
     throw new TypeError(`Unsupported algorithm ${options.alg}`)
   }
@@ -95,7 +94,6 @@ function getPreset(bytes, presets) {
   throw new TypeError(`Unsupported preset ${bytes}`)
 }
 
-/**
 /**
  * Decode varsig header
  *
@@ -119,39 +117,44 @@ export function decode(buf) {
   }
   const [code] = varint.decode(buf, 2)
 
+  /** @type {import('./types.js').DecodeOutput} */
+  let output
   switch (SIG_PREFIX[code]) {
-    case 'RSA': {
-      return {
-        alg: getPreset(bytes.readBytes(5), ['RS256']),
-        enc: getEncoding(bytes.readBytes(1)),
-      }
-    }
     case 'EdDSA': {
-      return {
+      output = {
         alg: getPreset(bytes.readBytes(5), ['Ed25519']),
         enc: getEncoding(bytes.readBytes(1)),
       }
+      break
     }
     case 'ECDSA': {
       const isEIP191 = varint.decode(buf, 2 + 5)[0] === EIP191_ENCODING
-      if (isEIP191) {
-        return {
-          alg: getPreset(bytes.readBytes(8), ['EIP191']),
-          enc: getEncoding(bytes.readBytes(1)),
-        }
-      }
-
-      return {
-        alg: getPreset(bytes.readBytes(5), [
-          'ES256',
-          'ES256K',
-          'ES384',
-          'ES512',
-        ]),
-        enc: getEncoding(bytes.readBytes(1)),
-      }
+      output = isEIP191
+        ? {
+            alg: getPreset(bytes.readBytes(8), ['EIP191']),
+            enc: getEncoding(bytes.readBytes(1)),
+          }
+        : {
+            alg: getPreset(bytes.readBytes(5), [
+              'ES256',
+              'ES256K',
+              'ES384',
+              'ES512',
+            ]),
+            enc: getEncoding(bytes.readBytes(1)),
+          }
+      break
     }
     default:
       throw new TypeError(`Unsupported algorithm ${code}`)
   }
+
+  const trailing = buf.length - bytes.offset
+  if (trailing !== 0) {
+    throw new TypeError(
+      `Invalid varsig header ${trailing} trailing byte(s) after the payload encoding`
+    )
+  }
+
+  return output
 }