@reclaimprotocol/agent 0.1.34 → 0.1.36

package/skill/verification-client-integration.md

@@ -21,12 +21,16 @@ server), or migrate to the session flow below. When migrating, remove
 1. `get_devtools_mode` confirms Builder mode. `get_me` or `authenticate` signs
    in the developer. Find the organization with `list_orgs`; call `create_org`
    only when they want a new one.
-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`; keep the private key only in
-   the backend. `set_org_keypair` refuses to replace an existing key unless you
-   pass `replace: true`; pass it only when the developer asks.
+2. Receive callbacks. Local development: call
+   `proxy_callback_events({ port, path })` to forward the org's events to the
+   app's callback route on localhost; no public URL. Deployed app (required for
+   production): register a
+   public callback URL with `create_org_callback_subscription`, including
+   all five session-ending events. If the
+   app needs encrypted results, register its public key with `set_org_keypair`;
+   keep the private key only in the backend. `set_org_keypair` refuses to
+   replace an existing key unless you pass `replace: true`; pass it only when
+   the developer asks.
 3. Org key: reuse the `RECLAIM_ORG_SECRET` the app already has. Otherwise an
    organization owner calls `issue_org_token`. It writes the key to the
    project's env file (default `.env`, variable `RECLAIM_ORG_SECRET`) and
@@ -43,12 +47,22 @@ server), or migrate to the session flow below. When migrating, remove
    is not proof of success. Use `@reclaimprotocol/client`
    (`ReclaimVerification.create({ orgSecret })`, `sessions.create`) only when
    the developer asks for it.
-5. Add a backend callback endpoint. Persist each delivery idempotently and load
+5. Add a backend callback route. Persist each delivery idempotently and load
    the expected session ID and org ID from app storage. To verify the result on
-   your callback, install `@reclaimprotocol/client` in the backend and call
+   your callback route, install `@reclaimprotocol/client` in the backend 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.
+   Store every failure on the verification session record: failure events, and
+   a thrown `ResultVerificationError` (`error.reason` and each
+   `error.outcome.proofs[].reason`). Respond `error.retryable ? 503 : 200`.
+   A result that failed verification gets 2xx: retrying can't fix it, and an
+   unacknowledged delivery holds back that session's later events. Respond 5xx
+   for any other temporary problem too, such as a database outage.
+   Add a status route that returns the stored status, data points, and failure
+   reason. While the app has no result, it also reads
+   `GET /verifications/sessions/{sessionId}`, so a session Builder has ended
+   never stays pending in the app. Render the frontend per
+   [UI states](#ui-states).
 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
@@ -75,10 +89,12 @@ Use the API base URL the developer's Builder runs at (production:
 `https://build.reclaimprotocol.org`). Every call authenticates with
 `authorization: Bearer $RECLAIM_ORG_SECRET`.
 
-Subscribe a callback once (or use `create_org_callback_subscription`). Session
-creation returns 409 while the org has none, and a result is only delivered to
+Deployed apps subscribe a callback once (or use
+`create_org_callback_subscription`); local development uses
+`proxy_callback_events` instead. Session creation returns 409 while the org has
+no subscription, and a result is only delivered to
 subscriptions that include the event the session ends with, so subscribe to all
-five:
+five session-ending events:
 
 ```bash
 curl -X POST https://build.reclaimprotocol.org/verifications/callback-subscriptions \
@@ -119,16 +135,37 @@ Receive and verify the result on the callback route. This is the one place the
 client package is needed:
 
 ```js
-import { ReclaimVerification } from '@reclaimprotocol/client'
+import { ReclaimVerification, ResultVerificationError } from '@reclaimprotocol/client'
 
 const reclaim = ReclaimVerification.create({
   orgSecret: process.env.RECLAIM_ORG_SECRET,
 })
 
 app.post('/reclaim/callback', async(req, res) => {
-  const outcome = await reclaim.results.receive(req.body, {
-    reclaimSessionId: sessionId, // the id you stored
-  })
+  let outcome
+  try {
+    outcome = await reclaim.results.receive(req.body, {
+      reclaimSessionId: sessionId, // the id you stored
+    })
+  } catch(error) {
+    if(!(error instanceof ResultVerificationError)) {
+      throw error
+    }
+
+    if(error.retryable) {
+      return res.sendStatus(503) // temporary: Builder retries the delivery
+    }
+
+    // Retrying can't fix a result that failed verification. Store the failure
+    // where the status route returns it, then acknowledge the delivery.
+    const proofReasons = (error.outcome.proofs ?? [])
+      .filter((proof) => !proof.proofValid)
+      .map((proof) => proof.reason)
+    console.warn('result failed verification', error.reason, proofReasons)
+    await markSessionFailed(sessionId, error.reason) // your app's storage
+    return res.sendStatus(200)
+  }
+
   if(outcome.kind === 'result') {
     console.log(outcome.result.payload) // verified
   }
@@ -137,8 +174,34 @@ app.post('/reclaim/callback', async(req, res) => {
 })
 ```
 
-Check or investigate a session, from the backend (optional, e.g. a status
-endpoint the frontend polls) or by hand with `curl`. All take the org key:
+### UI states
+
+Apply these rules when you write the frontend. Test each state, including one
+failure.
+
+| State | Render |
+| --- | --- |
+| Idle | The **Verify** button. |
+| Waiting in the other tab | The current step ("Finish verifying in the new tab") and a way to reopen `verificationUrl`. After about 30 seconds, say what is happening and offer **Cancel** or **Try again**. |
+| Verifying | "Checking your result". |
+| Verified | The requested data points. |
+| Failed | A plain-language reason and what to do next, near the **Verify** button, with **Try again**. |
+| Expired or cancelled | Say which, with **Try again**. |
+
+- Show the current step, never an indefinite spinner (Nielsen heuristic 1,
+  visibility of system status).
+- Write errors in plain language that says what happened and what to do next,
+  visible next to the action, with a recovery action (Nielsen Norman Group
+  error-message guidelines).
+- Send reason codes (`error.reason`, proof `reason`) to logs or an expandable
+  **Details** section, not the headline.
+- Announce changes: `role="status"` (or `aria-live="polite"`) for progress,
+  `role="alert"` for failures (WCAG 2.2 SC 4.1.3).
+- Pair color with text or an icon (WCAG 2.2 SC 1.4.1).
+- Stop the waiting state when the status route reports a terminal status.
+
+Check or investigate a session from the status route or by hand with `curl`.
+All routes take the org key:
 
 | Route | Use |
 | --- | --- |