@did-btcr2/common 1.1.0

package/src/canonicalization.ts

@@ -0,0 +1,180 @@
+import { sha256 } from '@noble/hashes/sha2';
+import { bytesToHex } from '@noble/hashes/utils';
+import { canonicalize as jcsa } from 'json-canonicalize';
+import { base58btc } from 'multiformats/bases/base58';
+import rdf from 'rdf-canonize';
+import { CanonicalizationAlgorithm, HashBytes, JSONObject } from './types.js';
+import { CanonicalizationError } from './errors.js';
+
+/**
+ * Canonicalization class provides methods for canonicalizing JSON objects
+ * and hashing them using SHA-256. It supports different canonicalization
+ * algorithms and encoding formats (hex and base58).
+ * @class Canonicalization
+ * @type {Canonicalization}
+ */
+export class Canonicalization {
+  private _algorithm: CanonicalizationAlgorithm;
+
+  /**
+   * Initializes the Canonicalization class with the specified algorithm.
+   * @param {CanonicalizationAlgorithm} algorithm The canonicalization algorithm to use ('jcs' or 'rdfc').
+   */
+  // TODO: Need to move to using RDFC by default
+  constructor(algorithm: CanonicalizationAlgorithm = 'jcs') {
+    this._algorithm = algorithm;
+  }
+
+  /**
+   * Sets the canonicalization algorithm.
+   * @param {'jcs' | 'rdfc'} algorithm Either 'jcs' or 'rdfc'.
+   */
+  set algorithm(algorithm: 'jcs' | 'rdfc') {
+    // Normalize the passed algorithm to lowercase
+    algorithm = algorithm.toLowerCase() as CanonicalizationAlgorithm;
+
+    // Validate the algorithm is either 'jcs' or 'rdfc'
+    if(!['jcs', 'rdfc'].includes(algorithm)){
+      throw new CanonicalizationError(`Unsupported algorithm: ${algorithm}`, 'ALGORITHM_ERROR');
+    }
+    // Set the algorithm
+    this._algorithm = algorithm;
+  }
+
+  /**
+   * Gets the canonicalization algorithm.
+   * @returns {CanonicalizationAlgorithm} The current canonicalization algorithm.
+   */
+  get algorithm(): CanonicalizationAlgorithm {
+    return this._algorithm;
+  }
+
+  /**
+   * Implements {@link http://dcdpr.github.io/did-btcr2/#json-canonicalization-and-hash | 9.2 JSON Canonicalization and Hash}.
+   *
+   * A macro function that takes in a JSON document, document, and canonicalizes it following the JSON Canonicalization
+   * Scheme. The function returns the canonicalizedBytes.
+   *
+   * Optionally encodes a sha256 hashed canonicalized JSON object.
+   * Step 1 Canonicalize (JCS/RDFC) → Step 2 Hash (SHA256) → Step 3 Encode (Hex/Base58).
+   *
+   * @param {JSONObject} object The object to process.
+   * @param {string} encoding The encoding format ('hex' or 'base58').
+   * @returns {Promise<string>} The final SHA-256 hash bytes as a hex string.
+   */
+  public async process(object: JSONObject, encoding: string = 'hex'): Promise<string> {
+    // Step 1: Canonicalize
+    const canonicalized = await this.canonicalize(object);
+    // Step 2: Hash
+    const hashed = this.hash(canonicalized);
+    // Step 3: Encode
+    const encoded = this.encode(hashed, encoding);
+    // Return the encoded string
+    return encoded;
+  }
+
+  /**
+   * Step 1: Uses this.algorithm to determine the method (JCS/RDFC).
+   * @param {JSONObject} object The object to canonicalize.
+   * @returns {Promise<string>} The canonicalized object.
+   */
+  public async canonicalize(object: JSONObject): Promise<string> {
+    return await (this[this.algorithm] as (object: JSONObject) => any)(object);
+  }
+
+  /**
+   * Step 1: Canonicalizes an object using JCS (JSON Canonicalization Scheme).
+   * @param {JSONObject} object The object to canonicalize.
+   * @returns {string} The canonicalized object.
+   */
+  public jcs(object: JSONObject): any {
+    return jcsa(object);
+  }
+
+  /**
+   * Step 1: Canonicalizes an object using RDF Canonicalization (RDFC).
+   * @param {JSONObject} object The object to canonicalize.
+   * @returns {Promise<string>} The canonicalized object.
+   */
+  public rdfc(object: JSONObject): Promise<string> {
+    return rdf.canonize([object], { algorithm: 'RDFC-1.0' });
+  }
+
+  /**
+   * Step 2: SHA-256 hashes a canonicalized object.
+   * @param {string} canonicalized The canonicalized object.
+   * @returns {HashBytes} The SHA-256 HashBytes (Uint8Array).
+   */
+  public hash(canonicalized: string): HashBytes {
+    return sha256(canonicalized);
+  }
+
+  /**
+   * Step 3: Encodes SHA-256 hashed, canonicalized object as a hex or base58 string.
+   * @param {string} canonicalizedhash The canonicalized object to encode.
+   * @param {string} encoding The encoding format ('hex' or 'base58').
+   * @throws {CanonicalizationError} If the encoding format is not supported.
+   * @returns {string} The encoded string.
+   */
+  public encode(canonicalizedhash: HashBytes, encoding: string = 'hex'): string {
+    switch(encoding) {
+      case 'hex':
+        return this.hex(canonicalizedhash);
+      case 'base58':
+        return this.base58(canonicalizedhash);
+      default:
+        throw new CanonicalizationError(`Unsupported encoding: ${encoding}`, 'ENCODING_ERROR');
+    }
+  }
+
+  /**
+   * Step 3.1: Encodes HashBytes (Uint8Array) to a hex string.
+   * @param {HashBytes} hashBytes The hash as a Uint8Array.
+   * @returns {string} The hash as a hex string.
+   */
+  public hex(hashBytes: HashBytes): string {
+    return bytesToHex(hashBytes);
+  }
+
+  /**
+   * Step 3.2: Encodes HashBytes (Uint8Array) to a base58btc string.
+   * @param {HashBytes} hashBytes The hash as a Uint8Array.
+   * @returns {string} The hash as a hex string.
+   */
+  public base58(hashBytes: HashBytes): string {
+    return base58btc.encode(hashBytes);
+  }
+
+  /**
+   * Canonicalizes an object, hashes it and returns it as hash bytes.
+   * Step 1-2: Canonicalize → Hash.
+   * @param {JSONObject} object The object to process.
+   * @returns {Promise<HashBytes>} The final SHA-256 hash bytes.
+   */
+  public async canonicalhash(object: JSONObject): Promise<HashBytes> {
+    const canonicalized = await this.canonicalize(object);
+    return this.hash(canonicalized);
+  }
+
+  /**
+   * Computes the SHA-256 hash of a canonicalized object and encodes it as a hex string.
+   * Step 2-3: Hash → Encode(Hex).
+   * @param {string} canonicalized The canonicalized object to hash.
+   * @returns {string} The SHA-256 hash as a hex string.
+   */
+  public hashhex(canonicalized: string): string {
+    return this.encode(this.hash(canonicalized));
+  }
+
+  /**
+   * Computes the SHA-256 hashes of canonicalized object and encodes it as a base58 string.
+   * Step 2-3: Hash → Encode(base58).
+   * @param {string} canonicalized The canonicalized object to hash.
+   * @returns {string} The SHA-256 hash as a base58 string.
+   */
+  public hashb58(canonicalized: string): string {
+    return this.encode(this.hash(canonicalized), 'base58');
+  }
+}
+
+export const canonicalization = new Canonicalization();

package/src/constants.ts

@@ -0,0 +1,123 @@
+import { sha256 } from '@noble/hashes/sha2';
+import { Bytes, HashHex } from './types.js';
+
+export const ID_PLACEHOLDER_VALUE = 'did:btcr2:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
+export const OP_RETURN = 0x6a;
+export const OP_PUSH32 = 0x20;
+export const VALID_HRP = ['k', 'x'];
+export const MULTIBASE_URI_PREFIX = 'urn:mb:';
+export const INITIAL_BLOCK_REWARD = 50;
+export const HALVING_INTERVAL = 150;
+export const COINBASE_MATURITY_DELAY = 100;
+export const POLAR_BOB_CLIENT_CONFIG = {
+  username           : 'polaruser',
+  password           : 'polarpass',
+  host               : 'http://127.0.0.1:18443',
+  allowDefaultWallet : true,
+  version            : '28.1.0'
+};
+export const POLAR_ALICE_CLIENT_CONFIG = {
+  username           : 'polaruser',
+  password           : 'polarpass',
+  host               : 'http://127.0.0.1:18444',
+  allowDefaultWallet : true,
+  version            : '28.1.0'
+};
+export const DEFAULT_REST_CONFIG = { host: 'http://localhost:3000' };
+export const DEFAULT_RPC_CONFIG = POLAR_BOB_CLIENT_CONFIG;
+export const DEFAULT_BLOCK_CONFIRMATIONS = 7;
+
+// Fixed public key header bytes per the Data Integrity BIP340 Cryptosuite spec: [0xe7, 0x01] / [231, 1]
+export const BIP340_PUBLIC_KEY_MULTIBASE_PREFIX: Bytes = new Uint8Array([0xe7, 0x01]);
+// Hash of the BIP-340 Multikey prefix
+export const BIP340_PUBLIC_KEY_MULTIBASE_PREFIX_HASH: HashHex = Buffer.from(sha256(BIP340_PUBLIC_KEY_MULTIBASE_PREFIX)).toString('hex');
+// Fixed secret key header bytes per the Data Integrity BIP340 Cryptosuite spec: [0x81, 0x26] / [129, 38]
+export const BIP340_SECRET_KEY_MULTIBASE_PREFIX: Bytes = new Uint8Array([0x81, 0x26]);
+// Hash of the BIP-340 Multikey prefix
+export const BIP340_SECRET_KEY_MULTIBASE_PREFIX_HASH: HashHex = Buffer.from(sha256(BIP340_SECRET_KEY_MULTIBASE_PREFIX)).toString('hex');
+// curve's field size
+export const B256 = 2n ** 256n;
+// curve's field prime
+export const P = B256 - 0x1000003d1n;
+// curve (group) order
+export const N = B256 - 0x14551231950b75fc4402da1732fc9bebfn;
+// base point x
+export const Gx = 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798n;
+// base point y
+export const Gy = 0x483ada7726a3c4655da4fbfc0e1108a8fd17b448a68554199c47d08ffb10d4b8n;
+// curve parameters
+export const a = 0n;
+export const b = 7n;
+export const p = P;
+export const n = N;
+export const CURVE = {
+  p,
+  n,
+  a,
+  b,
+  Gx,
+  Gy
+};
+
+export const W3C_DID_V1 = 'https://www.w3.org/ns/did/v1';
+export const W3C_DID_V1_1 =  'https://www.w3.org/TR/did-1.1';
+export const W3C_DATA_INTEGRITY_V1 = 'https://w3id.org/security/data-integrity/v1';
+export const W3C_DATA_INTEGRITY_V2 = 'https://w3id.org/security/data-integrity/v2';
+export const W3C_SECURITY_V2 = 'https://w3id.org/security/v2';
+export const BTC1_METHOD_CONTEXT = 'https://btcr2.dev/context/v1';
+export const W3C_ZCAP_V1 = 'https://w3id.org/zcap/v1';
+export const W3C_JSONLD_PATCH_V1 = 'https://w3id.org/json-ld-patch/v1';
+export const W3C_MULTIKEY_V1 = 'https://w3id.org/security/multikey/v1';
+export const W3C_DID_RESOLUTION_V1 = 'https://w3id.org/did-resolution/v1';
+export const CONTEXT_URL_MAP = {
+  w3c : {
+    did           : {
+      v1   : 'https://www.w3.org/ns/did/v1',
+      v1_1 : 'https://www.w3.org/TR/did-1.1',
+    },
+    didresolution : {
+      v1 : 'https://w3id.org/did-resolution/v1',
+    },
+    security : {
+      v2 : 'https://w3id.org/security/v2',
+    },
+    dataintegrity : {
+      v1 : 'https://w3id.org/security/data-integrity/v1',
+      v2 : 'https://w3id.org/security/data-integrity/v2',
+    },
+    zcap          : {
+      v1 : 'https://w3id.org/zcap/v1',
+    },
+    jsonldpatch   : {
+      v1 : 'https://w3id.org/json-ld-patch/v1',
+    },
+    multikey      : {
+      v1 : 'https://w3id.org/security/multikey/v1',
+    },
+  },
+  btcr2 : {
+    diddocument : {
+      v1 : 'https://dcdpr.github.io/did-btcr2-js/ns/did-document/v1',
+    },
+    method : {
+      v1 : 'https://btcr2.dev/context/v1'
+    },
+  },
+
+};
+
+export const BTC1_DID_DOCUMENT_CONTEXT = [
+  CONTEXT_URL_MAP.w3c.did.v1_1,
+  CONTEXT_URL_MAP.btcr2.method.v1,
+];
+
+export const BTC1_MULTIKEY_CONTEXT = [
+  CONTEXT_URL_MAP.w3c.did.v1,
+  CONTEXT_URL_MAP.w3c.multikey.v1
+];
+
+export const BTC1_DID_UPDATE_PAYLOAD_CONTEXT = [
+  CONTEXT_URL_MAP.w3c.security.v2,
+  CONTEXT_URL_MAP.w3c.zcap.v1,
+  CONTEXT_URL_MAP.w3c.jsonldpatch.v1,
+];

package/src/errors.ts

@@ -0,0 +1,224 @@
+/**
+ * An enumeration of possible DID error codes.
+ */
+export enum Btc1ErrorCode {
+  /** The DID supplied does not conform to valid syntax. */
+  INVALID_DID = 'INVALID_DID',
+
+  /** The supplied method name is not supported by the DID method and/or DID resolver implementation. */
+  METHOD_NOT_SUPPORTED = 'METHOD_NOT_SUPPORTED',
+
+  /** An unexpected error occurred during the requested DID operation. */
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+
+  /** The DID document supplied does not conform to valid syntax. */
+  INVALID_DID_DOCUMENT = 'INVALID_DID_DOCUMENT',
+
+  /** The DID Update supplied does not conform to valid syntax. */
+  INVALID_DID_UPDATE = 'INVALID_DID_UPDATE',
+
+  /** The byte length of a DID document does not match the expected value. */
+  INVALID_DID_DOCUMENT_LENGTH = 'INVALID_DID_DOCUMENT_LENGTH',
+
+  /** The DID URL supplied to the dereferencing function does not conform to valid syntax. */
+  INVALID_DID_URL = 'INVALID_DID_URL',
+
+  /** The given proof of a previous DID is invalid */
+  INVALID_PREVIOUS_DID_PROOF = 'INVALID_PREVIOUS_DID_PROOF',
+
+  /** An invalid public key is detected during a DID operation. */
+  INVALID_PUBLIC_KEY = 'INVALID_PUBLIC_KEY',
+
+  /** An invalid multibase format is detected on the public key during a DID operation. */
+  INVALID_PUBLIC_KEY_MULTIBASE = 'INVALID_PUBLIC_KEY_MULTIBASE',
+
+  /** The byte length of a public key does not match the expected value. */
+  INVALID_PUBLIC_KEY_LENGTH = 'INVALID_PUBLIC_KEY_LENGTH',
+
+  /** An invalid public key type was detected during a DID operation. */
+  INVALID_PUBLIC_KEY_TYPE = 'INVALID_PUBLIC_KEY_TYPE',
+
+  /** Verification of a signature failed during a DID operation. */
+  INVALID_SIGNATURE = 'INVALID_SIGNATURE',
+
+  /** General: The resource requested was not found. */
+  /** DID Resolution: The DID resolver was unable to find the DID document resulting from the resolution request.  */
+  NOT_FOUND = 'NOT_FOUND',
+
+  /**
+   * The representation requested via the `accept` input metadata property is not supported by the
+   * DID method and/or DID resolver implementation.
+   */
+  REPRESENTATION_NOT_SUPPORTED = 'REPRESENTATION_NOT_SUPPORTED',
+
+  /** The type of a public key is not supported by the DID method and/or DID resolver implementation. */
+  UNSUPPORTED_PUBLIC_KEY_TYPE = 'UNSUPPORTED_PUBLIC_KEY_TYPE',
+
+  /** The proof verification operation failed. */
+  PROOF_VERIFICATION_ERROR = 'PROOF_VERIFICATION_ERROR',
+
+  /** The proof generation operation failed. */
+  PROOF_GENERATION_ERROR = 'PROOF_GENERATION_ERROR',
+
+  /** The proof serialization operation failed. */
+  PROOF_SERIALIZATION_ERROR = 'PROOF_SERIALIZATION_ERROR',
+
+  /** The proof could not be parsed properly. */
+  PROOF_PARSING_ERROR = 'PROOF_PARSING_ERROR',
+
+  /** The verification method was formed improperly. */
+  VERIFICATION_METHOD_ERROR = 'VERIFICATION_METHOD_ERROR',
+
+ /** Something about the DID Update Payload indicates the potential for late publishing. */
+  LATE_PUBLISHING_ERROR = 'LATE_PUBLISHING_ERROR',
+
+  /** The sidecar data in the DID Update Payload was invalid. */
+  INVALID_SIDECAR_DATA = 'INVALID_SIDECAR_DATA',
+
+  /** The proof is missing or has a malformed challenge field. */
+  INVALID_CHALLENGE_ERROR = 'INVALID_CHALLENGE_ERROR',
+
+  /** The proof is missing or has a malformed domain field. */
+  INVALID_DOMAIN_ERROR = 'INVALID_DOMAIN_ERROR'
+}
+
+export const {
+  INVALID_DID,
+  METHOD_NOT_SUPPORTED,
+  INTERNAL_ERROR,
+  INVALID_DID_DOCUMENT,
+  INVALID_DID_UPDATE,
+  INVALID_DID_DOCUMENT_LENGTH,
+  INVALID_DID_URL,
+  INVALID_PREVIOUS_DID_PROOF,
+  INVALID_PUBLIC_KEY,
+  INVALID_PUBLIC_KEY_MULTIBASE,
+  INVALID_PUBLIC_KEY_LENGTH,
+  INVALID_PUBLIC_KEY_TYPE,
+  INVALID_SIGNATURE,
+  NOT_FOUND,
+  REPRESENTATION_NOT_SUPPORTED,
+  UNSUPPORTED_PUBLIC_KEY_TYPE,
+  PROOF_VERIFICATION_ERROR,
+  PROOF_GENERATION_ERROR,
+  PROOF_SERIALIZATION_ERROR,
+  PROOF_PARSING_ERROR,
+  VERIFICATION_METHOD_ERROR,
+  LATE_PUBLISHING_ERROR,
+  INVALID_SIDECAR_DATA,
+  INVALID_CHALLENGE_ERROR,
+  INVALID_DOMAIN_ERROR
+} = Btc1ErrorCode;
+
+export type ErrorOptions = {
+  type?: string;
+  name?: string;
+  data?: any;
+}
+
+export class DidBtc1Error extends Error {
+  name: string = 'DidBtc1Error';
+  type: string = 'DidBtc1Error';
+  data?: Record<string, any>;
+
+  constructor(message: string, options: ErrorOptions = {}) {
+    super(message);
+    this.type = options.type ?? this.type;
+    this.name = options.name ?? this.name;
+    this.data = options.data;
+
+    // Ensures that instanceof works properly, the correct prototype chain when using inheritance,
+    // and that V8 stack traces (like Chrome, Edge, and Node.js) are more readable and relevant.
+    Object.setPrototypeOf(this, new.target.prototype);
+
+    // Captures the stack trace in V8 engines (like Chrome, Edge, and Node.js).
+    // In non-V8 environments, the stack trace will still be captured.
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, DidBtc1Error);
+    }
+  }
+}
+
+export class Btc1Error extends DidBtc1Error {
+  constructor(message: string, type: string, data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class Btc1ReadError extends DidBtc1Error {
+  constructor(message: string, type: string = 'Btc1ReadError', data?: Record<string, any>) {
+    super(message, { type, name: 'Btc1ReadError', data });
+  }
+}
+
+export class Btc1KeyManagerError extends DidBtc1Error {
+  constructor(message: string, type: string = 'Btc1KeyManagerError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class DidDocumentError extends DidBtc1Error {
+  constructor(message: string, type: string = 'DidDocumentError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class CryptosuiteError extends DidBtc1Error {
+  constructor(message: string, type: string = 'CryptosuiteError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class KeyPairError extends DidBtc1Error {
+  constructor(message: string, type: string = 'KeyPairError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class SecretKeyError extends DidBtc1Error {
+  constructor(message: string, type: string = 'SecretKeyError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class PublicKeyError extends DidBtc1Error {
+  constructor(message: string, type: string = 'PublicKeyError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class MultikeyError extends DidBtc1Error {
+  constructor(message: string, type: string = 'MultikeyError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class ProofError extends DidBtc1Error {
+  constructor(message: string, type: string = 'ProofError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class SingletonBeaconError extends DidBtc1Error {
+  constructor(message: string, type: string = 'SingletonBeaconError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class CIDAggregateBeaconError extends DidBtc1Error {
+  constructor(message: string, type: string = 'CIDAggregateBeaconError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class SMTAggregateBeaconError extends DidBtc1Error {
+  constructor(message: string, type: string = 'SMTAggregateBeaconError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}
+
+export class CanonicalizationError extends DidBtc1Error {
+  constructor(message: string, type: string = 'CanonicalizationError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}