@vex-chat/crypto 2.0.0 → 2.1.0

package/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * 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 { hkdf } from "@noble/hashes/hkdf.js";
@@ -15,6 +21,247 @@ 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];
+
+/** 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 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);
+}
+
+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.
@@ -44,6 +291,7 @@ export class XUtils {
 
     /**
      * Checks if two buffer-like objects are equal.
+     * When lengths match, comparison is constant-time in the inputs (no early exit on first differing byte).
      *
      * @param buf1
      * @param buf2
@@ -59,12 +307,16 @@ export class XUtils {
         if (a.byteLength !== b.byteLength) {
             return false;
         }
+        let diff = 0;
         for (let i = 0; i !== a.byteLength; i++) {
-            if (a[i] !== b[i]) {
+            const x = a[i];
+            const y = b[i];
+            if (x === undefined || y === undefined) {
                 return false;
             }
+            diff |= x ^ y;
         }
-        return true;
+        return diff === 0;
     }
 
     /**
@@ -101,7 +353,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,
@@ -113,6 +365,37 @@ 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);
+    };
+
     /**
      * Returns the empty header (32 0's)
      *
@@ -135,21 +418,17 @@ export class XUtils {
     }
 
     /**
-   * Encrypts a secret key with a password and saves it as a file.
-   *
-   * @param path The path to save the keyfile.
-  /**
-   * Encrypts a secret key into a portable binary format.
-   * The result can be written to disk, sent over the network, etc.
-   * No I/O — the caller handles persistence.
-   *
-   * Format: [iterations(6)|salt(24)|nonce(24)|ciphertext(N)]
-   *
-   * @param password The password to derive the encryption key from.
-   * @param keyToSave The hex-encoded secret key to encrypt.
-   * @param iterationOverride Optional PBKDF2 iteration count (random if omitted).
-   * @returns The encrypted key data as a Uint8Array.
-   */
+     * Encrypts a secret key into a portable binary format.
+     * The result can be written to disk, sent over the network, etc.
+     * No I/O — the caller handles persistence.
+     *
+     * Format: [iterations(6)|salt(24)|nonce(24)|ciphertext(N)]
+     *
+     * @param password The password to derive the encryption key from.
+     * @param keyToSave The hex-encoded secret key to encrypt.
+     * @param iterationOverride Optional PBKDF2 iteration count (random if omitted).
+     * @returns The encrypted key data as a Uint8Array.
+     */
     public static encryptKeyData = (
         password: string,
         keyToSave: string,
@@ -157,7 +436,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
@@ -170,7 +449,7 @@ export class XUtils {
             dkLen: 32,
         });
         const NONCE = xMakeNonce();
-        const ENCRYPTED_SIGNKEY = nacl.secretbox(
+        const ENCRYPTED_SIGNKEY = provider().secretbox(
             UNENCRYPTED_SIGNKEY,
             NONCE,
             ENCRYPTION_KEY,
@@ -193,6 +472,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
@@ -219,7 +548,8 @@ export class XUtils {
     /**
      * Packs a javascript object and a 32 byte header into a vex message.
      *
-     * @param arr The array to convert.
+     * @param msg Message body (msgpack-serialized).
+     * @param header Optional 32-byte header; defaults to an empty header.
      * @returns the packed message.
      */
     public static packMessage(msg: unknown, header?: Uint8Array) {
@@ -244,9 +574,9 @@ export class XUtils {
 
     /**
      * Takes a vex message and unpacks it into its header and a javascript object
-     * respresentation of its body.
+     * representation of its body.
      *
-     * @param arr The array to convert.
+     * @param msg Full wire message (32-byte header + msgpack body).
      * @returns [32 byte header, message body]
      */
     public static unpackMessage(
@@ -323,10 +653,8 @@ export interface KeyPair {
 //     );
 // }
 
-/**
- * @ignore
- */
-interface XConstants {
+/** Shape of the {@link xConstants} runtime object. */
+export interface XConstants {
     CURVE: "X25519";
     HASH: "SHA-512";
     HEADER_SIZE: 32;
@@ -337,14 +665,52 @@ interface XConstants {
 
 /** 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);
 }
 
+/** Async box key restore from private key material. */
+export function xBoxKeyPairFromSecretAsync(
+    secretKey: Uint8Array,
+): Promise<KeyPair> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return Promise.resolve(xBoxKeyPairFromSecret(secretKey));
+    }
+    void secretKey;
+    return Promise.reject(
+        new Error(
+            'Crypto profile "fips" does not implement xBoxKeyPairFromSecretAsync yet.',
+        ),
+    );
+}
+
+// ── Key pair type ───────────────────────────────────────────────────────────
+
 /**
  * Concatanates multiple Uint8Arrays.
  *
@@ -370,6 +736,8 @@ export function xConcat(...arrays: Uint8Array[]): Uint8Array {
     return result;
 }
 
+// ── Key generation ─────────────────────────────────────────────────────────
+
 /**
  * Derives a shared Secret Key from a known private key and
  * a peer's known public key.
@@ -382,10 +750,27 @@ 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);
+}
 
 /**
  * Encode an X25519 or X448 public key PK into a byte sequence.
@@ -431,8 +816,6 @@ export function xEncode(
     return Uint8Array.from(bytes);
 }
 
-// ── Key generation ─────────────────────────────────────────────────────────
-
 /**
  * Hashes some data.
  *
@@ -443,6 +826,8 @@ export function xHash(data: Uint8Array) {
     return XUtils.encodeHex(sha512(data));
 }
 
+// ── Signing ────────────────────────────────────────────────────────────────
+
 export function xKDF(IKM: Uint8Array): Uint8Array {
     return hkdf(
         sha512,
@@ -457,23 +842,45 @@ 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);
 }
 
+// ── Symmetric encryption (XSalsa20-Poly1305) ──────────────────────────────
+
 /** 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);
+}
+
+// ── Random ─────────────────────────────────────────────────────────────────
+
+/** 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 +889,102 @@ 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 function xSignKeyPairFromSecretAsync(
+    secretKey: Uint8Array,
+): Promise<KeyPair> {
+    if (activeCryptoProfile === "tweetnacl") {
+        return Promise.resolve(xSignKeyPairFromSecret(secretKey));
+    }
+    void secretKey;
+    return Promise.reject(
+        new Error(
+            'Crypto profile "fips" does not implement xSignKeyPairFromSecretAsync yet.',
+        ),
+    );
 }
 
 /** Verify and open a signed message. Returns the original message, or null if verification fails. */
@@ -509,11 +992,86 @@ 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 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"],
+    );
 }
 
 /**
- * @ignore
+ * @internal
  */
 function isEven(value: bigint) {
     if (value % BigInt(2) === BigInt(0)) {
@@ -524,14 +1082,14 @@ function isEven(value: bigint) {
 }
 
 /**
- * @ignore
+ * @internal
  */
 function keyLength(curve: "X448" | "X25519"): number {
     return curve === "X25519" ? 32 : 57;
 }
 
 /**
- * @ignore
+ * @internal
  */
 function xMakeSalt(curve: "X448" | "X25519"): Uint8Array {
     const salt = new Uint8Array(keyLength(curve));