@did-btcr2/common 1.1.0

package/src/exts.ts

@@ -0,0 +1,293 @@
+import { Canonicalization } from './canonicalization.js';
+import { Patch } from './patch.js';
+import { JSONObject, Maybe, Prototyped, Unprototyped } from './types.js';
+
+/** Extend the global namespace */
+declare global {
+  /** Extend the global Array interface */
+  interface Array<T> {
+      /** Get the last element of the array */
+      last(): T | undefined;
+      /** Get the last element of the array */
+      [-1](): T | undefined;
+      /** Convert Array to Uint8Array */
+      toUint8Array(): Uint8Array;
+  }
+
+  /** Extend the global Buffer interface */
+   interface BufferConstructor {
+    /** Convert a hex string to a Buffer */
+    fromHex(hex: string): Buffer<ArrayBuffer>;
+    /** Convert a Uint8Array to a hex string */
+    toHex(ui8: Uint8Array): string;
+    /** Convert Buffer to Uint8Array */
+    toUint8Array(buf: Buffer<ArrayBuffer>): Uint8Array;
+  }
+
+  /** Extend the global Date interface */
+  interface Date {
+    /** Get the UTC date and time in ISO 8601 format */
+    getUTCDateTime(): string;
+    /** Convert date to Unix timestamp */
+    toUnix(): number;
+  }
+
+  /** Extend global JSON interface */
+  interface JSON {
+      /** Check if an object is a JSON object */
+      is(unknown: Maybe<JSONObject>): boolean;
+      /** Check if JSON string can be parsed to JSON object */
+      parsable(unknown: Maybe<string>): boolean;
+      /** Check if JSON object can be converted to JSON string */
+      stringifiable(unknown: Maybe<JSONObject>): boolean;
+      /** Check if JSON object is unprototyped [Object: null prototype] {} */
+      unprototyped(unknown: Maybe<Prototyped>): boolean;
+      /** Normalize unprototyped JSON object to prototyped JSON object */
+      normalize(unknown: Maybe<Unprototyped>): Prototyped;
+      /** Shallow copy of JSON object */
+      copy(o: JSONObject): JSONObject;
+      /** Clone (deep copy) of JSON object */
+      clone(o: JSONObject): JSONObject;
+      /** Deep copy of JSON object with replacement */
+      cloneReplace(o: JSONObject, e: RegExp, r: string): JSONObject;
+      /** Check if two objects are strictly equal */
+      equal(a: any, b: any): boolean;
+      /** Check if two objects are deeply equal */
+      deepEqual(a: any, b: any): boolean;
+      /** Delete key/value pair(s) from a JSON object */
+      delete(o: JSONObject, keys: Array<string | number | symbol>): JSONObject;
+      /** Sanitize a JSON object by removing any keys whose value is undefined */
+      sanitize(o: JSONObject): JSONObject;
+      /** Canonicalization object */
+      canonicalization: Canonicalization;
+      /** JSON Patch (IETF RFC 6902) */
+      patch: Patch;
+  }
+
+
+  /** Extend global Set interface */
+  interface Set<T> {
+    /** Get the difference between two sets */
+    difference(other: Set<T>): Set<T>;
+  }
+
+  interface String {
+    /** Convert to SCREAMING_SNAKE_CASE */
+    toSnakeScream(): string;
+    /** Convert to snake_case */
+    toSnake(): string;
+    /** Remove the last character from a string */
+    chop(): string;
+    /** Replace the end of a string */
+    replaceEnd(e: string | RegExp, r?: string): string;
+  }
+
+  /** Extend the global Uint8Array interface */
+  interface Uint8Array {
+    toArray(): number[];
+  }
+}
+
+/** Array Interface Extensions */
+Array.prototype.last = function <T>(): T | undefined {
+  return this[this.length - 1] ?? undefined;
+};
+
+Array.prototype[-1] = function <T>(): T | undefined {
+  return this.last();
+};
+
+Array.prototype.toUint8Array = function (): Uint8Array {
+  return new Uint8Array(this);
+};
+
+/** BufferConstructor/Buffer Interface Extensions */
+Buffer.fromHex = function (hex: string): Buffer<ArrayBuffer> {
+  return Buffer.from(hex, 'hex');
+};
+
+Buffer.toHex = function (ui8: Uint8Array): string {
+  return Buffer.from(ui8).toString('hex');
+};
+
+Buffer.toUint8Array = function (buf: Buffer<ArrayBuffer>): Uint8Array {
+  return new Uint8Array(buf);
+};
+
+/** Date Interface Extensions */
+Date.prototype.getUTCDateTime = function (): string {
+  return `${this.toISOString().slice(0, -5)}Z`;
+};
+
+Date.prototype.toUnix = function (): number {
+  const time = this.getTime();
+  if (isNaN(time)) {
+    throw new Error(`Invalid date string: "${this}"`);
+  }
+  return time;
+};
+
+/** JSON Interface Extensions */
+JSON.is = function (unknown: Maybe<JSONObject>): boolean {
+  if (unknown === null || typeof unknown !== 'object') return false;
+  if (Array.isArray(unknown))
+    return unknown.every(item => Object.getPrototypeOf(item) !== null);
+  else
+    return Object.getPrototypeOf(unknown) === null;
+};
+
+JSON.parsable = function (unknown: Maybe<string>): boolean {
+  try {
+    JSON.parse(unknown);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+JSON.stringifiable = function (unknown: Maybe<JSONObject>): boolean {
+  try {
+    JSON.stringify(unknown);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+JSON.unprototyped = function (unknown: Maybe<Unprototyped>): boolean {
+  if (Array.isArray(unknown)) {
+    return unknown.every(item => Object.getPrototypeOf(item) === null);
+  }
+  return Object.getPrototypeOf(unknown) === null;
+};
+
+JSON.normalize = function (unknown: Maybe<Unprototyped>): Prototyped {
+  try {
+    return JSON.parse(JSON.stringify(unknown));
+  } catch {
+    throw new Error('The object is not unprotocyped');
+  }
+};
+
+JSON.copy = function (o: JSONObject): JSONObject {
+  return Object.assign({}, o);
+};
+
+JSON.clone = function (o: JSONObject): JSONObject {
+  return JSON.parse(JSON.stringify(o));
+};
+
+JSON.cloneReplace = function (o: JSONObject, e: RegExp, r: string): JSONObject {
+  return JSON.parse(JSON.stringify(o).replaceAll(e, r));
+};
+
+JSON.equal = function (a: any, b: any): boolean {
+  return a === b;
+};
+
+JSON.deepEqual = function (a: any, b: any): boolean {
+  if(JSON.equal(a, b)) return true;
+
+  if (a === null || b === null || typeof a !== typeof b) return false;
+
+  if (typeof a === 'object') {
+    const isArrayA = Array.isArray(a);
+    const isArrayB = Array.isArray(b);
+    if (isArrayA !== isArrayB) return false;
+
+    if (isArrayA && isArrayB) {
+      if (a.length !== b.length) return false;
+      for (let i = 0; i < a.length; i++) {
+        if (!this.deepEqual(a[i], b[i])) return false;
+      }
+      return true;
+    } else {
+      const keysA = Object.keys(a);
+      const keysB = Object.keys(b);
+      if (keysA.length !== keysB.length) return false;
+
+      for (const key of keysA) {
+        if (!Object.prototype.hasOwnProperty.call(b, key)) {
+          return false;
+        }
+        if (!this.deepEqual(a[key], b[key])) {
+          return false;
+        }
+      }
+      return true;
+    }
+  }
+
+  return false;
+};
+
+JSON.delete = function(o: JSONObject, keys: Array<string | number | symbol>): JSONObject {
+  if (!JSON.is(o)) return o;
+
+  for(const key of keys) {
+    if (Object.prototype.hasOwnProperty.call(o, key)) {
+      delete o[key];
+    }
+
+    for (const key in o) {
+      if (typeof o[key] === 'object') {
+        o[key] = this.delete(o[key], [key]);
+      }
+    }
+  }
+
+  return o;
+};
+
+JSON.sanitize = function (o: JSONObject): JSONObject {
+  for (const key of Object.keys(o)) {
+    if (o[key] === undefined) {
+      delete o[key];
+    }
+  }
+  return o;
+};
+
+JSON.canonicalization = new Canonicalization();
+JSON.patch = new Patch();
+
+/** Set Interface Extensions */
+Set.prototype.difference = function <T>(other: Set<T>): Set<T> {
+  const result = new Set<T>(this);
+  for (const item of other) {
+    if (result.has(item)) {
+      result.delete(item);
+    }
+  }
+  return result;
+};
+
+/** String Interface Extensions */
+String.prototype.toSnake = function (): string {
+  return this
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .toLowerCase();
+};
+
+String.prototype.toSnakeScream = function (): string {
+  return this.toSnake().toUpperCase();
+};
+
+String.prototype.chop = function (): string {
+  return this.length > 0 ? this.slice(0, -1) : '';
+};
+
+String.prototype.replaceEnd = function (e: string | RegExp, r?: string): string {
+  const pattern = e instanceof RegExp
+    ? new RegExp(e.source.endsWith('$') ? e.source : `${e.source}$`, e.flags.replace('g', ''))
+    : new RegExp(`${e.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}$`);
+
+  return this.replace(pattern, r ?? '');
+};
+
+/** Uint8Array Interface Extensions */
+Uint8Array.prototype.toArray = function (): number[] {
+  return Array.from(this);
+};
+
+export default global;

package/src/index.ts

@@ -0,0 +1,11 @@
+import './exts.js';
+
+export * from './canonicalization.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './interfaces.js';
+export * from './logger.js';
+export * from './patch.js';
+export * from './types.js';
+
+export * from './exts.js';

package/src/interfaces.ts

@@ -0,0 +1,311 @@
+export type JsonPatch = Array<PatchOperation>;
+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
+  from?: string; // Required for move, copy
+}
+
+/**
+ * The unsigned payload object containing instructions for how to update a
+ * did:btcr2 DID Document. Once signed, it becomes a
+ * {@link DidUpdateInvocation | DID Update Invocation}
+ *
+ * DID BTCR2
+ * {@link https://dcdpr.github.io/did-btcr2/#construct-did-update-payload | 4.3.1 Construct DID Update Payload}.
+ *
+ * Found in DID BTCR2 Specification {@link https://dcdpr.github.io/did-btcr2/#dereference-root-capability-identifier | Section 9.4.2}
+ * @example
+ * ```
+ * {
+ *  "@context": [
+ *    "https://w3id.org/zcap/v1",
+ *    "https://w3id.org/security/data-integrity/v2",
+ *    "https://w3id.org/json-ld-patch/v1"
+ *  ],
+ *  "patch": [
+ *    {
+ *      "op": "add",
+ *      "path": "/service/4",
+ *      "value": {
+ *        "id": "#linked-domain",
+ *        "type": "LinkedDomains",
+ *        "serviceEndpoint": "https://contact-me.com"
+ *      }
+ *    }
+ *   ],
+ *   "proof":{
+ *   "type": "DataIntegrityProof,
+ *   "cryptosuite": "schnorr-secp256k1-jcs-2025,
+ *   "verificationMethod": "did:btcr2:k1qqpuwwde82nennsavvf0lqfnlvx7frrgzs57lchr02q8mz49qzaaxmqphnvcx#initialKey,
+ *   "invocationTarget": "did:btcr2:k1qqpuwwde82nennsavvf0lqfnlvx7frrgzs57lchr02q8mz49qzaaxmqphnvcx,
+ *   "capability": "urn:zcap:root:did%3Abtc1%3Ak1qqpuwwde82nennsavvf0lqfnlvx7frrgzs57lchr02q8mz49qzaaxmqphnvcx,
+ *   "capabilityAction": "Write,
+ *   "proofPurpose": "assertionMethod,
+ *   "proofValue": "z381yXYmxU8NudZ4HXY56DfMN6zfD8syvWcRXzT9xD9uYoQToo8QsXD7ahM3gXTzuay5WJbqTswt2BKaGWYn2hHhVFKJLXaD
+ *  }
+ * }
+ * ```
+ */
+export interface DidUpdatePayload {
+    /**
+     * JSON-LD context URIs for interpreting this payload, including contexts
+     * for ZCAP (capabilities), Data Integrity proofs, and JSON-LD patch ops.
+     */
+    '@context': string[];
+
+    /**
+     * A JSON Patch (or JSON-LD Patch) object defining the mutations to apply to
+     * the DID Document. Applying this patch to the current DID Document yields
+     * the new DID Document (which must remain valid per DID Core spec).
+     */
+    patch: JsonPatch;
+
+    /**
+     * The multihash of the current (source) DID Document, encoded as a multibase
+     * base58-btc string. This is a SHA-256 hash of the canonicalized source DID
+     * Document, used to ensure the patch is applied to the correct document state.
+     */
+    sourceHash: string;
+
+    /**
+     * The multihash of the updated (target) DID Document, encoded as multibase
+     * base58-btc. This is the SHA-256 hash of the canonicalized
+     * DID Document after applying the patch, used to verify the update result.
+     */
+    targetHash: string;
+
+    /**
+     * The version number of the DID Document after this update.
+     * It is equal to the previous document version + 1.
+     */
+    targetVersionId: number;
+
+    /**
+     * A proof object (Data Integrity proof) that authorizes this update.
+     * It is a JSON-LD proof indicating a capability invocation on the DID's
+     * root capability, typically signed with the DID's verification key (using
+     * Schnorr secp256k1 in did:btcr2).
+     */
+    proof?: Proof;
+}
+
+/**
+ * An extension of {@link DidUpdatePayload | DID Update Payload} containing a
+ * Data Integrity proof that authorizes the update. Once signed, the spec calls
+ * this an 'invoked DID Update Payload' or 'didUpdateInvocation'.
+ *
+ * DID BTCR2
+ * {@link https://dcdpr.github.io/did-btcr2/#invoke-did-update-payload | 4.3.2 Invoke DID Update Payload}
+ * and
+ * {@link https://dcdpr.github.io/did-btcr2/#root-didbtc1-update-capabilities | 9.4 Root did:btcr2 Update Capabilities}.
+ */
+export interface DidUpdateInvocation extends DidUpdatePayload {
+  proof: Proof;
+}
+
+/**
+ * Proof is the Data Integrity proof (ZCAP-LD style) added to a did:btcr2 DID
+ * Update Payload.
+ *
+ * Verifiable Credential Data Integrity
+ * {@link https://w3c.github.io/vc-data-integrity/#proofs | 2.1 Proofs}.
+ *
+ * DID BTCR2
+ * {@link https://dcdpr.github.io/did-btcr2/#invoke-did-update-payload | 4.3.2 Invoke DID Update Payload}.
+ */
+export interface Proof extends ProofOptions {
+  /**
+   * The cryptographic signature value. The exact property name may be defined
+   * by the cryptosuite (for instance, `proofValue` for a raw signature) and
+   * contains the actual signature bytes in an encoded form.
+   */
+  proofValue: string;
+}
+
+/**
+ * Proof Options used when adding a Data Integrity proof (ZCAP-LD style)
+ * to a did:btcr2 DID Update Payload.
+ *
+ * Verifiable Credential Data Integrity
+ * {@link https://w3c.github.io/vc-data-integrity/#proofs | 2.1 Proofs}.
+ *
+ * DID BTCR2
+ * {@link https://dcdpr.github.io/did-btcr2/#invoke-did-update-payload | 4.3.2 Invoke DID Update Payload}.
+ */
+export interface ProofOptions {
+  /**
+   * The proof type—per the spec’s example, "DataIntegrityProof".
+   */
+  type: string;
+
+  /**
+   * The cryptographic suite used, e.g. "schnorr-secp256k1-jcs-2025".
+   */
+  cryptosuite: string;
+
+  /**
+   * DID URL of the key invoking the capability, i.e. the DID
+   * Document's verificationMethod.id used to sign this update.
+   */
+  verificationMethod: string;
+
+  /**
+   * The purpose of the proof, which the spec sets to "capabilityInvocation".
+   */
+  proofPurpose: string;
+
+  /**
+   * The root capability being invoked. In did:btcr2, this is typically
+   * `urn:zcap:root:<urlencoded-did>` (see Section 9.4.1).
+   */
+  capability?: string;
+
+  /**
+   * The action performed under the capability—set to "Write" in the spec
+   * for DID document updates.
+   */
+  capabilityAction?: string;
+
+  /**
+   * (Optional) Some cryptosuites or proofs may include a timestamp, domain,
+   * or challenge. Although not explicitly required in the doc's steps, they
+   * often appear in Data Integrity proofs and may be included as needed.
+   */
+  created?: string;
+  domain?: string;
+  challenge?: string;
+}
+
+/**
+ * A JSON object that maps did:btcr2 identifiers to the CID of the corresponding
+ * DID Update Payload.
+ *
+ * DID BTCR2
+ * {@link https://dcdpr.github.io/did-btcr2/#cidaggregate-beacon | 5.2 CIDAggregate Beacons}.
+ */
+export interface DidUpdateBundle {
+  /**
+   * The keys are did:btcr2 identifiers as strings. The values are
+   * IPFS CIDs (or other CAS IDs) referencing the actual DID Update Payload.
+   */
+  [didBtc1Identifier: string]: string;
+}
+
+/**
+ * A container for out-of-band data the resolver may need. This includes the
+ * initial DID document if it isn't stored in IPFS, plus references for each
+ * on-chain Beacon signal.
+ *
+ * DID BTCR2
+ * {@link https://dcdpr.github.io/did-btcr2/#sidecar-initial-document-validation | 4.2.1.2.1 Sidecar Initial Document Validation},
+ * {@link https://dcdpr.github.io/did-btcr2/#resolve-target-document | 4.2.2 Resolve Target Document},
+ * {@link https://dcdpr.github.io/did-btcr2/#traverse-blockchain-history | 4.2.2.2 Traverse Blockchain History},
+ * {@link https://dcdpr.github.io/did-btcr2/#find-next-signals | 4.2.2.3 Find Next Signals}.
+ */
+export interface SidecarData {
+  /**
+   * The initial DID Document for an externally created did:btcr2,
+   * if not fetched from IPFS or another CAS.
+   */
+  initialDocument?: Record<string, any>; // or a typed DIDDocument from W3C DID Core
+
+  /**
+   * A map from Bitcoin transaction IDs to the sidecar info about that signal.
+   * Each signal might provide a single DID Update Payload, or (for aggregator beacons)
+   * a bundle or proofs.
+   */
+  signalsMetadata: {
+    [txid: string]: SignalSidecarData;
+  };
+}
+
+/**
+ * Sidecar data for a specific Beacon Signal. Different Beacon types store different fields.
+ * - SingletonBeacon might just store one `updatePayload`.
+ * - CIDAggregateBeacon might store `updateBundle` + an `updatePayload`.
+ * - SMTAggregateBeacon might store `updatePayload` + a `smtProof`.
+ */
+export interface SignalSidecarData {
+  updatePayload?: DidUpdateInvocation;   // or DidUpdatePayload if not yet invoked
+  updateBundle?: DidUpdateBundle;        // for CIDAggregateBeacon
+  /**
+   * For SMTAggregateBeacon, a Merkle proof that the `updatePayload`
+   * is included (or not included) in the aggregator's Sparse Merkle Tree.
+   */
+  smtProof?: SmtProof;
+}
+
+/**
+ * A placeholder for the actual Sparse Merkle Tree inclusion/non-inclusion proof.
+ *
+ * DID BTCR2
+ * {@link https://dcdpr.github.io/did-btcr2/#smtaggregate-beacon | 5.3 SMTAggregate Beacon}.
+ */
+export interface SmtProof {
+  // Implementation-specific structure for SMT proofs, e.g.:
+  siblingHashes: string[];
+  leafIndex?: string;
+}
+
+/**
+ * The known Beacon types from the spec.
+ */
+export type BeaconType =
+  | 'SingletonBeacon'
+  | 'CIDAggregateBeacon'
+  | 'SMTAggregateBeacon';
+
+/**
+ * Represents a transaction discovered on the Bitcoin blockchain that
+ * spends from a Beacon address, thus announcing DID updates.
+ *
+ * DID BTCR2
+ * {@link https://dcdpr.github.io/did-btcr2/#find-next-signals | 4.2.2.3 Find Next Signals}
+ * and
+ * {@link https://dcdpr.github.io/did-btcr2/#process-beacon-signals | 4.2.2.4 Process Beacon Signals}.
+ */
+export interface BeaconSignal {
+  /**
+   * The DID Document's `service` ID of the Beacon that produced this signal, e.g. "#cidAggregateBeacon".
+   */
+  beaconId: string;
+
+  /**
+   * The type of Beacon, e.g. "SingletonBeacon".
+   */
+  beaconType: BeaconType;
+
+  /**
+   * The Bitcoin transaction that is the actual on-chain Beacon Signal.
+   * Typically you'd store a minimal subset or a reference/ID for real usage.
+   */
+  tx: any;
+}
+
+/**
+ * A ZCAP-LD root capability object that authorizes updates for a particular did:btcr2.
+ *
+ * DID BTCR2
+ * {@link https://dcdpr.github.io/did-btcr2/#derive-root-capability-from-didbtc1-identifier | 9.4.1 Derive Root Capability from did:btcr2 Identifier}.
+ *
+ * @example Found in DID BTCR2 Specification Section 9.4.1
+ * ```
+ * {
+ *   "@context": "https://w3id.org/zcap/v1",
+ *   "id": "urn:zcap:root:did%3Abtc1%3Ak1qq...",
+ *   "controller": "did:btcr2:k1qq...",
+ *   "invocationTarget": "did:btcr2:k1qq..."
+ * }
+ * ```
+ */
+export interface DidBtc1RootCapability {
+  '@context': string | string[]; // e.g. "https://w3id.org/zcap/v1"
+  id: string;                    // e.g. "urn:zcap:root:<urlencoded-did>"
+  controller: string;           // the DID
+  invocationTarget: string;     // same as DID
+}

package/src/logger.browser.ts

@@ -0,0 +1,92 @@
+export enum Env {
+    Development = 'development',
+    Production = 'production',
+    Test = 'test',
+}
+
+export type Level = 'debug' | 'error' | 'info' | 'log' | 'warn' | 'security';
+
+export const NODE_ENV: Env =
+    (typeof process !== 'undefined' && (process.env?.NODE_ENV as Env)) ||
+    Env.Development;
+
+// Browser-friendly level "styles" using CSS in console
+const LEVEL_CSS: Record<Level, string> = {
+  debug    : 'color: #16a34a; font-weight: 600;',
+  error    : 'color: #ef4444; font-weight: 600;',
+  info     : 'color: #3b82f6; font-weight: 600;',
+  log      : 'color: #6b7280;',
+  warn     : 'color: #eab308; font-weight: 600;',
+  security : 'color: #a855f7; font-weight: 700;',
+};
+
+const LOG_LEVELS: Record<Env, Level[]> = {
+  development : ['debug', 'info', 'log', 'warn', 'security'],
+  test        : ['log', 'info', 'error'],
+  production  : ['error'],
+};
+
+// 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',
+};
+
+export class Logger {
+  private levels: Level[];
+  private namespace?: string;
+
+  constructor(namespace?: string) {
+    this.levels = LOG_LEVELS[NODE_ENV] || [];
+    this.namespace = namespace ?? 'did-btcr2-js';
+  }
+
+  private _log(level: Level, message?: unknown, ...args: unknown[]) {
+    if (!this.levels.includes(level)) return;
+
+    const ts = new Date().toISOString();
+    const ns = this.namespace ? `[${this.namespace}]` : '';
+    const method = LEVEL_METHODS[level];
+
+    // %c applies CSS to the next string token
+    (console[method] as (...a: any[]) => void)(
+      '%c' + ts + '%c ' + ns + ' ' + level + ':%c ' + String(message ?? ''),
+      'color:#9ca3af;',           // timestamp (gray)
+      'color:#9ca3af;',           // namespace (same gray)
+      LEVEL_CSS[level],
+      ...args,
+    );
+  }
+
+  public debug(m?: unknown, ...a: unknown[]) { this._log('debug', m, ...a); return this; }
+  public error(m?: unknown, ...a: unknown[]) { this._log('error', m, ...a); return this; }
+  public info(m?: unknown, ...a: unknown[]) { this._log('info', m, ...a); return this; }
+  public warn(m?: unknown, ...a: unknown[]) { this._log('warn', m, ...a); return this; }
+  public security(m?: unknown, ...a: unknown[]) { this._log('security', m, ...a); return this; }
+  public log(m?: unknown, ...a: unknown[]) { this._log('log', m, ...a); return this; }
+  public newline() { console.log(); return this; }
+
+  // Static convenience API
+  public static debug(m?: unknown, ...a: unknown[]) { new Logger().debug(m, ...a); }
+  public static error(m?: unknown, ...a: unknown[]) { new Logger().error(m, ...a); }
+  public static info(m?: unknown, ...a: unknown[]) { new Logger().info(m, ...a); }
+  public static warn(m?: unknown, ...a: unknown[]) { new Logger().warn(m, ...a); }
+  public static security(m?: unknown, ...a: unknown[]) { new Logger().security(m, ...a); }
+  public static log(m?: unknown, ...a: unknown[]) { new Logger().log(m, ...a); }
+  public static newline() { new Logger().newline(); }
+
+  // Keep signature but avoid Node 'path' – do a lightweight parse
+  // (unused by default; safe if you later enable it)
+  private static getCallerLocation(): string {
+    const stack = new Error().stack?.split('\n');
+    const line = stack?.[3] || stack?.[2] || '';
+    const match = line.match(/\((.*):(\d+):(\d+)\)/) || line.match(/at (.*):(\d+):(\d+)/);
+    if (!match) return '';
+    const file = (match[1] || '').split(/[\\/]/).pop() || '';
+    return `${file}:${match[2]}`;
+  }
+}