@did-btcr2/common 2.2.2 → 3.0.0

package/dist/types/utils/string.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Utility class string-related operations.
+ * @name StringUtils
+ * @class StringUtils
+ */
+export declare class StringUtils {
+    /**
+     * Escape special characters in a string for use in a regular expression.
+     * @param {string} value - The string to escape.
+     * @returns {string} The escaped string.
+     */
+    static escapeRegExp(value: string): string;
+    /**
+     * Convert a camelCase string to snake_case.
+     * @param {string} value - The camelCase string to convert.
+     * @returns {string} The converted snake_case string.
+     */
+    static toSnake(value: string): string;
+    /**
+     * Convert a string to SNAKE_SCREAMING_CASE.
+     * @param {string} value - The string to convert.
+     * @returns {string} The converted SNAKE_SCREAMING_CASE string.
+     */
+    static toSnakeScream(value: string): string;
+    /**
+     * Remove the last character from a string.
+     * @param {string} value - The string to chop.
+     * @returns {string} The chopped string.
+     */
+    static chop(value: string): string;
+    /**
+     * Replace the end of a string if it matches a given pattern.
+     * @param {string} value - The string to modify.
+     * @param {string | RegExp} pattern - The pattern to match at the end of the string.
+     * @param {string} [replacement=''] - The replacement string.
+     * @returns {string} The modified string.
+     */
+    static replaceEnd(value: string, pattern: string | RegExp, replacement?: string): string;
+}

package/dist/types/utils/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../../src/utils/string.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI1C;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAMrC;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI3C;;;;OAIG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIlC;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,WAAW,GAAE,MAAW,GAAG,MAAM;CAO7F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/common",
-  "version": "2.2.2",
+  "version": "3.0.0",
   "type": "module",
   "description": "Common utilities, types, interfaces, etc. shared across the did-btcr2-js monorepo packages.",
   "main": "./dist/cjs/index.js",
@@ -46,11 +46,10 @@
   "dependencies": {
     "@noble/hashes": "^1.7.1",
     "@scure/bip32": "^1.5.0",
-    "canonicalize": "^2.1.0",
     "chalk": "^5.4.1",
+    "fast-json-patch": "^3.1.1",
     "json-canonicalize": "^1.0.6",
-    "multiformats": "^13.3.2",
-    "rdf-canonize": "^4.0.1"
+    "multiformats": "^13.3.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.21.0",

package/src/canonicalization.ts

@@ -2,9 +2,8 @@ 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';
+import { CanonicalizationAlgorithm, CanonicalizationEncoding, HashBytes } from './types.js';
 
 /**
  * Canonicalization class provides methods for canonicalizing JSON objects
@@ -14,39 +13,50 @@ import { CanonicalizationError } from './errors.js';
  * @type {Canonicalization}
  */
 export class Canonicalization {
-  private _algorithm: CanonicalizationAlgorithm;
+  private readonly _defaultAlgorithm: CanonicalizationAlgorithm;
 
   /**
    * Initializes the Canonicalization class with the specified algorithm.
-   * @param {CanonicalizationAlgorithm} algorithm The canonicalization algorithm to use ('jcs' or 'rdfc').
+   * @param {CanonicalizationAlgorithm} algorithm The canonicalization algorithm to use ('jcs').
    */
-  // TODO: Need to move to using RDFC by default
   constructor(algorithm: CanonicalizationAlgorithm = 'jcs') {
-    this._algorithm = algorithm;
+    this._defaultAlgorithm = Canonicalization.normalizeAlgorithm(algorithm);
   }
 
   /**
-   * Sets the canonicalization algorithm.
-   * @param {'jcs' | 'rdfc'} algorithm Either 'jcs' or 'rdfc'.
+   * Gets the canonicalization algorithm.
+   * @returns {CanonicalizationAlgorithm} The current canonicalization algorithm.
    */
-  set algorithm(algorithm: 'jcs' | 'rdfc') {
-    // Normalize the passed algorithm to lowercase
-    algorithm = algorithm.toLowerCase() as CanonicalizationAlgorithm;
+  get algorithm(): CanonicalizationAlgorithm {
+    return this._defaultAlgorithm;
+  }
 
-    // Validate the algorithm is either 'jcs' or 'rdfc'
-    if(!['jcs', 'rdfc'].includes(algorithm)){
+  /**
+   * Normalizes the canonicalization algorithm.
+   * @param {CanonicalizationAlgorithm} algorithm
+   * @returns {CanonicalizationAlgorithm} The normalized algorithm.
+   * @throws {CanonicalizationError} If the algorithm is not supported.
+   */
+  static normalizeAlgorithm(algorithm: CanonicalizationAlgorithm): CanonicalizationAlgorithm {
+    const normalized = algorithm.toLowerCase() as CanonicalizationAlgorithm;
+    if (normalized !== 'jcs') {
       throw new CanonicalizationError(`Unsupported algorithm: ${algorithm}`, 'ALGORITHM_ERROR');
     }
-    // Set the algorithm
-    this._algorithm = algorithm;
+    return normalized;
   }
 
   /**
-   * Gets the canonicalization algorithm.
-   * @returns {CanonicalizationAlgorithm} The current canonicalization algorithm.
+   * Normalizes the canonicalization encoding.
+   * @param {CanonicalizationEncoding} encoding - The encoding to normalize.
+   * @returns {CanonicalizationEncoding} The normalized encoding.
+   * @throws {CanonicalizationError} If the encoding is not supported.
    */
-  get algorithm(): CanonicalizationAlgorithm {
-    return this._algorithm;
+  static normalizeEncoding(encoding: CanonicalizationEncoding): CanonicalizationEncoding {
+    const normalized = encoding.toLowerCase() as CanonicalizationEncoding;
+    if (normalized !== 'hex' && normalized !== 'base58') {
+      throw new CanonicalizationError(`Unsupported encoding: ${encoding}`, 'ENCODING_ERROR');
+    }
+    return normalized;
   }
 
   /**
@@ -56,50 +66,56 @@ export class 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).
+   * Step 1 Canonicalize (JCS) → 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').
+   * @param {Record<any, any>} object The object to process.
+   * @param {Object} [options] Options for processing.
+   * @param {CanonicalizationEncoding} [options.encoding='hex'] The encoding format ('hex' or 'base58').
+   * @param {CanonicalizationAlgorithm} [options.algorithm] The canonicalization algorithm to use.
    * @returns {Promise<string>} The final SHA-256 hash bytes as a hex string.
    */
-  public async process(object: JSONObject, encoding: string = 'hex'): Promise<string> {
+  async process(object: Record<any, any>, options: {
+    encoding?: CanonicalizationEncoding;
+    algorithm?: CanonicalizationAlgorithm;
+    multibase?: boolean;
+  } = {}): Promise<string> {
+    const algorithm = Canonicalization.normalizeAlgorithm(options.algorithm ?? this._defaultAlgorithm);
+    const encoding = Canonicalization.normalizeEncoding(options.encoding ?? 'hex');
+
     // Step 1: Canonicalize
-    const canonicalized = await this.canonicalize(object);
+    const canonicalized = await this.canonicalize(object, algorithm);
     // Step 2: Hash
     const hashed = this.hash(canonicalized);
     // Step 3: Encode
-    const encoded = this.encode(hashed, encoding);
+    const encoded = this.encode(hashed, encoding, options.multibase ?? false);
     // Return the encoded string
     return encoded;
   }
 
   /**
-   * Step 1: Uses this.algorithm to determine the method (JCS/RDFC).
-   * @param {JSONObject} object The object to canonicalize.
+   * Step 1: Uses this.algorithm to determine the method (JCS).
+   * @param {Record<any, any>} object The object to canonicalize.
+   * @param {CanonicalizationAlgorithm} [algorithm] The algorithm to use.
    * @returns {Promise<string>} The canonicalized object.
    */
-  public async canonicalize(object: JSONObject): Promise<string> {
-    return await (this[this.algorithm] as (object: JSONObject) => any)(object);
+  async canonicalize(object: Record<any, any>, algorithm: CanonicalizationAlgorithm = this._defaultAlgorithm): Promise<string> {
+    switch (Canonicalization.normalizeAlgorithm(algorithm)) {
+      case 'jcs':
+        return this.jcs(object);
+      default:
+        throw new CanonicalizationError(`Unsupported algorithm: ${algorithm}`, 'ALGORITHM_ERROR');
+    }
   }
 
   /**
    * Step 1: Canonicalizes an object using JCS (JSON Canonicalization Scheme).
-   * @param {JSONObject} object The object to canonicalize.
+   * @param {Record<any, any>} object The object to canonicalize.
    * @returns {string} The canonicalized object.
    */
-  public jcs(object: JSONObject): any {
+  jcs(object: Record<any, any>): string {
     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.
@@ -112,19 +128,18 @@ export class Canonicalization {
   /**
    * 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').
+   * @param {CanonicalizationEncoding} 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');
+  public encode(canonicalizedhash: HashBytes, encoding: CanonicalizationEncoding = 'hex', multibase: boolean = false): string {
+    const normalized = Canonicalization.normalizeEncoding(encoding);
+    if (normalized === 'hex') return this.hex(canonicalizedhash);
+    if (normalized === 'base58') {
+      const encoded = this.base58(canonicalizedhash);
+      return multibase ? `z${encoded}` : encoded;
     }
+    throw new CanonicalizationError(`Unsupported encoding: ${encoding}`, 'ENCODING_ERROR');
   }
 
   /**
@@ -142,17 +157,21 @@ export class Canonicalization {
    * @returns {string} The hash as a hex string.
    */
   public base58(hashBytes: HashBytes): string {
-    return base58btc.encode(hashBytes);
+    const encoded = base58btc.encode(hashBytes);
+    return encoded.startsWith('z') ? encoded.slice(1) : encoded;
   }
 
   /**
    * Canonicalizes an object, hashes it and returns it as hash bytes.
    * Step 1-2: Canonicalize → Hash.
-   * @param {JSONObject} object The object to process.
+   * @param {Record<any, any>} 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);
+  public async canonicalhash(
+    object: Record<any, any>,
+    algorithm: CanonicalizationAlgorithm = this._defaultAlgorithm
+  ): Promise<HashBytes> {
+    const canonicalized = await this.canonicalize(object, algorithm);
     return this.hash(canonicalized);
   }
 
@@ -163,7 +182,7 @@ export class Canonicalization {
    * @returns {string} The SHA-256 hash as a hex string.
    */
   public hashhex(canonicalized: string): string {
-    return this.encode(this.hash(canonicalized));
+    return this.encode(this.hash(canonicalized), 'hex');
   }
 
   /**
@@ -172,9 +191,7 @@ export class Canonicalization {
    * @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');
+  public hashbase58(canonicalized: string): string {
+    return this.encode(this.hash(canonicalized), 'base58', false);
   }
 }
-
-export const canonicalization = new Canonicalization();

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
@@ -118,4 +125,4 @@ export const BTCR2_DID_UPDATE_PAYLOAD_CONTEXT = [
   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;
+  }
+}