Plan production user onboarding portal

workplans/USER-WP-0020-self-service-and-user-administration-portal.md

@@ -0,0 +1,151 @@
+---
+id: USER-WP-0020
+type: workplan
+title: "Production self-service and user administration portal"
+domain: communication
+repo: user-engine
+status: ready
+owner: codex
+topic_slug: netkingdom
+created: "2026-07-27"
+updated: "2026-07-27"
+depends_on:
+  - USER-WP-0014
+  - USER-WP-0015
+  - USER-WP-0019
+---
+
+# USER-WP-0020 - Production self-service and user administration portal
+
+Turn the transport-neutral UI contracts from `USER-WP-0014` into a real,
+secure browser application and HTTP API backed by user-engine. The first
+production acceptance case is onboarding
+`bernd.worsch@binky-hedgehog.com` as tenant administrator for
+`tenant:friendly:binky`.
+
+user-engine remains authoritative for user-domain records, profiles,
+memberships, invitations, registration sessions, and onboarding state.
+KeyCape/NetKingdom remains authoritative for login, credentials, MFA,
+authentication sessions, and OIDC tokens. flex-auth remains authoritative for
+authorization decisions.
+
+## T01 - Ratify the portal boundary and threat model
+
+```task
+id: USER-WP-0020-T01
+status: todo
+priority: high
+```
+
+Define browser/API trust boundaries, public and authenticated routes, role
+projections, CSRF/session/XSS controls, rate limits, account-enumeration
+resistance, invitation abuse controls, audit correlation, privacy retention,
+and recovery behavior. Define an explicit `IdentityProvisioningPort`; the
+domain must not import LLDAP, privacyIDEA, KeyCape, email, or flex-auth clients.
+
+Keep enterprise federation, SCIM, corporate directory synchronization, and
+SAML administration out of scope while preserving provider-neutral identity
+links, membership envelopes, provisioning adapters, and external ownership
+metadata for that later stage.
+
+## T02 - Implement a production HTTP API
+
+```task
+id: USER-WP-0020-T02
+status: wait
+priority: high
+```
+
+Expose versioned APIs for registration start/resume/complete, invitation
+claim, current-user profile, tenant membership, onboarding, tenant-admin user
+management, and platform-admin tenant/user management. Consume verified
+KeyCape claims and require flex-auth decisions for protected writes. Add
+idempotency keys, optimistic concurrency, pagination, structured errors,
+OpenAPI, health/readiness, redacted audit, and transactional outbox behavior.
+
+## T03 - Implement self-service login and registration UX
+
+```task
+id: USER-WP-0020-T03
+status: wait
+priority: high
+```
+
+Build an accessible responsive browser flow for sign in, registration,
+invitation acceptance, email verification status, password-setup handoff,
+MFA-enrollment handoff, consent, profile completion, tenant selection, and
+resumable onboarding. Authentication and factor screens must redirect or
+handoff to NetKingdom-owned surfaces; the portal must never handle provider
+admin credentials or store password/MFA secrets.
+
+## T04 - Implement tenant-admin and platform-admin UX
+
+```task
+id: USER-WP-0020-T04
+status: wait
+priority: high
+```
+
+Tenant admins can invite, list, inspect, suspend, reactivate, and remove only
+users and memberships in tenants they administer, assign approved tenant
+roles, resend/expire invitations, and inspect redacted lifecycle/audit state.
+Platform admins can create/manage tenants, bootstrap the first tenant admin,
+inspect cross-tenant lifecycle gaps, and perform explicitly authorized
+recovery actions. Prove ordinary users and tenant admins cannot reach
+platform or other-tenant data.
+
+## T05 - Add production persistence and operability
+
+```task
+id: USER-WP-0020-T05
+status: wait
+priority: high
+```
+
+Package the service and web assets, use the provider-backed Postgres adapter,
+run migrations safely, expose metrics and structured logs, deliver secrets
+through approved runtime references, implement backups/restore evidence, and
+document rollback and zero-downtime upgrade expectations. Browser state must
+never become authoritative.
+
+## T06 - Security, accessibility, and workflow conformance
+
+```task
+id: USER-WP-0020-T06
+status: wait
+priority: high
+```
+
+Automate positive and negative flows for self-registration, invite-only
+registration where configured, duplicate identities, expired/replayed
+invitations, cross-tenant access, role escalation, CSRF, session expiry,
+provider outage, partial provisioning compensation, audit redaction, WCAG
+keyboard/screen-reader behavior, and mobile/desktop layouts.
+
+## T07 - Binky production acceptance
+
+```task
+id: USER-WP-0020-T07
+status: wait
+priority: high
+```
+
+Through the deployed portal—not a one-shot script—create or claim Binky,
+onboard `bernd.worsch@binky-hedgehog.com`, complete KeyCape login and MFA,
+assign only the Binky tenant-admin membership, and prove denial for
+`tenant:platform`, `tenant:coulomb`, and unrelated tenants. Confirm the same
+admin can invite and lifecycle-manage a disposable Binky test user.
+
+## T08 - Closure and next-stage handoff
+
+```task
+id: USER-WP-0020-T08
+status: wait
+priority: medium
+```
+
+Close after the portal is production-operable and the Binky acceptance case
+passes. Record enterprise federation follow-up triggers: customer demand for
+SAML/OIDC federation, SCIM, directory synchronization, just-in-time
+provisioning, or customer-owned identity lifecycle. Do not pre-implement
+those integrations here.