@enclave-technologies/pqc-primitives 0.1.0

package/dist/nodejs/enclave_pqc_primitives_wasm.d.ts

@@ -0,0 +1,218 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Canonical suite identifier matching the Rust crate (Category 5 algorithms).
+ */
+export function ENCLAVE_PQ_SUITE_ID(): string;
+
+/**
+ * Domain-separation prefix for the Enclave labeled KDF.
+ */
+export function KDF_LABEL_PREFIX(): string;
+
+/**
+ * Algorithm identifier (`"Argon2id"`).
+ */
+export function PWHASH_ALGORITHM(): string;
+
+/**
+ * Derived key length in bytes (matches AES-256-GCM key size).
+ */
+export function PWHASH_OUTPUT_BYTES(): number;
+
+/**
+ * Salt length in bytes produced by [`generate_salt`].
+ */
+export function PWHASH_SALT_BYTES(): number;
+
+/**
+ * OWASP baseline Argon2id params: `{ memoryCostKib, iterations, parallelism }`.
+ *
+ * Sourced from the OWASP Password Storage Cheat Sheet (19 MiB / t=2 / p=1).
+ * Slow and memory-hard by design — lowering these for login latency is a
+ * security tradeoff, not a free optimization.
+ */
+export function RECOMMENDED_PARAMS(): any;
+
+/**
+ * Decrypt AES-256-GCM ciphertext (including trailing tag).
+ *
+ * Throws on authentication failure (`AeadFailure: ...`).
+ */
+export function aeadDecrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array): Uint8Array;
+
+/**
+ * Encrypt with AES-256-GCM under an explicit key and nonce.
+ *
+ * Returns `ciphertext || tag` (16-byte tag suffix). Callers must ensure
+ * `(key, nonce)` uniqueness.
+ */
+export function aeadEncrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Uint8Array;
+
+/**
+ * Cryptographically random 16-byte salt for Argon2id.
+ */
+export function generateSalt(): Uint8Array;
+
+/**
+ * Return the [`CryptoUsageRecord`] from the last WASM primitive call.
+ *
+ * Shape: `{ algorithm, suiteId, operation, crateVersion }`.
+ * Returns `undefined` if no operation has run yet in this WASM instance.
+ *
+ * This is the CBOM attach point for product layers (Encrypt, etc.). This
+ * binding does not persist or transmit the record.
+ */
+export function getLastUsageRecord(): any;
+
+/**
+ * SHAKE256 over UTF-8 string bytes.
+ */
+export function hashUtf8(value: string, output_len: number): Uint8Array;
+
+/**
+ * Decapsulate an ML-KEM-1024 ciphertext.
+ *
+ * `secret_key` may be a 64-byte seed or a 3168-byte expanded key.
+ */
+export function kemDecapsulate(ciphertext: Uint8Array, secret_key: Uint8Array): Uint8Array;
+
+/**
+ * Encapsulate a shared secret to an ML-KEM-1024 public key.
+ *
+ * Returns `{ ciphertext, sharedSecret }` (1568 / 32 bytes).
+ */
+export function kemEncapsulate(public_key: Uint8Array): any;
+
+/**
+ * Deterministic encapsulation for known-answer / KAT compliance.
+ *
+ * # Hazmat
+ *
+ * **KATs only.** Production code must call [`kem_encapsulate`].
+ */
+export function kemEncapsulateDeterministic(public_key: Uint8Array, m: Uint8Array): any;
+
+/**
+ * Expand a 64-byte seed-form secret key to the FIPS expanded encoding
+ * ([`kem::SECRET_KEY_BYTES`] bytes).
+ */
+export function kemExpandedSecretKey(secret_key: Uint8Array): Uint8Array;
+
+/**
+ * Generate a fresh ML-KEM-1024 keypair (includes PCT).
+ *
+ * Returns `{ publicKey, secretKey }` where `secretKey` is the preferred
+ * seed form ([`kem::SECRET_KEY_SEED_BYTES`] = 64). Expanded size is
+ * [`kem::SECRET_KEY_BYTES`] = 3168 — use [`kem_expanded_secret_key`].
+ *
+ * Throws `PairwiseConsistencyFailureError` if the PCT fails.
+ */
+export function kemGenerateKeypair(): any;
+
+/**
+ * Derive an ML-KEM-1024 keypair from a 64-byte seed (`d || z`). Includes PCT.
+ */
+export function kemKeypairFromSeed(seed: Uint8Array): any;
+
+/**
+ * Derive key material with `enclave-kdf-v1` labeled SHAKE256.
+ *
+ * Throws `InvalidParameter` on empty `label` or `length == 0`.
+ */
+export function labeledKdf(label: string, ikm: Uint8Array, length: number): Uint8Array;
+
+/**
+ * [`labeled_kdf`] with a 32-byte output.
+ */
+export function labeledKdf32(label: string, ikm: Uint8Array): Uint8Array;
+
+/**
+ * Derive a 32-byte key from a password + salt with Argon2id.
+ *
+ * `params` must be `{ memoryCostKib, iterations, parallelism }` (see
+ * [`recommended_params`]). Throws on empty password / wrong salt length /
+ * invalid costs.
+ *
+ * This call is intentionally slow (~tens–hundreds of ms depending on host).
+ * That cost is the offline brute-force defense — do not lower params casually.
+ */
+export function pwhashDeriveKey(password: Uint8Array, salt: Uint8Array, params: any): Uint8Array;
+
+/**
+ * Run known-answer CASTs for ML-KEM-1024, ML-DSA-87, and Argon2id.
+ *
+ * Throws `SelfTestFailureError` if any CAST fails. Pair-wise consistency is
+ * already enforced inside key generation — this is the power-on / module-entry
+ * known-answer path. The Argon2id CAST is slower (memory-hard by design).
+ */
+export function runSelfTests(): void;
+
+/**
+ * One-shot SHAKE256 hash of `input` into `output_len` bytes.
+ */
+export function shake256(input: Uint8Array, output_len: number): Uint8Array;
+
+/**
+ * Expand a 32-byte seed-form secret key to the FIPS expanded encoding
+ * ([`sig::SECRET_KEY_BYTES`] bytes).
+ */
+export function sigExpandedSecretKey(secret_key: Uint8Array): Uint8Array;
+
+/**
+ * Generate a fresh ML-DSA-87 keypair (includes PCT).
+ *
+ * Returns `{ publicKey, secretKey }` where `secretKey` is the preferred
+ * seed form ([`sig::SECRET_KEY_SEED_BYTES`] = 32). Expanded size is
+ * [`sig::SECRET_KEY_BYTES`] = 4896.
+ *
+ * Throws `PairwiseConsistencyFailureError` if the PCT fails.
+ */
+export function sigGenerateKeypair(): any;
+
+/**
+ * Derive an ML-DSA-87 keypair from a 32-byte seed. Includes PCT.
+ */
+export function sigKeypairFromSeed(seed: Uint8Array): any;
+
+/**
+ * Sign a message with empty context (deterministic ML-DSA-87).
+ *
+ * Empty `message` throws `InvalidLength` (matches Rust).
+ */
+export function sigSign(secret_key: Uint8Array, message: Uint8Array): Uint8Array;
+
+/**
+ * Deterministic ML-DSA.Sign with an explicit context (`context.len() <= 255`).
+ *
+ * Empty `message` or `context.len() > 255` throws (matches Rust).
+ */
+export function sigSignWithContext(secret_key: Uint8Array, message: Uint8Array, context: Uint8Array): Uint8Array;
+
+/**
+ * Verify an ML-DSA-87 signature (empty context).
+ *
+ * Returns `false` on a cryptographically invalid signature. Throws only for
+ * malformed input lengths / encodings.
+ */
+export function sigVerify(public_key: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+
+/**
+ * Verify an ML-DSA-87 signature with an explicit context.
+ *
+ * Returns `false` on cryptographic failure; throws on malformed lengths.
+ */
+export function sigVerifyWithContext(public_key: Uint8Array, message: Uint8Array, signature: Uint8Array, context: Uint8Array): boolean;
+
+/**
+ * Overwrite a JS `Uint8Array` in place with zeros.
+ *
+ * # Security note
+ *
+ * Rust-side secret keys are zeroized on `Drop`, but that guarantee **does not**
+ * cross the WASM boundary. Once secret material lives in a JS `Uint8Array`, the
+ * JS garbage collector will not zero it. Call this when you are finished with
+ * long-lived secret buffers.
+ */
+export function zeroize(buf: Uint8Array): void;

package/dist/nodejs/enclave_pqc_primitives_wasm_bg.wasm.d.ts

@@ -0,0 +1,41 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const aeadDecrypt: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
+export const aeadEncrypt: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
+export const hashUtf8: (a: number, b: number, c: number) => [number, number, number, number];
+export const shake256: (a: number, b: number, c: number) => [number, number, number, number];
+export const sigExpandedSecretKey: (a: number, b: number) => [number, number, number, number];
+export const sigGenerateKeypair: () => [number, number, number];
+export const sigKeypairFromSeed: (a: number, b: number) => [number, number, number];
+export const sigSign: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const sigSignWithContext: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
+export const sigVerify: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+export const sigVerifyWithContext: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number];
+export const PWHASH_ALGORITHM: () => [number, number];
+export const PWHASH_OUTPUT_BYTES: () => number;
+export const PWHASH_SALT_BYTES: () => number;
+export const RECOMMENDED_PARAMS: () => [number, number, number];
+export const generateSalt: () => [number, number, number, number];
+export const kemDecapsulate: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const kemEncapsulate: (a: number, b: number) => [number, number, number];
+export const kemEncapsulateDeterministic: (a: number, b: number, c: number, d: number) => [number, number, number];
+export const kemExpandedSecretKey: (a: number, b: number) => [number, number, number, number];
+export const kemGenerateKeypair: () => [number, number, number];
+export const kemKeypairFromSeed: (a: number, b: number) => [number, number, number];
+export const pwhashDeriveKey: (a: number, b: number, c: number, d: number, e: any) => [number, number, number, number];
+export const ENCLAVE_PQ_SUITE_ID: () => [number, number];
+export const KDF_LABEL_PREFIX: () => [number, number];
+export const getLastUsageRecord: () => [number, number, number];
+export const labeledKdf: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+export const labeledKdf32: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const runSelfTests: () => [number, number];
+export const zeroize: (a: any) => void;
+export const __wbindgen_exn_store: (a: number) => void;
+export const __externref_table_alloc: () => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_start: () => void;

package/dist/nodejs/index.d.ts

@@ -0,0 +1,157 @@
+/** Category 5 sizes — must match Rust ENCLAVE_PQ_SUITE_v1. */
+export declare const ENCLAVE_PQ_SUITE_ID: "ENCLAVE_PQ_SUITE_v1";
+export declare const KDF_LABEL_PREFIX: "enclave-kdf-v1";
+export declare const KEM: {
+  readonly ALGORITHM: "ML-KEM-1024";
+  readonly PUBLIC_KEY_BYTES: 1568;
+  readonly SECRET_KEY_SEED_BYTES: 64;
+  readonly SECRET_KEY_EXPANDED_BYTES: 3168;
+  readonly SECRET_KEY_BYTES: 3168;
+  readonly CIPHERTEXT_BYTES: 1568;
+  readonly SHARED_SECRET_BYTES: 32;
+  readonly ENCAP_RANDOMNESS_BYTES: 32;
+};
+export declare const SIG: {
+  readonly ALGORITHM: "ML-DSA-87";
+  readonly PUBLIC_KEY_BYTES: 2592;
+  readonly SECRET_KEY_SEED_BYTES: 32;
+  readonly SECRET_KEY_EXPANDED_BYTES: 4896;
+  readonly SECRET_KEY_BYTES: 4896;
+  readonly SIGNATURE_BYTES: 4627;
+  readonly MAX_CONTEXT_BYTES: 255;
+};
+export declare const AEAD: {
+  readonly ALGORITHM: "AES-256-GCM";
+  readonly KEY_BYTES: 32;
+  readonly NONCE_BYTES: 12;
+  readonly TAG_BYTES: 16;
+};
+export declare const HASH: {
+  readonly ALGORITHM: "SHAKE256";
+  readonly DEFAULT_OUTPUT_BYTES: 32;
+};
+export declare const PWHASH: {
+  readonly ALGORITHM: "Argon2id";
+  readonly SALT_BYTES: 16;
+  readonly OUTPUT_BYTES: 32;
+  readonly RECOMMENDED_PARAMS: {
+    readonly memoryCostKib: 19456;
+    readonly iterations: 2;
+    readonly parallelism: 1;
+  };
+};
+
+export type Argon2Params = {
+  memoryCostKib: number;
+  iterations: number;
+  parallelism: number;
+};
+
+export type KemKeypair = { publicKey: Uint8Array; secretKey: Uint8Array };
+export type KemEncapsulation = {
+  ciphertext: Uint8Array;
+  sharedSecret: Uint8Array;
+};
+export type SigKeypair = { publicKey: Uint8Array; secretKey: Uint8Array };
+export type CryptoUsageRecord = {
+  algorithm: string;
+  suiteId: string;
+  operation: string;
+  crateVersion: string;
+};
+
+export declare function isPairwiseConsistencyFailure(err: unknown): boolean;
+export declare function isSelfTestFailure(err: unknown): boolean;
+
+export declare function kemGenerateKeypair(): KemKeypair;
+export declare function kemKeypairFromSeed(seed: Uint8Array): KemKeypair;
+export declare function kemExpandedSecretKey(secretKey: Uint8Array): Uint8Array;
+export declare function kemEncapsulate(publicKey: Uint8Array): KemEncapsulation;
+/** Hazmat — KATs only. Prefer kemEncapsulate. */
+export declare function kemEncapsulateDeterministic(
+  publicKey: Uint8Array,
+  m: Uint8Array,
+): KemEncapsulation;
+export declare function kemDecapsulate(
+  ciphertext: Uint8Array,
+  secretKey: Uint8Array,
+): Uint8Array;
+
+export declare function sigGenerateKeypair(): SigKeypair;
+export declare function sigKeypairFromSeed(seed: Uint8Array): SigKeypair;
+export declare function sigExpandedSecretKey(secretKey: Uint8Array): Uint8Array;
+export declare function sigSign(
+  secretKey: Uint8Array,
+  message: Uint8Array,
+): Uint8Array;
+export declare function sigSignWithContext(
+  secretKey: Uint8Array,
+  message: Uint8Array,
+  context: Uint8Array,
+): Uint8Array;
+export declare function sigVerify(
+  publicKey: Uint8Array,
+  message: Uint8Array,
+  signature: Uint8Array,
+): boolean;
+export declare function sigVerifyWithContext(
+  publicKey: Uint8Array,
+  message: Uint8Array,
+  signature: Uint8Array,
+  context: Uint8Array,
+): boolean;
+
+export declare function aeadEncrypt(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array,
+): Uint8Array;
+export declare function aeadDecrypt(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  ciphertext: Uint8Array,
+  aad: Uint8Array,
+): Uint8Array;
+
+export declare function shake256(
+  input: Uint8Array,
+  outputLen: number,
+): Uint8Array;
+export declare function hashUtf8(value: string, outputLen: number): Uint8Array;
+
+export declare function labeledKdf(
+  label: string,
+  ikm: Uint8Array,
+  length: number,
+): Uint8Array;
+export declare function labeledKdf32(
+  label: string,
+  ikm: Uint8Array,
+): Uint8Array;
+
+/**
+ * Argon2id password → 32-byte key. Deliberately slow / memory-hard.
+ * Prefer PWHASH.RECOMMENDED_PARAMS unless you have measured otherwise.
+ */
+export declare function pwhashDeriveKey(
+  password: Uint8Array,
+  salt: Uint8Array,
+  params: Argon2Params,
+): Uint8Array;
+/** Cryptographically random 16-byte Argon2id salt. */
+export declare function generateSalt(): Uint8Array;
+/** Same values as PWHASH.RECOMMENDED_PARAMS (WASM mirror). */
+export declare function RECOMMENDED_PARAMS(): Argon2Params;
+
+/** CBOM attach point: usage from the last WASM primitive call, or undefined. */
+export declare function getLastUsageRecord(): CryptoUsageRecord | undefined;
+
+/** CAST self-tests; rejects with SelfTestFailureError (`err.name`). */
+export declare function runSelfTests(): Promise<void>;
+
+/**
+ * Overwrite buffer bytes in place. WASM Drop zeroization does not apply to
+ * secret material copied into JS Uint8Arrays — call this when finished.
+ */
+export declare function zeroize(buf: Uint8Array): void;

package/dist/nodejs/index.js

@@ -0,0 +1,54 @@
+/**
+ * @enclave-technologies/pqc-primitives — algorithm-only façade (nodejs).
+ *
+ * Category 5 exclusively (ML-KEM-1024 / ML-DSA-87). No suite parameter.
+ *
+ * Secret zeroization does NOT cross the WASM boundary. Call zeroize(buf) on
+ * long-lived secret Uint8Arrays when finished.
+ */
+export {
+  AEAD,
+  ENCLAVE_PQ_SUITE_ID,
+  HASH,
+  KDF_LABEL_PREFIX,
+  KEM,
+  PWHASH,
+  SIG,
+  isPairwiseConsistencyFailure,
+  isSelfTestFailure,
+} from "./constants.js";
+
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const wasm = require("./enclave_pqc_primitives_wasm.cjs");
+
+export const aeadDecrypt = wasm.aeadDecrypt;
+export const aeadEncrypt = wasm.aeadEncrypt;
+export const getLastUsageRecord = wasm.getLastUsageRecord;
+export const hashUtf8 = wasm.hashUtf8;
+export const kemDecapsulate = wasm.kemDecapsulate;
+export const kemEncapsulate = wasm.kemEncapsulate;
+/** Hazmat — KATs only. Prefer kemEncapsulate in production. */
+export const kemEncapsulateDeterministic = wasm.kemEncapsulateDeterministic;
+export const kemExpandedSecretKey = wasm.kemExpandedSecretKey;
+export const kemGenerateKeypair = wasm.kemGenerateKeypair;
+export const kemKeypairFromSeed = wasm.kemKeypairFromSeed;
+export const labeledKdf = wasm.labeledKdf;
+export const labeledKdf32 = wasm.labeledKdf32;
+export const pwhashDeriveKey = wasm.pwhashDeriveKey;
+export const generateSalt = wasm.generateSalt;
+export const RECOMMENDED_PARAMS = wasm.RECOMMENDED_PARAMS;
+export const shake256 = wasm.shake256;
+export const sigExpandedSecretKey = wasm.sigExpandedSecretKey;
+export const sigGenerateKeypair = wasm.sigGenerateKeypair;
+export const sigKeypairFromSeed = wasm.sigKeypairFromSeed;
+export const sigSign = wasm.sigSign;
+export const sigSignWithContext = wasm.sigSignWithContext;
+export const sigVerify = wasm.sigVerify;
+export const sigVerifyWithContext = wasm.sigVerifyWithContext;
+export const zeroize = wasm.zeroize;
+
+/** Run CAST self-tests; throws SelfTestFailureError on failure. */
+export async function runSelfTests() {
+  wasm.runSelfTests();
+}

package/dist/web/constants.js

@@ -0,0 +1,63 @@
+/** @type {const} */
+export const ENCLAVE_PQ_SUITE_ID = "ENCLAVE_PQ_SUITE_v1";
+/** @type {const} */
+export const KDF_LABEL_PREFIX = "enclave-kdf-v1";
+/** @type {const} */
+export const KEM = Object.freeze({
+  ALGORITHM: "ML-KEM-1024",
+  PUBLIC_KEY_BYTES: 1568,
+  SECRET_KEY_SEED_BYTES: 64,
+  SECRET_KEY_EXPANDED_BYTES: 3168,
+  SECRET_KEY_BYTES: 3168,
+  CIPHERTEXT_BYTES: 1568,
+  SHARED_SECRET_BYTES: 32,
+  ENCAP_RANDOMNESS_BYTES: 32,
+});
+/** @type {const} */
+export const SIG = Object.freeze({
+  ALGORITHM: "ML-DSA-87",
+  PUBLIC_KEY_BYTES: 2592,
+  SECRET_KEY_SEED_BYTES: 32,
+  SECRET_KEY_EXPANDED_BYTES: 4896,
+  SECRET_KEY_BYTES: 4896,
+  SIGNATURE_BYTES: 4627,
+  MAX_CONTEXT_BYTES: 255,
+});
+/** @type {const} */
+export const AEAD = Object.freeze({
+  ALGORITHM: "AES-256-GCM",
+  KEY_BYTES: 32,
+  NONCE_BYTES: 12,
+  TAG_BYTES: 16,
+});
+/** @type {const} */
+export const HASH = Object.freeze({
+  ALGORITHM: "SHAKE256",
+  DEFAULT_OUTPUT_BYTES: 32,
+});
+/** @type {const} */
+export const PWHASH = Object.freeze({
+  ALGORITHM: "Argon2id",
+  SALT_BYTES: 16,
+  OUTPUT_BYTES: 32,
+  /**
+   * OWASP Password Storage Cheat Sheet baseline (verified 2026-07-14):
+   * m=19456 (19 MiB), t=2, p=1. Deliberately slow + memory-hard — do not
+   * lower these for login latency without treating that as a security tradeoff.
+   */
+  RECOMMENDED_PARAMS: Object.freeze({
+    memoryCostKib: 19456,
+    iterations: 2,
+    parallelism: 1,
+  }),
+});
+
+/** @param {unknown} err */
+export function isPairwiseConsistencyFailure(err) {
+  return err instanceof Error && err.name === "PairwiseConsistencyFailureError";
+}
+
+/** @param {unknown} err */
+export function isSelfTestFailure(err) {
+  return err instanceof Error && err.name === "SelfTestFailureError";
+}