@virtru/dsp-sdk 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Change Log - @virtru/dsp-sdk
 
-This log was last generated on Tue, 03 Mar 2026 16:24:41 GMT and should not be manually modified.
+This log was last generated on Thu, 12 Mar 2026 20:33:42 GMT and should not be manually modified.
+
+## 0.6.0
+Thu, 12 Mar 2026 20:33:42 GMT
+
+### Minor changes
+
+- expose fipsCryptoService implementation, useFips option
+
+## 0.5.0
+Thu, 12 Mar 2026 16:58:37 GMT
+
+### Minor changes
+
+- add FipsCryptoService implementation
 
 ## 0.4.1
 Tue, 03 Mar 2026 16:24:41 GMT

package/README.md

@@ -79,16 +79,96 @@ console.log(decrypted); // "hello world"
 
 ```
 
+### FIPS Mode
+
+The SDK supports FIPS 140-2 compliant cryptography using a validated BoringSSL WASM module. To enable FIPS mode:
+
+```typescript
+import { AuthProviders, DSP } from '@virtru/dsp-sdk';
+import { FipsCryptoService } from '@virtru/dsp-sdk/fips';
+
+// Create auth provider with FIPS crypto service
+const authProvider = await AuthProviders.clientSecretAuthProvider(
+  {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    oidcOrigin: 'https://oidc-endpoint',
+    exchange: 'client',
+  },
+  FipsCryptoService  // Use FIPS-validated crypto
+);
+
+// Initialize DSP with FIPS mode enabled
+const dsp = new DSP({
+  authProvider,
+  platformUrl: 'https://dsp-platform-url',
+  useFips: true,  // Enables FIPS mode
+});
+
+// Check if FIPS is enabled
+console.log('FIPS enabled:', dsp.fipsEnabled);  // true
+```
+
+When FIPS mode is enabled, TDF3/ZTDF cryptographic operations (encryption, decryption, signing, key generation) use the FIPS-validated BoringSSL WASM module instead of Web Crypto API (`crypto.subtle`). NanoTDF operations are not covered by FIPS mode and continue to use `crypto.subtle`.
+
+**Note:** FIPS mode only supports RSA keys; EC (Elliptic Curve) operations are not available in FIPS mode.
+
 Refer to the API documentation for a complete list of available methods and configuration options.
 
 ## Testing
 
-This section is intended for repository maintainers and contributors. To verify the integrity of the SDK and ensure all features work as expected, run the test suite using the following command:
+This section is intended for repository maintainers and contributors.
+
+The test setup is split into:
+- **Unit tests** (`test:unit`): run in Vitest `jsdom` mode and do **not** require Playwright.
+- **Integration/browser tests** (`test:integration`): run in Chromium via Playwright.
+
+To run the unit suite:
+
+```bash
+pnpm run build-fips-crypto
+pnpm run copy-wasm
+pnpm test:unit
+```
+
+To run the browser/integration suite:
+
+```bash
+pnpm test:integration
+```
+
+To run both:
 
 ```bash
 pnpm test
 ```
 
+### Integration Tests
+
+Integration tests verify end-to-end encrypt/decrypt operations against a live DSP server, including FIPS mode compliance testing.
+
+**Required environment variables:**
+```bash
+export DSP_PLATFORM_URL="http://localhost:8080"      # DSP platform URL
+export CLIENT_ID="your-client-id"                    # OAuth client ID
+export CLIENT_SECRET="your-client-secret"            # OAuth client secret
+export OIDC_ENDPOINT="http://localhost:8888/auth/realms/opentdf"  # OIDC endpoint
+```
+
+**Run integration tests:**
+```bash
+pnpm run build-fips-crypto
+pnpm run copy-wasm
+pnpm test:integration
+```
+
+**Run all tests (unit + integration):**
+```bash
+pnpm test
+```
+
+Integration tests include FIPS compliance verification to ensure `crypto.subtle` is not used when FIPS mode is enabled (validating that only FIPS-certified BoringSSL WASM is used for cryptographic operations).
+
 
 ### Linting
 
@@ -165,5 +245,3 @@ You only need to regenerate the code when:
 - Proto dependencies are updated
 
 After regenerating, commit the updated files in `src/gen/` to version control.
-
-

package/dist/src/fips.d.ts

@@ -0,0 +1,7 @@
+/**
+ * FIPS entrypoint — only import this if @virtru-private/fips-crypto-js is installed.
+ *
+ * @example
+ * import { FipsCryptoService, initializeFipsCrypto } from '@virtru/dsp-sdk/fips';
+ */
+export { FipsCryptoService, initializeFipsCrypto, } from './lib/fips-crypto-service';

package/dist/src/fips.js

@@ -0,0 +1,12 @@
+/*
+ * 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/>.
+ */
+/**
+ * FIPS entrypoint — only import this if @virtru-private/fips-crypto-js is installed.
+ *
+ * @example
+ * import { FipsCryptoService, initializeFipsCrypto } from '@virtru/dsp-sdk/fips';
+ */
+export { FipsCryptoService, initializeFipsCrypto, } from './lib/fips-crypto-service';

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

@@ -1,4 +1,4 @@
-import { OpenTDF, type OpenTDFOptions } from '@opentdf/sdk';
+import { OpenTDF, type OpenTDFOptions, type CryptoService } from '@opentdf/sdk';
 import { type PlatformServices } from '@opentdf/sdk/platform';
 import { type DSPClientServicesV1, type DSPClientServicesV2 } from './client';
 import type { Interceptor } from '@connectrpc/connect';
@@ -7,8 +7,24 @@ export type DSPServicesV2 = DSPClientServicesV2;
 export interface DSPOptions extends OpenTDFOptions {
     platformUrl: string;
     interceptors?: Interceptor[];
+    /**
+     * Enable FIPS 140-2 compliant cryptography for TDF3/ZTDF operations.
+     * When true, uses @virtru-private/fips-mode for encryption/decryption.
+     * Requires @virtru-private/fips-crypto-js WASM module to be loaded.
+     *
+     * Note: NanoTDF operations are NOT affected by this flag and will
+     * continue to use native crypto.subtle (not FIPS-compliant).
+     */
+    useFips?: boolean;
+    /**
+     * Optional: Provide a custom CryptoService implementation for TDF3/ZTDF.
+     * If provided, this takes precedence over useFips flag.
+     * NanoTDF operations are not affected.
+     */
+    cryptoService?: CryptoService;
 }
 export declare class DSP extends OpenTDF {
+    readonly fipsEnabled: boolean;
     readonly services: {
         v1: DSPServicesV1;
         v2: DSPServicesV2;

package/dist/src/lib/dsp.js

@@ -3,21 +3,44 @@
  *
  * Your use of this file is governed by the Virtu Terms of Service <https://www.virtru.com/terms-of-service/>.
  */
-import { OpenTDF } from '@opentdf/sdk';
+import { OpenTDF, } from '@opentdf/sdk';
 import { PlatformClient } from '@opentdf/sdk/platform';
 import { DSPClient, } from './client';
+import { FipsCryptoService, initializeFipsCrypto } from './fips-crypto-service';
 export class DSP extends OpenTDF {
     constructor(options) {
-        super(options);
+        // Validate required options first
+        if (!options.platformUrl) {
+            throw new Error('platformUrl is required for DSP client');
+        }
+        // Configure FIPS crypto service for TDF3/ZTDF
+        const configuredOptions = { ...options };
+        if (options.useFips && options.cryptoService) {
+            console.warn('[DSP] Both useFips and cryptoService are set. useFips will be ignored — the provided cryptoService will be used.');
+        }
+        if (options.cryptoService) {
+            configuredOptions.cryptoService = options.cryptoService;
+        }
+        else if (options.useFips) {
+            initializeFipsCrypto();
+            configuredOptions.cryptoService = FipsCryptoService;
+        }
+        // Pass configured options to OpenTDF
+        super(configuredOptions);
+        Object.defineProperty(this, "fipsEnabled", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "services", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        if (!options.platformUrl) {
-            throw new Error('platformUrl is required for DSP client');
-        }
+        this.fipsEnabled = configuredOptions.cryptoService === FipsCryptoService;
+        // Setup DSP and Platform clients
         const dspClient = new DSPClient({
             platformUrl: options.platformUrl,
             interceptors: options.interceptors,

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

@@ -0,0 +1,35 @@
+import { Binary } from '@opentdf/sdk/singlecontainer';
+import { type AsymmetricSigningAlgorithm, type ECCurve, type HkdfParams, type KeyPair, type PrivateKey, type PublicKey, type SymmetricKey } from '@opentdf/sdk/singlecontainer';
+/**
+ * Generate an RSA key pair for encryption/decryption (RSA-OAEP).
+ *
+ * VirtruCrypto generates a single combined keypair handle. Both the PublicKey
+ * and PrivateKey opaque wrappers reference the same VirtruCryptoKey — the
+ * handle already carries all necessary usages. No export/re-import needed.
+ */
+export declare function generateKeyPair(_size?: number): Promise<KeyPair>;
+/**
+ * Generate an RSA key pair for signing/verification (RSASSA-PKCS1-v1_5).
+ */
+export declare function generateSigningKeyPair(): Promise<KeyPair>;
+/**
+ * Encrypt with RSA-OAEP public key.
+ * Accepts Binary payload or a SymmetricKey for key-wrapping.
+ */
+export declare function encryptWithPublicKey(payload: Binary | SymmetricKey, publicKey: PublicKey): Promise<Binary>;
+/**
+ * Decrypt with RSA-OAEP private key.
+ */
+export declare function decryptWithPrivateKey(encryptedPayload: Binary, privateKey: PrivateKey): Promise<Binary>;
+/**
+ * Sign data with an RSA private key (RS256 only).
+ * VirtruCrypto requires pre-hashed data, so the data is SHA-256 hashed first.
+ */
+export declare function sign(data: Uint8Array, privateKey: PrivateKey, algorithm: AsymmetricSigningAlgorithm): Promise<Uint8Array>;
+/**
+ * Verify an RS256 signature.
+ * VirtruCrypto requires pre-hashed data.
+ */
+export declare function verify(data: Uint8Array, signature: Uint8Array, publicKey: PublicKey, algorithm: AsymmetricSigningAlgorithm): Promise<boolean>;
+export declare function generateECKeyPair(_curve?: ECCurve): Promise<KeyPair>;
+export declare function deriveKeyFromECDH(_privateKey: PrivateKey, _publicKey: PublicKey, _hkdfParams: HkdfParams): Promise<SymmetricKey>;

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

@@ -0,0 +1,116 @@
+/*
+ * 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 {} from '@opentdf/sdk/singlecontainer';
+import { ConfigurationError } from '@opentdf/sdk';
+import { getVirtruCrypto } from './primitives';
+import { isSymmetricKey, wrapKeyPair, unwrapPublicKey, unwrapPrivateKey, unwrapSymmetricKey } from './keys';
+// ─── Key Generation ───────────────────────────────────────────────────────────
+const ENC_DEC_METHODS = ['encrypt', 'decrypt'];
+const SIGN_VERIFY_METHODS = ['sign', 'verify'];
+const RSA_OAEP_PARAMS = {
+    name: 'RSA-OAEP',
+    modulusLength: 2048,
+    publicExponent: [1, 0, 1],
+    hash: 'SHA-256',
+};
+const RS256_PARAMS = {
+    name: 'RSASSA-PKCS1-v1_5',
+    modulusLength: 2048,
+    publicExponent: [1, 0, 1],
+    hash: 'SHA-256',
+};
+/**
+ * Generate an RSA key pair for encryption/decryption (RSA-OAEP).
+ *
+ * VirtruCrypto generates a single combined keypair handle. Both the PublicKey
+ * and PrivateKey opaque wrappers reference the same VirtruCryptoKey — the
+ * handle already carries all necessary usages. No export/re-import needed.
+ */
+export async function generateKeyPair(_size) {
+    const crypto = await getVirtruCrypto();
+    const combined = await crypto.generateKey(RSA_OAEP_PARAMS, true, ENC_DEC_METHODS);
+    return wrapKeyPair(combined, combined, 'rsa:2048');
+}
+/**
+ * Generate an RSA key pair for signing/verification (RSASSA-PKCS1-v1_5).
+ */
+export async function generateSigningKeyPair() {
+    const crypto = await getVirtruCrypto();
+    const combined = await crypto.generateKey(RS256_PARAMS, true, SIGN_VERIFY_METHODS);
+    return wrapKeyPair(combined, combined, 'rsa:2048');
+}
+// ─── RSA Encrypt / Decrypt ────────────────────────────────────────────────────
+/**
+ * Encrypt with RSA-OAEP public key.
+ * Accepts Binary payload or a SymmetricKey for key-wrapping.
+ */
+export async function encryptWithPublicKey(payload, publicKey) {
+    const crypto = await getVirtruCrypto();
+    let payloadBytes;
+    if (isSymmetricKey(payload)) {
+        payloadBytes = await crypto.exportKey('raw', unwrapSymmetricKey(payload));
+    }
+    else {
+        payloadBytes = new Uint8Array(payload.asArrayBuffer());
+    }
+    const vKey = unwrapPublicKey(publicKey);
+    const encrypted = await crypto.encrypt(RSA_OAEP_PARAMS, vKey, payloadBytes);
+    return Binary.fromArrayBuffer(encrypted.buffer);
+}
+/**
+ * Decrypt with RSA-OAEP private key.
+ */
+export async function decryptWithPrivateKey(encryptedPayload, privateKey) {
+    const crypto = await getVirtruCrypto();
+    const vKey = unwrapPrivateKey(privateKey);
+    const payloadBytes = new Uint8Array(encryptedPayload.asArrayBuffer());
+    const decrypted = await crypto.decrypt(RSA_OAEP_PARAMS, vKey, payloadBytes);
+    return Binary.fromArrayBuffer(decrypted.buffer);
+}
+// ─── Sign / Verify ────────────────────────────────────────────────────────────
+/**
+ * Sign data with an RSA private key (RS256 only).
+ * VirtruCrypto requires pre-hashed data, so the data is SHA-256 hashed first.
+ */
+export async function sign(data, privateKey, algorithm) {
+    if (algorithm !== 'RS256') {
+        throw new ConfigurationError(`Signing algorithm '${algorithm}' not supported in FIPS mode. Only RS256 is supported.`);
+    }
+    const crypto = await getVirtruCrypto();
+    const vKey = unwrapPrivateKey(privateKey);
+    // VirtruCrypto signs a pre-computed hash, not raw data
+    const hash = await crypto.digest({ name: 'SHA-256' }, data);
+    const sig = await crypto.sign(RS256_PARAMS, vKey, new Uint8Array(hash));
+    return new Uint8Array(sig);
+}
+/**
+ * Verify an RS256 signature.
+ * VirtruCrypto requires pre-hashed data.
+ */
+export async function verify(data, signature, publicKey, algorithm) {
+    if (algorithm !== 'RS256') {
+        throw new ConfigurationError(`Verification algorithm '${algorithm}' not supported in FIPS mode. Only RS256 is supported.`);
+    }
+    const crypto = await getVirtruCrypto();
+    const vKey = unwrapPublicKey(publicKey);
+    const hash = await crypto.digest({ name: 'SHA-256' }, data);
+    try {
+        return await crypto.verify(RS256_PARAMS, vKey, signature, new Uint8Array(hash));
+    }
+    catch (e) {
+        if (e === 'Signature verification error')
+            return false;
+        throw e;
+    }
+}
+// ─── EC Stubs (unsupported in FIPS mode) ─────────────────────────────────────
+export async function generateECKeyPair(_curve) {
+    throw new ConfigurationError('EC key generation is not supported in FIPS mode.');
+}
+export async function deriveKeyFromECDH(_privateKey, _publicKey, _hkdfParams) {
+    throw new ConfigurationError('ECDH key derivation is not supported in FIPS mode.');
+}

package/dist/src/lib/fips-crypto/key-format.d.ts

@@ -0,0 +1,51 @@
+import { type KeyOptions, type PrivateKey, type PublicKey, type PublicKeyInfo } from '@opentdf/sdk/singlecontainer';
+/**
+ * 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.
+ */
+export declare function importPublicKey(pem: string, options: KeyOptions): Promise<PublicKey>;
+/**
+ * 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'`.
+ */
+export declare function importPrivateKey(pem: string, options: KeyOptions): Promise<PrivateKey>;
+/**
+ * Export an opaque public key to PEM (SPKI / `-----BEGIN PUBLIC KEY-----`).
+ * Handles VirtruCrypto's PKCS#1 output for generated keys transparently.
+ */
+export declare function exportPublicKeyPem(key: PublicKey): Promise<string>;
+/**
+ * Export an opaque public key to JWK.
+ * Uses WebCrypto for the JWK conversion after normalizing to SPKI.
+ */
+export declare function exportPublicKeyJwk(key: PublicKey): Promise<JsonWebKey>;
+/**
+ * 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.
+ */
+export declare function exportPrivateKeyPem(key: PrivateKey): Promise<string>;
+/**
+ * Use the WebCrypto API to parse a PEM public key and extract its algorithm info.
+ */
+export declare function parsePublicKeyPem(pem: string): Promise<PublicKeyInfo>;
+/**
+ * Use the WebCrypto API to extract the public key PEM from a certificate or PEM string.
+ */
+export declare function extractPublicKeyPem(certOrPem: string): Promise<string>;
+/**
+ * Use the WebCrypto API to convert a JWK public key to PEM format.
+ */
+export declare function jwkToPublicKeyPem(jwk: JsonWebKey): Promise<string>;

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

@@ -0,0 +1,233 @@
+/*
+ * 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 { WebCryptoService, } from '@opentdf/sdk/singlecontainer';
+import { ConfigurationError } from '@opentdf/sdk';
+import { formatAsPem, removePemFormatting, guessAlgorithmName } from '@opentdf/sdk/cryptoutils';
+import { base64, hex } from '@opentdf/sdk/encodings';
+import { getVirtruCrypto } from './primitives';
+import { wrapPublicKey, wrapPrivateKey, unwrapPublicKey, unwrapPrivateKey } from './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(base64.decodeArrayBuffer(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 = hex.encodeArrayBuffer(derBytes.buffer);
+    try {
+        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.
+ */
+export 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 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 getVirtruCrypto();
+    const vKey = await crypto.importKey('spki', keyBytes, { name: 'RSASSA-PKCS1-v1_5' }, extractable, usages);
+    return 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'`.
+ */
+export 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 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 getVirtruCrypto();
+    const vKey = await crypto.importKey('pkcs8', keyBytes, { name: 'RSASSA-PKCS1-v1_5' }, extractable, usages);
+    return 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.
+ */
+export async function exportPublicKeyPem(key) {
+    const crypto = await getVirtruCrypto();
+    const exported = await crypto.exportKey('spki', unwrapPublicKey(key));
+    const spki = normalizePublicKeyToSpki(exported);
+    return formatAsPem(spki.buffer, 'PUBLIC KEY');
+}
+/**
+ * Export an opaque public key to JWK.
+ * Uses WebCrypto for the JWK conversion after normalizing to SPKI.
+ */
+export async function exportPublicKeyJwk(key) {
+    const crypto = await getVirtruCrypto();
+    const exported = await crypto.exportKey('spki', 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.
+ */
+export async function exportPrivateKeyPem(key) {
+    const crypto = await getVirtruCrypto();
+    const exported = await crypto.exportKey('pkcs8', unwrapPrivateKey(key));
+    const pkcs8 = normalizePrivateKeyToPkcs8(exported);
+    return formatAsPem(pkcs8.buffer, 'PRIVATE KEY');
+}
+// ─── Public Key Utils ─────────────────────────────────────
+/**
+ * Use the WebCrypto API to parse a PEM public key and extract its algorithm info.
+ */
+export async function parsePublicKeyPem(pem) {
+    return WebCryptoService.parsePublicKeyPem(pem);
+}
+/**
+ * Use the WebCrypto API to extract the public key PEM from a certificate or PEM string.
+ */
+export async function extractPublicKeyPem(certOrPem) {
+    return WebCryptoService.extractPublicKeyPem(certOrPem);
+}
+/**
+ * Use the WebCrypto API to convert a JWK public key to PEM format.
+ */
+export async function jwkToPublicKeyPem(jwk) {
+    return WebCryptoService.jwkToPublicKeyPem(jwk);
+}