@crvouga/mockingbird-service-persona

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of Persona's identity-verification API for test suites: create an inquiry, the "reusable inquiry" list lookup, fetch one inquiry, the hosted flow page members are sent to, and the Persona-Signature-signed events Persona posts back. Inquiries move only when a test says so (an admin action or a click on the hosted page), so the Rx consultation's ID verification step (flag rx-id-verification) runs without a real sandbox or a real selfie.

• Operation coverage: SUPPORT.md
• Persona publishes no OpenAPI document: the contract (openapi.yaml) is hand-authored from Persona's API reference (JSON:API, Persona-Version: 2023-01-05) and our EMR's zod schemas.

Install

npm install -D @crvouga/mockingbird-service-persona

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-persona serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

Point the EMR at the emulator (all of these are required in E/config/env.ts):

npx mockingbird-persona serve --port 8815 \
  --webhook-url http://127.0.0.1:4000/v1/identify-verification/webhook \
  --webhook-secret "$PERSONA_WEBHOOK_SECRET"

import { createServer } from "@crvouga/mockingbird-service-persona/server"

// Test setup: a local Persona that posts its signed events to the app's webhook route.
const server = await createServer({
  webhooks: { url: "http://127.0.0.1:4000/v1/identify-verification/webhook", secret: "wbhsec_test" },
})
const baseUrl = server.url // the app's PERSONA_API_URL

// Application code: the request it sends to Persona.
const created = await fetch(`${baseUrl}/inquiries`, {
  method: "POST",
  headers: { authorization: "Bearer persona_sandbox_x", "content-type": "application/json" },
  body: JSON.stringify({
    data: { type: "inquiry", attributes: { "inquiry-template-id": "itmpl_identity", "reference-id": "patient-1" } },
  }),
})
const { data } = (await created.json()) as { data: { id: string } }

// Test control: finish it the way a member and Persona's workflow would: started → completed →
// approved, one signed event per step.
await fetch(`${baseUrl}/__admin/inquiries/${data.id}/approve`, { method: "POST" })

await server.close()

Routes

The inquiry resource carries Persona's attributes (status, reference-id, note, created-at, started-at, completed-at, failed-at, decisioned-at, expired-at, name-first/name-last/birthdate from prefill, fields as {type, value}) and relationships (inquiry-template.data {type: "inquiry-template", id}, empty reports, verifications, sessions, documents, selfies). Errors are JSON:API with a string status, which our consumer's PersonaErrorSchema requires.

Auth: Authorization: Bearer <key> on every API route (missing → 401 JSON:API error). PUT /__admin/settings {"apiKeys": [...]} restricts which keys are accepted.

Lifecycle and webhooks

created → pending → completed → approved | declined | needs_review, plus failed and expired from an open inquiry. A decision on an open inquiry passes through completed first (as a member finishing the flow and a workflow deciding would), so each step emits its own event: inquiry.created, inquiry.started, inquiry.completed, inquiry.approved, inquiry.declined, inquiry.marked-for-review, inquiry.failed, inquiry.expired.

Each event is Persona's envelope, {data: {type: "event", id: "evt_…", attributes: {name, payload: {data: <inquiry>, included: [], meta: {}}, created-at}}}, posted with Persona-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. The timestamp is wall clock. Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h); GET /__admin/webhooks, /__admin/webhooks/events, POST /__admin/webhooks/flush, /__admin/webhooks/:id/replay and PUT /__admin/webhook-endpoints work as everywhere.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): list_fails (the reusable lookup 500s; our client fails open and creates), create_fails, not_found, unauthorized, rate_limited (429), server_error, slow (3 s), webhook_duplicate, webhook_reorder, webhook_drop.

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix on PERSONA_API_URL and PERSONA_WEB_INQUIRY_URL (the hosted page's links keep it), or by API key: PUT /__admin/credentials {"credentials": {"<PERSONA_API_KEY>": "<namespace>"}}.

What our consumer does with it (discrepancies)

• Our EMR acts only on status === "completed" (updateIdentityVerificationForPatient); approved/declined events are parsed and ignored. So a declined inquiry has already marked the member verified at completed. The emulator sends both events so suites can see that.
• Our receiver compares signatures with crypto.timingSafeEqual, which throws on a length mismatch: a wrong-length v1= is an uncaught 500, not a 401 (signature-faults short).
• There is no official Persona Node SDK in our consumer (plain fetch), so there is no SDK drop-in test.

Deliberately not modelled

• Verifications, reports, sessions, documents and selfies: the relationships are always empty and no government-ID or selfie capture happens. The hosted page is a set of links.
• Inquiry templates' steps and workflows (next-step-name is only start / success), resume session tokens (POST /inquiries/{id}/resume), redaction, tags and accounts.
• Inquiry expiry on a timer: inquiries expire only through …/expire.
• The embedded (JS SDK / iframe) flow and mobile SDKs.

API

Part of mockingbird.