@reclaimprotocol/client 0.1.0-dev.1 → 0.1.0-dev.2

package/lib/index.js

@@ -1,4 +1,12 @@
 export * from "./client.js";
+export { throwProblemError } from "./errors.js";
 export { DEFAULT_BASE_URL, PROBLEM_CONTENT_TYPE, USER_AGENT } from "./consts.js";
-export { deriveFromPrivateKey, generateKeypair, } from "./keypair.js";
-export * from "./types/index.js";
+export { addressFromPublicKey, deriveFromPrivateKey, generateKeypair, } from "./keypair.js";
+export { canonicalJson } from "./canonical.js";
+export { b64url, base64urlToBytes, bytesToHex, hexToBytes, } from "./encoding.js";
+export { addressFromUncompressedPubkey, secp, } from "./secp.js";
+export { decodeJwsPayload, decryptCallback, encryptForPublicJwk, ResultVerificationError, signResultJws, verifyJwsSignature, verifyResult, verifyResultFull, } from "./result.js";
+export { loadDecryptionKey, publicPemToJwk, } from "./enckeys.js";
+export { createReclaim, TERMINAL_EVENTS, } from "./reclaim.js";
+export { fetchJwks, jwksFromPrivateKey, jwkToUncompressedPublicKey, selectKey, } from "./jwks.js";
+export { verifyNestedProof, } from "./attestor-proof.js";

package/lib/jwks.d.ts

@@ -0,0 +1,26 @@
+export interface Jwk {
+    kty: string;
+    crv: string;
+    x: string;
+    y: string;
+    kid?: string;
+    alg?: string;
+    use?: string;
+}
+/**
+ * Build the JWK set for an ES256K signing key (the Verification Client's
+ * result-signing key). `kid` is the key's ETH address; `x`/`y` are the
+ * uncompressed public-key coordinates. Empty set when no key is configured.
+ */
+export declare function jwksFromPrivateKey(privateKeyHex?: string): {
+    keys: Jwk[];
+};
+/** Fetch the JWK set published at `<iss>/.well-known/jwks.json`. */
+export declare function fetchJwks(iss: string, fetchImpl?: typeof fetch): Promise<Jwk[]>;
+/** Find the key matching `kid` (case-insensitive — kids are ETH addresses). */
+export declare function selectKey(keys: Jwk[], kid: string): Jwk | undefined;
+/**
+ * Reconstruct the uncompressed secp256k1 public key (`0x04` + X + Y) from an
+ * EC JWK's base64url `x`/`y` coordinates, for signature verification.
+ */
+export declare function jwkToUncompressedPublicKey(jwk: Jwk): string;

package/lib/jwks.js

@@ -0,0 +1,63 @@
+/**
+ * JWKS (RFC 7517) discovery for verifying result/proof signatures. Signers
+ * (the Verification Client, the Attestor) publish their secp256k1 public keys
+ * at `<iss>/.well-known/jwks.json` with `kid` = the signer's ETH address.
+ */
+import { b64url, base64urlToBytes, bytesToHex } from "./encoding.js";
+import { addressFromUncompressedPubkey, secp } from "./secp.js";
+/**
+ * Build the JWK set for an ES256K signing key (the Verification Client's
+ * result-signing key). `kid` is the key's ETH address; `x`/`y` are the
+ * uncompressed public-key coordinates. Empty set when no key is configured.
+ */
+export function jwksFromPrivateKey(privateKeyHex) {
+    if (!privateKeyHex) {
+        return { keys: [] };
+    }
+    const priv = privateKeyHex.replace(/^0x/, '');
+    const pub = secp.getPublicKey(Uint8Array.from(Buffer.from(priv, 'hex')), false);
+    return {
+        keys: [
+            {
+                kty: 'EC',
+                crv: 'secp256k1',
+                alg: 'ES256K',
+                use: 'sig',
+                kid: addressFromUncompressedPubkey(pub),
+                x: b64url(pub.subarray(1, 33)),
+                y: b64url(pub.subarray(33, 65)),
+            },
+        ],
+    };
+}
+/** Fetch the JWK set published at `<iss>/.well-known/jwks.json`. */
+export async function fetchJwks(iss, fetchImpl = fetch) {
+    const base = iss.replace(/\/+$/, '');
+    const res = await fetchImpl(`${base}/.well-known/jwks.json`);
+    if (!res.ok) {
+        throw new Error(`JWKS fetch failed for ${base}: HTTP ${res.status}`);
+    }
+    const body = (await res.json());
+    return body.keys ?? [];
+}
+/** Find the key matching `kid` (case-insensitive — kids are ETH addresses). */
+export function selectKey(keys, kid) {
+    const want = kid.toLowerCase();
+    return keys.find((k) => (k.kid ?? '').toLowerCase() === want);
+}
+/**
+ * Reconstruct the uncompressed secp256k1 public key (`0x04` + X + Y) from an
+ * EC JWK's base64url `x`/`y` coordinates, for signature verification.
+ */
+export function jwkToUncompressedPublicKey(jwk) {
+    const x = base64urlToBytes(jwk.x);
+    const y = base64urlToBytes(jwk.y);
+    if (x.length !== 32 || y.length !== 32) {
+        throw new Error('invalid EC JWK: x/y must be 32 bytes each');
+    }
+    const out = new Uint8Array(65);
+    out[0] = 0x04;
+    out.set(x, 1);
+    out.set(y, 33);
+    return '0x' + bytesToHex(out);
+}

package/lib/keypair.d.ts

@@ -1,6 +1,10 @@
 export type EthKeypair = {
     address: string;
     privateKey: string;
+    /** Uncompressed secp256k1 public key (`0x04` + 128 hex). Used to derive the
+     *  ETH address and to verify ES256K JWS signatures (published via JWKS as
+     *  `x`/`y`). Result *encryption* now uses X25519 JWE, not this key. */
+    publicKey: string;
 };
 /**
  * Generate a fresh secp256k1 key-pair and derive its lowercase
@@ -19,3 +23,11 @@ export declare function generateKeypair(): EthKeypair;
  * importing a key the user already holds.
  */
 export declare function deriveFromPrivateKey(privateKey: string): EthKeypair;
+/**
+ * Derive the lowercase Ethereum address that owns an uncompressed secp256k1
+ * public key (`0x04` + 128 hex) — keccak-256 of the key minus the `0x04`
+ * prefix byte, last 20 bytes. The holder of the matching private key controls
+ * this address; used to scope a callback subscription to its key's owner
+ * without ever needing the private key.
+ */
+export declare function addressFromPublicKey(publicKey: string): string;

package/lib/keypair.js

@@ -1,4 +1,5 @@
 import { keccak_256 } from '@noble/hashes/sha3.js';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
 import * as secp from '@noble/secp256k1';
 /**
  * Generate a fresh secp256k1 key-pair and derive its lowercase
@@ -15,8 +16,9 @@ export function generateKeypair() {
     const priv = secp.utils.randomSecretKey();
     const pub = secp.getPublicKey(priv, false);
     return {
-        address: '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40),
+        address: addressFromPubBytes(pub),
         privateKey: '0x' + bytesToHex(priv),
+        publicKey: '0x' + bytesToHex(pub),
     };
 }
 /**
@@ -28,24 +30,23 @@ export function deriveFromPrivateKey(privateKey) {
     const priv = hexToBytes(hex);
     const pub = secp.getPublicKey(priv, false);
     return {
-        address: '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40),
+        address: addressFromPubBytes(pub),
         privateKey: '0x' + hex,
+        publicKey: '0x' + bytesToHex(pub),
     };
 }
-function bytesToHex(bytes) {
-    let out = '';
-    for (const b of bytes) {
-        out += b.toString(16).padStart(2, '0');
-    }
-    return out;
+/**
+ * Derive the lowercase Ethereum address that owns an uncompressed secp256k1
+ * public key (`0x04` + 128 hex) — keccak-256 of the key minus the `0x04`
+ * prefix byte, last 20 bytes. The holder of the matching private key controls
+ * this address; used to scope a callback subscription to its key's owner
+ * without ever needing the private key.
+ */
+export function addressFromPublicKey(publicKey) {
+    return addressFromPubBytes(hexToBytes(publicKey.replace(/^0x/, '')));
 }
-function hexToBytes(hex) {
-    if (hex.length % 2 !== 0) {
-        throw new Error('private key hex must have even length');
-    }
-    const out = new Uint8Array(hex.length / 2);
-    for (let i = 0; i < out.length; i++) {
-        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-    }
-    return out;
+/** keccak-256 of the uncompressed pubkey minus its `0x04` prefix byte,
+ *  last 20 bytes — the Ethereum address derivation, lowercase (no checksum). */
+function addressFromPubBytes(pub) {
+    return '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40);
 }

package/lib/reclaim.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Declarative entry point for the consumer SDK. The ONLY config is the org
+ * secret (`rorg_…`) — it authenticates every call and identifies the org
+ * server-side. Everything else is passed where it's actually used: the `orgId`
+ * to the org-scoped `credential.set`/`get`, and the X25519 decryption key to
+ * `results.decrypt`/`receive` (only when results arrive encrypted):
+ *
+ *   const reclaim = createReclaim({ orgSecret })
+ *   // one-time setup:
+ *   await reclaim.callbacks.register({ callbackUrl })
+ *   // enable encryption:
+ *   await reclaim.credential.set(orgId, { publicKeyJwk })
+ *   const session = await reclaim.sessions.create({ providerId, context })
+ *   // …end-user completes session.verificationUrl…
+ *   const outcome = await reclaim.results.receive(callbackBody, {
+ *   	credential: privateJwk, // omit for plaintext
+ *   	expectedReclaimSessionId: session.id,
+ *   })
+ *
+ * Built by composition over the package's pure helpers (`decryptCallback`,
+ * `verifyResultFull`, …) — drop down to those, or to `reclaim.api`, for full
+ * control.
+ */
+import type { components } from './types/openapi.gen.ts';
+import { ReclaimClient } from './client.ts';
+import { type DecryptionKeyInput } from './enckeys.ts';
+import { type CallbackBody, type Jws, type VerifyResultFullOptions, type VerifyResultFullOutcome } from './result.ts';
+type CallbackSubscription = components['schemas']['CallbackSubscription'];
+type VerificationSession = components['schemas']['VerificationSession'];
+type VerificationEvent = components['schemas']['VerificationEvent'];
+type VerificationEventRecord = components['schemas']['VerificationEventRecord'];
+type OrgCredential = components['schemas']['OrgCredential'];
+/** The three terminal events a subscription can receive. */
+export declare const TERMINAL_EVENTS: readonly ["verification_success", "verification_rejected", "verification_error"];
+export interface RegisterCallbackInput {
+    callbackUrl: string;
+    events: VerificationEvent[];
+}
+export interface CreateSessionInput {
+    providerId: string;
+    version?: string;
+    context: Record<string, unknown>;
+    /** URL with a `{sessionId}` placeholder the end-user opens. */
+    verificationClientUrl: string;
+}
+export interface SetCredentialInput {
+    /** The org's X25519 encryption public key as an SPKI PEM — the content of
+     *  `openssl pkey -in key.pem -pubout` (the `-----BEGIN PUBLIC KEY-----`
+     *  block). It's converted to a JWK and stored; results are JWE-encrypted to
+     *  it. Keep the matching private PEM to decrypt (pass it to
+     *  `results.receive`/`decrypt`). */
+    publicKeyPem: string;
+    label?: string;
+}
+export interface ReclaimConfig {
+    /** The org secret (`rorg_…`). Authenticates ALL API calls and identifies
+     *  the org server-side. The only required config. */
+    orgSecret: string;
+    /** Backend base URL. Defaults to the production Builder. */
+    baseUrl?: string;
+    /** Custom fetch implementation. */
+    fetch?: typeof fetch;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+}
+/** Options for `results.receive` — the verification options plus an optional
+ *  X25519 decryption key (a JWK, a PKCS#8 PEM string, or `{ env }` / env-var
+ *  name). The key is needed only when the delivery is an encrypted (JWE). */
+export type ReceiveOptions = VerifyResultFullOptions & {
+    credential?: DecryptionKeyInput;
+};
+export interface Reclaim {
+    /** Typed escape hatch: `reclaim.api('OperationId', args)` for any spec
+     *  operation. */
+    api: ReclaimClient['call'];
+    sessions: {
+        /** Create a verification session. `verificationClientUrl` defaults to
+         *  the Builder's own `/v/{sessionId}` page. */
+        create(input: Omit<CreateSessionInput, 'verificationClientUrl'> & Partial<Pick<CreateSessionInput, 'verificationClientUrl'>>): Promise<VerificationSession>;
+        get(sessionId: string): Promise<VerificationSession>;
+        listEvents(sessionId: string): Promise<VerificationEventRecord[]>;
+    };
+    callbacks: {
+        /** Register a callback subscription (one-time setup). Delivery is scoped
+         *  to the token's org; results are JWE-encrypted to the org's credential
+         *  when one is set (see `credential.set`), else plaintext. `events`
+         *  defaults to all three terminal events. */
+        register(input: Partial<RegisterCallbackInput> & Pick<RegisterCallbackInput, 'callbackUrl'>): Promise<CallbackSubscription>;
+        list(): Promise<CallbackSubscription[]>;
+        remove(subscriptionId: string): Promise<void>;
+    };
+    credential: {
+        /** Set/replace org `orgId`'s single X25519 encryption credential. Once
+         *  set, terminal results are delivered as a compact JWE encrypted to it. */
+        set(orgId: string, input: SetCredentialInput): Promise<OrgCredential>;
+        /** Get org `orgId`'s encryption credential, or `undefined` when none is
+         *  set (delivery is plaintext). */
+        get(orgId: string): Promise<OrgCredential | undefined>;
+    };
+    results: {
+        /** Decrypt a callback body (JWE or plaintext JWS) to the signed JWS.
+         *  Pass the X25519 `credential` (JWK/PEM/env) only when the delivery is
+         *  a JWE. */
+        decrypt(body: CallbackBody, credential?: DecryptionKeyInput): Promise<Jws>;
+        /** Verify a decrypted JWS: JWKS discovery, ES256K signature,
+         *  `reclaimSessionId`/`aud`/`exp`, nested attestor proofs. */
+        verify(jws: Jws, opts?: VerifyResultFullOptions): Promise<VerifyResultFullOutcome>;
+        /** Handle any callback delivery in one call — the 90% path. Branches on
+         *  the envelope's `event`: a terminal event is decrypted (with
+         *  `opts.credential` when encrypted) + verified into a `result`; a
+         *  non-terminal event is returned as a plaintext (unsigned) `event`
+         *  notification without decryption. (A raw JWE/JWS body with no envelope
+         *  `event` is treated as a terminal result.) */
+        receive(body: CallbackBody, opts?: ReceiveOptions): Promise<ReceivedDelivery>;
+    };
+}
+/** Outcome of `results.receive` — a verified terminal result or a plaintext
+ *  non-terminal progress notification. Branch on `kind`. */
+export type ReceivedDelivery = {
+    kind: 'result';
+    result: VerifyResultFullOutcome;
+} | {
+    kind: 'event';
+    event: VerificationEvent;
+    eventData: Record<string, unknown>;
+};
+export declare function createReclaim(config: ReclaimConfig): Reclaim;
+export {};

package/lib/reclaim.js

@@ -0,0 +1,155 @@
+import { ReclaimClient } from "./client.js";
+import { loadDecryptionKey, publicPemToJwk, } from "./enckeys.js";
+import { decryptCallback, verifyResultFull, } from "./result.js";
+/** The three terminal events a subscription can receive. */
+export const TERMINAL_EVENTS = [
+    'verification_success',
+    'verification_rejected',
+    'verification_error',
+];
+export function createReclaim(config) {
+    if (!config?.orgSecret) {
+        throw new Error('createReclaim requires an org secret — pass '
+            + 'createReclaim({ orgSecret: <rorg_… org secret> })');
+    }
+    const client = new ReclaimClient({
+        baseUrl: config.baseUrl,
+        token: config.orgSecret,
+        fetch: config.fetch,
+        headers: config.headers,
+    });
+    // Load an X25519 decryption key on demand — `undefined` input ⇒ no key, so
+    // plaintext-only consumers never touch the loader.
+    const resolveKey = (input) => (input === undefined
+        ? Promise.resolve(undefined)
+        : loadDecryptionKey(input));
+    return {
+        api: client.call.bind(client),
+        sessions: {
+            async create(input) {
+                const body = {
+                    ...input,
+                    verificationClientUrl: input.verificationClientUrl ?? `${client.baseUrl}/v/{sessionId}`,
+                };
+                const { data } = await client.call('CreateVerificationSession', {
+                    body,
+                });
+                return data;
+            },
+            async get(sessionId) {
+                const { data } = await client.call('GetVerificationSession', {
+                    params: { sessionId },
+                });
+                return data;
+            },
+            async listEvents(sessionId) {
+                const { data } = await client.call('ListVerificationEvents', {
+                    params: { sessionId },
+                });
+                return data.items;
+            },
+        },
+        callbacks: {
+            async register(input) {
+                const events = input.events ?? [...TERMINAL_EVENTS];
+                const { data } = await client.call('CreateCallbackSubscription', {
+                    body: { callbackUrl: input.callbackUrl, events },
+                });
+                return data;
+            },
+            async list() {
+                const { data } = await client.call('ListCallbackSubscriptions');
+                return data.items;
+            },
+            async remove(subscriptionId) {
+                await client.call('DeleteCallbackSubscription', {
+                    params: { subscriptionId },
+                });
+            },
+        },
+        credential: {
+            async set(orgId, input) {
+                // Convert the consumer's SPKI public PEM to the JWK the API stores
+                // (PEM at the edge; JWK on the wire/DB/VC stays unchanged).
+                const publicKeyJwk = (await publicPemToJwk(input.publicKeyPem));
+                const { data } = await client.call('SetOrgCredential', {
+                    params: { orgId },
+                    body: { publicKeyJwk, label: input.label },
+                });
+                return data;
+            },
+            async get(orgId) {
+                try {
+                    const { data } = await client.call('GetOrgCredential', {
+                        params: { orgId },
+                    });
+                    return data;
+                }
+                catch (err) {
+                    // 404 ⇒ no credential set (plaintext delivery).
+                    if (isNotFound(err)) {
+                        return undefined;
+                    }
+                    throw err;
+                }
+            },
+        },
+        results: {
+            async decrypt(body, credential) {
+                return decryptCallback(await resolveKey(credential), body);
+            },
+            verify(jws, opts) {
+                return verifyResultFull(jws, { fetchImpl: config.fetch, ...opts });
+            },
+            async receive(body, opts) {
+                // A delivery envelope tagged with a non-terminal event carries a
+                // plaintext, unsigned `{ event, eventData }` payload — return it
+                // directly, no decryption/verification.
+                if (body && typeof body === 'object'
+                    && !(body instanceof Uint8Array)
+                    && !(body instanceof ArrayBuffer)) {
+                    const env = body;
+                    if (env.event
+                        && !TERMINAL_EVENTS.includes(env.event)) {
+                        const decoded = parseEventData(env.data);
+                        return {
+                            kind: 'event',
+                            event: env.event,
+                            eventData: decoded,
+                        };
+                    }
+                }
+                const { credential, ...verifyOpts } = opts ?? {};
+                const key = await resolveKey(credential);
+                const jws = await decryptCallback(key, body);
+                const result = await verifyResultFull(jws, {
+                    fetchImpl: config.fetch,
+                    ...verifyOpts,
+                });
+                return { kind: 'result', result };
+            },
+        },
+    };
+}
+/** Non-terminal `data` is a base64-encoded JSON `{ event, eventData }`. */
+function parseEventData(data) {
+    if (!data) {
+        return {};
+    }
+    try {
+        const decoded = JSON.parse(Buffer.from(data, 'base64').toString('utf8'));
+        return decoded.eventData ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** True for a `404` thrown by {@link ReclaimClient.call} — a Boom error whose
+ *  `output.statusCode` is 404 (see ./errors.ts). */
+function isNotFound(err) {
+    if (typeof err !== 'object' || err === null) {
+        return false;
+    }
+    const boom = err;
+    return boom.output?.statusCode === 404 || boom.statusCode === 404;
+}

package/lib/result.d.ts

@@ -0,0 +1,132 @@
+import type { JWK } from 'jose';
+import type { components } from './types/openapi.gen.ts';
+import type { DecryptionKey } from './enckeys.ts';
+export interface Jws {
+    payload: string;
+    signatures: {
+        protected: string;
+        header?: Record<string, unknown>;
+        signature: string;
+    }[];
+}
+export interface VerifyResultOptions {
+    /** Uncompressed ETH public key (`0x04`+128 hex) of the signer; when given,
+     *  the JWS signature is verified. Omit to only decode + check the nonce. */
+    signerPublicKey?: string;
+    /** The `reclaimSessionId` the consumer expects (the session id they got
+     *  back at creation). When given, mismatch fails verification. */
+    expectedReclaimSessionId?: string;
+}
+export interface VerifyResultOutcome {
+    valid: boolean;
+    reason?: string;
+    payload: Record<string, unknown>;
+    reclaimSessionId?: string;
+}
+/**
+ * JWE-encrypt `plaintext` for the holder of `publicJwk` (an X25519 public JWK,
+ * `{kty:'OKP', crv:'X25519', x}`) as a compact JWE (`ECDH-ES + A256GCM`). Used
+ * by the first-party Verification Client to encrypt the signed JWS for each
+ * Consumer before submitting it to the Builder (which only relays the
+ * ciphertext). Consumers never call this — they only {@link decryptCallback}.
+ *
+ * `plaintext` is bytes (e.g. `new TextEncoder().encode(JSON.stringify(jws))`);
+ * returns the compact JWE string.
+ */
+export declare function encryptForPublicJwk(publicJwk: JWK, plaintext: Uint8Array): Promise<string>;
+/**
+ * What a consumer's callback endpoint receives — the Builder POSTs the JSON
+ * `VerificationResultDelivery` envelope: plaintext `sessionId`/`event`/
+ * `timestamp` routing hints. For terminal events `data` is a compact JWE
+ * string wrapping the signed JWS (or the plaintext JWS JSON when the org has
+ * no encryption credential). The envelope is unauthenticated; trust only the
+ * decrypted+verified JWS.
+ *
+ * Derived from the generated spec type so it can't drift; the hint fields
+ * are relaxed to optional — decryption only needs `data`.
+ */
+export type DeliveryEnvelope = Partial<components['schemas']['VerificationResultDelivery']> & Pick<components['schemas']['VerificationResultDelivery'], 'data'>;
+/** Anything a callback handler may have on hand: the parsed envelope, its
+ *  JSON text, its raw body bytes — or a bare compact JWE / JWS string. */
+export type CallbackBody = DeliveryEnvelope | string | Uint8Array | ArrayBuffer;
+/**
+ * Decrypt a delivered terminal callback to the signed JWS. `data` is either a
+ * compact JWE (decrypted with the X25519 `privateKey`) or — when the org has no
+ * encryption credential — the plaintext JWS JSON. A compact JWE has exactly
+ * five dot-separated base64url segments; a JSON JWS starts with `{`.
+ *
+ * `privateKey` may be absent (plaintext delivery); an encrypted delivery with
+ * no key throws a clear error.
+ */
+export declare function decryptCallback(privateKey: DecryptionKey | undefined, body: CallbackBody): Promise<Jws>;
+/**
+ * Sign a verification result as a flattened JWS (JOSE ES256K = ECDSA/secp256k1
+ * over SHA-256 of the `<protected>.<payload>` signing input — a single hash).
+ * `kid` is the signer's ETH address (published via JWKS); `iss` is the issuer
+ * URL. Used by the Verification Client to sign results before encrypting them.
+ */
+export declare function signResultJws(privateKeyHex: string, payload: Record<string, unknown>, iss: string): Jws;
+/** Decode the JWS payload (base64url JSON). */
+export declare function decodeJwsPayload(jws: Jws): Record<string, unknown>;
+/**
+ * Verify a JWS signature (JOSE ES256K = ECDSA/secp256k1 over SHA-256 of the
+ * `<protected>.<payload>` signing input) with an uncompressed public key.
+ */
+export declare function verifyJwsSignature(jws: Jws, signerPublicKey: string): boolean;
+export interface VerifyResultFullOptions {
+    /** The `reclaimSessionId` the consumer expects (mismatch fails). */
+    expectedReclaimSessionId?: string;
+    /** The consumer's `orgId`; the result's `aud` must match it. */
+    expectedAud?: string;
+    /** Allowlist of trusted attestor ETH addresses (lowercased compared). */
+    attestorAddresses?: string[];
+    /** Override the VC signer key instead of JWKS discovery via header `iss`. */
+    signerPublicKey?: string;
+    /** Injectable fetch (for JWKS); defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Override "now" (unix seconds) for `exp` checks. */
+    now?: number;
+}
+export interface ResultProofOutcome {
+    requestId?: string;
+    proofValid: boolean;
+    reason?: string;
+    attestorAddress?: string;
+}
+export interface VerifyResultFullOutcome extends VerifyResultOutcome {
+    proofs?: ResultProofOutcome[];
+}
+/**
+ * Thrown by {@link verifyResult} / {@link verifyResultFull} (and therefore
+ * `reclaim.results.verify`/`receive`) when a result fails verification. Carries
+ * the full invalid outcome so callers can inspect it in a `catch`:
+ *
+ *   try {
+ *     const { result } = await reclaim.results.receive(body, { credential })
+ *     // result is verified — use result.payload
+ *   } catch (err) {
+ *     if (err instanceof ResultVerificationError) {
+ *       // e.g. 'expired', { payload, … }
+ *       console.error(err.reason, err.outcome)
+ *     }
+ *   }
+ */
+export declare class ResultVerificationError extends Error {
+    /** Machine-readable failure reason — `'bad-signature'`, `'expired'`,
+     *  `'reclaimSessionId-mismatch'`, `'aud-mismatch'`, `'invalid-proof'`, … */
+    readonly reason: string;
+    /** The full (invalid) outcome: `payload`, `reclaimSessionId`, and per-proof
+     *  detail (`proofs`) when verification got that far. */
+    readonly outcome: VerifyResultFullOutcome;
+    constructor(outcome: VerifyResultFullOutcome);
+}
+/**
+ * Full consumer verification: discovers the Verification Client's signing key
+ * via JWKS (header `iss`/`kid`), verifies the top-level JWS, checks
+ * `reclaimSessionId`/`aud`/`exp`, then verifies each result's nested attestor
+ * proof and its `content_hash`. Network access (JWKS) makes this async; use
+ * {@link verifyResult} for the offline primitive.
+ */
+export declare function verifyResultFull(jws: Jws, opts?: VerifyResultFullOptions): Promise<VerifyResultFullOutcome>;
+/** Decrypt-and-verify in one step. */
+export declare function verifyResult(jws: Jws, opts?: VerifyResultOptions): VerifyResultOutcome;