gdc-common-utils-ts 1.0.5 → 1.0.8

package/dist/AesManager.d.ts

@@ -0,0 +1,27 @@
+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 declare class AesManager {
+    private readonly ALGORITHM;
+    private readonly KEY_SIZE;
+    private readonly IV_GENERATION_SIZE;
+    private readonly TAG_SIZE_BYTES;
+    /**
+     * 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.
+     */
+    encrypt(plaintext: string, cekBytes: Uint8Array, aad: string): Promise<ProtectedDataAES>;
+    /**
+     * 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.
+     */
+    decrypt(encryptedData: ProtectedDataAES, cekBytes: Uint8Array, aad: string): Promise<string>;
+}

package/dist/AesManager.js

@@ -0,0 +1,62 @@
+// 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.js';
+/**
+ * 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 {
+    ALGORITHM = 'aes-256-gcm';
+    KEY_SIZE = 32; // 256-bit key
+    IV_GENERATION_SIZE = 12; // 96-bit IV, recommended by NIST for GCM
+    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, cekBytes, aad) {
+        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, cekBytes, aad) {
+        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);
+    }
+}

package/dist/CryptographyService.d.ts

@@ -0,0 +1,76 @@
+import { ICryptoHelper } from './interfaces/ICryptoHelper';
+import { ICryptography } from './interfaces/ICryptography';
+import { DataCompactJWT, JwtCompactParts } from './models/jwt';
+import { JweObject } from './models/jwe';
+import { MlkemPublicJwk, MldsaPublicJwk, PublicJwk, MlkemPrivateJwk, MldsaAlg, MlkemCurve } from './interfaces/Cryptography.types';
+import { ProtectedDataAES } from './models/aes';
+/**
+ * Implements the ICryptography interface, providing a complete suite of low-level,
+ * stateless cryptographic functions. This service is the "engine" of the security layer,
+ * orchestrating Post-Quantum and AES primitives.
+ */
+export declare class CryptographyService implements ICryptography {
+    private aesManager;
+    private cryptoHelper;
+    private mlDsaModule;
+    private mlKemModule;
+    private readonly ML_KEM_SEED_SIZE;
+    private readonly ML_DSA_SEED_SIZE;
+    constructor(cryptoHelper: ICryptoHelper);
+    private loadMlDsa;
+    private loadMlKem;
+    digestString(data: string, algorithm: string): Promise<string>;
+    generateKeyPairMlKem(seedBytes?: Uint8Array, crv?: MlkemCurve): Promise<{
+        publicJWKey: MlkemPublicJwk & {
+            kid: string;
+        };
+        secretKeyBytes: Uint8Array;
+    }>;
+    generateKeyPairMlDsa(seedBytes?: Uint8Array, alg?: MldsaAlg): Promise<{
+        publicJWKey: MldsaPublicJwk & {
+            kid: string;
+        };
+        secretKeyBytes: Uint8Array;
+    }>;
+    encryptJwe(payload: object, protectedHeader: object, secretJWKey: MlkemPrivateJwk, recipientsJWKeys: MlkemPublicJwk[]): Promise<JweObject>;
+    encryptJweToCompact(payload: object | string, protectedHeader: object, secretJWKey: MlkemPrivateJwk, recipientJWKey: MlkemPublicJwk): Promise<string>;
+    decryptJwe(jwe: JweObject | string, secretKeyJwk: MlkemPrivateJwk): Promise<{
+        decryptedBytes: Uint8Array;
+        protectedHeader: object;
+    }>;
+    getRecipientKidsFromJwe(jwe: JweObject | string): string[];
+    signDataJws(payload: object, protectedHeader: object, secretKeyBytes: Uint8Array): Promise<JwtCompactParts>;
+    verifyJws(jws: JwtCompactParts | string, publicJwk: PublicJwk): Promise<boolean>;
+    verifyDetachedJws(payloadBytes: Uint8Array, detachedJws: string, publicJWKey: PublicJwk): Promise<boolean>;
+    encrypt(plaintext: string, cekBytes: Uint8Array, aad: string): Promise<ProtectedDataAES>;
+    decrypt(encryptedData: ProtectedDataAES, cekBytes: Uint8Array, aad: string): Promise<string>;
+    encapsulate(cekSeedBytes: Uint8Array, secretKeyBytes: Uint8Array, recipientPublicKeyBytes: Uint8Array): Promise<{
+        encapsulatedCekBytes: Uint8Array;
+        derivedCekBytes: Uint8Array;
+    }>;
+    decapsulate(encapsulatedBytes: Uint8Array, secretKeyBytes: Uint8Array): Promise<Uint8Array>;
+    signBytes(payloadBytes: Uint8Array, secretKeyBytes: Uint8Array, alg: MldsaAlg): Promise<Uint8Array>;
+    verifyBytes(signatureBytes: Uint8Array, dataBytes: Uint8Array, publicKey: PublicJwk): Promise<boolean>;
+    jwsToCompact(jws: DataCompactJWT): string;
+    parseCompactJws(jwsString: string): DataCompactJWT;
+    parseCompactJwe(jweString: string): JweObject;
+    /**
+     * Computes a JWK thumbprint using a specified hash algorithm.
+     * This implementation is platform-agnostic by using the injected ICryptoHelper.
+     */
+    private _computeJwkThumbprint;
+    /**
+     * Creates a canonical string from a simple, flat JSON object as required by
+     * RFC 7638 for JWK thumbprints.
+     */
+    private _canonicalizeForJwkThumbprint;
+    /**
+     * Extracts the Base JWK for thumbprint calculation per RFC 7638.
+     * This handles both Post-Quantum (OKP, AKP) and legacy (EC) key types.
+     */
+    private _toBaseJwk;
+    /**
+     * Utility to convert a hex string to a Uint8Array.
+     */
+    private _hexToBytes;
+}

package/dist/CryptographyService.js

@@ -0,0 +1,403 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/CryptographyService.ts
+import * as pako from 'pako';
+import * as jwtUtils from './utils/jwt.js';
+import { AesManager } from './AesManager.js';
+import { Content } from './utils/content.js';
+/**
+ * Implements the ICryptography interface, providing a complete suite of low-level,
+ * stateless cryptographic functions. This service is the "engine" of the security layer,
+ * orchestrating Post-Quantum and AES primitives.
+ */
+export class CryptographyService {
+    aesManager;
+    cryptoHelper;
+    mlDsaModule = null;
+    mlKemModule = null;
+    // Constants for seed sizes, as per @noble library requirements.
+    ML_KEM_SEED_SIZE = 64;
+    ML_DSA_SEED_SIZE = 32;
+    constructor(cryptoHelper) {
+        this.aesManager = new AesManager();
+        this.cryptoHelper = cryptoHelper;
+    }
+    async loadMlDsa() {
+        if (this.mlDsaModule)
+            return this.mlDsaModule;
+        try {
+            // Use explicit .js subpath to satisfy package exports in Metro/Node ESM.
+            const module = await import('@noble/post-quantum/ml-dsa.js');
+            this.mlDsaModule = module;
+            return module;
+        }
+        catch (error) {
+            throw new Error('[CryptographyService] Missing dependency "@noble/post-quantum/ml-dsa.js". Install it for ML-DSA operations.');
+        }
+    }
+    async loadMlKem() {
+        if (this.mlKemModule)
+            return this.mlKemModule;
+        try {
+            // Use explicit .js subpath to satisfy package exports in Metro/Node ESM.
+            const module = await import('@noble/post-quantum/ml-kem.js');
+            this.mlKemModule = module;
+            return module;
+        }
+        catch (error) {
+            throw new Error('[CryptographyService] Missing dependency "@noble/post-quantum/ml-kem.js". Install it for ML-KEM operations.');
+        }
+    }
+    digestString(data, algorithm) {
+        return this.cryptoHelper.digestString(data, algorithm);
+    }
+    // --- Key Generation ---
+    async generateKeyPairMlKem(seedBytes, crv = 'ML-KEM-768') {
+        const mlKem = await this.loadMlKem();
+        let seed;
+        if (seedBytes && seedBytes.length === this.ML_KEM_SEED_SIZE) {
+            seed = seedBytes;
+        }
+        else {
+            seed = await this.cryptoHelper.getRandomBytes(this.ML_KEM_SEED_SIZE);
+        }
+        let keygenFn;
+        switch (crv) {
+            case 'ML-KEM-512':
+                keygenFn = mlKem.ml_kem512.keygen;
+                break;
+            case 'ML-KEM-1024':
+                keygenFn = mlKem.ml_kem1024.keygen;
+                break;
+            case 'ML-KEM-768':
+            default:
+                keygenFn = mlKem.ml_kem768.keygen;
+                break;
+        }
+        const { secretKey, publicKey: publicKeyBytes } = keygenFn(seed);
+        const pubJwkWithoutKid = {
+            kty: 'OKP', crv: crv, x: Content.bytesToRawBase64UrlSafe(publicKeyBytes),
+        };
+        const kid = await this._computeJwkThumbprint(pubJwkWithoutKid);
+        const publicKey = { ...pubJwkWithoutKid, kid };
+        return { publicJWKey: publicKey, secretKeyBytes: secretKey };
+    }
+    async generateKeyPairMlDsa(seedBytes, alg = 'ML-DSA-44') {
+        const mlDsa = await this.loadMlDsa();
+        let seed;
+        if (seedBytes && seedBytes.length === this.ML_DSA_SEED_SIZE) {
+            seed = seedBytes;
+        }
+        else {
+            seed = await this.cryptoHelper.getRandomBytes(this.ML_DSA_SEED_SIZE);
+        }
+        let keygenFn;
+        switch (alg) {
+            case 'ML-DSA-65':
+                keygenFn = mlDsa.ml_dsa65.keygen;
+                break;
+            case 'ML-DSA-87':
+                keygenFn = mlDsa.ml_dsa87.keygen;
+                break;
+            case 'ML-DSA-44':
+            default:
+                keygenFn = mlDsa.ml_dsa44.keygen;
+                break;
+        }
+        const { secretKey, publicKey: publicKeyBytes } = keygenFn(seed);
+        const pubJwkWithoutKid = {
+            kty: 'AKP', alg: alg, pub: Content.bytesToRawBase64UrlSafe(publicKeyBytes),
+        };
+        const kid = await this._computeJwkThumbprint(pubJwkWithoutKid);
+        const publicKey = { ...pubJwkWithoutKid, kid };
+        return { publicJWKey: publicKey, secretKeyBytes: secretKey };
+    }
+    // --- High-Level Workflows ---
+    async encryptJwe(payload, protectedHeader, secretJWKey, recipientsJWKeys) {
+        // ARCHITECTURAL NOTE: This implementation is currently only suitable for a single recipient.
+        // A Key Encapsulation Mechanism (KEM) derives a *different* shared secret for each recipient's public key.
+        // A true multi-recipient JWE requires a single Content Encryption Key (CEK) that is then
+        // encrypted (wrapped) for each recipient. This code uses the KEM-derived shared secret as the CEK.
+        // This must be refactored to a key-wrapping approach to support multiple recipients correctly.
+        if (recipientsJWKeys.length !== 1) {
+            // Temporarily throw until the architecture is fixed for multi-recipient.
+            throw new Error("CryptographyService.encryptJwe currently only supports a single recipient.");
+        }
+        const recipient = recipientsJWKeys[0];
+        const publicKeyBytes = Content.base64ToBytes(recipient.x);
+        // Per RFC 9278, we generate a random seed for the KEM. The KEM then derives both the
+        // final Content Encryption Key (CEK) and the encapsulated key from this seed.
+        const cekSeedBytes = await this.cryptoHelper.getRandomBytes(32);
+        const { derivedCekBytes, // This is the actual Content Encryption Key
+        encapsulatedCekBytes // This is the encrypted key for the recipient
+         } = await this.encapsulate(cekSeedBytes, secretJWKey.dBytes, publicKeyBytes);
+        // 2. Now, use the *derived* CEK to encrypt the payload with AES.
+        const protectedHeaderB64Url = Content.objectToRawBase64UrlSafe(protectedHeader);
+        let payloadBytes = Content.objectToBytes(payload);
+        let payloadString;
+        if (protectedHeader.zip === 'DEF') {
+            payloadBytes = pako.deflate(payloadBytes);
+            payloadString = Content.bytesToRawBase64UrlSafe(payloadBytes);
+        }
+        else {
+            payloadString = Content.bytesToStringASCII(payloadBytes);
+        }
+        const encrypted = await this.encrypt(payloadString, derivedCekBytes, protectedHeaderB64Url);
+        // 3. Assemble the JWE. The `encrypted_key` is the result of the KEM encapsulation.
+        const recipientData = [{
+                header: { alg: recipient.crv, kid: recipient.kid },
+                encrypted_key: Content.bytesToRawBase64UrlSafe(encapsulatedCekBytes),
+            }];
+        return {
+            protected: protectedHeaderB64Url,
+            recipients: recipientData,
+            iv: encrypted.iv,
+            ciphertext: encrypted.ciphertext,
+            tag: encrypted.tag,
+        };
+    }
+    async encryptJweToCompact(payload, protectedHeader, secretJWKey, recipientJWKey) {
+        // 1. Construct the complete, final protected header by merging the main and recipient headers.
+        const recipientHeader = { alg: recipientJWKey.crv, kid: recipientJWKey.kid };
+        const finalProtectedHeader = { ...protectedHeader, ...recipientHeader };
+        const protectedHeaderB64Url = Content.objectToRawBase64UrlSafe(finalProtectedHeader);
+        // 2. Perform KEM to derive the Content Encryption Key (CEK).
+        const publicKeyBytes = Content.base64ToBytes(recipientJWKey.x);
+        const cekSeedBytes = await this.cryptoHelper.getRandomBytes(32);
+        const { derivedCekBytes, encapsulatedCekBytes } = await this.encapsulate(cekSeedBytes, secretJWKey.dBytes, publicKeyBytes);
+        const encapsulatedKeyB64Url = Content.bytesToRawBase64UrlSafe(encapsulatedCekBytes);
+        // 3. Encrypt the payload using the derived CEK and the *final* protected header as AAD.
+        const payloadBytes = typeof payload === 'string'
+            ? Content.stringToBytesUTF8(payload)
+            : Content.objectToBytes(payload);
+        if (finalProtectedHeader.zip === 'DEF') {
+            // Note: Compressing a compact JWS string is often inefficient, but supported.
+            const compressedPayload = pako.deflate(payloadBytes);
+            const payloadString = Content.bytesToRawBase64UrlSafe(compressedPayload);
+            const encrypted = await this.encrypt(payloadString, derivedCekBytes, protectedHeaderB64Url);
+            return `${protectedHeaderB64Url}.${encapsulatedKeyB64Url}.${encrypted.iv}.${encrypted.ciphertext}.${encrypted.tag}`;
+        }
+        const payloadString = Content.bytesToStringASCII(payloadBytes);
+        const encrypted = await this.encrypt(payloadString, derivedCekBytes, protectedHeaderB64Url);
+        // 4. Assemble the 5 parts of the compact JWE.
+        return `${protectedHeaderB64Url}.${encapsulatedKeyB64Url}.${encrypted.iv}.${encrypted.ciphertext}.${encrypted.tag}`;
+    }
+    async decryptJwe(jwe, secretKeyJwk) {
+        const jweObject = typeof jwe === 'string' ? this.parseCompactJwe(jwe) : jwe;
+        const recipient = jweObject.recipients.find(r => r.header?.kid === secretKeyJwk.kid);
+        if (!recipient || !recipient.encrypted_key) {
+            throw new Error(`JWE does not contain a recipient with kid=${secretKeyJwk.kid}`);
+        }
+        // Decapsulate to get the CEK
+        const encapsulatedKeyBytes = Content.base64ToBytes(recipient.encrypted_key);
+        const cekBytes = await this.decapsulate(encapsulatedKeyBytes, secretKeyJwk.dBytes);
+        // Decrypt the payload
+        const encryptedData = { ciphertext: jweObject.ciphertext, iv: jweObject.iv, tag: jweObject.tag };
+        const decryptedPayloadString = await this.decrypt(encryptedData, cekBytes, jweObject.protected);
+        // Handle decompression
+        const protectedHeader = Content.base64UrlSafeToJSON(jweObject.protected);
+        let decryptedBytes;
+        if (protectedHeader.zip === 'DEF') {
+            const compressedBytes = Content.base64ToBytes(decryptedPayloadString);
+            decryptedBytes = pako.inflate(compressedBytes);
+        }
+        else {
+            decryptedBytes = Content.stringToBytesUTF8(decryptedPayloadString);
+        }
+        return { decryptedBytes, protectedHeader };
+    }
+    getRecipientKidsFromJwe(jwe) {
+        const jweObject = typeof jwe === 'string' ? this.parseCompactJwe(jwe) : jwe;
+        if (!jweObject.recipients) {
+            return [];
+        }
+        return jweObject.recipients
+            .map(recipient => recipient.header?.kid)
+            .filter((kid) => !!kid);
+    }
+    async signDataJws(payload, protectedHeader, secretKeyBytes) {
+        const protectedHeaderB64Url = Content.objectToRawBase64UrlSafe(protectedHeader);
+        const payloadB64Url = await jwtUtils.encodePayload(payload);
+        const signingInput = `${protectedHeaderB64Url}.${payloadB64Url}`;
+        const signingInputBytes = Content.stringToBytesUTF8(signingInput);
+        // Infer algorithm from protected header
+        const alg = protectedHeader.alg;
+        if (!alg)
+            throw new Error("Protected header must contain 'alg' property for signing.");
+        const signatureBytes = await this.signBytes(signingInputBytes, secretKeyBytes, alg);
+        const jwsParts = {
+            protected: protectedHeaderB64Url,
+            payload: payloadB64Url,
+            signature: Content.bytesToRawBase64UrlSafe(signatureBytes),
+        };
+        return jwsParts;
+    }
+    async verifyJws(jws, publicJwk) {
+        const parts = typeof jws === 'string' ? jwtUtils.getPartsJWT(jws) : jws;
+        if (!parts)
+            throw new Error('Invalid Compact JWS format');
+        const signingInput = `${parts.protected}.${parts.payload}`;
+        const signingInputBytes = Content.stringToBytesUTF8(signingInput);
+        const signatureBytes = Content.base64ToBytes(parts.signature);
+        return this.verifyBytes(signatureBytes, signingInputBytes, publicJwk);
+    }
+    async verifyDetachedJws(payloadBytes, detachedJws, publicJWKey) {
+        const parts = detachedJws.split('..');
+        if (parts.length !== 2)
+            throw new Error("Invalid Detached JWS format");
+        const protectedHeaderB64Url = parts[0];
+        const signatureB64Url = parts[1];
+        const payloadB64Url = Content.bytesToRawBase64UrlSafe(payloadBytes);
+        const signingInput = `${protectedHeaderB64Url}.${payloadB64Url}`;
+        const signingInputBytes = Content.stringToBytesUTF8(signingInput);
+        const signatureBytes = Content.base64ToBytes(signatureB64Url);
+        return this.verifyBytes(signatureBytes, signingInputBytes, publicJWKey);
+    }
+    // --- Low-Level Primitives ---
+    encrypt(plaintext, cekBytes, aad) {
+        return this.aesManager.encrypt(plaintext, cekBytes, aad);
+    }
+    decrypt(encryptedData, cekBytes, aad) {
+        return this.aesManager.decrypt(encryptedData, cekBytes, aad);
+    }
+    async encapsulate(cekSeedBytes, secretKeyBytes, recipientPublicKeyBytes) {
+        // According to RFC 9278 (JWE with ML-KEM), a seed is used for the KEM encapsulation.
+        // The KEM then derives a shared secret from this seed. It is this *derived* shared secret
+        // that is used to encrypt the content, NOT the original seed.
+        // The `encapsulate` function from the noble library handles this correctly by accepting the
+        // seed as the second argument. It returns both the encapsulated key (`cipherText`)
+        // and the derived shared secret, which we must use as the actual AES key.
+        const mlKem = await this.loadMlKem();
+        const { sharedSecret, cipherText } = await mlKem.ml_kem768.encapsulate(recipientPublicKeyBytes, cekSeedBytes);
+        return { derivedCekBytes: sharedSecret, encapsulatedCekBytes: cipherText };
+    }
+    async decapsulate(encapsulatedBytes, secretKeyBytes) {
+        const mlKem = await this.loadMlKem();
+        return mlKem.ml_kem768.decapsulate(encapsulatedBytes, secretKeyBytes);
+    }
+    async signBytes(payloadBytes, secretKeyBytes, alg) {
+        const mlDsa = await this.loadMlDsa();
+        switch (alg) {
+            case 'ML-DSA-44': return mlDsa.ml_dsa44.sign(payloadBytes, secretKeyBytes);
+            case 'ML-DSA-65': return mlDsa.ml_dsa65.sign(payloadBytes, secretKeyBytes);
+            case 'ML-DSA-87': return mlDsa.ml_dsa87.sign(payloadBytes, secretKeyBytes);
+            default: throw new Error(`Unsupported ML-DSA algorithm: ${alg}`);
+        }
+    }
+    async verifyBytes(signatureBytes, dataBytes, publicKey) {
+        const mlDsa = await this.loadMlDsa();
+        const publicKeyBytes = Content.base64ToBytes(publicKey.pub || publicKey.x);
+        const alg = publicKey.alg;
+        if (!alg)
+            throw new Error("Public key must contain 'alg' property for verification.");
+        switch (alg) {
+            case 'ML-DSA-44': return mlDsa.ml_dsa44.verify(signatureBytes, dataBytes, publicKeyBytes);
+            case 'ML-DSA-65': return mlDsa.ml_dsa65.verify(signatureBytes, dataBytes, publicKeyBytes);
+            case 'ML-DSA-87': return mlDsa.ml_dsa87.verify(signatureBytes, dataBytes, publicKeyBytes);
+            default: throw new Error(`Unsupported ML-DSA algorithm: ${alg}`);
+        }
+    }
+    // --- Formatting & Parsing Utilities ---
+    jwsToCompact(jws) {
+        return `${jws.protected}.${jws.payload}.${jws.signature}`;
+    }
+    parseCompactJws(jwsString) {
+        if (jwsString.trim().startsWith('{')) {
+            const parsed = JSON.parse(jwsString);
+            if (!parsed.payload || !parsed.signatures || !parsed.signatures[0]) {
+                throw new Error("Invalid JWS JSON format");
+            }
+            return {
+                payload: parsed.payload,
+                protected: parsed.signatures[0].protected,
+                signature: parsed.signatures[0].signature,
+            };
+        }
+        const parts = jwtUtils.getPartsJWT(jwsString);
+        if (!parts)
+            throw new Error("Invalid Compact JWS format");
+        const result = {
+            payload: Content.base64UrlSafeToJSON(parts.payload),
+            protected: Content.base64UrlSafeToJSON(parts.protected),
+            signature: Content.base64ToBytes(parts.signature),
+        };
+        return result;
+    }
+    parseCompactJwe(jweString) {
+        if (jweString.trim().startsWith('{')) {
+            return JSON.parse(jweString);
+        }
+        const parts = jweString.split('.');
+        if (parts.length !== 5)
+            throw new Error("Invalid Compact JWE format");
+        const protectedHeader = Content.base64UrlSafeToJSON(parts[0]);
+        // Compact JWE has no per-recipient header, but our model requires one.
+        // The 'kid' should be in the main protected header for decryption to work.
+        return {
+            protected: parts[0],
+            recipients: [{
+                    header: { alg: protectedHeader.alg || '', kid: protectedHeader.kid || '' },
+                    encrypted_key: parts[1]
+                }],
+            iv: parts[2],
+            ciphertext: parts[3],
+            tag: parts[4],
+        };
+    }
+    // --- JWK Thumbprint Calculation (RFC 7638) ---
+    /**
+     * Computes a JWK thumbprint using a specified hash algorithm.
+     * This implementation is platform-agnostic by using the injected ICryptoHelper.
+     */
+    async _computeJwkThumbprint(jwk, hash = "SHA-256") {
+        const baseJwk = this._toBaseJwk(jwk);
+        const canonical = this._canonicalizeForJwkThumbprint(baseJwk);
+        // Use the platform-agnostic digest method
+        const digestHex = await this.cryptoHelper.digestString(canonical, hash);
+        // The digestString returns a hex string, but thumbprints are Base64UrlSafe.
+        // We need to convert from hex to bytes, then bytes to Base64UrlSafe.
+        const digestBytes = this._hexToBytes(digestHex);
+        return Content.bytesToRawBase64UrlSafe(digestBytes);
+    }
+    /**
+     * Creates a canonical string from a simple, flat JSON object as required by
+     * RFC 7638 for JWK thumbprints.
+     */
+    _canonicalizeForJwkThumbprint(obj) {
+        const keys = Object.keys(obj).sort();
+        const parts = keys.map(k => `"${k}":${JSON.stringify(obj[k])}`);
+        return `{${parts.join(",")}}`;
+    }
+    /**
+     * Extracts the Base JWK for thumbprint calculation per RFC 7638.
+     * This handles both Post-Quantum (OKP, AKP) and legacy (EC) key types.
+     */
+    _toBaseJwk(jwk) {
+        if (jwk.kty === "OKP") {
+            const { crv, x } = jwk;
+            return { kty: "OKP", crv, x };
+        }
+        else if (jwk.kty === "AKP") {
+            const { alg, pub } = jwk;
+            return { kty: "AKP", alg, pub };
+        }
+        else if (jwk.kty === "EC") {
+            const { crv, x, y } = jwk;
+            const baseJwk = { kty: "EC", crv, x, y };
+            return baseJwk;
+        }
+        else {
+            const exhaustiveCheck = jwk;
+            throw new Error(`Unsupported key type for JWK thumbprint: ${exhaustiveCheck.kty}`);
+        }
+    }
+    /**
+     * Utility to convert a hex string to a Uint8Array.
+     */
+    _hexToBytes(hex) {
+        const bytes = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < hex.length; i += 2) {
+            bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+        }
+        return bytes;
+    }
+}

package/dist/constants/Schemas.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Defines the types of form requests that can be sent in a batch.
+ */
+export declare const FormRequestType: {
+    readonly IndividualTerms: "IndividualTerms";
+    readonly PersonalIdentity: "PersonalIdentity";
+};
+export declare const Sector: {
+    readonly EMERGENCY: "emergency";
+    readonly HEALTH_CARE: "health-care";
+    readonly HEALTH_INSURANCE: "health-insurance";
+    readonly RESEARCH: "research";
+};
+export type Sector = typeof Sector[keyof typeof Sector];
+export declare const Section: {
+    readonly REGISTRY: "registry";
+    readonly ENTITY: "entity";
+    readonly INDIVIDUAL: "individual";
+    readonly NETWORK: "network";
+};
+export type Section = typeof Section[keyof typeof Section];
+export declare const Format: {
+    readonly SCHEMA: "org.schema";
+    readonly FHIR_API: "org.hl7.fhir.api";
+};
+export type Format = typeof Format[keyof typeof Format];
+export declare const Resource: {
+    readonly PERSON: "Person";
+    readonly RELATED_PERSON: "RelatedPerson";
+    readonly EMPLOYEE: "Employee";
+    readonly EMPLOYEE_ROLE: "EmployeeRole";
+    readonly PRACTITIONER: "Practitioner";
+    readonly PRACTITIONER_ROLE: "PractitionerRole";
+    readonly ORGANIZATION: "Organization";
+    readonly LOCATION: "Location";
+    readonly GROUP: "Group";
+};
+export type Resource = typeof Resource[keyof typeof Resource];
+export declare const JobAction: {
+    readonly BATCH: "_batch";
+    readonly CREATE: "_create";
+    readonly DISCOVERY: "_discovery";
+};
+export type JobAction = typeof JobAction[keyof typeof JobAction];
+export declare const knownDomainsReversed: readonly ["org.schema", "org.hl7.fhir", "org.ilo.isco", "net.openid"];

package/dist/constants/Schemas.js

@@ -0,0 +1,48 @@
+// constants/Schemas.ts
+// Based on the backend's src/models/schemaorg.ts
+/**
+ * Defines the types of form requests that can be sent in a batch.
+ */
+export const FormRequestType = {
+    IndividualTerms: 'IndividualTerms',
+    PersonalIdentity: 'PersonalIdentity',
+};
+// --- Enums for URL construction and validation ---
+export const Sector = {
+    EMERGENCY: 'emergency',
+    HEALTH_CARE: 'health-care',
+    HEALTH_INSURANCE: 'health-insurance',
+    RESEARCH: 'research',
+};
+export const Section = {
+    REGISTRY: 'registry',
+    ENTITY: 'entity',
+    INDIVIDUAL: 'individual',
+    NETWORK: 'network',
+};
+export const Format = {
+    SCHEMA: 'org.schema',
+    FHIR_API: 'org.hl7.fhir.api',
+};
+export const Resource = {
+    PERSON: 'Person',
+    RELATED_PERSON: 'RelatedPerson',
+    EMPLOYEE: 'Employee',
+    EMPLOYEE_ROLE: 'EmployeeRole',
+    PRACTITIONER: 'Practitioner',
+    PRACTITIONER_ROLE: 'PractitionerRole',
+    ORGANIZATION: 'Organization',
+    LOCATION: 'Location',
+    GROUP: 'Group',
+};
+export const JobAction = {
+    BATCH: '_batch',
+    CREATE: '_create',
+    DISCOVERY: '_discovery',
+};
+export const knownDomainsReversed = [
+    'org.schema',
+    'org.hl7.fhir',
+    'org.ilo.isco',
+    'net.openid',
+];

package/dist/constants/index.js

@@ -0,0 +1 @@
+export * from './schemaorg.js';