@zkp-auth/core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,293 @@
+/**
+ * Generates a fresh `(privateKey, publicKey)` pair for the ZKP-auth
+ * scheme.
+ *
+ * The `privateKey` is a uniform 32-byte little-endian encoding of a
+ * scalar `n ∈ [1, L)`, drawn via bounded rejection sampling against
+ * the CSPRNG chokepoint `randomBytes32()`. The `publicKey` is the
+ * canonical 32-byte encoding of `n · G`, where `G` is the Ed25519
+ * base point.
+ *
+ * The two outputs are returned as fresh `Uint8Array` instances —
+ * `privateKey` is the accepted CSPRNG draw itself (a copy detached
+ * from Node's internal buffer pool, see `rng.ts`'s `Uint8Array.from`
+ * step), and `publicKey` is produced by `@noble/curves`'s `toBytes()`
+ * which allocates a fresh array. Callers may zero-fill the returned
+ * `privateKey` after use without affecting any other observer
+ * (Requirement 6.4 hygiene; not enforced by this function but
+ * permitted by its allocation contract).
+ *
+ * Failure modes — both surface as `RandomnessError` with
+ * `code === 'RNG_FAILURE'`, never as a partial or zero-padded result
+ * (Requirement 1.5):
+ *
+ * - The underlying `randomBytes32()` throws (CSPRNG anomaly or short
+ *   read). Any error — whether a `RandomnessError` already produced
+ *   by `rng.ts`, or a raw `Error` injected by tests via `vi.mock` —
+ *   is caught and, if not already a `RandomnessError`, re-wrapped as
+ *   one. This mirrors the defense-in-depth pattern in `compute-proof.ts`.
+ * - 256 successive draws all decode to scalars outside `[1, L)`. This
+ *   is statistically impossible under a healthy CSPRNG (≈ `2^-252`
+ *   per draw), so exhaustion is reported as an RNG failure rather
+ *   than as a separate exhaustion-specific error class.
+ *
+ * @returns An object with `privateKey` (32 bytes, encoding a scalar
+ *   in `[1, L)`) and `publicKey` (32 bytes, encoding `privateKey · G`).
+ * @throws RandomnessError When the CSPRNG fails or rejection sampling
+ *   exhausts its 256-iteration bound.
+ */
+declare function generateKeyPair(): {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+
+/**
+ * Generates a fresh 32-byte challenge for a Schnorr-proof
+ * authentication session.
+ *
+ * The returned bytes are drawn from the OS CSPRNG via the library's
+ * single chokepoint (`randomBytes32`) and are statistically
+ * independent of `sessionId` — the parameter exists only so the
+ * caller's wire protocol can validate session-handle shape at a
+ * single, well-defined entry point. See the file-header comment for
+ * the security rationale (Requirement 2.5 / Property 4).
+ *
+ * The returned `Uint8Array` is a fresh allocation, detached from any
+ * internal CSPRNG buffer pool (see `rng.ts`'s `Uint8Array.from` step),
+ * so the caller may zero-fill it after use without affecting any
+ * other observer.
+ *
+ * Failure modes:
+ *
+ * - `InvalidInputError` with `code === 'INVALID_SESSION_ID'` — thrown
+ *   when `sessionId` is not a `Uint8Array`, has length 0, or has
+ *   length greater than 256 bytes. The 1..256-byte inclusive window
+ *   is enforced by `assertUint8ArrayLengthBetween`.
+ * - `RandomnessError` with `code === 'RNG_FAILURE'` — thrown when
+ *   `randomBytes32()` throws (any underlying CSPRNG fault), or when
+ *   the returned buffer is not exactly 32 bytes. In production,
+ *   `rng.ts` wraps both cases before they reach this function; the
+ *   extra length guard and try/catch here are defense-in-depth for
+ *   test-injected mocks (property-13, `vi.mock`). No partial or
+ *   zero-padded challenge is ever returned (Requirement 2.4).
+ *
+ * @param sessionId Caller-supplied session handle. Validated for
+ *   `Uint8Array` shape and a length in the inclusive range
+ *   `[1, 256]`; never read after validation.
+ * @returns A fresh 32-byte CSPRNG-derived `Uint8Array`, independent
+ *   of `sessionId`.
+ * @throws InvalidInputError When `sessionId` fails shape or length
+ *   validation.
+ * @throws RandomnessError When the underlying CSPRNG throws or
+ *   returns a short read.
+ */
+declare function generateChallenge(sessionId: Uint8Array): Uint8Array;
+
+/**
+ * Computes a 64-byte Schnorr proof of knowledge of `privateKey` over
+ * a verifier-chosen `challenge`, with `password` carried as opaque
+ * (and currently unused) metadata for forward-compatibility.
+ *
+ * The returned proof is `R_bytes || s_bytes` (32 bytes each), where
+ * `R = r · G` is the commitment to a fresh CSPRNG-drawn nonce
+ * `r ∈ [1, L)`, and `s = (r + c · x) mod L` is the response, with
+ * `c = int_LE(SHA-512(R || X || challenge)) mod L` and
+ * `x = int_LE(privateKey)` (Requirement 11.1: `x` is derived from
+ * `privateKey` only; `password` does NOT participate).
+ *
+ * The proof verifies under `verify-proof.ts`'s
+ * `s · G == R + c · publicKey` equation when invoked with the
+ * matching `publicKey = x · G` (Property 6 round-trip).
+ *
+ * `password` is validated for shape (Requirement 3.7) but is then
+ * treated as opaque bytes — it is NOT mixed into the scalar `x`, NOT
+ * folded into the Fiat-Shamir transcript, and NOT touched in any
+ * computation past validation (Requirements 3.3, 11.1; Property 10).
+ *
+ * Failure modes:
+ *
+ * - `InvalidInputError` with `code === 'INVALID_PRIVATE_KEY'` —
+ *   `privateKey` is not a `Uint8Array(32)`, OR its little-endian
+ *   decoding is `0`, OR its little-endian decoding is `≥ L`
+ *   (Requirements 3.5, 11.4). The `≥ L` and `=== 0` checks are
+ *   performed on the RAW decoding, not on `reduceScalar`'s output:
+ *   `generateKeyPair` always produces in-range keys, so any
+ *   out-of-range input is an integration error and we surface it
+ *   verbatim rather than silently reduce.
+ * - `InvalidInputError` with `code === 'INVALID_PASSWORD'` —
+ *   `password` is not a `Uint8Array`, or its length exceeds 4096
+ *   bytes (Requirement 3.7). The bound is wide enough to admit any
+ *   reasonable user-supplied password yet rejects payloads large
+ *   enough to suggest accidental data-passing or a DoS attempt.
+ * - `InvalidInputError` with `code === 'INVALID_CHALLENGE'` —
+ *   `challenge` is not a `Uint8Array(32)` (Requirement 3.6).
+ * - `RandomnessError` with `code === 'RNG_FAILURE'` — the underlying
+ *   `randomBytes32()` threw or short-read, OR rejection sampling
+ *   exhausted its 256-iteration bound (Requirement 3.10). No
+ *   partial or zero-padded proof is emitted on this failure path.
+ *
+ * @param privateKey 32-byte little-endian encoding of a scalar in
+ *   `[1, L)`. Never read after `x` is derived; the buffer is not
+ *   wiped by this function (the caller owns its lifecycle).
+ * @param password   Opaque bytes, length `[0, 4096]`. Validated for
+ *   shape and then ignored.
+ * @param challenge  32-byte verifier-chosen challenge, ideally
+ *   produced by `generateChallenge`.
+ * @returns A fresh 64-byte `Uint8Array` carrying `R_bytes || s_bytes`.
+ * @throws InvalidInputError When any input fails shape or range
+ *   validation.
+ * @throws RandomnessError When the CSPRNG throws, returns a short
+ *   read, or rejection sampling exhausts its iteration bound.
+ */
+declare function computeProof(privateKey: Uint8Array, password: Uint8Array, challenge: Uint8Array): Uint8Array;
+
+/**
+ * Verifies a 64-byte Schnorr proof against the registered `publicKey`
+ * and the verifier-chosen `challenge`.
+ *
+ * Returns `true` iff `proof = R_bytes || s_bytes` satisfies the
+ * non-interactive Schnorr equation
+ *
+ *   s · G == R + c · publicKey
+ *
+ * with `c = int_LE(SHA-512(R_bytes || publicKey || challenge)) mod L`
+ * (the Fiat-Shamir scalar pinned in `transcript.ts`, identical to the
+ * one used by `compute-proof.ts`).
+ *
+ * Failure modes:
+ *
+ * - `InvalidInputError` with `code === 'INVALID_PUBLIC_KEY'` —
+ *   `publicKey` is not a `Uint8Array(32)` (Requirement 4.5), OR it
+ *   fails to decode as an Edwards point, OR it decodes to the
+ *   identity point `O = (0, 1)`. The identity-point rejection is the
+ *   one Requirement 4.5 specifically calls out: with `publicKey = O`,
+ *   the verification equation collapses to `s · G == R`, which any
+ *   forger can satisfy by picking any `s` and setting `R = s · G`.
+ * - `InvalidInputError` with `code === 'INVALID_CHALLENGE'` —
+ *   `challenge` is not a `Uint8Array(32)` (Requirement 4.6).
+ * - `InvalidInputError` with `code === 'INVALID_PROOF'` — `proof` is
+ *   not a `Uint8Array(64)` (Requirement 4.6, applied to the proof
+ *   shape).
+ * - Returns `false` (does NOT throw) when:
+ *     • `R_bytes` does not decode to a valid Edwards point
+ *       (Requirement 4.7), OR
+ *     • `s = int_LE(s_bytes) >= L` (Requirement 4.8), OR
+ *     • the verification equation `s · G != R + c · publicKey` does
+ *       not hold (Requirement 4.9, the standard "wrong proof"
+ *       rejection).
+ *
+ *   The silent-`false` returns are deliberate (design "Key design
+ *   decisions → 5–6"): the verify path must NOT distinguish between
+ *   "malformed proof material" and "well-formed but mathematically
+ *   invalid proof" via thrown errors, since that would expose an
+ *   oracle to a prover-side adversary.
+ *
+ * @param publicKey 32-byte Ed25519 point encoding of the registered
+ *   public key. Must decode to a non-identity point.
+ * @param challenge 32-byte verifier-chosen challenge, ideally
+ *   produced by `generateChallenge`.
+ * @param proof     64-byte proof `R_bytes || s_bytes` produced by
+ *   `compute-proof.ts`.
+ * @returns `true` iff the proof satisfies the Schnorr verification
+ *   equation under `(publicKey, challenge)`; `false` for any
+ *   well-typed-but-invalid proof or attacker-tampered proof material.
+ * @throws InvalidInputError When any caller-supplied input fails
+ *   shape, length, decoding, or identity-point validation.
+ */
+declare function verifyProof(publicKey: Uint8Array, challenge: Uint8Array, proof: Uint8Array): boolean;
+
+/**
+ * Stable, machine-readable identifiers attached to every thrown error.
+ *
+ * Callers are expected to pattern-match on `.code` rather than inspect
+ * `.message`, which is for human readers only. The set is closed: adding a
+ * new code is a breaking change to the public API surface.
+ *
+ * - `INVALID_PRIVATE_KEY` — privateKey shape, length, or scalar range invalid.
+ * - `INVALID_PUBLIC_KEY`  — publicKey shape, length, decode, or identity-point.
+ * - `INVALID_CHALLENGE`   — challenge shape or length invalid.
+ * - `INVALID_PROOF`       — proof shape or length invalid (NOT verification failure).
+ * - `INVALID_PASSWORD`    — password shape or length invalid.
+ * - `INVALID_SESSION_ID`  — sessionId shape, empty, or oversize.
+ * - `RNG_FAILURE`         — CSPRNG threw, returned short, or rejection-sampling exhausted.
+ * - `CURVE_ERROR`         — `@noble/curves` raised an unexpected internal error.
+ */
+type ErrorCode = 'INVALID_PRIVATE_KEY' | 'INVALID_PUBLIC_KEY' | 'INVALID_CHALLENGE' | 'INVALID_PROOF' | 'INVALID_PASSWORD' | 'INVALID_SESSION_ID' | 'RNG_FAILURE' | 'CURVE_ERROR';
+/**
+ * Thrown when a public function receives an input that fails shape, length,
+ * encoding, or range validation. The accompanying `.code` indicates which
+ * input was invalid.
+ *
+ * `.name` is set as a readonly class field so it cannot be silently shadowed
+ * by user-land subclasses or by `Error`'s default `'Error'` value.
+ *
+ * @example
+ * try {
+ *   computeProof(privateKey, password, challenge);
+ * } catch (e) {
+ *   if (e instanceof InvalidInputError && e.code === 'INVALID_CHALLENGE') {
+ *     // handle challenge-shape failure
+ *   }
+ * }
+ */
+declare class InvalidInputError extends Error {
+    /** Class name; fixed for all instances. */
+    readonly name = "InvalidInputError";
+    /** Stable, machine-readable identifier for the failing input. */
+    readonly code: ErrorCode;
+    /**
+     * @param code    Stable identifier for the failing input.
+     * @param message Human-readable description; not part of the stable API.
+     */
+    constructor(code: ErrorCode, message: string);
+}
+/**
+ * Thrown when the underlying CSPRNG throws, returns a short read, or when
+ * bounded rejection sampling exhausts its iteration cap (treated as an RNG
+ * anomaly). The library MUST NOT emit a partial output on this failure path.
+ *
+ * `.code` is fixed to `'RNG_FAILURE'`. The optional `cause` carries the
+ * underlying error (e.g. the `node:crypto.randomBytes` throw) for diagnostics.
+ *
+ * `cause` is attached via a structural cast so the assignment works under
+ * any tsconfig `lib` selection that may or may not include
+ * `lib.es2022.error.d.ts` (per design.md).
+ */
+declare class RandomnessError extends Error {
+    /** Class name; fixed for all instances. */
+    readonly name = "RandomnessError";
+    /** Stable, machine-readable identifier; fixed for this class. */
+    readonly code: ErrorCode;
+    /**
+     * @param message Human-readable description; not part of the stable API.
+     * @param options Optional bag carrying the underlying `cause`.
+     */
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when an internal `@noble/curves` operation raises an unexpected
+ * error (e.g. invalid point encoding) on a code path where the library's
+ * contract is to throw rather than return `false`. The verification path's
+ * silent-`false` returns for malformed `R` and out-of-range `s` are
+ * deliberate exceptions to this rule (see design.md, Requirements 4.7, 4.8).
+ *
+ * `.code` is fixed to `'CURVE_ERROR'`. The optional `cause` carries the
+ * underlying noble error for diagnostics.
+ */
+declare class CryptoError extends Error {
+    /** Class name; fixed for all instances. */
+    readonly name = "CryptoError";
+    /** Stable, machine-readable identifier; fixed for this class. */
+    readonly code: ErrorCode;
+    /**
+     * @param message Human-readable description; not part of the stable API.
+     * @param options Optional bag carrying the underlying `cause`.
+     */
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+export { CryptoError, type ErrorCode, InvalidInputError, RandomnessError, computeProof, generateChallenge, generateKeyPair, verifyProof };

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+/**
+ * Generates a fresh `(privateKey, publicKey)` pair for the ZKP-auth
+ * scheme.
+ *
+ * The `privateKey` is a uniform 32-byte little-endian encoding of a
+ * scalar `n ∈ [1, L)`, drawn via bounded rejection sampling against
+ * the CSPRNG chokepoint `randomBytes32()`. The `publicKey` is the
+ * canonical 32-byte encoding of `n · G`, where `G` is the Ed25519
+ * base point.
+ *
+ * The two outputs are returned as fresh `Uint8Array` instances —
+ * `privateKey` is the accepted CSPRNG draw itself (a copy detached
+ * from Node's internal buffer pool, see `rng.ts`'s `Uint8Array.from`
+ * step), and `publicKey` is produced by `@noble/curves`'s `toBytes()`
+ * which allocates a fresh array. Callers may zero-fill the returned
+ * `privateKey` after use without affecting any other observer
+ * (Requirement 6.4 hygiene; not enforced by this function but
+ * permitted by its allocation contract).
+ *
+ * Failure modes — both surface as `RandomnessError` with
+ * `code === 'RNG_FAILURE'`, never as a partial or zero-padded result
+ * (Requirement 1.5):
+ *
+ * - The underlying `randomBytes32()` throws (CSPRNG anomaly or short
+ *   read). Any error — whether a `RandomnessError` already produced
+ *   by `rng.ts`, or a raw `Error` injected by tests via `vi.mock` —
+ *   is caught and, if not already a `RandomnessError`, re-wrapped as
+ *   one. This mirrors the defense-in-depth pattern in `compute-proof.ts`.
+ * - 256 successive draws all decode to scalars outside `[1, L)`. This
+ *   is statistically impossible under a healthy CSPRNG (≈ `2^-252`
+ *   per draw), so exhaustion is reported as an RNG failure rather
+ *   than as a separate exhaustion-specific error class.
+ *
+ * @returns An object with `privateKey` (32 bytes, encoding a scalar
+ *   in `[1, L)`) and `publicKey` (32 bytes, encoding `privateKey · G`).
+ * @throws RandomnessError When the CSPRNG fails or rejection sampling
+ *   exhausts its 256-iteration bound.
+ */
+declare function generateKeyPair(): {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+
+/**
+ * Generates a fresh 32-byte challenge for a Schnorr-proof
+ * authentication session.
+ *
+ * The returned bytes are drawn from the OS CSPRNG via the library's
+ * single chokepoint (`randomBytes32`) and are statistically
+ * independent of `sessionId` — the parameter exists only so the
+ * caller's wire protocol can validate session-handle shape at a
+ * single, well-defined entry point. See the file-header comment for
+ * the security rationale (Requirement 2.5 / Property 4).
+ *
+ * The returned `Uint8Array` is a fresh allocation, detached from any
+ * internal CSPRNG buffer pool (see `rng.ts`'s `Uint8Array.from` step),
+ * so the caller may zero-fill it after use without affecting any
+ * other observer.
+ *
+ * Failure modes:
+ *
+ * - `InvalidInputError` with `code === 'INVALID_SESSION_ID'` — thrown
+ *   when `sessionId` is not a `Uint8Array`, has length 0, or has
+ *   length greater than 256 bytes. The 1..256-byte inclusive window
+ *   is enforced by `assertUint8ArrayLengthBetween`.
+ * - `RandomnessError` with `code === 'RNG_FAILURE'` — thrown when
+ *   `randomBytes32()` throws (any underlying CSPRNG fault), or when
+ *   the returned buffer is not exactly 32 bytes. In production,
+ *   `rng.ts` wraps both cases before they reach this function; the
+ *   extra length guard and try/catch here are defense-in-depth for
+ *   test-injected mocks (property-13, `vi.mock`). No partial or
+ *   zero-padded challenge is ever returned (Requirement 2.4).
+ *
+ * @param sessionId Caller-supplied session handle. Validated for
+ *   `Uint8Array` shape and a length in the inclusive range
+ *   `[1, 256]`; never read after validation.
+ * @returns A fresh 32-byte CSPRNG-derived `Uint8Array`, independent
+ *   of `sessionId`.
+ * @throws InvalidInputError When `sessionId` fails shape or length
+ *   validation.
+ * @throws RandomnessError When the underlying CSPRNG throws or
+ *   returns a short read.
+ */
+declare function generateChallenge(sessionId: Uint8Array): Uint8Array;
+
+/**
+ * Computes a 64-byte Schnorr proof of knowledge of `privateKey` over
+ * a verifier-chosen `challenge`, with `password` carried as opaque
+ * (and currently unused) metadata for forward-compatibility.
+ *
+ * The returned proof is `R_bytes || s_bytes` (32 bytes each), where
+ * `R = r · G` is the commitment to a fresh CSPRNG-drawn nonce
+ * `r ∈ [1, L)`, and `s = (r + c · x) mod L` is the response, with
+ * `c = int_LE(SHA-512(R || X || challenge)) mod L` and
+ * `x = int_LE(privateKey)` (Requirement 11.1: `x` is derived from
+ * `privateKey` only; `password` does NOT participate).
+ *
+ * The proof verifies under `verify-proof.ts`'s
+ * `s · G == R + c · publicKey` equation when invoked with the
+ * matching `publicKey = x · G` (Property 6 round-trip).
+ *
+ * `password` is validated for shape (Requirement 3.7) but is then
+ * treated as opaque bytes — it is NOT mixed into the scalar `x`, NOT
+ * folded into the Fiat-Shamir transcript, and NOT touched in any
+ * computation past validation (Requirements 3.3, 11.1; Property 10).
+ *
+ * Failure modes:
+ *
+ * - `InvalidInputError` with `code === 'INVALID_PRIVATE_KEY'` —
+ *   `privateKey` is not a `Uint8Array(32)`, OR its little-endian
+ *   decoding is `0`, OR its little-endian decoding is `≥ L`
+ *   (Requirements 3.5, 11.4). The `≥ L` and `=== 0` checks are
+ *   performed on the RAW decoding, not on `reduceScalar`'s output:
+ *   `generateKeyPair` always produces in-range keys, so any
+ *   out-of-range input is an integration error and we surface it
+ *   verbatim rather than silently reduce.
+ * - `InvalidInputError` with `code === 'INVALID_PASSWORD'` —
+ *   `password` is not a `Uint8Array`, or its length exceeds 4096
+ *   bytes (Requirement 3.7). The bound is wide enough to admit any
+ *   reasonable user-supplied password yet rejects payloads large
+ *   enough to suggest accidental data-passing or a DoS attempt.
+ * - `InvalidInputError` with `code === 'INVALID_CHALLENGE'` —
+ *   `challenge` is not a `Uint8Array(32)` (Requirement 3.6).
+ * - `RandomnessError` with `code === 'RNG_FAILURE'` — the underlying
+ *   `randomBytes32()` threw or short-read, OR rejection sampling
+ *   exhausted its 256-iteration bound (Requirement 3.10). No
+ *   partial or zero-padded proof is emitted on this failure path.
+ *
+ * @param privateKey 32-byte little-endian encoding of a scalar in
+ *   `[1, L)`. Never read after `x` is derived; the buffer is not
+ *   wiped by this function (the caller owns its lifecycle).
+ * @param password   Opaque bytes, length `[0, 4096]`. Validated for
+ *   shape and then ignored.
+ * @param challenge  32-byte verifier-chosen challenge, ideally
+ *   produced by `generateChallenge`.
+ * @returns A fresh 64-byte `Uint8Array` carrying `R_bytes || s_bytes`.
+ * @throws InvalidInputError When any input fails shape or range
+ *   validation.
+ * @throws RandomnessError When the CSPRNG throws, returns a short
+ *   read, or rejection sampling exhausts its iteration bound.
+ */
+declare function computeProof(privateKey: Uint8Array, password: Uint8Array, challenge: Uint8Array): Uint8Array;
+
+/**
+ * Verifies a 64-byte Schnorr proof against the registered `publicKey`
+ * and the verifier-chosen `challenge`.
+ *
+ * Returns `true` iff `proof = R_bytes || s_bytes` satisfies the
+ * non-interactive Schnorr equation
+ *
+ *   s · G == R + c · publicKey
+ *
+ * with `c = int_LE(SHA-512(R_bytes || publicKey || challenge)) mod L`
+ * (the Fiat-Shamir scalar pinned in `transcript.ts`, identical to the
+ * one used by `compute-proof.ts`).
+ *
+ * Failure modes:
+ *
+ * - `InvalidInputError` with `code === 'INVALID_PUBLIC_KEY'` —
+ *   `publicKey` is not a `Uint8Array(32)` (Requirement 4.5), OR it
+ *   fails to decode as an Edwards point, OR it decodes to the
+ *   identity point `O = (0, 1)`. The identity-point rejection is the
+ *   one Requirement 4.5 specifically calls out: with `publicKey = O`,
+ *   the verification equation collapses to `s · G == R`, which any
+ *   forger can satisfy by picking any `s` and setting `R = s · G`.
+ * - `InvalidInputError` with `code === 'INVALID_CHALLENGE'` —
+ *   `challenge` is not a `Uint8Array(32)` (Requirement 4.6).
+ * - `InvalidInputError` with `code === 'INVALID_PROOF'` — `proof` is
+ *   not a `Uint8Array(64)` (Requirement 4.6, applied to the proof
+ *   shape).
+ * - Returns `false` (does NOT throw) when:
+ *     • `R_bytes` does not decode to a valid Edwards point
+ *       (Requirement 4.7), OR
+ *     • `s = int_LE(s_bytes) >= L` (Requirement 4.8), OR
+ *     • the verification equation `s · G != R + c · publicKey` does
+ *       not hold (Requirement 4.9, the standard "wrong proof"
+ *       rejection).
+ *
+ *   The silent-`false` returns are deliberate (design "Key design
+ *   decisions → 5–6"): the verify path must NOT distinguish between
+ *   "malformed proof material" and "well-formed but mathematically
+ *   invalid proof" via thrown errors, since that would expose an
+ *   oracle to a prover-side adversary.
+ *
+ * @param publicKey 32-byte Ed25519 point encoding of the registered
+ *   public key. Must decode to a non-identity point.
+ * @param challenge 32-byte verifier-chosen challenge, ideally
+ *   produced by `generateChallenge`.
+ * @param proof     64-byte proof `R_bytes || s_bytes` produced by
+ *   `compute-proof.ts`.
+ * @returns `true` iff the proof satisfies the Schnorr verification
+ *   equation under `(publicKey, challenge)`; `false` for any
+ *   well-typed-but-invalid proof or attacker-tampered proof material.
+ * @throws InvalidInputError When any caller-supplied input fails
+ *   shape, length, decoding, or identity-point validation.
+ */
+declare function verifyProof(publicKey: Uint8Array, challenge: Uint8Array, proof: Uint8Array): boolean;
+
+/**
+ * Stable, machine-readable identifiers attached to every thrown error.
+ *
+ * Callers are expected to pattern-match on `.code` rather than inspect
+ * `.message`, which is for human readers only. The set is closed: adding a
+ * new code is a breaking change to the public API surface.
+ *
+ * - `INVALID_PRIVATE_KEY` — privateKey shape, length, or scalar range invalid.
+ * - `INVALID_PUBLIC_KEY`  — publicKey shape, length, decode, or identity-point.
+ * - `INVALID_CHALLENGE`   — challenge shape or length invalid.
+ * - `INVALID_PROOF`       — proof shape or length invalid (NOT verification failure).
+ * - `INVALID_PASSWORD`    — password shape or length invalid.
+ * - `INVALID_SESSION_ID`  — sessionId shape, empty, or oversize.
+ * - `RNG_FAILURE`         — CSPRNG threw, returned short, or rejection-sampling exhausted.
+ * - `CURVE_ERROR`         — `@noble/curves` raised an unexpected internal error.
+ */
+type ErrorCode = 'INVALID_PRIVATE_KEY' | 'INVALID_PUBLIC_KEY' | 'INVALID_CHALLENGE' | 'INVALID_PROOF' | 'INVALID_PASSWORD' | 'INVALID_SESSION_ID' | 'RNG_FAILURE' | 'CURVE_ERROR';
+/**
+ * Thrown when a public function receives an input that fails shape, length,
+ * encoding, or range validation. The accompanying `.code` indicates which
+ * input was invalid.
+ *
+ * `.name` is set as a readonly class field so it cannot be silently shadowed
+ * by user-land subclasses or by `Error`'s default `'Error'` value.
+ *
+ * @example
+ * try {
+ *   computeProof(privateKey, password, challenge);
+ * } catch (e) {
+ *   if (e instanceof InvalidInputError && e.code === 'INVALID_CHALLENGE') {
+ *     // handle challenge-shape failure
+ *   }
+ * }
+ */
+declare class InvalidInputError extends Error {
+    /** Class name; fixed for all instances. */
+    readonly name = "InvalidInputError";
+    /** Stable, machine-readable identifier for the failing input. */
+    readonly code: ErrorCode;
+    /**
+     * @param code    Stable identifier for the failing input.
+     * @param message Human-readable description; not part of the stable API.
+     */
+    constructor(code: ErrorCode, message: string);
+}
+/**
+ * Thrown when the underlying CSPRNG throws, returns a short read, or when
+ * bounded rejection sampling exhausts its iteration cap (treated as an RNG
+ * anomaly). The library MUST NOT emit a partial output on this failure path.
+ *
+ * `.code` is fixed to `'RNG_FAILURE'`. The optional `cause` carries the
+ * underlying error (e.g. the `node:crypto.randomBytes` throw) for diagnostics.
+ *
+ * `cause` is attached via a structural cast so the assignment works under
+ * any tsconfig `lib` selection that may or may not include
+ * `lib.es2022.error.d.ts` (per design.md).
+ */
+declare class RandomnessError extends Error {
+    /** Class name; fixed for all instances. */
+    readonly name = "RandomnessError";
+    /** Stable, machine-readable identifier; fixed for this class. */
+    readonly code: ErrorCode;
+    /**
+     * @param message Human-readable description; not part of the stable API.
+     * @param options Optional bag carrying the underlying `cause`.
+     */
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when an internal `@noble/curves` operation raises an unexpected
+ * error (e.g. invalid point encoding) on a code path where the library's
+ * contract is to throw rather than return `false`. The verification path's
+ * silent-`false` returns for malformed `R` and out-of-range `s` are
+ * deliberate exceptions to this rule (see design.md, Requirements 4.7, 4.8).
+ *
+ * `.code` is fixed to `'CURVE_ERROR'`. The optional `cause` carries the
+ * underlying noble error for diagnostics.
+ */
+declare class CryptoError extends Error {
+    /** Class name; fixed for all instances. */
+    readonly name = "CryptoError";
+    /** Stable, machine-readable identifier; fixed for this class. */
+    readonly code: ErrorCode;
+    /**
+     * @param message Human-readable description; not part of the stable API.
+     * @param options Optional bag carrying the underlying `cause`.
+     */
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+export { CryptoError, type ErrorCode, InvalidInputError, RandomnessError, computeProof, generateChallenge, generateKeyPair, verifyProof };