gdc-common-utils-ts 1.0.1

package/PUBLISHING.md

@@ -0,0 +1,33 @@
+# Publishing
+
+This package is published as a public, unscoped package (`gdc-common-utils-ts`).
+
+## NPM token
+
+When creating a token in npmjs.com:
+- `Packages and scopes` must be **Read and write**.
+- `Organizations` permissions are **not required** for unscoped packages. Enable only if publishing under an org scope (`@org/`).
+
+## Configure the token
+
+```bash
+npm config set //registry.npmjs.org/:_authToken=YOUR_TOKEN
+```
+
+Verify:
+
+```bash
+npm whoami
+```
+
+## Publish
+
+```bash
+npm publish --access public
+```
+
+If 2FA for publish is enabled, add an OTP:
+
+```bash
+NPM_CONFIG_OTP=123456 npm publish --access public
+```

package/__tests__/AesManager.test.ts

@@ -0,0 +1,53 @@
+// src/__tests__/unit/security/AesManager.test.ts
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import { jest } from '@jest/globals';
+import { randomBytes } from 'crypto'; // Use Node.js native crypto module
+import { ProtectedDataAES } from '../src/models/aes.js';
+import { AesManager } from '../src/AesManager.js';
+
+describe('AesManager', () => {
+  let aesManager: AesManager;
+
+  beforeEach(() => {
+    aesManager = new AesManager();
+  });
+
+  it('should perform a round-trip (encrypt/decrypt) using base64url strings', async () => {
+    // --- 1. Arrange ---
+    const payload = { message: 'This is a secret message.', timestamp: Date.now() };
+    const plaintext = JSON.stringify(payload);
+    const cekBytes = randomBytes(32); // 256-bit Content Encryption Key
+    const aad = 'integrity-protected-data';
+    // --- 2. Act ---
+    // The public interface works with base64url strings, as required by JWE.
+    const encryptedData: ProtectedDataAES = await aesManager.encrypt(plaintext, cekBytes, aad);
+
+    // The result is then passed back to the decryption method.
+    const decryptedText = await aesManager.decrypt(encryptedData, cekBytes, aad);
+    const decryptedPayload = JSON.parse(decryptedText);
+    // --- 3. Assert ---
+    // The output of encrypt should be correctly formatted strings.
+    expect(typeof encryptedData.ciphertext).toBe('string');
+    expect(typeof encryptedData.iv).toBe('string');
+    expect(typeof encryptedData.tag).toBe('string');
+
+    // The final decrypted object must match the original payload.
+    expect(decryptedPayload).toEqual(payload);
+  });
+
+  it('should fail decryption if the AAD is tampered with', async () => {
+    // --- 1. Arrange ---
+    const plaintext = JSON.stringify({ data: 'secret' });
+    const cekBytes = randomBytes(32);
+    const originalAad = 'original_aad';
+    const tamperedAad = 'tampered_aad';
+
+    const encryptedData = await aesManager.encrypt(plaintext, cekBytes, originalAad);
+    // --- 2. Assert ---
+    // Expect decryption to fail when using the wrong AAD.
+    await expect(
+      aesManager.decrypt(encryptedData, cekBytes, tamperedAad)
+    ).rejects.toThrow();
+  });
+});

package/__tests__/CryptographyService.test.ts

@@ -0,0 +1,194 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import { randomBytes, createHash, randomUUID } from 'crypto';
+import { CryptographyService } from '../src/CryptographyService';
+import type { ICryptoHelper } from '../src/interfaces/ICryptoHelper';
+import { Content } from '../src/utils/content';
+import { MlDsaPrivKeySizeLevel2, MlDsaPubKeySizeLevel2 } from '../src/interfaces/MlDsa';
+import { Kyber512PKBytes } from '../src/interfaces/MlKem';
+
+const cryptoHelper: ICryptoHelper = {
+  async getRandomBytes(byteCount: number): Promise<Uint8Array> {
+    return randomBytes(byteCount);
+  },
+  async digestString(data: string, algorithm: string): Promise<string> {
+    const normalized = String(algorithm).replace('-', '').toLowerCase();
+    return createHash(normalized).update(data).digest('hex');
+  },
+  randomUUID(): string {
+    return randomUUID();
+  },
+};
+
+describe('CryptographyService (PQC)', () => {
+  const service = new CryptographyService(cryptoHelper);
+
+  it('generates ML-KEM key pairs and encapsulates/decapsulates', async () => {
+    const { publicJWKey, secretKeyBytes } = await service.generateKeyPairMlKem();
+    expect(publicJWKey?.x).toBeDefined();
+    expect(publicJWKey?.kid).toBeDefined();
+    expect(secretKeyBytes.length).toBeGreaterThan(0);
+
+    const recipientPublicKeyBytes = Content.base64ToBytes(publicJWKey.x);
+    const cekSeedBytes = await cryptoHelper.getRandomBytes(32);
+    const { derivedCekBytes, encapsulatedCekBytes } = await service.encapsulate(
+      cekSeedBytes,
+      secretKeyBytes,
+      recipientPublicKeyBytes
+    );
+    const derivedFromDecap = await service.decapsulate(encapsulatedCekBytes, secretKeyBytes);
+
+    expect(derivedCekBytes.length).toBeGreaterThan(0);
+    expect(derivedFromDecap.length).toBe(derivedCekBytes.length);
+    expect(Buffer.from(derivedFromDecap).equals(Buffer.from(derivedCekBytes))).toBe(true);
+  });
+
+  it('generates deterministic ML-KEM key pairs with a seed', async () => {
+    const seed = new Uint8Array(64).fill(7);
+    const first = await service.generateKeyPairMlKem(seed, 'ML-KEM-512');
+    const second = await service.generateKeyPairMlKem(seed, 'ML-KEM-512');
+    expect(first.publicJWKey.x).toBe(second.publicJWKey.x);
+    expect(first.publicJWKey.kid).toBe(second.publicJWKey.kid);
+    expect(first.secretKeyBytes.length).toBeGreaterThan(0);
+    expect(Content.base64ToBytes(first.publicJWKey.x).length).toBe(Kyber512PKBytes);
+  });
+
+  it('generates ML-DSA key pairs with expected sizes', async () => {
+    const seed = new Uint8Array(32).fill(3);
+    const { publicJWKey, secretKeyBytes } = await service.generateKeyPairMlDsa(seed, 'ML-DSA-44');
+    expect(publicJWKey.alg).toBe('ML-DSA-44');
+    expect(secretKeyBytes.length).toBeGreaterThanOrEqual(MlDsaPrivKeySizeLevel2);
+    expect(Content.base64ToBytes(publicJWKey.pub).length).toBe(MlDsaPubKeySizeLevel2);
+  });
+
+  it('signs and verifies with ML-DSA', async () => {
+    const { publicJWKey, secretKeyBytes } = await service.generateKeyPairMlDsa(undefined, 'ML-DSA-44');
+    const payload = Content.stringToBytesUTF8('test-payload');
+
+    const signature = await service.signBytes(payload, secretKeyBytes, 'ML-DSA-44');
+    const verified = await service.verifyBytes(signature, payload, publicJWKey);
+    expect(verified).toBe(true);
+
+    const tampered = Content.stringToBytesUTF8('test-payload-tampered');
+    const verifiedTampered = await service.verifyBytes(signature, tampered, publicJWKey);
+    expect(verifiedTampered).toBe(false);
+  });
+
+  it('signs JWS objects and verifies compact + detached forms', async () => {
+    const { publicJWKey, secretKeyBytes } = await service.generateKeyPairMlDsa(undefined, 'ML-DSA-44');
+    const protectedHeader = { alg: 'ML-DSA-44', typ: 'JWT' };
+    const payload = { sub: '123', aud: 'test' };
+
+    const jws = await service.signDataJws(payload, protectedHeader, secretKeyBytes);
+    const compact = `${jws.protected}.${jws.payload}.${jws.signature}`;
+    const verified = await service.verifyJws(compact, publicJWKey);
+    expect(verified).toBe(true);
+
+    const detached = `${jws.protected}..${jws.signature}`;
+    const payloadBytes = Content.stringToBytesUTF8(JSON.stringify(payload));
+    expect(await service.verifyDetachedJws(payloadBytes, detached, publicJWKey)).toBe(true);
+  });
+
+  it('throws on invalid detached JWS format', async () => {
+    await expect(service.verifyDetachedJws(new Uint8Array([1]), 'not-detached', { kty: 'AKP', alg: 'ML-DSA-44', pub: 'AA' }))
+      .rejects.toThrow(/Detached JWS format/);
+  });
+
+  it('throws on missing alg in headers for signing and verification', async () => {
+    const { publicJWKey, secretKeyBytes } = await service.generateKeyPairMlDsa(undefined, 'ML-DSA-44');
+    await expect(service.signDataJws({ a: 1 }, {}, secretKeyBytes)).rejects.toThrow(/alg/);
+
+    const missingAlg = { ...publicJWKey };
+    delete (missingAlg as any).alg;
+    await expect(service.verifyBytes(new Uint8Array([1]), new Uint8Array([2]), missingAlg as any)).rejects.toThrow(/alg/);
+  });
+
+  it('encrypts and decrypts JWE objects (zip + no zip)', async () => {
+    const recipient = await service.generateKeyPairMlKem(undefined, 'ML-KEM-768');
+    const recipientPrivate = { ...recipient.publicJWKey, dBytes: recipient.secretKeyBytes };
+
+    const payload = { msg: 'hello' };
+    const headerNoZip = { typ: 'JWE', kid: recipient.publicJWKey.kid };
+    const jwe = await service.encryptJwe(payload, headerNoZip, recipientPrivate, [recipient.publicJWKey]);
+    const decrypted = await service.decryptJwe(jwe, recipientPrivate);
+    expect(Content.bytesToStringUTF8(decrypted.decryptedBytes)).toBe(JSON.stringify(payload));
+
+    const headerZip = { typ: 'JWE', zip: 'DEF', kid: recipient.publicJWKey.kid };
+    const jweZip = await service.encryptJwe(payload, headerZip, recipientPrivate, [recipient.publicJWKey]);
+    const decryptedZip = await service.decryptJwe(jweZip, recipientPrivate);
+    expect(Content.bytesToStringUTF8(decryptedZip.decryptedBytes)).toBe(JSON.stringify(payload));
+  });
+
+  it('encrypts and decrypts compact JWE', async () => {
+    const recipient = await service.generateKeyPairMlKem(undefined, 'ML-KEM-768');
+    const recipientPrivate = { ...recipient.publicJWKey, dBytes: recipient.secretKeyBytes };
+
+    const payload = 'hello-compact';
+    const protectedHeader = { typ: 'JWE', zip: 'DEF' };
+    const compact = await service.encryptJweToCompact(payload, protectedHeader, recipientPrivate, recipient.publicJWKey);
+    const parsed = service.parseCompactJwe(compact);
+    const decrypted = await service.decryptJwe(parsed, recipientPrivate);
+    expect(Content.bytesToStringUTF8(decrypted.decryptedBytes)).toBe(payload);
+  });
+
+  it('rejects multiple recipients in encryptJwe', async () => {
+    const recipient = await service.generateKeyPairMlKem(undefined, 'ML-KEM-768');
+    const recipientPrivate = { ...recipient.publicJWKey, dBytes: recipient.secretKeyBytes };
+    await expect(
+      service.encryptJwe({ a: 1 }, { typ: 'JWE' }, recipientPrivate, [recipient.publicJWKey, recipient.publicJWKey])
+    ).rejects.toThrow(/single recipient/);
+  });
+
+  it('parses and rejects malformed compact structures', async () => {
+    expect(() => service.parseCompactJws('a.b')).toThrow(/Compact JWS/);
+    expect(() => service.parseCompactJwe('a.b.c')).toThrow(/Compact JWE/);
+  });
+
+  it('parses compact JWS into structured data', async () => {
+    const { publicJWKey, secretKeyBytes } = await service.generateKeyPairMlDsa(undefined, 'ML-DSA-44');
+    const jws = await service.signDataJws({ sub: 'abc' }, { alg: 'ML-DSA-44' }, secretKeyBytes);
+    const compact = `${jws.protected}.${jws.payload}.${jws.signature}`;
+    const parsed = service.parseCompactJws(compact);
+    expect(parsed.payload).toEqual({ sub: 'abc' });
+    expect(parsed.protected).toEqual({ alg: 'ML-DSA-44' });
+    expect(await service.verifyJws(compact, publicJWKey)).toBe(true);
+  });
+
+  it('parses JWS JSON serialization', async () => {
+    const { secretKeyBytes } = await service.generateKeyPairMlDsa(undefined, 'ML-DSA-44');
+    const jws = await service.signDataJws({ sub: 'json' }, { alg: 'ML-DSA-44' }, secretKeyBytes);
+    const jwsJson = JSON.stringify({
+      payload: jws.payload,
+      signatures: [{ protected: jws.protected, signature: jws.signature }],
+    });
+    const parsed = service.parseCompactJws(jwsJson);
+    expect(parsed.payload).toBe(jws.payload);
+    expect(parsed.protected).toBe(jws.protected);
+    expect(parsed.signature).toBe(jws.signature);
+  });
+
+  it('extracts recipient kids from JWE objects', async () => {
+    const recipient = await service.generateKeyPairMlKem(undefined, 'ML-KEM-768');
+    const recipientPrivate = { ...recipient.publicJWKey, dBytes: recipient.secretKeyBytes };
+    const jwe = await service.encryptJwe({ a: 1 }, { typ: 'JWE', kid: recipient.publicJWKey.kid }, recipientPrivate, [recipient.publicJWKey]);
+    expect(service.getRecipientKidsFromJwe(jwe)).toEqual([recipient.publicJWKey.kid]);
+    expect(service.getRecipientKidsFromJwe({} as any)).toEqual([]);
+  });
+
+  it('parses JWE JSON serialization', async () => {
+    const recipient = await service.generateKeyPairMlKem(undefined, 'ML-KEM-768');
+    const recipientPrivate = { ...recipient.publicJWKey, dBytes: recipient.secretKeyBytes };
+    const jwe = await service.encryptJwe({ msg: 'json' }, { typ: 'JWE', kid: recipient.publicJWKey.kid }, recipientPrivate, [recipient.publicJWKey]);
+    const parsed = service.parseCompactJwe(JSON.stringify(jwe));
+    const decrypted = await service.decryptJwe(parsed, recipientPrivate);
+    expect(Content.bytesToStringUTF8(decrypted.decryptedBytes)).toBe(JSON.stringify({ msg: 'json' }));
+  });
+
+  it('computes JWK thumbprints for EC keys', async () => {
+    const ecJwk = { kty: 'EC', crv: 'P-256', x: 'AA', y: 'BB' };
+    const thumbprint = await (service as any)._computeJwkThumbprint(ecJwk, 'SHA-384');
+    const thumbprint2 = await (service as any)._computeJwkThumbprint(ecJwk, 'SHA-384');
+    expect(thumbprint).toBe(thumbprint2);
+    expect(thumbprint.length).toBeGreaterThan(0);
+  });
+});

package/__tests__/bundle.test.ts

@@ -0,0 +1,29 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import { extractResources, getNextLink } from '../src/utils/bundle';
+
+describe('bundle utils', () => {
+  it('extracts resources from FHIR bundle entry', () => {
+    const bundle = {
+      entry: [{ resource: { id: 'r1' } }, { resource: { id: 'r2' } }],
+    };
+    expect(extractResources(bundle)).toEqual([{ id: 'r1' }, { id: 'r2' }]);
+  });
+
+  it('extracts resources from JSON:API data', () => {
+    const bundle = {
+      data: [{ resource: { id: 'r1' } }, { id: 'r2' }],
+    };
+    expect(extractResources(bundle)).toEqual([{ id: 'r1' }, { id: 'r2' }]);
+  });
+
+  it('returns resource fallback when bundle is a resource', () => {
+    const bundle = { resourceType: 'Patient', id: 'p1' };
+    expect(extractResources(bundle)).toEqual([bundle]);
+  });
+
+  it('reads next link', () => {
+    const bundle = { link: [{ relation: 'next', url: 'https://next' }] };
+    expect(getNextLink(bundle)).toBe('https://next');
+  });
+});

package/__tests__/content.test.ts

@@ -0,0 +1,72 @@
+// src/__tests__/unit/utils/convert.test.ts
+
+import { Content } from '../src/utils/content.js';
+
+describe("Content Class - Conversion Utilities", () => {
+
+    describe("Base58 Conversions", () => {
+        it("should encode and decode a string to/from Base58", () => {
+            const testString = "Hello world!";
+            const testBytes = Content.stringToBytesUTF8(testString);
+
+            // Encode
+            const encoded = Content.bytesToBase58(testBytes);
+            expect(encoded).toBe("2NEpo7TZRhna7vSvL");
+
+            // Decode
+            const decodedBytes = Content.base58ToBytes(encoded);
+            const decodedString = Content.bytesToStringUTF8(decodedBytes);
+
+            expect(decodedString).toBe(testString);
+        });
+    });
+
+    describe("Base64URL Conversions", () => {
+        it("should encode and decode bytes to/from raw Base64URL", () => {
+            const testString = "some important data!?";
+            const testBytes = Content.stringToBytesUTF8(testString);
+
+            // Encode
+            const encoded = Content.bytesToRawBase64UrlSafe(testBytes);
+            expect(encoded).toBe("c29tZSBpbXBvcnRhbnQgZGF0YSE_");
+
+            // Decode
+            const decodedBytes = Content.base64ToBytes(encoded);
+            expect(decodedBytes).toEqual(testBytes);
+        });
+    });
+
+    describe("Object Serialization", () => {
+        it("should serialize and deserialize an object to/from raw Base64URL", () => {
+            const testObject = {
+                id: "12345",
+                aud: ["did:web:example.com"],
+                exp: 1678886400,
+                verified: true,
+            };
+
+            // Serialize
+            const encoded = Content.objectToRawBase64UrlSafe(testObject);
+
+            // Deserialize
+            const decodedObject = Content.base64UrlSafeToJSON(encoded);
+
+            expect(decodedObject).toEqual(testObject);
+        });
+    });
+
+    describe("Array Utilities", () => {
+        it("should correctly compare two identical arrays of primitives", () => {
+            const arr1 = [1, 2, "hello", true, null];
+            const arr2 = [1, 2, "hello", true, null];
+            expect(Content.arrayCompare(arr1, arr2)).toBe(true);
+        });
+
+        it("should correctly identify two different arrays", () => {
+            const arr1 = [1, 2, 5];
+            const arr2 = [1, 2, 9];
+            expect(Content.arrayCompare(arr1, arr2)).toBe(false);
+        });
+    });
+});
+

package/__tests__/crypto-encode-decode.test.ts

@@ -0,0 +1,52 @@
+import { encodeJWT as encodeJWTEncode } from '../src/cryptoEncode.js';
+import { encodeJWT as encodeJWTDecode, decodeBase64Url, decodePayloadRequest } from '../src/cryptoDecode.js';
+
+function base64UrlEncode(str: string): string {
+  return Buffer.from(str)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+describe('crypto encode/decode', () => {
+  it('encodes JWTs with alg none (cryptoEncode)', () => {
+    const header = { alg: 'none' };
+    const payload = { sub: '123' };
+    const token = encodeJWTEncode([], payload, [], header);
+    const parts = token.split('.');
+    expect(parts.length).toBe(3);
+    expect(decodeBase64Url(parts[0])).toBe(JSON.stringify(header));
+    expect(decodeBase64Url(parts[1])).toBe(JSON.stringify(payload));
+  });
+
+  it('encodes JWTs with alg none (cryptoDecode)', () => {
+    const header = { alg: 'none' };
+    const payload = { sub: '456' };
+    const token = encodeJWTDecode([], payload, [], header);
+    const parts = token.split('.');
+    expect(decodeBase64Url(parts[0])).toBe(JSON.stringify(header));
+    expect(decodeBase64Url(parts[1])).toBe(JSON.stringify(payload));
+  });
+
+  it('decodes payloads from authorization headers', () => {
+    const header = { alg: 'none' };
+    const payload = { a: 1 };
+    const token = `${base64UrlEncode(JSON.stringify(header))}.${base64UrlEncode(JSON.stringify(payload))}.`;
+    const decoded = decodePayloadRequest('tenant', undefined, `Bearer ${token}`);
+    expect(decoded).toBe(JSON.stringify(payload));
+  });
+
+  it('returns null when token is missing', () => {
+    const spy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    expect(decodePayloadRequest('tenant', undefined, undefined)).toBeNull();
+    spy.mockRestore();
+  });
+
+  it('returns empty string for invalid payload JSON', () => {
+    const invalid = base64UrlEncode('not-json');
+    const spy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    expect(decodeBase64Url(invalid)).toBe('');
+    spy.mockRestore();
+  });
+});

package/__tests__/crypto-hmac.test.ts

@@ -0,0 +1,21 @@
+import { computeHmacSha256, computeHmacSha256Base64Url } from '../src/hmac.js';
+
+describe('hmac utilities', () => {
+  it('computes HMAC-SHA3-256 bytes deterministically', async () => {
+    const key = new Uint8Array([1, 2, 3, 4]);
+    const message = 'hello';
+    const first = await computeHmacSha256(message, key);
+    const second = await computeHmacSha256(message, key);
+    expect(Array.from(first)).toEqual(Array.from(second));
+    expect(first.length).toBe(32);
+  });
+
+  it('computes base64url HMAC output consistently', async () => {
+    const key = new Uint8Array([9, 8, 7, 6]);
+    const message = 'hello';
+    const first = await computeHmacSha256Base64Url(message, key);
+    const second = await computeHmacSha256Base64Url(message, key);
+    expect(first).toBe(second);
+    expect(first.length).toBe(43);
+  });
+});

package/__tests__/did-generateServiceId.errors.test.ts

@@ -0,0 +1,8 @@
+import { generateServiceId } from '../src/utils/did.js';
+
+describe('generateServiceId (edge cases)', () => {
+  it('keeps action casing', () => {
+    const id = generateServiceId({ section: 'identity', format: 'openid', resourceType: 'device', action: '_DCR' });
+    expect(id).toBe('#identity:openid:device:_DCR');
+  });
+});

package/__tests__/did-generateServiceId.test.ts

@@ -0,0 +1,18 @@
+import { generateServiceId } from '../src/utils/did.js';
+
+describe('generateServiceId', () => {
+  it('builds #section:format:resourceType:action', () => {
+    const id = generateServiceId({
+      section: 'identity',
+      format: 'openid',
+      resourceType: 'Device',
+      action: '_dcr',
+    });
+    expect(id).toBe('#identity:openid:device:_dcr');
+  });
+
+  it('filters empty parts', () => {
+    const id = generateServiceId({ section: 'x', format: 'y', resourceType: '', action: '_batch' });
+    expect(id).toBe('#x:y:_batch');
+  });
+});

package/__tests__/models-clinical-sections.test.ts

@@ -0,0 +1,32 @@
+import {
+  clinicalSectionRegistry,
+  getClinicalSectionByCode,
+  loincI18nKey,
+  supportedClinicalSectionCodes,
+  clinicalSectionTitleEn,
+} from '../src/models/clinical-sections.js';
+
+describe('clinical sections', () => {
+  it('builds i18n keys from LOINC codes', () => {
+    expect(loincI18nKey('1234-5')).toBe('org.loinc.1234-5');
+  });
+
+  it('exposes supported section codes', () => {
+    const codes = Object.keys(clinicalSectionTitleEn);
+    expect(supportedClinicalSectionCodes.length).toBe(codes.length);
+    expect(supportedClinicalSectionCodes).toContain(codes[0]);
+  });
+
+  it('provides registry entries', () => {
+    const code = supportedClinicalSectionCodes[0];
+    const entry = clinicalSectionRegistry[code];
+    expect(entry.code).toBe(code);
+    expect(entry.i18nKey).toBe(loincI18nKey(code));
+  });
+
+  it('gets clinical section by code', () => {
+    const code = supportedClinicalSectionCodes[0];
+    expect(getClinicalSectionByCode(code)?.code).toBe(code);
+    expect(getClinicalSectionByCode('missing')).toBeUndefined();
+  });
+});

package/__tests__/models-multibase58.test.ts

@@ -0,0 +1,33 @@
+import {
+  decodeMultibase58btc,
+  decodeMultibase58btcToHex,
+  decodeMultibase58btcToUUID,
+  encodeHexToMultibase58btc,
+  encodeMultibase58btc,
+} from '../src/models/multibase58.js';
+
+describe('models multibase58', () => {
+  it('round-trips hex to multibase and back', () => {
+    const hex = '00112233445566778899aabbccddeeff';
+    const encoded = encodeHexToMultibase58btc(hex);
+    const decodedHex = decodeMultibase58btcToHex(encoded);
+    expect(decodedHex).toBe(hex);
+  });
+
+  it('decodes to UUID with hyphens', () => {
+    const hex = '00112233445566778899aabbccddeeff';
+    const encoded = encodeHexToMultibase58btc(hex);
+    expect(decodeMultibase58btcToUUID(encoded)).toBe('00112233-4455-6677-8899-aabbccddeeff');
+  });
+
+  it('encodes and decodes raw bytes', () => {
+    const bytes = new Uint8Array([9, 9, 9]);
+    const encoded = encodeMultibase58btc(bytes);
+    const decoded = decodeMultibase58btc(encoded);
+    expect(Array.from(decoded)).toEqual([9, 9, 9]);
+  });
+
+  it('throws for invalid hex input', () => {
+    expect(() => encodeHexToMultibase58btc('not-hex')).toThrow(/Invalid 16-byte hex string/);
+  });
+});

package/__tests__/multibase58.errors.test.ts

@@ -0,0 +1,7 @@
+import { decodeMultibase58btc } from '../src/utils/multibase58.js';
+
+describe('multibase58 (errors)', () => {
+  it('throws on empty string', () => {
+    expect(() => decodeMultibase58btc('')).toThrow();
+  });
+});

package/__tests__/multibase58.test.ts

@@ -0,0 +1,28 @@
+import {
+  decodeMultibase58btc,
+  decodeMultibase58btcToHex,
+  decodeMultibase58btcToUUID,
+  encodeHexToMultibase58btc,
+  encodeMultibase58btc,
+} from '../src/utils/multibase58.js';
+
+describe('multibase58', () => {
+  it('round-trips bytes', () => {
+    const bytes = new Uint8Array([1, 2, 3, 250, 251, 252]);
+    const encoded = encodeMultibase58btc(bytes);
+    expect(encoded.startsWith('z')).toBe(true);
+    const decoded = decodeMultibase58btc(encoded);
+    expect(Array.from(decoded)).toEqual(Array.from(bytes));
+  });
+
+  it('throws if prefix is missing', () => {
+    expect(() => decodeMultibase58btc('not-prefixed')).toThrow(/missing 'z' prefix/i);
+  });
+
+  it('round-trips hex to multibase and back', () => {
+    const hex = '00112233445566778899aabbccddeeff';
+    const encoded = encodeHexToMultibase58btc(hex);
+    expect(decodeMultibase58btcToHex(encoded)).toBe(hex);
+    expect(decodeMultibase58btcToUUID(encoded)).toBe('00112233-4455-6677-8899-aabbccddeeff');
+  });
+});

package/__tests__/multibasehash.test.ts

@@ -0,0 +1,25 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+
+import baseX from 'base-x';
+import { encodeMultibaseSha384 } from '../src/utils/multibasehash';
+
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const base58btc = baseX(BASE58_ALPHABET);
+
+describe('encodeMultibaseSha384', () => {
+  it('returns a multibase base58btc string with SHA-384 prefix', () => {
+    const output = encodeMultibaseSha384('hello');
+    expect(output.startsWith('z')).toBe(true);
+
+    const decoded = base58btc.decode(output.slice(1));
+    expect(decoded[0]).toBe(0x15);
+    expect(decoded[1]).toBe(0x30);
+    expect(decoded.length).toBe(2 + 48);
+  });
+
+  it('is deterministic for same input', () => {
+    const a = encodeMultibaseSha384('same');
+    const b = encodeMultibaseSha384('same');
+    expect(a).toBe(b);
+  });
+});

package/__tests__/utils-actor.test.ts

@@ -0,0 +1,22 @@
+import { parseActorFromSub } from '../src/utils/actor.js';
+
+describe('parseActorFromSub', () => {
+  it('returns trimmed subject and minimal info for empty input', () => {
+    expect(parseActorFromSub('  ')).toEqual({ sub: '' });
+  });
+
+  it('parses did:web subject with organization, email, and role', () => {
+    const sub = 'did:web:api.acme.org:employee:Doctor1@ACME.org:role:ISCO-08|2211';
+    const parsed = parseActorFromSub(sub);
+    expect(parsed.sub).toBe(sub);
+    expect(parsed.organization).toBe('did:web:api.acme.org');
+    expect(parsed.email).toBe('doctor1@acme.org');
+    expect(parsed.role).toBe('ISCO-08|2211');
+  });
+
+  it('parses raw email subject', () => {
+    const parsed = parseActorFromSub('  User@Example.com ');
+    expect(parsed.sub).toBe('User@Example.com');
+    expect(parsed.email).toBe('user@example.com');
+  });
+});