@did-btcr2/method 0.59.0 → 0.60.0

package/src/core/identifier.ts

@@ -1,8 +1,19 @@
 import type { Bytes, DocumentBytes, KeyBytes, SchnorrKeyPairObject } from '@did-btcr2/common';
-import { BitcoinNetworkNames, IdentifierError, IdentifierTypes, INVALID_DID, METHOD_NOT_SUPPORTED } from '@did-btcr2/common';
+import {
+  BitcoinNetworkNames,
+  canonicalHashBytes,
+  IdentifierError,
+  IdentifierTypes,
+  INVALID_DID,
+  METHOD_NOT_SUPPORTED
+} from '@did-btcr2/common';
 import { CompressedSecp256k1PublicKey, SchnorrKeyPair } from '@did-btcr2/keypair';
-import { bech32m } from '@scure/base';
+import { equalBytes } from '@noble/curves/utils.js';
+import { bech32m, hex } from '@scure/base';
 import type { DidCreateOptions } from '../did-btcr2.js';
+// did-document.js imports this module. Both modules use the other only inside a
+// method body, never at module evaluation, so the cycle is safe in ESM and CJS.
+import { GenesisDocument, ID_PLACEHOLDER_VALUE } from '../utils/did-document.js';
 
 /**
  * Components of a did:btcr2 identifier.
@@ -28,6 +39,69 @@ export interface IdentifierComponents {
     network: string;
     genesisBytes: Bytes;
 }
+
+/**
+ * The name of one check that {@link Identifier.validate} runs. The names are in run order.
+ * @typedef {string} IdentifierCheckName
+ */
+export type IdentifierCheckName =
+  | 'prefix'
+  | 'lowercase'
+  | 'bech32m'
+  | 'version'
+  | 'network'
+  | 'genesisBytes'
+  | 'roundTrip'
+  | 'genesisBytesMatch'
+  | 'genesisDocument';
+
+/**
+ * The result of one check that {@link Identifier.validate} ran.
+ * @interface IdentifierCheck
+ * @property {IdentifierCheckName} name The name of the check.
+ * @property {boolean} ok True if the check passed.
+ * @property {string} [detail] What the check found.
+ */
+export interface IdentifierCheck {
+    name: IdentifierCheckName;
+    ok: boolean;
+    detail?: string;
+}
+
+/**
+ * Options for {@link Identifier.validate}.
+ * @interface IdentifierValidateOptions
+ * @property {Bytes} [genesisBytes] The genesis bytes that the identifier must encode: the 33-byte
+ *   compressed public key of a KEY identifier, or the 32-byte genesis document hash of an EXTERNAL
+ *   identifier. If present, the report includes the `genesisBytesMatch` check.
+ * @property {object} [genesisDocument] The genesis document of an EXTERNAL identifier.
+ *   If present, the report includes the `genesisDocument` check.
+ */
+export interface IdentifierValidateOptions {
+    genesisBytes?: Bytes;
+    genesisDocument?: object;
+}
+
+/**
+ * The report that {@link Identifier.validate} returns.
+ * @interface IdentifierReport
+ * @property {string} did The identifier that was verified.
+ * @property {boolean} valid True if every check passed.
+ * @property {IdentifierTypes} [idType] The identifier type, known after the `bech32m` check.
+ * @property {string} [network] The network name, known after the `network` check.
+ * @property {Array<IdentifierCheck>} checks The checks that ran, in run order. The run stops at the first failed check.
+ */
+export interface IdentifierReport {
+    did: string;
+    valid: boolean;
+    idType?: IdentifierTypes;
+    network?: string;
+    checks: Array<IdentifierCheck>;
+}
+
+/** The prefix of every did:btcr2 identifier. */
+const DID_PREFIX = 'did:btcr2:';
+
 /**
  * Implements {@link https://dcdpr.github.io/did-btcr2/#syntax | 3 Syntax}.
  * A did:btcr2 DID consists of a did:btcr2 prefix, followed by an id-bech32 value, which is a Bech32m encoding of:
@@ -106,7 +180,7 @@ export class Identifier {
     // byte, then append genesisBytes. Bech32m-encode the result.
     const firstByte = ((version - 1) << 4) | networkValue;
     const dataBytes = new Uint8Array([firstByte, ...genesisBytes]);
-    return `did:btcr2:${bech32m.encodeFromBytes(hrp, dataBytes)}`;
+    return `${DID_PREFIX}${bech32m.encodeFromBytes(hrp, dataBytes)}`;
   }
 
   /**
@@ -143,23 +217,29 @@ export class Identifier {
       throw new IdentifierError(`Invalid method-specific id: ${identifier}`, INVALID_DID, { identifier });
     }
 
-    // 6. Bech32m-decode the id into its hrp and dataBytes.
+    // 6. The method-specific id MUST be lowercase. A Bech32m decoder accepts an all-uppercase
+    //    string, so this check runs before the Bech32m step.
+    if (encoded !== encoded.toLowerCase()) {
+      throw new IdentifierError(`Invalid method-specific id (must be lowercase): ${identifier}`, INVALID_DID, { identifier });
+    }
+
+    // 7. Bech32m-decode the id into its hrp and dataBytes.
     const { prefix: hrp, bytes: dataBytes } = bech32m.decodeToBytes(encoded);
 
-    // 7. The hrp MUST be "k" (KEY) or "x" (EXTERNAL).
+    // 8. The hrp MUST be "k" (KEY) or "x" (EXTERNAL).
     if (!['x', 'k'].includes(hrp)) {
       throw new IdentifierError(`Invalid hrp: ${hrp}`, INVALID_DID, { identifier });
     }
 
-    // 8. There MUST be at least one byte to read btcr2_version and network_value from.
+    // 9. There MUST be at least one byte to read btcr2_version and network_value from.
     if (!dataBytes || dataBytes.length < 1) {
       throw new IdentifierError(`Failed to decode id: ${encoded}`, INVALID_DID, { identifier });
     }
 
-    // 9. Map hrp to idType.
+    // 10. Map hrp to idType.
     const idType = hrp === 'k' ? 'KEY' : 'EXTERNAL';
 
-    // 10. btcr2_version is the high nibble of the first byte and MUST be 0, which is version_number 1.
+    // 11. btcr2_version is the high nibble of the first byte and MUST be 0, which is version_number 1.
     //     The version-extension scheme (a leading nibble of 0xF chaining into further bytes) is reserved
     //     and not valid under v1, so any non-zero high nibble (0x1 through 0xF) is a malformed or forged
     //     identifier and is rejected here. Reading a single flat nibble (rather than looping on 0xF) is
@@ -171,23 +251,20 @@ export class Identifier {
     }
     const version = 1;
 
-    // 11. network_value is the low nibble of the first byte. 0-5 map to named networks; 12-14 are custom
-    //     networks (returned as the numeric values 1-3); 6-11 and 15 are reserved/out-of-range and rejected.
+    // 12. network_value is the low nibble of the first byte. 0-5 map to named networks. 6-11 are
+    //     reserved. 12-15 are custom networks; this implementation supports no custom network, so the
+    //     decoder rejects them, as the specification recommends (ADR 107).
     const networkValue = dataBytes[0] & 0x0F;
-    const networkName = BitcoinNetworkNames[networkValue] as string | undefined;
-    let network: string | number;
-    if (typeof networkName === 'string') {
-      network = networkName;
-    } else if (networkValue >= 12 && networkValue <= 14) {
-      network = networkValue - 11;
-    } else {
-      throw new IdentifierError(`Invalid network: ${networkValue}`, INVALID_DID, { identifier });
+    const network = BitcoinNetworkNames[networkValue] as string | undefined;
+    if (typeof network !== 'string') {
+      const reason = networkValue >= 12 ? 'custom network not supported' : 'reserved';
+      throw new IdentifierError(`Invalid network (${reason}): ${networkValue}`, INVALID_DID, { identifier });
     }
 
-    // 12. genesisBytes is everything after the first byte.
+    // 13. genesisBytes is everything after the first byte.
     const genesisBytes = dataBytes.slice(1);
 
-    // 13. genesisBytes MUST match the identifier type: a valid compressed secp256k1 public key for KEY,
+    // 14. genesisBytes MUST match the identifier type: a valid compressed secp256k1 public key for KEY,
     //     or a 32-byte hash for EXTERNAL.
     if (idType === 'KEY') {
       try {
@@ -199,10 +276,178 @@ export class Identifier {
       throw new IdentifierError(`Invalid genesisBytes: ${genesisBytes}`, INVALID_DID, { identifier });
     }
 
-    // 14. Return idType, hrp, version, network, and genesisBytes.
+    // 15. Return idType, hrp, version, network, and genesisBytes.
     return { idType, hrp, version, network, genesisBytes } as DidComponents;
   }
 
+  /**
+   * Validates that a did:btcr2 identifier conforms to
+   * {@link https://dcdpr.github.io/did-btcr2/#didbtcr2-identifier-decoding | 3.3 did:btcr2 Identifier Decoding}
+   * and returns a report of the checks. The method does not throw on an invalid identifier.
+   *
+   * The checks run in this order: `prefix`, `lowercase`, `bech32m`, `version`, `network`,
+   * `genesisBytes`, `roundTrip`, `genesisBytesMatch`, and `genesisDocument`. The run stops at the
+   * first failed check. The `network` check accepts a named network only: a reserved value (6 to
+   * 11) and a custom value (12 to 15) fail, because this implementation supports no custom network.
+   * The `genesisBytesMatch` check runs only if `options.genesisBytes` is present: the supplied bytes
+   * must equal the genesis bytes of the identifier, for a KEY or an EXTERNAL identifier. The
+   * `genesisDocument` check runs only if `options.genesisDocument` is present. For an EXTERNAL
+   * identifier it confirms that the document is a valid Genesis Document and that its canonical
+   * SHA-256 hash equals the genesis bytes. For a KEY identifier it fails.
+   *
+   * @param {string} identifier The did:btcr2 identifier to validate.
+   * @param {IdentifierValidateOptions} [options] The validation options.
+   * @returns {IdentifierReport} The report. See {@link IdentifierReport} for details.
+   */
+  static validate(identifier: string, options: IdentifierValidateOptions = {}): IdentifierReport {
+    const checks: Array<IdentifierCheck> = [];
+    const pass = (name: IdentifierCheckName, detail?: string): void => {
+      checks.push(detail === undefined ? { name, ok: true } : { name, ok: true, detail });
+    };
+    const fail = (name: IdentifierCheckName, detail: string, partial: Partial<IdentifierReport> = {}): IdentifierReport => {
+      checks.push({ name, ok: false, detail });
+      return { did: identifier, valid: false, ...partial, checks };
+    };
+
+    // prefix: the string is "did:btcr2:" followed by a non-empty method-specific id.
+    if (typeof identifier !== 'string') {
+      return fail('prefix', 'The identifier is not a string.');
+    }
+    const parts = identifier.split(':');
+    if (parts.length !== 3 || parts[0] !== 'did' || parts[1] !== 'btcr2') {
+      return fail('prefix', `The identifier must be "${DID_PREFIX}" followed by the method-specific id.`);
+    }
+    const encoded = parts[2];
+    if (encoded.length === 0) {
+      return fail('prefix', 'The method-specific id is empty.');
+    }
+    pass('prefix');
+
+    // lowercase: the method-specific id is lowercase.
+    if (encoded !== encoded.toLowerCase()) {
+      return fail('lowercase', 'The method-specific id must be lowercase.');
+    }
+    pass('lowercase');
+
+    // bech32m: the id decodes, the hrp is "k" or "x", and the data bytes are not empty.
+    let hrp: string;
+    let dataBytes: Uint8Array;
+    try {
+      ({ prefix: hrp, bytes: dataBytes } = bech32m.decodeToBytes(encoded));
+    } catch (error: unknown) {
+      return fail('bech32m', `Bech32m decoding failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (hrp !== 'k' && hrp !== 'x') {
+      return fail('bech32m', `The hrp must be "k" or "x", got "${hrp}".`);
+    }
+    const idType = hrp === 'k' ? IdentifierTypes.KEY : IdentifierTypes.EXTERNAL;
+    if (dataBytes.length < 1) {
+      return fail('bech32m', 'The data bytes are empty.', { idType });
+    }
+    pass('bech32m', `hrp "${hrp}", ${dataBytes.length} data bytes`);
+
+    // version: btcr2_version (the high nibble of the first byte) is 0.
+    const btcr2Version = dataBytes[0] >>> 4;
+    if (btcr2Version !== 0) {
+      return fail('version', `btcr2_version must be 0, got ${btcr2Version}.`, { idType });
+    }
+    pass('version', 'btcr2_version 0 (version_number 1)');
+
+    // network: network_value (the low nibble of the first byte) names a network.
+    const networkValue = dataBytes[0] & 0x0F;
+    const network = BitcoinNetworkNames[networkValue] as string | undefined;
+    if (typeof network !== 'string') {
+      const detail = networkValue >= 12
+        ? `network_value ${networkValue} is a custom network, not supported by this implementation.`
+        : `network_value ${networkValue} is reserved.`;
+      return fail('network', detail, { idType });
+    }
+    pass('network', `network_value ${networkValue} (${network})`);
+
+    // genesisBytes: a 33-byte SEC compressed secp256k1 public key (KEY) or a 32-byte hash (EXTERNAL).
+    const genesisBytes = dataBytes.slice(1);
+    if (idType === IdentifierTypes.KEY) {
+      try {
+        new CompressedSecp256k1PublicKey(genesisBytes);
+      } catch {
+        return fail(
+          'genesisBytes',
+          `Expected a 33-byte SEC compressed secp256k1 public key, got ${genesisBytes.length} bytes that are not a valid key.`,
+          { idType, network }
+        );
+      }
+      pass('genesisBytes', '33-byte SEC compressed secp256k1 public key');
+    } else {
+      if (genesisBytes.length !== 32) {
+        return fail('genesisBytes', `Expected a 32-byte SHA-256 hash, got ${genesisBytes.length} bytes.`, { idType, network });
+      }
+      pass('genesisBytes', '32-byte SHA-256 hash');
+    }
+
+    // roundTrip: encoding the decoded components reproduces the identifier.
+    let reEncoded: string;
+    try {
+      reEncoded = Identifier.encode(genesisBytes, { idType, version: 1, network: network as DidCreateOptions['network'] });
+    } catch (error: unknown) {
+      return fail('roundTrip', `Re-encoding failed: ${error instanceof Error ? error.message : String(error)}`, { idType, network });
+    }
+    if (reEncoded !== identifier) {
+      return fail('roundTrip', `Re-encoding produced "${reEncoded}".`, { idType, network });
+    }
+    pass('roundTrip');
+
+    // genesisBytesMatch: only if the caller supplied genesis bytes.
+    if (options.genesisBytes !== undefined) {
+      const supplied = options.genesisBytes;
+      if (!(supplied instanceof Uint8Array)) {
+        return fail('genesisBytesMatch', 'The supplied genesis bytes are not a Uint8Array.', { idType, network });
+      }
+      if (supplied.length !== genesisBytes.length) {
+        return fail(
+          'genesisBytesMatch',
+          `Expected ${genesisBytes.length} genesis bytes for a ${idType} identifier, got ${supplied.length}.`,
+          { idType, network }
+        );
+      }
+      if (!equalBytes(supplied, genesisBytes)) {
+        return fail(
+          'genesisBytesMatch',
+          `The supplied genesis bytes ${hex.encode(supplied)} do not equal the genesis bytes of the identifier ${hex.encode(genesisBytes)}.`,
+          { idType, network }
+        );
+      }
+      pass('genesisBytesMatch', 'The supplied genesis bytes equal the genesis bytes of the identifier.');
+    }
+
+    // genesisDocument: only if the caller supplied a document.
+    if (options.genesisDocument !== undefined) {
+      const document = options.genesisDocument;
+      if (idType === IdentifierTypes.KEY) {
+        return fail('genesisDocument', 'A KEY identifier has no genesis document.', { idType, network });
+      }
+      const id = (document as { id?: unknown }).id;
+      if (id !== ID_PLACEHOLDER_VALUE) {
+        return fail('genesisDocument', `The genesis document id must be "${ID_PLACEHOLDER_VALUE}", got ${JSON.stringify(id)}.`, { idType, network });
+      }
+      try {
+        GenesisDocument.fromJSON(document);
+      } catch (error: unknown) {
+        return fail('genesisDocument', `Invalid genesis document: ${error instanceof Error ? error.message : String(error)}`, { idType, network });
+      }
+      const documentHash = canonicalHashBytes(document);
+      if (!equalBytes(documentHash, genesisBytes)) {
+        return fail(
+          'genesisDocument',
+          `The genesis document hash ${hex.encode(documentHash)} does not equal the genesis bytes ${hex.encode(genesisBytes)}.`,
+          { idType, network }
+        );
+      }
+      pass('genesisDocument', 'The genesis document hashes to the genesis bytes.');
+    }
+
+    return { did: identifier, valid: true, idType, network, checks };
+  }
+
   /**
    * Generates a new did:btcr2 identifier based on a newly generated key pair.
    * @returns {string} The new did:btcr2 identifier.
@@ -249,4 +494,4 @@ export class Identifier {
       return false;
     }
   }
-}
+}