Deploy KeyCape client MFA override for coulomb-social

Register coulomb-social with mfaRequired: false, roll key-cape image that
honors client policy, and track NK-WP-0025 public registration orchestration.

docs/public-registration-orchestration-contract.md

@@ -0,0 +1,106 @@
+# Public registration orchestration contract
+
+Status: implementation contract for NK-WP-0025-T02 and USER-WP-0022-T01/T02.
+
+## Boundary
+
+`user-engine` owns the public registration state machine. It never accepts an
+LLDAP password or an LLDAP administrator credential. A verification service
+proves mailbox control; the existing identity-provisioner creates the ordinary
+LLDAP identity and returns a provider-owned, single-use password-setup URL.
+
+The public browser is not an authenticated user-engine actor. It receives only
+opaque registration and verification handles. A verified applicant actor is
+constructed from consumed verification evidence and is authorized only for
+the registration instance named by that evidence.
+
+## Public flow
+
+1. `POST /api/v1/public/registrations`
+   accepts `username`, `email`, `display_name`, `client_id`, and optional
+   `tenant_hint`. Client and tenant values must be registered allow-list
+   entries; browser-provided return URLs are rejected.
+2. The response is always the same `202 Accepted` envelope for syntactically
+   valid requests, whether the username/email is new, duplicated, throttled,
+   or already pending. It contains no existence result.
+3. user-engine records an expiring registration intent and emits
+   `registration.verification_requested` through its transactional outbox.
+   The mail receiver obtains the recipient and an opaque verification handle;
+   the general event receiver gets only `recipient_present=true`.
+4. `POST /api/v1/public/registrations/verify` consumes the opaque handle.
+   Verification is single-use, expiry checked, purpose bound, and returns
+   normalized mailbox evidence bound to the registration ID and submitted
+   username.
+5. user-engine attaches the verified email factor, completes registration,
+   and calls identity-provisioner using the registration ID as the stable
+   idempotency key. Only the baseline ordinary-user group may be requested.
+6. The provisioner creates or resumes exactly one LLDAP identity, links the
+   provider subject to the user-engine user, and returns its single-use
+   password-setup URL. Provider collision is a reconciliation result, never a
+   second privileged identity.
+7. After provider password setup, the browser starts a fresh KeyCape
+   authorization-code/PKCE flow for the allow-listed client. Registration
+   state is never accepted as an application session.
+
+## Required state
+
+Registration intent persistence must include:
+
+- opaque registration ID and lifecycle status;
+- normalized username and email hash, with display values separately
+  protected from general event/audit output;
+- registered client ID and tenant;
+- verification handle digest, issued/expiry/consumed timestamps, attempt
+  counters, and purpose;
+- provisioning idempotency key and external provider result;
+- allow-listed post-setup authorization target identifier, not a raw URL;
+- correlation ID and redacted failure/compensation state.
+
+No password, verification token plaintext, LLDAP admin credential, MFA seed,
+or provider bearer token may enter registration state, logs, audit, State Hub,
+or the general event lane.
+
+## Validation and abuse controls
+
+- Usernames use the LLDAP-compatible canonical grammar, length limit, and
+  reserved-name list; case folding happens before uniqueness checks.
+- Email is normalized for comparison without provider-specific alias
+  rewriting. Mailbox verification proves control but does not authorize
+  linking to an existing user.
+- Rate limits apply per source network bucket, normalized email digest, and
+  username digest. Responses and timing remain non-enumerating.
+- CSRF applies to browser form submission; JSON callers additionally require
+  an allow-listed client registration and idempotency key.
+- Verification handles are random, high entropy, stored only as a digest,
+  purpose-bound, expiring, and atomically consumed.
+- Duplicate email/username, expired/replayed verification, and provider
+  conflict enter explicit reconciliation or terminal states. They never fall
+  back to auto-linking by email.
+
+## Provider contract
+
+The identity-provisioner request is the existing `ProvisioningRequest` plus a
+validated canonical username. The response remains `ProvisioningResult` with
+`external_subject`, `status`, and optional `password_setup_url`.
+
+For public registration the adapter must guarantee:
+
+- the same idempotency key returns the same external subject;
+- baseline membership only; no tenant-admin or platform groups;
+- password setup is provider-owned, single-use, and expiring;
+- partial creation is resumable/reconcilable and observable without exposing
+  credentials;
+- the external subject is linked before registration reports completion.
+
+## Activation gates
+
+Public registration stays disabled until all of the following pass together:
+
+1. verification issuer and mail receiver conformance, including replay and
+   expiry;
+2. user-engine persistence migration and anonymous-route abuse controls;
+3. flex-auth policy limiting the verified applicant actor to its registration;
+4. identity-provisioner canonical-username/idempotency conformance;
+5. KeyCape fresh-login return flow and client allow-list checks;
+6. disposable-user live tests and cleanup on railiance01.
+