@did-btcr2/common 2.2.1 → 3.0.0

package/src/constants.ts

@@ -1,4 +1,5 @@
 import { sha256 } from '@noble/hashes/sha2';
+import { bytesToHex } from '@noble/hashes/utils';
 import { Bytes, HashHex } from './types.js';
 
 export const ID_PLACEHOLDER_VALUE = 'did:btcr2:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
@@ -9,32 +10,38 @@ 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 = {
+export const DEFAULT_POLAR_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_RPC_CONFIG = DEFAULT_POLAR_CONFIG;
 export const DEFAULT_BLOCK_CONFIRMATIONS = 7;
 
+/**
+ * Load a default RPC config, allowing environment overrides to avoid hard-coding credentials/hosts in bundles.
+ * @returns {typeof DEFAULT_POLAR_CONFIG} The RPC config.
+ */
+export function getDefaultRpcConfig(): typeof DEFAULT_POLAR_CONFIG {
+  return {
+    ...DEFAULT_POLAR_CONFIG,
+    host     : process.env.BTCR2_RPC_HOST ?? DEFAULT_POLAR_CONFIG.host,
+    username : process.env.BTCR2_RPC_USER ?? DEFAULT_POLAR_CONFIG.username,
+    password : process.env.BTCR2_RPC_PASS ?? DEFAULT_POLAR_CONFIG.password,
+  };
+}
+
 // 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');
+export const BIP340_PUBLIC_KEY_MULTIBASE_PREFIX_HASH: HashHex = bytesToHex(sha256(BIP340_PUBLIC_KEY_MULTIBASE_PREFIX));
 // 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');
+export const BIP340_SECRET_KEY_MULTIBASE_PREFIX_HASH: HashHex = bytesToHex(sha256(BIP340_SECRET_KEY_MULTIBASE_PREFIX));
 // curve's field size
 export const B256 = 2n ** 256n;
 // curve's field prime
@@ -72,35 +79,32 @@ 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',
+      v1   : W3C_DID_V1,
+      v1_1 : W3C_DID_V1_1,
     },
     didresolution : {
-      v1 : 'https://w3id.org/did-resolution/v1',
+      v1 : W3C_DID_RESOLUTION_V1,
     },
     security : {
-      v2 : 'https://w3id.org/security/v2',
+      v2 : W3C_SECURITY_V2,
     },
     dataintegrity : {
-      v1 : 'https://w3id.org/security/data-integrity/v1',
-      v2 : 'https://w3id.org/security/data-integrity/v2',
+      v1 : W3C_DATA_INTEGRITY_V1,
+      v2 : W3C_DATA_INTEGRITY_V2,
     },
     zcap          : {
-      v1 : 'https://w3id.org/zcap/v1',
+      v1 : W3C_ZCAP_V1,
     },
     jsonldpatch   : {
-      v1 : 'https://w3id.org/json-ld-patch/v1',
+      v1 : W3C_JSONLD_PATCH_V1,
     },
     multikey      : {
-      v1 : 'https://w3id.org/security/multikey/v1',
+      v1 : W3C_MULTIKEY_V1,
     },
   },
   btcr2 : {
-    diddocument : {
-      v1 : 'https://dcdpr.github.io/did-btcr2-js/ns/did-document/v1',
-    },
     method : {
-      v1 : 'https://btcr2.dev/context/v1'
+      v1 : BTCR2_METHOD_CONTEXT
     },
   },
 
@@ -117,7 +121,8 @@ export const BTCR2_MULTIKEY_CONTEXT = [
 ];
 
 export const BTCR2_DID_UPDATE_PAYLOAD_CONTEXT = [
+  CONTEXT_URL_MAP.btcr2.method.v1,
   CONTEXT_URL_MAP.w3c.security.v2,
   CONTEXT_URL_MAP.w3c.zcap.v1,
   CONTEXT_URL_MAP.w3c.jsonldpatch.v1,
-];
+];

package/src/index.ts

@@ -1,11 +1,11 @@
-import './exts.js';
-
 export * from './canonicalization.js';
 export * from './constants.js';
 export * from './errors.js';
 export * from './interfaces.js';
+export * from './json-patch.js';
 export * from './logger.js';
-export * from './patch.js';
 export * from './types.js';
-
-export * from './exts.js';
+export * from './utils/date.js';
+export * from './utils/json.js';
+export * from './utils/set.js';
+export * from './utils/string.js';

package/src/interfaces.ts

@@ -1,12 +1,12 @@
 export type JsonPatch = Array<PatchOperation>;
-export type PatchOpCode = 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test' | string;
+export type PatchOpCode = 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test' | (string & {});
 /**
  * A JSON Patch operation, as defined in {@link https://datatracker.ietf.org/doc/html/rfc6902 | RFC 6902}.
  */
 export interface PatchOperation {
   op: PatchOpCode;
   path: string;
-  value?: any; // Required for add, replace, test
+  value?: unknown; // Required for add, replace, test
   from?: string; // Required for move, copy
 }
 

package/src/json-patch.ts

@@ -0,0 +1,103 @@
+import jsonPatch, { Operation } from 'fast-json-patch';
+import { MethodError } from './errors.js';
+import { PatchOperation } from './interfaces.js';
+import { JSONObject } from './types.js';
+
+const { applyPatch, compare, deepClone } = jsonPatch;
+
+/**
+ * Thin wrapper around fast-json-patch to keep a stable API within this package.
+ * @class JSONPatch
+ * @type {JSONPatch}
+ */
+export class JSONPatch {
+  /**
+   * Applies a JSON Patch to a source document and returns the patched document.
+   * Does not mutate the input document.
+   * @param {JSONObject} sourceDocument - The source JSON document to apply the patch to.
+   * @param {PatchOperation[]} operations - The JSON Patch operations to apply.
+   * @returns {JSONObject} The patched JSON document.
+   */
+  static apply(
+    sourceDocument: Record<any, any>,
+    operations: PatchOperation[],
+    options: { mutate?: boolean; clone?: (value: any) => any } = {}
+  ): Record<any, any> {
+    const mutate = options.mutate ?? false;
+    const cloneFn = options.clone ?? deepClone;
+    const docClone = mutate ? sourceDocument : cloneFn(sourceDocument);
+    const validationError = this.validateOperations(operations);
+    if (validationError) {
+      throw new MethodError('Invalid JSON Patch operations', 'JSON_PATCH_APPLY_ERROR', { error: validationError });
+    }
+    try {
+      const result = applyPatch(docClone, operations as Operation[], true, mutate);
+      if (result.newDocument === undefined) {
+        throw new MethodError('JSON Patch application failed', 'JSON_PATCH_APPLY_ERROR', { result });
+      }
+      return result.newDocument as JSONObject;
+    } catch (error) {
+      throw new MethodError('JSON Patch application failed', 'JSON_PATCH_APPLY_ERROR', { error });
+    }
+  }
+
+  /**
+   * Compute a JSON Patch diff from source => target.
+   * @param {JSONObject} sourceDocument - The source JSON document.
+   * @param {JSONObject} targetDocument - The target JSON document.
+   * @param {string} [path] - An optional base path to prefix to each operation.
+   * @returns {PatchOperation[]} The computed JSON Patch operations.
+   */
+  static diff(sourceDocument: JSONObject, targetDocument: JSONObject, path: string = ''): PatchOperation[] {
+    const ops = compare(sourceDocument ?? {}, targetDocument ?? {}) as PatchOperation[];
+    if (!path) return ops;
+
+    const prefix = path.endsWith('/') ? path.slice(0, -1) : path;
+    return ops.map(op => ({
+      ...op,
+      path : this.joinPointer(prefix, op.path)
+    }));
+  }
+
+  /**
+ * Join a base pointer prefix with an operation path ensuring correct escaping.
+ * @param {string} prefix - The base pointer prefix.
+ * @param {string} opPath - The operation path.
+ * @returns {string} The joined pointer.
+ */
+  static joinPointer(prefix: string, opPath: string): string {
+    if (!prefix) return opPath;
+    const normalizedPrefix = prefix.startsWith('/') ? prefix : `/${prefix}`;
+    return `${this.escapeSegmentPath(normalizedPrefix)}${opPath}`;
+  }
+
+  /**
+ * Escape a JSON Pointer segment according to RFC 6901.
+ * @param {string} pointer - The JSON Pointer to escape.
+ * @returns {string} The escaped JSON Pointer.
+ */
+  static escapeSegmentPath(pointer: string): string {
+    return pointer
+      .split('/')
+      .map((segment, idx) => idx === 0 ? segment : segment.replace(/~/g, '~0').replace(/\//g, '~1'))
+      .join('/');
+  }
+
+  /**
+ * Validate JSON Patch operations.
+ * @param {PatchOperation[]} operations - The operations to validate.
+ * @returns {Error | null} An Error if validation fails, otherwise null.
+ */
+  static validateOperations(operations: PatchOperation[]): Error | null {
+    if (!Array.isArray(operations)) return new Error('Operations must be an array');
+    for (const op of operations) {
+      if (!op || typeof op !== 'object') return new Error('Operation must be an object');
+      if (typeof op.op !== 'string') return new Error('Operation.op must be a string');
+      if (typeof op.path !== 'string') return new Error('Operation.path must be a string');
+      if ((op.op === 'move' || op.op === 'copy') && typeof op.from !== 'string') {
+        return new Error(`Operation.from must be a string for op=${op.op}`);
+      }
+    }
+    return null;
+  }
+}

package/src/logger.ts

@@ -51,18 +51,35 @@ const LEVEL_METHODS: Record<Level, keyof Console> = {
  * - File/line tracing
  * - Timestamps
  * - Colorized output
+ * @class Logger
+ * @type {Logger}
  */
 export class Logger {
   private levels: Level[];
   private namespace?: string;
+  private useColors: boolean;
+  private static shared: Logger;
 
-  constructor(namespace?: string) {
-    this.levels = LOG_LEVELS[NODE_ENV] || [];
-    this.namespace = namespace ?? 'did-btcr2-js';
+  /**
+   * Creates a new Logger instance.
+   * @param {string} namespace - Optional namespace for log messages.
+   * @param {Object} options - Configuration options.
+   * @param {Level[]} options.levels - Log levels to enable.
+   * @param {boolean} options.useColors - Whether to use colored output.
+   */
+  constructor(namespace?: string, options: { levels?: Level[]; useColors?: boolean } = {}) {
+    this.levels = options.levels || LOG_LEVELS[NODE_ENV] || [];
+    this.namespace = namespace || 'did-btcr2-js';
+    const envForce = process.env.LOG_COLORS;
+    this.useColors = options.useColors || (envForce ? envForce !== '0' && envForce.toLowerCase() !== 'false' : Boolean(process.stdout.isTTY));
   }
 
   /**
    * Logs a message with the specified level.
+   * @param {Level} level - The log level.
+   * @param {unknown} message - The message to log.
+   * @param {...unknown[]} args - Additional arguments to log.
+   * @returns {void}
    */
   private _log(level: Level, message?: unknown, ...args: unknown[]): void {
     if (!this.levels.includes(level)) return;
@@ -72,70 +89,85 @@ export class Logger {
 
     const timestamp = new Date().toISOString();
     const namespace = this.namespace ? `[${this.namespace}]` : '';
+    const render = this.useColors ? color : (v: string) => v;
+    const renderGray = this.useColors ? chalk.gray : (v: string) => v;
 
     (console[method] as (...args: any[]) => void)(
-      `${chalk.gray(timestamp)} ${namespace} ${color(level)}: ${chalk.white(message)}`,
+      `${renderGray(timestamp)} ${namespace} ${render(level)}: ${message}`,
       ...args
     );
   }
 
-  // 🔹 Instance-based logging methods
-  public debug(message?: unknown, ...args: unknown[]) {
+  debug(message?: unknown, ...args: unknown[]): Logger {
     this._log('debug', message, ...args); return this;
   }
 
-  public error(message?: unknown, ...args: unknown[]) {
+  error(message?: unknown, ...args: unknown[]): Logger {
     this._log('error', message, ...args); return this;
   }
 
-  public info(message?: unknown, ...args: unknown[]) {
+  info(message?: unknown, ...args: unknown[]): Logger {
     this._log('info', message, ...args); return this;
   }
 
-  public warn(message?: unknown, ...args: unknown[]) {
+  warn(message?: unknown, ...args: unknown[]): Logger {
     this._log('warn', message, ...args); return this;
   }
 
-  public security(message?: unknown, ...args: unknown[]) {
+  security(message?: unknown, ...args: unknown[]): Logger {
     this._log('security', message, ...args); return this;
   }
 
-  public log(message?: unknown, ...args: unknown[]) {
+  log(message?: unknown, ...args: unknown[]): Logger {
     this._log('log', message, ...args); return this;
   }
 
-  public newline() {
+  newline(): Logger {
     console.log(); return this;
   }
 
   /**
    * Static methods for convenience (auto-instantiate).
+   * These use a shared singleton instance.
+   * @param {unknown} message - The message to log.
+   * @param {...unknown[]} args - Additional arguments to log.
+   * @returns {void}
    */
-  public static debug(message?: unknown, ...args: unknown[]) {
-    new Logger().debug(message, ...args);
+  static debug(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().debug(message, ...args);
   }
 
-  public static error(message?: unknown, ...args: unknown[]) {
-    new Logger().error(message, ...args);
+  static error(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().error(message, ...args);
   }
 
-  public static info(message?: unknown, ...args: unknown[]) {
-    new Logger().info(message, ...args);
+  static info(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().info(message, ...args);
   }
 
-  public static warn(message?: unknown, ...args: unknown[]) {
-    new Logger().warn(message, ...args);
+  static warn(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().warn(message, ...args);
   }
 
-  public static security(message?: unknown, ...args: unknown[]) {
-    new Logger().security(message, ...args);
+  static security(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().security(message, ...args);
   }
 
-  public static log(message?: unknown, ...args: unknown[]) {
-    new Logger().log(message, ...args);
+  static log(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().log(message, ...args);
   }
 
-  public static newline() {
-    new Logger().newline();
+  static newline() {
+    Logger.instance().newline();
   }
-}
+
+  private static instance(levels?: Level[], useColors?: boolean): Logger {
+    if (!Logger.shared) {
+      Logger.shared = new Logger(undefined, { levels, useColors });
+    } else {
+      if (levels) Logger.shared.levels = levels;
+      if (useColors !== undefined) Logger.shared.useColors = useColors;
+    }
+    return Logger.shared;
+  }
+}

package/src/types.ts

@@ -66,19 +66,24 @@ export enum BitcoinNetworkNames {
     testnet4 = 4,
     mutinynet = 5
 }
-export type KeyIdentifier = string;
+export type DecentralizedIdentifier = string;
+export type Did = DecentralizedIdentifier;
 export type BeaconUri = string;
 export type DidPlaceholder = 'did:btcr2:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
 export type CanonicalizedProofConfig = string;
 export type CryptosuiteName = 'bip340-jcs-2025' | 'bip340-rdfc-2025';
-export type ContextObject = Record<string | number | symbol, any>;
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArray = JsonValue[];
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+export type JsonObject = { [key: string]: JsonValue };
+export type JSONObject = JsonObject; // JSON object: prototyped or unprototyped
+export type Prototyped = JSONObject;
+export type Unprototyped = JSONObject;
+export type ContextObject = Record<string, JsonValue>;
 export type Context = string | string[] | ContextObject | ContextObject[]
 
 /* General Types */
-export type Maybe<T> = T | any;
-export type JSONObject = Record<string | number | symbol, any>; // JSON object: prototyped or unprototyped
-export type Prototyped = JSONObject;
-export type Unprototyped = JSONObject;
+export type Maybe<T> = T | unknown;
 export type TwoDigits = `${number}${number}`;
 export type ThreeDigits = `${number}${number}${number}`;
 export type Year = `${1 | 2}${ThreeDigits}`;
@@ -92,4 +97,5 @@ export type TzOffset = `${Hours}:${Minutes}`;
 export type DateTimestamp = `${UtcTimestamp}Z` | `${UtcTimestamp}-${TzOffset}`;
 export type CanonicalizableObject = Record<string, any>;
 export type CanonicalizationAlgorithm = 'jcs' | 'rdfc';
-export type UnixTimestamp = number;
+export type CanonicalizationEncoding = 'hex' | 'base58';
+export type UnixTimestamp = number;

package/src/utils/date.ts

@@ -0,0 +1,32 @@
+/**
+ * Utility class for date-related operations.
+ * @name DateUtils
+ * @class DateUtils
+ */
+export class DateUtils {
+  /**
+   * Render an ISO 8601 UTC timestamp without fractional seconds.
+   * @param {Date} [date=new Date()] - The date to format.
+   * @returns {string} The formatted date string.
+   */
+  static getUTCDateTime(date: Date = new Date()): string {
+    const time = date.getTime();
+    if (Number.isNaN(time)) {
+      throw new Error(`Invalid date: ${date}`);
+    }
+    return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+  }
+
+  /**
+   * Unix timestamp in seconds (integer).
+   * @param {Date} [date=new Date()] - The date to convert.
+   * @returns {number} The Unix timestamp in seconds.
+   */
+  static toUnixSeconds(date: Date = new Date()): number {
+    const time = date.getTime();
+    if (Number.isNaN(time)) {
+      throw new Error(`Invalid date: ${date}`);
+    }
+    return Math.floor(date.getTime() / 1000);
+  }
+}