@reclaimprotocol/client 0.1.28 → 0.1.31

package/README.md

@@ -6,17 +6,28 @@ order. Integrate it directly into your app.
 
 One package gives you:
 
-- **`createReclaim(...)`** — create verification sessions, register callbacks,
-  and receive and verify results with a small declarative client.
+- **`ReclaimVerification.create(...)`** — create verification sessions and
+  receive and verify results.
 - **`ReclaimClient`** — call any operation in the spec with the low-level typed
   HTTP client (`call('OperationId', args)`).
 - **Crypto helpers** — decrypt ECIES results with the organization's ETH key,
-  sign and verify result JWSs, discover JWKS keys, and verify exact legacy
-  proofs.
+  verify Builder-signed result JWSs, discover JWKS keys, and verify exact
+  proofs. Result signing is Builder-managed in `api=2`.
 
 Use the API-only entry point in browsers and edge runtimes. Use the package
 root in trusted runtimes that need proof verification, signing, or encryption.
 
+## Contents
+
+- [Choose an entry point](#choose-an-entry-point)
+- [The model in one paragraph](#the-model-in-one-paragraph)
+- [Install](#install)
+- [Quick start](#quick-start-consumer)
+- [API reference](#api-reference)
+- [Crypto and key helpers](#crypto-and-key-helpers)
+- [`ReclaimClient` low-level API](#reclaimclient-low-level)
+- [Security notes](#security-notes)
+
 ## Choose an entry point
 
 Use the narrowest entry point that fits the code:
@@ -24,7 +35,7 @@ Use the narrowest entry point that fits the code:
 | Import | Use it for | Includes |
 | --- | --- | --- |
 | `@reclaimprotocol/client/api` | Browser Verification Clients, frontend dashboards, agents, and backend API calls | Browser-safe `fetch` transport plus OpenAPI-generated operation and schema types |
-| `@reclaimprotocol/client` | Consumer backends and other trusted runtimes | API client, session workflows, result verification, proof verification, signing, and encryption |
+| `@reclaimprotocol/client` | Consumer backends and other trusted runtimes | API client, session workflows, result verification, proof verification, legacy signing, and encryption |
 | `@reclaimprotocol/client/openapi` | Type-only integrations | OpenAPI-generated types only |
 
 Both runtime entry points export the exact same `ReclaimClient`,
@@ -66,8 +77,8 @@ Boom-compatible: `@hapi/boom`'s `isBoom(error)` returns `true`, and
 `error.output.statusCode` contains the HTTP status. The API entry point creates
 this shape without importing the Boom runtime into browser bundles.
 
-A registered Verification Client uses its session-bound UUID header instead
-of a consumer bearer token:
+A registered Verification Client uses its session-bound UUID to call the
+bootstrap endpoint:
 
 ```ts
 import { ReclaimClient } from '@reclaimprotocol/client/api'
@@ -77,16 +88,43 @@ const builder = new ReclaimClient({
   headers: { 'x-reclaim-vc-id': verificationClientId },
 })
 
-const { data: recipe } = await builder.call('GetVerificationRecipe', {
+const { data: bootstrap } = await builder.call('BootstrapVerificationClient', {
   params: { sessionId },
 })
 ```
 
+Builder also returns an immutable, session-scoped feature configuration on
+`VerificationSession.runtimeConfig`. Read only keys the Verification Client
+implements, and use a safe fallback because older sessions can omit the
+snapshot:
+
+```ts
+import {
+  getBooleanFeatureFlag,
+  ReclaimClient,
+} from '@reclaimprotocol/client/api'
+
+const { data: bootstrap } = await builder.call('BootstrapVerificationClient', {
+  params: { sessionId },
+})
+const useNewPicker = getBooleanFeatureFlag(
+  bootstrap.session.runtimeConfig,
+  'portal.newRequestPicker',
+  false,
+)
+```
+
+The `/api` and package-root entry points export the same browser-safe flag
+readers. Verification Clients never call the admin feature-flag endpoints or
+fetch live values during a session. See
+[Verification Client feature flags](../../docs/verification-feature-flags.md).
+
 Treat the Verification Client ID as deployment configuration, not as proof of
-identity. Builder authorizes it only for the session assigned to that
-registered client. Never put an organization secret, result-signing private
-key, or proof-owner private key in browser code. Keep result signing in the
-Verification Client backend and call `verifyResultFull` from the consumer
+identity. Builder requires it to match the client assigned to the session, but
+the public UUID doesn't authenticate the caller. Never put an organization
+secret, result-signing private key, or proof-owner private key in browser code.
+Builder owns result signing in Builder mode; claimant-facing Verification
+Clients receive no signing key. Call `verifyResultFull` from the consumer
 backend after receiving a result.
 
 ## The model in one paragraph
@@ -97,14 +135,13 @@ secrets. An **Ethereum (secp256k1) public key** identifies the organization.
 When `canEncryptResult` is enabled, verification **results are encrypted with
 ECIES** (secp256k1 + AES-256-GCM) to the organization's ETH public key. Keep the
 matching **ETH private key** (`0x`-hex, the form any wallet or ethers emits) to
-decrypt. The Verification Client signs the result JWS with `ES256K`; verify it
-against that client's registered trusted JWKS.
+decrypt. Builder signs the result JWS with its managed `ES256K` key; verify it
+against the Builder's trusted issuer and well-known JWKS.
 
 ```
                           ┌─ one-time setup ─────────────────────────┐
-  reclaim.callbacks.register({ callbackUrl })      ← where results go
-  reclaim.keypair.set(orgId, { publicKey,          ← identity + (optional)
-                       canEncryptResult: true })      encrypt to your key
+  Configure callback in dashboard or raw API       ← where results go
+  SetOrgKeypair via dashboard or raw API            ← optional encryption
                           └──────────────────────────────────────────┘
                           ┌─ per verification ───────────────────────┐
   reclaim.sessions.create(...) → open session.verificationUrl
@@ -125,9 +162,9 @@ Configure the client once with your organization secret. In the example,
 `orgId` identifies the organization that owns the secret.
 
 ```ts
-import { createReclaim } from '@reclaimprotocol/client'
+import { ReclaimVerification } from '@reclaimprotocol/client'
 
-const reclaim = createReclaim({
+const reclaim = ReclaimVerification.create({
   orgSecret: process.env.RECLAIM_ORG_SECRET!,  // rorg_… (issued by an org owner)
 })
 const orgId = process.env.RECLAIM_ORG_ID!      // your org's id
@@ -139,9 +176,11 @@ Register the endpoint where Builder posts verification results. Complete this
 one-time setup with the **dashboard** or the **agent** too; see [Three ways to
 set up](#three-ways-to-set-up).
 
-```ts
-await reclaim.callbacks.register({ callbackUrl: 'https://my.app/reclaim/callback' })
-```
+The high-level verification client intentionally excludes callback management.
+Use the dashboard, the MCP `create_org_callback_subscription` tool, or call the
+generated `CreateOrgCallbackSubscription` operation with a human-authenticated
+`ReclaimClient` when automating organization setup. The consumer `orgSecret`
+does not authenticate this management operation.
 
 ### 2. Enable encryption (optional, one-time)
 
@@ -158,9 +197,12 @@ const { privateKeyHex, publicKeyHex } = generateEthKeypair()
 
 ```ts
 // (also doable from the dashboard, which can mint the keypair in-browser)
-await reclaim.keypair.set(orgId, {
-  publicKey: publicKeyHex,   // 0x04+128 hex (or pass publicKeyJwk)
-  canEncryptResult: true,
+await reclaim.api('SetOrgKeypair', {
+  params: { orgId },
+  body: {
+    publicKey: publicKeyHex,
+    canEncryptResult: true,
+  },
 })
 ```
 
@@ -173,7 +215,7 @@ const session = await reclaim.sessions.create({
   // Optional: snapshot this active organization theme onto the session.
   themeId: '550e8400-e29b-41d4-a716-446655440000',
   // Optional: derive and bind the legacy TEE nonce locally after creation.
-  teeAttestation: { appSecret: organizationVerificationPrivateKey },
+  orgEthPrivateKey,
 })
 console.log('open this:', session.verificationUrl)   // hand to the end-user
 ```
@@ -184,33 +226,15 @@ console.log('open this:', session.verificationUrl)   // hand to the end-user
 Verification Client with its registered base URL:
 
 ```ts
-import {
-  KNOWN_VERIFICATION_CLIENTS,
-  type KnownVerificationClientUrlMap,
-} from '@reclaimprotocol/client'
-
-const verificationClientUrls = {
-  [KNOWN_VERIFICATION_CLIENTS.portals]:
-    process.env.RECLAIM_PORTAL_URL,
-  [KNOWN_VERIFICATION_CLIENTS.verifierApp]:
-    process.env.RECLAIM_VERIFIER_APP_URL,
-  [KNOWN_VERIFICATION_CLIENTS.inAppSdk]:
-    process.env.RECLAIM_INAPP_URL,
-  [KNOWN_VERIFICATION_CLIENTS.reclaimBrowserExtension]:
-    process.env.RECLAIM_BROWSER_EXTENSION_URL,
-} satisfies KnownVerificationClientUrlMap
-
-const clientName = KNOWN_VERIFICATION_CLIENTS.portals
-const verificationClientUrl = verificationClientUrls[clientName]
-if (!verificationClientUrl) throw new Error(`${clientName} URL isn't configured`)
+import { VerificationClient } from '@reclaimprotocol/client'
 
 const session = await reclaim.sessions.create({
   providers: [
-    // Blank/omitted version → latest; exact and npm semver ranges also work.
+    // Blank/omitted → latest; 1.2.2 → exact; ^1.2.2 → >=1.2.2 <2.0.0.
     { providerId: 'prov_…', version: '^1.2.0' },
   ],
   context: { userId: 'abc', orderId: 'order-123' },
-  verificationClientUrl,
+  verificationClientUrl: VerificationClient.portals,
 })
 
 // Builder resolves the URL to a registered client, pins its UUID on the
@@ -218,6 +242,15 @@ const session = await reclaim.sessions.create({
 console.log(session.verificationUrl)
 ```
 
+Builder resolves each provider independently and returns its exact
+`resolvedVersion`. Verification Clients execute that resolved recipe; they
+don't resolve versions themselves.
+
+For imported legacy providers, pass consumer values in `context`. Builder-mode
+clients support `{{context.key}}`, then `{{context_key}}`, then `{{key}}` as
+compatibility aliases. Explicit request or provider-script parameters take
+precedence.
+
 Builder snapshots the selected theme at session creation. Omit `themeId` to use
 the organization's most recently updated active theme. If the organization has
 no active theme, the Verification Client uses its default presentation. A
@@ -238,12 +271,14 @@ enable logs containing personal data, so don't add it to normal production
 links. Redirect parameters are also client-owned: append them to the returned
 URL instead of putting them in the session request.
 
-Use `{{context.key}}` in new Builder recipes for values supplied in
-`context`; Builder validates those through the provider's `requiredContext`.
-For an old DevTools recipe that still uses bare `{{key}}`, Builder-mode
-Verification Clients seed a missing `parameters.key` from scalar
-`context.key`. An explicit parameter wins. This compatibility alias applies
-only to `api=2`; it doesn't change legacy sessions. Builder-owned
+Use `{{context.key}}` in new Builder recipes for values supplied in `context`;
+Builder validates those through the provider's `requiredContext`. Imported
+recipes can fall back to `{{context_key}}` and then `{{key}}`. A lower-priority
+alias is used only when the recipe doesn't use a higher-priority spelling, and
+an explicit parameter always wins. Clients apply this to URLs, headers, request
+bodies, response matches, response redactions, provider scripts, and
+interceptor-created claims. This applies only to `api=2`; it doesn't change
+legacy sessions. Builder-owned
 `reclaimSessionId` and `attestationNonce` remain context-only.
 
 The value must exactly equal that deployment's registered
@@ -253,90 +288,87 @@ yourself. Builder either substitutes it or adds a `sessionId` query parameter,
 then adds `api=2`. An unregistered or slightly different URL is rejected with
 HTTP 400.
 
-The SDK exposes stable registry names for these intended uses. A standard
-deployment seeds all six rows, but an administrator must configure each row's
-URL, issuer, JWKS URL, and signing key before consumers select it:
+The SDK exposes declarative URLs for these intended uses.
+Builder owns terminal-result signing and encryption; claimant-facing clients
+receive no signing key, issuer, JWKS URL, or callback key:
 
-| Registry name | How the consumer selects it | Builder v2 use |
-| --- | --- | --- |
-| `builder` | Omit `verificationClientUrl`. | Built-in `/v/{sessionId}` client; available whenever Builder is running. |
-| `portals` | Pass the exact registered portal URL. | Interactive web portal. Its deployment must configure the bridge URL and registered Client UUID. |
-| `verifier-app` | Pass the exact registered HTTPS app/universal-link URL. | Reclaim Verifier mobile app. Its build must configure the bridge URL and registered Client UUID. |
-| `inapp-sdk` | Pass the exact registered URL owned by the host app. | In-app SDK or add-to-app module. The host app must configure Builder transport and the registered Client UUID. |
-| `reclaim-browser-extension` | Pass the exact registered extension launch URL. | Browser extension. Use a build that supports Builder mode (`api=2`). Its existing legacy `oprf-raw` support is independent of Builder-mode hardening. |
-| `zkfetch` | Don't use as an interactive claimant client unless the deployment explicitly supports it. | Separate programmatic `ZKFETCH` quota pool, not one of the current portal/mobile Builder flows. |
+| Registry name | Builder v2 use |
+| --- | --- |
+| `builder` | Builder's hosted claimant page at `/v/{sessionId}`. |
+| `portals` | Interactive web portal. The default when you omit the URL. |
+| `verifier-app` | Reclaim Verifier mobile app identifier. |
+| `inapp-sdk` | In-app SDK or add-to-app module identifier. |
+| `reclaim-browser-extension` | Browser extension identifier. |
+| `zkfetch` | Programmatic client in the separate `ZKFETCH` quota pool. |
 
-`KNOWN_VERIFICATION_CLIENTS` is the public string map for these stable registry
-names:
+Use `VerificationClient` to select a built-in client or supply a registered
+custom URL:
 
 ```ts
-{
-  builder: 'builder',
-  portals: 'portals',
-  verifierApp: 'verifier-app',
-  inAppSdk: 'inapp-sdk',
-  reclaimBrowserExtension: 'reclaim-browser-extension',
-  zkFetch: 'zkfetch',
-}
+VerificationClient.builder
+VerificationClient.portals
+VerificationClient.verifierApp
+VerificationClient.inAppSdk
+VerificationClient.reclaimBrowserExtension
+VerificationClient.zkFetch
+VerificationClient.custom('https://verify.example.com')
 ```
 
-Use `KnownVerificationClientName` when accepting a client choice in your own
-API and `KnownVerificationClientUrlMap` for deployment configuration. Validate
-untrusted input against the map's values. The names are stable; the URLs are
-not.
-
-Client URLs are deployment configuration, not package constants. A seeded
-registry row can be only an identifier until an administrator replaces its URI
-with the real deployed client URL and configures its issuer, JWKS, bridge, and
-signing key. Get the exact value from the Builder administrator or the
-admin-only `/admin/verification-clients` registry; never accept it from a
-claimant or derive it from a signed result. An organization token cannot list
-the admin registry. Administrators can also register additional clients with
-their own URL, issuer, JWKS URL, and signing key.
+Administrators can also register additional clients with their own URL.
 
 Examples for the currently supported interactive clients:
 
 ```ts
-// Replace these examples with exact values from your Builder registry.
-const registeredClients = {
-  portal: 'https://portal.your-deployment.example/',
-  verifierApp: 'https://verify.your-deployment.example/app',
-  inApp: 'https://app.your-deployment.example/reclaim',
-  browserExtension: 'https://extension.your-deployment.example/launch',
-}
+import { VerificationClient } from '@reclaimprotocol/client'
 
-// 1. Built-in Builder client — omit verificationClientUrl.
-const builtIn = await reclaim.sessions.create({
+// 1. Default (Portal) — omit verificationClientUrl.
+const byDefault = await reclaim.sessions.create({
   providers: [{ providerId }],
   context,
 })
 
-// 2. Portal — the URL must be the exact registered portals.uri.
+// 2. Portal, selected explicitly.
 const portal = await reclaim.sessions.create({
   providers: [{ providerId }],
   context,
-  verificationClientUrl: registeredClients.portal,
+  verificationClientUrl: VerificationClient.portals,
 })
 
-// 3. Reclaim Verifier app — use its registered HTTPS app link.
+// 3. Reclaim Verifier app.
 const verifierApp = await reclaim.sessions.create({
   providers: [{ providerId }],
   context,
-  verificationClientUrl: registeredClients.verifierApp,
+  verificationClientUrl: VerificationClient.verifierApp,
 })
 
-// 4. In-app SDK/add-to-app host — use the host app's registered link.
+// 4. In-app SDK or add-to-app host.
 const inApp = await reclaim.sessions.create({
   providers: [{ providerId }],
   context,
-  verificationClientUrl: registeredClients.inApp,
+  verificationClientUrl: VerificationClient.inAppSdk,
 })
 
-// 5. Browser extension — use a deployed build with Builder-mode support.
+// 5. Browser extension.
 const browserExtension = await reclaim.sessions.create({
   providers: [{ providerId }],
   context,
-  verificationClientUrl: registeredClients.browserExtension,
+  verificationClientUrl: VerificationClient.reclaimBrowserExtension,
+})
+
+// 6. Builder's hosted claimant page.
+const hosted = await reclaim.sessions.create({
+  providers: [{ providerId }],
+  context,
+  verificationClientUrl: VerificationClient.builder,
+})
+
+// 7. Separately registered client or another Builder deployment.
+const custom = await reclaim.sessions.create({
+  providers: [{ providerId }],
+  context,
+  verificationClientUrl: VerificationClient.custom(
+    'https://verify.example.com',
+  ),
 })
 ```
 
@@ -385,48 +417,26 @@ sequenceDiagram
   Backend-->>Frontend: Return verified status
 ```
 
-**1. Create the request on your backend.** Keep `RECLAIM_ORG_SECRET` private,
-validate the requested client name against `KNOWN_VERIFICATION_CLIENTS`, map it
-to your deployment's registered URL, and save the returned session ID with your
-user or order.
+**1. Create the request on your backend.** Keep `RECLAIM_ORG_SECRET` private
+and save the returned session ID with your user or order. The session opens in
+the Portal unless you pass a `VerificationClient` URL.
 
 ```ts
 import {
   type CallbackBody,
-  createReclaim,
-  KNOWN_VERIFICATION_CLIENTS,
-  type KnownVerificationClientName,
-  type KnownVerificationClientUrlMap,
+  ReclaimVerification,
 } from '@reclaimprotocol/client'
 
-const reclaim = createReclaim({
+const reclaim = ReclaimVerification.create({
   orgSecret: process.env.RECLAIM_ORG_SECRET!,
 })
 
-const clientUrls: KnownVerificationClientUrlMap = {
-  [KNOWN_VERIFICATION_CLIENTS.portals]: process.env.RECLAIM_PORTAL_URL!,
-  [KNOWN_VERIFICATION_CLIENTS.verifierApp]:
-    process.env.RECLAIM_VERIFIER_APP_URL!,
-  [KNOWN_VERIFICATION_CLIENTS.inAppSdk]: process.env.RECLAIM_INAPP_URL!,
-  [KNOWN_VERIFICATION_CLIENTS.reclaimBrowserExtension]:
-    process.env.RECLAIM_BROWSER_EXTENSION_URL!,
-}
-
 async function createVerificationRequest(
   userId: string,
-  clientName: KnownVerificationClientName,
 ) {
-  const verificationClientUrl = clientName === KNOWN_VERIFICATION_CLIENTS.builder
-    ? undefined
-    : clientUrls[clientName]
-  if (clientName !== KNOWN_VERIFICATION_CLIENTS.builder && !verificationClientUrl) {
-    throw new Error(`${clientName} URL isn't configured`)
-  }
-
   const session = await reclaim.sessions.create({
     providers: [{ providerId: 'prov_…', version: '^1.2.0' }],
     context: { userId },
-    ...(verificationClientUrl ? { verificationClientUrl } : {}),
   })
   await savePendingVerification({
     sessionId: session.id,
@@ -467,8 +477,21 @@ encoded. Persist the delivery before returning a successful HTTP status so a
 process crash can't lose it.
 
 ```ts
-await reclaim.callbacks.register({
-  callbackUrl: 'https://my.app/reclaim/callback/{{sessionId}}',
+// One-time setup as the signed-in organization member, not with orgSecret.
+import { ReclaimClient } from '@reclaimprotocol/client/api'
+const setupClient = new ReclaimClient({ token: humanAccessToken })
+await setupClient.call('CreateOrgCallbackSubscription', {
+  params: { orgId },
+  body: {
+    callbackUrl: 'https://my.app/reclaim/callback/{{sessionId}}',
+    events: [
+      'verification_success',
+      'verification_rejected',
+      'verification_error',
+      'verification_cancelled',
+      'session_expired',
+    ],
+  },
 })
 
 // HTTP callback handler. `sessionId` comes from the route path.
@@ -482,17 +505,17 @@ async function acceptCallback(sessionId: string, requestBody: CallbackBody) {
 Verify the durable delivery in a backend worker. Load the expected session and
 organization from your database; don't take either expected value from the
 callback payload. `results.receive` decrypts when needed, validates the
-registered Verification Client issuer and JWKS, verifies the outer result JWS,
-checks the session/audience and any legacy result expiry, and runs the package's legacy-compatible
-`verifyProof` checks for every proof.
+Builder issuer and JWKS, verifies the outer result JWS,
+checks the session/audience and any legacy result expiry, and runs the package's
+`verifyRequestProof` checks for every proof.
 
 ```ts
 async function verifyCallbackDelivery(deliveryId: string) {
   const delivery = await loadCallbackDelivery(deliveryId)
   const expected = await loadPendingVerification(delivery.sessionId)
   const outcome = await reclaim.results.receive(delivery.requestBody, {
-    credential: process.env.RECLAIM_ETH_PRIVATE_KEY,
-    expectedReclaimSessionId: expected.sessionId,
+    orgEthPrivateKey: process.env.RECLAIM_ETH_PRIVATE_KEY,
+    reclaimSessionId: expected.sessionId,
     expectedAud: expected.orgId,
   })
 
@@ -517,14 +540,15 @@ Removing `api=2` does not turn this request into a valid legacy request. To
 create a legacy verification, continue using the legacy JS SDK/backend request
 format. URLs without `api=2` stay on each client's unchanged legacy parser.
 
-With `teeAttestation`, the SDK creates the session, derives the selected exact
+With `orgEthPrivateKey`, the SDK creates the session, derives the selected exact
 legacy nonce, signs the Builder binding with
 EIP-191, and registers it at
 `PUT /verifications/sessions/{sessionId}/tee-nonce`. The private key is never
 sent to Builder. The binding is idempotent for identical values and immutable
 afterward; bind before proof generation starts. The default `nonceMode: 'hash'`
 uses `RECLAIM_TEE_NONCE_V1`. Set `nonceMode: 'signature'` for the older
-65-byte EIP-191 nonce that legacy `verifyProof` also accepts.
+65-byte EIP-191 nonce that legacy `verifyProof` also accepts. Use
+`teeNonceMode: 'signature'` on `sessions.create` for this compatibility mode.
 
 Because this endpoint is an authenticated POST, you can use `curl` without the
 SDK. The organization secret is the only credential:
@@ -552,7 +576,7 @@ Never send the private key in either request.
 
 When the user finishes, Builder sends a POST request to your `callbackUrl`.
 Pass the request body to `results.receive`. It decrypts encrypted results,
-verifies the outer signature, and verifies every exact legacy proof. It
+verifies the outer signature, and verifies every exact proof. It
 **throws if the result is invalid**, so reaching the `result` branch means the
 result is verified.
 
@@ -560,12 +584,12 @@ result is verified.
 // Load these expected values from your database, not from the callback body.
 const expected = await loadPendingVerification(callbackRouteSessionId)
 const outcome = await reclaim.results.receive(requestBody, {
-  credential: process.env.RECLAIM_ETH_PRIVATE_KEY,  // 0x-hex ETH key; omit for plaintext
-  expectedReclaimSessionId: expected.sessionId,
+  orgEthPrivateKey: process.env.RECLAIM_ETH_PRIVATE_KEY,
+  reclaimSessionId: expected.sessionId,
   expectedAud: expected.orgId,
 })
 if (outcome.kind === 'result') {
-  // These values came from verifyProof. Don't trust diagnostic copies from
+  // These values came from verifyRequestProof. Don't trust diagnostic copies from
   // the outer payload for application decisions.
   const trustedClaims = outcome.result.proofs?.flatMap((proof) => (
     proof.data ? [proof.data] : []
@@ -580,7 +604,9 @@ if (outcome.kind === 'result') {
 
 Choose any of these one-time setup methods; each uses the same API:
 
-- **This SDK** — `reclaim.callbacks.register(...)` + `reclaim.keypair.set(...)`, as above (good for scripting/CI).
+- **Raw OpenAPI client** — use a human-authenticated `ReclaimClient` for
+  `CreateOrgCallbackSubscription`. Use `SetOrgKeypair` through `reclaim.api`
+  when configuring result encryption, which is useful for scripting or CI.
 - **The dashboard** — the organization's web console has a callback-subscription form and a "Set encryption keypair" dialog that can **generate the ETH keypair in your browser** and download the private key for you.
 - **The agent** (`@reclaimprotocol/agent` — the `reclaim` CLI / MCP server) — handy while building and testing a provider locally.
 
@@ -592,10 +618,10 @@ authentication and the ETH private key for decryption. The
 
 ## API reference
 
-### `createReclaim(config)`
+### `ReclaimVerification.create(config)`
 
-Call `createReclaim(config)` to return a `Reclaim` with four namespaces —
-`sessions`, `callbacks`, `keypair`, and `results` — plus an `api` escape hatch.
+Call `ReclaimVerification.create(config)` to return a client with `sessions`
+and `results` namespaces, plus an `api` escape hatch.
 
 | `ReclaimConfig` field | type | required | notes |
 |---|---|---|---|
@@ -604,47 +630,51 @@ Call `createReclaim(config)` to return a `Reclaim` with four namespaces —
 | `fetch` | `typeof fetch` | no | Custom fetch (tests, edge runtimes). |
 | `headers` | `Record<string,string>` | no | Extra headers merged into every request. |
 
-`orgSecret` is the only required configuration value. Pass each other value to
-the method that uses it: **`orgId`** to `keypair.set`/`get`, the optional **TEE
-private key** (`0x`-hex) to `sessions.create({ teeAttestation: { appSecret } })`,
-and the **ETH private key** to `results.receive`/`decrypt`.
+`orgSecret` is the only required configuration value. Pass the optional ETH
+private key directly to `sessions.create`, `results.receive`, or
+`results.decrypt`. The SDK doesn't cache or serialize that key.
 
-### Known verification client names
+Use `reclaim.export()` to serialize non-secret configuration. Restore it with
+runtime credentials:
 
 ```ts
-import {
-  KNOWN_VERIFICATION_CLIENTS,
-  type KnownVerificationClientName,
-  type KnownVerificationClientUrlMap,
-} from '@reclaimprotocol/client'
+const saved = reclaim.export()
+const restored = ReclaimVerification.import(saved, { orgSecret })
+```
+
+The JSON contains only a format version and Builder base URL. It never contains
+the organization secret, ETH private key, headers, or custom `fetch` function.
+
+### Verification clients
+
+```ts
+import { VerificationClient } from '@reclaimprotocol/client'
 ```
 
-- `KNOWN_VERIFICATION_CLIENTS` maps TypeScript-friendly keys to the stable
-  registry names `builder`, `portals`, `verifier-app`, `inapp-sdk`,
-  `reclaim-browser-extension`, and `zkfetch`.
-- `KnownVerificationClientName` is the union of those string values.
-- `KnownVerificationClientUrlMap` is a partial map from those names to the
-  exact URLs registered in one Builder deployment.
+- `VerificationClient.builder`, `.portals`, `.verifierApp`, `.inAppSdk`,
+  `.reclaimBrowserExtension`, and `.zkFetch` contain production URLs.
+- `VerificationClient.custom(uri)` returns a separately registered client URL
+  unchanged.
 
-The map doesn't make a URL trusted and doesn't select a client by name in the
-Builder API. Your backend chooses a configured URL, and
+The helper doesn't make a URL trusted or register it in Builder. Your backend
+chooses an already registered URL, and
 `sessions.create({ verificationClientUrl })` asks Builder to resolve that URL
-to its registered client UUID. Omit the URL to select `builder`.
+to its registered client UUID. Omit the URL to select `portals`.
 
 ### `reclaim.sessions`
 
 ```ts
-reclaim.sessions.create({ providers, context, verificationClientUrl?, teeAttestation? })
+reclaim.sessions.create({ providers, context, verificationClientUrl?, orgEthPrivateKey? })
   // providers: { providerId, version? }[] — proved in order, one combined result; all required.
   // → VerificationSession (has `id`, `verificationUrl`, `status`, `mode`, …)
-  // verificationClientUrl selects a registered Verification Client by URL.
-  // teeAttestation: { appSecret } — optional org verification private key;
-  //   kept local while the SDK derives and registers the post-create TEE binding.
+  // verificationClientUrl selects a registered Verification Client by URL;
+  // omitted, it defaults to the Portal.
+  // orgEthPrivateKey optionally creates the post-create TEE binding locally.
   // The returned verificationUrl contains sessionId and api=2.
-reclaim.sessions.bindTeeNonce(sessionId, { appSecret, timestamp? })
+reclaim.sessions.bindTeeNonce(reclaimSessionId, { orgEthPrivateKey, timestamp? })
   // Explicit two-step/retry form. Reads the session, derives locally, and binds.
-reclaim.sessions.get(sessionId)         // → VerificationSession
-reclaim.sessions.listEvents(sessionId)  // → VerificationEventRecord[]
+reclaim.sessions.get(reclaimSessionId)         // → VerificationSession
+reclaim.sessions.listEvents(reclaimSessionId)  // → VerificationEventRecord[]
 ```
 
 The Builder resolves `verificationClientUrl` to the session's registered
@@ -654,45 +684,21 @@ the selected Verification Client understands; the Builder does not interpret
 or execute them. A URL without `api=2` is handled by the selected client's
 legacy path.
 
-### `reclaim.callbacks`
-
-```ts
-reclaim.callbacks.register({ callbackUrl, events? })  // the dashboard preselects 5 terminal events
-  // → CallbackSubscription. Org-scoped; no address/publicKey/secret.
-reclaim.callbacks.list()                  // → CallbackSubscription[]
-reclaim.callbacks.remove(subscriptionId)  // → void
-```
-
-`events` is any subset of `VerificationEvent`. Builder terminal events are
-`verification_success`, `verification_rejected`, `verification_error`,
-`verification_cancelled`, and `session_expired`. The dashboard preselects all
-five. Terminal result deliveries contain the signed result when one is
-available. Treat cancellation and expiry as terminal outcomes.
-Non-terminal events deliver plaintext progress notifications.
-
-### `reclaim.keypair` (the organization's single ETH encryption key)
-
-```ts
-await reclaim.keypair.set(orgId, { publicKey, canEncryptResult?: true, label?: 'prod' })  // → OrgKeypair
-await reclaim.keypair.get(orgId)  // → OrgKeypair | undefined (undefined ⇒ keyless / plaintext delivery)
-```
-
-`publicKey` is the organization's ETH **uncompressed public key** (`0x04` +
-128 hex — the form `generateEthKeypair()` and ethers produce). Alternatively,
-pass `publicKeyJwk` (a secp256k1 JWK). `set` stores the JWK and derived ETH
-address. There is exactly **one** keypair per organization; `set` replaces it
-(rotation). `canEncryptResult` toggles whether results are encrypted to it
-(default `false` ⇒ plaintext). Keep the matching **ETH private key** (`0x`-hex)
-and pass it as the decryption key to `results.receive`/`decrypt`.
-
 ### `reclaim.results`
 
 ```ts
 reclaim.results.receive(body, opts?)        // → ReceivedDelivery  ← the 90% path
-reclaim.results.decrypt(body, credential?)  // → Jws   (ECIES or plaintext → signed JWS)
+reclaim.results.decrypt(body, orgEthPrivateKey?) // → Jws
 reclaim.results.verify(jws, opts?)          // → VerifyResultFullOutcome
 ```
 
+Each verified `result.proofs` entry includes the exact `proof` received
+from the Verification Client, its provider and request identity, all attestor
+addresses, derived proof hashes, trusted `data`, unverified `publicData`, and
+the claimant/session and attestor TEE verification outcomes. This preserves the
+complete proof for storage or on-chain use while keeping trusted
+extracted parameters separate from unverified convenience data.
+
 `receive` branches on the delivery:
 
 ```ts
@@ -701,23 +707,21 @@ type ReceivedDelivery =
   | { kind: 'event'; event: VerificationEvent; eventData: Record<string, unknown> } // plaintext lifecycle event
 ```
 
-`opts` (`ReceiveOptions`) is `VerifyResultFullOptions` (`expectedReclaimSessionId`
-nonce check, `expectedAud`, trusted issuer configuration, attestor allowlists,
-`fetchImpl`, `now`, `ignoreExpiration`) **plus** an optional `credential` — the ETH decryption key
-as a **`0x`-hex private key string** (the key content, not a path or environment
-variable name). All three methods are async; pass `credential` only when the
-delivery is encrypted.
+`ReceiveOptions` includes the `reclaimSessionId` check, `expectedAud`, trusted
+issuer configuration, attestor allowlists, and an optional
+`orgEthPrivateKey`. The private key decrypts encrypted results and verifies TEE
+proof binding. All three methods are async.
 
-`verifyResultFull` is the recommended server-side API. Configure either an
-explicit `issuer`/`trustedIssuers` list, or resolve the registered issuer for
-the signed session's `verificationClientId`:
+`verifyResultFull` is the recommended server-side API. Configure the canonical
+Builder issuer and well-known JWKS URL (or keep those values in your own
+server-side trust configuration):
 
 ```ts
 await reclaim.results.verify(jws, {
-  expectedReclaimSessionId: session.id,
+  reclaimSessionId: session.id,
   expectedAud: orgId,
-  resolveIssuers: (verificationClientId) => registry.issuersFor(verificationClientId),
-  resolveJwksUrl: (verificationClientId) => registry.jwksUrlFor(verificationClientId),
+  trustedIssuers: ['https://build.reclaimprotocol.org'],
+  jwksUrl: 'https://build.reclaimprotocol.org/.well-known/jwks.json',
 })
 ```
 
@@ -726,21 +730,36 @@ fetches JWKS. It never uses an untrusted `iss` as a network destination. Keep
 issuer resolution server-side and treat a missing or changed issuer as a
 verification failure.
 
-Issuer trust and key discovery are separate inputs: resolve the registered
-`verificationClientIssuer` and `verificationClientJwksUrl` independently (or
-pass `trustedIssuers` and `jwksUrl`). Do not construct the JWKS URL from the
-JWS payload.
+Issuer trust and key discovery are separate Builder deployment inputs. Do not
+construct the JWKS URL from the JWS payload.
 
-`verifyResultFull` calls this package's legacy-compatible `verifyProof`
+`verifyResultFull` calls this package's `verifyRequestProof`
 implementation for every exact `Proof` object in the signed result. It does
 not base64-decode, wrap, reconstruct, or otherwise transform those proofs.
+When you provide `reclaimSessionId`, every proof must
+also contain that session ID. This prevents a valid proof from an older session
+from being placed in a newly signed result envelope. For an older deployment
+that produced unbound proofs, set `proofValidation.requireSessionBinding` to
+`false` explicitly during its migration. A different embedded session ID is
+always rejected.
 By default, it uses each result's
-`provider_id` and exact `resolved_version` to resolve the legacy provider hash
+`provider_id` and exact `resolved_version` to resolve the provider hash
 requirements. You can instead pass `hashes`, `proofValidation`, or
-`proofValidationByProviderId`. These options mirror the legacy verifier,
+`proofValidationByProviderId`. These options mirror `verifyRequestProof`,
 including `hasNoPii`, verifier TEE (`teeAttestation.appSecret`), and
-attestor-TEE checks. The same registered Builder JWKS URL supplies the
-purpose-bound result keys and its `x-reclaim-attestors` trust list. TEE settings preserve the legacy configuration objects;
+attestor-TEE checks. The configured Builder JWKS URL supplies the
+purpose-bound result keys, its `x-reclaim-attestors` signer list, and its
+`x-reclaim-attestor-image-digests` Confidential Space image allowlist. When
+the JWKS publishes image digests, `verifyResultFull` automatically verifies
+every witness's attestor TEE `claimAttestation` — its attestor address and
+claim signature always, and its `attestation_report` when the witness carries
+one. The report is optional: production attestors sign claims without
+returning one, so a witness with only an address and a signature verifies, and
+`isAttestorTeeAttestationVerified` comes back `false` to say nothing was
+attested. If
+`proofValidation.attestorTeeAttestation.expectedImageDigests` is also set, the
+SDK uses the intersection: caller policy can narrow the published trust list,
+but can't broaden it. TEE settings preserve the same configuration objects;
 `verifyResultFull` does not accept injected verification hooks. The surrounding
 issuer, session, and context checks are stateless; persist accepted session IDs
 in your application to prevent replay.
@@ -772,7 +791,10 @@ is therefore always verified; wrap the call to inspect failures:
 ```ts
 import { ResultVerificationError } from '@reclaimprotocol/client'
 try {
-  const { result } = await reclaim.results.receive(body, { credential })
+  const { result } = await reclaim.results.receive(body, {
+    orgEthPrivateKey,
+    reclaimSessionId,
+  })
   // result.payload is verified
 } catch (err) {
   if (err instanceof ResultVerificationError) {
@@ -802,18 +824,17 @@ loadDecryptionKey(hex): DecryptionKey            // 0x-hex eth private key → r
 uncompressedPubkeyToJwk(hex): Jwk                // 0x04+128 hex → secp256k1 JWK
 pubkeyJwkToEthAddress(jwk): string               // secp256k1 JWK → 0x eth address
 
-// ECIES (encryptForEthPublicKey is used by the first-party Verification Client; consumers only decrypt)
+// ECIES (Builder encrypts terminal results; consumers only decrypt)
 encryptForEthPublicKey(publicJwk, bytes): Promise<string>  // → ECIES ciphertext (base64url)
 decryptCallback(decryptionKey, body): Promise<Jws>          // ECIES/plaintext → JWS
 
-// Result JWS (eth ES256K)
-signResultJws(ethPrivHex, payload, issuer): Jws                // VC-side
+// Result JWS (Builder-managed ES256K)
 verifyResult(jws, opts): VerifyResultOutcome                   // offline signature/nonce check (throws if invalid)
-verifyResultFull(jws, opts): Promise<VerifyResultFullOutcome>  // + JWKS discovery + exact legacy-proof verification (throws if invalid)
+verifyResultFull(jws, opts): Promise<VerifyResultFullOutcome>  // + JWKS discovery + exact proof verification (throws if invalid)
 verifyJwsSignature(jws, signerPublicKey), decodeJwsPayload(jws)
 
-// JWKS (signature-key discovery / publishing)
-fetchJwks(url), jwksFromPrivateKey(ethPrivHex), selectKey(...), jwkToUncompressedPublicKey(jwk)
+// JWKS (signature-key discovery)
+fetchJwks(url), selectKey(...), jwkToUncompressedPublicKey(jwk)
 
 // Legacy compatibility helper. verifyResultFull does not use an inner proof JWS.
 verifyNestedProof(...): NestedProofOutcome