gdc-common-utils-ts 1.0.1

package/src/utils/jwt.ts

@@ -0,0 +1,165 @@
+// crypto-ts/utils/jwt.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+// Use `import * as pako` to ensure compatibility with CommonJS/ESM module resolution.
+// This resolves a stubborn TypeScript error (`esModuleInterop`) during testing.
+import * as pako from 'pako';
+import { Content } from './content';
+import { DataCompactJWT, JwtCompactParts } from '../models/jwt';
+
+// --- JWT Parsing and Decoding ---
+
+/**
+ * Splits a compact JWT string into its three parts.
+ * @param compactToken The compact JWT string.
+ * @returns A PartsJWT object or undefined if the format is invalid.
+ */
+export function getPartsJWT(compactToken: string | undefined): JwtCompactParts | undefined {
+  if (!compactToken) {
+    return undefined;
+  }
+  const parts = compactToken.split('.');
+  if (parts.length !== 3) {
+    return undefined;
+  }
+  return {
+    protected: parts[0],
+    payload: parts[1],
+    signature: parts[2],
+  };
+}
+
+/**
+ * Decodes the Base64Url header of a JWT into a JSON object.
+ * @param headerB64Url The Base64Url-encoded header string.
+ * @returns A JSON object representing the header claims.
+ */
+export function decodeHeader(headerB64Url: string): any {
+  try {
+    const headerBytes = Content.base64ToBytes(headerB64Url);
+    const headerString = Content.bytesToStringASCII(headerBytes);
+    return JSON.parse(headerString);
+  } catch (e) {
+    console.error(`Cannot decode JWT header: ${e}`);
+    return {};
+  }
+}
+
+/**
+ * Decodes the payload of a JWT, decompressing it if necessary.
+ * @param payloadB64Url The Base64Url-encoded payload string.
+ * @param isDeflated True if the payload is compressed with DEFLATE.
+ * @returns The decoded payload as a JSON object.
+ */
+export async function decodePayload(payloadB64Url: string, isDeflated?: boolean): Promise<object> {
+  try {
+    let payloadBytes = Content.base64ToBytes(payloadB64Url);
+    if (isDeflated) {
+      payloadBytes = pako.inflate(payloadBytes);
+    }
+    // CRITICAL: The output of a decompression library like pako is a raw binary
+    // stream. It is NOT guaranteed to be valid UTF-8. Using the strict
+    // `bytesToStringUTF8` can fail. `bytesToStringASCII` is a more permissive
+    // decoder that is robust enough to handle this binary data and convert it
+    // to a string that can be safely parsed by `JSON.parse()`.
+    const payloadString = Content.bytesToStringASCII(payloadBytes);
+    return JSON.parse(payloadString);
+  } catch (e) {
+    console.error(`Cannot decode JWT payload: ${e}`);
+    return {};
+  }
+}
+
+/**
+ * Fully decodes a compact JWT into a `DataCompactJWT` object with JSON headers and payload.
+ * @returns A (compact) JWT object or undefined if parsing fails.
+ */
+export async function getDataJWT(compactJWT: string | undefined): Promise<DataCompactJWT | undefined> {
+  const parts = getPartsJWT(compactJWT);
+  if (!parts) {
+    return undefined;
+  }
+
+  const header = decodeHeader(parts.protected);
+  const isDeflated = header.zip === 'DEF';
+  const payload = await decodePayload(parts.payload, isDeflated);
+  
+  return {
+    protected: header,
+    payload,
+    signature: parts.signature ? Content.base64ToBytes(parts.signature) : undefined,
+  };
+}
+
+
+// --- JWT Creation and Encoding ---
+
+/**
+ * Encodes a JSON object into a Base64Url string.
+ * @param header The header object.
+ * @returns The encoded string.
+ */
+export function encodeHeader(header: object): string {
+  try {
+    return Content.objectToRawBase64UrlSafe(header);
+  } catch (e) {
+    console.warn('Cannot encode JWT header', e);
+    return '';
+  }
+}
+
+/**
+ * Encodes a JSON object into a Base64Url payload, compressing it if required.
+ * @param payload The payload object.
+ * @param deflate True to compress the payload with DEFLATE.
+ * @returns The encoded string.
+ */
+export async function encodePayload(payload: object, deflate?: boolean): Promise<string> {
+  try {
+    // CRITICAL: When creating a payload, we start with a JSON string, which IS
+    // valid UTF-8. We must use the strict `stringToBytesUTF8` encoder to ensure
+    // standards compliance.
+    let payloadBytes = Content.stringToBytesUTF8(JSON.stringify(payload));
+    if (deflate) {
+      payloadBytes = pako.deflate(payloadBytes);
+    }
+    return Content.bytesToRawBase64UrlSafe(payloadBytes);
+  } catch (e) {
+    console.warn('Cannot encode JWT payload', e);
+    return '';
+  }
+}
+
+/**
+ * Encodes a signature byte array into a Base64Url string.
+ * @param signatureBytes The signature bytes.
+ * @returns The encoded string, or an empty string if no signature is provided.
+ */
+export function encodeSignature(signatureBytes?: Uint8Array): string {
+  if (!signatureBytes || signatureBytes.length < 1) {
+    return '';
+  }
+  try {
+    return Content.bytesToRawBase64UrlSafe(signatureBytes);
+  } catch (e) {
+    console.warn('Cannot encode JWT signature', e);
+    return '';
+  }
+}
+
+/**
+ * Assembles a header, payload, and signature into a compact JWT string.
+ * @param header The header object.
+ * @param payload The payload object.
+ * @param signatureBytes The optional signature.
+ * @returns A compact JWT string.
+ */
+export async function compactJWT(header: object, payload: object, signatureBytes?: Uint8Array): Promise<string> {
+  const encodedHeader = encodeHeader(header);
+  const isDeflated = (header as any).zip === 'DEF';
+  const encodedPayload = await encodePayload(payload, isDeflated);
+  const encodedSignature = encodeSignature(signatureBytes);
+
+  return `${encodedHeader}.${encodedPayload}.${encodedSignature}`;
+}
+

package/src/utils/manager-error.ts

@@ -0,0 +1,27 @@
+// src/utils/manager-error.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import { IssueTypeCode, IssueTypeToHttpStatus } from "../models/issue";
+
+/**
+ * A custom error class used to propagate specific operational failures from deep
+ * within the manager's logic to the central error handler.
+ * It carries the necessary information to build a well-formed ErrorEntry.
+ */
+export class ManagerError extends Error {
+  public readonly code: IssueTypeCode;
+  public readonly status: string; // This is a string
+
+  /**
+   * @param message The diagnostic message for the error.
+   * @param code The classification of the error, from which the HTTP status will be derived.
+   */
+  constructor(message: string, code: IssueTypeCode) {
+    super(message);
+    this.name = 'ManagerError';
+    this.code = code;
+    // Automatically derive the HTTP status string from the issue code.
+    this.status = IssueTypeToHttpStatus[code] || '500';
+  }
+}
+

package/src/utils/multibase58.ts

@@ -0,0 +1,46 @@
+// crypto-ts/crypto-ts/utils/multibase58.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import baseX from "base-x";
+
+const BASE58_BTC_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const base58btc = baseX(BASE58_BTC_ALPHABET);
+
+/**
+ * Encode bytes into multibase base58btc string (prefixed with 'z').
+ * Equivalent to multiformats base58btc.encode.
+ */
+export function encodeMultibase58btc(data: Uint8Array): string {
+  return "z" + base58btc.encode(Buffer.from(data));
+}
+
+/**
+ * Decode a multibase base58btc string (must start with 'z').
+ * Equivalent to multiformats base58btc.decode.
+ */
+export function decodeMultibase58btc(multibaseStr: string): Uint8Array {
+  if (!multibaseStr.startsWith("z")) {
+    throw new Error("Invalid multibase58btc string: missing 'z' prefix");
+  }
+  return new Uint8Array(base58btc.decode(multibaseStr.slice(1)));
+}
+
+// HEX ➜ multibase base58btc (quita guiones si los hay)
+export function encodeHexToMultibase58btc(hexStr: string): string {
+  const hexClean = hexStr.replace(/-/g, "").toLowerCase();
+  if (!/^[0-9a-f]{32}$/i.test(hexClean)) throw new Error("Invalid 16-byte hex string");
+  const bytes = new Uint8Array(hexClean.match(/.{1,2}/g)!.map(b => parseInt(b, 16)));
+  return encodeMultibase58btc(bytes);
+}
+
+// multibase base58btc ➜ hex (no hyppens)
+export function decodeMultibase58btcToHex(b58str: string): string {
+  const bytes = decodeMultibase58btc(b58str);
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+
+// multibase base58btc ➜ UUID (with hyppens)
+export function decodeMultibase58btcToUUID(b58str: string): string {
+  const hex = decodeMultibase58btcToHex(b58str);
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/utils/multibasehash.ts

@@ -0,0 +1,28 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+// Use explicit .js subpaths to satisfy package exports in Metro/Node ESM.
+import { sha384 } from '@noble/hashes/sha2.js';
+import { utf8ToBytes } from '@noble/hashes/utils.js';
+import baseX from 'base-x';
+
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const base58btc = baseX(BASE58_ALPHABET);
+
+/**
+ * Encodes input into multibase(base58btc(multihash(sha384))).
+ * - Multihash prefix: 0x15 0x30
+ *   - 0x15: code for SHA-384
+ *   - 0x30: length of SHA-384 = 48 bytes
+ * - Multibase prefix: 'z'
+ */
+export function encodeMultibaseSha384(input: string | Uint8Array): string {
+  const bytes = typeof input === 'string' ? utf8ToBytes(input) : input;
+  const hashBytes = sha384(bytes);
+
+  const multihashBytes = new Uint8Array(2 + hashBytes.length);
+  multihashBytes[0] = 0x15; // SHA-384 code
+  multihashBytes[1] = 0x30; // length = 48
+  multihashBytes.set(hashBytes, 2);
+
+  return 'z' + base58btc.encode(multihashBytes);
+}

package/src/utils/normalize.ts

@@ -0,0 +1,43 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/utils/normalize.ts
+
+/**
+ * Creates a stable, serialized JSON string from an object by sorting its keys alphabetically.
+ * This is the core function for achieving canonical serialization.
+ * @param obj The object to serialize.
+ * @returns A stable JSON string.
+ */
+function stableStringify(obj: object): string {
+  const sortedKeys = Object.keys(obj).sort();
+  const sortedObject: { [key: string]: any } = {};
+  for (const key of sortedKeys) {
+    sortedObject[key] = (obj as any)[key];
+  }
+  return JSON.stringify(sortedObject);
+}
+
+/**
+ * Normalizes an object for hashing by excluding a standard set of volatile properties.
+ * This function is based on the original `normalizeAndSerializeObject` from the backend utils.
+ *
+ * @param obj The object to normalize.
+ * @returns A stable, canonical JSON string of the object's core properties.
+ */
+export function normalizeObject(obj: object): string {
+  // Exclude properties that are often volatile or client-specific
+  // and should not be part of the core content hash.
+  const { id, meta, text, contained, ...coreContent } = obj as any;
+  return stableStringify(coreContent);
+}
+
+/**
+ * Normalizes a DIDComm payload specifically for generating the `payload.id` (version hash).
+ * According to the defined architecture, this specifically excludes `id` and `meta`.
+ *
+ * @param payload The DIDComm payload object.
+ * @returns A stable JSON string representation of the payload's core content.
+ */
+export function normalizeDidcommPayloadForId(payload: object): string {
+  const { id, meta, ...coreContent } = payload as any;
+  return stableStringify(coreContent);
+}

package/src/utils/object-convert.ts

@@ -0,0 +1,57 @@
+// crypto-ts/utils/object-convert.ts
+
+import { decodeURLSafe } from "@stablelib/base64";
+import { bytesToStringUTF8, stringToBytesUTF8 } from './string-convert';
+import { bytesToRawBase64UrlSafe } from './base-convert';
+
+/** Compares two arrays and returns true if they are the same, false otherwise. */
+export function arrayCompare(a: any[], b: any[]): boolean {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** Merges two Uint8Arrays into a single Uint8Array. */
+export function arrayMerge(a: Uint8Array, b: Uint8Array): Uint8Array {
+    const mergedArray = new Uint8Array(a.length + b.length);
+    mergedArray.set(a);
+    mergedArray.set(b, a.length);
+    return mergedArray;
+}
+
+/**
+ * Serializes a JavaScript object to a Uint8Array of UTF-8 bytes.
+ * NOTE: This does not perform canonicalization (sorting keys).
+ */
+export function objectToBytes(data: object): Uint8Array {
+    return stringToBytesUTF8(JSON.stringify(data));
+};
+
+/**
+ * Serializes a JavaScript object to a raw Base64URL string.
+ * NOTE: This does not perform canonicalization (sorting keys).
+ */
+export function objectToRawBase64UrlSafe(data: object): string {
+    const dataBytes = objectToBytes(data);
+    return bytesToRawBase64UrlSafe(dataBytes);
+}
+
+/**
+ * Deserializes a Base64URL string back into a JavaScript object.
+ * @param base64UrlSafe The Base64URL encoded JSON string.
+ * @returns A JavaScript object.
+ */
+export function base64UrlSafeToJSON(base64UrlSafe: string | undefined): object {
+    if (!base64UrlSafe) {
+        throw new Error("Input string is undefined.");
+    }
+    const dataBytes: Uint8Array = decodeURLSafe(base64UrlSafe);
+    return JSON.parse(bytesToStringUTF8(dataBytes));
+}
+

package/src/utils/string-convert.ts

@@ -0,0 +1,71 @@
+// crypto-ts/utils/string-convert.ts
+
+import { encode as encodeUTF8, decode as decodeUTF8 } from "@stablelib/utf8";
+
+/**
+ * Encodes a standard JavaScript string into a Uint8Array of strictly-validated UTF-8 bytes.
+ * This is the standard and safest method for serializing text data.
+ * @param str The string to convert.
+ * @returns A Uint8Array.
+ */
+export function stringToBytesUTF8(str: string): Uint8Array {
+    return encodeUTF8(str);
+}
+
+/**
+ * Decodes a Uint8Array of strictly-validated UTF-8 bytes back into a string.
+ * This will fail if the byte array does not represent valid UTF-8.
+ * Use this for standard text and JSON.
+ * @param array The UTF-8 byte array to convert.
+ * @returns A string.
+ */
+export function bytesToStringUTF8(array: Uint8Array): string {
+    return decodeUTF8(array);
+}
+
+/**
+ * Decodes a Uint8Array containing binary data into a string by processing
+ * each byte individually. This is more permissive than `bytesToStringUTF8` and is
+ * specifically required for handling payloads from libraries (e.g., pako) that
+ * may not be strictly UTF-8. Use this for decoding JWT payloads.
+ * @param array The binary/ASCII byte array to convert.
+ * @returns A string.
+ */
+export function bytesToStringASCII(array: Uint8Array): string {
+    var out, i, len, c;
+    var char2, char3;
+
+    out = "";
+    len = array.length;
+    i = 0;
+    while (i < len) {
+        c = array[i++];
+        switch (
+        c >> 4
+        ) {
+            case 0:
+            case 1:
+            case 2:
+            case 3:
+            case 4:
+            case 5:
+            case 6:
+            case 7:
+                out += String.fromCharCode(c);
+                break;
+            case 12:
+            case 13:
+                char2 = array[i++];
+                out += String.fromCharCode(((c & 0x1f) << 6) | (char2 & 0x3f));
+                break;
+            case 14:
+                char2 = array[i++];
+                char3 = array[i++];
+                out += String.fromCharCode(
+                    ((c & 0x0f) << 12) | ((char2 & 0x3f) << 6) | ((char3 & 0x3f) << 0)
+                );
+                break;
+        }
+    }
+    return out;
+}

package/src/utils/string-utils.ts

@@ -0,0 +1,70 @@
+// crypto-ts/utils/string-utils.ts
+
+/**
+ * Capitalizes the first letter of a string.
+ * @param s The input string.
+ * @returns The capitalized string.
+ */
+export function capitalize(s: string): string {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * A simple string sanitizer that removes characters that are not alphanumeric or common punctuation.
+ * @param str The string to sanitize.
+ * @returns The sanitized string.
+ */
+export function sanitizeString(str: string): string {
+    str = str.replace(/[^a-z0-9áéíóúñü \.,_-]/gim, "");
+    return str.trim();
+}
+
+/**
+ * Converts a string to a string of its ASCII character codes.
+ * @param text The input string.
+ * @returns A string of character codes.
+ */
+/* tslint:disable:forin */
+export function stringToASCII(text: any): string {
+    let ascii = "";
+    for (const f in text) {
+        ascii = ascii + text.charCodeAt(f);
+    }
+    return ascii;
+}
+
+/**
+ * Converts a string to an array of numbers representing its byte values.
+ * From google closure library: https://github.com/google/closure-library/blob/8598d87242af59aac233270742c8984e2b2bdbe0/closure/goog/crypt/crypt.js#L117-L143
+ * @param str The input string.
+ * @returns An array of numbers.
+ */
+export function stringToBytesArrayOfNumbers(str: string): number[] {
+    let out = [],
+        p = 0;
+    for (var i = 0; i < str.length; i++) {
+        var c = str.charCodeAt(i);
+        if (c < 128) {
+            out[p++] = c;
+        } else if (c < 2048) {
+            out[p++] = (c >> 6) | 192;
+            out[p++] = (c & 63) | 128;
+        } else if (
+            (c & 0xfc00) == 0xd800 &&
+            i + 1 < str.length &&
+            (str.charCodeAt(i + 1) & 0xfc00) == 0xdc00
+        ) {
+            // Surrogate Pair
+            c = 0x10000 + ((c & 0x03ff) << 10) + (str.charCodeAt(++i) & 0x03ff);
+            out[p++] = (c >> 18) | 240;
+            out[p++] = ((c >> 12) & 63) | 128;
+            out[p++] = ((c >> 6) & 63) | 128;
+            out[p++] = (c & 63) | 128;
+        } else {
+            out[p++] = (c >> 12) | 224;
+            out[p++] = ((c >> 6) & 63) | 128;
+            out[p++] = (c & 63) | 128;
+        }
+    }
+    return out;
+}

package/src/utils/url.ts

@@ -0,0 +1,46 @@
+// crypto-ts/utils/url.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+/**
+ * Join the base_url and path without adding extra slashes.
+ * 
+ * @param base_url - The base URL.
+ * @param path - The path to be appended to the base URL.
+ * @returns The safely joined URL.
+ */
+export function safelyJoinUrl(base_url: string, path: string): string {
+    // Remove trailing slash from base_url if it exists
+    if (base_url.endsWith('/')) {
+        base_url = base_url.substring(0, base_url.length - 1);
+    }
+    // Remove leading slash from path if it exists
+    if (path.startsWith('/')) {
+        path = path.substring(1);
+    }
+    return `${base_url}/${path}`;
+}
+
+/**
+ * Splits a given URL into its domain and path components.
+ *
+ * @param {string} urlString - The full URL string to be split.
+ * @returns {{ domain: string; path: string }} An object containing the `domain` and `path` of the URL.
+ * If the URL is not valid it returns empty domain and path.
+ *
+ * @example
+ * Returns { domain: 'www.example.com', path: '/some/path' }
+ * const result = splitUrl('https://www.example.com/some/path?query=string');
+ *
+ * @example
+ * Returns null for invalid URLs
+ * const result = splitUrl('invalid-url');
+ */
+export function splitUrl(urlString: string): { domain: string; path: string } | null {
+    try {
+        const url = new URL(urlString);
+        return { domain: url.hostname, path: url.pathname };
+    } catch (error) {
+        console.error("Invalid URL provided:", (error as any).message);
+    }
+    return null;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "__tests__/**", "src/**/*.txt"]
+}