@umbra-privacy/sdk 1.0.0 → 2.0.1

package/dist/interfaces-D2NO6kDD.d.cts

@@ -0,0 +1,997 @@
+import { i as U512BeBytes, S as SubSubBrandedType, f as U256 } from './types-C_V_CaKK.cjs';
+
+/**
+ * BN254 Field Arithmetic Interfaces
+ *
+ * This module defines TypeScript function-type interfaces that abstract modular
+ * arithmetic operations over the BN254 scalar prime field F_r. These interfaces
+ * decouple callers from specific implementations, allowing constant-time,
+ * optimized, or platform-specific variants to be substituted without changes to
+ * calling code.
+ *
+ * @remarks
+ * ## Overview
+ *
+ * Modular arithmetic is the mathematical foundation of elliptic curve cryptography
+ * and zero-knowledge proof systems. Every field operation — addition, subtraction,
+ * multiplication, negation, and inversion — produces a result that is reduced
+ * modulo the field prime `p` and lies in `[0, p-1]`.
+ *
+ * The interfaces defined here are function types (not class or object interfaces),
+ * making them composable and easy to pass as dependencies (dependency injection).
+ * Concrete implementations are provided in `field-arithmetic.ts`.
+ *
+ * ## Constant-Time Considerations
+ *
+ * In cryptographic contexts, arithmetic functions must execute in *constant time*
+ * to prevent timing side-channel attacks. An adversary who can precisely measure
+ * how long an operation takes may recover secret inputs (e.g., private keys or
+ * witness values) if the runtime depends on those inputs.
+ *
+ * Implementations conforming to these interfaces should:
+ * - Avoid data-dependent branching (`if`/`else` on secret data)
+ * - Use uniform execution paths regardless of input values
+ * - Employ bitwise masking instead of conditional selection
+ * - Not short-circuit on special values (e.g., zero or one)
+ *
+ * Note: JavaScript's `bigint` type does not provide hardware-level constant-time
+ * guarantees due to JIT optimization and platform differences. The implementations
+ * in `field-arithmetic.ts` are *constant-operation-count*, which is the practical
+ * standard for safe JavaScript cryptography.
+ *
+ * ## Limb Representation
+ *
+ * The concrete implementations in `field-arithmetic.ts` operate on 256-bit field
+ * elements decomposed into 4 x 64-bit limbs in little-endian order. This
+ * representation enables efficient constant-time arithmetic via native 64-bit
+ * operations and avoids variable-time branches in the BigInt layer.
+ *
+ * See `Bn254FieldElementLimb` for the canonical limb tuple type.
+ *
+ * ## Field Element Sampling
+ *
+ * This module also defines the interface and dependency injection types for the
+ * U512-based BN254 field element sampler, which reduces a 512-bit byte array to
+ * a uniformly distributed field element.
+ *
+ * @see {@link ./field-arithmetic} Concrete constant-time implementations
+ * @see {@link ./types} BN254 field element types and validation
+ * @see {@link ./field-element-sampler} Concrete sampler implementation
+ *
+ * @packageDocumentation
+ * @module math/bn254/interfaces
+ */
+
+/**
+ * The 4-limb (64-bit little-endian) internal representation of a BN254 field element.
+ *
+ * A 256-bit field element is split into four 64-bit `bigint` limbs stored in
+ * little-endian order (least significant limb first):
+ * - `limbs[0]`: bits 0–63   (least significant)
+ * - `limbs[1]`: bits 64–127
+ * - `limbs[2]`: bits 128–191
+ * - `limbs[3]`: bits 192–255 (most significant)
+ *
+ * @remarks
+ * ## Why 4-Limb Representation?
+ *
+ * Native JavaScript `bigint` operations are not constant-time — their runtime
+ * depends on the magnitude of the operands. The 4-limb representation allows
+ * constant-time arithmetic to be implemented by operating on fixed-size 64-bit
+ * chunks independently, using bitwise masking for conditional selection and
+ * carry propagation for addition/subtraction.
+ *
+ * ## Reconstruction Formula
+ *
+ * The bigint value `v` represented by a limb tuple `[l0, l1, l2, l3]` is:
+ * ```
+ * v = l0 + l1 * 2^64 + l2 * 2^128 + l3 * 2^192
+ * ```
+ *
+ * ## Readonly Constraint
+ *
+ * The tuple is `readonly` to prevent accidental in-place mutation of limb arrays,
+ * which could introduce subtle state corruption bugs in arithmetic pipelines.
+ *
+ * @example
+ * ```typescript
+ * import { type Bn254FieldElementLimb } from "@umbra/sdk";
+ *
+ * // The number 1 in limb representation
+ * const one: Bn254FieldElementLimb = [1n, 0n, 0n, 0n];
+ *
+ * // A 65-bit value (spans limbs 0 and 1)
+ * const large: Bn254FieldElementLimb = [
+ *   0xFFFFFFFFFFFFFFFFn, // bits 0-63: all set
+ *   0x0000000000000001n, // bits 64-127: only bit 64 set
+ *   0n,
+ *   0n,
+ * ];
+ * // large represents 2^64 + (2^64 - 1) = 2^65 - 1
+ * ```
+ *
+ * @see {@link ModuloAddFunction} Uses this type internally
+ * @see {@link ./field-arithmetic} The module that uses this representation
+ *
+ * @public
+ */
+type Bn254FieldElementLimb = readonly [bigint, bigint, bigint, bigint];
+/**
+ * A function type for constant-time modular addition over the BN254 scalar field.
+ *
+ * Computes `(a + b) mod p` where `p` is `BN254_FIELD_PRIME`.
+ *
+ * @param a - First operand. Must be in the canonical range `[0, p-1]`.
+ * @param b - Second operand. Must be in the canonical range `[0, p-1]`.
+ * @returns The sum `(a + b) mod p` in the canonical range `[0, p-1]`.
+ *
+ * @remarks
+ * ## Algorithm (Constant-Time)
+ *
+ * A constant-time implementation proceeds as follows, operating on 64-bit limbs:
+ *
+ * 1. **Raw addition**: compute `t = a + b` with carry propagation across all 4 limbs.
+ *    Record whether the sum overflowed 256 bits (`tCarry`).
+ * 2. **Trial subtraction**: compute `d = t - p` with borrow propagation.
+ *    Record whether the subtraction underflowed (`borrow`).
+ * 3. **Constant-time selection**: return `d` if `tCarry == 1` (overflow occurred,
+ *    so `t >= p`) or if `borrow == 0` (no underflow, so `t >= p`); otherwise return `t`.
+ *
+ * No data-dependent branch is taken — the selection is performed using bitwise masking.
+ *
+ * @example
+ * ```typescript
+ * import { bn254ModuloAdd, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * // Basic addition
+ * const sum = bn254ModuloAdd(10n, 20n); // 30n
+ *
+ * // Wrap-around at the field boundary
+ * const nearPrime = BN254_FIELD_PRIME - 1n;
+ * const wrapped = bn254ModuloAdd(nearPrime, 2n); // 1n
+ * ```
+ *
+ * @see {@link ModuloSubFunction} For modular subtraction
+ * @see {@link ModuloMulFunction} For modular multiplication
+ * @see {@link ./field-arithmetic.bn254ModuloAdd} The concrete implementation
+ *
+ * @public
+ */
+type ModuloAddFunction = (a: bigint, b: bigint) => bigint;
+/**
+ * A function type for constant-time modular subtraction over the BN254 scalar field.
+ *
+ * Computes `(a - b) mod p` where `p` is `BN254_FIELD_PRIME`.
+ *
+ * @param a - Minuend. Must be in the canonical range `[0, p-1]`.
+ * @param b - Subtrahend. Must be in the canonical range `[0, p-1]`.
+ * @returns The difference `(a - b) mod p` in the canonical range `[0, p-1]`.
+ *
+ * @remarks
+ * ## Algorithm (Constant-Time)
+ *
+ * A constant-time implementation proceeds as follows, operating on 64-bit limbs:
+ *
+ * 1. **Raw subtraction**: compute `diff = a - b` with borrow propagation across
+ *    all 4 limbs. Record whether underflow occurred (`borrow`).
+ * 2. **Conditional correction**: if `borrow == 1` (underflow), the result is
+ *    negative — add `p` back. The addition of `p` is gated by a bitmask derived
+ *    from `borrow`, so it executes unconditionally in both branches (the mask is
+ *    `0xFFF...F` when correction is needed, `0x000...0` otherwise).
+ *
+ * No data-dependent branch is taken — the correction is performed via bitwise masking.
+ *
+ * @example
+ * ```typescript
+ * import { bn254ModuloSub, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * // Basic subtraction
+ * const diff = bn254ModuloSub(30n, 10n); // 20n
+ *
+ * // Underflow wraps around via field addition
+ * const wrapped = bn254ModuloSub(5n, 10n); // BN254_FIELD_PRIME - 5n
+ * ```
+ *
+ * @see {@link ModuloAddFunction} For modular addition
+ * @see {@link ModuloNegFunction} For modular negation (special case of subtraction)
+ * @see {@link ./field-arithmetic.bn254ModuloSub} The concrete implementation
+ *
+ * @public
+ */
+type ModuloSubFunction = (a: bigint, b: bigint) => bigint;
+/**
+ * A function type for constant-time modular multiplication over the BN254 scalar field.
+ *
+ * Computes `(a * b) mod p` where `p` is `BN254_FIELD_PRIME`.
+ *
+ * @param a - First factor. Must be in the canonical range `[0, p-1]`.
+ * @param b - Second factor. Must be in the canonical range `[0, p-1]`.
+ * @returns The product `(a * b) mod p` in the canonical range `[0, p-1]`.
+ *
+ * @remarks
+ * ## Why Not `(a * b) % p` Directly?
+ *
+ * The naive `(a * b) % p` is NOT constant-time: JavaScript's `bigint` modulo
+ * operation has variable latency that depends on the operand sizes and potentially
+ * their values. For secret-key operations, this leaks timing information.
+ *
+ * ## Montgomery Multiplication
+ *
+ * The standard constant-time approach is Montgomery multiplication. It transforms
+ * values into "Montgomery domain" (`a -> aR mod p`, where `R = 2^256`), performs
+ * multiplication, and transforms back. Within the Montgomery domain, one reduction
+ * step replaces the full modulo operation:
+ *
+ * 1. Convert: `aR = a * R^2 * R^(-1) mod p = MontMul(a, R^2)`
+ * 2. Multiply in Montgomery domain: `abR = MontMul(aR, bR)`
+ * 3. Convert back: `ab = MontMul(abR, 1) mod p`
+ *
+ * The Montgomery reduction step (REDC or CIOS) works exclusively with 64-bit limb
+ * arithmetic and a precomputed constant `p' = -p^(-1) mod 2^64`, making it
+ * constant-time.
+ *
+ * @example
+ * ```typescript
+ * import { bn254ModuloMul, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * const product = bn254ModuloMul(7n, 8n); // 56n
+ *
+ * // All results are reduced mod p
+ * const result = bn254ModuloMul(BN254_FIELD_PRIME - 1n, 2n); // p - 2n
+ * ```
+ *
+ * @see {@link ModuloAddFunction} For modular addition
+ * @see {@link ModuloInvFunction} For multiplicative inverse
+ * @see {@link ./field-arithmetic.bn254ModuloMul} The concrete Montgomery implementation
+ *
+ * @public
+ */
+type ModuloMulFunction = (a: bigint, b: bigint) => bigint;
+/**
+ * A function type for constant-time modular negation over the BN254 scalar field.
+ *
+ * Computes `-a mod p`, which equals `p - a` for non-zero `a` and `0` when `a == 0`.
+ *
+ * @param a - The value to negate. Must be in the canonical range `[0, p-1]`.
+ * @returns `-a mod p` in the canonical range `[0, p-1]`.
+ *
+ * @remarks
+ * ## Formula
+ *
+ * ```
+ * result = (a == 0) ? 0 : (p - a)
+ * ```
+ *
+ * The additive inverse of a field element `a` is the unique element `-a` such that
+ * `a + (-a) ≡ 0 (mod p)`.
+ *
+ * ## Constant-Time Zero Handling
+ *
+ * The special case `a == 0` (where the naive `p - a = p` would be out of range)
+ * must be handled without a data-dependent branch. A constant-time implementation
+ * computes `p - a` unconditionally and then uses bitwise masking to zero out the
+ * result when `a` is zero:
+ * ```
+ * isZero = (a[0] | a[1] | a[2] | a[3]) == 0 ? 1 : 0
+ * result = ctSelect(isZero, 0, p - a)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { bn254ModuloNeg, bn254ModuloAdd, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * const a = 10n;
+ * const negA = bn254ModuloNeg(a); // BN254_FIELD_PRIME - 10n
+ *
+ * // Verify: a + (-a) = 0 (mod p)
+ * const sum = bn254ModuloAdd(a, negA); // 0n
+ *
+ * // Special case: negation of zero is zero
+ * console.log(bn254ModuloNeg(0n) === 0n); // true
+ * ```
+ *
+ * @see {@link ModuloSubFunction} Subtraction generalizes negation
+ * @see {@link ./field-arithmetic.bn254ModuloNeg} The concrete implementation
+ *
+ * @public
+ */
+type ModuloNegFunction = (a: bigint) => bigint;
+/**
+ * A function type for constant-time modular multiplicative inverse over the BN254 field.
+ *
+ * Computes `a^(-1) mod p`, the unique field element satisfying `a * a^(-1) ≡ 1 (mod p)`.
+ *
+ * @param a - The value to invert. Must be in the canonical range `[1, p-1]`.
+ *   Passing `0` is undefined behavior and implementations should throw.
+ * @returns `a^(-1) mod p` in the canonical range `[1, p-1]`.
+ * @throws {Error} If `a === 0n`. Zero has no multiplicative inverse in any field.
+ *
+ * @remarks
+ * ## Mathematical Background
+ *
+ * For a prime field F_p, every non-zero element `a` has a unique multiplicative
+ * inverse by Fermat's Little Theorem:
+ * ```
+ * a^(p-1) ≡ 1 (mod p)   =>   a^(-1) ≡ a^(p-2) (mod p)
+ * ```
+ *
+ * ## Implementation Strategy
+ *
+ * Rather than the Extended Euclidean Algorithm (which has variable-time
+ * data-dependent branches), implementations conforming to this interface should
+ * use Fermat's Little Theorem with square-and-multiply in Montgomery form:
+ *
+ * 1. Convert `a` to Montgomery form: `aM = MontMul(a, R^2)`
+ * 2. Compute `aM^(p-2)` via square-and-multiply (using `montgomeryMulLimbs`)
+ * 3. Convert result back from Montgomery form
+ *
+ * The Montgomery square-and-multiply is NOT constant-time with respect to the
+ * exponent because it branches on bits of `p-2`. However, since `p` is a public
+ * constant (not secret), this is acceptable.
+ *
+ * ## Use Cases
+ *
+ * - Polynomial division (multiply by the inverse of the divisor)
+ * - Computing Lagrange basis polynomials
+ * - Batch inversion via Montgomery's trick
+ *
+ * @example
+ * ```typescript
+ * import { bn254ModuloInv, bn254ModuloMul } from "@umbra/sdk";
+ *
+ * const a = 7n;
+ * const invA = bn254ModuloInv(a);
+ *
+ * // Verify: a * a^(-1) = 1 (mod p)
+ * const product = bn254ModuloMul(a, invA); // 1n
+ *
+ * // Division: b / a = b * a^(-1) mod p
+ * const b = 42n;
+ * const quotient = bn254ModuloMul(b, invA); // 6n (42 / 7)
+ * ```
+ *
+ * @see {@link ModuloMulFunction} For multiplication (used to verify inverse)
+ * @see {@link ./field-arithmetic.bn254ModuloInv} The concrete Fermat-based implementation
+ * @see {@link ./operations.computeBn254ModularInverse} Higher-level branded-type inverse
+ *
+ * @public
+ */
+type ModuloInvFunction = (a: bigint) => bigint;
+/**
+ * Optional dependency injection container for the U512-based BN254 field element sampler.
+ *
+ * Callers may inject custom `modAdd` and `modMul` implementations to override the
+ * default constant-time arithmetic used by `getBn254FieldElementSampler`.
+ * This is useful for:
+ * - **Testing**: inject mock arithmetic that counts invocations or logs values.
+ * - **Optimization**: inject a faster (potentially non-constant-time) implementation
+ *   for non-secret contexts such as test vector generation.
+ * - **Benchmarking**: compare performance of different implementation strategies.
+ *
+ * @remarks
+ * All fields are optional. When a field is omitted, the factory function falls back
+ * to the production constant-time implementations from `field-arithmetic.ts`:
+ * - `modAdd` defaults to `bn254ModuloAdd`
+ * - `modMul` defaults to `bn254ModuloMul`
+ *
+ * @example
+ * ```typescript
+ * import { getBn254FieldElementSampler } from "@umbra/sdk";
+ *
+ * // Override only modMul for testing
+ * let mulCallCount = 0;
+ * const sampler = getBn254FieldElementSampler({
+ *   modMul: (a, b) => {
+ *     mulCallCount++;
+ *     return (a * b) % BN254_FIELD_PRIME; // simple non-CT version for tests
+ *   },
+ * });
+ *
+ * sampler(someInput);
+ * console.log(mulCallCount); // 1 (one multiplication per sampler call)
+ * ```
+ *
+ * @see {@link U512BasedBn254FieldElementSamplerFunction} The sampler function type
+ * @see {@link ModuloAddFunction} The addition function interface
+ * @see {@link ModuloMulFunction} The multiplication function interface
+ *
+ * @public
+ */
+interface U512BasedBn254FieldElementSamplerDeps {
+    /**
+     * Custom modular addition function for `(a + b) mod p`.
+     *
+     * If not provided, defaults to the constant-time `bn254ModuloAdd` implementation
+     * from `field-arithmetic.ts`.
+     *
+     * @see {@link ModuloAddFunction}
+     */
+    readonly modAdd?: ModuloAddFunction;
+    /**
+     * Custom modular multiplication function for `(a * b) mod p`.
+     *
+     * If not provided, defaults to the constant-time `bn254ModuloMul` (Montgomery
+     * multiplication) implementation from `field-arithmetic.ts`.
+     *
+     * @see {@link ModuloMulFunction}
+     */
+    readonly modMul?: ModuloMulFunction;
+}
+/**
+ * A function type for reducing a 512-bit big-endian byte array to a uniformly
+ * distributed BN254 scalar field element.
+ *
+ * @param input - A 512-bit (64-byte) byte array in big-endian order (`U512BeBytes`).
+ *   The caller is responsible for ensuring the input has exactly 64 bytes.
+ * @returns A BN254 scalar field element (as `bigint`) in the canonical range `[0, p-1]`.
+ *
+ * @remarks
+ * ## Purpose
+ *
+ * Cryptographic protocols frequently need to derive field elements from hash outputs
+ * or random byte strings. A 256-bit input would introduce non-negligible bias because
+ * `2^256 mod p != 0` (the top few values of the 256-bit range would be over-represented).
+ * Using a 512-bit input reduces the statistical bias to `2^(-256)`, which is
+ * cryptographically negligible.
+ *
+ * ## Algorithm
+ *
+ * The 512-bit input `h` is split into two 256-bit halves in big-endian byte order:
+ * ```
+ * high = h[0..31]   (most significant 256 bits)
+ * low  = h[32..63]  (least significant 256 bits)
+ * ```
+ *
+ * Each half is independently reduced to `[0, p-1]` using constant-time trial
+ * subtraction. Then the field element is computed as:
+ * ```
+ * result = (high * R + low) mod p
+ * ```
+ * where `R = 2^256 mod p` is a precomputed constant
+ * (`6350874878119819312338956282401532410528162663560392320966563075034087161851n`).
+ *
+ * ## Uniformity Analysis
+ *
+ * The 512-bit input space has `2^512` values; the field has `p ≈ 2^254` elements.
+ * The number of inputs mapping to each field element differs by at most 1, giving
+ * maximum bias of `1 / p ≈ 2^(-254)`, well within cryptographic security bounds.
+ *
+ * ## Constant-Time Guarantees
+ *
+ * Implementations conforming to this interface should use constant-time modular
+ * arithmetic for both the `reduce256` step and the final `high * R + low` computation.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getBn254FieldElementSampler,
+ *   bn254FieldElementSampler,
+ * } from "@umbra/sdk";
+ *
+ * // Using the pre-instantiated default sampler
+ * const input = new Uint8Array(64); // 512 zero bits
+ * assertU512BeBytes(input);
+ * const zero = bn254FieldElementSampler(input);
+ * // zero is 0n (the additive identity of the field)
+ *
+ * // Using the factory for custom arithmetic
+ * const sampler = getBn254FieldElementSampler();
+ * const randomBytes = crypto.getRandomValues(new Uint8Array(64));
+ * assertU512BeBytes(randomBytes);
+ * const fieldElement = sampler(randomBytes);
+ * // fieldElement is a uniformly random element of F_r
+ * ```
+ *
+ * @see {@link U512BasedBn254FieldElementSamplerDeps} Optional dependency injection
+ * @see {@link ./field-element-sampler.getBn254FieldElementSampler} The factory
+ * @see {@link ./field-element-sampler.bn254FieldElementSampler} Pre-instantiated sampler
+ *
+ * @public
+ */
+type U512BasedBn254FieldElementSamplerFunction = (input: U512BeBytes) => bigint;
+
+/**
+ * Curve25519 Base Field Types
+ *
+ * This module defines the branded type and validation primitives for elements
+ * of the Curve25519 base field, whose prime modulus is p = 2^255 - 19.
+ *
+ * ## What is Curve25519?
+ *
+ * Curve25519 is a Montgomery-form elliptic curve designed by Daniel J. Bernstein
+ * for high-performance, side-channel-resistant Diffie-Hellman key exchange. It is
+ * specified in RFC 7748 and underlies two widely deployed cryptographic primitives:
+ *
+ * - **X25519** — Diffie-Hellman key agreement. Used in Umbra for encrypted token
+ *   account key registration (users register an X25519 public key so MXE-encrypted
+ *   balances can be shared with them).
+ * - **Ed25519** — Digital signatures (uses the twisted-Edwards form of the same
+ *   underlying field).
+ *
+ * ## The Base Field GF(p)
+ *
+ * All Curve25519 point coordinates are elements of the prime field GF(p) where:
+ * ```
+ * p = 2^255 - 19
+ *   = 57896044618658097711785492504343953926634992332820282019728792003956564819949
+ * ```
+ *
+ * The near-power-of-two structure of p makes modular reduction especially
+ * efficient: because p ≡ -19 (mod 2^255), any reduction can be expressed as a
+ * small multiply-and-add rather than a full division.
+ *
+ * ## Rescue-XLIX Cipher
+ *
+ * Within the Umbra SDK, field arithmetic over GF(p) is used primarily by the
+ * **Rescue-XLIX block cipher** (see `crypto/rescue-cipher/`). Rescue-XLIX operates
+ * over this same field and is the symmetric cipher used inside Arcium MPC
+ * computations to produce and verify ciphertexts for encrypted Umbra token accounts.
+ *
+ * ## Contrast with BN254
+ *
+ * The SDK also provides `math/bn254/` for the BN254 scalar field
+ * (p ≈ 2^254, ~100-bit security, pairing-friendly). That field is used for
+ * Groth16 ZK proofs and Poseidon hashes. The two fields are **not interchangeable**:
+ * elements of one field are not valid elements of the other.
+ *
+ * ## Branded Types
+ *
+ * `Curve25519FieldElement` is a branded `bigint` subtype. The branding enforces
+ * at compile time that only validated, in-range values are passed to field
+ * arithmetic functions, preventing silent truncation bugs.
+ *
+ * @module math/curve25519/types
+ * @packageDocumentation
+ */
+
+/**
+ * Branded type representing a validated element of the Curve25519 base field
+ * GF(2^255 - 19).
+ *
+ * @remarks
+ * A `Curve25519FieldElement` is a `bigint` that has been verified to lie in the
+ * canonical range [0, p-1] where p = 2^255 - 19. The branding is a
+ * compile-time phantom that prevents unvalidated bigints from being passed
+ * to functions that expect field elements.
+ *
+ * The type sits at the third level of the branded-type hierarchy:
+ * ```
+ * bigint
+ *   └── U256            (branded bigint: 0 ≤ value < 2^256)
+ *         └── Curve25519FieldElement  (branded U256: 0 ≤ value < p)
+ * ```
+ *
+ * Unlike BN254FieldElement (used for Groth16 proofs / Poseidon hashes),
+ * Curve25519FieldElement operates over a **different prime** and must not be
+ * mixed with BN254 arithmetic. Field elements from the two curves are
+ * structurally identical at runtime (both are `bigint`) but semantically
+ * incompatible; the branded type hierarchy enforces this distinction
+ * statically.
+ *
+ * ## Security Properties
+ *
+ * - Provides approximately 128 bits of security for discrete-logarithm problems.
+ * - Curve25519 is designed to resist timing attacks: the prime's structure
+ *   permits implementations with uniform execution paths.
+ * - Used in X25519 (ECDH) for Umbra encrypted token account key registration
+ *   and in Rescue-XLIX for MPC-layer symmetric encryption.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   assertCurve25519FieldElement,
+ *   type Curve25519FieldElement,
+ * } from "@umbra-privacy/sdk";
+ *
+ * // Obtain a branded field element after validation
+ * const raw = 12345n;
+ * assertCurve25519FieldElement(raw, "raw");
+ * const element: Curve25519FieldElement = raw;
+ *
+ * // Type error: plain bigint is not assignable to Curve25519FieldElement
+ * // const bad: Curve25519FieldElement = 12345n; // compile error
+ * ```
+ *
+ * @see {@link assertCurve25519FieldElement} — runtime validator that narrows `bigint` to this type
+ * @see {@link CURVE25519_FIELD_PRIME} — the field prime p = 2^255 - 19
+ * @see https://cr.yp.to/ecdh/curve25519-20060209.pdf — original Curve25519 specification
+ * @see https://www.rfc-editor.org/rfc/rfc7748 — X25519 / X448 RFC
+ *
+ * @public
+ */
+type Curve25519FieldElement = SubSubBrandedType<U256, "Curve25519FieldElement">;
+
+/**
+ * Curve25519 Base Field Arithmetic — Function Type Interfaces
+ *
+ * This module defines TypeScript function-type aliases and dependency-injection
+ * interfaces for modular arithmetic operations over the Curve25519 prime field
+ * GF(p), where p = 2^255 - 19. The interfaces are consumed by the
+ * `math/curve25519/field-arithmetic` implementation module and by the
+ * Rescue-XLIX cipher (`crypto/rescue-cipher/`) which operates over this field.
+ *
+ * ## Purpose of Interface Separation
+ *
+ * Defining arithmetic operations as named function types (rather than
+ * inline signatures) provides three benefits:
+ *
+ * - **Substitutability** — callers can inject alternative implementations
+ *   (e.g., a faster platform-native library, or a simplified test double)
+ *   without changing call sites.
+ * - **Testability** — test suites can supply deterministic stubs.
+ * - **Documentation clarity** — each operation has an unambiguous name and
+ *   a single authoritative description.
+ *
+ * ## Background: Modular Arithmetic over GF(p)
+ *
+ * A **prime field** GF(p) is the set {0, 1, …, p-1} equipped with addition
+ * and multiplication defined modulo p. For the Curve25519 field:
+ * ```
+ * p = 2^255 - 19
+ *   ≈ 5.79 × 10^76
+ * ```
+ *
+ * Every non-zero element has a unique multiplicative inverse; the field
+ * is closed under all four arithmetic operations (with division by zero
+ * being the sole undefined case).
+ *
+ * ## Constant-Time Considerations
+ *
+ * In cryptographic contexts, it is critical that arithmetic operations execute
+ * in constant time to prevent timing side-channel attacks. Implementations
+ * conforming to these interfaces should:
+ *
+ * - Avoid data-dependent branching (if/else on secret data).
+ * - Use uniform execution paths regardless of input values.
+ * - Employ bitwise masking instead of conditional selection.
+ *
+ * Note: true hardware-level constant time cannot be guaranteed in JavaScript
+ * due to JIT compilation and GC pauses. The SDK's implementations are
+ * **constant-operation-count**, which is the practical standard for JS crypto.
+ *
+ * ## 4-Limb Little-Endian Representation
+ *
+ * Because JavaScript `BigInt` operations are not constant-time and can vary
+ * in cost with the magnitude of their operands, the implementations behind
+ * these interfaces decompose each 256-bit field element into four 64-bit
+ * **limbs** stored in little-endian order:
+ *
+ * | Limb index | Bit range       |
+ * | ---------- | --------------- |
+ * | 0          | 0 – 63 (LSB)    |
+ * | 1          | 64 – 127        |
+ * | 2          | 128 – 191       |
+ * | 3          | 192 – 255 (MSB) |
+ *
+ * Operating on fixed-width 64-bit chunks produces uniform BigInt sizes and
+ * therefore uniform execution time, regardless of the numeric magnitude of
+ * the field element being processed.
+ *
+ * ## Relationship to Other Modules
+ *
+ * - **`math/curve25519/types`** — defines `Curve25519FieldElement` (the
+ *   branded output type) and `CURVE25519_FIELD_PRIME`.
+ * - **`math/curve25519/field-arithmetic`** — provides the concrete
+ *   constant-time implementations of the function types defined here.
+ * - **`crypto/rescue-cipher/`** — the Rescue-XLIX block cipher that operates
+ *   over GF(2^255 - 19) and uses these interfaces for field arithmetic.
+ * - **`math/bn254/`** — analogous interfaces for the BN254 scalar field
+ *   (a different prime, different use case — Groth16 proofs and Poseidon hashes).
+ *
+ * @module math/curve25519/interfaces
+ * @packageDocumentation
+ */
+
+/**
+ * 4-limb little-endian representation of a 256-bit Curve25519 field element.
+ *
+ * @remarks
+ * A `Curve25519FieldElementLimb` is a fixed-size tuple `[limb0, limb1, limb2, limb3]`
+ * where each entry is a non-negative `bigint` in the range [0, 2^64 - 1]. The
+ * full 256-bit value is reconstructed as:
+ *
+ * ```
+ * value = limb0
+ *       + limb1 × 2^64
+ *       + limb2 × 2^128
+ *       + limb3 × 2^192
+ * ```
+ *
+ * Little-endian ordering means the **least significant** limb occupies index 0.
+ * This convention matches x86/x64 multi-precision integer layouts and simplifies
+ * carry propagation in hand-rolled addition and subtraction loops.
+ *
+ * ## Why 4 × 64-bit Limbs?
+ *
+ * The Curve25519 prime p = 2^255 - 19 fits in 255 bits, which requires at
+ * least 4 × 64-bit = 256 bits of storage. The fourth limb (index 3) always
+ * has its top bit clear for valid field elements (its maximum value is
+ * 0x7FFFFFFFFFFFFFFF). Using exactly 4 limbs avoids the overhead of a 5-limb
+ * representation while still covering the full field.
+ *
+ * ## Constant-Time Use
+ *
+ * Decomposing a field element into same-sized 64-bit limbs ensures that
+ * BigInt arithmetic on each limb operates on identically-sized values,
+ * keeping per-operation cost uniform regardless of the element's magnitude.
+ *
+ * @example
+ * ```typescript
+ * import type { Curve25519FieldElementLimb } from "@umbra-privacy/sdk";
+ *
+ * // The multiplicative identity 1 in limb representation
+ * const one: Curve25519FieldElementLimb = [1n, 0n, 0n, 0n];
+ *
+ * // A value that uses all four limbs, e.g. 2^192
+ * const highValue: Curve25519FieldElementLimb = [0n, 0n, 0n, 1n];
+ * // Reconstructed: 0 + 0 + 0 + 1 × 2^192 = 2^192
+ * ```
+ *
+ * @public
+ */
+type Curve25519FieldElementLimb = readonly [bigint, bigint, bigint, bigint];
+/**
+ * Function type for constant-time modular addition over GF(2^255 - 19).
+ *
+ * @remarks
+ * Computes the field sum:
+ * ```
+ * result ≡ a + b  (mod p),  where p = 2^255 - 19
+ * ```
+ *
+ * The result always lies in the canonical range [0, p-1]. Implementations
+ * must not return values outside this range, even when a + b overflows 255 bits.
+ *
+ * A constant-time implementation performs the addition unconditionally and
+ * then conditionally subtracts p using bitwise masking — never an `if` branch
+ * on whether the sum exceeded p.
+ *
+ * @param a - First field element. Must be in the canonical range [0, p-1].
+ * @param b - Second field element. Must be in the canonical range [0, p-1].
+ * @returns The canonical field sum `(a + b) mod p`, in range [0, p-1].
+ *
+ * @see {@link Curve25519ModuloSubFunction} — the complementary subtraction type
+ * @see {@link Curve25519ModuloMulFunction} — multiplication type
+ *
+ * @public
+ */
+type Curve25519ModuloAddFunction = (a: bigint, b: bigint) => bigint;
+/**
+ * Function type for constant-time modular subtraction over GF(2^255 - 19).
+ *
+ * @remarks
+ * Computes the field difference:
+ * ```
+ * result ≡ a - b  (mod p),  where p = 2^255 - 19
+ * ```
+ *
+ * When a < b the result would be negative in ordinary arithmetic; in the field
+ * the result wraps around: (a - b) mod p = a - b + p, which is still in [0, p-1].
+ *
+ * A constant-time implementation always computes the subtraction and conditionally
+ * adds back p via a borrow-driven bitmask — never branches on whether a borrow
+ * occurred.
+ *
+ * @param a - Minuend. Must be in the canonical range [0, p-1].
+ * @param b - Subtrahend. Must be in the canonical range [0, p-1].
+ * @returns The canonical field difference `(a - b) mod p`, in range [0, p-1].
+ *
+ * @see {@link Curve25519ModuloAddFunction} — the complementary addition type
+ *
+ * @public
+ */
+type Curve25519ModuloSubFunction = (a: bigint, b: bigint) => bigint;
+/**
+ * Function type for constant-time modular multiplication over GF(2^255 - 19).
+ *
+ * @remarks
+ * Computes the field product:
+ * ```
+ * result ≡ a × b  (mod p),  where p = 2^255 - 19
+ * ```
+ *
+ * Multiplication of two 255-bit numbers produces a 510-bit intermediate product
+ * which must be reduced modulo p before the result is returned. The SDK's
+ * concrete implementation uses schoolbook multiplication followed by Barrett or
+ * direct reduction, rather than Montgomery form (whose conversion overhead is
+ * not amortized in this context).
+ *
+ * @param a - First factor. Must be in the canonical range [0, p-1].
+ * @param b - Second factor. Must be in the canonical range [0, p-1].
+ * @returns The canonical field product `(a × b) mod p`, in range [0, p-1].
+ *
+ * @see {@link Curve25519ModuloPowFunction} — repeated squaring using this operation
+ * @see {@link Curve25519ModuloInvFunction} — inversion via Fermat's little theorem
+ *
+ * @public
+ */
+type Curve25519ModuloMulFunction = (a: bigint, b: bigint) => bigint;
+/**
+ * Function type for modular multiplicative inverse over GF(2^255 - 19).
+ *
+ * @remarks
+ * Computes the multiplicative inverse:
+ * ```
+ * result ≡ a^(-1)  (mod p)   such that  a × result ≡ 1  (mod p)
+ * ```
+ *
+ * The inverse exists for every non-zero field element. By **Fermat's Little
+ * Theorem**, since p is prime:
+ * ```
+ * a^(-1) ≡ a^(p-2)  (mod p)
+ * ```
+ *
+ * Implementations may therefore compute the inverse via modular exponentiation
+ * with exponent p - 2, which costs O(log p) multiplications (≈ 255 squarings
+ * and ~128 multiplications for this specific prime). Alternatively, an extended
+ * Euclidean algorithm can be used if a constant-time variant is available.
+ *
+ * @param a - The field element to invert. Must be in range [1, p-1].
+ *   **Zero has no multiplicative inverse.**
+ * @returns The unique inverse `a^(-1) mod p`, in range [1, p-1].
+ * @throws {Error} When `a === 0n`. Zero has no multiplicative inverse in any field.
+ *
+ * @see {@link Curve25519ModuloPowFunction} — generalized exponentiation used internally
+ *
+ * @public
+ */
+type Curve25519ModuloInvFunction = (a: bigint) => bigint;
+/**
+ * Function type for modular exponentiation over GF(2^255 - 19).
+ *
+ * @remarks
+ * Computes the field power:
+ * ```
+ * result ≡ base^exp  (mod p),  where p = 2^255 - 19
+ * ```
+ *
+ * The standard algorithm is **square-and-multiply** (also known as
+ * binary exponentiation):
+ * 1. Start with `result = 1`.
+ * 2. For each bit of `exp` from LSB to MSB:
+ *    - If the bit is 1, multiply `result` by the current power of `base`.
+ *    - Square the current power of `base`.
+ * 3. Return `result`.
+ *
+ * This runs in O(log exp) field multiplications. For the full exponent range
+ * of 0 to p-1, that is at most 255 squarings.
+ *
+ * Special cases:
+ * - `base^0 ≡ 1 (mod p)` for all `base` (including `base = 0`).
+ * - `0^exp ≡ 0 (mod p)` for all `exp > 0`.
+ *
+ * @param base - The base element. Must be in range [0, p-1].
+ * @param exp - The exponent. Must be a non-negative `bigint`.
+ * @returns `base^exp mod p`, in range [0, p-1].
+ *
+ * @see {@link Curve25519ModuloInvFunction} — uses this with exponent p-2
+ *
+ * @public
+ */
+type Curve25519ModuloPowFunction = (base: bigint, exp: bigint) => bigint;
+/**
+ * Optional dependency-injection bag for {@link U512BasedCurve25519FieldElementSamplerFunction}
+ * factory functions.
+ *
+ * @remarks
+ * The sampler algorithm requires two field operations: modular addition and
+ * modular multiplication. By default it uses the SDK's constant-time
+ * implementations from `math/curve25519/field-arithmetic`. Providing custom
+ * implementations here allows:
+ *
+ * - **Testing** — inject deterministic stubs to isolate sampler logic.
+ * - **Optimization** — swap in a faster native-bigint implementation when
+ *   side-channel resistance is not required (e.g., server-side tooling).
+ * - **Alternative backends** — use a WASM-compiled field library.
+ *
+ * Both fields are optional; any combination of overrides is valid. Fields not
+ * provided fall back to the default SDK implementation.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getCurve25519FieldElementSampler,
+ *   type U512BasedCurve25519FieldElementSamplerDeps,
+ * } from "@umbra-privacy/sdk";
+ *
+ * // Override only multiplication with a naive implementation for testing
+ * const deps: U512BasedCurve25519FieldElementSamplerDeps = {
+ *   modMul: (a, b) => (a * b) % ((1n << 255n) - 19n),
+ * };
+ * const sampler = getCurve25519FieldElementSampler(deps);
+ * ```
+ *
+ * @see {@link getCurve25519FieldElementSampler} — the factory that accepts these deps
+ *
+ * @public
+ */
+interface U512BasedCurve25519FieldElementSamplerDeps {
+    /**
+     * Custom modular addition function to use in place of the SDK default.
+     *
+     * @remarks
+     * If omitted, the factory uses `curve25519ModuloAdd` from
+     * `math/curve25519/field-arithmetic`, which is the constant-time
+     * 4-limb implementation.
+     */
+    readonly modAdd?: Curve25519ModuloAddFunction;
+    /**
+     * Custom modular multiplication function to use in place of the SDK default.
+     *
+     * @remarks
+     * If omitted, the factory uses `curve25519ModuloMul` from
+     * `math/curve25519/field-arithmetic`, which delegates to JavaScript BigInt
+     * multiplication followed by direct modular reduction.
+     */
+    readonly modMul?: Curve25519ModuloMulFunction;
+}
+/**
+ * Function type for sampling a Curve25519 field element from a 512-bit
+ * big-endian byte array.
+ *
+ * @remarks
+ * ## Purpose
+ *
+ * Cryptographic key-derivation and hash-to-field algorithms often produce
+ * 512-bit (64-byte) outputs to ensure statistical uniformity when mapping
+ * into a prime field. Naively taking the output modulo p introduces bias
+ * because 2^512 is not a multiple of p; this function uses a two-step
+ * technique that keeps the bias negligible (below 2^-256).
+ *
+ * ## Algorithm
+ *
+ * Given a 512-bit big-endian byte array `input`:
+ *
+ * 1. **Split** into two 256-bit halves in big-endian order:
+ *    - `high = input[0..31]` (most significant 256 bits)
+ *    - `low  = input[32..63]` (least significant 256 bits)
+ *
+ * 2. **Reduce** each half independently to the canonical range [0, p) using
+ *    constant-time trial subtraction (a single conditional subtract of p).
+ *
+ * 3. **Combine** using the precomputed constant R = 2^256 mod p:
+ *    ```
+ *    result = (high × R + low)  mod p
+ *    ```
+ *    For Curve25519, R = 38 (since 2^256 = 2p + 38, so 2^256 mod p = 38).
+ *
+ * ## Uniformity Analysis
+ *
+ * The input space has 2^512 distinct values. After the hash-and-reduce step,
+ * each of the p ≈ 2^255 field elements is represented by exactly ⌊2^512/p⌋ or
+ * ⌊2^512/p⌋ + 1 input values. The resulting bias is at most 1/p < 2^-254,
+ * which is cryptographically negligible.
+ *
+ * ## Constant-Time Guarantees
+ *
+ * The default implementation is constant-operation-count: reduction and
+ * combination use bitwise masking rather than data-dependent branches.
+ *
+ * @param input - A 512-bit (64-byte) big-endian byte array (`U512BeBytes`).
+ * @returns A `Curve25519FieldElement` in the canonical range [0, p-1].
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   curve25519FieldElementSampler,
+ *   type U512BasedCurve25519FieldElementSamplerFunction,
+ * } from "@umbra-privacy/sdk";
+ *
+ * // 64 zero bytes → deterministic field element
+ * const input = new Uint8Array(64) as U512BeBytes;
+ * const element = curve25519FieldElementSampler(input);
+ * // element is a valid Curve25519FieldElement (== 0n for all-zero input)
+ *
+ * // Typical use: pass the 64-byte output of SHA-512 or BLAKE2b-512
+ * const hashOutput: U512BeBytes = sha512(someData);
+ * const fieldElement = curve25519FieldElementSampler(hashOutput);
+ * ```
+ *
+ * @see {@link getCurve25519FieldElementSampler} — factory that creates instances of this type
+ * @see {@link curve25519FieldElementSampler} — default pre-instantiated sampler
+ *
+ * @public
+ */
+type U512BasedCurve25519FieldElementSamplerFunction = (input: U512BeBytes) => Curve25519FieldElement;
+
+export type { Bn254FieldElementLimb as B, Curve25519FieldElement as C, ModuloInvFunction as M, U512BasedBn254FieldElementSamplerFunction as U, U512BasedCurve25519FieldElementSamplerFunction as a, ModuloSubFunction as b, ModuloAddFunction as c, Curve25519FieldElementLimb as d, Curve25519ModuloAddFunction as e, Curve25519ModuloInvFunction as f, Curve25519ModuloMulFunction as g, Curve25519ModuloPowFunction as h, Curve25519ModuloSubFunction as i, ModuloMulFunction as j, ModuloNegFunction as k, U512BasedBn254FieldElementSamplerDeps as l, U512BasedCurve25519FieldElementSamplerDeps as m };