feat(auth): pre-persist registration webhook so rejected signups never leave orphaned Kratos identities

[islandbitcoin]

Why

On 2026-09-01 every api replica crash-looped on requests from identities that exist in Kratos but have no Mongo account (#499 covers the crash side). Those orphans are created by the registration webhook itself: http://api:4002/kratos/registration is configured response.parse: false, and in Kratos v1.0.0 (what prod runs) that is a post-persist hook — the identity is committed before the api is even called. Any rejection inside createAccountWithPhoneIdentifier strands it. From today's api logs, in a few hours:

• DuplicateKeyForPersistError × 26 (a users document already holding the phone)
• IbexError × 13
• InvalidCarrierTypeForPhoneMetadataError × 3 (a policy rejection raised after the identity was already committed)

plus any pod dying mid-hook.

Kratos mechanics (verified in ory/kratos at v1.0.0)

selfservice/hook/web_hook.go:

func (e *WebHook) ExecutePostRegistrationPrePersistHook(...) error {
	if !(gjson.GetBytes(e.conf, "can_interrupt").Bool() || gjson.GetBytes(e.conf, "response.parse").Bool()) {
		return nil
	}
	...
func (e *WebHook) ExecutePostRegistrationPostPersistHook(...) error {
	if gjson.GetBytes(e.conf, "can_interrupt").Bool() || gjson.GetBytes(e.conf, "response.parse").Bool() {
		return nil
	}

So response.parse: true (or the deprecated can_interrupt: true) moves the hook before persistence. parseWebhookResponse then defines the contract: status ≥ 400 must carry a JSON body {"messages":[{"instance_ptr":"#/traits/phone","messages":[{"id":<int>,"text":"…","type":"error"}]}]} and aborts the flow with those messages (nothing is persisted); a 200 must be JSON ({} is fine) or a 204; a non-JSON body on either path fails the registration with an opaque "webhook failed". response.ignore must stay false on that hook. In the pre-persist hook ctx.identity.id is the nil uuid (identity.NewIdentity() sets ID: uuid.Nil; the persister assigns the real id).

Why two hooks, not one

Moving the whole account write pre-persist would create the inverse orphan: a Mongo account (and a users document holding the phone) whose Kratos persist then fails — e.g. two concurrent registrations for the same number — which locks that phone out of ever registering. So:

1. New pre-persist hook POST /kratos/preregistration (response.parse: true) — validation only, no writes: callback secret, schema, phone parse, carrier metadata (PhoneMetadataValidator), and "no users document already binds this phone" (the DuplicateKey source). identity_id is never inspected.
2. Existing post-persist /registration hook unchanged — still creates the account once the identity exists. What it can still leave behind (infra failure mid-hook) is what fix(auth): never crash the api on an orphaned kratos identity; self-heal missing accounts #499's session self-heal repairs.

This is the design the team sketched in dev/ory/kratos.yml (the commented preregistration hook).

Changes

• src/servers/event-handlers/kratos.ts — new route POST /kratos/preregistration; always JSON. /registration untouched.
• src/app/authentication/validate-preregistration-payload.ts — read-only app function.
• src/domain/authentication/registration-payload-validator.ts — PreRegistrationPayloadValidator (no identity id); the phone/metadata checks are shared with the existing validator, whose behaviour is unchanged.
• src/domain/authentication/kratos-hook-messages.ts — the hook contract: message ids, texts, body builder, and the id extractor used on the client side.
• src/services/kratos/registration-flow-error.ts — when Kratos hands the rejected flow back as a 400, map our ids back to domain errors: 4100002 → PhoneAlreadyRegisteredError (INVALID_INPUT, sign-up wording: "This phone number is already registered. Contact support if you can't sign in" — deliberately not PhoneAlreadyExistsError, whose "one phone per account" text belongs to the add-phone-to-account flow); 4100001 → PhoneNotAllowedForRegistrationError; 4100003 / 4100401 / 4100500 → RegistrationHookFailedError (ErrorLevel.Critical: malformed hook payload, bad callback secret or repository failure is a deploy defect, so it goes to the unexpected-error catch-all and is never reported as a phone-policy answer); any other 400 keeps today's LikelyUserAlreadyExistError. Wired into createIdentityWithSession and createIdentityWithCookie (createIdentityNoSession uses the admin API, which runs no self-service hooks, and is left alone).
• src/graphql/error-map.ts — PhoneNotAllowedForRegistrationError → validation error "This phone number can't be used to sign up"; PhoneAlreadyRegisteredError → validation error "This phone number is already registered. Contact support if you can't sign in" (both INVALID_INPUT, neither falls into the retry-and-contact-support catch-all); RegistrationHookFailedError joins the unexpected-error catch-all.
• dev/ory/kratos.yml — real pre-registration hook entry, before the existing one.
• docker-compose.yml — integration-tests gets the bats-tests network alias (and depends_on: kratos) so the compose Kratos can reach the hook routes the integration suite serves from the test process.
• quickstart/bin/splice-kratos-preregistration-hook.sh + quickstart/bin/re-render.sh + quickstart/dev/ory/kratos.yml — the quickstart copy is not derived from dev/ory/kratos.yml: re-render.sh vendir-syncs upstream galoy at the pinned ref (which still ships the hook commented out) and only rewrites hosts, and both Quickstart CI and make smoke-env-up run make re-render before boot, so a hand edit is lost on the next render. The splice runs after the host rewrite, inserts the response.parse: true hook ahead of /registration, retires upstream's commented-out draft, is a no-op when the hook is already there, and fails the render (exit 1) when the /registration anchor is missing or laid out differently. The rendered file is regenerated and committed; only its hooks list changed.

Route contract

Case	Status	Body
pass	200	{}
phone unparsable / carrier metadata invalid	400	id 4100001 "This phone number can't be used to sign up."
phone already bound to a users document	400	id 4100002 "This phone number is already registered."
hook payload malformed (missing phone/schema, wrong schema)	400	id 4100003 "Sign-up request was invalid. Please try again."
bad callback secret	401	id 4100401 "Sign-up is temporarily unavailable."
unexpected error (e.g. Mongo down)	500	id 4100500 "Sign-up is temporarily unavailable. Please try again."

Every non-200 body is {"messages":[{"instance_ptr":"#/traits/phone","messages":[{"id":…,"text":…,"type":"error"}]}]}.

Deploy order (matters)

1. Ship this api image first. The route must exist before Kratos is told to call it.
2. Then the config PRs (charts values.yaml and deployments tf-modules/flash/kratos-postgres/postgres-values.tmpl.yaml): add the web_hook for http://api:4002/kratos/preregistration with response: { parse: true } before the existing /registration hook. Applying the config first would fail every registration with "webhook failed".
3. TEST before prod.

Tests

Test Suites: 229 passed, 229 total
Tests:       3 skipped, 2474 passed, 2477 total
tsc --noEmit -p tsconfig.d.json: exit 0
tsc --noEmit: only the 2 pre-existing Express `Application` errors in graphql-server.ts / graphql-admin-server.ts
eslint: exit 0 on all 21 changed .ts files
typos: exit 0

Unit — new: preregistration-payload-validator.spec.ts (incl. the nil-uuid payload), kratos-hook-messages.spec.ts, validate-preregistration-payload.spec.ts, servers/event-handlers/kratos-preregistration-route.spec.ts (exact bodies for 200/400×3/401/500), services/kratos/registration-flow-error.spec.ts (all five ids, the unmapped-400 fallback, non-400 passthrough), dev/kratos-registration-hooks.spec.ts (both dev/ory/kratos.yml and quickstart/dev/ory/kratos.yml run the pre-persist hook before the post-persist one with the session hook last — fails on the previous rendered quickstart file — plus the splice script on upstream's input, idempotency and both refusal paths); regression case in error-map.spec.ts.

Integration — test/flash/integration/authentication/kratos-preregistration-hook.spec.ts drives the real self-service registration flow against the compose Kratos v1.0.0 with the api's hook routes served from the test process, and asserts against Kratos' admin API what was stored: a phone already bound to a users document is refused as PhoneAlreadyRegisteredError and no identity exists afterwards; carrier metadata the api rejects (carried through transient_payload → body.jsonnet) is refused as PhoneNotAllowedForRegistrationError, again with nothing persisted; an accepted sign-up still gets its account from the post-persist hook.

Quickstart — make re-render (ytt v0.55.1, vendir v0.46.1, galoy 6906f1b) reproduces the committed quickstart/dev/ory/kratos.yml; the splice gives byte-identical output under BSD awk (macOS) and mawk (ubuntu 24.04); Kratos v1.0.0 boots on the rendered config (config validated at startup, admin /health/ready ok, registration flow initialised).

Follow-ups

• Config PRs for charts + deployments (same route path and contract as above).
• Stale users documents (phone bound to a deleted identity) now get a clean "already registered" instead of an orphan; a reconcile for those is separate.
• InvalidCarrierTypeForPhoneMetadataError could also be checked in isAllowedToOnboard before the flow is even started; this PR makes the hook the safety net either way.
• make re-render on the pinned galoy ref also rewrites quickstart/galoy/**, quickstart/dev/apollo-federation/router.yaml, quickstart/graphql/public/schema.graphql and quickstart/vendir.lock.yml away from what is committed (pre-existing drift, reverted here to keep this PR to the hook); worth a separate re-sync so CI and the checked-in tree agree.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EtQzyzQ38thfC2F8BLK4u8

[islandbitcoin]

Simon review: 3 rounds. Round 1 (2 blockers, 5 should-fixes) and round 2 (2 should-fixes) applied in 6f55b1a and 6c6f199 by the fix pass; round 3's last should-fix (the splice script's no-op branch accepting a non-pre-persist hook) in the commit above. Full unit suite on the branch: 229 suites / 2,474 tests green; tsc only the 2 pre-existing Express errors; eslint clean.

🤖 Generated with Claude Code