@virtru/dsp-sdk 0.4.0 → 0.5.0

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

@@ -0,0 +1,162 @@
+/*
+ * 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 {
+  type AsymmetricSigningAlgorithm,
+  type ECCurve,
+  type HkdfParams,
+  type KeyPair,
+  type PrivateKey,
+  type PublicKey,
+  type SymmetricKey,
+} 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'] as const;
+const SIGN_VERIFY_METHODS = ['sign', 'verify'] as const;
+
+const RSA_OAEP_PARAMS = {
+  name: 'RSA-OAEP' as const,
+  modulusLength: 2048,
+  publicExponent: [1, 0, 1],
+  hash: 'SHA-256' as const,
+};
+
+const RS256_PARAMS = {
+  name: 'RSASSA-PKCS1-v1_5' as const,
+  modulusLength: 2048,
+  publicExponent: [1, 0, 1],
+  hash: 'SHA-256' as const,
+};
+
+/**
+ * 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?: number): Promise<KeyPair> {
+  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(): Promise<KeyPair> {
+  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: Binary | SymmetricKey,
+  publicKey: PublicKey
+): Promise<Binary> {
+  const crypto = await getVirtruCrypto();
+
+  let payloadBytes: Uint8Array;
+  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 as any, vKey, payloadBytes);
+  return Binary.fromArrayBuffer((encrypted as Uint8Array).buffer as ArrayBuffer);
+}
+
+/**
+ * Decrypt with RSA-OAEP private key.
+ */
+export async function decryptWithPrivateKey(
+  encryptedPayload: Binary,
+  privateKey: PrivateKey
+): Promise<Binary> {
+  const crypto = await getVirtruCrypto();
+  const vKey = unwrapPrivateKey(privateKey);
+  const payloadBytes = new Uint8Array(encryptedPayload.asArrayBuffer());
+  const decrypted = await crypto.decrypt(RSA_OAEP_PARAMS as any, vKey, payloadBytes);
+  return Binary.fromArrayBuffer((decrypted as Uint8Array).buffer as ArrayBuffer);
+}
+
+// ─── 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: Uint8Array,
+  privateKey: PrivateKey,
+  algorithm: AsymmetricSigningAlgorithm
+): Promise<Uint8Array> {
+  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: Uint8Array,
+  signature: Uint8Array,
+  publicKey: PublicKey,
+  algorithm: AsymmetricSigningAlgorithm
+): Promise<boolean> {
+  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?: ECCurve): Promise<KeyPair> {
+  throw new ConfigurationError('EC key generation is not supported in FIPS mode.');
+}
+
+export async function deriveKeyFromECDH(
+  _privateKey: PrivateKey,
+  _publicKey: PublicKey,
+  _hkdfParams: HkdfParams
+): Promise<SymmetricKey> {
+  throw new ConfigurationError('ECDH key derivation is not supported in FIPS mode.');
+}

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

@@ -0,0 +1,287 @@
+/*
+ * 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 {
+  type KeyAlgorithm,
+  type KeyOptions,
+  type PrivateKey,
+  type PublicKey,
+  type PublicKeyInfo,
+  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, type VirtruKeyUsage } from './primitives';
+import { wrapPublicKey, wrapPrivateKey, unwrapPublicKey, unwrapPrivateKey } from './keys';
+
+const VERIFY_USAGE: readonly VirtruKeyUsage[] = ['verify'];
+const ENCRYPT_VERIFY_USAGES: readonly VirtruKeyUsage[] = ['encrypt', 'verify'];
+const SIGN_USAGE: readonly VirtruKeyUsage[] = ['sign'];
+const DECRYPT_USAGE: readonly VirtruKeyUsage[] = ['decrypt'];
+
+// ─── PEM Utilities ────────────────────────────────────────────────────────────
+
+/**
+ * Strip PEM headers/footers and whitespace, decode base64 → raw DER bytes.
+ */
+function pemToBytes(pem: string): Uint8Array {
+  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: Uint8Array): number {
+  let pos = 0;
+
+  const readLen = (): number => {
+    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: number): Uint8Array {
+  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: Uint8Array[]): Uint8Array {
+  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: Uint8Array[]): Uint8Array {
+  const body = asn1Concat(elements);
+  return asn1Concat([new Uint8Array([0x30]), asn1EncodeLength(body.length), body]);
+}
+
+function asn1BitString(data: Uint8Array): Uint8Array {
+  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: Uint8Array): boolean {
+  const hexStr = hex.encodeArrayBuffer(derBytes.buffer as ArrayBuffer);
+  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: Uint8Array): Uint8Array {
+  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: Uint8Array): Uint8Array {
+  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: string, options: KeyOptions): Promise<PublicKey> {
+  const { usage = 'encrypt', extractable = true, algorithmHint } = options;
+
+  const keyBytes = pemToBytes(pem);
+
+  let algorithm: KeyAlgorithm;
+  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: string, options: KeyOptions): Promise<PrivateKey> {
+  const { usage = 'encrypt', extractable = false, algorithmHint } = options;
+
+  const keyBytes = pemToBytes(pem);
+  const algorithm: KeyAlgorithm = 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: PublicKey): Promise<string> {
+  const crypto = await getVirtruCrypto();
+  const exported = await crypto.exportKey('spki', unwrapPublicKey(key));
+  const spki = normalizePublicKeyToSpki(exported);
+  return formatAsPem(spki.buffer as ArrayBuffer, 'PUBLIC KEY');
+}
+
+/**
+ * Export an opaque public key to JWK.
+ * Uses WebCrypto for the JWK conversion after normalizing to SPKI.
+ */
+export async function exportPublicKeyJwk(key: PublicKey): Promise<JsonWebKey> {
+  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: PrivateKey): Promise<string> {
+  const crypto = await getVirtruCrypto();
+  const exported = await crypto.exportKey('pkcs8', unwrapPrivateKey(key));
+  const pkcs8 = normalizePrivateKeyToPkcs8(exported);
+  return formatAsPem(pkcs8.buffer as ArrayBuffer, '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: string): Promise<PublicKeyInfo> {
+    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: string): Promise<string> {
+    return WebCryptoService.extractPublicKeyPem(certOrPem);
+}
+
+/**
+ * Use the WebCrypto API to convert a JWK public key to PEM format.
+ */
+export async function jwkToPublicKeyPem(jwk: JsonWebKey): Promise<string> {
+    return WebCryptoService.jwkToPublicKeyPem(jwk);
+}

package/src/lib/fips-crypto/keys.ts

@@ -0,0 +1,190 @@
+/*
+ * 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 {
+  type KeyAlgorithm,
+  type KeyPair,
+  type PrivateKey,
+  type PublicKey,
+  type SymmetricKey,
+  type ECCurve,
+} from '@opentdf/sdk/singlecontainer';
+
+interface VirtruCryptoKeyHandle {
+  release(): void;
+  [key: string]: unknown;
+}
+
+// Opaque Key Types
+//
+// Asymmetric keys (PublicKey, PrivateKey) store a VirtruCryptoKey handle,
+// keeping the key material inside the FIPS WASM keystore at all times.
+//
+// Symmetric keys (SymmetricKey) store a VirtruCryptoKey handle pointing to
+// either a keystore slot (imported keys) or a heap allocation (generated keys).
+//
+// All opaque wrappers are registered with keyFinalizer so WASM slots/heap
+// memory are freed automatically when the JS wrapper is garbage collected.
+// This covers the common case where callers (e.g. the opentdf SDK) never
+// call release() explicitly — without this, every TDF operation would
+// permanently consume a keystore slot and the WASM would exhaust all 50 slots (NUM_KEYS).
+
+export type OpaquePublicKey = PublicKey & { readonly _internal: VirtruCryptoKeyHandle };
+export type OpaquePrivateKey = PrivateKey & { readonly _internal: VirtruCryptoKeyHandle };
+export type OpaqueSymmetricKey = SymmetricKey & { readonly _internal: VirtruCryptoKeyHandle };
+
+type KeyBrand = 'PublicKey' | 'PrivateKey' | 'SymmetricKey';
+
+interface OpaqueKeyShapeBase<TBrand extends KeyBrand> {
+  _brand: TBrand;
+  _internal: VirtruCryptoKeyHandle;
+}
+
+interface OpaquePublicKeyShape extends OpaqueKeyShapeBase<'PublicKey'> {
+  algorithm: KeyAlgorithm;
+  modulusBits?: number;
+  curve?: ECCurve;
+}
+
+interface OpaquePrivateKeyShape extends OpaqueKeyShapeBase<'PrivateKey'> {
+  algorithm: KeyAlgorithm;
+  modulusBits?: number;
+}
+
+interface OpaqueSymmetricKeyShape extends OpaqueKeyShapeBase<'SymmetricKey'> {
+  length: number;
+}
+
+// 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.
+export const keyFinalizer = new FinalizationRegistry((handle: { release(): void }) => {
+  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: VirtruCryptoKeyHandle): { release(): void } {
+  let refs = 2;
+  return {
+    release() {
+      if (--refs === 0) key.release();
+    },
+  };
+}
+
+// Wrap Helpers
+
+export function wrapPublicKey(key: VirtruCryptoKeyHandle, algorithm: KeyAlgorithm): PublicKey {
+  const result: OpaquePublicKeyShape = {
+    _brand: 'PublicKey' as const,
+    algorithm,
+    _internal: key,
+  };
+  if (algorithm.startsWith('rsa:')) {
+    result.modulusBits = parseInt(algorithm.split(':')[1], 10);
+  } else if (algorithm.startsWith('ec:')) {
+    const curveMap: Record<string, ECCurve> = {
+      secp256r1: 'P-256',
+      secp384r1: 'P-384',
+      secp521r1: 'P-521',
+    };
+    result.curve = curveMap[algorithm.split(':')[1]];
+  }
+  keyFinalizer.register(result, key);
+  return result as PublicKey;
+}
+
+export function wrapPrivateKey(key: VirtruCryptoKeyHandle, algorithm: KeyAlgorithm): PrivateKey {
+  const result: OpaquePrivateKeyShape = {
+    _brand: 'PrivateKey' as const,
+    algorithm,
+    _internal: key,
+  };
+  if (algorithm.startsWith('rsa:')) {
+    result.modulusBits = parseInt(algorithm.split(':')[1], 10);
+  }
+  keyFinalizer.register(result, key);
+  return result as PrivateKey;
+}
+
+export function wrapSymmetricKey(key: VirtruCryptoKeyHandle, lengthBits: number): SymmetricKey {
+  const result: OpaqueSymmetricKeyShape = {
+    _brand: 'SymmetricKey' as const,
+    length: lengthBits,
+    _internal: key,
+  };
+  keyFinalizer.register(result, key);
+  return result as SymmetricKey;
+}
+
+export function wrapKeyPair(
+  publicKey: VirtruCryptoKeyHandle,
+  privateKey: VirtruCryptoKeyHandle,
+  algorithm: KeyAlgorithm
+): KeyPair {
+  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: OpaquePublicKeyShape = {
+      _brand: 'PublicKey' as const,
+      algorithm,
+      _internal: publicKey,
+    };
+    const priv: OpaquePrivateKeyShape = {
+      _brand: 'PrivateKey' as const,
+      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: Record<string, ECCurve> = {
+        secp256r1: 'P-256',
+        secp384r1: 'P-384',
+        secp521r1: 'P-521',
+      };
+      pub.curve = curveMap[algorithm.split(':')[1]];
+    }
+    keyFinalizer.register(pub, shared);
+    keyFinalizer.register(priv, shared);
+    return { publicKey: pub as PublicKey, privateKey: priv as PrivateKey };
+  }
+  return {
+    publicKey: wrapPublicKey(publicKey, algorithm),
+    privateKey: wrapPrivateKey(privateKey, algorithm),
+  };
+}
+
+// ─── Unwrap Helpers ───────────────────────────────────────────────────────────
+
+export function unwrapPublicKey(key: PublicKey): VirtruCryptoKeyHandle {
+  return (key as OpaquePublicKey)._internal;
+}
+
+export function unwrapPrivateKey(key: PrivateKey): VirtruCryptoKeyHandle {
+  return (key as OpaquePrivateKey)._internal;
+}
+
+export function unwrapSymmetricKey(key: SymmetricKey): VirtruCryptoKeyHandle {
+  return (key as OpaqueSymmetricKey)._internal;
+}
+
+export function isSymmetricKey(value: unknown): value is SymmetricKey {
+  if (!value || typeof value !== 'object' || !('_brand' in value)) {
+    return false;
+  }
+
+  const candidate = value as { _brand?: unknown };
+  return candidate._brand === 'SymmetricKey';
+}