iso-ucan 1.0.0 → 3.0.0

package/readme.md

@@ -115,10 +115,11 @@ const invocation = await Invocation.from({
 })
 ```
 
-The store is keyed on `invocation.replayKey`, the CID of the signed payload.
-Do not deduplicate on `invocation.cid`: it also covers the signature, and
-some signature algorithms (such as ECDSA) accept more than one valid signature
-for the same payload.
+The store is keyed on `invocation.cid`. `iso-ucan` verifies signatures in
+strict mode, which accepts only the
+[canonical Varsig encoding](https://github.com/ChainAgnostic/varsig#canonical-signatures),
+for example low-S for ECDSA. An attacker can't re-encode an intercepted
+invocation under a different CID.
 
 `KVReplayStore` is atomic within one process only. When several processes or
 instances execute invocations, implement the `ReplayStore` interface on a
@@ -128,11 +129,58 @@ shared store with an atomic set-if-absent, such as Redis `SET NX` or SQL
 ## Revocation
 
 Pass `isRevoked` to `Delegation.from`, `Delegation#validate` or
-`Invocation.from` to reject revoked delegations by CID. Because ECDSA and
-EIP-191 signatures can be re-encoded into another valid signature, a revoked
-delegation can reappear under a different CID. `iso-ucan` therefore calls
-`isRevoked` with every CID the delegation could have been issued under (up to
-2 for ECDSA and 4 for EIP-191), and rejects it if any is revoked.
+`Invocation.from` to reject revoked delegations by CID. Strict verification
+rejects non-canonical signatures, so a revoked delegation can't come back under
+a different CID.
+
+### Migrate revocation lists from earlier versions
+
+Earlier versions accepted ECDSA (ES256, ES384, ES512) signatures with high S,
+and EIP-191 signatures with `v` of 0 or 1. If your revocation list holds the
+CID of such a delegation, anyone holding the delegation can convert it to the
+canonical encoding. The canonical CID is not in your list, so the revoked
+delegation passes `isRevoked`.
+
+To keep those revocations, add the canonical CID of each revoked delegation to
+your list. Compute it from the stored delegation bytes:
+
+```js
+import { Delegation } from 'iso-ucan/delegation'
+import * as Envelope from 'iso-ucan/envelope'
+import { normalizeS } from 'iso-signatures/signers/ecdsa.js'
+import { normalizeSignature } from 'iso-signatures/signers/eip191.js'
+
+const CURVES = { ES256: 'P-256', ES384: 'P-384', ES512: 'P-521' }
+
+/**
+ * @param {Uint8Array} bytes - Revoked delegation, as stored
+ * @param {import('iso-ucan/types').VerifierResolver} verifierResolver
+ */
+async function canonicalCid(bytes, verifierResolver) {
+  const envelope = Envelope.decode({ envelope: bytes })
+  let signature = envelope.signature
+  if (envelope.alg === 'EIP191') {
+    signature = normalizeSignature(signature)
+  } else if (envelope.alg in CURVES) {
+    signature = normalizeS(CURVES[envelope.alg], signature)
+  }
+
+  const canonical = Envelope.encode({
+    signature,
+    signaturePayload: Envelope.getSignaturePayload({
+      spec: envelope.spec,
+      version: envelope.version,
+      signatureType: envelope.alg,
+      payload: envelope.payload,
+    }),
+  })
+  const delegation = await Delegation.from({ bytes: canonical, verifierResolver })
+  return delegation.cid
+}
+```
+
+Ed25519 and ES256K signatures were already canonical, so their CIDs don't
+change.
 
 ## EIP-191 wallet signing
 

package/src/delegation.js

@@ -3,12 +3,15 @@ import { parse as didParse } from 'iso-did'
 import { randomBytes } from 'iso-web/crypto'
 import * as Envelope from './envelope.js'
 import {
+  assertCanonical,
   assertExpiration,
   assertIsValidCommand,
   assertMeta,
   assertNonce,
   assertNotBefore,
   assertNotRevoked,
+  assertPolicy,
+  assertTimestamp,
   cid,
   expOrTtl,
   verifySignature,
@@ -84,12 +87,13 @@ export class Delegation {
       )
     }
 
+    assertCanonical(envelope, bytes)
     assertStructure(envelope.payload, options.now)
 
     await verifySignature(envelope, verifierResolver, didResolveOptions)
 
     const _cid = await cid(envelope)
-    await assertNotRevoked(envelope, options.isRevoked)
+    await assertNotRevoked(_cid, options.isRevoked)
 
     return new Delegation(envelope, bytes, _cid)
   }
@@ -112,6 +116,7 @@ export class Delegation {
       )
     }
 
+    assertCanonical(envelope, bytes)
     assertStructure(envelope.payload, options.now)
     const _cid = await cid(envelope)
     return new Delegation(envelope, bytes, _cid)
@@ -146,7 +151,7 @@ export class Delegation {
 
     assertStructure(payload, options.now)
 
-    const { signature, signaturePayload } = await Envelope.sign({
+    const { alg, signature, signaturePayload } = await Envelope.sign({
       spec: 'dlg',
       signer: options.iss,
       payload,
@@ -156,7 +161,7 @@ export class Delegation {
 
     /** @type {import("./types.js").DecodedEnvelope<'dlg'>} */
     const envelope = {
-      alg: options.iss.signatureType,
+      alg,
       enc: 'DAG-CBOR',
       signature,
       payload,
@@ -182,7 +187,7 @@ export class Delegation {
       options.verifierResolver,
       options.didResolver
     )
-    await assertNotRevoked(this.envelope, options.isRevoked)
+    await assertNotRevoked(this.cid, options.isRevoked)
 
     return true
   }
@@ -232,9 +237,10 @@ function assertStructure(payload, now) {
 
   assertIsValidCommand(payload.cmd)
   assertExpiration(payload.exp, now)
+  assertTimestamp(payload.nbf, 'nbf')
   assertNonce(payload.nonce)
 
-  // assertPolicy(payload.pol)
+  assertPolicy(payload.pol)
 
   assertMeta(payload.meta)
 }

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
  *
@@ -110,6 +187,10 @@ export async function sign(options) {
   })
   const signature = await signer.sign(cbor.encode(signaturePayload))
   return {
+    // getSignaturePayload throws for algorithms varsig does not support
+    alg: /** @type {import('./types.js').VarsigAlgorithm} */ (
+      signer.signatureType
+    ),
     signature,
     signaturePayload,
   }
@@ -141,20 +222,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,17 +9,17 @@ import {
   assertIsValidCommand,
   assertMeta,
   assertNonce,
+  assertTimestamp,
   cid,
   commandCovers,
   expOrTtl,
+  isObject,
   nowInSeconds,
-  replayKey,
   verifySignature,
 } from './utils.js'
 
 /**
  * @import {Delegation} from './delegation.js'
- * @import {CID} from 'multiformats'
  */
 
 /**
@@ -35,32 +36,19 @@ export class Invocation {
    */
   cid
 
-  /**
-   * Key to deduplicate this invocation on: the CID of its signature payload.
-   *
-   * Use this instead of {@link Invocation.cid} to detect replays. The CID
-   * covers the signature bytes, and some signature algorithms (e.g. ECDSA)
-   * accept more than one valid signature for the same payload.
-   *
-   * @type {string}
-   */
-  replayKey
-
   /**
    *
    * @param {import("./types.js").DecodedEnvelope<'inv'>} envelope
    * @param {Uint8Array} bytes
    * @param {CID} cid
    * @param {Delegation[]} delegations
-   * @param {string} replayKey
    */
-  constructor(envelope, bytes, cid, delegations, replayKey) {
+  constructor(envelope, bytes, cid, delegations) {
     this.envelope = envelope
     this.payload = envelope.payload
     this.bytes = bytes
     this.cid = cid
     this.delegations = delegations
-    this.replayKey = replayKey
   }
 
   /**
@@ -87,7 +75,7 @@ export class Invocation {
       )
     }
 
-    assertStructure(envelope.payload)
+    assertStructure(envelope.payload, options.now)
     await verifySignature(
       envelope,
       options.verifierResolver,
@@ -101,6 +89,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
+        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)
       }
@@ -112,20 +107,20 @@ export class Invocation {
       assertMaxTtl(envelope.payload.exp, options.maxTtl, options.now)
     }
 
-    const _replayKey = await replayKey(envelope)
+    const _cid = await cid(envelope)
 
     // Must run last, so only fully validated invocations are recorded
     if (
       options.replayStore &&
-      !(await options.replayStore.checkAndSet(_replayKey, envelope.payload.exp))
+      !(await options.replayStore.checkAndSet(
+        _cid.toString(),
+        envelope.payload.exp
+      ))
     ) {
-      throw new Error(
-        `UCAN Invocation replay detected, already seen ${_replayKey}`
-      )
+      throw new Error(`UCAN Invocation replay detected, already seen ${_cid}`)
     }
 
-    const _cid = await cid(envelope)
-    return new Invocation(envelope, bytes, _cid, proofs, _replayKey)
+    return new Invocation(envelope, bytes, _cid, proofs)
   }
 
   /**
@@ -151,17 +146,15 @@ export class Invocation {
     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) {
@@ -171,7 +164,7 @@ export class Invocation {
       assertProofs(payload, options.prf)
     }
 
-    const { signature, signaturePayload } = await Envelope.sign({
+    const { alg, signature, signaturePayload } = await Envelope.sign({
       spec: 'inv',
       signer: options.iss,
       payload,
@@ -181,7 +174,7 @@ export class Invocation {
 
     /** @type {import("./types.js").DecodedEnvelope<'inv'>} */
     const envelope = {
-      alg: options.iss.signatureType,
+      alg,
       enc: 'DAG-CBOR',
       signature,
       payload,
@@ -189,13 +182,7 @@ export class Invocation {
       version: Envelope.VERSION,
     }
 
-    return new Invocation(
-      envelope,
-      bytes,
-      await cid(envelope),
-      options.prf,
-      await replayKey(envelope)
-    )
+    return new Invocation(envelope, bytes, await cid(envelope), options.prf)
   }
 }
 
@@ -219,8 +206,9 @@ 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)
 
@@ -237,8 +225,29 @@ function assertStructure(payload) {
   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')
+  }
 }
 
 /**