dashboard: three-QR signup ceremony demo at /demo/registration

End-user-visible counterpart to the ADR 0023 backend. The operator
opens the route, types a name + email, clicks "Open session & mint
QR1", and the page walks through three QR steps:

  1. QR1 ("Pair your phone") — encodes the pair-step deeplink. A
     phone scanning the QR (or, in this demo, the simulator panel)
     POSTs to /v1/registrations/pair-device with the code + a
     hardware fingerprint. Server flips state to awaiting_commitment
     and mints the enroll_code.

  2. QR2 ("Submit your biometric commitment") — the phone captures
     the biometric locally (mobile/biometric/ pipeline), computes
     the Poseidon commitment + DID, scans QR2 to POST them to
     /v1/registrations/submit-commitment. State flips to
     awaiting_verification; server mints verify_code + a 128-bit
     challenge_nonce baked into QR3's deeplink.

  3. QR3 ("Verify and create account") — phone re-captures the
     biometric, produces a Groth16 proof, scans QR3 to POST to
     /v1/registrations/complete. Server checks the challenge_nonce
     matches, asserts publicSignals[0] equals the stored commitment,
     verifies the proof off-chain, creates the tenant_user.

The biometric never crosses a wire. Only the commitment (step 2)
and the proof (step 3) do. The deeplink format is
zeroauth://reg?step=<pair|enroll|verify>&session=<uuid>&code=<code>
[&challenge=<hex>] — same format the android/ companion app
handles.

Right column is a "Simulate phone" panel that exercises the
phone-side endpoints directly so an operator can drive the
ceremony from one browser window without an actual companion app.
Pair + commit steps run end-to-end against the live backend. The
verify step intentionally lands a `verify_failed` because the demo
posts a stub Groth16 proof — that's the verifier doing its job. The
real green path goes through the android/ mobile prover (Phase 1
Sprint 4 integration).

Server side: three new console proxies at /api/console/registrations
(POST / GET :id / DELETE :id) mirror /v1/registrations but auth via
console JWT. Both surfaces strip pair_code_hash, enroll_code_hash,
verify_code_hash, verify_challenge_nonce out of the response shape
before it touches the browser — the plaintext codes are returned
only at issuance, the challenge nonce travels only in the QR3
deeplink.

Nav: "QR sign-in" + "QR signup" now sit side by side under the
shared /demo/ namespace; the old singular "Demos" label split to
make the two flows distinguishable.

Verify:
  - npx tsc --noEmit                  (dashboard + backend)  clean
  - npm test     (dashboard, vitest)  56/56
  - npm test     (backend, jest)      524/524 across 44 suites
  - npm run build (dashboard)         121 modules, QrRegistration
                                      lazy chunk = 28.4 kB / 9.95 kB
                                      gzip; main bundle unchanged

Author: Pulkit Pareek

dashboard/src/App.tsx

@@ -22,6 +22,10 @@ import { NotFound } from './routes/NotFound';
 // host today; lazy-loading keeps it (and any future scanner deps) out
 // of the main bundle until the operator opens /demo/qr-proof-login.
 const QrProofLogin = lazy(() => import('./routes/demo/QrProofLogin'));
+// The three-QR end-user signup ceremony demo (ADR 0023). Lazy-loaded
+// because qrcode.react (~30kB after tree-shake) only matters when the
+// operator opens the demo. The bundle main path never imports it.
+const QrRegistration = lazy(() => import('./routes/demo/QrRegistration'));
 
 // Live verifications view (SSE-streamed, ADR 0017 face-first flow).
 // Lazy-loaded so the EventSource cost is paid only when the operator
@@ -125,6 +129,14 @@ export function App() {
                       </RouteSuspense>
                     }
                   />
+                  <Route
+                    path="/demo/registration"
+                    element={
+                      <RouteSuspense>
+                        <QrRegistration />
+                      </RouteSuspense>
+                    }
+                  />
 
                   {/* ADR 0017 face-first views — live SSE counterparts to
                       the polled /verifications + /users. Both coexist

dashboard/src/components/layout/AppShell.tsx

@@ -55,7 +55,10 @@ const NAV = [
   // W3 wrapper demo: desktop QR-proof sign-in (ADR-0009). Sits under
   // its own /demo/ namespace so additional wrapper demos can co-locate
   // without polluting the primary console nav.
-  { to: '/demo/qr-proof-login', label: 'Demos', icon: 'qr' },
+  { to: '/demo/qr-proof-login', label: 'QR sign-in', icon: 'qr' },
+  // ADR 0023 three-QR end-user signup ceremony. Demos sit side-by-side
+  // under /demo/ so an operator can pick the flow they're presenting.
+  { to: '/demo/registration', label: 'QR signup', icon: 'qr' },
   { to: '/settings', label: 'Settings', icon: 'gear' },
 ] as const;
 

dashboard/src/lib/api.ts

@@ -286,6 +286,46 @@ export interface DeviceEnrollmentInvite {
   };
 }
 
+// ─── Three-QR end-user signup ceremony (ADR 0023) ────────────────
+
+export type RegistrationSessionState =
+  | 'awaiting_device'
+  | 'awaiting_commitment'
+  | 'awaiting_verification'
+  | 'completed'
+  | 'abandoned';
+
+/**
+ * Server-redacted shape of the registration_sessions row. The
+ * console proxy strips pair_code_hash, enroll_code_hash,
+ * verify_code_hash, and verify_challenge_nonce before this hits
+ * the browser — the plaintext codes are returned only at issuance
+ * (and only to the issuing browser).
+ */
+export interface RegistrationSession {
+  id: string;
+  tenant_id: string;
+  environment: Environment;
+  profile: Record<string, unknown>;
+  state: RegistrationSessionState;
+  device_id: string | null;
+  did: string | null;
+  commitment: string | null;
+  tenant_user_id: string | null;
+  pair_code_expires_at: string | null;
+  enroll_code_expires_at: string | null;
+  verify_code_expires_at: string | null;
+  expires_at: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface RegistrationStartResponse {
+  environment: Environment;
+  session: RegistrationSession;
+  pair: { code: string; expires_at: string; deeplink: string };
+}
+
 export interface User {
   id: string;
   external_id: string;
@@ -722,6 +762,52 @@ export const api = {
     },
   ) => request<{ environment: Environment; device: Device }>(`/api/console/devices/${encodeURIComponent(deviceId)}`, { method: 'PATCH', body: input }),
 
+  // Registrations — three-QR signup ceremony (ADR 0023). Console
+  // proxies live at /api/console/registrations/*. The plaintext
+  // pair_code is returned exactly once on POST; subsequent codes
+  // (enroll_code, verify_code) only travel from the server to the
+  // phone via the next-step deeplinks, never to the dashboard.
+  startRegistration: (input: {
+    environment: Environment;
+    profile?: Record<string, unknown>;
+  }) =>
+    request<RegistrationStartResponse>('/api/console/registrations', { method: 'POST', body: input }),
+  pollRegistration: (sessionId: string, params: { environment: Environment }) =>
+    request<{ environment: Environment; session: RegistrationSession }>(
+      `/api/console/registrations/${encodeURIComponent(sessionId)}`,
+      { query: params },
+    ),
+  abandonRegistration: (sessionId: string, params: { environment: Environment }) =>
+    request<{ environment: Environment; session: RegistrationSession }>(
+      `/api/console/registrations/${encodeURIComponent(sessionId)}`,
+      { method: 'DELETE', body: params },
+    ),
+  // Phone-side endpoints — the demo's "Simulate phone" panel calls
+  // these directly so the operator can drive the ceremony from one
+  // browser window without an actual phone. In production the phone
+  // hits these via /v1/registrations/* on the public origin.
+  __phonePair: (input: { pair_code: string; fingerprint: string; attestation_kind?: string }) =>
+    request<{
+      session_id: string;
+      device_id: string | null;
+      next: { step: string; code: string; expires_at: string; deeplink: string };
+    }>('/v1/registrations/pair-device', { method: 'POST', body: input, auth: false }),
+  __phoneSubmitCommitment: (input: { enroll_code: string; did: string; commitment: string; attestation_kind?: string }) =>
+    request<{
+      session_id: string;
+      next: { step: string; code: string; expires_at: string; deeplink: string; challenge_nonce: string };
+    }>('/v1/registrations/submit-commitment', { method: 'POST', body: input, auth: false }),
+  __phoneComplete: (input: {
+    verify_code: string;
+    challenge_nonce: string;
+    proof: unknown;
+    public_signals: unknown[];
+  }) =>
+    request<{ session_id: string; tenant_user: Record<string, unknown>; device: Record<string, unknown> | null }>(
+      '/v1/registrations/complete',
+      { method: 'POST', body: input, auth: false },
+    ),
+
   // Users
   listUsers: (params: { environment: Environment; status?: User['status']; limit?: number }) =>
     request<{ environment: Environment; users: User[] }>('/api/console/users', { query: params }),