iso-ucan 0.5.2 → 2.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.ts

@@ -123,14 +123,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
   /**

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'
 
 /**
@@ -51,6 +52,29 @@ export async function cid(envelope) {
   return CID.create(1, dagCbor.code, hash)
 }
 
+/**
+ * Assert that `bytes` is the canonical DAG-CBOR encoding of `envelope`.
+ *
+ * {@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 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'
+    )
+  }
+}
+
 /**
  * Replay key of a UCAN: the CID of its signature payload, the exact bytes the
  * signature covers.
@@ -124,6 +148,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 +170,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')
   }
 }
@@ -488,17 +527,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 +563,7 @@ export const statement =
       z.tuple([
         z.union([z.literal('=='), z.literal('!=')]),
         selector,
-        z.unknown(),
+        cborValue,
       ]), // Equality
       z.tuple([
         z.union([
@@ -519,14 +573,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

@@ -95,7 +95,6 @@ function getPreset(bytes, presets) {
   throw new TypeError(`Unsupported preset ${bytes}`)
 }
 
-/**
 /**
  * Decode varsig header
  *
@@ -119,39 +118,51 @@ export function decode(buf) {
   }
   const [code] = varint.decode(buf, 2)
 
+  /** @type {import('./types.js').DecodeOutput} */
+  let output
   switch (SIG_PREFIX[code]) {
     case 'RSA': {
-      return {
+      output = {
         alg: getPreset(bytes.readBytes(5), ['RS256']),
         enc: getEncoding(bytes.readBytes(1)),
       }
+      break
     }
     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
 }