@did-btcr2/common 1.1.0

package/src/logger.ts

@@ -0,0 +1,162 @@
+import chalk, { ChalkInstance } from 'chalk';
+import path from 'path';
+
+export enum Env {
+  Development = 'development',
+  Production = 'production',
+  Test = 'test',
+}
+
+export type Level = 'debug' | 'error' | 'info' | 'log' | 'warn' | 'security';
+
+export const NODE_ENV = (process.env.NODE_ENV as Env) || Env.Development;
+
+/**
+ * Mapping of log levels to colors for cleaner, more flexible logging.
+ */
+const LOG_LEVELS: Record<Env, Level[]> = {
+  development : ['debug', 'info', 'log', 'warn', 'security'],
+  test        : ['log', 'info', 'error'],
+  production  : ['error'],
+};
+
+/**
+ * Colors associated with each log level.
+ */
+const LEVEL_STYLES: Record<Level, ChalkInstance> = {
+  debug    : chalk.green,
+  error    : chalk.red,
+  info     : chalk.blue,
+  log      : chalk.gray,
+  warn     : chalk.yellow,
+  security : chalk.magenta,
+};
+
+/**
+ * Defines the method mapping for console methods.
+ */
+// eslint-disable-next-line no-undef
+const LEVEL_METHODS: Record<Level, keyof Console> = {
+  debug    : 'debug',
+  error    : 'error',
+  info     : 'info',
+  log      : 'log',
+  warn     : 'warn',
+  security : 'warn',
+};
+
+/**
+ * A flexible, feature-rich logger with:
+ * - Environment-based filtering
+ * - Namespacing
+ * - File/line tracing
+ * - Timestamps
+ * - Colorized output
+ */
+export class Logger {
+  private levels: Level[];
+  private namespace?: string;
+
+  constructor(namespace?: string) {
+    this.levels = LOG_LEVELS[NODE_ENV] || [];
+    this.namespace = namespace ?? 'did-btcr2-js';
+  }
+
+  /**
+   * Logs a message with the specified level.
+   */
+  private _log(level: Level, message?: unknown, ...args: unknown[]): void {
+    if (!this.levels.includes(level)) return;
+
+    const color = LEVEL_STYLES[level];
+    const method = LEVEL_METHODS[level];
+
+    const timestamp = new Date().toISOString();
+    const namespace = this.namespace ? `[${this.namespace}]` : '';
+
+    (console[method] as (...args: any[]) => void)(
+      `${chalk.gray(timestamp)} ${namespace} ${color(level)}: ${chalk.white(message)}`,
+      ...args
+    );
+  }
+
+  // 🔹 Instance-based logging methods
+  public debug(message?: unknown, ...args: unknown[]) {
+    this._log('debug', message, ...args); return this;
+  }
+
+  public error(message?: unknown, ...args: unknown[]) {
+    this._log('error', message, ...args); return this;
+  }
+
+  public info(message?: unknown, ...args: unknown[]) {
+    this._log('info', message, ...args); return this;
+  }
+
+  public warn(message?: unknown, ...args: unknown[]) {
+    this._log('warn', message, ...args); return this;
+  }
+
+  public security(message?: unknown, ...args: unknown[]) {
+    this._log('security', message, ...args); return this;
+  }
+
+  public log(message?: unknown, ...args: unknown[]) {
+    this._log('log', message, ...args); return this;
+  }
+
+  public newline() {
+    console.log(); return this;
+  }
+
+  /**
+   * Static methods for convenience (auto-instantiate).
+   */
+  public static debug(message?: unknown, ...args: unknown[]) {
+    new Logger().debug(message, ...args);
+  }
+
+  public static error(message?: unknown, ...args: unknown[]) {
+    new Logger().error(message, ...args);
+  }
+
+  public static info(message?: unknown, ...args: unknown[]) {
+    new Logger().info(message, ...args);
+  }
+
+  public static warn(message?: unknown, ...args: unknown[]) {
+    new Logger().warn(message, ...args);
+  }
+
+  public static security(message?: unknown, ...args: unknown[]) {
+    new Logger().security(message, ...args);
+  }
+
+  public static log(message?: unknown, ...args: unknown[]) {
+    new Logger().log(message, ...args);
+  }
+
+  public static newline() {
+    new Logger().newline();
+  }
+
+  /**
+   * Returns the caller's file and line number.
+   */
+  private static getCallerLocation(): string {
+    const stack = new Error().stack?.split('\n');
+    if (!stack) return '';
+
+    // The first lines are irrelevant, we want the caller of the logger
+    const callerLine = stack[3] || stack[2] || '';
+
+    // Extract file path and line number
+    const match = callerLine.match(/\((.*):(\d+):(\d+)\)/);
+    if (!match) return '';
+
+    const filePath = match[1];
+    const lineNumber = match[2];
+
+    return `${path.basename(filePath)}:${lineNumber}`;
+  }
+}

package/src/patch.ts

@@ -0,0 +1,181 @@
+import { PatchOperation } from './interfaces.js';
+import { JSONObject } from './types.js';
+import { Btc1Error } from './errors.js';
+
+/**
+ * Implementation of {@link https://datatracker.ietf.org/doc/html/rfc6902 | IETF RFC 6902 JSON Patch}.
+ *
+ * JavaScript Object Notation (JSON) Patch defines a JSON document structure for expressing a sequence of operations to
+ * apply to a JavaScript Object Notation (JSON) document; it is suitable for use with the HTTP PATCH method. The
+ * "application/json-patch+json" media type is used to identify such patch documents.
+ *
+ * @class Patch
+ * @type {Patch}
+ */
+export class Patch {
+  /**
+   * Applies a JSON Patch to a source document and returns the patched document.
+   * @param {JSONObject} sourceDocument The source document to patch.
+   * @param {PatchOperation[]} operations The JSON Patch operations to apply.
+   * @returns {JSONObject} The patched document.
+   * @throws {Error} If an unsupported operation is provided.
+   */
+  public apply(sourceDocument: JSONObject, operations: PatchOperation[]): JSONObject {
+    const patchedDocument = JSON.normalize(sourceDocument);
+
+    for (const operation of operations) {
+      const { op, path, value, from } = operation;
+
+      const segments = path.split('/').slice(1);
+
+      switch (op) {
+        case 'add':
+          this.setValue(patchedDocument, segments, value);
+          break;
+
+        case 'remove':
+          this.removeValue(patchedDocument, segments);
+          break;
+
+        case 'replace':
+          this.setValue(patchedDocument, segments, value);
+          break;
+
+        case 'move':{
+          if (!from) throw new Error('Missing \'from\' in move operation');
+          const fromSegments = from.split('/').slice(1);
+          const movedValue = this.getValue(patchedDocument, fromSegments);
+          this.removeValue(patchedDocument, fromSegments);
+          this.setValue(patchedDocument, segments, movedValue);
+          break;
+        }
+        case 'copy':{
+          if (!from) throw new Error('Missing \'from\' in copy operation');
+          const copiedValue = this.getValue(patchedDocument, from.split('/').slice(1));
+          this.setValue(patchedDocument, segments, copiedValue);
+          break;
+
+        }
+        case 'test':{
+          const existingValue = this.getValue(patchedDocument, segments);
+          if (JSON.stringify(existingValue) !== JSON.stringify(value)) {
+            throw new Btc1Error(`Test operation failed at path`, 'JSON_PATCH_APPLY_ERROR', { path });
+          }
+          break;
+        }
+        default:
+          throw new Btc1Error(`Unsupported JSON Patch operation`, 'JSON_PATCH_APPLY_ERROR', { op });
+      }
+    }
+
+    return patchedDocument;
+  }
+
+  /**
+ * Constructs a JSON Patch with a single operation (e.g. add service).
+ * @param {PatchOperation} patches - The patch operation to create.
+ * @param {string} patch.op - The patch operation type (e.g. 'add').
+ * @param {string} patch.path - The JSON Pointer path to apply the operation.
+ * @param {*} patch.value - The value to apply (if applicable).
+ * @returns {PatchOperation[]} A single-entry JSON Patch array.
+ */
+  public create(patches: PatchOperation[]): PatchOperation[] {
+    return patches.map(({ op, path, value, from }) => {
+      const operation: PatchOperation = { op, path };
+
+      if (value !== undefined) {
+        operation.value = value;
+      }
+
+      if (from !== undefined) {
+        operation.from = from;
+      }
+
+      return operation;
+    });
+  }
+
+  /**
+   * Find the diff between a source and target document constructing the patch operations from source => target.
+   * @param {JSONObject} sourceDocument The original JSON object.
+   * @param {JSONObject} targetDocument The target JSON object to transform into.
+   * @returns {PatchOperation[]} An array of JSON Patch operations.
+   */
+  public diff(sourceDocument: JSONObject, targetDocument: JSONObject, path: string): PatchOperation[] {
+    const operations: Array<PatchOperation> = [];
+    const sourceKeys = new Set(Object.keys(sourceDocument || {}));
+    const targetKeys = new Set(Object.keys(targetDocument || {}));
+
+    // Handle removed keys
+    for (const key of sourceKeys) {
+      if (!targetKeys.has(key)) {
+        operations.push({ op: 'remove', path: `${path}/${key}` });
+      }
+    }
+
+    // Handle added or updated keys
+    for (const key of targetKeys) {
+      const sourceVal = sourceDocument?.[key];
+      const targetVal = targetDocument?.[key];
+      const currentPath = `${path}/${key}`;
+
+      if (!(key in (sourceDocument || {}))) {
+        operations.push({ op: 'add', path: currentPath, value: targetVal });
+      } else if (typeof sourceVal === 'object' && sourceVal !== null && typeof targetVal === 'object' && targetVal !== null) {
+        operations.push(...this.diff(sourceVal, targetVal, currentPath));
+      } else if (JSON.stringify(sourceVal) !== JSON.stringify(targetVal)) {
+        operations.push({ op: 'replace', path: currentPath, value: targetVal });
+      }
+    }
+
+    return operations;
+  }
+
+  /**
+   * Gets the value at a given path in an object.
+   * @private
+   * @param {*} obj The object to get the value from.
+   * @param {string[]} path The path to the value.
+   * @returns {*} The value at the given path.
+   */
+  private getValue(obj: any, path: string[]): any {
+    return path.reduce((acc, key) => (acc && acc[key] !== undefined ? acc[key] : undefined), obj);
+  }
+
+
+  /**
+   * Sets the value at a given path in an object.
+   * @private
+   * @param {*} obj The object to set the value in.
+   * @param {string[]} path The path to the value.
+   * @param {*} value The value to set.
+   * @returns {*} The object with the value set.
+   */
+  private setValue(obj: any, path: string[], value: any): void {
+    let current = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+      const key = path[i];
+      if (!(key in current)) current[key] = {};
+      current = current[key];
+    }
+    current[path[path.length - 1]] = value;
+  }
+
+
+  /**
+   * Removes the value at a given path in an object.
+   * @private
+   * @param {*} obj The object to remove the value from.
+   * @param {string[]} path The path to the value.
+   * @returns {*} The object with the value removed.
+   */
+  private removeValue(obj: any, path: string[]): void {
+    let current = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+      const key = path[i];
+      if (!(key in current)) return;
+      current = current[key];
+    }
+    delete current[path[path.length - 1]];
+  }
+}

package/src/rdf-canonize.d.ts

@@ -0,0 +1,6 @@
+// rdf-canonize.d.ts
+declare module 'rdf-canonize' {
+    const rdfc: any;
+    export default rdfc;
+  }
+  

package/src/types.ts

@@ -0,0 +1,113 @@
+import { HDKey } from '@scure/bip32';
+
+/* Crypto Types */
+export type Hex = Uint8Array | string;
+export type SignatureHex = Hex;
+export type HashHex = Hex;
+
+export type Bytes = Uint8Array;
+export type DocumentBytes = Bytes;
+export type SignatureBytes = Bytes;
+export type ProofBytes = Bytes;
+export type HashBytes = Bytes;
+export type MessageBytes = Bytes;
+export type Entropy = Bytes | bigint;
+
+export type CompressedPublicKeyParityByte = 0x02 | 0x03;
+export type Bip340Encoding = string;
+export type Base58BtcPrefix = 'z';
+
+export type KeyBytes = Bytes;
+export type Point = {
+  x: Array<number>;
+  y: Array<number>;
+  parity: number;
+}
+export type PublicKeyObject = {
+  point: Point;
+  hex: Hex;
+  multibase: MultibaseObject;
+};
+export type SecretKeyObject = {
+  bytes: Array<number>;
+  seed?: string;
+  hex?: Hex;
+};
+export type SchnorrKeyPair = {
+  secretKey: KeyBytes;
+  publicKey: KeyBytes;
+};
+export type SchnorrKeyPairObject = {
+  secretKey: SecretKeyObject;
+  publicKey: PublicKeyObject;
+};
+export type MultibaseObject = {
+  address: string;
+  prefix: Bytes;
+  key: Array<number>;
+};
+export type HdWallet = {
+    mnemonic: string;
+    hdkey: HDKey
+};
+
+/* DID Types */
+export type DID = 'did';
+export type MethodName = string;
+export type MethodSpecificId = string;
+export type DecentralizedIdentifierExplicit = `${DID}:${MethodName}:${MethodSpecificId}`;
+export type DecentralizedIdentifier = string;
+export type Btc1MethodName = 'btcr2';
+export type Btc1DeterministicPrefix = 'k';
+export type Btc1ExternalPrefix = 'x';
+export type Btc1Prefix = `${Btc1DeterministicPrefix | Btc1ExternalPrefix}1`;
+export type Bech32Id = string;
+export type Btc1Id = `${Btc1Prefix}${Bech32Id}`
+export type Btc1IdentifierExplicit = `${DID}:${Btc1MethodName}:${Btc1Id}`;
+export type Btc1Identifier = string;
+export type Controller = Btc1Identifier;
+export type Id = 'initialKey';
+export type FullId = `${Controller}#${Id}`;
+export enum Btc1IdentifierTypes {
+    KEY = 'KEY',
+    EXTERNAL = 'EXTERNAL'
+}
+export enum Btc1IdentifierHrp {
+    k = 'k',
+    x = 'x'
+}
+export enum BitcoinNetworkNames {
+    bitcoin = 0,
+    signet = 1,
+    regtest = 2,
+    testnet3 = 3,
+    testnet4 = 4,
+    mutinynet = 5
+}
+export type KeyIdentifier = string;
+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 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 TwoDigits = `${number}${number}`;
+export type ThreeDigits = `${number}${number}${number}`;
+export type Year = `${1 | 2}${ThreeDigits}`;
+export type Month = TwoDigits;
+export type Day = TwoDigits;
+export type Hours = TwoDigits;
+export type Minutes = TwoDigits;
+export type Seconds = TwoDigits;
+export type UtcTimestamp = `${Year}-${Month}-${Day}T${Hours}:${Minutes}:${Seconds}`;
+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;