diff --git a/workplans/USER-WP-0020-self-service-and-user-administration-portal.md b/workplans/USER-WP-0020-self-service-and-user-administration-portal.md new file mode 100644 index 0000000..0e5c1e2 --- /dev/null +++ b/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.