@did-btcr2/common 3.1.0 → 5.0.0

package/src/canonicalization.ts

@@ -1,36 +1,24 @@
 import { sha256 } from '@noble/hashes/sha2';
-import { bytesToHex } from '@noble/hashes/utils';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
 import { canonicalize as jcsa } from 'json-canonicalize';
 import { base58btc } from 'multiformats/bases/base58';
 import { CanonicalizationError } from './errors.js';
-import { CanonicalizationAlgorithm, CanonicalizationEncoding, HashBytes } from './types.js';
+import { CanonicalizationAlgorithm, CanonicalizationEncoding, HashBytes, HexString } from './types.js';
+import { base64url } from 'multiformats/bases/base64';
+
+export interface CanonicalizationOptions {
+  algorithm?: CanonicalizationAlgorithm;
+  encoding?: CanonicalizationEncoding;
+}
 
 /**
  * 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).
+ * algorithms and encoding formats (hex and base58btc).
  * @class Canonicalization
  * @type {Canonicalization}
  */
 export class Canonicalization {
-  private readonly _defaultAlgorithm: CanonicalizationAlgorithm;
-
-  /**
-   * Initializes the Canonicalization class with the specified algorithm.
-   * @param {CanonicalizationAlgorithm} algorithm The canonicalization algorithm to use ('jcs').
-   */
-  constructor(algorithm: CanonicalizationAlgorithm = 'jcs') {
-    this._defaultAlgorithm = Canonicalization.normalizeAlgorithm(algorithm);
-  }
-
-  /**
-   * Gets the canonicalization algorithm.
-   * @returns {CanonicalizationAlgorithm} The current canonicalization algorithm.
-   */
-  get algorithm(): CanonicalizationAlgorithm {
-    return this._defaultAlgorithm;
-  }
-
   /**
    * Normalizes the canonicalization algorithm.
    * @param {CanonicalizationAlgorithm} algorithm
@@ -53,7 +41,7 @@ export class Canonicalization {
    */
   static normalizeEncoding(encoding: CanonicalizationEncoding): CanonicalizationEncoding {
     const normalized = encoding.toLowerCase() as CanonicalizationEncoding;
-    if (normalized !== 'hex' && normalized !== 'base58') {
+    if (!['hex', 'base58btc', 'base64url'].includes(normalized)) {
       throw new CanonicalizationError(`Unsupported encoding: ${encoding}`, 'ENCODING_ERROR');
     }
     return normalized;
@@ -70,24 +58,22 @@ export class Canonicalization {
    *
    * @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 {CanonicalizationEncoding} [options.encoding='hex'] The encoding format ('hex' or 'base58btc').
    * @param {CanonicalizationAlgorithm} [options.algorithm] The canonicalization algorithm to use.
    * @returns {string} The final SHA-256 hash bytes as a hex string.
    */
-  process(object: Record<any, any>, options: {
-    encoding?: CanonicalizationEncoding;
-    algorithm?: CanonicalizationAlgorithm;
-    multibase?: boolean;
-  } = {}): string {
-    const algorithm = Canonicalization.normalizeAlgorithm(options.algorithm ?? this._defaultAlgorithm);
-    const encoding = Canonicalization.normalizeEncoding(options.encoding ?? 'hex');
+  static process(object: Record<any, any>, options?: CanonicalizationOptions): string {
+    // Normalize the algorithm
+    const algorithm = Canonicalization.normalizeAlgorithm(options?.algorithm ?? 'jcs');
+    // Normalize the encoding
+    const encoding = Canonicalization.normalizeEncoding(options?.encoding ?? 'hex');
 
     // Step 1: Canonicalize
     const canonicalized = this.canonicalize(object, algorithm);
     // Step 2: Hash
-    const hashed = this.hash(canonicalized);
+    const hashed = this.toHash(canonicalized);
     // Step 3: Encode
-    const encoded = this.encode(hashed, encoding, options.multibase ?? false);
+    const encoded = this.encode(hashed, encoding);
     // Return the encoded string
     return encoded;
   }
@@ -98,7 +84,7 @@ export class Canonicalization {
    * @param {CanonicalizationAlgorithm} [algorithm] The algorithm to use.
    * @returns {string} The canonicalized object.
    */
-  canonicalize(object: Record<any, any>, algorithm: CanonicalizationAlgorithm = this._defaultAlgorithm): string {
+  static canonicalize(object: Record<any, any>, algorithm: CanonicalizationAlgorithm = 'jcs'): string {
     switch (Canonicalization.normalizeAlgorithm(algorithm)) {
       case 'jcs':
         return this.jcs(object);
@@ -112,7 +98,7 @@ export class Canonicalization {
    * @param {Record<any, any>} object The object to canonicalize.
    * @returns {string} The canonicalized object.
    */
-  jcs(object: Record<any, any>): string {
+  static jcs(object: Record<any, any>): string {
     return jcsa(object);
   }
 
@@ -121,44 +107,121 @@ export class Canonicalization {
    * @param {string} canonicalized The canonicalized object.
    * @returns {HashBytes} The SHA-256 HashBytes (Uint8Array).
    */
-  hash(canonicalized: string): HashBytes {
+  static toHash(canonicalized: string): HashBytes {
     return sha256(canonicalized);
   }
 
   /**
-   * Step 3: Encodes SHA-256 hashed, canonicalized object as a hex or base58 string.
+   * Step 3: Encodes SHA-256 hashed, canonicalized object as a hex or base58btc string.
    * @param {string} canonicalizedhash The canonicalized object to encode.
-   * @param {CanonicalizationEncoding} encoding The encoding format ('hex' or 'base58').
+   * @param {CanonicalizationEncoding} encoding The encoding format ('hex' or 'base58btc').
    * @throws {CanonicalizationError} If the encoding format is not supported.
    * @returns {string} The encoded string.
    */
-  encode(canonicalizedhash: HashBytes, encoding: CanonicalizationEncoding = 'hex', multibase: boolean = false): string {
+  static encode(canonicalizedhash: HashBytes, encoding: CanonicalizationEncoding = 'hex'): string {
+    // Normalize encoding
     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;
+
+    // If encoding is hex, encode to hex
+    if (normalized === 'hex') {
+      return this.toHex(canonicalizedhash);
     }
+
+    // If encoding is base58btc, encode to base58btc
+    if (normalized === 'base58btc') {
+      return this.toBase58(canonicalizedhash);
+    }
+
+    // If encoding is base64url, encode to base64url
+    if (normalized === 'base64url') {
+      return this.toBase64Url(canonicalizedhash);
+    }
+
+    // Throw error if encoding is unsupported
     throw new CanonicalizationError(`Unsupported encoding: ${encoding}`, 'ENCODING_ERROR');
   }
 
+  /**
+   * Decodes SHA-256 hashed, canonicalized object as a hex or base58btc string.
+   * @param {string} canonicalizedhash The canonicalized object to encode.
+   * @param {CanonicalizationEncoding} encoding The encoding format ('hex' or 'base58btc').
+   * @throws {CanonicalizationError} If the encoding format is not supported.
+   * @returns {string} The encoded string.
+   */
+  static decode(canonicalizedhash: string, encoding: CanonicalizationEncoding = 'hex'): HashBytes {
+    // Normalize encoding
+    const normalized = Canonicalization.normalizeEncoding(encoding);
+
+    // If encoding is hex, decode from hex
+    if (normalized === 'hex') {
+      return this.fromHex(canonicalizedhash);
+    }
+
+    // If encoding is base58btc, decode from base58btc
+    if (normalized === 'base58btc') {
+      return this.fromBase58(canonicalizedhash);
+    }
+
+    if(normalized === 'base64url') {
+      return this.fromBase64Url(canonicalizedhash);
+    }
+
+    // Throw error if encoding is unsupported
+    throw new CanonicalizationError(`Unsupported encoding: ${encoding}`, 'DECODING_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.
    */
-  hex(hashBytes: HashBytes): string {
+  static toHex(hashBytes: HashBytes): string {
     return bytesToHex(hashBytes);
   }
 
+  /**
+   * Decodes a hex string to HashBytes (Uint8Array).
+   * @param {HexString} hexString The hash as a hex string.
+   * @returns {HashBytes} The hash bytes.
+   */
+  static fromHex(hexString: HexString): HashBytes {
+    return hexToBytes(hexString);
+  }
+
   /**
    * 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.
    */
-  base58(hashBytes: HashBytes): string {
-    const encoded = base58btc.encode(hashBytes);
-    return encoded.startsWith('z') ? encoded.slice(1) : encoded;
+  static toBase58(hashBytes: HashBytes): string {
+    return base58btc.encode(hashBytes);
+  }
+
+  /**
+   * Decodes a base58btc string to HashBytes (Uint8Array).
+   * @param {string} b58str The hash as a base58btc string.
+   * @returns {HashBytes} The hash bytes.
+   */
+  static fromBase58(b58str: string): HashBytes {
+    return base58btc.decode(b58str);
+  }
+
+  /**
+   * Step 3.2: Encodes HashBytes (Uint8Array) to a base64url string.
+   * @param {HashBytes} hashBytes The hash as a Uint8Array.
+   * @returns {string} The hash as a base64url string.
+   */
+  static toBase64Url(hashBytes: HashBytes): string {
+    return base64url.encode(hashBytes);
+  }
+
+  /**
+   * Decodes a base64url string to HashBytes (Uint8Array).
+   * @param {string} b64urlstr The hash as a base64url string.
+   * @returns {HashBytes} The hash bytes.
+   */
+  static fromBase64Url(b64urlstr: string): HashBytes {
+    return base64url.decode(b64urlstr);
   }
 
   /**
@@ -167,12 +230,16 @@ export class Canonicalization {
    * @param {Record<any, any>} object The object to process.
    * @returns {Promise<HashBytes>} The final SHA-256 hash bytes.
    */
-  canonicalhash(
+  static andHash(
     object: Record<any, any>,
-    algorithm: CanonicalizationAlgorithm = this._defaultAlgorithm
+    algorithm: CanonicalizationAlgorithm = 'jcs'
   ): HashBytes {
+    // Step 1: Canonicalize
     const canonicalized = this.canonicalize(object, algorithm);
-    return this.hash(canonicalized);
+    // Step 2: Hash
+    const hashed = this.toHash(canonicalized);
+    // Return canonicalized hash bytes
+    return hashed;
   }
 
   /**
@@ -181,17 +248,32 @@ export class Canonicalization {
    * @param {string} canonicalized The canonicalized object to hash.
    * @returns {string} The SHA-256 hash as a hex string.
    */
-  hashhex(canonicalized: string): string {
-    return this.encode(this.hash(canonicalized), 'hex');
+  static andHashToHex(canonicalized: string): string {
+    // Step 2: Hash
+    const hashed = this.toHash(canonicalized);
+    // Step 3: Encode (Hex)
+    const hexed = this.toHex(hashed);
+    // Return the hashed encoded string
+    return hexed;
+  }
+
+  /**
+   * Computes the SHA-256 hashes of canonicalized object and encodes it as a base58btc string.
+   * Step 2-3: Hash → Encode(base58btc).
+   * @param {string} canonicalized The canonicalized object to hash.
+   * @returns {string} The SHA-256 hash as a base58btc string.
+   */
+  static andHashToBase58(canonicalized: string): string {
+    return this.encode(this.toHash(canonicalized), 'base58btc');
   }
 
   /**
-   * Computes the SHA-256 hashes of canonicalized object and encodes it as a base58 string.
-   * Step 2-3: Hash → Encode(base58).
+   * Computes the SHA-256 hashes of canonicalized object and encodes it as a base64url string.
+   * Step 2-3: Hash → Encode(base64url).
    * @param {string} canonicalized The canonicalized object to hash.
-   * @returns {string} The SHA-256 hash as a base58 string.
+   * @returns {string} The SHA-256 hash as a base64url string.
    */
-  hashbase58(canonicalized: string): string {
-    return this.encode(this.hash(canonicalized), 'base58', false);
+  static andHashToBase64Url(canonicalized: string): string {
+    return this.toBase64Url(this.toHash(canonicalized));
   }
 }

package/src/errors.ts

@@ -82,7 +82,10 @@ export enum MethodErrorCode {
   INVALID_UPDATE = 'INVALID_UPDATE',
 
   /** The proof is missing or has a malformed domain field. */
-  INVALID_DOMAIN_ERROR = 'INVALID_DOMAIN_ERROR'
+  INVALID_DOMAIN_ERROR = 'INVALID_DOMAIN_ERROR',
+
+  /** Options required for resolution are missing. */
+  MISSING_RESOLUTION_OPTIONS = 'MISSING_RESOLUTION_OPTIONS'
 }
 
 export const {
@@ -111,7 +114,8 @@ export const {
   INVALID_SIDECAR_DATA,
   MISSING_UPDATE_DATA,
   INVALID_UPDATE,
-  INVALID_DOMAIN_ERROR
+  INVALID_DOMAIN_ERROR,
+  MISSING_RESOLUTION_OPTIONS
 } = MethodErrorCode;
 
 export type ErrorOptions = {

package/src/index.ts

@@ -1,7 +1,6 @@
 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 './types.js';

package/src/json-patch.ts

@@ -1,10 +1,20 @@
 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;
 
+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?: unknown; // Required for add, replace, test
+  from?: string; // Required for move, copy
+}
+
 /**
  * Thin wrapper around fast-json-patch to keep a stable API within this package.
  * @class JSONPatch

package/src/types.ts

@@ -26,13 +26,13 @@ export type Point = {
 }
 export type PublicKeyObject = {
   point: Point;
-  hex: Hex;
+  hex: HexString;
   multibase: MultibaseObject;
 };
 export type SecretKeyObject = {
   bytes: Array<number>;
   seed?: string;
-  hex?: Hex;
+  hex?: HexString;
 };
 export type SchnorrKeyPair = {
   secretKey: KeyBytes;
@@ -70,7 +70,6 @@ export enum BitcoinNetworkNames {
 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 JsonPrimitive = string | number | boolean | null;
@@ -98,5 +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 CanonicalizationEncoding = 'hex' | 'base58';
+export type CanonicalizationEncoding = 'hex' | 'base58btc' | 'base64url';
 export type UnixTimestamp = number;

package/dist/cjs/interfaces.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=interfaces.js.map

package/dist/cjs/interfaces.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":""}

package/dist/esm/interfaces.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=interfaces.js.map

package/dist/esm/interfaces.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":""}

package/dist/types/interfaces.d.ts

@@ -1,11 +0,0 @@
-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?: unknown;
-    from?: string;
-}

package/dist/types/interfaces.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC;AAC9C,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAClG;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,WAAW,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/src/interfaces.ts

@@ -1,11 +0,0 @@
-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?: unknown; // Required for add, replace, test
-  from?: string; // Required for move, copy
-}