/** * RFC 9474 fixes the RSA public exponent at 65537, and so does §6.12's keyset * encoding (`be32(e)`, "MUST equal 65537"). Enforced on every entry point * here as well as at keyset ingestion: `DenomPublic` is a plain object, so * nothing guarantees a value reaching {@link verify} came through the keyset * parser, and with `e = 1` RSAVP1 is the identity map -- the encoded message * *is* a valid signature under any modulus, a universal forgery requiring no * key material at all. */ export declare const RSA_PUBLIC_EXPONENT = 65537n; /** Smallest RSA modulus px402 will touch, in bits (spec §3, §6.13). */ export declare const MIN_MODULUS_BITS = 2048; /** * Largest RSA modulus px402 will touch, in bits. Not a cryptographic bound -- * it caps the allocation an attacker-supplied `n` can induce in * {@link encodeMessage}, and keeps the MGF1 block counter far below 2^32. */ export declare const MAX_MODULUS_BITS = 16384; /** * PSSZERO: the EMSA-PSS salt length is zero, so no salt bytes appear in the * encoding at all. {@link encodeMessage} writes out the `sLen = 0` case * directly (no salt in `M'`, none in `DB`, `dbLen = emLen - hLen - 1`), so * this constant **documents** the ciphersuite and is not a knob: raising it * would change nothing about the encoding while making the constant a lie. * A nonzero salt would also break the refresh cut-and-choose reveal check * (§6.6), which recomputes the wallet's blinded messages byte-exactly. */ export declare const SALT_LEN = 0; /** A denomination's public key: the RSA modulus and public exponent. */ export interface DenomPublic { readonly n: bigint; readonly e: bigint; } /** * A signature that did not verify under a well-formed key. * * Distinct from the `RangeError`s a degenerate key raises, and deliberately * so: §6.5 maps this crate's errors onto x402 `invalidReason`, so a * facilitator forwards the distinction to whoever sent the coin. Reporting a * misloaded keyset as a bad signature would send an operator hunting for a * forged coin. This discloses nothing -- `n` and `e` come from a keyset that * is published and committed on-chain (§4). * * Carries no operand values: the message under signature is a coin public key * and the signature is the coin itself. */ export declare class BadSignatureError extends Error { constructor(); } /** * The one modulus-domain check in this module, and the only place `L` is * defined (spec §6.12, §6.13). Returns `bitlen(n)`. * * Three conditions, in this order -- the order is what the error taxonomy * depends on, so a 16385-bit modulus reports the ceiling rather than the * alignment: * * 1. `bitlen(n) >= 2048`; * 2. `bitlen(n) <= 16384`; * 3. `bitlen(n) % 8 === 0`. * * **Why alignment belongs here rather than in one caller.** `selectSeeded` * draws `ceil(bitlen(n)/8)`-byte candidates and accepts only `r < n`, so the * acceptance rate is `n / 2^(8L)`: at least 1/2 when `bitlen(n)` is a multiple * of 8, and up to 256x worse when it is not, while the draw budget stays at * `floor(16320 / L)`. A 2049-bit modulus fails roughly 83% of blindings, and * because the derivation is deterministic (§6.11) those failures are permanent * per coin index -- the wallet can never retry into success. Enforcing * alignment in the shared check also makes `ceil(bits/8)` and `bits/8` * provably the same function on the whole reachable domain, so the wire width * has one formula in one place. */ export declare function modulusBits(n: bigint): number; /** * `L = ceil(bitlen(N) / 8)` -- the fixed width, in bytes, of every value * modulo `N` this module puts on the wire or into a hash (spec §6.12; * `modulus_len` in RFC 9474). * * Written as `bits / 8` because {@link checkPublic} has just established * `bits % 8 === 0`, which makes that equal to `ceil` on every value that can * reach this line. */ export declare function modulusLen(pk: DenomPublic): number; /** * Encode a value modulo `pk.n` for the wire: `pad(v, L)` from §6.12, i.e. * `I2OSP(v, L)`. Fails rather than truncating if `v` does not fit. * * This is the function to call on `z` before it goes into a `commitmentHash` * (§6.1, §6.6) or an issuer request, and on `σ` before it is stored as a coin. */ export declare function toWire(pk: DenomPublic, v: bigint): Uint8Array; /** * Decode a wire value modulo `pk.n`: `OS2IP(bytes)`, but only if `bytes` is * exactly `L` bytes long. * * The length check is the half that cannot be skipped. RFC 9474 §4.3 step 1 * (`If len(blinded_msg) != modulus_len, raise "unexpected input size"`) exists * because without it a peer submits the 255-byte minimal encoding and the * 256-byte padded encoding of the *same* integer and receives one signature * for two requests an issuer deduplicating on bytes sees as different. A * `blinded < n` check closes that at the integer level only; this closes it at * the byte level. */ export declare function fromWire(pk: DenomPublic, bytes: Uint8Array): bigint; /** * EMSA-PSS-ENCODE (RFC 8017 §9.1.1) with SHA-384, MGF1-SHA-384 and * `sLen = 0`, returned as an integer. * * `modBits` is the bit length of the RSA modulus the encoding is destined for. * The encoding is performed with **`emBits = modBits - 1`**. * * # Do not "correct" the `- 1`. RFC 9474's published text is wrong here. * * RFC 9474 §4.2 step 1 reads verbatim * `encoded_msg = EMSA-PSS-ENCODE(msg, bit_len(n))`. That text is an error. * **RFC Errata ID 9089** corrects it to `bit_len(n) - 1`, with the note that * the published form "causes signatures to fail verification approximately * half the time". RFC 8017 §8.1.1 (`emBits = modBits - 1`) is the correct * authority, and spec §6.13 pins `emBits = bitlen(N) - 1` normatively for * every implementation of this protocol, Rust and TypeScript alike. * * The `- 1` is what keeps `EM < 2^(modBits - 1) <= n`, so the encoded message * stays inside the RSA domain, and it is what makes the signature verifiable * by a stock RSASSA-PSS verifier. * * A test suite that only round-trips its own sign-then-verify will **not** * catch the off-by-one: {@link verify} recomputes the encoding with the same * wrong `emBits`, and about 54% of messages have a clear top bit anyway. That * is why `blind.corpus.test.ts` exists and why the RFC 9474 Appendix A.4 * vector does not replace it (§6.13). * * The output is a pure function of `msg` and `modBits`: nothing here reads a * clock, a counter or an RNG. */ export declare function encodeMessage(msg: Uint8Array, modBits: number): bigint; /** * Blind `msg` under `pk` with a blinding factor derived deterministically * from `ikm` (RFC 9474 §4.1, seeded variant). Returns the blinded message * `z` and the factor `r`. * * `r` is returned rather than only its inverse because the caller stores * nothing: it re-derives `ikm` from the wallet seed (or from a refresh * transfer secret) and calls this again to recover the same `r`. * * # Caller invariant: every `ikm` must be unique (spec §6.13) * * `r = selectSeeded(ikm, N)` is a function of `ikm` **alone** -- `N` is not * bound into the KDF, so two different denominations reached with the same * `ikm` return the *identical* `r`. Reusing a blinding factor across two coins * under the same issuer key is a privacy failure, and nothing in this function * can detect it. Every `(withdraw, coin index)` and every `(refresh session, * target index)` MUST therefore produce a distinct `ikm`; §6.1's per-coin * counter and §6.6's `(attempt, i, j)` indices satisfy this, and any new * caller must establish it independently rather than assume it. * * # Wire encoding * * The returned `blinded` is an integer. Hash it or transmit it only via * {@link toWire}: §6.12 forbids the minimal-length encoding, and roughly 1 * value in 256 has a leading zero byte. */ export declare function blindSeeded(pk: DenomPublic, msg: Uint8Array, ikm: Uint8Array): { blinded: bigint; r: bigint; }; /** * Remove the blinding: `sig = blindSig * r^-1 mod n` (RFC 9474 §4.4 steps * 2-4). * * # This is not RFC 9474 `Finalize`, and the difference is load-bearing * * `Finalize` unblinds **and then verifies**, raising "invalid signature" on * failure (steps 5-6). A caller that skips the verification stores whatever a * malicious or faulty issuer returned as a coin and discovers at spend time * that it is worthless -- after the money is gone. Spec §6.1 step 7 puts * `SigVerify else raise` at the call site; callers who do not want to carry * that obligation should use {@link finalize}. */ export declare function unblind(pk: DenomPublic, blindSig: bigint, r: bigint): bigint; /** * RFC 9474 §4.4 `Finalize`: unblind, **verify**, and emit the signature as a * fixed-width byte string. * * `blindSig` is the issuer's response as it arrived on the wire, so step 1's * length check applies to it. `r` is the wallet's own re-derived blinding * factor, not a wire value, so it stays an integer. The returned `σ` is * `pad(sig, L)` per §6.12 -- the bytes a coin is actually stored and hashed as. */ export declare function finalize(pk: DenomPublic, msg: Uint8Array, blindSig: Uint8Array, r: bigint): Uint8Array; /** * Verify an unblinded signature against `msg`. Returns normally on success * and throws {@link BadSignatureError} on failure. * * Rejects `s < 0` or `s >= n` before doing anything else (RSAVP1's range * check, RFC 8017 §5.2.2): `s + n` satisfies the exponentiation exactly, and a * malleable signature would break every invariant that treats the signature * bytes as part of a coin's identity. */ export declare function verify(pk: DenomPublic, msg: Uint8Array, sig: bigint): void; /** * {@link verify} against a signature as it appears on the wire: exactly * `L = ceil(bitlen(n)/8)` bytes, per §6.12. * * A facilitator checking a coin should use this, not {@link verify}. Two byte * strings that decode to one integer are one signature to `verify` and two * distinct coins to anything that hashes or deduplicates the bytes; rejecting * the non-canonical width here keeps those two views from diverging. */ export declare function verifyBytes(pk: DenomPublic, msg: Uint8Array, sig: Uint8Array): void;