@virtru/dsp-sdk 0.4.1 → 0.5.0

package/lib-commonjs/src/lib/fips-crypto/key-format.js

@@ -0,0 +1,243 @@
+"use strict";
+/*
+ * Copyright (c) Virtru Corporation.  All rights reserved.
+ *
+ * Your use of this file is governed by the Virtu Terms of Service <https://www.virtru.com/terms-of-service/>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importPublicKey = importPublicKey;
+exports.importPrivateKey = importPrivateKey;
+exports.exportPublicKeyPem = exportPublicKeyPem;
+exports.exportPublicKeyJwk = exportPublicKeyJwk;
+exports.exportPrivateKeyPem = exportPrivateKeyPem;
+exports.parsePublicKeyPem = parsePublicKeyPem;
+exports.extractPublicKeyPem = extractPublicKeyPem;
+exports.jwkToPublicKeyPem = jwkToPublicKeyPem;
+const singlecontainer_1 = require("@opentdf/sdk/singlecontainer");
+const sdk_1 = require("@opentdf/sdk");
+const cryptoutils_1 = require("@opentdf/sdk/cryptoutils");
+const encodings_1 = require("@opentdf/sdk/encodings");
+const primitives_1 = require("./primitives");
+const keys_1 = require("./keys");
+const VERIFY_USAGE = ['verify'];
+const ENCRYPT_VERIFY_USAGES = ['encrypt', 'verify'];
+const SIGN_USAGE = ['sign'];
+const DECRYPT_USAGE = ['decrypt'];
+// ─── PEM Utilities ────────────────────────────────────────────────────────────
+/**
+ * Strip PEM headers/footers and whitespace, decode base64 → raw DER bytes.
+ */
+function pemToBytes(pem) {
+    return new Uint8Array(encodings_1.base64.decodeArrayBuffer((0, cryptoutils_1.removePemFormatting)(pem)));
+}
+/**
+ * Parse the RSA modulus bit length from SPKI-formatted DER bytes.
+ * Walks: SEQUENCE { AlgorithmIdentifier, BIT STRING { RSAPublicKey { modulus INTEGER } } }
+ */
+function rsaModulusBitsFromSpki(spki) {
+    let pos = 0;
+    const readLen = () => {
+        let len = spki[pos++];
+        if (len & 0x80) {
+            const n = len & 0x7f;
+            len = 0;
+            for (let i = 0; i < n; i++)
+                len = (len << 8) | spki[pos++];
+        }
+        return len;
+    };
+    // SPKI outer SEQUENCE
+    pos++;
+    readLen();
+    // Skip AlgorithmIdentifier SEQUENCE
+    pos++;
+    pos += readLen();
+    // BIT STRING
+    pos++;
+    readLen();
+    pos++; // unused-bits byte
+    // RSAPublicKey SEQUENCE
+    pos++;
+    readLen();
+    // modulus INTEGER tag + length
+    pos++;
+    const modulusLen = readLen();
+    // Leading 0x00 is a sign byte for positive INTEGERs — exclude it
+    const padding = spki[pos] === 0x00 ? 1 : 0;
+    return (modulusLen - padding) * 8;
+}
+// ─── ASN.1 Helpers ────────────────────────────────────────────────────────────
+function asn1EncodeLength(len) {
+    if (len < 0x80)
+        return new Uint8Array([len]);
+    if (len < 0x100)
+        return new Uint8Array([0x81, len]);
+    return new Uint8Array([0x82, (len >> 8) & 0xff, len & 0xff]);
+}
+function asn1Concat(arrays) {
+    const total = arrays.reduce((s, a) => s + a.length, 0);
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const a of arrays) {
+        out.set(a, off);
+        off += a.length;
+    }
+    return out;
+}
+function asn1Sequence(elements) {
+    const body = asn1Concat(elements);
+    return asn1Concat([new Uint8Array([0x30]), asn1EncodeLength(body.length), body]);
+}
+function asn1BitString(data) {
+    const inner = asn1Concat([new Uint8Array([0x00]), data]); // 0x00 = zero unused bits
+    return asn1Concat([new Uint8Array([0x03]), asn1EncodeLength(inner.length), inner]);
+}
+// RSA AlgorithmIdentifier: SEQUENCE { OID 1.2.840.113549.1.1.1, NULL }
+const RSA_ALG_ID = asn1Sequence([
+    new Uint8Array([0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01]),
+    new Uint8Array([0x05, 0x00]),
+]);
+/**
+ * Returns true if the DER bytes are already SPKI format (have an AlgorithmIdentifier OID).
+ */
+function isSpkiFormat(derBytes) {
+    const hexStr = encodings_1.hex.encodeArrayBuffer(derBytes.buffer);
+    try {
+        (0, cryptoutils_1.guessAlgorithmName)(hexStr);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wraps a bare RSAPublicKey (PKCS#1) blob in an SPKI AlgorithmIdentifier container.
+ * VirtruCrypto returns PKCS#1 for generated keys; imported keys are already SPKI.
+ */
+function normalizePublicKeyToSpki(exported) {
+    if (isSpkiFormat(exported))
+        return exported;
+    return asn1Sequence([RSA_ALG_ID, asn1BitString(exported)]);
+}
+/**
+ * Wraps a bare RSAPrivateKey (PKCS#1) blob in a PKCS#8 PrivateKeyInfo container.
+ * VirtruCrypto's exportKey('pkcs8') returns raw PKCS#1 DER — the 'pkcs8' flag
+ * just selects "export private key" vs "export public key" from the combined slot.
+ * We wrap it here to produce standard PKCS#8:
+ *   SEQUENCE { INTEGER 0, AlgorithmIdentifier, OCTET STRING { RSAPrivateKey } }
+ */
+function normalizePrivateKeyToPkcs8(pkcs1) {
+    const version = new Uint8Array([0x02, 0x01, 0x00]); // INTEGER 0
+    const privateKeyOctetString = asn1Concat([
+        new Uint8Array([0x04]),
+        asn1EncodeLength(pkcs1.length),
+        pkcs1,
+    ]);
+    return asn1Sequence([version, RSA_ALG_ID, privateKeyOctetString]);
+}
+// ─── Key Import ───────────────────────────────────────────────────────────────
+/**
+ * Import a PEM public key (SPKI) as an opaque PublicKey.
+ * Only RSA keys are supported in FIPS mode.
+ *
+ * @param pem - PEM-encoded public key (`-----BEGIN PUBLIC KEY-----`)
+ * @param options.usage - `'encrypt'` (RSA-OAEP) or `'sign'` (RS256 verify). Defaults to `'encrypt'`.
+ * @param options.extractable - Defaults to `true`.
+ * @param options.algorithmHint - Skips SPKI parsing when provided.
+ */
+async function importPublicKey(pem, options) {
+    const { usage = 'encrypt', extractable = true, algorithmHint } = options;
+    const keyBytes = pemToBytes(pem);
+    let algorithm;
+    if (algorithmHint) {
+        algorithm = algorithmHint;
+    }
+    else {
+        const modulusBits = rsaModulusBitsFromSpki(keyBytes);
+        algorithm = modulusBits <= 2048 ? 'rsa:2048' : 'rsa:4096';
+    }
+    if (!algorithm.startsWith('rsa:')) {
+        throw new sdk_1.ConfigurationError(`Key algorithm '${algorithm}' not supported in FIPS mode. Only RSA keys are supported.`);
+    }
+    // VirtruCrypto uses RSASSA-PKCS1-v1_5 as the import algorithm name for all RSA keys;
+    // the per-operation algorithm (RSA-OAEP vs PKCS1v15) is specified at call time.
+    const usages = usage === 'sign' ? VERIFY_USAGE : ENCRYPT_VERIFY_USAGES;
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const vKey = await crypto.importKey('spki', keyBytes, { name: 'RSASSA-PKCS1-v1_5' }, extractable, usages);
+    return (0, keys_1.wrapPublicKey)(vKey, algorithm);
+}
+/**
+ * Import a PEM private key (PKCS#8) as an opaque PrivateKey.
+ * Only RSA keys are supported in FIPS mode.
+ *
+ * @param pem - PEM-encoded private key (`-----BEGIN PRIVATE KEY-----`)
+ * @param options.usage - `'encrypt'` (RSA-OAEP decrypt) or `'sign'` (RS256). Defaults to `'encrypt'`.
+ * @param options.extractable - Defaults to `false`.
+ * @param options.algorithmHint - Algorithm label to attach. Defaults to `'rsa:2048'`.
+ */
+async function importPrivateKey(pem, options) {
+    const { usage = 'encrypt', extractable = false, algorithmHint } = options;
+    const keyBytes = pemToBytes(pem);
+    const algorithm = algorithmHint ?? 'rsa:2048';
+    if (!algorithm.startsWith('rsa:')) {
+        throw new sdk_1.ConfigurationError(`Key algorithm '${algorithm}' not supported in FIPS mode. Only RSA keys are supported.`);
+    }
+    const usages = usage === 'sign' ? SIGN_USAGE : DECRYPT_USAGE;
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const vKey = await crypto.importKey('pkcs8', keyBytes, { name: 'RSASSA-PKCS1-v1_5' }, extractable, usages);
+    return (0, keys_1.wrapPrivateKey)(vKey, algorithm);
+}
+// ─── Key Export ───────────────────────────────────────────────────────────────
+/**
+ * Export an opaque public key to PEM (SPKI / `-----BEGIN PUBLIC KEY-----`).
+ * Handles VirtruCrypto's PKCS#1 output for generated keys transparently.
+ */
+async function exportPublicKeyPem(key) {
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const exported = await crypto.exportKey('spki', (0, keys_1.unwrapPublicKey)(key));
+    const spki = normalizePublicKeyToSpki(exported);
+    return (0, cryptoutils_1.formatAsPem)(spki.buffer, 'PUBLIC KEY');
+}
+/**
+ * Export an opaque public key to JWK.
+ * Uses WebCrypto for the JWK conversion after normalizing to SPKI.
+ */
+async function exportPublicKeyJwk(key) {
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const exported = await crypto.exportKey('spki', (0, keys_1.unwrapPublicKey)(key));
+    const spki = normalizePublicKeyToSpki(exported);
+    const webKey = await globalThis.crypto.subtle.importKey('spki', spki, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, true, ['verify']);
+    return globalThis.crypto.subtle.exportKey('jwk', webKey);
+}
+/**
+ * Export an opaque private key to PEM (PKCS#8 / `-----BEGIN PRIVATE KEY-----`).
+ *
+ * FOR TESTING / DEVELOPMENT ONLY — not included in the CryptoService interface.
+ * Only works for keys that were imported via importPrivateKey (PKCS#8 format).
+ * Generated private keys cannot be exported from the FIPS keystore.
+ */
+async function exportPrivateKeyPem(key) {
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const exported = await crypto.exportKey('pkcs8', (0, keys_1.unwrapPrivateKey)(key));
+    const pkcs8 = normalizePrivateKeyToPkcs8(exported);
+    return (0, cryptoutils_1.formatAsPem)(pkcs8.buffer, 'PRIVATE KEY');
+}
+// ─── Public Key Utils ─────────────────────────────────────
+/**
+ * Use the WebCrypto API to parse a PEM public key and extract its algorithm info.
+ */
+async function parsePublicKeyPem(pem) {
+    return singlecontainer_1.WebCryptoService.parsePublicKeyPem(pem);
+}
+/**
+ * Use the WebCrypto API to extract the public key PEM from a certificate or PEM string.
+ */
+async function extractPublicKeyPem(certOrPem) {
+    return singlecontainer_1.WebCryptoService.extractPublicKeyPem(certOrPem);
+}
+/**
+ * Use the WebCrypto API to convert a JWK public key to PEM format.
+ */
+async function jwkToPublicKeyPem(jwk) {
+    return singlecontainer_1.WebCryptoService.jwkToPublicKeyPem(jwk);
+}

package/lib-commonjs/src/lib/fips-crypto/keys.js

@@ -0,0 +1,134 @@
+"use strict";
+/*
+ * Copyright (c) Virtru Corporation.  All rights reserved.
+ *
+ * Your use of this file is governed by the Virtu Terms of Service <https://www.virtru.com/terms-of-service/>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyFinalizer = void 0;
+exports.wrapPublicKey = wrapPublicKey;
+exports.wrapPrivateKey = wrapPrivateKey;
+exports.wrapSymmetricKey = wrapSymmetricKey;
+exports.wrapKeyPair = wrapKeyPair;
+exports.unwrapPublicKey = unwrapPublicKey;
+exports.unwrapPrivateKey = unwrapPrivateKey;
+exports.unwrapSymmetricKey = unwrapSymmetricKey;
+exports.isSymmetricKey = isSymmetricKey;
+const singlecontainer_1 = require("@opentdf/sdk/singlecontainer");
+// FinalizationRegistry: when an opaque key wrapper is GC'd, release its WASM slot.
+// The held value is any object with a release() method — either a VirtruCryptoKey
+// directly, or a SharedReleasable for key pairs that share a single WASM handle.
+// The registry keeps the held value alive until the callback fires, so release()
+// is always safe to call inside the callback.
+exports.keyFinalizer = new FinalizationRegistry((handle) => {
+    handle.release();
+});
+// SharedReleasable wraps a single VirtruCryptoKey handle that is referenced by
+// two wrappers (e.g. the public and private halves of a generated key pair).
+// release() decrements a ref count and only frees the underlying WASM slot
+// when both wrappers have been garbage collected, preventing a double-free.
+function sharedReleasable(key) {
+    let refs = 2;
+    return {
+        release() {
+            if (--refs === 0)
+                key.release();
+        },
+    };
+}
+// Wrap Helpers
+function wrapPublicKey(key, algorithm) {
+    const result = {
+        _brand: 'PublicKey',
+        algorithm,
+        _internal: key,
+    };
+    if (algorithm.startsWith('rsa:')) {
+        result.modulusBits = parseInt(algorithm.split(':')[1], 10);
+    }
+    else if (algorithm.startsWith('ec:')) {
+        const curveMap = {
+            secp256r1: 'P-256',
+            secp384r1: 'P-384',
+            secp521r1: 'P-521',
+        };
+        result.curve = curveMap[algorithm.split(':')[1]];
+    }
+    exports.keyFinalizer.register(result, key);
+    return result;
+}
+function wrapPrivateKey(key, algorithm) {
+    const result = {
+        _brand: 'PrivateKey',
+        algorithm,
+        _internal: key,
+    };
+    if (algorithm.startsWith('rsa:')) {
+        result.modulusBits = parseInt(algorithm.split(':')[1], 10);
+    }
+    exports.keyFinalizer.register(result, key);
+    return result;
+}
+function wrapSymmetricKey(key, lengthBits) {
+    const result = {
+        _brand: 'SymmetricKey',
+        length: lengthBits,
+        _internal: key,
+    };
+    exports.keyFinalizer.register(result, key);
+    return result;
+}
+function wrapKeyPair(publicKey, privateKey, algorithm) {
+    if (publicKey === privateKey) {
+        // VirtruCrypto returns a single combined handle for generated key pairs.
+        // Use a ref-counted releasable so the WASM slot is freed exactly once
+        // after both wrappers are garbage collected.
+        const shared = sharedReleasable(publicKey);
+        const pub = {
+            _brand: 'PublicKey',
+            algorithm,
+            _internal: publicKey,
+        };
+        const priv = {
+            _brand: 'PrivateKey',
+            algorithm,
+            _internal: privateKey,
+        };
+        if (algorithm.startsWith('rsa:')) {
+            pub.modulusBits = parseInt(algorithm.split(':')[1], 10);
+            priv.modulusBits = pub.modulusBits;
+        }
+        else if (algorithm.startsWith('ec:')) {
+            const curveMap = {
+                secp256r1: 'P-256',
+                secp384r1: 'P-384',
+                secp521r1: 'P-521',
+            };
+            pub.curve = curveMap[algorithm.split(':')[1]];
+        }
+        exports.keyFinalizer.register(pub, shared);
+        exports.keyFinalizer.register(priv, shared);
+        return { publicKey: pub, privateKey: priv };
+    }
+    return {
+        publicKey: wrapPublicKey(publicKey, algorithm),
+        privateKey: wrapPrivateKey(privateKey, algorithm),
+    };
+}
+// ─── Unwrap Helpers ───────────────────────────────────────────────────────────
+function unwrapPublicKey(key) {
+    return key._internal;
+}
+function unwrapPrivateKey(key) {
+    return key._internal;
+}
+function unwrapSymmetricKey(key) {
+    return key._internal;
+}
+function isSymmetricKey(value) {
+    if (!value || typeof value !== 'object' || !('_brand' in value)) {
+        return false;
+    }
+    const candidate = value;
+    return candidate._brand === 'SymmetricKey';
+}

package/lib-commonjs/src/lib/fips-crypto/primitives.js

@@ -0,0 +1,112 @@
+"use strict";
+/*
+ * Copyright (c) Virtru Corporation.  All rights reserved.
+ *
+ * Your use of this file is governed by the Virtu Terms of Service <https://www.virtru.com/terms-of-service/>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeFipsCrypto = exports.getVirtruCrypto = void 0;
+exports.randomBytes = randomBytes;
+exports.digest = digest;
+const sdk_1 = require("@opentdf/sdk");
+const singlecontainer_1 = require("@opentdf/sdk/singlecontainer");
+// ─── VirtruCrypto Init ────────────────────────────────────────────────────────
+let virtruCryptoInstance = null;
+let virtruCryptoInitPromise = null;
+// fips-crypto-js initialization is asynchronous (WASM fetch + runtime init).
+// Keep this bounded so callers fail fast with a clear error if readiness never
+// occurs (missing wasm, blocked fetch, or runtime init failure).
+const VIRTRU_CRYPTO_INIT_TIMEOUT_MS = 10000;
+// fips-crypto-js creates window.VirtruFipsWasmLib early, before the WASM
+// runtime finishes wiring methods. Treat it as ready only once initialized.
+function isVirtruCryptoInitialized(candidate) {
+    if (!candidate || typeof candidate !== 'object') {
+        return false;
+    }
+    const maybe = candidate;
+    return maybe.isInitialized === true && typeof maybe.generateKey === 'function';
+}
+const getVirtruCrypto = async () => {
+    if (typeof window === 'undefined') {
+        throw new sdk_1.ConfigurationError('FIPS crypto requires a browser environment. VirtruCrypto WASM is not supported in Node.js or SSR contexts.');
+    }
+    if (virtruCryptoInstance)
+        return virtruCryptoInstance;
+    if (virtruCryptoInitPromise) {
+        await virtruCryptoInitPromise;
+        return virtruCryptoInstance;
+    }
+    virtruCryptoInitPromise = new Promise((resolve, reject) => {
+        // Fast path when another import already completed initialization.
+        if (isVirtruCryptoInitialized(window.VirtruFipsWasmLib)) {
+            resolve();
+            return;
+        }
+        const onReady = () => {
+            clearTimeout(timeout);
+            resolve();
+        };
+        const timeout = setTimeout(() => {
+            window.removeEventListener('wasmReady', onReady);
+            reject(new Error('Timeout waiting for VirtruCrypto WASM initialization.'));
+        }, VIRTRU_CRYPTO_INIT_TIMEOUT_MS);
+        // fips-crypto-js dispatches wasmReady on window (not document).
+        window.addEventListener('wasmReady', onReady, { once: true });
+        // Handle race: initialization may complete between the first check and the
+        // event listener registration above.
+        if (isVirtruCryptoInitialized(window.VirtruFipsWasmLib)) {
+            window.removeEventListener('wasmReady', onReady);
+            clearTimeout(timeout);
+            resolve();
+        }
+    });
+    await virtruCryptoInitPromise;
+    virtruCryptoInstance = window.VirtruFipsWasmLib;
+    if (!isVirtruCryptoInitialized(virtruCryptoInstance)) {
+        throw new Error('VirtruCrypto failed to initialize properly.');
+    }
+    return virtruCryptoInstance;
+};
+exports.getVirtruCrypto = getVirtruCrypto;
+/**
+ * Eagerly initialize FIPS WASM (used by DSP when `useFips: true`).
+ * Loaded dynamically so non-FIPS consumers do not require the optional peer.
+ */
+const initializeFipsCrypto = () => {
+    // Keep specifier dynamic so Vite/Rollup does not eagerly resolve the optional
+    // peer in non-FIPS builds; load occurs only when FIPS mode is enabled.
+    const modulePath = '@virtru-private/fips-crypto-js';
+    void Promise.resolve(`${modulePath}`).then(s => require(s)).catch((err) => {
+        console.error('Virtru FIPS crypto initialization failed: @virtru-private/fips-crypto-js is not installed.', err);
+    });
+    void (0, exports.getVirtruCrypto)().catch((err) => {
+        // Avoid unhandled rejections; same error appears on first crypto call too.
+        console.error('Virtru FIPS crypto initialization failed:', err);
+    });
+};
+exports.initializeFipsCrypto = initializeFipsCrypto;
+// ─── Randomness / Digest ──────────────────────────────────────────────────────
+/**
+ * Generate random bytes via WebCrypto CSPRNG.
+ * fips-crypto-js only exposes fixed-length IV generation.
+ *
+ * Note: this does not route through the fips-crypto-js WASM boundary.
+ * It should not be used when a strict "all cryptographic operations must be
+ * performed inside the FIPS module" requirement applies.
+ */
+async function randomBytes(byteLength) {
+    const buf = new Uint8Array(byteLength);
+    globalThis.crypto.getRandomValues(buf);
+    return buf;
+}
+/**
+ * Compute a hash digest. Only SHA-256 is supported by fips-crypto-js.
+ */
+async function digest(algorithm, data) {
+    if (algorithm !== 'SHA-256') {
+        throw new sdk_1.ConfigurationError(`Hash algorithm '${algorithm}' not supported in FIPS mode. Only SHA-256 is supported.`);
+    }
+    const crypto = await (0, exports.getVirtruCrypto)();
+    const result = await crypto.digest({ name: 'SHA-256' }, data);
+    return new Uint8Array(result);
+}

package/lib-commonjs/src/lib/fips-crypto/symmetric.js

@@ -0,0 +1,162 @@
+"use strict";
+/*
+ * Copyright (c) Virtru Corporation.  All rights reserved.
+ *
+ * Your use of this file is governed by the Virtu Terms of Service <https://www.virtru.com/terms-of-service/>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateKey = generateKey;
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+exports.hmac = hmac;
+exports.verifyHmac = verifyHmac;
+exports.importSymmetricKey = importSymmetricKey;
+exports.splitSymmetricKey = splitSymmetricKey;
+exports.mergeSymmetricKeys = mergeSymmetricKeys;
+const singlecontainer_1 = require("@opentdf/sdk/singlecontainer");
+const sdk_1 = require("@opentdf/sdk");
+const primitives_1 = require("./primitives");
+const keys_1 = require("./keys");
+const AES_CBC_URN = 'http://www.w3.org/2001/04/xmlenc#aes256-cbc';
+const SYM_KEY_METHODS = ['encrypt', 'decrypt', 'sign', 'verify'];
+/**
+ * Generate a random AES-256 symmetric key.
+ * The VirtruCryptoKey handle is kept alive inside the opaque SymmetricKey —
+ * key material never leaves the FIPS WASM keystore.
+ */
+async function generateKey(length) {
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const bitLen = (length || 32) * 8;
+    // extractable=true and internal=true: keystore-based AES key that can be exported
+    // for RSA key-wrapping (encryptWithPublicKey calls exportKey on the DEK).
+    const vKey = await crypto.generateKey({ name: 'AES-GCM', length: bitLen }, true, SYM_KEY_METHODS, true);
+    return (0, keys_1.wrapSymmetricKey)(vKey, bitLen);
+}
+/**
+ * Encrypt a payload with a symmetric AES key.
+ * When payload is a SymmetricKey the key bytes are exported internally to
+ * perform key-wrapping — they are never surfaced to the caller.
+ */
+async function encrypt(payload, key, iv, algorithm) {
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const algName = algorithm === AES_CBC_URN ? 'AES-CBC' : 'AES-GCM';
+    let payloadBytes;
+    if ((0, keys_1.isSymmetricKey)(payload)) {
+        // Key-wrapping path: export symmetric key bytes from keystore.
+        // Only works if the key was created with extractable:true (e.g. via importSymmetricKey).
+        payloadBytes = await crypto.exportKey('raw', (0, keys_1.unwrapSymmetricKey)(payload));
+    }
+    else {
+        payloadBytes = new Uint8Array(payload.asArrayBuffer());
+    }
+    const vKey = (0, keys_1.unwrapSymmetricKey)(key);
+    const ivBytes = new Uint8Array(iv.asArrayBuffer());
+    const cipherBytes = await crypto.encrypt({ name: algName, length: 256, iv: ivBytes }, vKey, payloadBytes);
+    if (algName === 'AES-GCM') {
+        return {
+            payload: singlecontainer_1.Binary.fromArrayBuffer(cipherBytes.slice(0, -16).buffer),
+            authTag: singlecontainer_1.Binary.fromArrayBuffer(cipherBytes.slice(-16).buffer),
+        };
+    }
+    return { payload: singlecontainer_1.Binary.fromArrayBuffer(cipherBytes.buffer) };
+}
+/**
+ * Decrypt a payload with a symmetric AES key.
+ */
+async function decrypt(payload, key, iv, algorithm, authTag) {
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const algName = algorithm === AES_CBC_URN ? 'AES-CBC' : 'AES-GCM';
+    let payloadBytes = new Uint8Array(payload.asArrayBuffer());
+    const ivBytes = new Uint8Array(iv.asArrayBuffer());
+    if (algName === 'AES-GCM') {
+        if (!authTag) {
+            throw new Error('Missing authTag for AES-GCM decryption');
+        }
+        const tagBytes = new Uint8Array(authTag.asArrayBuffer());
+        const combined = new Uint8Array(payloadBytes.length + tagBytes.length);
+        combined.set(payloadBytes, 0);
+        combined.set(tagBytes, payloadBytes.length);
+        payloadBytes = combined;
+    }
+    const vKey = (0, keys_1.unwrapSymmetricKey)(key);
+    const plainBytes = await crypto.decrypt({ name: algName, length: 256, iv: ivBytes }, vKey, payloadBytes);
+    return { payload: singlecontainer_1.Binary.fromArrayBuffer(plainBytes.buffer) };
+}
+// ─── HMAC ─────────────────────────────────────────────────────────────────────
+const HMAC_PARAMS = { name: 'HMAC', hash: 'SHA-256' };
+/**
+ * Compute HMAC-SHA256.
+ * The SymmetricKey must have been created with extractable:true (e.g. via
+ * importSymmetricKey) so its bytes can be re-imported as an HMAC key.
+ */
+async function hmac(data, key) {
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const vKey = (0, keys_1.unwrapSymmetricKey)(key);
+    // The key was imported with 'sign' usage (see importSymmetricKey).
+    // VirtruCrypto sign() checks usage.includes('sign') then calls the WASM
+    // hmac() with the slot number — the key type string is irrelevant for HMAC.
+    // Do NOT call release() here: the key handle must remain valid for future calls.
+    const sig = await crypto.sign(HMAC_PARAMS, vKey, data);
+    return new Uint8Array(sig);
+}
+/**
+ * Verify HMAC-SHA256 using constant-time comparison.
+ */
+async function verifyHmac(data, signature, key) {
+    const expected = await hmac(data, key);
+    if (signature.length !== expected.length)
+        return false;
+    let mismatch = 0;
+    for (let i = 0; i < signature.length; i++) {
+        mismatch |= signature[i] ^ expected[i];
+    }
+    return mismatch === 0;
+}
+// ─── Symmetric Key Import / Split / Merge ─────────────────────────────────────
+/**
+ * Import raw key bytes as an opaque SymmetricKey.
+ * The resulting key is extractable so it can be used for HMAC and key-wrapping.
+ */
+async function importSymmetricKey(keyBytes) {
+    const crypto = await (0, primitives_1.getVirtruCrypto)();
+    const bitLen = keyBytes.length * 8;
+    // Include 'sign'/'verify' so this key can also be used for HMAC-SHA256.
+    // VirtruCrypto's sign() checks key.usage.includes('sign'); the underlying
+    // WASM hmac() takes the slot number and works with any 256-bit key material.
+    const vKey = await crypto.importKey('raw', keyBytes, { name: 'AES-GCM' }, true, SYM_KEY_METHODS);
+    return (0, keys_1.wrapSymmetricKey)(vKey, bitLen);
+}
+/**
+ * Split a symmetric key into N shares using XOR secret sharing.
+ *
+ * For numShares === 1 (single-KAS), the key is returned as-is — no key
+ * material is exported and no splitting occurs. This is the common DSP case.
+ *
+ * For numShares > 1 (multi-KAS), XOR secret sharing requires exporting the
+ * raw key bytes. This is not yet implemented in FIPS mode.
+ */
+async function splitSymmetricKey(key, numShares) {
+    if (numShares === 1) {
+        return [key];
+    }
+    throw new sdk_1.ConfigurationError(`splitSymmetricKey with ${numShares} shares is not yet supported in FIPS mode. ` +
+        'Multi-KAS key splitting requires raw key export which violates FIPS key boundary constraints.');
+}
+/**
+ * Merge symmetric key shares back into the original key using XOR.
+ *
+ * For a single share (single-KAS), the share is returned as-is — no key
+ * material is exported and no XOR occurs. This is the common DSP case.
+ *
+ * For multiple shares (multi-KAS), XOR merging requires exporting raw key bytes.
+ * This is not yet implemented in FIPS mode.
+ */
+async function mergeSymmetricKeys(shares) {
+    if (shares.length === 0)
+        throw new sdk_1.ConfigurationError('No shares provided to mergeSymmetricKeys');
+    if (shares.length === 1) {
+        return shares[0];
+    }
+    throw new sdk_1.ConfigurationError(`mergeSymmetricKeys with ${shares.length} shares is not yet supported in FIPS mode. ` +
+        'Multi-KAS key merging requires raw key export which violates FIPS key boundary constraints.');
+}