@reclaimprotocol/agent 0.1.28 → 0.1.31

package/skill/verification-client-integration.md

@@ -0,0 +1,130 @@
+# Integrate a Builder verification client
+
+## Set up an application with the coding agent
+
+When asked to integrate Reclaim into an app, inspect that app's frontend,
+backend, package manager, configuration, and callback conventions. Complete
+the integration in its codebase and run its relevant checks. The MCP tools
+configure Builder resources; the coding agent's file tools edit the app.
+
+If the app depends on `@reclaimprotocol/js-sdk`, ask the developer first:
+keep it (call `set_devtools_mode({ mode: "old" })` and have them restart the MCP
+server), or migrate to `@reclaimprotocol/client` with the steps below. When
+migrating, remove `@reclaimprotocol/js-sdk` and replace its
+`ReclaimProofRequest` and `verifyProof` calls with the session flow below.
+
+1. Use `get_devtools_mode` to confirm Builder mode and `get_me` or
+   `authenticate` to sign in as the developer. Find the intended organization
+   with `list_orgs`; call `create_org` only when a new organization is wanted.
+2. Register a callback URL owned by the app's backend with
+   `create_org_callback_subscription`. Include terminal success, rejection,
+   error, cancellation, and expiry events. If the app needs encrypted results,
+   register its public key with `set_org_keypair`; retain the private key only
+   in the backend.
+3. An organization owner can call `issue_org_token`. Its `orgSecret` is shown
+   once. Put it in the app backend's secret configuration as
+   `RECLAIM_ORG_SECRET`; keep it out of frontend bundles, logs, source control,
+   and the final response. Reuse an already configured secret when available;
+   issue a new token when setup needs one.
+4. Install `@reclaimprotocol/client` in the backend. Use
+   `ReclaimVerification.create({ orgSecret })` to create sessions, save each
+   returned session ID alongside the app's own user or order, and return only
+   `verificationUrl` to the frontend. The frontend opens that URL and asks its
+   backend for the final status; a browser redirect alone is not proof of
+   success.
+5. Add a backend callback endpoint. Persist each delivery idempotently, load
+   the expected session ID and org ID from app storage, and call
+   `reclaim.results.receive(body, { reclaimSessionId, expectedAud,
+   orgEthPrivateKey })`. Use the verified proof data to update app state.
+   Handle callback retries and terminal failure outcomes.
+6. Exercise one session through the selected registered Verification Client,
+   inspect its Builder events, and test the app's success and failure paths.
+   Omit `verificationClientUrl` to use the Portal, or select another client
+   from `VerificationClient` in the SDK. Do not send an unregistered URL or
+   call a legacy backend for an `api=2` session.
+
+The one-time management calls above use the developer's Builder login. The
+consumer backend uses the separate organization token. The SDK's API-only
+entry point, `@reclaimprotocol/client/api`, is available when an application
+needs typed Builder operations without the full verification workflow.
+
+## Create and launch a session
+
+Consumers authenticate with an organization token (`rorg_…`, issued in the
+dashboard or via `POST /orgs/{orgId}/token`) and call
+`POST /verifications/sessions`. Open the returned `verificationUrl` for the
+claimant. It contains only the registered Verification Client URL, session ID,
+and `api=2` mode selector.
+
+A consumer can pass `launchOptions` (`redirectUrl`/`redirectUrlOptions` on
+success, `cancelRedirectUrl`/`cancelRedirectUrlOptions` on cancellation, `https:`
+only) in the `POST /verifications/sessions` body. Builder validates and stores
+them on the session at creation and returns them unchanged from bootstrap
+(`session.launchOptions`); it never redirects to them itself — only the
+Verification Client that renders the flow does. Set `diagnostics: true` on the
+same request only for deliberate troubleshooting, since diagnostic logs can
+contain personal data; Builder appends `diag=1` to `verificationUrl` for that
+session and strips any `diag` the consumer's own `verificationClientUrl` carries.
+
+An optional `themeId` selects an active organization theme. If it is absent,
+Builder snapshots the organization's most recently updated active theme. A
+localized consent block tells supported clients to show consent before the
+first provider. Branding and theme data don't affect proof trust.
+
+## Call the direct Builder API
+
+In `api=2` mode, send the registered client UUID in `x-reclaim-vc-id` on every
+request. Generate the client from `packages/app/openapi.yaml`; don't hand-write
+route types or proxy these calls through `api.reclaimprotocol.org`.
+The UUID must match the session, but it is public and doesn't authenticate the
+caller.
+
+| Route | Purpose |
+| --- | --- |
+| `GET /verifications/sessions/{sessionId}/bootstrap` | Load the session, resolved recipes, runtime configuration, branding, and theme. |
+| `PATCH /verifications/sessions/{sessionId}/claimant` | Update the latest claimant and device snapshot. |
+| `POST /verifications/sessions/{sessionId}/events` | Report canonical lower-snake-case analytics events. |
+| `POST /verifications/sessions/{sessionId}/attestor-auth` | Request session-bound attestor authentication. Don't send a legacy application secret or provider signature. |
+| `POST /verifications/sessions/{sessionId}/results` | Submit exact proof objects or a terminal error/cancellation. Builder atomically records the canonical outcome and prepares signed callback delivery. |
+
+URLs without `api=2` stay on each client's existing legacy path. Builder mode
+must not call legacy lifecycle, application-info, or result APIs.
+
+## Preserve and verify proofs
+
+Verification Clients put each exact proof in the Builder result. They
+don't reverify proofs. Builder signs the outer result JWS without
+rewriting the proof.
+
+Consumers call `verifyResultFull` on their backend. It verifies the registered
+Builder issuer, outer JWS, session, audience, and every proof with the local
+`verifyRequestProof` implementation. Treat outer `extracted_parameters` and
+`content_hash` as diagnostics, not trusted proof inputs.
+
+Results are delivered to the org's registered callback subscriptions
+(`POST /orgs/{orgId}/callback-subscriptions`), plaintext by default. When the
+org has enabled `canEncryptResult` on its secp256k1 keypair
+(`PUT /orgs/{orgId}/keypair`), Builder ECIES-encrypts the terminal payload to
+that public key instead; decrypt it with `@reclaimprotocol/client`'s
+`decryptCallback`/`verifyResult` and the org's eth private key before treating
+it as a result. A session created without `canEncryptResult` never needs this
+step. Troubleshoot a stuck or failed session with `get_verification_session`,
+`list_verification_events`, and `list_org_verification_sessions`.
+
+## Use the browser extension
+
+For an `api=2` URL, use
+`reclaimExtensionSDK.fromVerificationUrl` or `initBuilder` with the returned
+`verificationClientId`, then call `startVerification()`. The extension sends
+`x-reclaim-vc-id`, loads recipes from bootstrap, runs them sequentially, and
+submits the raw proofs. It doesn't perform redundant `allowedJsRequests`
+validation. Missing or unknown `api` values keep the existing `init`,
+`fromJsonString`, and direct-callback behavior.
+
+## Bind a TEE nonce when required
+
+A consumer can pass `orgEthPrivateKey` to `sessions.create`. The SDK derives the
+legacy-compatible nonce locally, signs the binding payload with EIP-191, and
+calls `PUT /verifications/sessions/{sessionId}/tee-nonce` with the organization
+token. The private key stays in the consumer process. Bind before proof
+generation; the same binding is idempotent and a different binding is rejected.

package/src/consts.ts

@@ -64,12 +64,13 @@ export function reclaimHome(): string {
 
 /**
  * `USE_OLD_DEVTOOLS` — single source of truth for which backend the MCP
- * server targets. Defaults to OLD devtools while the builder backend is under
- * development. Builder mode must be opted into EXPLICITLY with
- * `USE_OLD_DEVTOOLS=false`; anything else keeps old mode on.
+ * server targets. Builder is the default. Set `USE_OLD_DEVTOOLS=true` to
+ * explicitly use the legacy backend.
  */
 export function useOldDevtools(): boolean {
-	return (process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase() !== 'false'
+	return ['true', '1'].includes(
+		(process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase(),
+	)
 }
 
 /** True when `USE_OLD_DEVTOOLS` is set to a non-empty value (explicit). */
@@ -79,7 +80,8 @@ function oldDevtoolsEnvSet(): boolean {
 
 /**
  * Effective mode, layering the persisted preference under the env var:
- * explicit `USE_OLD_DEVTOOLS` wins → persisted config `mode` → default (old).
+ * explicit `USE_OLD_DEVTOOLS` wins → persisted config `mode` →
+ * default (builder).
  * The persisted value comes from `~/.reclaim/config.json` (set via the
  * `set_devtools_mode` tool); the caller reads it so this module needn't import
  * `ConfigStore` (which would create an import cycle).
@@ -93,13 +95,13 @@ export function resolveOldMode(persisted?: 'old' | 'builder'): boolean {
 		return persisted === 'old'
 	}
 
-	return true
+	return false
 }
 
 /**
  * Where the effective mode came from — the same precedence as
  * `resolveOldMode`: explicit `USE_OLD_DEVTOOLS` env var → persisted config
- * `mode` → default (old). Surfaced by the `get_devtools_mode` tool so the
+ * `mode` → default (builder). Surfaced by the `get_devtools_mode` tool so the
  * user can tell why the server is in the mode it reports.
  */
 export function oldModeSource(