import { type DenomPublic } from "./blind.js"; import { type Keyset } from "./denom.js"; /** * One `(i, j)` cell of a refresh session: everything the wallet derives for * target denomination `j` under cut-and-choose index `i`. * * Every field is a pure function of `(seed, target, oldPub, j)`. A conforming * wallet persists none of it. */ export interface Derived { /** The X25519 transfer scalar, clamped per RFC 7748 §5. Secret. */ readonly t: Uint8Array; /** `T`: the X25519 base-point multiple of `t`, published in the melt record. */ readonly tPub: Uint8Array; /** The transfer secret `x`. Secret: whoever holds it derives the new coin. */ readonly x: Uint8Array; /** The new coin's Ed25519 secret, `HKDF(x ‖ be32(j), "px402/v1/refresh-coin")`. Secret. */ readonly coin: Uint8Array; /** The new coin's public key -- the message that gets blind-signed. */ readonly coinPub: Uint8Array; /** The blinding factor, `SelectSeeded(HKDF(x ‖ be32(j), "px402/v1/refresh-blind"), N_j)`. */ readonly r: bigint; /** `z(i,j) = Blind(pk_D_j, C'_p(i,j); r(i,j))`, as an integer -- encode it with `toWire`. */ readonly blinded: bigint; } /** * One entry in the blinded-message half of {@link commitHash} and of * {@link linkSigMessage}. * * It carries the denomination's **key**, not a caller-supplied byte width, * because `L_j = bitlen(N_j)/8` is exactly the value §6.12 forbids getting * wrong: taking `L` as a number would let a caller pass the minimal length of * `z` and reintroduce the very bug the fixed-width rule exists to prevent. * * Build one with {@link resolveTarget} wherever a keyset is in hand -- which * is every protocol path, since the wallet verified the keyset against the * on-chain commitment before withdrawing. {@link uncheckedTarget} exists for * conformance fixtures and for consumers holding a single denomination out of * context, and is named for what it does not do. */ export interface BlindedTarget { /** The denomination identifier, hashed with a `be32` length prefix. */ readonly denomId: string; /** The denomination public key `z` was blinded under -- the source of `L`. */ readonly key: DenomPublic; /** The blinded message, as an integer. */ readonly z: bigint; } /** A refresh linking signature that did not verify under the melted coin's key. */ export declare class BadLinkSignatureError extends Error { constructor(); } /** * The checked constructor: resolve `denomId` against `keyset` and bind `z` to * the key that keyset says the id names. * * This is what every protocol path should use. The alternative a consumer * would otherwise invent -- resolving keys by position in the `{D_j}` array -- * is exactly the mis-pairing that would let a wallet re-point a committed * `m(γ,j)` at a richer denomination. Resolution runs the whole keyset * ingestion check first (see `denom.ts`). */ export declare function resolveTarget(keyset: Keyset, denomId: string, z: bigint): BlindedTarget; /** * The unchecked constructor: pair `denomId` with a key the caller resolved * some other way. Whatever produced `key` is responsible for the property * {@link resolveTarget} establishes -- that this id names this key. */ export declare function uncheckedTarget(denomId: string, key: DenomPublic, z: bigint): BlindedTarget; /** * Reject a non-canonical X25519 public key: the top bit must be clear and the * u-coordinate must be strictly less than `p = 2^255 - 19`. * * RFC 7748 §5 has implementations mask the high bit and reduce, so `u`, * `u + p` and `u + 2^255` are one point and three byte strings. Every `T` a * conforming wallet publishes is canonical, so this rejects nothing honest -- * but the melt record is keyed by `T`'s *bytes*, and this is what makes those * bytes name exactly one transfer key. */ export declare function checkCanonicalX25519(u: Uint8Array): void; /** * `s_i = HKDF(c⁰_s ‖ be32(attempt) ‖ be32(i), "px402/v1/refresh-seed")` -- the * per-session seed for cut-and-choose index `i` of melt `attempt` (§6.6). * * Derived, never random. `attempt` comes from `registry.meltAttempt(C⁰_p)`, so * a wallet restored from seed reads it back from the registry rather than * remembering it, recomputes the identical `h_C`, re-requests the session and * receives the **same** `γ`. Both indices are 0-based (§6.6). */ export declare function refreshSeed(oldSecret: Uint8Array, attempt: number, i: number): Uint8Array; /** * Derive one `(i, j)` cell of a refresh session (§6.6): * * ```text * t = HKDF(s_i, "px402/v1/transfer") clamped per RFC 7748 §5 * T = X25519 base-point multiple of t * x = ECDH(t, toX25519_pub(C⁰_p)) * ``` * * then the shared derivation for the coin, `r` and `z`. Call it once per * target with the same `seed` to build one session's row. * * # Caller invariant: `seed` and `oldPub` must be the same coin * * Nothing in the type system ties them together and a mismatch is silent. * `oldPub` MUST be the coin the melt request names as `C⁰_p`, because that is * the only key a recovering wallet has when it walks `/link`. Derive against * some other public key and the arithmetic still succeeds, the issuer still * signs, and the change is simply never found again. */ export declare function refreshDerive(seed: Uint8Array, target: DenomPublic, oldPub: Uint8Array, j: number): Derived; /** * Recover the coin secret and blinding factor for one `(T, j)` cell from the * melted coin's secret -- the right-hand side of the module's identity. * * This is both halves of the same coin in the literal sense: it is a wallet * recovering its own change from its seed (§6.10) and it is the link property * that makes coins non-transferable (§6.6). The returned `r` is what unblinds * the issuer's stored `σ_blind(γ,j)` into a usable coin -- pass it to * `finalize`, which verifies before handing back the signature. * * A caller walking `/link` over untrusted melt records should treat a throw as * "not my coin" and continue, not as a failure of its own state. */ export declare function linkRecover(oldSecret: Uint8Array, tPub: Uint8Array, target: DenomPublic, j: number): { coin: Uint8Array; r: bigint; }; /** * Absorb a list of blinded items using the one item encoding §6.12 fixes for * both commitment hashes: * * ```text * for each item, in the caller's order: * be32(len(denomId)) ‖ denomId ‖ pad(z, L) L = bitlen(N)/8, from the key * ``` * * Nothing sorts, and nothing is length-prefixed that §6.12 says should be * bare: ids are variable-length and carry `be32` prefixes (without one, * `"ab" ‖ "c"` and `"a" ‖ "bc"` absorb identically and the boundary is * forgeable), while `z` is fixed-width at `L` and carries none. * * # Exported because §6.1 and §6.6 must share one encoder * * §6.1's `commitmentDigest` is this encoding hashed once; §6.6's `h_C` is the * same encoding hashed as the second half of a two-part digest that also * covers the transfer keys. `client.ts` builds the former from this function * rather than restating the encoding, exactly as `px402-core`'s `withdraw.rs` * calls `refresh::hash_blinded_items`. A divergence between the two would be * invisible until a wallet's withdraw and refresh disagreed in production, so * there is one implementation and one place to change it. */ export declare function encodeBlindedItems(items: readonly BlindedTarget[]): Uint8Array; /** * The refresh commitment hash `h_C` (§6.6, encoded per §6.12): * * ```text * h_C = SHA-384( SHA-384( T_0 ‖ T_1 ‖ … ‖ T_{κ-1} ) * ‖ SHA-384( for i = 0 … κ-1 (outer, ascending): * for j = 0 … |targets|-1 (inner, ascending): * be32(len(denomId_j)) ‖ denomId_j * ‖ pad(m(i,j), L_j) ) ) * ``` * * Transfer keys are fixed 32-byte values and take **no** length prefix * (§6.12: a redundant prefix is a second encoding of the same value that two * implementations can disagree about). * * # The caller flattens the grid, and this function binds the order * * `blinded` is the κ × |targets| grid already flattened, and the conforming * flattening is **`i` ascending (outer), then `j` ascending (inner)**, both * 0-based. The issuer rebuilds the list the same way; since `h_C` binds the * order, a transposed grid fails the reveal rather than silently succeeding * -- which means an honest melt is forfeited on a hash mismatch that reads * like corruption. `vectors/refresh.json` pins both the conforming digest of * an asymmetric 3 × 2 grid and the digest its transpose produces, precisely * so a port cannot get this right by accident on a square or single-cell * grid. * * # `pad(z, L)`, not a minimal-length encoding * * `L` comes from the denomination key in each {@link BlindedTarget}, never * from the byte length of `z`. `z` is uniform mod `N`, so about 1 value in 256 * has a leading zero byte that a bignum library's natural conversion would * drop; wallet and issuer would then disagree on roughly 0.4% of refreshes. * `toWire` fails rather than truncating. */ export declare function commitHash(tPubs: readonly Uint8Array[], blinded: readonly BlindedTarget[]): Uint8Array; /** * Domain-separation tag prefixed to every `s_L` message: the 21 ASCII bytes * `px402/v1/refresh-link` (§6.3). * * The melted coin's key `c⁰_s` signs more than one thing -- the commit * request, this reveal-step linking signature, the deposit permission at * spend time, the melt authorization. Without a tag, the only thing keeping a * signature made in one context from being replayed as another is that their * encodings happen not to overlap, which is an argument that has to be * re-made every time a message format changes. A constant prefix makes the * separation structural. It is a constant, so §6.12's fixed-width rule * applies: emitted bare, with no length prefix. */ export declare const LINK_SIG_CONTEXT: Uint8Array; /** * One revealed seed of a §6.6 reveal: `s_i` for one row `i ≠ γ`, paired with * its row index. * * `i` travels with `seed` rather than being implied by array position, so * `s_L` binds *which row* each seed opens; without it, re-labelling a seed to * another index would be an unsigned change to what the issuer's consistency * check computes. Build the list with {@link refreshSeed} for every * `i` in `0 … κ-1` except `γ`, in ascending order -- the only order * {@link linkSigMessage} accepts. */ export interface RevealedSeed { /** The cut-and-choose row index this seed opens, `i ≠ γ`. */ readonly i: number; /** `s_i`, exactly as {@link refreshSeed} derives it. Secret. */ readonly seed: Uint8Array; } /** * The exact bytes signed by `s_L`, the refresh linking signature (§6.6 * Reveal, amended), encoded per §6.12: * * ```text * LINK_SIG_CONTEXT 21 bytes, constant, no prefix * ‖ C⁰_p 32 bytes, no prefix * ‖ T_γ 32 bytes, no prefix * ‖ be32(κ-1) number of revealed seeds * ‖ for i ascending, i≠γ: * be32(i) ‖ s_i 4 + 32 bytes, both fixed-width * ‖ be32(count) number of targets that follow * ‖ for j = 0 … count-1, ascending: * be32(len(denomId_j)) ‖ denomId_j variable-length: be32-prefixed * ‖ be32(L_j) ‖ pad(m(γ,j), L_j) L_j = bitlen(N_j)/8 * ``` * * # The revealed seeds, and why leaving them out was a live vulnerability * * **Anything the consistency check depends on must be inside the signature. * Otherwise "signed" does not mean "the wallet committed to this content".** * The issuer's §6.6 check recomputes every row `i ≠ γ` *from the revealed * seeds* and requires the resulting `h_C` to equal the one committed at the * commit step. An earlier revision of this encoding covered `C⁰_p`, `T_γ` * and the `{denomId_j, m(γ,j)}` pairs but not `{s_i}`, which put the check's * own inputs outside its authentication. An active network attacker who * observed a reveal in flight could flip a single byte inside one seed: * `s_L` still verified, the recomputed `h_C` no longer matched, and the * issuer classified the reveal as an *inconsistent signed reveal* -- * forfeited, permanently (an expired or forfeited melt does not restore the * residual, which is what keeps the cut-and-choose from being free to * retry). One flipped byte therefore destroyed a coin's entire residual, * remotely, holding no key material at all. * * With the seeds covered, the same flip breaks `s_L` instead. The reveal is * then merely *unauthenticated*, which §6.6 requires be rejected and * retried, and no melt is burned. * * `be32(i)` accompanies each seed rather than relying on position, so `s_L` * binds *which row* each seed opens -- see {@link assertAscendingSeeds}. The * sequence must arrive in **strictly ascending index order**, which also * makes a duplicate index impossible, and with it the trick of padding * `be32(κ-1)` to the expected width while leaving a row unopened. * * The count is written `be32(κ-1)` because a reveal opens every row but `γ`; * this function does not know `κ` or `γ` to check that claim, only the * length of `seeds` itself. An empty sequence is accepted here rather than * refused: it means `κ = 1`, a degenerate choice of protocol *parameter* * rather than a malformed *encoding*, and the counted layout describes it * unambiguously. The issuer enforces the real constraint (exactly `κ-1` * seeds, none of them `γ`). * * # Why this layout, field by field * * - **The two sequences are interleaved into one sequence of pairs.** §6.6 * lists `{D_j}` and `{m(γ,j)}` as separate sets. Encoding them as two * separate sequences would leave the *pairing* unbound: a reveal could * present `m(γ,0)` against `denomId_1`, asking the issuer to blind-sign a * message under a richer denomination's key than the one it was committed * under. `h_C` happens to bind the pairing too, but a signature whose * safety depends on another value's encoding breaks when that value * changes. * - **`T_γ` is hoisted ahead of the sequences**, out of the tuple's written * order, so every fixed-width field sits at a constant offset and the only * variable-length region is the counted tail. * - **`be32(count)` before each sequence**, per §6.12's rule that every * variable-length sequence carries an explicit count. * - **`be32(len(denomId_j))`**, without which `"ab" ‖ "c"` and `"a" ‖ "bc"` * sign identically and the boundary is forgeable. * - **`be32(L_j)` before `pad(m(γ,j), L_j)`**: `m` is fixed-width *within* a * denomination but variable-width *across* the sequence, so the message * stays parseable with no keyset in hand. The two commitment hashes omit * this prefix because their formulas were already pinned; this encoding is * newer and follows the rule. * * # `attempt` and `γ` are not in the message, and that is safe * * Both are bound transitively through `T_γ`, which is the base-point multiple * of `HKDF(s_γ, "px402/v1/transfer")` for `s_γ = HKDF(c⁰_s ‖ be32(attempt) ‖ * be32(γ), …)`: a given `T` belongs to exactly one `(coin, attempt, i)` and * cannot be replayed into another session. `γ` is additionally pinned by * omission -- it is the one index in `0 … κ-1` the signed seed sequence does * not carry. * * # Zero targets is not a reveal * * `items` must be non-empty. The two commitment hashes deliberately accept an * empty list -- their formulas are pinned and an empty digest is well defined * -- but a linking signature is not a digest, it is an authorization, and an * authorization over nothing has no meaning to give. */ export declare function linkSigMessage(oldPub: Uint8Array, tPub: Uint8Array, seeds: readonly RevealedSeed[], items: readonly BlindedTarget[]): Uint8Array; /** * Produce `s_L`: Ed25519 over {@link linkSigMessage} with the melted coin's * secret (§6.6 Reveal). * * `C⁰_p` is **derived from `oldSecret`**, not taken as an argument. The * message names the coin it authorizes, and letting a caller pass that * separately is a footgun with no upside: the only `C⁰_p` a valid `s_L` can * carry is the one belonging to the signing key, since the issuer verifies * against the `C⁰_p` in the melt record. */ export declare function linkSign(oldSecret: Uint8Array, tPub: Uint8Array, seeds: readonly RevealedSeed[], items: readonly BlindedTarget[]): Uint8Array; /** * The issuer's half of §6.6's Reveal step: verify `s_L` against the melted * coin's public key over the transfer key and blinded messages just revealed. * * # `zip215: false` is load-bearing, not a stylistic option * * This is the TypeScript form of "`verify_strict`, never `verify`". * `@noble/curves` defaults `ed25519.verify` to **ZIP-215**, the permissive * consensus-oriented rule set that accepts non-canonical point encodings and * does not reject a small-order public key. Under it, with `C⁰_p` set to the * compressed Ed25519 identity, the pair `(R = [s]B, S = s)` satisfies the * verification equation for **any** message, because `[k]A` is the identity: * anyone could then produce a valid `s_L` over any reveal whatsoever, holding * no secret at all. * * §6.6 distinguishes an *inconsistent signed reveal* (forfeits the melt) from * an *unauthenticated* one (rejected, retryable, never burns a melt), so the * issuer must be able to tell "this signature is not valid" apart from "this * signature is valid and the contents disagree with `h_C`". A forgeable `s_L` * collapses exactly that distinction, and the melt-forfeit rule is the only * thing standing between the cut-and-choose and a free retry. * * An undecodable or degenerate `C⁰_p` lands in the same refusal rather than a * separate error: both outcomes are "unauthenticated", which is the branch * §6.6 cares about, and both are retryable without burning a melt. * * The issuance-side counterpart is `validateCoinPublic`, which keeps such a * coin from being blind-signed in the first place. This function deliberately * does not call it: `oldPub` arrives from the melt record, and the property * being enforced here is that the *signature check* stands on its own. * * @throws BadLinkSignatureError if the signature does not verify over the * recomputed message -- which covers a tampered `m(γ,j)`, a swapped or * reordered `denomId`, a substituted `T_γ`, a flipped byte in or a * re-indexed revealed seed, and a signature made by another coin. */ export declare function linkVerify(oldPub: Uint8Array, tPub: Uint8Array, seeds: readonly RevealedSeed[], items: readonly BlindedTarget[], sig: Uint8Array): void;