@reallyme/crypto 0.2.0 → 0.3.1

package/README.md

@@ -9,14 +9,13 @@ SPDX-License-Identifier: Apache-2.0
 [![npm](https://img.shields.io/npm/v/@reallyme/crypto?label=npm&color=2563eb)](https://www.npmjs.com/package/@reallyme/crypto)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/reallyme/crypto/blob/main/LICENSE)
 
-ReallyMe Crypto provides a platform-agnostic cryptography API for TypeScript,
-Rust, Swift, and Kotlin.
+`@reallyme/crypto` is the TypeScript SDK for ReallyMe Crypto. It provides typed,
+synchronous APIs for Node.js and browsers, with explicit JavaScript and
+package-owned WASM providers.
 
-Applications can implement cryptographic operations once and rely on identical
-algorithms, key formats, verification behavior, and protocol contracts across
-servers, browsers, iOS, Android, and WASM. Native platform providers are used
-where appropriate, while shared conformance vectors ensure byte-for-byte
-compatible behavior across every supported language.
+The package shares algorithm identifiers, byte formats, typed failures, and
+conformance vectors with the Rust, Swift, Kotlin, and Android SDKs. Availability
+is provider-specific; unsupported routes fail closed.
 
 ## Why
 
@@ -24,10 +23,9 @@ Modern cryptography APIs differ across platforms. Algorithms are exposed
 differently, key formats vary, providers have different capabilities, and error
 behavior is inconsistent.
 
-ReallyMe Crypto provides one consistent cryptography contract across every
-supported platform. The same application logic can be shared between backend
-services, mobile applications, and browsers without maintaining separate
-cryptographic implementations.
+ReallyMe Crypto makes platform differences explicit while preserving a stable
+contract for every supported route. Applications can share protocol logic
+without silently changing cryptographic providers.
 
 ## Installation
 
@@ -49,6 +47,11 @@ const digest = ReallyMeCrypto.hash(
 The API is synchronous. Signature verification throws `ReallyMeCryptoError` on
 invalid input rather than returning a boolean that can be accidentally ignored.
 
+KDF facade selectors are family-specific: `deriveKey` accepts only PBKDF2,
+`deriveHkdf` accepts only HKDF, and the JWA Concat KDF and KMAC methods accept
+their exact selectors. Argon2id uses the dedicated `deriveArgon2id` route with
+an immutable profile version rather than an iteration count.
+
 ## Post-Quantum and WASM
 
 Classical primitives are backed by pinned `@noble` packages. The primitives that
@@ -62,22 +65,36 @@ explicit provider object. Missing WASM providers fail closed with
 to the published `@reallyme/codec` package, so applications that use those
 helpers should also install the Codec WASM provider.
 
+JSON and protobuf JWKS ingress routes accept at most 1,024 keys. Encoded JWK
+and JWKS protobuf inputs are capped at one mebibyte before decoding, and an
+embedded canonical JCS value is capped at 8 KiB. These limits apply equally to
+the direct message adapters and byte-oriented helpers.
+
 ```ts
 import { readFileSync } from "node:fs";
 import { installReallyMeCodecWasmProvider } from "@reallyme/codec";
-import * as codecWasmProvider from "@reallyme/codec/wasm/reallyme_codec_wasm.js";
+import { initSync as initCodecWasm } from "@reallyme/codec/wasm/reallyme_codec_wasm.js";
 import {
   createReallyMeCrypto,
   createReallyMeWasmProvider,
   installReallyMeWasmProvider,
   ReallyMeCrypto,
 } from "@reallyme/crypto";
-import * as wasmProvider from "@reallyme/crypto/wasm/reallyme_crypto_wasm.js";
+import { initSync as initCryptoWasm } from "@reallyme/crypto/wasm/reallyme_crypto_wasm.js";
+
+// Provider constructors validate the dynamically imported module as `unknown`
+// against the package's explicit required-export list.
+const wasmProvider: unknown = await import(
+  "@reallyme/crypto/wasm/reallyme_crypto_wasm.js"
+);
+const codecWasmProvider: unknown = await import(
+  "@reallyme/codec/wasm/reallyme_codec_wasm.js"
+);
 
 const wasmUrl = import.meta.resolve(
   "@reallyme/crypto/wasm/reallyme_crypto_wasm_bg.wasm",
 );
-wasmProvider.initSync({ module: readFileSync(new URL(wasmUrl)) });
+initCryptoWasm({ module: readFileSync(new URL(wasmUrl)) });
 installReallyMeWasmProvider(wasmProvider);
 const isolatedCrypto = createReallyMeCrypto({
   wasmProvider: createReallyMeWasmProvider(wasmProvider),
@@ -86,7 +103,7 @@ const isolatedCrypto = createReallyMeCrypto({
 const codecWasmUrl = import.meta.resolve(
   "@reallyme/codec/wasm/reallyme_codec_wasm_bg.wasm",
 );
-codecWasmProvider.initSync({ module: readFileSync(new URL(codecWasmUrl)) });
+initCodecWasm({ module: readFileSync(new URL(codecWasmUrl)) });
 installReallyMeCodecWasmProvider(codecWasmProvider);
 
 const keyPair = ReallyMeCrypto.generateKemKeyPair("X-Wing-768");
@@ -97,6 +114,52 @@ The explicit facade form is preferred for Workers, SSR, tests, and multi-bundle
 applications because each instance owns its provider routing and does not depend
 on package-global mutable state.
 
+The package-owned WASM provider derives ML-DSA, ML-KEM, and X-Wing seed-based
+keypairs inside Rust and returns the public key produced by that implementation.
+Custom provider objects are trusted providers: if an application supplies its
+own seed-derived keypair provider, it is responsible for public-key
+correspondence and must be covered by its own conformance evidence.
+
+## Raw WASM Module Contract
+
+The raw `@reallyme/crypto/wasm/reallyme_crypto_wasm.js` export is an internal
+provider artifact for installing or constructing `ReallyMeWasmProvider`
+instances. Direct raw WASM calls are unsupported for application logic. Use the
+typed TypeScript facades, which validate caller inputs, numeric ranges, provider
+outputs, aliasing, and cleanup before invoking the raw module.
+
+This distinction matters for numeric parameters: JavaScript-to-WASM glue can
+coerce raw `number` arguments before Rust receives them. The supported facades
+reject out-of-range Argon2id, KMAC, HPKE, and RSA selector or length values
+before provider dispatch. Package checks verify that the README, package
+exports, TypeScript declarations, and generated WASM glue continue to agree on
+this support boundary and that no ambient global crypto-provider functions are
+used.
+
+Variable-length direct primitive inputs are capped at one mebibyte before any
+WASM copy or provider dispatch. Authenticated ciphertext may additionally carry
+the 16-byte tag. HPKE `info` is capped at 65,530 bytes so the fixed five-byte
+key-schedule label remains within RFC 9180's two-byte context-length limit.
+
+### Browser WASM Lifecycle
+
+Argon2id V1 and V2 require 256 MiB and 512 MiB of working memory respectively.
+WebAssembly linear memory does not shrink, so an instance can retain that
+resident allocation after derivation. Browser applications should run Argon2id
+in a short-lived dedicated Worker and terminate the Worker after use, especially
+on memory-constrained devices.
+
+Treat a WebAssembly trap as fatal for that provider instance. The SDK maps the
+trap to `provider-failure`, but does not guarantee that an instance interrupted
+mid-operation remains reusable; discard its Worker or provider context before
+performing another operation.
+
+The generated loader resolves its `.wasm` file by relative URL and does not
+embed a content hash. The npm tarball protects the installed package artifact,
+but applications that separately host WASM bytes should use immutable asset
+URLs and verify those bytes against a deployment-controlled digest before
+initialization.
+
 ## Memory Hygiene
 
 Rust-owned secret buffers are zeroized by the Rust implementation and WASM
@@ -109,6 +172,18 @@ as practical:
 bestEffortClear(secretBytes);
 ```
 
+Explicit provider results must be independently owned `Uint8Array` values that
+do not overlap caller inputs or sibling result fields. The facade rejects
+aliases as `provider-failure` without modifying caller storage. Malformed
+provider-owned secret outputs are cleared before the same typed failure is
+returned.
+
+AES-KW provider results must have the exact RFC 3394 `plaintext + 8` or
+`wrapped - 8` length. The facade wipes and rejects a returned typed array whose
+length violates that contract. KMAC keys and customization strings are capped
+at 4 KiB, contexts at 64 KiB, and outputs at 64 KiB before WASM copies are
+created.
+
 Do not move private keys, passwords, plaintext, shared secrets, or derived keys
 through strings or JSON paths.
 
@@ -119,11 +194,26 @@ through strings or JSON paths.
 - Shared conformance vectors across Rust, Swift, Kotlin, and TypeScript.
 - Native providers where available, WASM-backed implementations where needed.
 - Typed errors and fail-closed verification behavior.
-- Protobuf algorithm identifiers for API and storage boundaries, via
-  `@reallyme/crypto/proto`.
+- Generated protobuf operations, algorithm identifiers, and typed wire errors
+  via `@reallyme/crypto/proto`.
 - JWK, multikey, multicodec, HPKE, ML-KEM, ML-DSA, Ed25519, secp256k1, X25519,
   AES-GCM, ChaCha20-Poly1305, and more.
 
+## Protobuf Process Boundary
+
+`processOperationResponse(request)` accepts one generated binary
+`CryptoOperationRequest`. `processOperationResponseJson(requestJson)` accepts
+the strict generated ProtoJSON view only for non-secret hash, verification,
+key-generation, encapsulation, and sender-export requests. Both return binary
+`CryptoOperationResponse` bytes, so malformed input, unsupported algorithms,
+and resource-limit failures preserve their structured protobuf branch and
+reason. This is the single executable structured response contract.
+
+ProtoJSON is request-only. Decode returned binary protobuf with the generated
+exports from `@reallyme/crypto/proto`. Secret-bearing operation selectors are
+rejected before JSON value deserialization and must use protobuf bytes. Clear
+caller-owned `Uint8Array` values after use.
+
 ## Documentation
 
 The complete documentation, provider matrix, protocol contracts, and conformance

package/dist/aead.js

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { ReallyMeCryptoError } from "./errors.js";
-import { ensureByteArray, ensureBytes } from "./validateBytes.js";
+import { ensureByteArrayAtMost, ensureBytes, ensureIndependentByteArray, MAX_CRYPTO_INPUT_LENGTH, } from "./validateBytes.js";
 import { requireReallyMeWasmProvider } from "./wasmProvider.js";
 export const AEAD_KEY_LENGTH = 32;
 export const AES_128_GCM_KEY_LENGTH = 16;
@@ -64,24 +64,31 @@ const aeadSuiteWithProvider = (algorithm, provider) => {
 const sealWithSuite = (suite, key, nonce, aad, plaintext) => {
     ensureBytes(key, suite.keyLength);
     ensureBytes(nonce, suite.nonceLength);
-    ensureByteArray(aad);
-    ensureByteArray(plaintext);
-    return requireBytesOutput(suite.seal(key, nonce, aad, plaintext));
+    ensureByteArrayAtMost(aad, MAX_CRYPTO_INPUT_LENGTH);
+    ensureByteArrayAtMost(plaintext, MAX_CRYPTO_INPUT_LENGTH);
+    return requireBytesOutput(suite.seal(key, nonce, aad, plaintext), plaintext.length + AEAD_TAG_LENGTH, [key, nonce, aad, plaintext]);
 };
 const openWithSuite = (suite, key, nonce, aad, ciphertextWithTag) => {
     ensureBytes(key, suite.keyLength);
     ensureBytes(nonce, suite.nonceLength);
-    ensureByteArray(aad);
-    ensureByteArray(ciphertextWithTag);
+    ensureByteArrayAtMost(aad, MAX_CRYPTO_INPUT_LENGTH);
+    ensureByteArrayAtMost(ciphertextWithTag, MAX_CRYPTO_INPUT_LENGTH + AEAD_TAG_LENGTH);
     if (ciphertextWithTag.length < AEAD_TAG_LENGTH) {
         throw new ReallyMeCryptoError("invalid-input");
     }
-    return requireBytesOutput(suite.open(key, nonce, aad, ciphertextWithTag));
+    return requireBytesOutput(suite.open(key, nonce, aad, ciphertextWithTag), ciphertextWithTag.length - AEAD_TAG_LENGTH, [key, nonce, aad, ciphertextWithTag]);
 };
-const requireBytesOutput = (value) => {
+const requireBytesOutput = (value, expectedLength, inputs) => {
     if (!(value instanceof Uint8Array)) {
         throw new ReallyMeCryptoError("provider-failure");
     }
+    // Validate ownership before clearing malformed provider output so an alias
+    // cannot turn error cleanup into mutation of caller-owned secret material.
+    ensureIndependentByteArray(value, inputs);
+    if (value.length !== expectedLength) {
+        value.fill(0);
+        throw new ReallyMeCryptoError("provider-failure");
+    }
     return value;
 };
 export const ReallyMeAead = {

package/dist/aesKw.d.ts

@@ -1,4 +1,7 @@
 import type { ReallyMeWasmProvider } from "./wasmProvider.js";
+import type { ReallyMeKeyWrapAlgorithm } from "./algorithms.js";
+export declare const AES_128_KW_KEK_LENGTH = 16;
+export declare const AES_192_KW_KEK_LENGTH = 24;
 export declare const AES_256_KW_KEK_LENGTH = 32;
 export declare const AES_KW_BLOCK_LENGTH = 8;
 export declare const AES_KW_INTEGRITY_CHECK_LENGTH = 8;
@@ -6,8 +9,8 @@ export declare const AES_KW_MIN_KEY_DATA_LENGTH = 16;
 export declare const AES_KW_MIN_WRAPPED_KEY_LENGTH: number;
 export declare const AES_KW_MAX_KEY_DATA_LENGTH = 4096;
 export declare const ReallyMeAesKw: {
-    readonly wrapKey: (wrappingKey: Uint8Array, keyToWrap: Uint8Array) => Uint8Array;
-    readonly wrapKeyWithProvider: (provider: ReallyMeWasmProvider, wrappingKey: Uint8Array, keyToWrap: Uint8Array) => Uint8Array;
-    readonly unwrapKey: (wrappingKey: Uint8Array, wrappedKey: Uint8Array) => Uint8Array;
-    readonly unwrapKeyWithProvider: (provider: ReallyMeWasmProvider, wrappingKey: Uint8Array, wrappedKey: Uint8Array) => Uint8Array;
+    readonly wrapKey: (algorithm: ReallyMeKeyWrapAlgorithm, wrappingKey: Uint8Array, keyToWrap: Uint8Array) => Uint8Array;
+    readonly wrapKeyWithProvider: (algorithm: ReallyMeKeyWrapAlgorithm, provider: ReallyMeWasmProvider, wrappingKey: Uint8Array, keyToWrap: Uint8Array) => Uint8Array;
+    readonly unwrapKey: (algorithm: ReallyMeKeyWrapAlgorithm, wrappingKey: Uint8Array, wrappedKey: Uint8Array) => Uint8Array;
+    readonly unwrapKeyWithProvider: (algorithm: ReallyMeKeyWrapAlgorithm, provider: ReallyMeWasmProvider, wrappingKey: Uint8Array, wrappedKey: Uint8Array) => Uint8Array;
 };

package/dist/aesKw.js

@@ -2,8 +2,10 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { ReallyMeCryptoError } from "./errors.js";
-import { ensureBytes } from "./validateBytes.js";
+import { ensureByteArray, ensureBytes, ensureIndependentByteArray, } from "./validateBytes.js";
 import { requireReallyMeWasmProvider } from "./wasmProvider.js";
+export const AES_128_KW_KEK_LENGTH = 16;
+export const AES_192_KW_KEK_LENGTH = 24;
 export const AES_256_KW_KEK_LENGTH = 32;
 export const AES_KW_BLOCK_LENGTH = 8;
 export const AES_KW_INTEGRITY_CHECK_LENGTH = 8;
@@ -25,31 +27,76 @@ const validateWrappedKeyLength = (length) => {
         throw new ReallyMeCryptoError("invalid-input");
     }
 };
-const requireBytesOutput = (value) => {
+const requireBytesOutput = (value, expectedLength, inputs) => {
     if (!(value instanceof Uint8Array)) {
         throw new ReallyMeCryptoError("provider-failure");
     }
+    // Reject aliases before wiping malformed output. Otherwise a provider could
+    // return a caller-owned key/input view and make validation erase that input.
+    ensureIndependentByteArray(value, inputs);
+    if (value.length !== expectedLength) {
+        value.fill(0);
+        throw new ReallyMeCryptoError("provider-failure");
+    }
     return value;
 };
+const kekLengthForAlgorithm = (algorithm) => {
+    switch (algorithm) {
+        case "AES-128-KW":
+            return AES_128_KW_KEK_LENGTH;
+        case "AES-192-KW":
+            return AES_192_KW_KEK_LENGTH;
+        case "AES-256-KW":
+            return AES_256_KW_KEK_LENGTH;
+    }
+};
+const wrapFunctionForAlgorithm = (provider, algorithm) => {
+    switch (algorithm) {
+        case "AES-128-KW":
+            return provider.aes128KwWrapKey;
+        case "AES-192-KW":
+            return provider.aes192KwWrapKey;
+        case "AES-256-KW":
+            return provider.aes256KwWrapKey;
+    }
+};
+const unwrapFunctionForAlgorithm = (provider, algorithm) => {
+    switch (algorithm) {
+        case "AES-128-KW":
+            return provider.aes128KwUnwrapKey;
+        case "AES-192-KW":
+            return provider.aes192KwUnwrapKey;
+        case "AES-256-KW":
+            return provider.aes256KwUnwrapKey;
+    }
+};
+const wrapKey = (algorithm, wrappingKey, keyToWrap) => {
+    ensureBytes(wrappingKey, kekLengthForAlgorithm(algorithm));
+    ensureByteArray(keyToWrap);
+    validateKeyDataLength(keyToWrap.length);
+    return requireBytesOutput(wrapFunctionForAlgorithm(requireReallyMeWasmProvider(), algorithm)(wrappingKey, keyToWrap), keyToWrap.length + AES_KW_INTEGRITY_CHECK_LENGTH, [wrappingKey, keyToWrap]);
+};
+const wrapKeyWithProvider = (algorithm, provider, wrappingKey, keyToWrap) => {
+    ensureBytes(wrappingKey, kekLengthForAlgorithm(algorithm));
+    ensureByteArray(keyToWrap);
+    validateKeyDataLength(keyToWrap.length);
+    return requireBytesOutput(wrapFunctionForAlgorithm(provider, algorithm)(wrappingKey, keyToWrap), keyToWrap.length + AES_KW_INTEGRITY_CHECK_LENGTH, [wrappingKey, keyToWrap]);
+};
+const unwrapKey = (algorithm, wrappingKey, wrappedKey) => {
+    ensureBytes(wrappingKey, kekLengthForAlgorithm(algorithm));
+    ensureByteArray(wrappedKey);
+    validateWrappedKeyLength(wrappedKey.length);
+    return requireBytesOutput(unwrapFunctionForAlgorithm(requireReallyMeWasmProvider(), algorithm)(wrappingKey, wrappedKey), wrappedKey.length - AES_KW_INTEGRITY_CHECK_LENGTH, [wrappingKey, wrappedKey]);
+};
+const unwrapKeyWithProvider = (algorithm, provider, wrappingKey, wrappedKey) => {
+    ensureBytes(wrappingKey, kekLengthForAlgorithm(algorithm));
+    ensureByteArray(wrappedKey);
+    validateWrappedKeyLength(wrappedKey.length);
+    return requireBytesOutput(unwrapFunctionForAlgorithm(provider, algorithm)(wrappingKey, wrappedKey), wrappedKey.length - AES_KW_INTEGRITY_CHECK_LENGTH, [wrappingKey, wrappedKey]);
+};
 export const ReallyMeAesKw = {
-    wrapKey(wrappingKey, keyToWrap) {
-        ensureBytes(wrappingKey, AES_256_KW_KEK_LENGTH);
-        validateKeyDataLength(keyToWrap.length);
-        return requireBytesOutput(requireReallyMeWasmProvider().aes256KwWrapKey(wrappingKey, keyToWrap));
-    },
-    wrapKeyWithProvider(provider, wrappingKey, keyToWrap) {
-        ensureBytes(wrappingKey, AES_256_KW_KEK_LENGTH);
-        validateKeyDataLength(keyToWrap.length);
-        return requireBytesOutput(provider.aes256KwWrapKey(wrappingKey, keyToWrap));
-    },
-    unwrapKey(wrappingKey, wrappedKey) {
-        ensureBytes(wrappingKey, AES_256_KW_KEK_LENGTH);
-        validateWrappedKeyLength(wrappedKey.length);
-        return requireBytesOutput(requireReallyMeWasmProvider().aes256KwUnwrapKey(wrappingKey, wrappedKey));
-    },
-    unwrapKeyWithProvider(provider, wrappingKey, wrappedKey) {
-        ensureBytes(wrappingKey, AES_256_KW_KEK_LENGTH);
-        validateWrappedKeyLength(wrappedKey.length);
-        return requireBytesOutput(provider.aes256KwUnwrapKey(wrappingKey, wrappedKey));
-    },
+    wrapKey,
+    wrapKeyWithProvider,
+    unwrapKey,
+    unwrapKeyWithProvider,
 };

package/dist/algorithms.d.ts

@@ -4,15 +4,23 @@ export declare const REALLYME_HASH_ALGORITHMS: readonly ["SHA2-256", "SHA2-384",
 export type ReallyMeHashAlgorithm = (typeof REALLYME_HASH_ALGORITHMS)[number];
 export declare const REALLYME_AEAD_ALGORITHMS: readonly ["AES-128-GCM", "AES-192-GCM", "AES-256-GCM", "AES-256-GCM-SIV", "ChaCha20-Poly1305", "XChaCha20-Poly1305"];
 export type ReallyMeAeadAlgorithm = (typeof REALLYME_AEAD_ALGORITHMS)[number];
-export declare const REALLYME_KEM_ALGORITHMS: readonly ["ML-KEM-512", "ML-KEM-768", "ML-KEM-1024", "X-Wing-768", "X-Wing-1024"];
+export declare const REALLYME_KEM_ALGORITHMS: readonly ["ML-KEM-512", "ML-KEM-768", "ML-KEM-1024", "X-Wing-768"];
 export type ReallyMeKemAlgorithm = (typeof REALLYME_KEM_ALGORITHMS)[number];
 export declare const REALLYME_KEY_AGREEMENT_ALGORITHMS: readonly ["X25519", "P-256-ECDH", "P-384-ECDH", "P-521-ECDH"];
 export type ReallyMeKeyAgreementAlgorithm = (typeof REALLYME_KEY_AGREEMENT_ALGORITHMS)[number];
-export declare const REALLYME_MAC_ALGORITHMS: readonly ["HMAC-SHA-256", "HMAC-SHA-512"];
+export declare const REALLYME_MAC_ALGORITHMS: readonly ["HMAC-SHA-256", "HMAC-SHA-384", "HMAC-SHA-512"];
 export type ReallyMeMacAlgorithm = (typeof REALLYME_MAC_ALGORITHMS)[number];
-export declare const REALLYME_KDF_ALGORITHMS: readonly ["HKDF-SHA256", "Argon2id", "PBKDF2-HMAC-SHA-256", "PBKDF2-HMAC-SHA-512", "JWA-CONCAT-KDF-SHA256"];
+export declare const REALLYME_KDF_ALGORITHMS: readonly ["HKDF-SHA256", "HKDF-SHA384", "Argon2id", "KMAC256", "PBKDF2-HMAC-SHA-256", "PBKDF2-HMAC-SHA-512", "JWA-CONCAT-KDF-SHA256"];
 export type ReallyMeKdfAlgorithm = (typeof REALLYME_KDF_ALGORITHMS)[number];
-export declare const REALLYME_KEY_WRAP_ALGORITHMS: readonly ["AES-256-KW"];
+/** PBKDF2 selectors accepted by the password-based `deriveKey` facade. */
+export type ReallyMePbkdf2Algorithm = Extract<ReallyMeKdfAlgorithm, "PBKDF2-HMAC-SHA-256" | "PBKDF2-HMAC-SHA-512">;
+/** HKDF selectors accepted by the `deriveHkdf` facade. */
+export type ReallyMeHkdfAlgorithm = Extract<ReallyMeKdfAlgorithm, "HKDF-SHA256" | "HKDF-SHA384">;
+/** JWA Concat KDF selector accepted by its dedicated facade. */
+export type ReallyMeJwaConcatKdfAlgorithm = Extract<ReallyMeKdfAlgorithm, "JWA-CONCAT-KDF-SHA256">;
+/** KMAC KDF selector accepted by its dedicated facade. */
+export type ReallyMeKmacKdfAlgorithm = Extract<ReallyMeKdfAlgorithm, "KMAC256">;
+export declare const REALLYME_KEY_WRAP_ALGORITHMS: readonly ["AES-128-KW", "AES-192-KW", "AES-256-KW"];
 export type ReallyMeKeyWrapAlgorithm = (typeof REALLYME_KEY_WRAP_ALGORITHMS)[number];
 export declare const REALLYME_HPKE_SUITES: readonly ["DHKEM-P256-HKDF-SHA256-HKDF-SHA256-AES-256-GCM", "DHKEM-X25519-HKDF-SHA256-HKDF-SHA256-CHACHA20-POLY1305"];
 export type ReallyMeHpkeSuite = (typeof REALLYME_HPKE_SUITES)[number];

package/dist/algorithms.js

@@ -43,7 +43,6 @@ export const REALLYME_KEM_ALGORITHMS = [
     "ML-KEM-768",
     "ML-KEM-1024",
     "X-Wing-768",
-    "X-Wing-1024",
 ];
 export const REALLYME_KEY_AGREEMENT_ALGORITHMS = [
     "X25519",
@@ -53,16 +52,23 @@ export const REALLYME_KEY_AGREEMENT_ALGORITHMS = [
 ];
 export const REALLYME_MAC_ALGORITHMS = [
     "HMAC-SHA-256",
+    "HMAC-SHA-384",
     "HMAC-SHA-512",
 ];
 export const REALLYME_KDF_ALGORITHMS = [
     "HKDF-SHA256",
+    "HKDF-SHA384",
     "Argon2id",
+    "KMAC256",
     "PBKDF2-HMAC-SHA-256",
     "PBKDF2-HMAC-SHA-512",
     "JWA-CONCAT-KDF-SHA256",
 ];
-export const REALLYME_KEY_WRAP_ALGORITHMS = ["AES-256-KW"];
+export const REALLYME_KEY_WRAP_ALGORITHMS = [
+    "AES-128-KW",
+    "AES-192-KW",
+    "AES-256-KW",
+];
 export const REALLYME_HPKE_SUITES = [
     "DHKEM-P256-HKDF-SHA256-HKDF-SHA256-AES-256-GCM",
     "DHKEM-X25519-HKDF-SHA256-HKDF-SHA256-CHACHA20-POLY1305",

package/dist/argon2id.d.ts

@@ -2,6 +2,7 @@ import type { ReallyMeWasmProvider } from "./wasmProvider.js";
 export declare const ARGON2ID_DERIVED_KEY_LENGTH = 32;
 export declare const ARGON2ID_SALT_MIN_LENGTH = 16;
 export declare const ARGON2ID_SALT_MAX_LENGTH = 32;
+export declare const ARGON2ID_SECRET_MAX_LENGTH = 1048576;
 export declare const ARGON2ID_V1 = 1;
 export declare const ARGON2ID_V2 = 2;
 export declare const ReallyMeArgon2id: {

package/dist/argon2id.js

@@ -2,10 +2,12 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { ReallyMeCryptoError } from "./errors.js";
+import { ensureByteArrayAtMost, ensureIndependentByteArray, } from "./validateBytes.js";
 import { requireReallyMeWasmProvider } from "./wasmProvider.js";
 export const ARGON2ID_DERIVED_KEY_LENGTH = 32;
 export const ARGON2ID_SALT_MIN_LENGTH = 16;
 export const ARGON2ID_SALT_MAX_LENGTH = 32;
+export const ARGON2ID_SECRET_MAX_LENGTH = 1_048_576;
 export const ARGON2ID_V1 = 1;
 export const ARGON2ID_V2 = 2;
 const validateVersion = (kdfVersion) => {
@@ -15,17 +17,24 @@ const validateVersion = (kdfVersion) => {
     }
 };
 const validateSecret = (secret) => {
+    ensureByteArrayAtMost(secret, ARGON2ID_SECRET_MAX_LENGTH);
     if (secret.length === 0) {
         throw new ReallyMeCryptoError("invalid-input");
     }
 };
 const validateSalt = (salt) => {
+    ensureByteArrayAtMost(salt, ARGON2ID_SALT_MAX_LENGTH);
     if (salt.length < ARGON2ID_SALT_MIN_LENGTH || salt.length > ARGON2ID_SALT_MAX_LENGTH) {
         throw new ReallyMeCryptoError("invalid-input");
     }
 };
-const requireDerivedKey = (value) => {
-    if (!(value instanceof Uint8Array) || value.length !== ARGON2ID_DERIVED_KEY_LENGTH) {
+const requireDerivedKey = (value, inputs) => {
+    if (!(value instanceof Uint8Array)) {
+        throw new ReallyMeCryptoError("provider-failure");
+    }
+    ensureIndependentByteArray(value, inputs);
+    if (value.length !== ARGON2ID_DERIVED_KEY_LENGTH) {
+        value.fill(0);
         throw new ReallyMeCryptoError("provider-failure");
     }
     return value;
@@ -35,12 +44,12 @@ export const ReallyMeArgon2id = {
         validateVersion(kdfVersion);
         validateSecret(secret);
         validateSalt(salt);
-        return requireDerivedKey(requireReallyMeWasmProvider().argon2idDeriveKey(kdfVersion, secret, salt));
+        return requireDerivedKey(requireReallyMeWasmProvider().argon2idDeriveKey(kdfVersion, secret, salt), [secret, salt]);
     },
     deriveKeyWithProvider(provider, kdfVersion, secret, salt) {
         validateVersion(kdfVersion);
         validateSecret(secret);
         validateSalt(salt);
-        return requireDerivedKey(provider.argon2idDeriveKey(kdfVersion, secret, salt));
+        return requireDerivedKey(provider.argon2idDeriveKey(kdfVersion, secret, salt), [secret, salt]);
     },
 };

package/dist/cryptoFacade.d.ts

@@ -1,4 +1,4 @@
-import type { ReallyMeAeadAlgorithm, ReallyMeHashAlgorithm, ReallyMeHpkeSuite, ReallyMeKdfAlgorithm, ReallyMeKemAlgorithm, ReallyMeKeyAgreementAlgorithm, ReallyMeKeyWrapAlgorithm, ReallyMeMacAlgorithm, ReallyMeSignatureAlgorithm } from "./algorithms.js";
+import type { ReallyMeAeadAlgorithm, ReallyMeHashAlgorithm, ReallyMeHkdfAlgorithm, ReallyMeHpkeSuite, ReallyMeJwaConcatKdfAlgorithm, ReallyMeKemAlgorithm, ReallyMeKeyAgreementAlgorithm, ReallyMeKeyWrapAlgorithm, ReallyMeKmacKdfAlgorithm, ReallyMeMacAlgorithm, ReallyMePbkdf2Algorithm, ReallyMeSignatureAlgorithm } from "./algorithms.js";
 import type { ReallyMeRsaPublicKeyDerEncoding } from "./rsa.js";
 import type { ReallyMeWasmProvider } from "./wasmProvider.js";
 export type ReallyMeSignatureKeyPair = Readonly<{
@@ -27,18 +27,31 @@ export type ReallyMeCryptoProviders = Readonly<{
 /**
  * Generic package facade. Algorithm-specific objects remain available for
  * callers that want direct provider access; this facade gives consumers a
- * stable typed route that fails closed for not-yet-exposed algorithms.
+ * stable typed route and rejects algorithm/operation combinations that the
+ * selected method does not define.
  */
 declare const createReallyMeCryptoFacade: (resolveWasmProvider: () => ReallyMeWasmProvider) => {
+    /**
+     * Executes a generated binary request and returns a binary
+     * `CryptoOperationResponse`.
+     */
+    readonly processOperationResponse: (request: Uint8Array) => Uint8Array;
+    /**
+     * Executes a permitted non-secret generated ProtoJSON request and returns
+     * the same binary `CryptoOperationResponse`. Secret-bearing selectors fail
+     * before JSON value deserialization.
+     */
+    readonly processOperationResponseJson: (requestJson: Uint8Array) => Uint8Array;
     readonly hash: (algorithm: ReallyMeHashAlgorithm, bytes: Uint8Array) => Uint8Array;
     readonly seal: (algorithm: ReallyMeAeadAlgorithm, key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, plaintext: Uint8Array) => Uint8Array;
     readonly open: (algorithm: ReallyMeAeadAlgorithm, key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, ciphertextWithTag: Uint8Array) => Uint8Array;
     readonly authenticate: (algorithm: ReallyMeMacAlgorithm, key: Uint8Array, message: Uint8Array) => Uint8Array;
     readonly verifyMac: (algorithm: ReallyMeMacAlgorithm, tag: Uint8Array, key: Uint8Array, message: Uint8Array) => boolean;
     readonly deriveArgon2id: (kdfVersion: number, secret: Uint8Array, salt: Uint8Array) => Uint8Array;
-    readonly deriveKey: (algorithm: ReallyMeKdfAlgorithm, password: Uint8Array, salt: Uint8Array, iterations: number, outputLength: number) => Uint8Array;
-    readonly deriveHkdf: (algorithm: ReallyMeKdfAlgorithm, inputKeyMaterial: Uint8Array, salt: Uint8Array, info: Uint8Array, outputLength: number) => Uint8Array;
-    readonly deriveJwaConcatKdfSha256: (algorithm: ReallyMeKdfAlgorithm, sharedSecret: Uint8Array, algorithmId: Uint8Array, partyUInfo: Uint8Array, partyVInfo: Uint8Array, outputLength: number) => Uint8Array;
+    readonly deriveKey: (algorithm: ReallyMePbkdf2Algorithm, password: Uint8Array, salt: Uint8Array, iterations: number, outputLength: number) => Uint8Array;
+    readonly deriveHkdf: (algorithm: ReallyMeHkdfAlgorithm, inputKeyMaterial: Uint8Array, salt: Uint8Array, info: Uint8Array, outputLength: number) => Uint8Array;
+    readonly deriveJwaConcatKdfSha256: (algorithm: ReallyMeJwaConcatKdfAlgorithm, sharedSecret: Uint8Array, algorithmId: Uint8Array, partyUInfo: Uint8Array, partyVInfo: Uint8Array, outputLength: number) => Uint8Array;
+    readonly deriveKmac256: (algorithm: ReallyMeKmacKdfAlgorithm, key: Uint8Array, context: Uint8Array, customization: Uint8Array, outputLength: number) => Uint8Array;
     readonly wrapKey: (algorithm: ReallyMeKeyWrapAlgorithm, wrappingKey: Uint8Array, keyToWrap: Uint8Array) => Uint8Array;
     readonly unwrapKey: (algorithm: ReallyMeKeyWrapAlgorithm, wrappingKey: Uint8Array, wrappedKey: Uint8Array) => Uint8Array;
     readonly generateKeyPair: (algorithm: ReallyMeSignatureAlgorithm) => ReallyMeSignatureKeyPair;
@@ -59,15 +72,27 @@ declare const createReallyMeCryptoFacade: (resolveWasmProvider: () => ReallyMeWa
 export type ReallyMeCryptoFacade = ReturnType<typeof createReallyMeCryptoFacade>;
 export declare const createReallyMeCrypto: (providers?: ReallyMeCryptoProviders) => ReallyMeCryptoFacade;
 export declare const ReallyMeCrypto: {
+    /**
+     * Executes a generated binary request and returns a binary
+     * `CryptoOperationResponse`.
+     */
+    readonly processOperationResponse: (request: Uint8Array) => Uint8Array;
+    /**
+     * Executes a permitted non-secret generated ProtoJSON request and returns
+     * the same binary `CryptoOperationResponse`. Secret-bearing selectors fail
+     * before JSON value deserialization.
+     */
+    readonly processOperationResponseJson: (requestJson: Uint8Array) => Uint8Array;
     readonly hash: (algorithm: ReallyMeHashAlgorithm, bytes: Uint8Array) => Uint8Array;
     readonly seal: (algorithm: ReallyMeAeadAlgorithm, key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, plaintext: Uint8Array) => Uint8Array;
     readonly open: (algorithm: ReallyMeAeadAlgorithm, key: Uint8Array, nonce: Uint8Array, aad: Uint8Array, ciphertextWithTag: Uint8Array) => Uint8Array;
     readonly authenticate: (algorithm: ReallyMeMacAlgorithm, key: Uint8Array, message: Uint8Array) => Uint8Array;
     readonly verifyMac: (algorithm: ReallyMeMacAlgorithm, tag: Uint8Array, key: Uint8Array, message: Uint8Array) => boolean;
     readonly deriveArgon2id: (kdfVersion: number, secret: Uint8Array, salt: Uint8Array) => Uint8Array;
-    readonly deriveKey: (algorithm: ReallyMeKdfAlgorithm, password: Uint8Array, salt: Uint8Array, iterations: number, outputLength: number) => Uint8Array;
-    readonly deriveHkdf: (algorithm: ReallyMeKdfAlgorithm, inputKeyMaterial: Uint8Array, salt: Uint8Array, info: Uint8Array, outputLength: number) => Uint8Array;
-    readonly deriveJwaConcatKdfSha256: (algorithm: ReallyMeKdfAlgorithm, sharedSecret: Uint8Array, algorithmId: Uint8Array, partyUInfo: Uint8Array, partyVInfo: Uint8Array, outputLength: number) => Uint8Array;
+    readonly deriveKey: (algorithm: ReallyMePbkdf2Algorithm, password: Uint8Array, salt: Uint8Array, iterations: number, outputLength: number) => Uint8Array;
+    readonly deriveHkdf: (algorithm: ReallyMeHkdfAlgorithm, inputKeyMaterial: Uint8Array, salt: Uint8Array, info: Uint8Array, outputLength: number) => Uint8Array;
+    readonly deriveJwaConcatKdfSha256: (algorithm: ReallyMeJwaConcatKdfAlgorithm, sharedSecret: Uint8Array, algorithmId: Uint8Array, partyUInfo: Uint8Array, partyVInfo: Uint8Array, outputLength: number) => Uint8Array;
+    readonly deriveKmac256: (algorithm: ReallyMeKmacKdfAlgorithm, key: Uint8Array, context: Uint8Array, customization: Uint8Array, outputLength: number) => Uint8Array;
     readonly wrapKey: (algorithm: ReallyMeKeyWrapAlgorithm, wrappingKey: Uint8Array, keyToWrap: Uint8Array) => Uint8Array;
     readonly unwrapKey: (algorithm: ReallyMeKeyWrapAlgorithm, wrappingKey: Uint8Array, wrappedKey: Uint8Array) => Uint8Array;
     readonly generateKeyPair: (algorithm: ReallyMeSignatureAlgorithm) => ReallyMeSignatureKeyPair;