@virtru/dsp-sdk 0.4.1 → 0.5.0

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

@@ -0,0 +1,105 @@
+/*
+ * 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/>.
+ */
+import { ConfigurationError } from '@opentdf/sdk';
+import {} from '@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';
+}
+export const getVirtruCrypto = async () => {
+    if (typeof window === 'undefined') {
+        throw new 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;
+};
+/**
+ * Eagerly initialize FIPS WASM (used by DSP when `useFips: true`).
+ * Loaded dynamically so non-FIPS consumers do not require the optional peer.
+ */
+export 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 import(/* @vite-ignore */ modulePath).catch((err) => {
+        console.error('Virtru FIPS crypto initialization failed: @virtru-private/fips-crypto-js is not installed.', err);
+    });
+    void getVirtruCrypto().catch((err) => {
+        // Avoid unhandled rejections; same error appears on first crypto call too.
+        console.error('Virtru FIPS crypto initialization failed:', err);
+    });
+};
+// ─── 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.
+ */
+export 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.
+ */
+export async function digest(algorithm, data) {
+    if (algorithm !== 'SHA-256') {
+        throw new ConfigurationError(`Hash algorithm '${algorithm}' not supported in FIPS mode. Only SHA-256 is supported.`);
+    }
+    const crypto = await getVirtruCrypto();
+    const result = await crypto.digest({ name: 'SHA-256' }, data);
+    return new Uint8Array(result);
+}

package/dist/src/lib/fips-crypto/symmetric.d.ts

@@ -0,0 +1,61 @@
+import { Binary, type SymmetricKey } from '@opentdf/sdk/singlecontainer';
+type AlgorithmUrn = string;
+type EncryptResult = {
+    payload: Binary;
+    authTag?: Binary;
+};
+type DecryptResult = {
+    payload: Binary;
+};
+/**
+ * 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.
+ */
+export declare function generateKey(length?: number): Promise<SymmetricKey>;
+/**
+ * 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.
+ */
+export declare function encrypt(payload: Binary | SymmetricKey, key: SymmetricKey, iv: Binary, algorithm?: AlgorithmUrn): Promise<EncryptResult>;
+/**
+ * Decrypt a payload with a symmetric AES key.
+ */
+export declare function decrypt(payload: Binary, key: SymmetricKey, iv: Binary, algorithm?: AlgorithmUrn, authTag?: Binary): Promise<DecryptResult>;
+/**
+ * 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.
+ */
+export declare function hmac(data: Uint8Array, key: SymmetricKey): Promise<Uint8Array>;
+/**
+ * Verify HMAC-SHA256 using constant-time comparison.
+ */
+export declare function verifyHmac(data: Uint8Array, signature: Uint8Array, key: SymmetricKey): Promise<boolean>;
+/**
+ * Import raw key bytes as an opaque SymmetricKey.
+ * The resulting key is extractable so it can be used for HMAC and key-wrapping.
+ */
+export declare function importSymmetricKey(keyBytes: Uint8Array): Promise<SymmetricKey>;
+/**
+ * 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.
+ */
+export declare function splitSymmetricKey(key: SymmetricKey, numShares: number): Promise<SymmetricKey[]>;
+/**
+ * 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.
+ */
+export declare function mergeSymmetricKeys(shares: SymmetricKey[]): Promise<SymmetricKey>;
+export {};

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

@@ -0,0 +1,152 @@
+/*
+ * 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/>.
+ */
+import { Binary } from '@opentdf/sdk/singlecontainer';
+import { ConfigurationError } from '@opentdf/sdk';
+import { getVirtruCrypto } from './primitives';
+import { isSymmetricKey, wrapSymmetricKey, unwrapSymmetricKey } from './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.
+ */
+export async function generateKey(length) {
+    const crypto = await 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 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.
+ */
+export async function encrypt(payload, key, iv, algorithm) {
+    const crypto = await getVirtruCrypto();
+    const algName = algorithm === AES_CBC_URN ? 'AES-CBC' : 'AES-GCM';
+    let payloadBytes;
+    if (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', unwrapSymmetricKey(payload));
+    }
+    else {
+        payloadBytes = new Uint8Array(payload.asArrayBuffer());
+    }
+    const vKey = 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: Binary.fromArrayBuffer(cipherBytes.slice(0, -16).buffer),
+            authTag: Binary.fromArrayBuffer(cipherBytes.slice(-16).buffer),
+        };
+    }
+    return { payload: Binary.fromArrayBuffer(cipherBytes.buffer) };
+}
+/**
+ * Decrypt a payload with a symmetric AES key.
+ */
+export async function decrypt(payload, key, iv, algorithm, authTag) {
+    const crypto = await 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 = unwrapSymmetricKey(key);
+    const plainBytes = await crypto.decrypt({ name: algName, length: 256, iv: ivBytes }, vKey, payloadBytes);
+    return { payload: 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.
+ */
+export async function hmac(data, key) {
+    const crypto = await getVirtruCrypto();
+    const vKey = 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.
+ */
+export 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.
+ */
+export async function importSymmetricKey(keyBytes) {
+    const crypto = await 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 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.
+ */
+export async function splitSymmetricKey(key, numShares) {
+    if (numShares === 1) {
+        return [key];
+    }
+    throw new 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.
+ */
+export async function mergeSymmetricKeys(shares) {
+    if (shares.length === 0)
+        throw new ConfigurationError('No shares provided to mergeSymmetricKeys');
+    if (shares.length === 1) {
+        return shares[0];
+    }
+    throw new 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.');
+}

package/dist/src/lib/fips-crypto-service.d.ts

@@ -0,0 +1,5 @@
+import { type CryptoService } from '@opentdf/sdk/singlecontainer';
+export { initializeFipsCrypto } from './fips-crypto/primitives';
+export { wrapPublicKey, wrapPrivateKey, wrapSymmetricKey, wrapKeyPair, unwrapPublicKey, unwrapPrivateKey, unwrapSymmetricKey, } from './fips-crypto/keys';
+export { importPrivateKey, exportPrivateKeyPem } from './fips-crypto/key-format';
+export declare const FipsCryptoService: CryptoService;

package/dist/src/lib/fips-crypto-service.js

@@ -0,0 +1,44 @@
+/*
+ * 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/>.
+ */
+import {} from '@opentdf/sdk/singlecontainer';
+export { initializeFipsCrypto } from './fips-crypto/primitives';
+export { wrapPublicKey, wrapPrivateKey, wrapSymmetricKey, wrapKeyPair, unwrapPublicKey, unwrapPrivateKey, unwrapSymmetricKey, } from './fips-crypto/keys';
+import { randomBytes, digest } from './fips-crypto/primitives';
+import { generateKey, encrypt, decrypt, hmac, verifyHmac, importSymmetricKey, splitSymmetricKey, mergeSymmetricKeys } from './fips-crypto/symmetric';
+import { generateKeyPair, generateSigningKeyPair, encryptWithPublicKey, decryptWithPrivateKey, sign, verify, generateECKeyPair, deriveKeyFromECDH } from './fips-crypto/asymmetric';
+import { importPublicKey, importPrivateKey, exportPublicKeyPem, exportPrivateKeyPem, exportPublicKeyJwk, parsePublicKeyPem, extractPublicKeyPem, jwkToPublicKeyPem } from './fips-crypto/key-format';
+export { importPrivateKey, exportPrivateKeyPem } from './fips-crypto/key-format';
+// ─── FipsCryptoService ────────────────────────────────────────────────────────
+export const FipsCryptoService = {
+    name: 'FipsCryptoService',
+    method: 'http://www.w3.org/2001/04/xmlenc#aes256-cbc',
+    decrypt,
+    decryptWithPrivateKey,
+    encrypt,
+    encryptWithPublicKey,
+    generateKey,
+    generateKeyPair,
+    generateSigningKeyPair,
+    randomBytes,
+    sign,
+    verify,
+    hmac,
+    verifyHmac,
+    digest,
+    generateECKeyPair,
+    deriveKeyFromECDH,
+    importPublicKey,
+    importPrivateKey,
+    exportPublicKeyPem,
+    exportPrivateKeyPem,
+    exportPublicKeyJwk,
+    parsePublicKeyPem,
+    extractPublicKeyPem,
+    jwkToPublicKeyPem,
+    importSymmetricKey,
+    splitSymmetricKey,
+    mergeSymmetricKeys,
+};

package/dist/src/lib/utils.d.ts

@@ -1,5 +1,6 @@
 import type { AuthProvider } from '@opentdf/sdk';
 import { AuthProviders, OpenTDF } from '@opentdf/sdk';
+import { type CryptoService } from '@opentdf/sdk/singlecontainer';
 import type { Certificate } from '../gen/virtru/policy/objects_pb';
 import type { Interceptor as Inter } from '@connectrpc/connect';
 export type Interceptor = Inter;
@@ -27,7 +28,7 @@ export type GetUserEntitlementsResponse = {
  * @param authProvider - An instance of `AuthProvider` used to generate authentication credentials.
  * @returns An `Interceptor` function that modifies requests to include authentication headers.
  */
-export declare function createAuthInterceptor(authProvider: AuthProvider): Interceptor;
+export declare function createAuthInterceptor(authProvider: AuthProvider, _cryptoService?: CryptoService): Interceptor;
 /** Creates a new instance of an OIDC Auth Provider consumed by the TDF Clients */
 export declare function createAuthProvider(options: {
     oidc: {
@@ -36,6 +37,7 @@ export declare function createAuthProvider(options: {
         userInfoEndpoint: string;
     };
     refreshToken: string;
+    cryptoService?: CryptoService;
 }): Promise<AuthProviders.OIDCRefreshTokenProvider>;
 export declare function createOpenTDFClient(options: {
     oidc: {
@@ -46,6 +48,7 @@ export declare function createOpenTDFClient(options: {
     platformEndpoint: string;
     refreshToken: string;
     obligations: string[];
+    cryptoService?: CryptoService;
 }): Promise<OpenTDF>;
 export declare const getObligations: (ciphertext: ArrayBuffer, options: {
     oidc: {
@@ -56,6 +59,7 @@ export declare const getObligations: (ciphertext: ArrayBuffer, options: {
     platformEndpoint: string;
     refreshToken: string;
     obligations: string[];
+    cryptoService?: CryptoService;
 }) => Promise<string[]>;
 export declare function getUserEntitlements(options: {
     oidc: {
@@ -65,6 +69,7 @@ export declare function getUserEntitlements(options: {
     };
     platformEndpoint: string;
     refreshToken: string;
+    cryptoService?: CryptoService;
 }): Promise<GetUserEntitlementsResponse>;
 export declare const flattenObligations: (obligations: SupportedObligations) => string[];
 /**
@@ -110,6 +115,7 @@ export declare function getTrustedCertificates(options: {
     };
     platformEndpoint: string;
     refreshToken: string;
+    cryptoService?: CryptoService;
 }): Promise<Certificate[]>;
 export type JWSValidationResult = {
     valid: boolean;
@@ -148,4 +154,4 @@ export type JWSValidationResult = {
  * }
  * ```
  */
-export declare function validateJWSCertificateChain(x5c: string[], trustedRootCertificates: Certificate[]): Promise<JWSValidationResult>;
+export declare function validateJWSCertificateChain(x5c: string[], trustedRootCertificates: Certificate[], _cryptoService?: CryptoService): Promise<JWSValidationResult>;

package/dist/src/lib/utils.js

@@ -4,6 +4,7 @@
  * Your use of this file is governed by the Virtu Terms of Service <https://www.virtru.com/terms-of-service/>.
  */
 import { AuthProviders, OpenTDF, PermissionDeniedError, } from '@opentdf/sdk';
+import { WebCryptoService } from '@opentdf/sdk/singlecontainer';
 import { PlatformClient } from '@opentdf/sdk/platform';
 import { ActiveStateEnum } from '@opentdf/sdk/platform/common/common_pb.js';
 import * as asn1js from 'asn1js';
@@ -21,7 +22,7 @@ import { DSPClient } from './client';
  * @param authProvider - An instance of `AuthProvider` used to generate authentication credentials.
  * @returns An `Interceptor` function that modifies requests to include authentication headers.
  */
-export function createAuthInterceptor(authProvider) {
+export function createAuthInterceptor(authProvider, _cryptoService) {
     return (next) => async (req) => {
         const url = new URL(req.url);
         const pathOnly = url.pathname;
@@ -67,6 +68,7 @@ export async function createOpenTDFClient(options) {
             noVerify: true,
         },
         disableDPoP: true,
+        cryptoService: options.cryptoService,
     });
 }
 export const getObligations = async (ciphertext, options) => {
@@ -92,6 +94,7 @@ export async function getUserEntitlements(options) {
     const authProvider = await createAuthProvider({
         oidc: options.oidc,
         refreshToken: options.refreshToken,
+        cryptoService: options.cryptoService,
     });
     const accessToken = await authProvider.oidcAuth.get();
     const userEntitlementsResponse = await fetch(`${options.platformEndpoint}/shared/entitlements`, {
@@ -174,17 +177,13 @@ async function getCertificatesForNamespace(dspClient, namespaceId) {
  * ```
  */
 export async function getTrustedCertificates(options) {
-    function generateSigningKeyPair() {
-        return crypto.subtle.generateKey({
-            name: 'ECDSA',
-            namedCurve: 'P-256',
-        }, true, ['sign', 'verify']);
-    }
+    const cs = options.cryptoService ?? WebCryptoService;
     const authProvider = await createAuthProvider({
         oidc: options.oidc,
         refreshToken: options.refreshToken,
+        cryptoService: options.cryptoService,
     });
-    await authProvider.updateClientPublicKey(await generateSigningKeyPair());
+    await authProvider.updateClientPublicKey(await cs.generateSigningKeyPair());
     // Create both clients
     const platform = new PlatformClient({
         authProvider,
@@ -300,7 +299,7 @@ function pemToArrayBuffer(pem) {
  * }
  * ```
  */
-export async function validateJWSCertificateChain(x5c, trustedRootCertificates) {
+export async function validateJWSCertificateChain(x5c, trustedRootCertificates, _cryptoService) {
     const warnings = [];
     try {
         // Validate inputs

package/dist/tests/fips-crypto.unit.test.d.ts

@@ -0,0 +1 @@
+export {};