@opentdf/sdk 0.12.0 → 0.13.0-beta.122

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentdf/sdk",
-  "version": "0.12.0",
+  "version": "0.13.0-beta.122",
   "description": "OpenTDF for the Web",
   "homepage": "https://github.com/opentdf/web-sdk",
   "bugs": {

package/src/auth/dpop.ts

@@ -63,8 +63,8 @@ function b64u(input: Uint8Array | ArrayBuffer) {
 /**
  * Generates 32 random bytes and encodes them using base64url.
  */
-async function randomBytes(cryptoService: CryptoService) {
-  return b64u(await cryptoService.randomBytes(32));
+async function randomBytes() {
+  return b64u(crypto.getRandomValues(new Uint8Array(32)));
 }
 
 /**
@@ -210,7 +210,7 @@ export default async function DPoP(
     {
       ...additional,
       iat: epochTime(),
-      jti: await randomBytes(cryptoService),
+      jti: await randomBytes(),
       htm,
       nonce,
       htu,

package/src/auth/oidc.ts

@@ -11,7 +11,7 @@ import { type CryptoService, type KeyPair } from '../../tdf3/src/crypto/declarat
 export type CommonCredentials = {
   /** The OIDC client ID used for token issuance and exchange flows */
   clientId: string;
-  /** The endpoint of the OIDC IdP to authenticate against, ex. 'https://virtru.com/auth' */
+  /** The endpoint of the OIDC IdP to authenticate against, ex. 'https://keycloak.opentdf.local/auth' */
   oidcOrigin: string;
   oidcTokenEndpoint?: string;
   oidcUserInfoEndpoint?: string;
@@ -176,6 +176,8 @@ export class AccessToken {
       }
       // Export opaque public key to PEM format for header
       const publicKeyPem = await this.cryptoService.exportPublicKeyPem(this.signingKey.publicKey);
+      // TODO: Rename to X-OpenTDF-PubKey; requires coordinated change with
+      // platform Keycloak mapper (lib/fixtures/keycloak.go `client.publickey`).
       headers['X-VirtruPubKey'] = base64.encode(publicKeyPem);
       headers.DPoP = await dpopFn(this.signingKey, this.cryptoService, url, 'POST');
     }
@@ -300,9 +302,9 @@ export class AccessToken {
   }
 
   async withCreds(httpReq: HttpRequest): Promise<HttpRequest> {
-    if (!this.signingKey) {
+    if (this.config.dpopEnabled && !this.signingKey) {
       throw new ConfigurationError(
-        'Client public key was not set via `updateClientPublicKey` or passed in via constructor, cannot fetch OIDC token with valid Virtru claims'
+        'Client public key was not set via `updateClientPublicKey` or passed in via constructor; required when DPoP is enabled'
       );
     }
     const accessToken = (this.currentAccessToken ??= await this.get());

package/src/version.ts

@@ -1,7 +1,7 @@
 /**
  * Exposes the released version number of the `@opentdf/sdk` package
  */
-export const version = '0.12.0'; // x-release-please-version
+export const version = '0.13.0'; // x-release-please-version
 
 /**
  * A string name used to label requests as coming from this library client.

package/tdf3/src/crypto/core/ec.ts

@@ -0,0 +1,118 @@
+import {
+  type ECCurve,
+  type HkdfParams,
+  type KeyAlgorithm,
+  type KeyPair,
+  type PrivateKey,
+  type PublicKey,
+  type SymmetricKey,
+} from '../declarations.js';
+import { ConfigurationError } from '../../../../src/errors.js';
+import { unwrapKey, wrapPrivateKey, wrapPublicKey, wrapSymmetricKey } from './keys.js';
+
+/**
+ * Map ECCurve to Web Crypto named curve.
+ */
+function curveToNamedCurve(curve: ECCurve): string {
+  switch (curve) {
+    case 'P-256':
+      return 'P-256';
+    case 'P-384':
+      return 'P-384';
+    case 'P-521':
+      return 'P-521';
+    default:
+      throw new ConfigurationError(`Unsupported curve: ${curve}`);
+  }
+}
+
+/**
+ * Generate an EC key pair for ECDH key agreement.
+ */
+export async function generateECKeyPair(curve: ECCurve = 'P-256'): Promise<KeyPair> {
+  const namedCurve = curveToNamedCurve(curve);
+
+  // Generate key pair for ECDH key agreement
+  const keyPair = await crypto.subtle.generateKey({ name: 'ECDH', namedCurve }, true, [
+    'deriveBits',
+  ]);
+
+  // Map to KeyAlgorithm literal type
+  let algorithm: KeyAlgorithm;
+  switch (namedCurve) {
+    case 'P-256':
+      algorithm = 'ec:secp256r1';
+      break;
+    case 'P-384':
+      algorithm = 'ec:secp384r1';
+      break;
+    case 'P-521':
+      algorithm = 'ec:secp521r1';
+      break;
+    default:
+      throw new ConfigurationError(`Unsupported curve: ${namedCurve}`);
+  }
+
+  return {
+    publicKey: wrapPublicKey(keyPair.publicKey, algorithm),
+    privateKey: wrapPrivateKey(keyPair.privateKey, algorithm),
+  };
+}
+
+/**
+ * Perform ECDH key agreement followed by HKDF key derivation.
+ * Returns opaque symmetric key for symmetric encryption.
+ */
+export async function deriveKeyFromECDH(
+  privateKey: PrivateKey,
+  publicKey: PublicKey,
+  hkdfParams: HkdfParams
+): Promise<SymmetricKey> {
+  // Unwrap the internal CryptoKeys
+  const privateKeyCrypto = unwrapKey(privateKey);
+  const publicKeyCrypto = unwrapKey(publicKey);
+
+  // Get curve from key metadata
+  const curve = publicKey.curve;
+  if (!curve) {
+    throw new ConfigurationError('EC curve not found on public key');
+  }
+
+  // Determine bits based on curve
+  const curveBits: Record<ECCurve, number> = {
+    'P-256': 256,
+    'P-384': 384,
+    // P-521 derives 528 bits (66 bytes)
+    'P-521': 528,
+  };
+  const bits = curveBits[curve];
+
+  // Perform ECDH to get shared secret
+  const sharedSecret = await crypto.subtle.deriveBits(
+    { name: 'ECDH', public: publicKeyCrypto },
+    privateKeyCrypto,
+    bits
+  );
+
+  // Import shared secret as HKDF key material
+  const hkdfKey = await crypto.subtle.importKey('raw', sharedSecret, 'HKDF', false, ['deriveKey']);
+
+  // Derive the final key using HKDF
+  const keyLength = hkdfParams.keyLength ?? 256;
+  const derivedKey = await crypto.subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: hkdfParams.hash,
+      salt: hkdfParams.salt,
+      info: hkdfParams.info ?? new Uint8Array(0),
+    },
+    hkdfKey,
+    { name: 'AES-GCM', length: keyLength },
+    true,
+    ['encrypt', 'decrypt']
+  );
+
+  // Export the derived key as raw bytes and wrap as SymmetricKey
+  const keyBytes = await crypto.subtle.exportKey('raw', derivedKey);
+  return wrapSymmetricKey(new Uint8Array(keyBytes));
+}

package/tdf3/src/crypto/core/key-format.ts

@@ -0,0 +1,420 @@
+import {
+  type KeyAlgorithm,
+  type KeyOptions,
+  MIN_ASYMMETRIC_KEY_SIZE_BITS,
+  type PrivateKey,
+  type PublicKey,
+  type PublicKeyInfo,
+} from '../declarations.js';
+import { ConfigurationError } from '../../../../src/errors.js';
+import { formatAsPem, removePemFormatting } from '../crypto-utils.js';
+import { encodeArrayBuffer as hexEncode } from '../../../../src/encodings/hex.js';
+import { decodeArrayBuffer as base64Decode } from '../../../../src/encodings/base64.js';
+import { exportSPKI, importX509 } from 'jose';
+import {
+  guessAlgorithmName,
+  guessCurveName,
+  toJwsAlg,
+} from '../../../../src/crypto/pemPublicToCrypto.js';
+import { unwrapKey, wrapPrivateKey, wrapPublicKey } from './keys.js';
+import { rsaOaepSha1 } from './rsa.js';
+
+/**
+ * Extract PEM public key from X.509 certificate or return PEM key as-is.
+ */
+export async function extractPublicKeyPem(
+  certOrPem: string,
+  jwaAlgorithm?: string
+): Promise<string> {
+  // If it's a certificate, extract the public key
+  if (certOrPem.includes('-----BEGIN CERTIFICATE-----')) {
+    let alg = jwaAlgorithm;
+    if (!alg) {
+      // Auto-detect algorithm from certificate OIDs
+      const certBody = certOrPem.replace(/-----(BEGIN|END) CERTIFICATE-----|\s/g, '');
+      const certBytes = base64Decode(certBody);
+      const hex = hexEncode(certBytes);
+      alg = toJwsAlg(hex);
+    }
+    const cert = await importX509(certOrPem, alg, { extractable: true });
+    return exportSPKI(cert);
+  }
+
+  // If it's already a PEM public key, return as-is
+  if (certOrPem.includes('-----BEGIN PUBLIC KEY-----')) {
+    return certOrPem;
+  }
+
+  throw new ConfigurationError('Input must be a PEM-encoded certificate or public key');
+}
+
+const SUPPORTED_EC_CURVES = ['P-256', 'P-384', 'P-521'] as const;
+type SupportedEcCurve = (typeof SUPPORTED_EC_CURVES)[number];
+
+/**
+ * Decode base64url string and return byte length.
+ * Uses the existing base64 decoder which handles both standard and URL-safe encoding.
+ */
+function base64urlByteLength(base64url: string): number {
+  // Add padding if needed (base64url omits padding)
+  const padding = (4 - (base64url.length % 4)) % 4;
+  const padded = base64url + '='.repeat(padding);
+  return base64Decode(padded).byteLength;
+}
+
+/**
+ * Extract EC curve from a public key by parsing ASN.1 OIDs.
+ * Reuses the existing guessCurveName function that checks for curve OIDs.
+ */
+function extractEcCurveFromPublicKey(keyData: ArrayBuffer): SupportedEcCurve {
+  // Convert to hex for OID parsing
+  const hexKey = hexEncode(keyData);
+  // Use existing OID parser (returns 'P-256', 'P-384', or 'P-521')
+  const curveName = guessCurveName(hexKey);
+  return curveName as SupportedEcCurve;
+}
+
+/**
+ * Extract RSA modulus bit length by importing key and exporting as JWK.
+ * Uses Web Crypto's built-in ASN.1 parsing for robustness.
+ */
+async function extractRsaModulusBitLength(keyData: ArrayBuffer): Promise<number> {
+  const key = await crypto.subtle.importKey(
+    'spki',
+    keyData,
+    { name: 'RSA-OAEP', hash: 'SHA-256' },
+    true,
+    ['encrypt']
+  );
+  const jwk = await crypto.subtle.exportKey('jwk', key);
+  if (!jwk.n) {
+    throw new ConfigurationError('Invalid RSA key: missing modulus');
+  }
+  // JWK 'n' is base64url-encoded modulus
+  // Decode and count bytes, multiply by 8 for bits
+  return base64urlByteLength(jwk.n) * 8;
+}
+
+/**
+ * Import and validate a PEM public key, returning algorithm info.
+ * Uses JWK export for robust key parameter detection.
+ */
+export async function parsePublicKeyPem(pem: string): Promise<PublicKeyInfo> {
+  // First extract public key if it's a certificate
+  let publicKeyPem = pem;
+  if (pem.includes('-----BEGIN CERTIFICATE-----')) {
+    publicKeyPem = await extractPublicKeyPem(pem);
+  }
+
+  if (!publicKeyPem.includes('-----BEGIN PUBLIC KEY-----')) {
+    throw new ConfigurationError('Input must be a PEM-encoded public key or certificate');
+  }
+
+  const keyData = base64Decode(removePemFormatting(publicKeyPem));
+
+  // Try RSA first - use JWK export to get modulus size
+  try {
+    const modulusBits = await extractRsaModulusBitLength(keyData);
+    let algorithm: PublicKeyInfo['algorithm'];
+    if (modulusBits < MIN_ASYMMETRIC_KEY_SIZE_BITS) {
+      throw new ConfigurationError(
+        `RSA key size ${modulusBits} bits is below the minimum of ${MIN_ASYMMETRIC_KEY_SIZE_BITS} bits`
+      );
+    } else if (modulusBits <= 2048) {
+      algorithm = 'rsa:2048';
+    } else if (modulusBits <= 4096) {
+      algorithm = 'rsa:4096';
+    } else {
+      throw new ConfigurationError(`Unsupported RSA key size: ${modulusBits} bits`);
+    }
+    return { algorithm, pem: publicKeyPem };
+  } catch (e) {
+    // If it's our own ConfigurationError, rethrow
+    if (e instanceof ConfigurationError) {
+      throw e;
+    }
+    // Not an RSA key, try EC next
+  }
+
+  // Try EC - parse curve from OID
+  try {
+    const detectedCurve = extractEcCurveFromPublicKey(keyData);
+    const curveMap = {
+      'P-256': 'ec:secp256r1',
+      'P-384': 'ec:secp384r1',
+      'P-521': 'ec:secp521r1',
+    } as const;
+    return { algorithm: curveMap[detectedCurve], pem: publicKeyPem };
+  } catch {
+    // Not a valid EC key
+  }
+
+  throw new ConfigurationError('Unable to determine public key algorithm - unsupported key type');
+}
+
+/**
+ * Convert a JWK (JSON Web Key) to PEM format.
+ */
+export async function jwkToPublicKeyPem(jwk: JsonWebKey): Promise<string> {
+  let key: CryptoKey;
+
+  if (jwk.kty === 'RSA') {
+    // RSA key
+    key = await crypto.subtle.importKey('jwk', jwk, { name: 'RSA-OAEP', hash: 'SHA-256' }, true, [
+      'encrypt',
+    ]);
+  } else if (jwk.kty === 'EC') {
+    // EC key
+    const crv = jwk.crv;
+    if (!crv || !['P-256', 'P-384', 'P-521'].includes(crv)) {
+      throw new ConfigurationError(`Unsupported EC curve: ${crv}`);
+    }
+    key = await crypto.subtle.importKey('jwk', jwk, { name: 'ECDH', namedCurve: crv }, true, []);
+  } else {
+    throw new ConfigurationError(`Unsupported JWK key type: ${jwk.kty}`);
+  }
+
+  const spkiBuffer = await crypto.subtle.exportKey('spki', key);
+  return formatAsPem(spkiBuffer, 'PUBLIC KEY');
+}
+
+/**
+ * Convert a PEM public key to JWK format.
+ * Returns only public key components (no private key data).
+ */
+export async function publicKeyPemToJwk(publicKeyPem: string): Promise<JsonWebKey> {
+  const keyDataBase64 = removePemFormatting(publicKeyPem);
+  const keyBuffer = base64Decode(keyDataBase64);
+  const hex = hexEncode(keyBuffer);
+
+  // Detect key type using OID
+  const algorithmName = guessAlgorithmName(hex);
+
+  if (algorithmName === 'ECDH' || algorithmName === 'ECDSA') {
+    // EC key - detect curve from OID
+    const namedCurve = guessCurveName(hex);
+    const key = await crypto.subtle.importKey(
+      'spki',
+      keyBuffer,
+      { name: 'ECDSA', namedCurve },
+      true,
+      ['verify']
+    );
+    const jwk = await crypto.subtle.exportKey('jwk', key);
+    // Return only public key components
+    const { kty, crv, x, y } = jwk;
+    return { kty, crv, x, y };
+  } else {
+    // RSA key
+    const key = await crypto.subtle.importKey(
+      'spki',
+      keyBuffer,
+      { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+      true,
+      ['verify']
+    );
+    const jwk = await crypto.subtle.exportKey('jwk', key);
+    // Return only public key components
+    const { kty, e, n } = jwk;
+    return { kty, e, n };
+  }
+}
+
+/**
+ * Import a PEM public key as an opaque key.
+ */
+export async function importPublicKey(pem: string, options: KeyOptions): Promise<PublicKey> {
+  const { usage = 'encrypt', extractable = true, algorithmHint } = options;
+
+  // Detect algorithm from PEM; also normalises certificates → plain SPKI PEM.
+  const keyInfo = await parsePublicKeyPem(pem);
+  const algorithm = algorithmHint || keyInfo.algorithm;
+  // Use keyInfo.pem (normalised SPKI) not the original pem, which may be a certificate.
+  // Passing raw X.509 DER bytes to crypto.subtle.importKey('spki') would throw DataError.
+  const keyData = removePemFormatting(keyInfo.pem);
+  const keyBuffer = base64Decode(keyData);
+
+  // Determine Web Crypto algorithm and usages based on key type and usage
+  let cryptoAlgorithm: RsaHashedImportParams | EcKeyImportParams;
+  let keyUsages: KeyUsage[];
+
+  if (algorithm.startsWith('rsa:')) {
+    if (usage === 'encrypt') {
+      cryptoAlgorithm = rsaOaepSha1();
+      keyUsages = ['encrypt'];
+    } else if (usage === 'sign') {
+      cryptoAlgorithm = { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' };
+      keyUsages = ['verify'];
+    } else {
+      throw new ConfigurationError('RSA keys only support usage: encrypt or sign');
+    }
+  } else if (algorithm.startsWith('ec:')) {
+    const curve = algorithm.split(':')[1];
+    const namedCurve =
+      curve === 'secp256r1'
+        ? 'P-256'
+        : curve === 'secp384r1'
+          ? 'P-384'
+          : curve === 'secp521r1'
+            ? 'P-521'
+            : (() => {
+                throw new ConfigurationError(`Unsupported EC curve: ${curve}`);
+              })();
+
+    if (usage === 'derive') {
+      cryptoAlgorithm = { name: 'ECDH', namedCurve };
+      keyUsages = [];
+    } else if (usage === 'sign') {
+      cryptoAlgorithm = { name: 'ECDSA', namedCurve };
+      keyUsages = ['verify'];
+    } else {
+      throw new ConfigurationError('EC keys only support usage: derive or sign');
+    }
+  } else {
+    throw new ConfigurationError(`Unsupported algorithm: ${algorithm}`);
+  }
+
+  // Import as CryptoKey
+  const cryptoKey = await crypto.subtle.importKey(
+    'spki',
+    keyBuffer,
+    cryptoAlgorithm,
+    extractable,
+    keyUsages
+  );
+
+  return wrapPublicKey(cryptoKey, algorithm);
+}
+
+/**
+ * Import a PEM private key as an opaque key.
+ */
+export async function importPrivateKey(pem: string, options: KeyOptions): Promise<PrivateKey> {
+  const { usage = 'encrypt', extractable = true, algorithmHint } = options;
+
+  // Detect algorithm from PEM structure (similar to public key detection)
+  // For now, use algorithmHint if provided, otherwise detect from key structure
+  let algorithm: KeyAlgorithm;
+
+  const keyData = removePemFormatting(pem);
+  const keyBuffer = base64Decode(keyData);
+
+  if (algorithmHint) {
+    algorithm = algorithmHint;
+  } else {
+    // PKCS#8 PrivateKeyInfo embeds the same AlgorithmIdentifier OIDs as SPKI,
+    // so guessAlgorithmName / guessCurveName work on private key bytes too.
+    const hex = hexEncode(keyBuffer);
+    const algorithmName = guessAlgorithmName(hex); // throws on unrecognised OID
+    if (algorithmName === 'ECDH' || algorithmName === 'ECDSA') {
+      const namedCurve = guessCurveName(hex);
+      const curveMap: Record<string, KeyAlgorithm> = {
+        'P-256': 'ec:secp256r1',
+        'P-384': 'ec:secp384r1',
+        'P-521': 'ec:secp521r1',
+      };
+      const mapped = curveMap[namedCurve];
+      if (!mapped)
+        throw new ConfigurationError(`Unsupported EC curve in private key: ${namedCurve}`);
+      algorithm = mapped;
+    } else {
+      // RSA — determine key size by importing and reading modulus length from JWK
+      const tempKey = await crypto.subtle.importKey(
+        'pkcs8',
+        keyBuffer,
+        { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+        true,
+        ['sign']
+      );
+      const jwk = await crypto.subtle.exportKey('jwk', tempKey);
+      if (!jwk.n) {
+        throw new ConfigurationError('Invalid RSA private key: missing modulus');
+      }
+      const modulusBits = base64urlByteLength(jwk.n) * 8;
+      if (modulusBits < MIN_ASYMMETRIC_KEY_SIZE_BITS) {
+        throw new ConfigurationError(
+          `RSA key size ${modulusBits} bits is below the minimum of ${MIN_ASYMMETRIC_KEY_SIZE_BITS} bits`
+        );
+      }
+      algorithm = modulusBits <= 2048 ? 'rsa:2048' : 'rsa:4096';
+    }
+  }
+
+  // Determine Web Crypto algorithm and usages
+  let cryptoAlgorithm: RsaHashedImportParams | EcKeyImportParams;
+  let keyUsages: KeyUsage[];
+
+  if (algorithm.startsWith('rsa:')) {
+    if (usage === 'encrypt') {
+      cryptoAlgorithm = rsaOaepSha1();
+      keyUsages = ['decrypt'];
+    } else if (usage === 'sign') {
+      cryptoAlgorithm = { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' };
+      keyUsages = ['sign'];
+    } else {
+      throw new ConfigurationError('RSA keys only support usage: encrypt or sign');
+    }
+  } else if (algorithm.startsWith('ec:')) {
+    const curve = algorithm.split(':')[1];
+    const namedCurve =
+      curve === 'secp256r1'
+        ? 'P-256'
+        : curve === 'secp384r1'
+          ? 'P-384'
+          : curve === 'secp521r1'
+            ? 'P-521'
+            : (() => {
+                throw new ConfigurationError(`Unsupported EC curve: ${curve}`);
+              })();
+
+    if (usage === 'derive') {
+      cryptoAlgorithm = { name: 'ECDH', namedCurve };
+      keyUsages = ['deriveBits'];
+    } else if (usage === 'sign') {
+      cryptoAlgorithm = { name: 'ECDSA', namedCurve };
+      keyUsages = ['sign'];
+    } else {
+      throw new ConfigurationError('EC keys only support usage: derive or sign');
+    }
+  } else {
+    throw new ConfigurationError(`Unsupported algorithm: ${algorithm}`);
+  }
+
+  // Import as CryptoKey
+  const cryptoKey = await crypto.subtle.importKey(
+    'pkcs8',
+    keyBuffer,
+    cryptoAlgorithm,
+    extractable,
+    keyUsages
+  );
+
+  return wrapPrivateKey(cryptoKey, algorithm);
+}
+
+/**
+ * Export an opaque public key to PEM format.
+ */
+export async function exportPublicKeyPem(key: PublicKey): Promise<string> {
+  const cryptoKey = unwrapKey(key);
+  const keyBuffer = await crypto.subtle.exportKey('spki', cryptoKey);
+  return formatAsPem(keyBuffer, 'PUBLIC KEY');
+}
+
+/**
+ * Export an opaque private key to PEM format.
+ * ONLY USE FOR TESTING/DEVELOPMENT. Private keys should NOT be exportable in secure environments.
+ */
+export async function exportPrivateKeyPem(key: PrivateKey): Promise<string> {
+  const cryptoKey = unwrapKey(key);
+  const keyBuffer = await crypto.subtle.exportKey('pkcs8', cryptoKey);
+  return formatAsPem(keyBuffer, 'PRIVATE KEY');
+}
+
+/**
+ * Export an opaque public key to JWK format.
+ */
+export async function exportPublicKeyJwk(key: PublicKey): Promise<JsonWebKey> {
+  const cryptoKey = unwrapKey(key);
+  return await crypto.subtle.exportKey('jwk', cryptoKey);
+}

package/tdf3/src/crypto/core/keys.ts

@@ -0,0 +1,86 @@
+import {
+  type KeyAlgorithm,
+  type PrivateKey,
+  type PublicKey,
+  type SymmetricKey,
+} from '../declarations.js';
+
+/**
+ * Wrap a CryptoKey as an opaque PublicKey.
+ * @internal
+ */
+export function wrapPublicKey(key: CryptoKey, algorithm: KeyAlgorithm): PublicKey {
+  const result: any = {
+    _brand: 'PublicKey',
+    algorithm,
+    _internal: key,
+  };
+  if (algorithm.startsWith('rsa:')) {
+    result.modulusBits = parseInt(algorithm.split(':')[1], 10);
+  } else if (algorithm.startsWith('ec:')) {
+    const curvePart = algorithm.split(':')[1];
+    result.curve =
+      curvePart === 'secp256r1'
+        ? 'P-256'
+        : curvePart === 'secp384r1'
+          ? 'P-384'
+          : curvePart === 'secp521r1'
+            ? 'P-521'
+            : undefined;
+  }
+  return result as PublicKey;
+}
+
+/**
+ * Wrap a CryptoKey as an opaque PrivateKey.
+ * @internal
+ */
+export function wrapPrivateKey(key: CryptoKey, algorithm: KeyAlgorithm): PrivateKey {
+  const result: any = {
+    _brand: 'PrivateKey',
+    algorithm,
+    _internal: key,
+  };
+  if (algorithm.startsWith('rsa:')) {
+    result.modulusBits = parseInt(algorithm.split(':')[1], 10);
+  } else if (algorithm.startsWith('ec:')) {
+    const curvePart = algorithm.split(':')[1];
+    result.curve =
+      curvePart === 'secp256r1'
+        ? 'P-256'
+        : curvePart === 'secp384r1'
+          ? 'P-384'
+          : curvePart === 'secp521r1'
+            ? 'P-521'
+            : undefined;
+  }
+  return result as PrivateKey;
+}
+
+/**
+ * Unwrap an opaque key to get the internal CryptoKey.
+ * @internal
+ */
+export function unwrapKey(key: PublicKey | PrivateKey): CryptoKey {
+  return (key as any)._internal;
+}
+
+/**
+ * Wrap raw key bytes as an opaque SymmetricKey.
+ * @internal
+ */
+export function wrapSymmetricKey(keyBytes: Uint8Array): SymmetricKey {
+  return {
+    _brand: 'SymmetricKey',
+    length: keyBytes.length * 8, // bits
+    _internal: keyBytes,
+  } as SymmetricKey;
+}
+
+/**
+ * Unwrap an opaque SymmetricKey to get raw bytes.
+ * @internal
+ */
+export function unwrapSymmetricKey(key: SymmetricKey): Uint8Array {
+  return (key as any)._internal;
+}