@did-btcr2/method 0.62.0 → 0.64.0

package/src/core/updater.ts

@@ -1,11 +1,12 @@
 import type { BitcoinConnection } from '@did-btcr2/bitcoin';
 import type { PatchOperation } from '@did-btcr2/common';
-import { canonicalHash, INVALID_DID_UPDATE, JSONPatch, UpdateError } from '@did-btcr2/common';
+import { canonicalHash, canonicalize, INVALID_DID_UPDATE, JSONPatch, UpdateError } from '@did-btcr2/common';
 import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import type { Signer } from '@did-btcr2/keypair';
 import type { Btcr2DataIntegrityConfig, SignedBTCR2Update, UnsignedBTCR2Update } from './btcr2-update.js';
 import { BTCR2_UPDATE_CONTEXT } from './btcr2-update.js';
 import { DidDocument, type Btcr2DidDocument, type DidVerificationMethod } from '../utils/did-document.js';
+import { errorCause } from '../utils/error-cause.js';
 import type { BroadcastResult } from './beacon/beacon.js';
 import type { CASBroadcastOptions } from './beacon/cas-beacon.js';
 import { BeaconFactory } from './beacon/factory.js';
@@ -224,7 +225,19 @@ export class Updater {
       sourceHash      : canonicalHash(sourceDocument),
     };
 
-    const targetDocument = JSONPatch.apply(sourceDocument, patches);
+    // Spec "Construct BTCR2 Unsigned Update": apply jsonPatch strictly. The first operation
+    // that fails, including a failed test, fails the whole patch. A patch that a lenient
+    // library applies with no effect is refused here, before it is signed and announced: a
+    // conformant resolver would reject the announced update.
+    let targetDocument: Record<string, any>;
+    try {
+      targetDocument = JSONPatch.apply(sourceDocument, patches, { strict: true });
+    } catch(error) {
+      throw new UpdateError(
+        `Invalid patch: ${errorCause(error).message}`,
+        INVALID_DID_UPDATE, { cause: errorCause(error) }
+      );
+    }
 
     // Spec (operations/update.md): "An INVALID_DID_UPDATE error MUST be raised if
     // didTargetDocument.id is not equal to didSourceDocument.id." `DidDocument.isValid`
@@ -327,7 +340,32 @@ export class Updater {
     };
 
     const diproof = multikey.toCryptosuite().toDataIntegrityProof();
-    return diproof.addProof(unsignedUpdate, config);
+    const signedUpdate = diproof.addProof(unsignedUpdate, config) as SignedBTCR2Update;
+
+    // Spec "Construct BTCR2 Signed Update": verify update.proof before the announcement,
+    // with the public key that the verification method publishes, not the signer's key. A
+    // signer that returns a wrong signature for the right key passes the key comparison
+    // above. An announced update with an invalid proof permanently invalidates the DID, so
+    // the failure surfaces here, before the state machine asks for funding.
+    let verified: boolean;
+    try {
+      const verifier = SchnorrMultikey.fromVerificationMethod({ ...verificationMethod, id: absoluteMethodId });
+      verified = verifier.toCryptosuite().toDataIntegrityProof()
+        .verifyProof(canonicalize(signedUpdate), 'capabilityInvocation').verified;
+    } catch(error) {
+      throw new UpdateError(
+        `Invalid update: the proof does not verify with the public key of "${verificationMethod.id}": `
+        + errorCause(error).message,
+        INVALID_DID_UPDATE, { verificationMethodId: verificationMethod.id, cause: errorCause(error) }
+      );
+    }
+    if(!verified) {
+      throw new UpdateError(
+        `Invalid update: the proof does not verify with the public key of "${verificationMethod.id}".`,
+        INVALID_DID_UPDATE, { verificationMethodId: verificationMethod.id }
+      );
+    }
+    return signedUpdate;
   }
 
   /**

package/src/did-btcr2.ts

@@ -18,6 +18,7 @@ import {
   DidErrorCode
 } from '@web5/dids';
 import type { BeaconService } from './core/beacon/interfaces.js';
+import { DEACTIVATION_PATCH } from './core/btcr2-update.js';
 import { Identifier } from './core/identifier.js';
 import type { ResolutionOptions } from './core/interfaces.js';
 import { Resolver } from './core/resolver.js';
@@ -155,9 +156,11 @@ export class DidBtcr2 implements DidMethod {
    * @param {string} params.verificationMethodId The verification method ID to sign with.
    * @param {string} params.beaconId The beacon service ID to broadcast through.
    * @returns {Updater} A sans-I/O state machine for driving the update.
-   * @throws {UpdateError} If the verification method is not authorized, not found,
-   *   not of type `Multikey`, or does not have a `zQ3s` publicKeyMultibase prefix.
-   *   Also throws if the beacon service is not found.
+   * @throws {UpdateError} `INVALID_DID_UPDATE` if `sourceVersionId` is not an integer of at
+   *   least 1, if no entry of `capabilityInvocation` identifies the verification method, if a
+   *   reference entry names no member of `verificationMethod`, or if the beacon service is not
+   *   found. `INVALID_DID_DOCUMENT` if the method is not of type `Multikey` or does not have a
+   *   `zQ3s` publicKeyMultibase prefix.
    */
   static update({
     sourceDocument,
@@ -172,30 +175,37 @@ export class DidBtcr2 implements DidMethod {
     verificationMethodId: string;
     beaconId: string;
   }): Updater {
-    // Validate that the verificationMethodId is authorized for capabilityInvocation.
-    // Both sides are resolved to absolute DID URLs first, so the caller's spelling of the
-    // reference and the document's spelling of the entry may differ: either is legal per
-    // DID Core. This is the same rule the read path applies to an update's proof, so an
-    // update this factory authorizes is one the resolver will also accept.
-    const authorizedMethodId = Appendix.relationshipMethodId(verificationMethodId, sourceDocument.id);
-    const authorized = authorizedMethodId !== undefined && sourceDocument.capabilityInvocation?.some(
-      entry => Appendix.relationshipMethodId(entry, sourceDocument.id) === authorizedMethodId
-    );
-    if(!authorized) {
+    // The version of the source document is a positive integer: versionId starts at 1, and
+    // targetVersionId is sourceVersionId + 1. Without the guard, Number(undefined) + 1 is
+    // NaN, and the update carries no usable version.
+    if(!Number.isInteger(sourceVersionId) || sourceVersionId < 1) {
       throw new UpdateError(
-        'Invalid verificationMethodId: not authorized for capabilityInvocation',
-        INVALID_DID_DOCUMENT, sourceDocument
+        `Invalid sourceVersionId: expected an integer of at least 1, got ${String(sourceVersionId)}.`,
+        INVALID_DID_UPDATE, { sourceVersionId }
       );
     }
 
-    // Get the verification method to be used for signing the update
-    const verificationMethod = this.getSigningMethod(sourceDocument, verificationMethodId);
+    // Spec "Construct BTCR2 Signed Update": an entry of capabilityInvocation must identify
+    // the verificationMethodId, in the reference form or the embedded form. Both sides are
+    // resolved to absolute DID URLs first, so the caller's spelling of the reference and the
+    // document's spelling of the entry may differ: either is legal per DID Core. This is the
+    // same rule the read path applies to an update's proof, so an update this factory
+    // authorizes is one the resolver will also accept.
+    const entry = Appendix.capabilityInvocationEntry(sourceDocument, verificationMethodId);
+    if(entry === undefined) {
+      throw new UpdateError(
+        'Invalid verificationMethodId: not authorized for capabilityInvocation',
+        INVALID_DID_UPDATE, { verificationMethodId, capabilityInvocation: sourceDocument.capabilityInvocation }
+      );
+    }
 
-    // Validate the verificationMethod exists in the sourceDocument
+    // The verification method is the embedded object of the entry, or the member of
+    // verificationMethod[] that a reference entry names.
+    const verificationMethod = Appendix.verificationMethodOfEntry(sourceDocument, entry);
     if(!verificationMethod) {
       throw new UpdateError(
-        'Invalid verificationMethod: not found in source document',
-        INVALID_DID_DOCUMENT, { sourceDocument, verificationMethodId }
+        'Invalid verificationMethodId: not found in source document',
+        INVALID_DID_UPDATE, { verificationMethodId }
       );
     }
 
@@ -233,16 +243,50 @@ export class DidBtcr2 implements DidMethod {
       );
     }
 
-    // Return a sans-I/O state machine the caller will drive
+    // Return a sans-I/O state machine the caller will drive. The prefix check above proves
+    // that the method carries a publicKeyMultibase, which the btcr2 method type requires.
     return new Updater({
       sourceDocument,
       patches,
       sourceVersionId,
-      verificationMethod,
+      verificationMethod : verificationMethod as DidVerificationMethod,
       beaconService,
     });
   }
 
+  /**
+   * Entry point for section {@link https://dcdpr.github.io/did-btcr2/operations/deactivate.html | 7.4 Deactivate}.
+   *
+   * Deactivate is the Update operation with the predetermined patch {@link DEACTIVATION_PATCH}:
+   * it adds the `deactivated` property with the value `true`. The factory returns the
+   * {@link Updater} that {@link DidBtcr2.update} returns for that patch, and the caller drives
+   * it in the same way. Resolution stops at the deactivation for good. The factory does not
+   * refuse a source document that is deactivated already; the api does (ADR 100).
+   *
+   * @param params Deactivation parameters: the parameters of {@link DidBtcr2.update} without `patches`.
+   * @returns {Updater} A sans-I/O state machine for driving the deactivation.
+   * @throws {UpdateError} As {@link DidBtcr2.update}.
+   */
+  static deactivate({
+    sourceDocument,
+    sourceVersionId,
+    verificationMethodId,
+    beaconId,
+  }: {
+    sourceDocument: Btcr2DidDocument;
+    sourceVersionId: number;
+    verificationMethodId: string;
+    beaconId: string;
+  }): Updater {
+    return this.update({
+      sourceDocument,
+      patches : [{ ...DEACTIVATION_PATCH }],
+      sourceVersionId,
+      verificationMethodId,
+      beaconId,
+    });
+  }
+
   /**
    * Given the W3C DID Document of a `did:btcr2` identifier, return the signing verification method that will be used
    * for signing messages and credentials. If given, the `methodId` parameter is used to select the
@@ -272,9 +316,10 @@ export class DidBtcr2 implements DidMethod {
 
     // An unusable target matches nothing: without this guard it compares equal to every
     // method whose own id is unusable, and the document's first malformed method is
-    // returned as the signing method.
-    const verificationMethod = targetId === undefined ? undefined : didDocument.verificationMethod?.find(
-      (vm: DidVerificationMethod) => Appendix.absoluteDidUrl(vm.id, didDocument.id) === targetId
+    // returned as the signing method. The search covers verificationMethod[] first, then the
+    // methods that a verification relationship embeds.
+    const verificationMethod = targetId === undefined ? undefined : Appendix.getVerificationMethods(didDocument).find(
+      vm => Appendix.absoluteDidUrl(vm.id, didDocument.id) === targetId
     );
 
     // If no verification method is found, throw an error

package/src/utils/appendix.ts

@@ -60,6 +60,51 @@ export class Appendix {
     return Appendix.absoluteDidUrl(id, did);
   }
 
+  /**
+   * Finds the entry of `document.capabilityInvocation` that identifies `methodId`. A
+   * reference entry identifies it when the two DID URLs are equal. An embedded verification
+   * method object identifies it when its `id` is equal. Both spellings of a DID URL compare
+   * equal, as in {@link relationshipMethodId}. This is the lookup of the specification steps
+   * "Check `update.proof`" (the read path) and "Construct BTCR2 Signed Update" (the write
+   * path); the caller raises `INVALID_DID_UPDATE` when no entry identifies the method.
+   *
+   * @param {DidDocument} document The DID document.
+   * @param {unknown} methodId The verification method id, absolute or relative. A non-string yields `undefined`.
+   * @returns {string | DidVerificationMethod | undefined} The entry, or `undefined` if no entry identifies the id.
+   */
+  public static capabilityInvocationEntry(
+    document: DidDocument,
+    methodId: unknown
+  ): string | DidVerificationMethod | undefined {
+    const targetId = Appendix.relationshipMethodId(methodId, document.id);
+    if (targetId === undefined) return undefined;
+    return document.capabilityInvocation?.find(
+      entry => Appendix.relationshipMethodId(entry, document.id) === targetId
+    );
+  }
+
+  /**
+   * Returns the verification method that a relationship entry denotes: the object itself
+   * when the entry embeds the method, else the member of `document.verificationMethod` whose
+   * `id` equals the reference. Both spellings of a DID URL compare equal. The caller raises
+   * `INVALID_DID_UPDATE` when a reference names no member.
+   *
+   * @param {DidDocument} document The DID document.
+   * @param {string | DidVerificationMethod} entry The relationship entry: a reference, or an embedded method.
+   * @returns {DidVerificationMethod | undefined} The method, or `undefined` if a reference names no member.
+   */
+  public static verificationMethodOfEntry(
+    document: DidDocument,
+    entry: string | DidVerificationMethod
+  ): DidVerificationMethod | undefined {
+    if (Appendix.isDidVerificationMethod(entry)) return entry;
+    const targetId = Appendix.absoluteDidUrl(entry, document.id);
+    if (targetId === undefined) return undefined;
+    return document.verificationMethod?.find(
+      method => Appendix.absoluteDidUrl(method?.id, document.id) === targetId
+    );
+  }
+
   /**
    * Validates that the given object is a DidVerificationMethod
    * @param {unknown} obj The object to validate
@@ -194,13 +239,14 @@ export class Appendix {
     const rootCapability = {} as RootCapability;
 
     // 2. Set components to the result of capabilityId.split(":").
-    const [urn, zcap, root, did] = capabilityId.split(':') ?? [];
+    const components = capabilityId.split(':');
 
     // 3. Validate components:
     //    1. Assert length of components is 4.
-    if ([urn, zcap, root, did].length !== 4) {
+    if (components.length !== 4) {
       throw new DidError(DidErrorCode.InvalidDid, `Invalid capabilityId: ${capabilityId}`);
     }
+    const [urn, zcap, root, did] = components;
 
     //    2. components[0] == urn.
     if (!urn || urn !== 'urn') {

package/src/utils/error-cause.ts

@@ -0,0 +1,23 @@
+import { DidMethodError } from '@did-btcr2/common';
+
+/** The type and the message of an inner error, carried as `data.cause` by a wrapping error. */
+export interface ErrorCause {
+  /** The `type` of a typed error, or the `name` of a plain `Error`. */
+  type: string;
+
+  /** The message of the inner error. */
+  message: string;
+}
+
+/**
+ * Describe an inner error for the `data.cause` of a wrapping typed error. The update paths
+ * raise `INVALID_DID_UPDATE` for every failure that the specification names; the inner error
+ * of the cryptosuite, the multikey, the hash decoder, or the common package rides along here.
+ * @param {unknown} error The inner error.
+ * @returns {ErrorCause} The type and the message of the inner error.
+ */
+export function errorCause(error: unknown): ErrorCause {
+  if(error instanceof DidMethodError) return { type: error.type, message: error.message };
+  if(error instanceof Error) return { type: error.name, message: error.message };
+  return { type: 'unknown', message: String(error) };
+}