feat: age verification with an ID document (Didit), and closed registration (#4)

## Age verification with Didit

A new provider (`apps/api/src/age/didit.ts`) behind the existing vendor-neutral age interface. A person verifies once with an ID document, a passive liveness check and a face match; after that, all their linked IMVU accounts count as adult. The hub keeps only "over 18": never the document, photo or birth date.

- Webhooks are checked against Didit's signatures (the raw body or V2, with `-Previous` during secret rotation), and old ones are rejected. If the webhook has no decision, the hub fetches it from Didit.
- A later answer replaces an earlier one. An approval that's taken back (say, after a manual review) becomes `revoked`. A check still in review stays pending.
- Limits, for every provider: one unfinished check per person (starting again resumes it), at most 3 checks in 30 days, none once verified, and a monthly cap (`DIDIT_MONTHLY_LIMIT`, default 30: since 2026-11-01, Didit's free plan is $10 of credit a month, and a check costs $0.30).
- People are only ever sent back to the hub's website.
- The Account page gets an Age Verification card.
- Configuration: `AGE_PROVIDERS=imvu,didit`, `DIDIT_API_KEY`, `DIDIT_WORKFLOW_ID`, `DIDIT_WEBHOOK_SECRET`. The webhook is `<API_URL>/api/v1/age/webhook/didit`.

## Closed registration

Registration is open or closed. It's an admin's setting in the console, with its default from `REGISTRATION`.

- When it's closed, new accounts can only sign in until a moderator approves them, or declines them (which deletes the account).
- The website shows people who are waiting a waiting page, and the API treats them as signed out everywhere but `/me`.
- The console gets a Waiting count, a Waiting for approval filter, Approve and Decline on a person's page, and a Registration setting.
- The migration adds `user.approved` (existing accounts stay approved) and `hub_setting`.

## Testing

- New tests cover Didit (with a fake Didit server), the limits, revocation, return addresses and registration.
- `bun run test`: 35 pass. `bun run check-types` passes.
- Checked locally: the account, waiting, sign-up and console pages render.
- Not run against Didit itself yet. The sandbox workflow "T5DE Age Check" is published, and the next step is a real webhook once this is on staging.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Age verification with Didit

A new provider (`apps/api/src/age/didit.ts`) behind the existing vendor-neutral age interface. A person verifies once with an ID document, a passive liveness check and a face match; after that, all their linked IMVU accounts count as adult. The hub keeps only "over 18": never the document, photo or birth date.

- Webhooks are checked against Didit's signatures (the raw body or V2, with `-Previous` during secret rotation), and old ones are rejected. If the webhook has no decision, the hub fetches it from Didit.
- A later answer replaces an earlier one. An approval that's taken back (say, after a manual review) becomes `revoked`. A check still in review stays pending.
- Limits, for every provider: one unfinished check per person (starting again resumes it), at most 3 checks in 30 days, none once verified, and a monthly cap (`DIDIT_MONTHLY_LIMIT`, default 30: since 2026-11-01, Didit's free plan is $10 of credit a month, and a check costs $0.30).
- People are only ever sent back to the hub's website.
- The Account page gets an Age Verification card.
- Configuration: `AGE_PROVIDERS=imvu,didit`, `DIDIT_API_KEY`, `DIDIT_WORKFLOW_ID`, `DIDIT_WEBHOOK_SECRET`. The webhook is `<API_URL>/api/v1/age/webhook/didit`.

## Closed registration

Registration is open or closed. It's an admin's setting in the console, with its default from `REGISTRATION`.

- When it's closed, new accounts can only sign in until a moderator approves them, or declines them (which deletes the account).
- The website shows people who are waiting a waiting page, and the API treats them as signed out everywhere but `/me`.
- The console gets a Waiting count, a Waiting for approval filter, Approve and Decline on a person's page, and a Registration setting.
- The migration adds `user.approved` (existing accounts stay approved) and `hub_setting`.

## Testing

- New tests cover Didit (with a fake Didit server), the limits, revocation, return addresses and registration.
- `bun run test`: 35 pass. `bun run check-types` passes.
- Checked locally: the account, waiting, sign-up and console pages render.
- Not run against Didit itself yet. The sandbox workflow "T5DE Age Check" is published, and the next step is a real webhook once this is on staging.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: dhkatz <[email protected]>

docs/api.md

@@ -17,10 +17,11 @@ is. Codes: `invalid`, `signed_out`, `forbidden`, `not_found`, `no_such_imvu_acco
 
 | | |
 | --- | --- |
-| `POST /api/auth/sign-up/email` | `{email, password, name, username}`. Usernames 3-32 of `A-Za-z0-9_`; passwords 10-256 characters. The first account is an admin. |
+| `POST /api/auth/sign-up/email` | `{email, password, name, username}`. Usernames 3-32 of `A-Za-z0-9_`; passwords 10-256 characters. The first account is an admin. With registration closed, the others wait for approval (`approved: false`): every route but `/me` answers 403 `awaiting_approval`, and the rest of the hub treats them as signed out. |
 | `POST /api/auth/sign-in/username` | `{username, password}` |
 | `POST /api/auth/sign-out` | |
-| `GET /api/v1/me` | `{person}`, with `picture`: the avatar picture of their first linked IMVU account (from IMVU, kept an hour), or `null` |
+| `GET /api/v1/me` | `{person}` (`approved` false while waiting), with `picture`: the avatar picture of their first linked IMVU account (from IMVU, kept an hour), or `null` |
+| `GET /api/v1/hub` | (anyone) `{registration}`: `open` or `closed` |
 
 ## Proxies
 
@@ -97,17 +98,20 @@ person-level providers (phone wallets, document checks) are started here.
 
 | | |
 | --- | --- |
-| `GET /api/v1/age` | `{providers: [{id, label, scope}], checks}`: the providers in use and the person's own checks |
-| `POST /api/v1/age/:provider/start` | `{returnURL}` → `{kind: "done"}`, `{kind: "redirect", url, ref}` (send the person there) or `{kind: "browser", request, ref}` (hand `request` to the browser's Digital Credentials API) |
+| `GET /api/v1/age` | `{providers: [{id, label, vendor, scope}], checks}`: the providers in use and the person's own checks (newest first; status `pending`, `complete`, `failed` or `revoked`) |
+| `POST /api/v1/age/:provider/start` | `{returnURL}` (a path on the website, or an address on it) → `{kind: "done"}`, `{kind: "redirect", url, ref}` (send the person there) or `{kind: "browser", request, ref}` (hand `request` to the browser's Digital Credentials API). An unfinished check is given again. 409 `refused`: already verified, or a limit reached (`message` says which); 502 `provider_unavailable` |
 | `POST /api/v1/age/:provider/complete` | `{ref, response}`: the browser's answer, for wallet providers |
-| `POST /api/v1/age/webhook/:provider` | the provider's webhook; the provider checks its signature |
+| `POST /api/v1/age/webhook/:provider` | the provider's webhook; the provider checks its signature (401 if it isn't the provider's). A later answer replaces an earlier one (an adult answer taken back is `revoked`) |
 
 ## Console (moderators; roles: admins)
 
 | | |
 | --- | --- |
 | `GET /api/v1/console` | `{counts, connections, online, audit}` |
-| `GET /api/v1/console/people?q=` | `{people}` |
+| `GET /api/v1/console/people?q=&waiting=true` | `{people}` (`waiting`: only accounts waiting for approval) |
+| `POST /api/v1/console/people/:id/approve` | `{person}` |
+| `POST /api/v1/console/people/:id/decline` | an account waiting for approval: deletes it |
+| `GET /api/v1/console/settings`, `PUT` (admins) | `{registration}`: `open` or `closed` (default: the API's `REGISTRATION`, else open) |
 | `GET /api/v1/console/people/:id` | `{person, links, computers}` |
 | `POST /api/v1/console/people/:id/link-cap` | `{linkCap}` (0-1000) |
 | `POST /api/v1/console/people/:id/ban` | `{reason}`; only admins ban moderators |

docs/design.md

@@ -100,6 +100,9 @@ age, not verified) and `tagline`.
 - **Switching accounts in the client**: the proxy sees which IMVU account logs in and tells the hub. Not linked:
   offer to link. Linked to another hub account: no community features that session.
 - **Bans** apply to the person, so all linked accounts.
+- **Registration** is open or closed, an admin's setting in the console (default from `REGISTRATION`; staging is
+  meant to be closed, for testers only). Closed: anyone can sign up, but the account can only sign in until a
+  moderator approves it (or declines it, deleting it); the hub treats it as signed out everywhere else.
 
 ## Age (**Decided**: free, several providers, vendor-neutral)
 
@@ -112,8 +115,11 @@ No payment for verification (adult content rules out mainstream merchants of rec
 2. **Phone wallets** (planned): a government ID in Google Wallet, Apple Wallet or an EU age-verification wallet,
    asked for "age over 18" only, through the browser's Digital Credentials API. Free for the hub; no documents or
    birth date reach it. Scope: the person.
-3. **ID document and selfie** (planned): Didit's hosted check, within its free monthly allowance. Scope: the person
-   (the liveness step stops someone using another person's ID).
+3. **ID document and selfie** (live, `didit`): Didit's hosted check: ID document $0.15, passive liveness $0.10 and
+   face match $0.05, so $0.30 a check, paid from the free plan's $10 of credit a month (since 2026-11-01; the 500
+   free checks a month are gone), so about 30 a month unless topped up. Scope: the person (liveness and face match
+   stop someone using another person's ID). Over 18 is worked out from the age Didit reads off the document;
+   nothing else is kept. With so few checks, phone wallets (free) should become the main way.
 
 ### How it's built
 
@@ -128,14 +134,25 @@ No payment for verification (adult content rules out mainstream merchants of rec
   webhook), and optionally `recheck` (for providers whose answer can change, like IMVU). Which ones run is
   configuration (`AGE_PROVIDERS`), with each provider's keys in its own settings. Adding or replacing a vendor is
   one new adapter; nothing else changes.
-- Webhooks arrive at `/api/v1/age/webhook/<provider>` and each provider checks its own signature.
+- Webhooks arrive at `/api/v1/age/webhook/<provider>` and each provider checks its own signature. The provider's
+  latest answer stands: one taken back after approval (say, by a manual review) becomes `revoked`.
+- **Limits** on checks of a person, for every provider: one unfinished check at a time (starting again gives the
+  same one), at most 3 started in 30 days, none once verified, and a provider's monthly cap (`monthlyLimit`; Didit's
+  `DIDIT_MONTHLY_LIMIT`, default 30), counted from the checks started this month (UTC).
+- People are sent back only to the hub's website (`returnURL` is a path on it, or an address on `WEB_URL`).
 - Enforced at three points: catalogs (adult files need an adult token), the hub (adult items left out of room
   channels for viewers who aren't adult and opted in), and the viewer's proxy.
 
+### Setting up Didit
+
+In Didit's console (business.didit.me): an application; a KYC workflow with ID verification, passive liveness and
+face match only (no IP analysis, AML or proof of address, which cost extra; no white label, $0.10 a session more);
+an API key; and a webhook destination
+`<API_URL>/api/v1/age/webhook/didit` with its secret. Then the API's environment: `AGE_PROVIDERS=imvu,didit`,
+`DIDIT_API_KEY`, `DIDIT_WORKFLOW_ID`, `DIDIT_WEBHOOK_SECRET`. Use the sandbox application on staging.
+
 ### To add the planned providers
 
-- Didit: an account, an API key and webhook secret, and a workflow set to ID document plus liveness, returning
-  only "over 18". Confirm its free monthly allowance covers age checks.
 - Wallets: Google's Digital Credentials verifier registration (free), and an `age_over_18` request (OpenID4VP,
   mdoc); Apple and the EU wallet through the same browser API where supported.