@noble/post-quantum 0.6.1 → 0.7.1

package/src/utils.ts

@@ -8,7 +8,11 @@ import {
   type TypedArray,
   abytes,
   abytes as abytes_,
+  ahash as ahash_,
+  anumber,
+  bytesToHex,
   concatBytes,
+  isBytes,
   isLE,
   randomBytes as randb,
 } from '@noble/hashes/utils.js';
@@ -158,9 +162,30 @@ export { concatBytesDoc as concatBytes };
  */
 export const randomBytes: typeof randb = randb;
 
+export function aarray<T>(
+  item: unknown,
+  title: string,
+  inner: (elm: T, title: string) => void = () => {}
+): T[] {
+  if (!Array.isArray(item))
+    throw new TypeError(`"${title}" expected array, got type=${typeof item}`);
+  for (let i = 0; i < item.length; i++) inner(item[i], `${title}[${i}]`);
+  return item;
+}
+
+export function aobject<T extends object>(value: unknown, title = 'object'): T {
+  if (value === null || typeof value !== 'object' || Array.isArray(value))
+    throw new TypeError(
+      title === 'object'
+        ? 'expected valid options object'
+        : `"${title}" expected object, got type=${typeof value}`
+    );
+  return value as T;
+}
+
 /**
  * Compares two byte arrays in a length-constant way for equal lengths.
- * Unequal lengths return `false` immediately, and there is no runtime type validation.
+ * Inputs are validated as byte arrays; unequal lengths return `false` immediately.
  * @param a - First byte array.
  * @param b - Second byte array.
  * @returns Whether both arrays contain the same bytes.
@@ -171,6 +196,8 @@ export const randomBytes: typeof randb = randb;
  * ```
  */
 export function equalBytes(a: TArg<Uint8Array>, b: TArg<Uint8Array>): boolean {
+  a = abytes(a);
+  b = abytes(b);
   if (a.length !== b.length) return false;
   let diff = 0;
   for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
@@ -189,9 +216,10 @@ export function equalBytes(a: TArg<Uint8Array>, b: TArg<Uint8Array>): boolean {
  * ```
  */
 export function copyBytes(bytes: TArg<Uint8Array>): TRet<Uint8Array> {
-  // `Uint8Array.from(...)` would also accept arrays / other typed arrays. Keep this helper strict
-  // because callers use it at byte-validation boundaries before mutating the detached copy.
-  return Uint8Array.from(abytes(bytes)) as TRet<Uint8Array>;
+  // The typed-array constructor copies a typed-array source through its internal byte storage.
+  // Unlike `Uint8Array.from`, it does not invoke a subclass-overridden iterator. Keep the explicit
+  // validation because the constructor itself would also accept arrays and other typed arrays.
+  return new Uint8Array(abytes(bytes)) as TRet<Uint8Array>;
 }
 
 /**
@@ -287,8 +315,68 @@ export type SigOpts = VerOpts & {
  */
 export function validateOpts(opts: object): void {
   // Arrays silently passed here before, but these call sites expect named option-bag fields.
-  if (Object.prototype.toString.call(opts) !== '[object Object]')
-    throw new TypeError('expected valid options object');
+  if (isBytes(opts)) throw new TypeError('"opts" expected object, got Uint8Array');
+  aobject(opts, 'opts');
+  const proto = Object.getPrototypeOf(opts);
+  // Options are security parameters, not general class instances. Restricting the bag to own
+  // properties prevents values injected through Object.prototype (or a custom shared prototype)
+  // from silently changing signing behavior. Null-prototype records remain supported.
+  if (proto !== null && proto !== Object.prototype)
+    throw new TypeError('"opts" expected a plain object');
+}
+
+// Frozen because they are exported: an unfrozen array export lets anything in the
+// process push a key onto the accepted set and silently re-open exactly the hole this
+// validation closes.
+/** Keys accepted by `verify`. */
+export const VER_OPT_KEYS: readonly ['context'] = /* @__PURE__ */ Object.freeze([
+  'context',
+] as const);
+/** Keys accepted by `sign`. */
+export const SIG_OPT_KEYS: readonly ['context', 'extraEntropy'] = /* @__PURE__ */ Object.freeze([
+  'context',
+  'extraEntropy',
+] as const);
+
+/**
+ * Rejects option keys the caller did not mean to set.
+ *
+ * Validating the types of known keys while ignoring unknown ones makes a typo
+ * indistinguishable from an omission, and for these options an omission is a
+ * security downgrade rather than a no-op: `{ ctx }` instead of `{ context }` signs
+ * with no domain separation, succeeds, and verifies for anyone who also supplies
+ * none. Nothing at any layer reports it. TypeScript catches this through excess
+ * property checks, so the exposure is JavaScript callers specifically.
+ *
+ * @param opts - Options object to check.
+ * @param allowed - The keys this call site accepts.
+ * Returns a frozen null-prototype snapshot so later reads cannot fall through to a polluted
+ * prototype. Like `checkOpts()` in noble-hashes, only enumerable own properties are copied.
+ * @throws If any other copied key is present or the bag has a custom prototype. {@link TypeError}
+ * @returns Sanitized snapshot of the enumerable own options.
+ * @example
+ * Accept a known option key. A key the list does not name, such as `ctx`, throws instead.
+ * ```ts
+ * import { checkOptKeys } from '@noble/post-quantum/utils.js';
+ * checkOptKeys({ context: new Uint8Array() }, ['context']);
+ * ```
+ */
+export function checkOptKeys<T extends object>(opts: T, allowed: readonly string[]): T {
+  validateOpts(opts);
+  // Snapshot once before validation: Object.assign follows the same own-enumerable option-bag
+  // semantics as noble-hashes, while the null prototype keeps omitted fields immune to pollution.
+  const normalized = Object.assign(Object.create(null), opts) as Record<string, unknown>;
+  for (const [k, v] of Object.entries(normalized)) {
+    // `undefined` means unset everywhere else in these validators, and building an options bag by
+    // spread is a normal way to reach these calls, so present-but-undefined stays equivalent to
+    // omission.
+    if (v === undefined) continue;
+    if (!allowed.includes(k))
+      throw new TypeError(
+        'unexpected option "' + String(k) + '"; expected one of: ' + allowed.join(', ')
+      );
+  }
+  return Object.freeze(normalized) as T;
 }
 
 /**
@@ -296,16 +384,23 @@ export function validateOpts(opts: object): void {
  * `context` itself is validated with `abytes(...)`, and individual algorithms may narrow support
  * further after this shared plain-object gate.
  * @param opts - Verification options. See {@link VerOpts}.
+ * @param allowed - Keys this call site accepts. Defaults to {@link VER_OPT_KEYS}; surfaces that
+ * take extra keys, or take fewer, pass their own list.
  * @throws On wrong argument types. {@link TypeError}
+ * @returns Frozen null-prototype snapshot of the validated options.
  * @example
  * Validate common verification options.
  * ```ts
  * validateVerOpts({ context: new Uint8Array([1]) });
  * ```
  */
-export function validateVerOpts(opts: TArg<VerOpts>): void {
-  validateOpts(opts);
-  if (opts.context !== undefined) abytes(opts.context, undefined, 'opts.context');
+export function validateVerOpts<T extends TArg<VerOpts>>(
+  opts: T,
+  allowed: readonly string[] = VER_OPT_KEYS
+): T {
+  const normalized = checkOptKeys(opts, allowed);
+  if (normalized.context !== undefined) abytes(normalized.context, undefined, 'opts.context');
+  return normalized;
 }
 
 /**
@@ -313,17 +408,25 @@ export function validateVerOpts(opts: TArg<VerOpts>): void {
  * `extraEntropy` is validated with `abytes(...)`; exact lengths and extra algorithm-specific
  * restrictions are enforced later by callers.
  * @param opts - Signing options. See {@link SigOpts}.
+ * @param allowed - Keys this call site accepts. Defaults to {@link SIG_OPT_KEYS}; surfaces that
+ * take extra keys, or take fewer, pass their own list.
  * @throws On wrong argument types. {@link TypeError}
+ * @returns Frozen null-prototype snapshot of the validated options.
  * @example
  * Validate common signing options.
  * ```ts
  * validateSigOpts({ extraEntropy: new Uint8Array([1]) });
  * ```
  */
-export function validateSigOpts(opts: TArg<SigOpts>): void {
-  validateVerOpts(opts);
-  if (opts.extraEntropy !== false && opts.extraEntropy !== undefined)
-    abytes(opts.extraEntropy, undefined, 'opts.extraEntropy');
+export function validateSigOpts<T extends TArg<SigOpts>>(
+  opts: T,
+  allowed: readonly string[] = SIG_OPT_KEYS
+): T {
+  const normalized = checkOptKeys(opts, allowed);
+  if (normalized.context !== undefined) abytes(normalized.context, undefined, 'opts.context');
+  if (normalized.extraEntropy !== false && normalized.extraEntropy !== undefined)
+    abytes(normalized.extraEntropy, undefined, 'opts.extraEntropy');
+  return normalized;
 }
 
 /** Generic signature interface with key generation, signing, and verification. */
@@ -503,11 +606,12 @@ export function vecCoder<T>(c: TArg<BytesCoderLen<T>>, vecLen: number): TRet<Byt
   return {
     bytesLen,
     encode: (u: TArg<T[]>): TRet<Uint8Array> => {
-      if (u.length !== vecLen)
-        throw new RangeError(`vecCoder.encode: wrong length=${u.length}. Expected: ${vecLen}`);
+      const uArr = aarray<T>(u, 'u');
+      if (uArr.length !== vecLen)
+        throw new RangeError(`vecCoder.encode: wrong length=${uArr.length}. Expected: ${vecLen}`);
       const res = new Uint8Array(bytesLen);
-      for (let i = 0, pos = 0; i < u.length; i++) {
-        const b = coder.encode(u[i] as T);
+      for (let i = 0, pos = 0; i < uArr.length; i++) {
+        const b = coder.encode(uArr[i] as T);
         res.set(b, pos);
         b.fill(0); // clean
         pos += b.length;
@@ -546,6 +650,7 @@ export function cleanBytes(...list: (TypedArray | TypedArray[])[]): void {
  * Creates a 32-bit mask with the lowest `bits` bits set.
  * @param bits - Number of low bits to keep.
  * @returns Bit mask with `bits` ones.
+ * @throws On wrong argument types. {@link TypeError}
  * @throws On wrong argument ranges or values. {@link RangeError}
  * @example
  * Create a low-bit mask for packed-field operations.
@@ -554,8 +659,8 @@ export function cleanBytes(...list: (TypedArray | TypedArray[])[]): void {
  * ```
  */
 export function getMask(bits: number): number {
-  if (!Number.isSafeInteger(bits) || bits < 0 || bits > 32)
-    throw new RangeError(`expected bits in [0..32], got ${bits}`);
+  anumber(bits, 'bits');
+  if (bits > 32) throw new RangeError('"bits" expected <= 32, got ' + bits);
   // JS shifts are modulo 32, so bit 32 needs an explicit full-width mask.
   return bits === 32 ? 0xffffffff : ~(-1 << bits) >>> 0;
 }
@@ -577,8 +682,8 @@ export const EMPTY: TRet<Uint8Array> = /* @__PURE__ */ Uint8Array.of();
  * ```
  */
 export function getMessage(msg: TArg<Uint8Array>, ctx: TArg<Uint8Array> = EMPTY): TRet<Uint8Array> {
-  abytes_(msg);
-  abytes_(ctx);
+  abytes_(msg, undefined, 'msg');
+  abytes_(ctx, undefined, 'ctx');
   if (ctx.length > 255) throw new RangeError('context should be 255 bytes or less');
   return concatBytes(new Uint8Array([0, ctx.length]), ctx, msg);
 }
@@ -589,6 +694,20 @@ export function getMessage(msg: TArg<Uint8Array>, ctx: TArg<Uint8Array> = EMPTY)
 // 06 09 60 86 48 01 65 03 04 02
 const oidNistP = /* @__PURE__ */ Uint8Array.from([6, 9, 0x60, 0x86, 0x48, 1, 0x65, 3, 4, 2]);
 
+/**
+ * Output length, in bytes, that each XOF OID under this arc denotes.
+ *
+ * Unlike a fixed hash, an XOF's OID is a promise about the digest length: RFC 8702
+ * defines id-shake128 as SHAKE128 with 256-bit output and id-shake256 as SHAKE256 with
+ * 512-bit output, and FIPS 204 / FIPS 205 use exactly those pairings for pre-hash. Both
+ * bare noble-hashes defaults are half these values, so neither can be signed under its
+ * own OID.
+ */
+const XOF_OID_OUTPUT_LEN: Record<string, number> = /* @__PURE__ */ (() => ({
+  '060960864801650304020b': 32, // id-shake128, SHAKE128(M, 256)
+  '060960864801650304020c': 64, // id-shake256, SHAKE256(M, 512)
+}))();
+
 /**
  * Validates that a hash exposes a NIST hash OID and enough collision resistance.
  * Current accepted surface is broader than the FIPS algorithm tables: any hash/XOF under the NIST
@@ -607,11 +726,31 @@ const oidNistP = /* @__PURE__ */ Uint8Array.from([6, 9, 0x60, 0x86, 0x48, 1, 0x6
  * ```
  */
 export function checkHash(hash: CHash, requiredStrength: number = 0): void {
-  if (!hash.oid || !equalBytes(hash.oid.subarray(0, 10), oidNistP))
-    throw new Error('hash.oid is invalid: expected NIST hash');
+  if (typeof hash !== 'function' || typeof (hash as any).create !== 'function')
+    throw new TypeError('"hash" expected hash function, got type=' + typeof hash);
+  ahash_(hash);
+  anumber(requiredStrength, 'requiredStrength');
+  const oid = hash.oid as unknown as TArg<Uint8Array>;
+  abytes_(oid, undefined, 'hash.oid');
+  if (!equalBytes(oid.subarray(0, 10), oidNistP))
+    throw new Error('"hash.oid" is invalid: expected NIST hash');
   // FIPS 204 / FIPS 205 require both collision and second-preimage strength; for approved NIST
   // hashes/XOFs under this OID subtree, the collision bound from the configured digest length is
   // the tighter runtime check, so enforce that lower bound here.
+  // XOFs under this arc are identified by an OID that fixes their output length:
+  // FIPS 204 §5.4.1 (SHAKE128) and FIPS 205 §10.2.2 (both SHAKEs), matching RFC 8702, pair
+  // id-shake128 with SHAKE128(M, 256) and id-shake256 with SHAKE256(M, 512). getMessagePrehash embeds
+  // hash.oid beside hash(msg), so a shorter digest signs an M' that claims a length
+  // it does not have: noble-hashes' bare shake256 defaults to 32 bytes and cleared
+  // the collision bound at the 128-bit level, producing signatures a conformant
+  // verifier rejects because it recomputes 512 bits. Check the length the OID
+  // denotes rather than the generic bound.
+  const xofLen = XOF_OID_OUTPUT_LEN[bytesToHex(oid as Uint8Array)];
+  if (xofLen !== undefined && hash.outputLen !== xofLen) {
+    throw new Error(
+      'Pre-hash XOF output length must be ' + xofLen + ' bytes for this OID, got: ' + hash.outputLen
+    );
+  }
   const collisionResistance = (hash.outputLen * 8) / 2;
   if (requiredStrength > collisionResistance) {
     throw new Error(
@@ -646,9 +785,31 @@ export function getMessagePrehash(
   msg: TArg<Uint8Array>,
   ctx: TArg<Uint8Array> = EMPTY
 ): TRet<Uint8Array> {
-  abytes_(msg);
-  abytes_(ctx);
+  checkHash(hash);
+  abytes_(msg, undefined, 'msg');
+  abytes_(ctx, undefined, 'ctx');
   if (ctx.length > 255) throw new RangeError('context should be 255 bytes or less');
   const hashed = hash(msg);
   return concatBytes(new Uint8Array([1, ctx.length]), ctx, hash.oid!, hashed);
 }
+
+/**
+ * Asserts something is a string.
+ * @param value - Value to validate.
+ * @param title - Label included in thrown errors.
+ * @returns The validated string.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate a label string.
+ *
+ * ```ts
+ * astring('example', 'label');
+ * ```
+ */
+export function astring(value: unknown, title: string = ''): string {
+  if (typeof value !== 'string') {
+    const prefix = title && `"${title}" `;
+    throw new TypeError(prefix + 'expected string, got type=' + typeof value);
+  }
+  return value;
+}

package/src/webcrypto.ts

@@ -0,0 +1,322 @@
+/**
+ * Friendly async wrappers over ML-KEM and ML-KEM-768 + X25519 from built-in WebCrypto.
+ * Private keys use the same raw seed accepted by the synchronous implementations' `keygen(seed)`;
+ * they are not expanded decapsulation keys.
+ *
+ * # WebCrypto quirks
+ *
+ * - The algorithms are experimental: a runtime can expose `encapsulateBits` and friends while
+ *   implementing none of them, so support is probed with a full round-trip in `isSupported()`.
+ * - `MLKEM768-X25519` accepts `raw-seed` on import, but has no `raw-seed` / `raw-public` export.
+ *   Its key bytes are read out of the JWK `priv` / `pub` members instead.
+ * - base64url is hand-rolled: scure-base's `base64urlnopad` would do, but this module must not add
+ *   dependencies, and importing the synchronous implementations for four byte lengths would pull
+ *   the whole lattice math into a WebCrypto-only entrypoint.
+ * @module
+ */
+/*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
+import { abytes, cleanBytes, copyBytes, equalBytes, type TArg, type TRet } from './utils.ts';
+
+function _subtle(): any {
+  const cr = typeof globalThis === 'object' ? (globalThis as any).crypto : null;
+  const sb = cr?.subtle;
+  if (typeof sb === 'object' && sb != null) return sb;
+  throw new Error('crypto.subtle must be defined');
+}
+
+type MLKEMName = 'ML-KEM-512' | 'ML-KEM-768' | 'ML-KEM-1024';
+
+const PRIVATE_USAGES = ['decapsulateBits'];
+const PUBLIC_USAGES = ['encapsulateBits'];
+const ALL_USAGES = ['encapsulateBits', 'decapsulateBits'];
+const PROBED_METHODS = ['encapsulateBits', 'decapsulateBits', 'getPublicKey'];
+const SHARED_SECRET_LENGTH = 32;
+const arrayBufferByteLength = Object.getOwnPropertyDescriptor(
+  ArrayBuffer.prototype,
+  'byteLength'
+)?.get;
+
+// Typed-array constructors also accept numbers and array-like objects, which would turn malformed
+// provider results into newly allocated all-zero buffers. Use the intrinsic getter as a cross-realm
+// ArrayBuffer brand check before constructing a view.
+function providerBytes(value: unknown, title: string): TRet<Uint8Array> {
+  try {
+    if (arrayBufferByteLength === undefined) throw new TypeError('missing ArrayBuffer getter');
+    arrayBufferByteLength.call(value);
+  } catch {
+    throw new TypeError(`WebCrypto "${title}" expected ArrayBuffer`);
+  }
+  return new Uint8Array(value as ArrayBuffer) as TRet<Uint8Array>;
+}
+
+/** Byte lengths for a WebCrypto wrapper's serialized keys and ciphertexts. */
+type KEMLengths = {
+  /** Deterministic key-generation seed length. */
+  seed: number;
+  /**
+   * Raw seed private-key length. Note this is the *seed*, not the expanded decapsulation key:
+   * for ML-KEM the synchronous `lengths.secretKey` is much larger (1632 / 2400 / 3168 bytes), so
+   * these private keys only fit the synchronous `keygen(seed)`, never its `decapsulate(ct, sk)`.
+   */
+  secretKey: number;
+  /** Serialized public-key length. */
+  publicKey: number;
+  /** Encapsulated ciphertext length. */
+  cipherText: number;
+};
+
+/** Strategy for serializing keys, which differs between the raw and JWK-only algorithms. */
+type KeyCodec = {
+  importPublic(subtle: any, algorithm: any, publicKey: TArg<Uint8Array>): Promise<any>;
+  exportPublic(subtle: any, key: any, length: number): Promise<TRet<Uint8Array>>;
+  exportPrivate(subtle: any, key: any, length: number): Promise<TRet<Uint8Array>>;
+};
+
+/** Async KEM interface backed by the current runtime's WebCrypto implementation. */
+export type WebCryptoKEM = {
+  /** WebCrypto algorithm name passed to `crypto.subtle`. */
+  webCryptoName: string;
+  /** Byte lengths for this WebCrypto wrapper's serialized keys and ciphertexts. */
+  lengths: KEMLengths;
+  /**
+   * Checks whether the runtime implements the complete WebCrypto surface used by this wrapper.
+   * Probes with a real key generation and encapsulation round-trip, and memoizes the result.
+   * @returns Whether key generation, serialization, encapsulation, and decapsulation are supported.
+   */
+  isSupported(): Promise<boolean>;
+  /**
+   * Generates a KEM key pair.
+   * @param seed - Optional raw seed for deterministic key generation.
+   * @returns Raw seed private key and serialized public key.
+   */
+  keygen(seed?: TArg<Uint8Array>): TRet<Promise<{ secretKey: Uint8Array; publicKey: Uint8Array }>>;
+  /**
+   * Derives a serialized public key from a raw seed private key.
+   * @param secretKey - Raw seed private key.
+   * @returns Serialized public key.
+   */
+  getPublicKey(secretKey: TArg<Uint8Array>): TRet<Promise<Uint8Array>>;
+  /**
+   * Encapsulates a new random shared secret to a serialized public key.
+   * @param publicKey - Recipient public key.
+   * @returns Ciphertext and 32-byte shared secret.
+   */
+  encapsulate(
+    publicKey: TArg<Uint8Array>
+  ): TRet<Promise<{ cipherText: Uint8Array; sharedSecret: Uint8Array }>>;
+  /**
+   * Decapsulates a ciphertext with a raw seed private key.
+   * @param cipherText - Encapsulated ciphertext bytes.
+   * @param secretKey - Private key in WebCrypto `raw-seed` format.
+   * @returns Decapsulated 32-byte shared secret.
+   */
+  decapsulate(cipherText: TArg<Uint8Array>, secretKey: TArg<Uint8Array>): TRet<Promise<Uint8Array>>;
+};
+
+/** Async ML-KEM interface backed by the current runtime's WebCrypto implementation. */
+export type WebCryptoMLKEM = WebCryptoKEM & { webCryptoName: MLKEMName };
+
+function base64url(bytes: TArg<Uint8Array>): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return globalThis.btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function debase64url(value: unknown, title: string): TRet<Uint8Array> {
+  if (typeof value !== 'string') throw new Error(`WebCrypto JWK is missing ${title}`);
+  const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+  const padding = base64.length % 4;
+  const binary = globalThis.atob(base64 + (padding ? '='.repeat(4 - padding) : ''));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes as TRet<Uint8Array>;
+}
+
+/** Keys serialized through the `raw-seed` / `raw-public` WebCrypto formats. */
+const rawCodec: KeyCodec = {
+  importPublic: (subtle, algorithm, publicKey) =>
+    subtle.importKey('raw-public', publicKey, algorithm, false, PUBLIC_USAGES),
+  exportPublic: async (subtle, key, length) =>
+    abytes(new Uint8Array(await subtle.exportKey('raw-public', key)), length, 'publicKey'),
+  exportPrivate: async (subtle, key, length) =>
+    abytes(new Uint8Array(await subtle.exportKey('raw-seed', key)), length, 'secretKey'),
+};
+
+/** Keys serialized through the JWK `pub` / `priv` members, for algorithms without raw export. */
+function jwkCodec(webCryptoName: string): TRet<KeyCodec> {
+  const exportMember = async (subtle: any, key: any, member: 'priv' | 'pub', length: number) => {
+    const jwk = await subtle.exportKey('jwk', key);
+    return abytes(debase64url(jwk?.[member], member), length, member) as TRet<Uint8Array>;
+  };
+  return {
+    importPublic: (subtle, algorithm, publicKey) =>
+      subtle.importKey(
+        'jwk',
+        {
+          kty: 'AKP',
+          alg: webCryptoName,
+          key_ops: PUBLIC_USAGES,
+          ext: true,
+          pub: base64url(publicKey),
+        },
+        algorithm,
+        true,
+        PUBLIC_USAGES
+      ),
+    exportPublic: (subtle, key, length) => exportMember(subtle, key, 'pub', length),
+    exportPrivate: (subtle, key, length) => exportMember(subtle, key, 'priv', length),
+  };
+}
+
+function createWebCryptoKEM(
+  webCryptoName: string,
+  lengths: KEMLengths,
+  codec: KeyCodec
+): TRet<WebCryptoKEM> {
+  const algorithm = Object.freeze({ name: webCryptoName });
+  const frozen = Object.freeze(lengths);
+  let supported: boolean | undefined;
+
+  // Imports a raw seed, wiping the detached copy as soon as WebCrypto has consumed it.
+  const importSecret = async (subtle: any, secretKey: TArg<Uint8Array>) => {
+    const secret = copyBytes(abytes(secretKey, frozen.secretKey, 'secretKey'));
+    try {
+      return await subtle.importKey('raw-seed', secret, algorithm, false, PRIVATE_USAGES);
+    } finally {
+      cleanBytes(secret);
+    }
+  };
+
+  const getPublicKey = async (secretKey: TArg<Uint8Array>): Promise<TRet<Uint8Array>> => {
+    const subtle = _subtle();
+    const privateKey = await importSecret(subtle, secretKey);
+    const publicKey = await subtle.getPublicKey(privateKey, PUBLIC_USAGES);
+    return codec.exportPublic(subtle, publicKey, frozen.publicKey);
+  };
+
+  const keygen = async (seed?: TArg<Uint8Array>) => {
+    if (seed !== undefined) {
+      const secretKey = copyBytes(abytes(seed, frozen.seed, 'seed'));
+      try {
+        const publicKey = await getPublicKey(secretKey);
+        return { secretKey: secretKey as TRet<Uint8Array>, publicKey };
+      } catch (error) {
+        cleanBytes(secretKey);
+        throw error;
+      }
+    }
+    const subtle = _subtle();
+    const keys = await subtle.generateKey(algorithm, true, ALL_USAGES);
+    const [secretKey, publicKey] = await Promise.all([
+      codec.exportPrivate(subtle, keys.privateKey, frozen.secretKey),
+      codec.exportPublic(subtle, keys.publicKey, frozen.publicKey),
+    ]);
+    return { secretKey, publicKey };
+  };
+
+  const encapsulate = async (publicKey: TArg<Uint8Array>) => {
+    const subtle = _subtle();
+    // No copy: the bytes are public and WebCrypto consumes them before the next await.
+    const key = await codec.importPublic(
+      subtle,
+      algorithm,
+      abytes(publicKey, frozen.publicKey, 'publicKey')
+    );
+    const { ciphertext, sharedKey } = await subtle.encapsulateBits(algorithm, key);
+    // Provider outputs cross a trust boundary: some runtimes expose experimental methods with
+    // incomplete implementations. Materialize the secret first so every later rejection can wipe
+    // it, including a malformed ciphertext result.
+    const sharedSecret = providerBytes(sharedKey, 'sharedKey');
+    try {
+      const cipherText = abytes(
+        providerBytes(ciphertext, 'ciphertext'),
+        frozen.cipherText,
+        'cipherText'
+      ) as TRet<Uint8Array>;
+      abytes(sharedSecret, SHARED_SECRET_LENGTH, 'sharedSecret');
+      return { cipherText, sharedSecret: sharedSecret as TRet<Uint8Array> };
+    } catch (error) {
+      cleanBytes(sharedSecret);
+      throw error;
+    }
+  };
+
+  const decapsulate = async (
+    cipherText: TArg<Uint8Array>,
+    secretKey: TArg<Uint8Array>
+  ): Promise<TRet<Uint8Array>> => {
+    // Snapshot the ciphertext: the key import below awaits before WebCrypto reads these bytes.
+    const cipher = copyBytes(abytes(cipherText, frozen.cipherText, 'cipherText'));
+    const subtle = _subtle();
+    const key = await importSecret(subtle, secretKey);
+    const sharedSecret = providerBytes(
+      await subtle.decapsulateBits(algorithm, key, cipher),
+      'sharedKey'
+    );
+    try {
+      return abytes(sharedSecret, SHARED_SECRET_LENGTH, 'sharedSecret') as TRet<Uint8Array>;
+    } catch (error) {
+      cleanBytes(sharedSecret);
+      throw error;
+    }
+  };
+
+  return Object.freeze({
+    webCryptoName,
+    lengths: frozen,
+    async isSupported(): Promise<boolean> {
+      if (supported !== undefined) return supported;
+      let secretKey: Uint8Array | undefined;
+      let encapsulatedSecret: Uint8Array | undefined;
+      let decapsulatedSecret: Uint8Array | undefined;
+      try {
+        const subtle = _subtle();
+        for (const method of PROBED_METHODS)
+          if (typeof subtle[method] !== 'function') return (supported = false);
+        const generated = await keygen();
+        secretKey = generated.secretKey;
+        const { publicKey } = generated;
+        const encapsulated = await encapsulate(publicKey);
+        encapsulatedSecret = encapsulated.sharedSecret;
+        decapsulatedSecret = await decapsulate(encapsulated.cipherText, secretKey);
+        const ok =
+          equalBytes(await getPublicKey(secretKey), publicKey) &&
+          equalBytes(encapsulatedSecret, decapsulatedSecret);
+        return (supported = ok);
+      } catch {
+        return (supported = false);
+      } finally {
+        // A failed provider can throw at any point after producing secret material. Never let the
+        // support probe retain a generated seed or shared-secret output that it received.
+        if (secretKey !== undefined) cleanBytes(secretKey);
+        if (encapsulatedSecret !== undefined) cleanBytes(encapsulatedSecret);
+        if (decapsulatedSecret !== undefined) cleanBytes(decapsulatedSecret);
+      }
+    },
+    keygen,
+    getPublicKey,
+    encapsulate,
+    decapsulate,
+  }) as TRet<WebCryptoKEM>;
+}
+
+const mlKem = (name: MLKEMName, publicKey: number, cipherText: number) =>
+  createWebCryptoKEM(
+    name,
+    { seed: 64, secretKey: 64, publicKey, cipherText },
+    rawCodec
+  ) as TRet<WebCryptoMLKEM>;
+
+/** WebCrypto ML-KEM-512 wrapper. */
+export const ml_kem512: TRet<WebCryptoMLKEM> = /* @__PURE__ */ mlKem('ML-KEM-512', 800, 768);
+/** WebCrypto ML-KEM-768 wrapper. */
+export const ml_kem768: TRet<WebCryptoMLKEM> = /* @__PURE__ */ mlKem('ML-KEM-768', 1184, 1088);
+/** WebCrypto ML-KEM-1024 wrapper. */
+export const ml_kem1024: TRet<WebCryptoMLKEM> = /* @__PURE__ */ mlKem('ML-KEM-1024', 1568, 1568);
+
+/** WebCrypto ML-KEM-768 + X25519 (X-Wing) wrapper. */
+export const ml_kem768_x25519: TRet<WebCryptoKEM> = /* @__PURE__ */ createWebCryptoKEM(
+  'MLKEM768-X25519',
+  { seed: 32, secretKey: 32, publicKey: 1216, cipherText: 1120 },
+  /* @__PURE__ */ jwkCodec('MLKEM768-X25519')
+);