@vex-chat/crypto 2.0.1 → 2.1.1

package/src/index.ts

@@ -1,5 +1,14 @@
+/// <reference lib="dom" />
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
 import type { BaseMsg } from "@vex-chat/types";
 
+import { numberToBytesBE } from "@noble/curves/abstract/utils";
+import { p256 } from "@noble/curves/p256";
 import { hkdf } from "@noble/hashes/hkdf.js";
 import { hmac } from "@noble/hashes/hmac.js";
 import { pbkdf2 as noblePbkdf2 } from "@noble/hashes/pbkdf2.js";
@@ -15,6 +24,347 @@ import { Packr } from "msgpackr";
 import nacl from "tweetnacl";
 import { z } from "zod/v4";
 
+/** Runtime crypto profile selector. */
+export type CryptoProfile = "fips" | "tweetnacl";
+
+interface CryptoProvider {
+    boxBefore(myPrivateKey: Uint8Array, theirPublicKey: Uint8Array): Uint8Array;
+    boxKeyPair(): KeyPair;
+    boxKeyPairFromSecret(secretKey: Uint8Array): KeyPair;
+    profile: CryptoProfile;
+    randomBytes(length: number): Uint8Array;
+    secretbox(
+        plaintext: Uint8Array,
+        nonce: Uint8Array,
+        key: Uint8Array,
+    ): Uint8Array;
+    secretboxOpen(
+        ciphertext: Uint8Array,
+        nonce: Uint8Array,
+        key: Uint8Array,
+    ): null | Uint8Array;
+    sign(message: Uint8Array, secretKey: Uint8Array): Uint8Array;
+    signKeyPair(): KeyPair;
+    signKeyPairFromSecret(secretKey: Uint8Array): KeyPair;
+    signOpen(
+        signedMessage: Uint8Array,
+        publicKey: Uint8Array,
+    ): null | Uint8Array;
+}
+
+type WebCryptoKeyUsage =
+    | "decrypt"
+    | "deriveBits"
+    | "deriveKey"
+    | "encrypt"
+    | "sign"
+    | "unwrapKey"
+    | "verify"
+    | "wrapKey";
+
+interface WebCryptoLike {
+    getRandomValues: Crypto["getRandomValues"];
+    subtle: SubtleCrypto;
+}
+
+function getWebCrypto(): WebCryptoLike {
+    const cryptoCandidate: unknown = globalThis.crypto;
+    if (!isWebCryptoLike(cryptoCandidate)) {
+        throw new Error(
+            "Web Crypto API is not available in this runtime for fips profile operations.",
+        );
+    }
+    return cryptoCandidate;
+}
+
+function isWebCryptoLike(value: unknown): value is WebCryptoLike {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    return (
+        "getRandomValues" in value &&
+        typeof value.getRandomValues === "function" &&
+        "subtle" in value &&
+        typeof value.subtle === "object" &&
+        value.subtle !== null
+    );
+}
+
+function randomBytesWebCrypto(length: number): Uint8Array {
+    if (!Number.isInteger(length) || length < 0) {
+        throw new Error(
+            `Expected non-negative integer length, received ${String(length)}.`,
+        );
+    }
+    const cryptoImpl = getWebCrypto();
+    const result = new Uint8Array(length);
+    let offset = 0;
+    while (offset < length) {
+        const chunkLength = Math.min(65536, length - offset);
+        const chunk = result.subarray(offset, offset + chunkLength);
+        cryptoImpl.getRandomValues(chunk);
+        offset += chunkLength;
+    }
+    return result;
+}
+
+function unsupported(profile: CryptoProfile, operation: string): never {
+    throw new Error(
+        `Crypto profile "${profile}" does not implement ${operation} yet.`,
+    );
+}
+
+const tweetnaclProvider: CryptoProvider = {
+    boxBefore: (myPrivateKey, theirPublicKey) =>
+        nacl.box.before(theirPublicKey, myPrivateKey),
+    boxKeyPair: () => nacl.box.keyPair(),
+    boxKeyPairFromSecret: (secretKey) =>
+        nacl.box.keyPair.fromSecretKey(secretKey),
+    profile: "tweetnacl",
+    randomBytes: (length) => nacl.randomBytes(length),
+    secretbox: (plaintext, nonce, key) => nacl.secretbox(plaintext, nonce, key),
+    secretboxOpen: (ciphertext, nonce, key) =>
+        nacl.secretbox.open(ciphertext, nonce, key),
+    sign: (message, secretKey) => nacl.sign(message, secretKey),
+    signKeyPair: () => nacl.sign.keyPair(),
+    signKeyPairFromSecret: (secretKey) =>
+        nacl.sign.keyPair.fromSecretKey(secretKey),
+    signOpen: (signedMessage, publicKey) =>
+        nacl.sign.open(signedMessage, publicKey),
+};
+
+const fipsProvider: CryptoProvider = {
+    boxBefore: (myPrivateKey, theirPublicKey) => {
+        void myPrivateKey;
+        void theirPublicKey;
+        return unsupported("fips", "xDH");
+    },
+    boxKeyPair: () => unsupported("fips", "xBoxKeyPair"),
+    boxKeyPairFromSecret: (secretKey) => {
+        void secretKey;
+        return unsupported("fips", "xBoxKeyPairFromSecret");
+    },
+    profile: "fips",
+    randomBytes: (length) => randomBytesWebCrypto(length),
+    secretbox: (plaintext, nonce, key) => {
+        void plaintext;
+        void nonce;
+        void key;
+        return unsupported("fips", "xSecretbox");
+    },
+    secretboxOpen: (ciphertext, nonce, key) => {
+        void ciphertext;
+        void nonce;
+        void key;
+        return unsupported("fips", "xSecretboxOpen");
+    },
+    sign: (message, secretKey) => {
+        void message;
+        void secretKey;
+        return unsupported("fips", "xSign");
+    },
+    signKeyPair: () => unsupported("fips", "xSignKeyPair"),
+    signKeyPairFromSecret: (secretKey) => {
+        void secretKey;
+        return unsupported("fips", "xSignKeyPairFromSecret");
+    },
+    signOpen: (signedMessage, publicKey) => {
+        void signedMessage;
+        void publicKey;
+        return unsupported("fips", "xSignOpen");
+    },
+};
+
+const providers: Record<CryptoProfile, CryptoProvider> = {
+    fips: fipsProvider,
+    tweetnacl: tweetnaclProvider,
+};
+
+let activeCryptoProfile: CryptoProfile = "tweetnacl";
+let activeCryptoProvider: CryptoProvider = providers[activeCryptoProfile];
+
+/** `globalThis` may omit `Buffer` in browsers; Node types can still attach `Buffer` to `globalThis` unconditionally. */
+type NodeBufferish = {
+    from(data: ArrayBuffer | Uint8Array): {
+        toString(encoding: "base64url"): string;
+    };
+};
+
+/** Returns the currently configured crypto profile. */
+export function getCryptoProfile(): CryptoProfile {
+    return activeCryptoProfile;
+}
+
+/**
+ * Sets the runtime crypto profile.
+ *
+ * `tweetnacl` preserves existing behavior.
+ * `fips` currently enables only backend-agnostic helpers; NaCl-coupled
+ * primitives throw until a FIPS backend implementation is wired in.
+ */
+export function setCryptoProfile(profile: CryptoProfile): void {
+    activeCryptoProfile = profile;
+    activeCryptoProvider = providers[profile];
+}
+
+function bytesToBase64Url(bytes: Uint8Array): string {
+    const BufferCtor = getNodeBufferCtor();
+    if (BufferCtor !== undefined) {
+        return BufferCtor.from(bytes).toString("base64url");
+    }
+    return globalThis
+        .btoa(String.fromCodePoint(...Array.from(bytes)))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+/g, "");
+}
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+
+function decodeFipsSignedMessage(signedMessage: Uint8Array): {
+    message: Uint8Array;
+    signature: Uint8Array;
+} {
+    if (signedMessage.length < 2) {
+        throw new Error(
+            "Invalid FIPS signed message: missing signature length prefix.",
+        );
+    }
+    const signatureLength =
+        (signedMessage[0] ?? 0) * 256 + (signedMessage[1] ?? 0);
+    const signatureStart = 2;
+    const signatureEnd = signatureStart + signatureLength;
+    if (signedMessage.length < signatureEnd) {
+        throw new Error(
+            "Invalid FIPS signed message: signature length exceeds message length.",
+        );
+    }
+    return {
+        message: signedMessage.slice(signatureEnd),
+        signature: signedMessage.slice(signatureStart, signatureEnd),
+    };
+}
+
+function encodeFipsSignedMessage(
+    signature: Uint8Array,
+    message: Uint8Array,
+): Uint8Array {
+    if (signature.length > 65535) {
+        throw new Error("FIPS signature too long to encode.");
+    }
+    const prefix = new Uint8Array(2);
+    prefix[0] = (signature.length >> 8) & 0xff;
+    prefix[1] = signature.length & 0xff;
+    return concatBytes(concatBytes(prefix, signature), message);
+}
+
+async function fipsEcdhKeyPairFrom32ByteSeed(
+    secretKey: Uint8Array,
+    subtle: SubtleCrypto,
+): Promise<KeyPair> {
+    if (secretKey.length !== 32) {
+        throw new Error(
+            "FIPS: expected a 32-byte IKM/seed for ECDH from-secret.",
+        );
+    }
+    const d = p256.utils.normPrivateKeyToScalar(Uint8Array.from(secretKey));
+    const d32 = numberToBytesBE(d, 32);
+    const rawPub = p256.getPublicKey(d, false);
+    if (rawPub[0] !== 0x04) {
+        throw new Error("FIPS: expected uncompressed P-256 public key.");
+    }
+    const jwk: JsonWebKey = {
+        crv: "P-256",
+        d: bytesToBase64Url(d32),
+        kty: "EC",
+        x: bytesToBase64Url(rawPub.subarray(1, 33)),
+        y: bytesToBase64Url(rawPub.subarray(33, 65)),
+    };
+    const ecdhPriv = await subtle.importKey(
+        "jwk",
+        jwk,
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        ["deriveBits"],
+    );
+    const ecdhPubJwk = await subtle.exportKey("jwk", ecdhPriv);
+    const ecdhPubJwkNoD: JsonWebKey = { ...ecdhPubJwk };
+    delete ecdhPubJwkNoD.d;
+    ecdhPubJwkNoD.key_ops = [];
+    const ecdhPub = await subtle.importKey(
+        "jwk",
+        ecdhPubJwkNoD,
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        [],
+    );
+    return {
+        publicKey: new Uint8Array(await subtle.exportKey("raw", ecdhPub)),
+        secretKey: new Uint8Array(await subtle.exportKey("pkcs8", ecdhPriv)),
+    };
+}
+
+async function fipsEcdhKeyPairFromPkcs8(
+    secretKey: Uint8Array,
+    subtle: SubtleCrypto,
+): Promise<KeyPair> {
+    const ecdhPriv = await subtle.importKey(
+        "pkcs8",
+        toBufferSource(secretKey),
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        ["deriveBits"],
+    );
+    const jwk = await subtle.exportKey("jwk", ecdhPriv);
+    const ecdhPubJwk: JsonWebKey = { ...jwk };
+    delete ecdhPubJwk.d;
+    ecdhPubJwk.key_ops = [];
+    const ecdhPub = await subtle.importKey(
+        "jwk",
+        ecdhPubJwk,
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        [],
+    );
+    return {
+        publicKey: new Uint8Array(await subtle.exportKey("raw", ecdhPub)),
+        secretKey: new Uint8Array(await subtle.exportKey("pkcs8", ecdhPriv)),
+    };
+}
+
+function getNodeBufferCtor(): NodeBufferish | undefined {
+    if (!("Buffer" in globalThis)) {
+        return undefined;
+    }
+    return (globalThis as { Buffer: NodeBufferish }).Buffer;
+}
+
+function getSubtleCrypto(): SubtleCrypto {
+    return getWebCrypto().subtle;
+}
+
+function provider(): CryptoProvider {
+    return activeCryptoProvider;
+}
+
+function requireAesGcmNonce(nonce: Uint8Array): Uint8Array {
+    if (nonce.length < 12) {
+        throw new Error(
+            `AES-GCM requires a nonce of at least 12 bytes, received ${String(nonce.length)}.`,
+        );
+    }
+    return nonce.slice(0, 12);
+}
+
+function toBufferSource(bytes: Uint8Array): ArrayBuffer {
+    return Uint8Array.from(bytes).buffer;
+}
+
 // msgpackr with useRecords:false emits standard msgpack (no nonstandard record extension).
 // moreTypes:false keeps the extension set to only what other decoders understand.
 // pack() returns Node Buffer (tight view) so consumers like axios send the correct bytes.
@@ -106,7 +456,7 @@ export class XUtils {
             c: ITERATIONS,
             dkLen: 32,
         });
-        const DECRYPTED_SIGNKEY = nacl.secretbox.open(
+        const DECRYPTED_SIGNKEY = provider().secretboxOpen(
             ENCRYPTED_KEY,
             ENCRYPTION_NONCE,
             DERIVED_KEY,
@@ -118,6 +468,66 @@ export class XUtils {
         return XUtils.encodeHex(DECRYPTED_SIGNKEY);
     };
 
+    /**
+     * Async variant of decryptKeyData for cross-runtime/FIPS backends.
+     * Supports both profile formats emitted by encryptKeyDataAsync.
+     */
+    public static decryptKeyDataAsync = async (
+        keyData: Uint8Array,
+        password: string,
+    ): Promise<string> => {
+        const ITERATIONS = XUtils.uint8ArrToNumber(keyData.slice(0, 6));
+        const PKBDF_SALT = keyData.slice(6, 30);
+        const ENCRYPTION_NONCE = keyData.slice(30, 54);
+        const ENCRYPTED_KEY = keyData.slice(54);
+        const DERIVED_KEY = noblePbkdf2(sha512, password, PKBDF_SALT, {
+            c: ITERATIONS,
+            dkLen: 32,
+        });
+        const decrypted =
+            activeCryptoProfile === "fips"
+                ? await xSecretboxOpenAsync(
+                      ENCRYPTED_KEY,
+                      ENCRYPTION_NONCE,
+                      DERIVED_KEY,
+                  )
+                : xSecretboxOpen(ENCRYPTED_KEY, ENCRYPTION_NONCE, DERIVED_KEY);
+
+        if (decrypted === null) {
+            throw new Error("Decryption failed. Wrong password?");
+        }
+        return XUtils.encodeHex(decrypted);
+    };
+
+    /**
+     * 32-byte AES-256 key for local at-rest encryption (e.g. sqlite) derived from
+     * identity `secretKey`. For `tweetnacl` this is the 32-byte X25519 private key.
+     * For `fips` the identity secret is PKCS#8; HKDF is applied so AES keys never
+     * equal the raw private key material.
+     */
+    public static deriveLocalAtRestAesKey(
+        identitySk: Uint8Array,
+        profile: CryptoProfile,
+    ): Uint8Array {
+        if (profile === "tweetnacl") {
+            if (identitySk.length < 32) {
+                throw new Error(
+                    "Expected at least 32 bytes of identity secret in tweetnacl mode.",
+                );
+            }
+            return identitySk.subarray(0, 32);
+        }
+        return new Uint8Array(
+            hkdf(
+                sha256,
+                identitySk,
+                new Uint8Array(0),
+                new TextEncoder().encode("vex:at-rest:2.1.0-fips"),
+                32,
+            ),
+        );
+    }
+
     /**
      * Returns the empty header (32 0's)
      *
@@ -158,7 +568,7 @@ export class XUtils {
     ): Uint8Array => {
         const UNENCRYPTED_SIGNKEY = XUtils.decodeHex(keyToSave);
         const OFFSET = 1000;
-        const rand = nacl.randomBytes(2);
+        const rand = provider().randomBytes(2);
         const [N1 = 0, N2 = 0] = rand;
         const iterations =
             iterationOverride !== undefined && iterationOverride !== 0
@@ -171,7 +581,7 @@ export class XUtils {
             dkLen: 32,
         });
         const NONCE = xMakeNonce();
-        const ENCRYPTED_SIGNKEY = nacl.secretbox(
+        const ENCRYPTED_SIGNKEY = provider().secretbox(
             UNENCRYPTED_SIGNKEY,
             NONCE,
             ENCRYPTION_KEY,
@@ -194,6 +604,56 @@ export class XUtils {
         return result;
     };
 
+    /**
+     * Async variant of encryptKeyData for cross-runtime/FIPS backends.
+     * Format remains [iterations(6)|salt(24)|nonce(24)|ciphertext(N)].
+     */
+    public static encryptKeyDataAsync = async (
+        password: string,
+        keyToSave: string,
+        iterationOverride?: number,
+    ): Promise<Uint8Array> => {
+        const UNENCRYPTED_SIGNKEY = XUtils.decodeHex(keyToSave);
+        const OFFSET = 1000;
+        const rand = xRandomBytes(2);
+        const [N1 = 0, N2 = 0] = rand;
+        const iterations =
+            iterationOverride !== undefined && iterationOverride !== 0
+                ? iterationOverride
+                : N1 * N2 + OFFSET;
+        const ITERATIONS = XUtils.numberToUint8Arr(iterations);
+        const PKBDF_SALT = xMakeNonce();
+        const ENCRYPTION_KEY = noblePbkdf2(sha512, password, PKBDF_SALT, {
+            c: iterations,
+            dkLen: 32,
+        });
+        const NONCE = xMakeNonce();
+        const ENCRYPTED_SIGNKEY =
+            activeCryptoProfile === "fips"
+                ? await xSecretboxAsync(
+                      UNENCRYPTED_SIGNKEY,
+                      NONCE,
+                      ENCRYPTION_KEY,
+                  )
+                : xSecretbox(UNENCRYPTED_SIGNKEY, NONCE, ENCRYPTION_KEY);
+
+        const result = new Uint8Array(
+            ITERATIONS.length +
+                PKBDF_SALT.length +
+                NONCE.length +
+                ENCRYPTED_SIGNKEY.length,
+        );
+        let offset = 0;
+        result.set(ITERATIONS, offset);
+        offset += ITERATIONS.length;
+        result.set(PKBDF_SALT, offset);
+        offset += PKBDF_SALT.length;
+        result.set(NONCE, offset);
+        offset += NONCE.length;
+        result.set(ENCRYPTED_SIGNKEY, offset);
+        return result;
+    };
+
     /**
      * Returns a six bit Uint8Array representation of an integer.
      * The integer must be positive, and it must be able to be stored
@@ -335,16 +795,91 @@ export interface XConstants {
     MIN_OTK_SUPPLY: number;
 }
 
+/**
+ * FIPS: `device.signKey` in the database is the P-256 ECDSA public key (SPKI),
+ * used for account/device signature verification. X3DH on the client expects
+ * the same curve point as Web Crypto "raw" P-256 ECDH public bytes for
+ * `importEcdhPublicKey`. This converts SPKI → raw without a private key.
+ */
+export async function fipsEcdhRawPublicKeyFromEcdsaSpkiAsync(
+    ecdsaSpki: Uint8Array,
+): Promise<Uint8Array> {
+    if (ecdsaSpki.length === 0) {
+        throw new Error("FIPS: empty ECDSA SPKI.");
+    }
+    const subtle = getSubtleCrypto();
+    const ecdsaPub = await importEcdsaPublicKey(ecdsaSpki);
+    const jwk = await subtle.exportKey("jwk", ecdsaPub);
+    if (
+        jwk.x === undefined ||
+        jwk.y === undefined ||
+        jwk.x.length === 0 ||
+        jwk.y.length === 0
+    ) {
+        throw new Error("FIPS: could not export ECDSA public as JWK.");
+    }
+    const ecdhJwk: JsonWebKey = { ...jwk };
+    delete ecdhJwk.d;
+    ecdhJwk.key_ops = [];
+    ecdhJwk.ext = true;
+    const ecdhPub = await subtle.importKey(
+        "jwk",
+        ecdhJwk,
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        [],
+    );
+    return new Uint8Array(await subtle.exportKey("raw", ecdhPub));
+}
+
 /** Generate a fresh X25519 box key pair. */
 export function xBoxKeyPair(): KeyPair {
-    return nacl.box.keyPair();
+    return provider().boxKeyPair();
+}
+
+/** Async box keypair generation for the active profile. */
+export async function xBoxKeyPairAsync(): Promise<KeyPair> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return xBoxKeyPair();
+    }
+    const subtle = getSubtleCrypto();
+    const pair = await subtle.generateKey(
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        ["deriveBits"],
+    );
+    return {
+        publicKey: new Uint8Array(
+            await subtle.exportKey("raw", pair.publicKey),
+        ),
+        secretKey: new Uint8Array(
+            await subtle.exportKey("pkcs8", pair.privateKey),
+        ),
+    };
 }
 
 /** Restore an X25519 box key pair from a 32-byte secret key. */
 export function xBoxKeyPairFromSecret(secretKey: Uint8Array): KeyPair {
-    return nacl.box.keyPair.fromSecretKey(secretKey);
+    return provider().boxKeyPairFromSecret(secretKey);
 }
 
+// ── Key pair type ───────────────────────────────────────────────────────────
+
+/** Async box key restore from private key material. */
+export async function xBoxKeyPairFromSecretAsync(
+    secretKey: Uint8Array,
+): Promise<KeyPair> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return xBoxKeyPairFromSecret(secretKey);
+    }
+    if (secretKey.length === 32) {
+        return fipsEcdhKeyPairFrom32ByteSeed(secretKey, getSubtleCrypto());
+    }
+    return fipsEcdhKeyPairFromPkcs8(secretKey, getSubtleCrypto());
+}
+
+// ── Key generation ─────────────────────────────────────────────────────────
+
 /**
  * Concatanates multiple Uint8Arrays.
  *
@@ -382,10 +917,76 @@ export function xDH(
     myPrivateKey: Uint8Array,
     theirPublicKey: Uint8Array,
 ): Uint8Array {
-    return nacl.box.before(theirPublicKey, myPrivateKey);
+    return provider().boxBefore(myPrivateKey, theirPublicKey);
 }
 
-// ── Key pair type ───────────────────────────────────────────────────────────
+/** Async DH for cross-runtime/FIPS backends. */
+export async function xDHAsync(
+    myPrivateKey: Uint8Array,
+    theirPublicKey: Uint8Array,
+): Promise<Uint8Array> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return xDH(myPrivateKey, theirPublicKey);
+    }
+    const subtle = getSubtleCrypto();
+    const privateKey = await importEcdhPrivateKey(myPrivateKey);
+    const publicKey = await importEcdhPublicKey(theirPublicKey);
+    const shared = await subtle.deriveBits(
+        { name: "ECDH", public: publicKey },
+        privateKey,
+        256,
+    );
+    return new Uint8Array(shared);
+}
+
+/**
+ * In `fips` mode only: derive a P-256 ECDH `KeyPair` (raw public + pkcs8 secret)
+ * from a P-256 ECDSA `KeyPair` (spki + pkcs8) using the same private scalar in Web Crypto.
+ * In `tweetnacl` mode, use `XKeyConvert.convertKeyPair` to map Ed25519 → X25519 instead.
+ */
+export async function xEcdhKeyPairFromEcdsaKeyPairAsync(
+    sign: KeyPair,
+): Promise<KeyPair> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return Promise.reject(
+            new Error(
+                'xEcdhKeyPairFromEcdsaKeyPairAsync is for crypto profile "fips" only. Use XKeyConvert.convertKeyPair in tweetnacl mode.',
+            ),
+        );
+    }
+    const subtle = getSubtleCrypto();
+    const ecdsaPriv = await importEcdsaPrivateKey(sign.secretKey);
+    const jwk = await subtle.exportKey("jwk", ecdsaPriv);
+    if (typeof jwk.d !== "string" || jwk.d.length === 0) {
+        throw new Error("FIPS: could not export ECDSA private as JWK.");
+    }
+    const ecdhJwk: JsonWebKey = { ...jwk, key_ops: ["deriveBits"] };
+    ecdhJwk.ext = true;
+    const ecdhPriv = await subtle.importKey(
+        "jwk",
+        ecdhJwk,
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        ["deriveBits"],
+    );
+    const ecdhPubJwk = await subtle.exportKey("jwk", ecdhPriv);
+    const ecdhPubJwkNoD: JsonWebKey = { ...ecdhPubJwk };
+    delete ecdhPubJwkNoD.d;
+    ecdhPubJwkNoD.key_ops = [];
+    const ecdhPub = await subtle.importKey(
+        "jwk",
+        ecdhPubJwkNoD,
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        [],
+    );
+    return {
+        publicKey: new Uint8Array(await subtle.exportKey("raw", ecdhPub)),
+        secretKey: new Uint8Array(await subtle.exportKey("pkcs8", ecdhPriv)),
+    };
+}
+
+// ── Signing ────────────────────────────────────────────────────────────────
 
 /**
  * Encode an X25519 or X448 public key PK into a byte sequence.
@@ -431,8 +1032,6 @@ export function xEncode(
     return Uint8Array.from(bytes);
 }
 
-// ── Key generation ─────────────────────────────────────────────────────────
-
 /**
  * Hashes some data.
  *
@@ -443,6 +1042,8 @@ export function xHash(data: Uint8Array) {
     return XUtils.encodeHex(sha512(data));
 }
 
+// ── Symmetric encryption (XSalsa20-Poly1305) ──────────────────────────────
+
 export function xKDF(IKM: Uint8Array): Uint8Array {
     return hkdf(
         sha512,
@@ -457,23 +1058,43 @@ export function xKDF(IKM: Uint8Array): Uint8Array {
  * Returns a 24 byte random nonce of cryptographic quality.
  */
 export function xMakeNonce(): Uint8Array {
-    return nacl.randomBytes(24);
+    return provider().randomBytes(24);
 }
 
+// ── Random ─────────────────────────────────────────────────────────────────
+
 /** Cryptographically secure random bytes. */
 export function xRandomBytes(length: number): Uint8Array {
-    return nacl.randomBytes(length);
+    return provider().randomBytes(length);
 }
 
-// ── Signing ────────────────────────────────────────────────────────────────
-
 /** Encrypt with a shared secret key. */
 export function xSecretbox(
     plaintext: Uint8Array,
     nonce: Uint8Array,
     key: Uint8Array,
 ): Uint8Array {
-    return nacl.secretbox(plaintext, nonce, key);
+    return provider().secretbox(plaintext, nonce, key);
+}
+
+/** Async authenticated encryption for cross-runtime/FIPS backends. */
+export async function xSecretboxAsync(
+    plaintext: Uint8Array,
+    nonce: Uint8Array,
+    key: Uint8Array,
+): Promise<Uint8Array> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return xSecretbox(plaintext, nonce, key);
+    }
+    const subtle = getSubtleCrypto();
+    const iv = requireAesGcmNonce(nonce);
+    const aesKey = await importAesKey(key, ["encrypt"]);
+    const ciphertext = await subtle.encrypt(
+        { iv: toBufferSource(iv), name: "AES-GCM" },
+        aesKey,
+        toBufferSource(plaintext),
+    );
+    return new Uint8Array(ciphertext);
 }
 
 /** Decrypt with a shared secret key. Returns null if authentication fails. */
@@ -482,26 +1103,97 @@ export function xSecretboxOpen(
     nonce: Uint8Array,
     key: Uint8Array,
 ): null | Uint8Array {
-    return nacl.secretbox.open(ciphertext, nonce, key);
+    return provider().secretboxOpen(ciphertext, nonce, key);
 }
 
-// ── Symmetric encryption (XSalsa20-Poly1305) ──────────────────────────────
+/** Async authenticated decryption for cross-runtime/FIPS backends. */
+export async function xSecretboxOpenAsync(
+    ciphertext: Uint8Array,
+    nonce: Uint8Array,
+    key: Uint8Array,
+): Promise<null | Uint8Array> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return xSecretboxOpen(ciphertext, nonce, key);
+    }
+    const subtle = getSubtleCrypto();
+    const iv = requireAesGcmNonce(nonce);
+    const aesKey = await importAesKey(key, ["decrypt"]);
+    try {
+        const plaintext = await subtle.decrypt(
+            { iv: toBufferSource(iv), name: "AES-GCM" },
+            aesKey,
+            toBufferSource(ciphertext),
+        );
+        return new Uint8Array(plaintext);
+    } catch {
+        return null;
+    }
+}
 
 /** Sign a message with an Ed25519 secret key. Returns signed message (64-byte signature prefix + message). */
 export function xSign(message: Uint8Array, secretKey: Uint8Array): Uint8Array {
-    return nacl.sign(message, secretKey);
+    return provider().sign(message, secretKey);
+}
+
+/** Async signing for cross-runtime/FIPS backends. */
+export async function xSignAsync(
+    message: Uint8Array,
+    secretKey: Uint8Array,
+): Promise<Uint8Array> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return xSign(message, secretKey);
+    }
+    const subtle = getSubtleCrypto();
+    const privateKey = await importEcdsaPrivateKey(secretKey);
+    const signature = new Uint8Array(
+        await subtle.sign(
+            { hash: "SHA-256", name: "ECDSA" },
+            privateKey,
+            toBufferSource(message),
+        ),
+    );
+    return encodeFipsSignedMessage(signature, message);
 }
 
 /** Generate a fresh Ed25519 signing key pair. */
 export function xSignKeyPair(): KeyPair {
-    return nacl.sign.keyPair();
+    return provider().signKeyPair();
 }
 
-// ── Random ─────────────────────────────────────────────────────────────────
+/** Async keypair generation for the active profile. */
+export async function xSignKeyPairAsync(): Promise<KeyPair> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return xSignKeyPair();
+    }
+    const subtle = getSubtleCrypto();
+    const pair = await subtle.generateKey(
+        { name: "ECDSA", namedCurve: "P-256" },
+        true,
+        ["sign", "verify"],
+    );
+    return {
+        publicKey: new Uint8Array(
+            await subtle.exportKey("spki", pair.publicKey),
+        ),
+        secretKey: new Uint8Array(
+            await subtle.exportKey("pkcs8", pair.privateKey),
+        ),
+    };
+}
 
 /** Restore an Ed25519 signing key pair from a 64-byte secret key. */
 export function xSignKeyPairFromSecret(secretKey: Uint8Array): KeyPair {
-    return nacl.sign.keyPair.fromSecretKey(secretKey);
+    return provider().signKeyPairFromSecret(secretKey);
+}
+
+/** Async restore of signing keypair for the active profile. */
+export async function xSignKeyPairFromSecretAsync(
+    secretKey: Uint8Array,
+): Promise<KeyPair> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return xSignKeyPairFromSecret(secretKey);
+    }
+    return fipsEcdsaKeyPairFromPkcs8(secretKey, getSubtleCrypto());
 }
 
 /** Verify and open a signed message. Returns the original message, or null if verification fails. */
@@ -509,7 +1201,104 @@ export function xSignOpen(
     signedMessage: Uint8Array,
     publicKey: Uint8Array,
 ): null | Uint8Array {
-    return nacl.sign.open(signedMessage, publicKey);
+    return provider().signOpen(signedMessage, publicKey);
+}
+
+/** Async verify/open for cross-runtime/FIPS backends. */
+export async function xSignOpenAsync(
+    signedMessage: Uint8Array,
+    publicKey: Uint8Array,
+): Promise<null | Uint8Array> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return xSignOpen(signedMessage, publicKey);
+    }
+    const subtle = getSubtleCrypto();
+    const parsed = decodeFipsSignedMessage(signedMessage);
+    const verifyKey = await importEcdsaPublicKey(publicKey);
+    const valid = await subtle.verify(
+        { hash: "SHA-256", name: "ECDSA" },
+        verifyKey,
+        toBufferSource(parsed.signature),
+        toBufferSource(parsed.message),
+    );
+    return valid ? parsed.message : null;
+}
+
+async function fipsEcdsaKeyPairFromPkcs8(
+    secretKey: Uint8Array,
+    subtle: SubtleCrypto,
+): Promise<KeyPair> {
+    const ecdsaPriv = await importEcdsaPrivateKey(secretKey);
+    const jwk = await subtle.exportKey("jwk", ecdsaPriv);
+    const ecdsaPubJwk: JsonWebKey = { ...jwk };
+    delete ecdsaPubJwk.d;
+    ecdsaPubJwk.key_ops = ["verify"];
+    const ecdsaPub = await subtle.importKey(
+        "jwk",
+        ecdsaPubJwk,
+        { name: "ECDSA", namedCurve: "P-256" },
+        true,
+        ["verify"],
+    );
+    return {
+        publicKey: new Uint8Array(await subtle.exportKey("spki", ecdsaPub)),
+        secretKey: Uint8Array.from(secretKey),
+    };
+}
+
+async function importAesKey(
+    key: Uint8Array,
+    usages: WebCryptoKeyUsage[],
+): Promise<CryptoKey> {
+    return getSubtleCrypto().importKey(
+        "raw",
+        toBufferSource(key),
+        { name: "AES-GCM" },
+        false,
+        usages,
+    );
+}
+
+async function importEcdhPrivateKey(secretKey: Uint8Array): Promise<CryptoKey> {
+    return getSubtleCrypto().importKey(
+        "pkcs8",
+        toBufferSource(secretKey),
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        ["deriveBits"],
+    );
+}
+
+async function importEcdhPublicKey(publicKey: Uint8Array): Promise<CryptoKey> {
+    return getSubtleCrypto().importKey(
+        "raw",
+        toBufferSource(publicKey),
+        { name: "ECDH", namedCurve: "P-256" },
+        true,
+        [],
+    );
+}
+
+async function importEcdsaPrivateKey(
+    secretKey: Uint8Array,
+): Promise<CryptoKey> {
+    return getSubtleCrypto().importKey(
+        "pkcs8",
+        toBufferSource(secretKey),
+        { name: "ECDSA", namedCurve: "P-256" },
+        true,
+        ["sign"],
+    );
+}
+
+async function importEcdsaPublicKey(publicKey: Uint8Array): Promise<CryptoKey> {
+    return getSubtleCrypto().importKey(
+        "spki",
+        toBufferSource(publicKey),
+        { name: "ECDSA", namedCurve: "P-256" },
+        true,
+        ["verify"],
+    );
 }
 
 /**