iso-ucan 0.5.2 → 2.0.0

package/src/envelope.js

@@ -3,12 +3,63 @@ import { isObject } from './utils.js'
 import * as varsig from './varsig.js'
 
 /**
- * @import { Envelope, PayloadTag, EnvelopeDecodeOptions, EnvelopeEncodeOptions, EnvelopeSignOptions, SignaturePayload, PayloadSpec, DecodedEnvelope, DelegationPayload, InvocationPayload, Payload} from './types.js'
- * @import { ByteView } from 'multiformats'
+ * @import { PayloadTag, EnvelopeDecodeOptions, EnvelopeEncodeOptions, EnvelopeSignOptions, SignaturePayload, PayloadSpec, DecodedEnvelope, DelegationPayload, InvocationPayload, Payload} from './types.js'
  */
 
-/** Version */
-export const VERSION = '1.0.0-rc.1'
+/**
+ * Payload tag version used for new tokens (`ucan/dlg@1.0.0`, `ucan/inv@1.0.0`)
+ *
+ * @see https://github.com/ucan-wg/delegation#type-tag
+ * @see https://github.com/ucan-wg/invocation#type-tag
+ */
+export const VERSION = '1.0.0'
+
+/**
+ * Payload tag versions accepted on decode.
+ *
+ * `1.0.0-rc.1` is still accepted so tokens issued by iso-ucan <= 1.0.0 keep
+ * verifying. New tokens are always encoded with {@link VERSION}.
+ *
+ * @type {readonly string[]}
+ */
+export const SUPPORTED_VERSIONS = Object.freeze([VERSION, '1.0.0-rc.1'])
+
+/**
+ * Payload specs
+ *
+ * @type {readonly PayloadSpec[]}
+ */
+export const SPECS = Object.freeze(/** @type {const} */ (['dlg', 'inv']))
+
+const PAYLOAD_TAG_REGEX = /^ucan\/([^@/]+)@(.+)$/
+
+/**
+ * Parse and validate a payload tag (`ucan/<spec>@<version>`)
+ *
+ * @param {string} tag
+ */
+export function parsePayloadTag(tag) {
+  const match = PAYLOAD_TAG_REGEX.exec(tag)
+  if (!match) {
+    throw new TypeError(
+      `Invalid payload tag "${tag}" expected "ucan/<spec>@<version>"`
+    )
+  }
+  const spec = /** @type {PayloadSpec} */ (match[1])
+  const version = match[2]
+  if (!SPECS.includes(spec)) {
+    throw new TypeError(
+      `Unsupported payload tag spec "${spec}" in "${tag}" expected one of: ${SPECS.join(', ')}`
+    )
+  }
+  if (!SUPPORTED_VERSIONS.includes(version)) {
+    throw new TypeError(
+      `Unsupported payload tag version "${version}" in "${tag}" expected one of: ${SUPPORTED_VERSIONS.join(', ')}`
+    )
+  }
+
+  return { tag: /** @type {PayloadTag} */ (tag), spec, version }
+}
 
 /**
  * Get the signature payload for a given payload
@@ -22,7 +73,7 @@ export const VERSION = '1.0.0-rc.1'
 export function getSignaturePayload(options) {
   const { spec, version, signatureType, payload } = options
 
-  const payloadTag = /** @type {PayloadTag} */ (
+  const { tag: payloadTag } = parsePayloadTag(
     `ucan/${spec}@${version ?? VERSION}`
   )
 
@@ -37,44 +88,70 @@ export function getSignaturePayload(options) {
 }
 
 /**
- * Decode a signature payload
+ * Validate a decoded signature payload (`{ h, "ucan/<spec>@<version>": payload }`)
  *
- * @param {Uint8Array} bytes
+ * @see https://github.com/ucan-wg/spec#envelope
+ * @param {unknown} sigPayload
  */
-export function decodeSignaturePayload(bytes) {
-  const decode = /** @type typeof cbor.decode<SignaturePayload> **/ (
-    cbor.decode
-  )
-  const decoded = decode(bytes)
-
-  if (!isObject(decoded)) {
+function parseSignaturePayload(sigPayload) {
+  if (!isObject(sigPayload)) {
     throw new TypeError(
-      `Invalid signature payload expected object got ${typeof decoded}`
+      `Invalid signature payload expected object got ${Array.isArray(sigPayload) ? 'array' : typeof sigPayload}`
     )
   }
-  if (!('h' in decoded)) {
+  const keys = Object.keys(sigPayload)
+  if (keys.length !== 2) {
+    throw new TypeError(
+      `Invalid signature payload expected 2 keys (h and payload tag) got ${keys.length}: ${keys.join(', ')}`
+    )
+  }
+  if (!keys.includes('h')) {
     throw new TypeError('Invalid signature payload missing h')
   }
-  const keys = Object.keys(decoded)
-  if (keys.length !== 2) {
+  const { tag, spec, version } = parsePayloadTag(
+    /** @type {string} */ (keys.find((key) => key !== 'h'))
+  )
+  // DAG-CBOR sorts map keys by length first, so `h` must be the first key.
+  if (keys[0] !== 'h') {
     throw new TypeError(
-      `Invalid signature payload expected 2 keys got ${keys.length}`
+      'Invalid signature payload keys are not in canonical DAG-CBOR order'
     )
   }
-  if (!keys[1].startsWith('ucan/dlg') && !keys[1].startsWith('ucan/inv')) {
-    throw new TypeError('Invalid signature payload missing payload')
+
+  const header = sigPayload.h
+  if (!(header instanceof Uint8Array)) {
+    throw new TypeError('Invalid signature payload h expected bytes')
+  }
+  const { alg, enc } = varsig.decode(header)
+  if (enc !== 'DAG-CBOR') {
+    throw new TypeError(
+      `Unsupported varsig payload encoding ${enc} expected DAG-CBOR`
+    )
+  }
+
+  const payload = sigPayload[tag]
+  if (!isObject(payload)) {
+    throw new TypeError(`Invalid signature payload ${tag} expected object`)
   }
 
-  const payloadTag = /** @type {PayloadTag} */ (keys[1])
-  const { alg, enc } = varsig.decode(decoded.h)
-  const payload = decoded[payloadTag]
   return {
     alg,
     enc,
-    payload,
+    spec,
+    version,
+    payload: /** @type {Payload} */ (/** @type {unknown} */ (payload)),
   }
 }
 
+/**
+ * Decode and validate a signature payload
+ *
+ * @param {Uint8Array} bytes
+ */
+export function decodeSignaturePayload(bytes) {
+  return parseSignaturePayload(cbor.decode(bytes))
+}
+
 /**
  * Check if a payload is an invocation payload
  *
@@ -141,20 +218,20 @@ export function encode(options) {
 export function decode(options) {
   const { envelope } = options
 
-  const decoded = /** @type typeof cbor.decode<Envelope> **/ (cbor.decode)(
-    /** @type {ByteView<Envelope>} */ (envelope)
-  )
+  const decoded = cbor.decode(envelope)
 
-  const [signature, sigPayload] = decoded
-  const [_h, payloadTag] = Object.keys(sigPayload)
-  const header = sigPayload.h
-  /** @type {DelegationPayload | InvocationPayload} */
-  const payload = sigPayload[/** @type {PayloadTag} */ (payloadTag)]
+  if (!Array.isArray(decoded) || decoded.length !== 2) {
+    throw new TypeError(
+      `Invalid envelope expected array of 2 elements [signature, signature payload] got ${Array.isArray(decoded) ? `array of ${decoded.length} elements` : typeof decoded}`
+    )
+  }
 
-  const [_ucan, specVersion] = payloadTag.split('/')
-  const [spec, version] = specVersion.split('@')
+  const [signature, sigPayload] = decoded
+  if (!(signature instanceof Uint8Array)) {
+    throw new TypeError('Invalid envelope signature expected bytes')
+  }
 
-  const { alg, enc } = varsig.decode(header)
+  const { alg, enc, spec, version, payload } = parseSignaturePayload(sigPayload)
 
   return {
     alg,

package/src/invocation.js

@@ -1,5 +1,6 @@
 import { parse as didParse } from 'iso-did'
 import { randomBytes } from 'iso-web/crypto'
+import { CID } from 'multiformats/cid'
 import * as Envelope from './envelope.js'
 import { validate } from './policy.js'
 import {
@@ -8,9 +9,11 @@ import {
   assertIsValidCommand,
   assertMeta,
   assertNonce,
+  assertTimestamp,
   cid,
   commandCovers,
   expOrTtl,
+  isObject,
   nowInSeconds,
   replayKey,
   verifySignature,
@@ -18,7 +21,6 @@ import {
 
 /**
  * @import {Delegation} from './delegation.js'
- * @import {CID} from 'multiformats'
  */
 
 /**
@@ -79,18 +81,15 @@ export class Invocation {
         `Invalid envelope type. Expected "inv" but got "${envelope.spec}"`
       )
     }
-    // Audience or subject must match receiver
-    if (
-      audience &&
-      envelope.payload.aud !== audience.did &&
-      envelope.payload.sub !== audience.did
-    ) {
+    // The executor is `aud` when present, otherwise `sub`
+    const executor = envelope.payload.aud ?? envelope.payload.sub
+    if (audience && executor !== audience.did) {
       throw new TypeError(
-        `UCAN Invocation audience or subject does not match receiver. Expected: ${audience.did} but got: ${envelope.payload.aud ?? envelope.payload.sub ?? 'null'}`
+        `UCAN Invocation audience does not match receiver. Expected: ${audience.did} but got: ${executor ?? 'null'}`
       )
     }
 
-    assertStructure(envelope.payload)
+    assertStructure(envelope.payload, options.now)
     await verifySignature(
       envelope,
       options.verifierResolver,
@@ -104,6 +103,13 @@ export class Invocation {
     if (iss.did !== envelope.payload.sub) {
       for (const proof of envelope.payload.prf) {
         const delegation = await options.resolveProof(proof)
+        // The signature covers the proof CIDs, so the resolved delegation
+        // must be exactly that one (not an ECDSA-equivalent re-encoding)
+        if (!delegation.cid.equals(proof)) {
+          throw new Error(
+            `UCAN Invocation proof CID mismatch, expected ${proof} but resolver returned ${delegation.cid}`
+          )
+        }
         await delegation.validate(options)
         proofs.push(delegation)
       }
@@ -140,7 +146,6 @@ export class Invocation {
     /** @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,
@@ -148,20 +153,22 @@ export class Invocation {
       args: options.args,
       prf: options.prf.map((p) => p.cid),
     }
+    // `aud` MUST be omitted when the executor is the subject
+    if (options.aud && options.aud !== options.sub) {
+      payload.aud = options.aud
+    }
     if (options.cause) {
       payload.cause = options.cause
     }
-    if (options.meta) {
+    // `meta` MUST be omitted when empty
+    if (options.meta && Object.keys(options.meta).length > 0) {
       payload.meta = options.meta
     }
-    if (options.iat) {
+    if (options.iat !== undefined) {
       payload.iat = options.iat
     }
-    if (options.nbf) {
-      payload.nbf = options.nbf
-    }
 
-    assertStructure(payload)
+    assertStructure(payload, options.now)
 
     if (options.iss.did !== options.sub) {
       for (const proof of options.prf) {
@@ -219,20 +226,48 @@ function assertMaxTtl(exp, maxTtl, now = nowInSeconds()) {
 
 /**
  * @param {import('./types.js').InvocationPayload} payload
+ * @param {number} [now]
  */
-function assertStructure(payload) {
+function assertStructure(payload, now) {
   didParse(payload.iss)
   didParse(payload.sub)
 
   if (payload.aud) {
     didParse(payload.aud)
+    // Spec: `aud` MUST be omitted when the executor is the subject
+    if (payload.aud === payload.sub) {
+      throw new TypeError(
+        'UCAN Invocation audience must be omitted when it equals the subject'
+      )
+    }
   }
 
   assertIsValidCommand(payload.cmd)
   assertArgs(payload.args)
   assertMeta(payload.meta)
+  // Spec: `meta` MUST be a non-empty map, and omitted when empty
+  if (
+    payload.meta !== undefined &&
+    (!isObject(payload.meta) || Object.keys(payload.meta).length === 0)
+  ) {
+    throw new TypeError(
+      'UCAN Invocation meta must be a non-empty map, omit it when empty'
+    )
+  }
   assertNonce(payload.nonce)
-  assertExpiration(payload.exp)
+  assertExpiration(payload.exp, now)
+  assertTimestamp(payload.iat, 'iat')
+  // `nbf` is a delegation field, an invoker could wrongly expect it to delay execution
+  if ('nbf' in payload) {
+    throw new TypeError('UCAN Invocation must not have nbf')
+  }
+  // `prf` is required, even when empty for a self-issued invocation
+  if (
+    !Array.isArray(payload.prf) ||
+    !payload.prf.every((proof) => CID.asCID(proof) !== null)
+  ) {
+    throw new TypeError('UCAN Invocation prf must be an array of CIDs')
+  }
 }
 
 /**