@maatara/core-pqc-wasm 0.2.0 → 0.4.0

package/README.md

@@ -1,46 +1,46 @@
-# @maatara/core-pqc-wasm
-
-WASM bindings for Ma'atara's Post-Quantum Cryptography toolkit. Exposes Kyber ML‑KEM‑768, Dilithium (ML‑DSA‑65), HKDF‑SHA256, AES‑256‑GCM, and base64url helpers.
-
-- Targets: `web` (browsers) and `bundler` (modern bundlers)
-- Typings: included via wasm-pack generated `.d.ts`
-- Size: ~238 KB `.wasm` (0.1.0), under 500 KB budget
-
-## Install
-
-```bash
-npm install @maatara/core-pqc-wasm
-```
-
-## Usage (direct)
-
-Most projects should depend on the higher-level wrapper `@maatara/core-pqc`. If you need the raw WASM exports:
-
-```js
-import init, {
-  kyber_keygen,
-  kyber_encaps,
-  kyber_decaps,
-  hkdf_sha256,
-  aes_gcm_wrap,
-  aes_gcm_unwrap,
-  dilithium_keygen,
-  dilithium_sign,
-  dilithium_verify,
-} from '@maatara/core-pqc-wasm';
-
-await init();
-const { public_b64u, secret_b64u } = JSON.parse(kyber_keygen());
-```
-
-## Security notes
-
-- Zero‑knowledge: intended for client‑side use; servers should only perform verification.
-- Constant‑time: uses vetted crates (`subtle`, `aes-gcm`).
-- RNG: `getrandom` with `js` feature uses Web Crypto / Node WebCrypto.
-- Provenance: WASM uses pure‑Rust `ml-kem` and `ml-dsa` crates; native builds (not used here) rely on `pqcrypto` (PQClean).
-
-## Build targets
-
-- `wasm-pack build --target web`
-- `wasm-pack build --target bundler`
+# @maatara/core-pqc-wasm
+
+WASM bindings for Ma'atara's Post-Quantum Cryptography toolkit. Exposes Kyber ML‑KEM‑768, Dilithium (ML‑DSA‑65), HKDF‑SHA256, AES‑256‑GCM, and base64url helpers.
+
+- Targets: `web` (browsers) and `bundler` (modern bundlers)
+- Typings: included via wasm-pack generated `.d.ts`
+- Size: ~238 KB `.wasm` (0.1.0), under 500 KB budget
+
+## Install
+
+```bash
+npm install @maatara/core-pqc-wasm
+```
+
+## Usage (direct)
+
+Most projects should depend on the higher-level wrapper `@maatara/core-pqc`. If you need the raw WASM exports:
+
+```js
+import init, {
+  kyber_keygen,
+  kyber_encaps,
+  kyber_decaps,
+  hkdf_sha256,
+  aes_gcm_wrap,
+  aes_gcm_unwrap,
+  dilithium_keygen,
+  dilithium_sign,
+  dilithium_verify,
+} from '@maatara/core-pqc-wasm';
+
+await init();
+const { public_b64u, secret_b64u } = JSON.parse(kyber_keygen());
+```
+
+## Security notes
+
+- Zero‑knowledge: intended for client‑side use; servers should only perform verification.
+- Constant‑time: uses vetted crates (`subtle`, `aes-gcm`).
+- RNG: `getrandom` with `js` feature uses Web Crypto / Node WebCrypto.
+- Provenance: WASM uses pure‑Rust `ml-kem` and `ml-dsa` crates; native builds (not used here) rely on `pqcrypto` (PQClean).
+
+## Build targets
+
+- `wasm-pack build --target web`
+- `wasm-pack build --target bundler`

package/core_pqc_wasm.d.ts

@@ -1,70 +1,78 @@
 /* tslint:disable */
 /* eslint-disable */
-export function kyber_keygen(): string;
-export function kyber_encaps(public_b64u: string): string;
-export function kyber_decaps(secret_b64u: string, kem_ct_b64u: string): string;
-export function hkdf_sha256(secret_b64u: string, info_b64u: string, salt_b64u: string | null | undefined, len: number): string;
-export function aes_gcm_wrap(key_b64u: string, dek_b64u: string, aad_b64u: string): string;
+
 export function aes_gcm_unwrap(key_b64u: string, iv_b64u: string, ct_b64u: string, aad_b64u: string): string;
+
+export function aes_gcm_wrap(key_b64u: string, dek_b64u: string, aad_b64u: string): string;
+
+/**
+ * Create a nonce cache for replay attack prevention
+ * capacity: maximum number of nonces to track
+ * ttl_ms: time-to-live in milliseconds before nonces expire
+ */
+export function create_nonce_cache(capacity: number, ttl_ms: bigint): string;
+
+/**
+ * ML-DSA-65 key generation (FIPS 204 compliant)
+ * Security: Keys are generated using platform CSPRNG
+ */
 export function dilithium_keygen(): string;
+
+/**
+ * ML-DSA-65 signing (FIPS 204 compliant)
+ * Security: Input validation prevents DoS; constant-time operations
+ */
 export function dilithium_sign(message_b64u: string, secret_b64u: string): string;
+
+/**
+ * ML-DSA-65 verification (FIPS 204 compliant)
+ * Security: Input validation prevents DoS; constant-time comparison
+ */
 export function dilithium_verify(message_b64u: string, signature_b64u: string, public_b64u: string): string;
-export function start(): void;
+
+/**
+ * Get elastic hash table configuration for key caching
+ */
+export function elastic_hash_config(capacity: number, load_factor: number): string;
+
+export function hkdf_sha256(secret_b64u: string, info_b64u: string, salt_b64u: string | null | undefined, len: number): string;
+
 export function jcs_canonicalize(json: string): string;
-export function preimage_governance(policy_json: string): string;
+
+export function kyber_decaps(secret_b64u: string, kem_ct_b64u: string): string;
+
+export function kyber_encaps(public_b64u: string): string;
+
+export function kyber_keygen(): string;
+
+/**
+ * Check if a nonce has been seen (for replay prevention)
+ * Returns info about the nonce cache algorithm
+ */
+export function nonce_cache_info(): string;
+
+export function preimage_anchor(user_id: string, root_hex: string, epoch: string, chains_json: string): string;
+
 export function preimage_asset_mint(header_json: string, asset_json: string): string;
+
 export function preimage_asset_transfer(header_json: string): string;
-export function preimage_anchor(user_id: string, root_hex: string, epoch: string, chains_json: string): string;
-export function validate_royalty(receiver: string, bps: number): string;
-export function verify_attestations(msg_b64u: string, attestations_json: string, allowed_public_keys_json?: string | null): string;
 
-export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
-
-export interface InitOutput {
-  readonly memory: WebAssembly.Memory;
-  readonly kyber_keygen: () => [number, number];
-  readonly kyber_encaps: (a: number, b: number) => [number, number];
-  readonly kyber_decaps: (a: number, b: number, c: number, d: number) => [number, number];
-  readonly hkdf_sha256: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
-  readonly aes_gcm_wrap: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
-  readonly aes_gcm_unwrap: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
-  readonly dilithium_keygen: () => [number, number];
-  readonly dilithium_sign: (a: number, b: number, c: number, d: number) => [number, number];
-  readonly dilithium_verify: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
-  readonly start: () => void;
-  readonly jcs_canonicalize: (a: number, b: number) => [number, number];
-  readonly preimage_asset_mint: (a: number, b: number, c: number, d: number) => [number, number];
-  readonly preimage_asset_transfer: (a: number, b: number) => [number, number];
-  readonly preimage_anchor: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
-  readonly validate_royalty: (a: number, b: number, c: number) => [number, number];
-  readonly verify_attestations: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
-  readonly preimage_governance: (a: number, b: number) => [number, number];
-  readonly __wbindgen_exn_store: (a: number) => void;
-  readonly __externref_table_alloc: () => number;
-  readonly __wbindgen_export_2: WebAssembly.Table;
-  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_malloc: (a: number, b: number) => number;
-  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
-  readonly __wbindgen_start: () => void;
-}
-
-export type SyncInitInput = BufferSource | WebAssembly.Module;
+export function preimage_governance(policy_json: string): string;
+
 /**
-* Instantiates the given `module`, which can either be bytes or
-* a precompiled `WebAssembly.Module`.
-*
-* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
-*
-* @returns {InitOutput}
-*/
-export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+ * Compute shortest path verification info for provenance chains
+ * This returns the algorithm parameters for JS-side graph operations
+ */
+export function provenance_path_config(chain_length: number, branches: number): string;
 
 /**
-* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
-* for everything else, calls `WebAssembly.instantiate` directly.
-*
-* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
-*
-* @returns {Promise<InitOutput>}
-*/
-export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;
+ * Get SSSP algorithm configuration for graph verification
+ * nodes: expected number of nodes in the graph
+ */
+export function sssp_config(nodes: number): string;
+
+export function start(): void;
+
+export function validate_royalty(receiver: string, bps: number): string;
+
+export function verify_attestations(msg_b64u: string, attestations_json: string, allowed_public_keys_json?: string | null): string;