@lib-q/prf 0.0.2

package/README.md

@@ -0,0 +1,32 @@
+# lib-q-prf
+
+Legendre and Gold (power-residue) pseudorandom functions over prime fields \(\mathbb{F}_p\), using **safe-prime** pilot moduli and constant-time arithmetic via [`crypto_bigint`](https://github.com/RustCrypto/crypto-bigint) (`modular::FixedMontyForm` with `MontyParams<U256>` / `MontyParams<U512>`).
+
+## Scope
+
+- **Legendre PRF:** \(L_K(x)=\left(\frac{x+K}{p}\right)\) with explicit [`PrfError::ZeroInput`](src/error.rs) when \(x+K\equiv 0 \pmod p\).
+- **Gold PRF:** \(\mathrm{Gold}_k(x)=(k+x)^g \bmod p\) with pilot \(g=(p-1)/2\) for safe primes \(p=2q+1\).
+- **Key derivation:** domain-separated `SHAKE256` expansion into \([1,p)\) (see [`shake.rs`](src/shake.rs)).
+
+This crate does **not** implement full anonymous ring signatures; [`lib-q-ring-sig`](../lib-q-ring-sig/) may compose these PRFs behind the `pilot-insecure-prf-transcript` feature for **non-shipping** transcript experiments (see that crate’s module docs).
+
+## Features
+
+| Feature | Purpose |
+| ------- | ------- |
+| `alloc` (default) | Enables `lib-q-sha3/alloc` for XOF buffering. |
+| `std` | Pass-through to `alloc`. |
+
+`crypto-bigint/alloc` is intentionally **not** enabled: field elements use fixed-width `U256` / `U512` only.
+
+## Tests and KATs
+
+- [`tests/reference_vectors.txt`](tests/reference_vectors.txt) — hex KATs; regenerate with [`scripts/gen_prf_kat.py`](../scripts/gen_prf_kat.py) (requires SymPy).
+- SHA-256 fingerprints of modulus encodings catch typos in `params.rs`.
+
+## Documentation
+
+See [DESIGN.md](DESIGN.md) for assumptions, extension-field caveats, and safe-prime provenance.
+
+## Subresource integrity (SHA-384)
+Paths in `integrity-manifest.json` are relative to the package root.

package/integrity-manifest.json

@@ -0,0 +1,6 @@
+{
+  "integrity": {
+    "nodejs/lib_q_prf_bg.wasm": "sha384-3Y7hHhJrBrTDmyZRiudoa5awaMcPzfKiUA/fQMfMelBFiJMfhFKovkTBWRNqyXsf",
+    "web/lib_q_prf_bg.wasm": "sha384-3Y7hHhJrBrTDmyZRiudoa5awaMcPzfKiUA/fQMfMelBFiJMfhFKovkTBWRNqyXsf"
+  }
+}

package/nodejs/README.md

@@ -0,0 +1,29 @@
+# lib-q-prf
+
+Legendre and Gold (power-residue) pseudorandom functions over prime fields \(\mathbb{F}_p\), using **safe-prime** pilot moduli and constant-time arithmetic via [`crypto_bigint`](https://github.com/RustCrypto/crypto-bigint) (`modular::FixedMontyForm` with `MontyParams<U256>` / `MontyParams<U512>`).
+
+## Scope
+
+- **Legendre PRF:** \(L_K(x)=\left(\frac{x+K}{p}\right)\) with explicit [`PrfError::ZeroInput`](src/error.rs) when \(x+K\equiv 0 \pmod p\).
+- **Gold PRF:** \(\mathrm{Gold}_k(x)=(k+x)^g \bmod p\) with pilot \(g=(p-1)/2\) for safe primes \(p=2q+1\).
+- **Key derivation:** domain-separated `SHAKE256` expansion into \([1,p)\) (see [`shake.rs`](src/shake.rs)).
+
+This crate does **not** implement full anonymous ring signatures; [`lib-q-ring-sig`](../lib-q-ring-sig/) may compose these PRFs behind the `pilot-insecure-prf-transcript` feature for **non-shipping** transcript experiments (see that crate’s module docs).
+
+## Features
+
+| Feature | Purpose |
+| ------- | ------- |
+| `alloc` (default) | Enables `lib-q-sha3/alloc` for XOF buffering. |
+| `std` | Pass-through to `alloc`. |
+
+`crypto-bigint/alloc` is intentionally **not** enabled: field elements use fixed-width `U256` / `U512` only.
+
+## Tests and KATs
+
+- [`tests/reference_vectors.txt`](tests/reference_vectors.txt) — hex KATs; regenerate with [`scripts/gen_prf_kat.py`](../scripts/gen_prf_kat.py) (requires SymPy).
+- SHA-256 fingerprints of modulus encodings catch typos in `params.rs`.
+
+## Documentation
+
+See [DESIGN.md](DESIGN.md) for assumptions, extension-field caveats, and safe-prime provenance.

package/nodejs/lib_q_prf.d.ts

@@ -0,0 +1,552 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Algorithm identifiers for cryptographic operations
+ */
+export enum Algorithm {
+    MlKem512 = 0,
+    MlKem768 = 1,
+    MlKem1024 = 2,
+    CbKem348864 = 3,
+    CbKem460896 = 4,
+    CbKem6688128 = 5,
+    CbKem6960119 = 6,
+    CbKem8192128 = 7,
+    Hqc128 = 8,
+    Hqc192 = 9,
+    Hqc256 = 10,
+    MlDsa44 = 11,
+    MlDsa65 = 12,
+    MlDsa87 = 13,
+    FnDsa = 14,
+    FnDsa512 = 15,
+    FnDsa1024 = 16,
+    SlhDsaSha256128fRobust = 17,
+    SlhDsaSha256192fRobust = 18,
+    SlhDsaSha256256fRobust = 19,
+    SlhDsaShake256128fRobust = 20,
+    SlhDsaShake256192fRobust = 21,
+    SlhDsaShake256256fRobust = 22,
+    Shake128 = 23,
+    Shake256 = 24,
+    CShake128 = 25,
+    CShake256 = 26,
+    Sha3_224 = 27,
+    Sha3_256 = 28,
+    Sha3_384 = 29,
+    Sha3_512 = 30,
+    Keccak224 = 31,
+    Keccak256 = 32,
+    Keccak384 = 33,
+    Keccak512 = 34,
+    Kt128 = 35,
+    Kt256 = 36,
+    TurboShake128 = 37,
+    TurboShake256 = 38,
+    Kmac128 = 39,
+    Kmac256 = 40,
+    TupleHash128 = 41,
+    TupleHash256 = 42,
+    ParallelHash128 = 43,
+    ParallelHash256 = 44,
+    Sha224 = 45,
+    Sha256 = 46,
+    Sha384 = 47,
+    Sha512 = 48,
+    Sha512_224 = 49,
+    Sha512_256 = 50,
+    Saturnin = 51,
+    Shake256Aead = 52,
+    DuplexSpongeAead = 53,
+    TweakAead = 54,
+    RomulusN = 55,
+    RomulusM = 56,
+    /**
+     * Privacy-protocol identifiers (not standalone KEM/sig/hash providers).
+     */
+    LatticeRingSignature = 57,
+    LatticeBlindIssuance = 58,
+    LatticeAnonymousToken = 59,
+    LatticeNullifierRegistry = 60,
+    /**
+     * Witness-derived nullifier mode (SHAKE256 over opening witness wire; see `lib-q-lattice-zkp`).
+     */
+    LatticeWitnessNullifier = 61,
+    /**
+     * DualRing-LB (CCS 2021 Alg. 3 aggregated verify on Ajtai openings, `lib-q-ring-sig`).
+     */
+    LatticeDualRingLb = 62,
+    /**
+     * ML-KEM-768 layered encapsulation with Saturnin AEAD per hop (mix-layer transport).
+     */
+    MixOnionRouting = 63,
+    /**
+     * SHAKE256 session token and stateless retry-cookie derivation for resumption handshakes.
+     */
+    SessionResumptionBinding = 64,
+}
+
+/**
+ * Algorithm categories
+ */
+export enum AlgorithmCategory {
+    Kem = 0,
+    Signature = 1,
+    Hash = 2,
+    Aead = 3,
+    /**
+     * Anonymous credentials, mix-layer transport helpers, and related ZKP-adjacent protocols.
+     */
+    PrivacyProtocol = 4,
+}
+
+/**
+ * WASM-compatible hash result
+ */
+export class HashResultWasm {
+    free(): void;
+    [Symbol.dispose](): void;
+    constructor(hash: Uint8Array, algorithm: string);
+    readonly algorithm: string;
+    readonly hash: Uint8Array;
+}
+
+/**
+ * KEM keypair with automatic memory zeroization
+ */
+export class KemKeypair {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create a new KEM keypair from bytes for WASM
+     */
+    constructor(public_key: Uint8Array, secret_key: Uint8Array);
+    /**
+     * Get the public key as bytes for WASM
+     */
+    public_key_bytes(): Uint8Array;
+    /**
+     * Copy the secret key into a new `Uint8Array` for WASM (avoids returning an owned non-zeroizing `Vec<u8>`).
+     */
+    secret_key_bytes(): Uint8Array;
+}
+
+/**
+ * KEM public key
+ */
+export class KemPublicKey {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Get the key data as bytes for WASM
+     */
+    bytes(): Uint8Array;
+    /**
+     * Create a new KEM public key from bytes for WASM
+     */
+    constructor(data: Uint8Array);
+}
+
+/**
+ * KEM secret key with automatic memory zeroization
+ */
+export class KemSecretKey {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Copy the key material into a new `Uint8Array` for WASM (avoids returning an owned non-zeroizing `Vec<u8>`).
+     */
+    bytes(): Uint8Array;
+    /**
+     * Create a new KEM secret key from bytes for WASM
+     */
+    constructor(data: Uint8Array);
+}
+
+/**
+ * Secure WASM AEAD Context
+ *
+ * This context provides secure AEAD operations with:
+ * - Consistent error handling using Result<T, JsValue>
+ * - Security validation for all inputs
+ * - Protection against timing attacks
+ * - Memory safety with automatic cleanup
+ */
+export class SecureWasmAeadContext {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Decrypt data (Layer A `Result` ABI only; see [`crate::AeadDecryptSemantic`] for Layer B).
+     */
+    decrypt(algorithm: string, key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, associated_data?: Uint8Array | null): any;
+    /**
+     * Encrypt data
+     */
+    encrypt(algorithm: string, key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, associated_data?: Uint8Array | null): any;
+    /**
+     * Get supported algorithms
+     */
+    get_supported_algorithms(): any;
+    /**
+     * Create a new secure WASM AEAD context
+     */
+    constructor();
+}
+
+/**
+ * Secure WASM Hash Context
+ *
+ * This context provides secure hash operations with:
+ * - Consistent error handling using Result<T, JsValue>
+ * - Security validation for all inputs
+ * - Protection against timing attacks
+ * - Memory safety with automatic cleanup
+ */
+export class SecureWasmHashContext {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Get supported algorithms
+     */
+    get_supported_algorithms(): any;
+    /**
+     * Hash data
+     */
+    hash(algorithm: string, data: Uint8Array): any;
+    /**
+     * Create a new secure WASM hash context
+     */
+    constructor();
+}
+
+/**
+ * Secure WASM KEM Context
+ *
+ * This context provides secure KEM operations with:
+ * - Consistent error handling using Result<T, JsValue>
+ * - Security validation for all inputs
+ * - Protection against timing attacks
+ * - Memory safety with automatic cleanup
+ */
+export class SecureWasmKemContext {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Decapsulate a shared secret
+     */
+    decapsulate(algorithm: string, private_key: Uint8Array, ciphertext: Uint8Array): any;
+    /**
+     * Encapsulate a shared secret
+     */
+    encapsulate(algorithm: string, public_key: Uint8Array, randomness?: Uint8Array | null): any;
+    /**
+     * Generate a KEM keypair
+     */
+    generate_keypair(algorithm: string, randomness?: Uint8Array | null): any;
+    /**
+     * Get supported algorithms
+     */
+    get_supported_algorithms(): any;
+    /**
+     * Create a new secure WASM KEM context
+     */
+    constructor();
+}
+
+/**
+ * Secure WASM Signature Context
+ *
+ * This context provides secure signature operations with:
+ * - Consistent error handling using Result<T, JsValue>
+ * - Security validation for all inputs
+ * - Protection against timing attacks
+ * - Memory safety with automatic cleanup
+ */
+export class SecureWasmSignatureContext {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Generate a signature keypair
+     */
+    generate_keypair(algorithm: string, randomness?: Uint8Array | null): any;
+    /**
+     * Get supported algorithms
+     */
+    get_supported_algorithms(): any;
+    /**
+     * Create a new secure WASM signature context
+     */
+    constructor();
+    /**
+     * Sign a message
+     */
+    sign(algorithm: string, private_key: Uint8Array, message: Uint8Array, randomness?: Uint8Array | null): any;
+    /**
+     * Verify a signature
+     */
+    verify(algorithm: string, public_key: Uint8Array, message: Uint8Array, signature: Uint8Array): any;
+}
+
+/**
+ * Security levels for cryptographic algorithms
+ */
+export enum SecurityLevel {
+    Level1 = 1,
+    Level3 = 3,
+    Level4 = 4,
+    Level5 = 5,
+}
+
+/**
+ * Signature keypair with automatic memory zeroization
+ */
+export class SigKeypair {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * Signature public key
+ */
+export class SigPublicKey {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * Signature secret key with automatic memory zeroization
+ */
+export class SigSecretKey {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * WASM-compatible AEAD context wrapper
+ *
+ * This wrapper provides JavaScript-compatible bindings for AEAD operations:
+ * - Integrates with the new modular architecture
+ * - Includes security validation
+ * - Provides consistent error handling
+ * - Supports all AEAD algorithms
+ */
+export class WasmAeadContext {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * WASM-compatible CryptoProvider wrapper
+ *
+ * This wrapper provides JavaScript-compatible bindings for the crypto provider:
+ * - Integrates with the new modular architecture
+ * - Provides consistent error handling
+ * - Supports all cryptographic operations
+ */
+export class WasmCryptoProvider {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * WASM-compatible Hash context wrapper
+ *
+ * This wrapper provides JavaScript-compatible bindings for hash operations:
+ * - Integrates with the new modular architecture
+ * - Includes security validation
+ * - Provides consistent error handling
+ * - Supports all hash algorithms
+ */
+export class WasmHashContext {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * WASM-compatible KEM context wrapper
+ *
+ * This wrapper provides JavaScript-compatible bindings for KEM operations:
+ * - Integrates with the new modular architecture
+ * - Includes security validation
+ * - Provides consistent error handling
+ * - Supports all KEM algorithms
+ */
+export class WasmKemContext {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * Generic WASM key pair implementation
+ */
+export class WasmKeyPairImpl {
+    free(): void;
+    [Symbol.dispose](): void;
+    constructor(public_key: Uint8Array, secret_key: Uint8Array);
+    readonly public_key: Uint8Array;
+    readonly secret_key: Uint8Array;
+}
+
+/**
+ * WASM-compatible provider factory
+ *
+ * This factory provides JavaScript-compatible bindings for creating providers:
+ * - Integrates with the new modular architecture
+ * - Provides consistent error handling
+ * - Supports all provider creation operations
+ */
+export class WasmProviderFactory {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create a new provider manager
+     */
+    static create_provider_manager(): WasmProviderManager;
+    /**
+     * Create a provider manager with specific configuration
+     */
+    static create_provider_manager_with_config(config: string): WasmProviderManager;
+    /**
+     * Get available provider types
+     */
+    static get_available_providers(): string;
+    /**
+     * Validate provider configuration
+     */
+    static validate_provider_config(config: string): boolean;
+}
+
+/**
+ * WASM-compatible provider manager
+ *
+ * This manager provides JavaScript-compatible bindings for provider operations:
+ * - Integrates with the new modular architecture
+ * - Includes security validation
+ * - Provides consistent error handling
+ * - Supports all provider operations
+ */
+export class WasmProviderManager {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * WASM-compatible Signature context wrapper
+ *
+ * This wrapper provides JavaScript-compatible bindings for signature operations:
+ * - Integrates with the new modular architecture
+ * - Includes security validation
+ * - Provides consistent error handling
+ * - Supports all signature algorithms
+ */
+export class WasmSignatureContext {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Generate a keypair for the specified algorithm
+     */
+    generate_keypair(algorithm: string, randomness?: Uint8Array | null): any;
+    /**
+     * Check if an algorithm is supported
+     */
+    is_algorithm_supported(algorithm: string): boolean;
+    /**
+     * Get the security level of the context
+     */
+    security_level(): number;
+    /**
+     * Sign a message using the given secret key
+     */
+    sign(algorithm: string, secret_key_data: Uint8Array, message: Uint8Array, randomness?: Uint8Array | null): Uint8Array;
+    /**
+     * Get supported algorithms
+     */
+    supported_algorithms(): string;
+    /**
+     * Verify a signature using the given public key
+     */
+    verify(algorithm: string, public_key_data: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+}
+
+/**
+ * Convert bytes to hexadecimal string
+ *
+ * This function provides secure hex encoding for WASM:
+ * - Uses constant-time operations where possible
+ * - Handles large data efficiently
+ * - Returns JavaScript string
+ */
+export function bytes_to_hex(data: Uint8Array): string;
+
+/**
+ * Get library information for WASM
+ *
+ * This function provides library metadata for JavaScript consumption
+ */
+export function get_library_info(): string;
+
+/**
+ * Get supported algorithms by category
+ *
+ * This function provides algorithm information for JavaScript
+ */
+export function get_supported_algorithms(): string;
+
+/**
+ * Gold PRF on the 256-bit pilot parameters; inputs are **big-endian** 32-byte field elements.
+ * Returns hex-encoded 32-byte little-endian output residue.
+ */
+export function goldPrfU256BeHex(key_be_hex: string, x_be_hex: string): any;
+
+/**
+ * Convert hexadecimal string to bytes
+ *
+ * This function provides secure hex decoding for WASM:
+ * - Validates hex string format
+ * - Handles errors gracefully
+ * - Returns Uint8Array
+ */
+export function hex_to_bytes(hex: string): Uint8Array;
+
+/**
+ * Check if a feature is available
+ *
+ * This function allows JavaScript to check feature availability
+ */
+export function is_feature_available(feature: string): boolean;
+
+/**
+ * Legendre PRF on the 256-bit pilot modulus; `key` and `x` are **big-endian** 32-byte field elements (64 hex chars each).
+ */
+export function legendrePrfU256BeHex(key_be_hex: string, x_be_hex: string): number;
+
+/**
+ * Generate cryptographically secure random bytes for WASM
+ *
+ * This function provides secure random generation in WASM environments:
+ * - Uses the browser's crypto.getRandomValues() API
+ * - Validates input size to prevent DoS attacks
+ * - Returns Uint8Array for direct JavaScript consumption
+ */
+export function random_bytes(length: number): Uint8Array;
+
+/**
+ * Validate input data for WASM operations
+ *
+ * This function provides comprehensive input validation:
+ * - Checks for null/undefined values
+ * - Validates data size limits
+ * - Ensures data is not empty when required
+ */
+export function validate_input(data: Uint8Array, min_size?: number | null, max_size?: number | null): boolean;