gdc-common-utils-ts 1.0.1

package/__tests__/utils-base-convert.test.ts

@@ -0,0 +1,57 @@
+import {
+  base58ToBytes,
+  base64OrUrlSafeToBytes,
+  base64ToBase64Url,
+  base64UrlToBase64,
+  bytesToBase58,
+  bytesToBase64,
+  bytesToHexString,
+  bytesToRawBase64UrlSafe,
+  stringToBase64Url,
+  stringToStdBase64,
+} from '../src/utils/base-convert.js';
+import { stringToBytesUTF8, bytesToStringUTF8 } from '../src/utils/string-convert.js';
+
+function toArray(bytes: Uint8Array): number[] {
+  return Array.from(bytes);
+}
+
+describe('base-convert utilities', () => {
+  it('converts bytes to hex string', () => {
+    const hex = bytesToHexString(new Uint8Array([0, 15, 255]));
+    expect(hex).toBe('000fff');
+  });
+
+  it('round-trips base58 encoding', () => {
+    const bytes = stringToBytesUTF8('hello');
+    const encoded = bytesToBase58(bytes);
+    const decoded = base58ToBytes(encoded);
+    expect(toArray(decoded)).toEqual(toArray(bytes));
+  });
+
+  it('handles base64 and base64url conversions', () => {
+    const std = stringToStdBase64('hi');
+    expect(std).toBe('aGk=');
+    const url = stringToBase64Url('hi');
+    expect(url).toBe('aGk=');
+    expect(base64ToBase64Url('ab+/')).toBe('ab-_');
+    expect(base64UrlToBase64('ab-_')).toBe('ab+/');
+  });
+
+  it('decodes base64 or base64url into bytes', () => {
+    const withSlash = '//8='; // bytes [255, 255]
+    const fromBase64 = base64OrUrlSafeToBytes(withSlash);
+    expect(toArray(fromBase64)).toEqual([255, 255]);
+
+    const urlSafe = 'AQID'; // bytes [1,2,3]
+    const fromUrlSafe = base64OrUrlSafeToBytes(urlSafe);
+    expect(toArray(fromUrlSafe)).toEqual([1, 2, 3]);
+  });
+
+  it('encodes bytes to base64 and raw base64url', () => {
+    const bytes = stringToBytesUTF8('test');
+    expect(bytesToBase64(bytes)).toBe('dGVzdA==');
+    expect(bytesToRawBase64UrlSafe(bytes)).toBe('dGVzdA');
+    expect(bytesToStringUTF8(base64OrUrlSafeToBytes(bytesToRawBase64UrlSafe(bytes)))).toBe('test');
+  });
+});

package/__tests__/utils-baseN.test.ts

@@ -0,0 +1,40 @@
+import { alphabetBase58, BaseN, decodeN, encodeN } from '../src/utils/baseN.js';
+import { stringToBytesUTF8 } from '../src/utils/string-convert.js';
+
+describe('baseN', () => {
+  it('round-trips base58 encoding/decoding', () => {
+    const bytes = stringToBytesUTF8('hello world');
+    const encoded = encodeN(bytes, alphabetBase58, undefined);
+    const decoded = decodeN(encoded, alphabetBase58);
+    expect(Array.from(decoded)).toEqual(Array.from(bytes));
+  });
+
+  it('supports maxline output wrapping', () => {
+    const bytes = stringToBytesUTF8('hello world');
+    const encoded = encodeN(bytes, alphabetBase58, 4 as unknown as any);
+    expect(encoded.includes('\r\n')).toBe(true);
+  });
+
+  it('supports BaseN class helpers', () => {
+    const bytes = new Uint8Array([0, 1, 2, 3]);
+    const encodedBytes = BaseN.encodeBytesToBase58(bytes);
+    expect(Array.from(BaseN.decodeBytesFromBase58(encodedBytes))).toEqual(Array.from(bytes));
+
+    const encodedStr = BaseN.encodeStrToBase58('hello');
+    expect(BaseN.decodeStrFromBase58(encodedStr)).toBe('hello');
+  });
+
+  it('throws on invalid encode inputs', () => {
+    expect(() => encodeN('nope' as unknown as Uint8Array, alphabetBase58, undefined)).toThrow(/Uint8Array/);
+    expect(() => encodeN(new Uint8Array([1, 2, 3]), 123 as unknown as string, undefined)).toThrow(/alphabet/);
+    expect(() => encodeN(new Uint8Array([1, 2, 3]), alphabetBase58, 'x' as unknown as any)).toThrow(/maxline/);
+  });
+
+  it('handles decode edge cases', () => {
+    expect(() => decodeN(123 as unknown as string, alphabetBase58)).toThrow(/input/);
+    expect(() => decodeN('abc', 123 as unknown as string)).toThrow(/alphabet/);
+    expect(decodeN('', alphabetBase58)).toEqual(new Uint8Array(0));
+    expect(decodeN('0', alphabetBase58)).toEqual(new Uint8Array(0));
+    expect(decodeN(' 11', alphabetBase58).length).toBeGreaterThan(0);
+  });
+});

package/__tests__/utils-did-extra.test.ts

@@ -0,0 +1,33 @@
+import {
+  buildHostedDidDetails,
+  createHostedDidWeb,
+  getBaseUrlFromDidWeb,
+  normalizeDidWeb,
+} from '../src/utils/did.js';
+
+describe('did utilities', () => {
+  it('normalizes did:web values and role codes', () => {
+    const input = 'did:web:Api.Acme.Org:employee:doctor1@acme.org:role:ISCO-08|2211';
+    expect(normalizeDidWeb(input)).toBe('did:web:api.acme.org:employee:doctor1@acme.org:role:isco-08|2211');
+  });
+
+  it('creates hosted did:web strings', () => {
+    const did = createHostedDidWeb('did:web:host.example.com', 'acme', {
+      jurisdiction: 'es',
+      version: 'v1',
+      sector: 'health-care',
+    });
+    expect(did).toBe('did:web:host.example.com:acme:cds-es:v1:health-care');
+  });
+
+  it('builds hosted DID details with defaults', () => {
+    const details = buildHostedDidDetails({ host: 'example.com', alternateName: 'acme' });
+    expect(details.did).toBe('did:web:example.com:acme:cds-ES:v1:health-care');
+    expect(details.url).toBe('https://example.com/acme/cds-ES/v1/health-care/');
+  });
+
+  it('derives base URL from did:web', () => {
+    const url = getBaseUrlFromDidWeb('did:web:localhost%3A3000:acme:cds-es:v1:health-care');
+    expect(url).toBe('http://localhost:3000/acme/cds-ES/v1/health-care/');
+  });
+});

package/__tests__/utils-format-converter.test.ts

@@ -0,0 +1,87 @@
+import {
+  convertFhirErrorBundleToJsonApiError,
+  convertPrimaryDocToBundleFHIR,
+  convertResourceDataToArrayOfDataEntries,
+  convertResourceOrBundleToPrimaryDoc,
+} from '../src/utils/format-converter.js';
+
+describe('format-converter', () => {
+  it('normalizes a FHIR resource into entries', () => {
+    const resource = { resourceType: 'Patient', id: '123', name: [{ given: ['A'] }] };
+    const entries = convertResourceDataToArrayOfDataEntries(resource, '/fhir', 'https://example.com');
+    expect(entries).toEqual([
+      {
+        fullUrl: 'https://example.com/fhir/123',
+        resource,
+      },
+    ]);
+  });
+
+  it('passes through bundle entries', () => {
+    const bundle = { resourceType: 'Bundle', entry: [{ resource: { id: '1' } }] };
+    const entries = convertResourceDataToArrayOfDataEntries(bundle, '/fhir', 'https://example.com');
+    expect(entries).toEqual(bundle.entry);
+  });
+
+  it('returns input when already JSON:API-like', () => {
+    const input = { id: 'abc', type: 'test', attributes: { a: 1 } };
+    const entries = convertResourceDataToArrayOfDataEntries(input, '/fhir', 'https://example.com');
+    expect(entries).toEqual([input]);
+  });
+
+  it('converts resource or bundle to primary document', () => {
+    const resource = { resourceType: 'Patient', id: '123', name: [{ given: ['A'] }] };
+    const doc = convertResourceOrBundleToPrimaryDoc(resource, 'spec', 'https://example.com', '/fhir');
+    expect(doc).toEqual({
+      data: [
+        {
+          type: 'spec.Patient',
+          id: '123',
+          attributes: resource,
+        },
+      ],
+    });
+  });
+
+  it('converts primary doc with data and errors to FHIR bundle', () => {
+    const primaryDoc = {
+      data: [{ id: '1', attributes: { resourceType: 'Patient', id: '1' } }],
+      errors: [{ id: 'e1', status: '400', detail: 'Bad' }],
+    };
+    const bundle = convertPrimaryDocToBundleFHIR(primaryDoc, 'transaction');
+    expect(bundle.resourceType).toBe('Bundle');
+    expect(bundle.total).toBe(1);
+    expect(bundle.type).toBe('transaction');
+    expect(bundle.entry.length).toBe(2);
+    expect(bundle.entry[0].resource.resourceType).toBe('Patient');
+    expect(bundle.entry[1].resource.resourceType).toBe('OperationOutcome');
+  });
+
+  it('converts error bundles to JSON:API errors', () => {
+    const errorBundle = {
+      entry: [
+        {
+          resource: {
+            id: 'err-1',
+            issue: [{ code: 'invalid', severity: 'error', details: { text: 'Bad' }, diagnostics: 'Oops' }],
+          },
+          response: { status: 400 },
+        },
+      ],
+    };
+    const jsonApiError = convertFhirErrorBundleToJsonApiError(errorBundle);
+    expect(jsonApiError.errors[0]).toEqual({
+      id: 'err-1',
+      status: '400',
+      code: 'invalid',
+      title: 'Bad',
+      detail: 'Oops',
+      meta: { severity: 'error' },
+    });
+  });
+
+  it('returns default error for empty bundles', () => {
+    const jsonApiError = convertFhirErrorBundleToJsonApiError({});
+    expect(jsonApiError.errors[0].status).toBe('500');
+  });
+});

package/__tests__/utils-jwt.test.ts

@@ -0,0 +1,57 @@
+import {
+  compactJWT,
+  decodeHeader,
+  decodePayload,
+  encodeHeader,
+  encodePayload,
+  encodeSignature,
+  getDataJWT,
+  getPartsJWT,
+} from '../src/utils/jwt.js';
+
+const signatureBytes = new Uint8Array([1, 2, 3]);
+
+describe('jwt utilities', () => {
+  it('splits compact JWTs into parts', () => {
+    expect(getPartsJWT(undefined)).toBeUndefined();
+    expect(getPartsJWT('a.b')).toBeUndefined();
+    expect(getPartsJWT('a.b.c')).toEqual({ protected: 'a', payload: 'b', signature: 'c' });
+  });
+
+  it('encodes and decodes headers', () => {
+    const header = { alg: 'none' };
+    const encoded = encodeHeader(header);
+    expect(decodeHeader(encoded)).toEqual(header);
+    const spy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    expect(decodeHeader('not-base64')).toEqual({});
+    spy.mockRestore();
+  });
+
+  it('encodes and decodes payloads (raw and deflated)', async () => {
+    const payload = { sub: '123', aud: 'test' };
+    const encoded = await encodePayload(payload);
+    const decoded = await decodePayload(encoded);
+    expect(decoded).toEqual(payload);
+
+    const encodedDeflated = await encodePayload(payload, true);
+    const decodedDeflated = await decodePayload(encodedDeflated, true);
+    expect(decodedDeflated).toEqual(payload);
+  });
+
+  it('encodes signatures', () => {
+    expect(encodeSignature()).toBe('');
+    expect(encodeSignature(new Uint8Array(0))).toBe('');
+    expect(encodeSignature(signatureBytes)).not.toBe('');
+  });
+
+  it('round-trips compact JWTs', async () => {
+    const header = { alg: 'none' };
+    const payload = { sub: '123' };
+    const token = await compactJWT(header, payload, signatureBytes);
+
+    const data = await getDataJWT(token);
+    expect(data?.protected).toEqual(header);
+    expect(data?.payload).toEqual(payload);
+    expect(Array.from(data?.signature || [])).toEqual(Array.from(signatureBytes));
+  });
+});

package/__tests__/utils-manager-error.test.ts

@@ -0,0 +1,11 @@
+import { ManagerError } from '../src/utils/manager-error.js';
+import { IssueType } from '../src/models/issue.js';
+
+describe('ManagerError', () => {
+  it('sets name, code, and status from issue type', () => {
+    const err = new ManagerError('bad input', IssueType.Invalid);
+    expect(err.name).toBe('ManagerError');
+    expect(err.code).toBe(IssueType.Invalid);
+    expect(err.status).toBe('400');
+  });
+});

package/__tests__/utils-normalize.test.ts

@@ -0,0 +1,15 @@
+import { normalizeDidcommPayloadForId, normalizeObject } from '../src/utils/normalize.js';
+
+describe('normalize utilities', () => {
+  it('normalizes objects by removing volatile fields and sorting keys', () => {
+    const input = { b: 2, id: '123', a: 1, meta: { a: 1 }, contained: [], text: 'ignore' };
+    const normalized = normalizeObject(input);
+    expect(normalized).toBe('{"a":1,"b":2}');
+  });
+
+  it('normalizes DIDComm payloads by excluding id and meta', () => {
+    const payload = { z: 1, id: 'abc', meta: { i: 2 }, a: 2 };
+    const normalized = normalizeDidcommPayloadForId(payload);
+    expect(normalized).toBe('{"a":2,"z":1}');
+  });
+});

package/__tests__/utils-object-convert.test.ts

@@ -0,0 +1,38 @@
+import {
+  arrayCompare,
+  arrayMerge,
+  base64UrlSafeToJSON,
+  objectToBytes,
+  objectToRawBase64UrlSafe,
+} from '../src/utils/object-convert.js';
+import { bytesToStringUTF8 } from '../src/utils/string-convert.js';
+
+function toArray(bytes: Uint8Array): number[] {
+  return Array.from(bytes);
+}
+
+describe('object-convert', () => {
+  it('compares arrays', () => {
+    expect(arrayCompare([1, 2], [1, 2])).toBe(true);
+    expect(arrayCompare([1], [1, 2])).toBe(false);
+    expect(arrayCompare([1, 2], [1, 3])).toBe(false);
+  });
+
+  it('merges Uint8Arrays', () => {
+    const merged = arrayMerge(new Uint8Array([1, 2]), new Uint8Array([3]));
+    expect(toArray(merged)).toEqual([1, 2, 3]);
+  });
+
+  it('serializes objects to bytes and base64url', () => {
+    const obj = { a: 1, b: true };
+    const bytes = objectToBytes(obj);
+    expect(bytesToStringUTF8(bytes)).toBe(JSON.stringify(obj));
+
+    const encoded = objectToRawBase64UrlSafe(obj);
+    expect(base64UrlSafeToJSON(encoded)).toEqual(obj);
+  });
+
+  it('throws on undefined base64 input', () => {
+    expect(() => base64UrlSafeToJSON(undefined)).toThrow(/undefined/);
+  });
+});

package/__tests__/utils-string-convert.test.ts

@@ -0,0 +1,20 @@
+import { bytesToStringASCII, bytesToStringUTF8, stringToBytesUTF8 } from '../src/utils/string-convert.js';
+
+describe('string-convert', () => {
+  it('round-trips UTF-8 strings', () => {
+    const bytes = stringToBytesUTF8('hola');
+    expect(bytesToStringUTF8(bytes)).toBe('hola');
+  });
+
+  it('decodes ASCII/UTF-8 bytes permissively', () => {
+    const value = '\\u00f1';
+    const bytes = stringToBytesUTF8(value);
+    expect(bytesToStringASCII(bytes)).toBe(value);
+  });
+
+  it('decodes 3-byte UTF-8 sequences', () => {
+    const value = '\\u20ac';
+    const bytes = stringToBytesUTF8(value);
+    expect(bytesToStringASCII(bytes)).toBe(value);
+  });
+});

package/__tests__/utils-string-utils.test.ts

@@ -0,0 +1,25 @@
+import { capitalize, sanitizeString, stringToASCII, stringToBytesArrayOfNumbers } from '../src/utils/string-utils.js';
+
+describe('string-utils', () => {
+  it('capitalizes the first character', () => {
+    expect(capitalize('hello')).toBe('Hello');
+  });
+
+  it('sanitizes disallowed characters', () => {
+    expect(sanitizeString('Hello!!@#$% World')).toBe('Hello World');
+  });
+
+  it('converts a string to ASCII codes', () => {
+    expect(stringToASCII('AZ')).toBe('6590');
+  });
+
+  it('converts a string to byte array numbers', () => {
+    const bytes = stringToBytesArrayOfNumbers('A');
+    expect(bytes).toEqual([65]);
+  });
+
+  it('handles multi-byte and surrogate pairs', () => {
+    expect(stringToBytesArrayOfNumbers('\u00f1')).toEqual([195, 177]);
+    expect(stringToBytesArrayOfNumbers('\ud83d\ude00')).toEqual([240, 159, 152, 128]);
+  });
+});

package/__tests__/utils-url.test.ts

@@ -0,0 +1,21 @@
+import { safelyJoinUrl, splitUrl } from '../src/utils/url.js';
+
+describe('url utilities', () => {
+  it('joins URL parts safely', () => {
+    expect(safelyJoinUrl('https://example.com/', '/path')).toBe('https://example.com/path');
+    expect(safelyJoinUrl('https://example.com', 'path')).toBe('https://example.com/path');
+  });
+
+  it('splits a valid URL', () => {
+    expect(splitUrl('https://www.example.com/some/path?query=1')).toEqual({
+      domain: 'www.example.com',
+      path: '/some/path',
+    });
+  });
+
+  it('returns null for invalid URLs', () => {
+    const spy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    expect(splitUrl('not-a-url')).toBeNull();
+    spy.mockRestore();
+  });
+});

package/babel.config.cjs

@@ -0,0 +1,5 @@
+module.exports = {
+  presets: [
+    ['@babel/preset-env', { targets: { node: 'current' } }],
+  ],
+};

package/jest.config.ts

@@ -0,0 +1,46 @@
+import type { JestConfigWithTsJest } from 'ts-jest';
+
+const config: JestConfigWithTsJest = {
+  testEnvironment: 'node',
+  clearMocks: true,
+  extensionsToTreatAsEsm: ['.ts'],
+
+  roots: ['<rootDir>/__tests__'],
+  testMatch: ['**/*.test.ts'],
+
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        useESM: true,
+        tsconfig: {
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          allowSyntheticDefaultImports: true,
+          esModuleInterop: true,
+        },
+      },
+    ],
+    '^.+\\.(mjs|js)$': 'babel-jest',
+  },
+
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+
+  // Allow-list ESM deps in node_modules that must be transformed.
+  // Note: we need 4 backslashes in the template literal so the runtime string contains 2.
+  transformIgnorePatterns: [
+    `[/\\\\]node_modules[/\\\\](?!(@noble|@stablelib|multiformats))`,
+  ],
+
+  collectCoverage: true,
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.txt',
+    '!**/*.test.ts',
+    '!**/node_modules/**',
+  ],
+};
+
+export default config;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "gdc-common-utils-ts",
+  "version": "1.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "dependencies": {
+    "@noble/post-quantum": "^0.8.0",
+    "@stablelib/base64": "^1.0.1",
+    "@stablelib/utf8": "^1.0.2",
+    "base-x": "^4.0.0",
+    "multiformats": "^13.0.0",
+    "pako": "^2.1.0"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test -- --watchman=false"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./AesManager": "./src/AesManager.ts",
+    "./CryptographyService": "./src/CryptographyService.ts",
+    "./hmac": "./src/hmac.ts",
+    "./constants/*": "./src/constants/*.ts",
+    "./models/*": "./src/models/*.ts",
+    "./utils/*": "./src/utils/*.ts",
+    "./interfaces/*": "./src/interfaces/*.ts",
+    "./constants": "./src/constants/index.ts",
+    "./models": "./src/models/index.ts",
+    "./utils": "./src/utils/index.ts",
+    "./interfaces": "./src/interfaces/index.ts"
+  }
+}

package/src/AesManager.ts

@@ -0,0 +1,82 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/AesManager.ts
+
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+import { Content } from './utils/content';
+import { ProtectedDataAES } from './models/aes';
+
+/**
+ * Manages AES-GCM encryption and decryption using Node's native crypto module.
+ * This class handles the core cryptography and the base64url serialization required for JWE.
+ */
+export class AesManager {
+  private readonly ALGORITHM = 'aes-256-gcm';
+  private readonly KEY_SIZE = 32; // 256-bit key
+  private readonly IV_GENERATION_SIZE = 12; // 96-bit IV, recommended by NIST for GCM
+  private readonly TAG_SIZE_BYTES = 16; // 128-bit authentication tag
+
+  /**
+   * Encrypts a plaintext string and returns the components as base64url strings.
+   * @param plaintext The stringified data to encrypt (e.g. a stringified object or ASCII string from raw bytes)
+   * @param cekBytes The 32-byte Content Encryption Key.
+   * @param aad The Additional Authenticated Data string for integrity protection.
+   * @returns A promise resolving to the JWE-compatible encrypted components.
+   */
+  async encrypt(plaintext: string, cekBytes: Uint8Array, aad: string): Promise<ProtectedDataAES> {
+    if (cekBytes.length !== this.KEY_SIZE) {
+      throw new Error(`Invalid key length: a ${this.KEY_SIZE}-byte key is required.`);
+    }
+
+    const iv = randomBytes(this.IV_GENERATION_SIZE);
+    const aadBytes = Content.stringToBytesUTF8(aad);
+
+    const cipher = createCipheriv(this.ALGORITHM, cekBytes, iv, {
+      authTagLength: this.TAG_SIZE_BYTES
+    });
+
+    cipher.setAAD(aadBytes);
+
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+
+    return {
+      ciphertext: Content.bytesToRawBase64UrlSafe(ciphertext),
+      iv: Content.bytesToRawBase64UrlSafe(iv),
+      tag: Content.bytesToRawBase64UrlSafe(tag),
+    };
+  }
+
+  /**
+   * Decrypts JWE-compatible encrypted components back to a plaintext string.
+   * @param encryptedData The object containing the base64url-encoded ciphertext, iv, and tag.
+   * @param cekBytes The 32-byte Content Encryption Key.
+   * @param aad The Additional Authenticated Data for integrity verification.
+   * @returns A promise resolving to the decrypted plaintext string.
+   */
+  async decrypt(
+    encryptedData: ProtectedDataAES,
+    cekBytes: Uint8Array,
+    aad: string
+  ): Promise<string> {
+    if (cekBytes.length !== this.KEY_SIZE) {
+      throw new Error(`Invalid key length: a ${this.KEY_SIZE}-byte key is required.`);
+    }
+
+    const ciphertextBytes = Content.base64ToBytes(encryptedData.ciphertext);
+    const tagBytes = Content.base64ToBytes(encryptedData.tag);
+    const ivBytes = Content.base64ToBytes(encryptedData.iv);
+    const aadBytes = Content.stringToBytesUTF8(aad);
+
+    const decipher = createDecipheriv(this.ALGORITHM, cekBytes, ivBytes, {
+        authTagLength: this.TAG_SIZE_BYTES
+    });
+    
+    decipher.setAuthTag(tagBytes);
+    decipher.setAAD(aadBytes);
+
+    const decryptedBytes = Buffer.concat([decipher.update(ciphertextBytes), decipher.final()]);
+
+    return Content.bytesToStringUTF8(decryptedBytes);
+  }
+}
+