user-engine/workplans/USER-WP-0021-portal-product-expansion.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on	state_hub_workstream_id
USER-WP-0021	workplan	Expand user-engine portal beyond the proven Binky MVP	communication	user-engine	blocked	codex	netkingdom	2026-07-30	2026-08-10	USER-WP-0020 TEN-WP-0005	ba217f48-5fa5-4178-9c79-73aa225f3f2e

USER-WP-0021 - Portal product expansion

Preserve deliberately deferred product breadth from USER-WP-0020 without holding the proven production MVP open. Activate according to tenant demand.

T01 - Complete invitation and platform recovery APIs

id: USER-WP-0021-T01
status: progress
priority: high
state_hub_task_id: "342299b8-d9a3-408d-bf0d-914496714d5f"

Add invitation claim/resend/expiry, platform tenant management and recovery routes, optimistic concurrency, complete OpenAPI schemas, and durable outbox delivery/replay/dead-letter operations.

2026-08-08 increment: durable invitations now carry expiry and an optimistic version. The API supports tenant create/list, version-gated resend/expire, and authenticated claim with terminal-state and stale-version rejection. Outbox state now covers attempts, bounded failures, delivery, replay, and dead-letter through the store abstraction. OpenAPI 0.2 documents invitation and removal operations. Platform recovery breadth and an outbox operator transport remain.

2026-08-08 follow-up: a provider-neutral TenantManagementPort now supports platform-operator tenant creation with optional first-admin preparation. A redacted recovery route recreates or reconciles provider identity state and reactivates tenant lifecycle, while authenticated operator routes dispatch and replay durable outbox events. Ordinary tenant users are denied these routes. Broader tenant update/retirement operations remain.

T02 - Expand self-service onboarding UX

id: USER-WP-0021-T02
status: done
priority: medium
state_hub_task_id: "dc548cfb-db7c-4cbd-864f-2effeebc3dbd"

Add invitation acceptance, email-verification status, consent/profile, tenant-selection, and fully resumable onboarding screens while keeping password and MFA material on provider-owned surfaces.

2026-08-08 increment: invitation claim is now a first-class authenticated API operation and preserves the provider-owned credential boundary. Dedicated browser screens for the fully resumable journey remain.

2026-08-08 browser increment: authenticated users can review and accept an invitation through a CSRF-protected flow, then land on a responsive onboarding status screen showing provider verification, tenant memberships, and journey state. Acceptance binds the verified OIDC email to the invitation address. Consent/profile editing and tenant switching remain.

2026-08-08 completion increment: self-service profile completion and versioned consent are now durable, audited, and emitted through the outbox; verified email remains immutable. Membership-scoped tenant selection is available for onboarding views, and a PKCE reauthentication handoff carries a tenant hint so the identity provider—not browser state—changes authoritative tenant context. Interactive completion of subsystem-owned journey steps remains.

2026-08-08 completion: users can complete active user-engine-owned onboarding steps through API or CSRF-protected browser controls. Journey ownership is checked before mutation. Password, MFA, and other subsystem-owned steps expose handoff status only and cannot be completed from user-engine; their callbacks resume the durable journey. This completes the self-service onboarding scope.

T03 - Expand administration UX

id: USER-WP-0021-T03
status: done
priority: high
state_hub_task_id: "3e0b41ee-6159-46a4-a9fe-c5b6d714cc2a"

Add platform tenant creation, first-admin bootstrap, invitation/recovery management, account removal, and redacted lifecycle-gap diagnostics.

2026-08-08 increment: account removal now uses the provider-neutral deprovisioning port and disables the tenant lifecycle record. Platform creation/bootstrap and recovery UI remain.

2026-08-08 follow-up: platform APIs now create tenants through the tenant authority, prepare the first administrator, and perform redacted identity recovery. Browser administration screens for these operations remain.

2026-08-08 browser increment: tenant administrators can create, inspect, resend, and expire invitations with versioned CSRF-protected forms, and remove accounts through the provider-neutral deprovisioning boundary.

2026-08-08 platform-browser increment: platform operators have a responsive, CSRF-protected tenant-creation screen with optional first-admin preparation and a direct handoff to tenant administration. Redacted recovery and lifecycle-gap browser diagnostics remain.

2026-08-08 recovery-browser increment: platform operators can inspect redacted lifecycle-gap categories and invoke CSRF-protected identity recovery from the tenant member view. Recovery recreates a missing provider link or reconciles an existing identity, then restores the tenant lifecycle record without showing credentials, factor evidence, or provider error bodies.

2026-08-08 completion: tenant and platform browser surfaces now cover every listed administration operation while retaining tenant boundaries, CSRF, provider-neutral lifecycle ports, and redacted diagnostics.

T04 - Complete broad security and accessibility conformance

id: USER-WP-0021-T04
status: done
priority: high
state_hub_task_id: "fb59245e-6989-4bd9-b72a-68e53ea9f0af"

Automate duplicate/expired/replayed invitation, session expiry, provider outage, partial failure, audit-redaction, keyboard/screen-reader, and mobile/desktop conformance. Preserve existing cross-tenant and escalation denial gates.

2026-08-08 increment: conformance covers invitation conflicts, resend/expiry, outbox provider failure, replay, dead-letter, successful recovery, and provider-neutral account removal. Browser accessibility breadth remains.

2026-08-08 follow-up: conformance now also proves ordinary-user denial of the platform surface and the positive platform tenant/bootstrap, recovery, and outbox delivery workflow.

2026-08-08 browser increment: conformance proves CSRF enforcement, invitation email binding, successful browser claim and onboarding redirect, responsive viewport metadata, focus-visible controls, semantic landmarks, and invitation and removal administration controls.

2026-08-08 self-service/recovery increment: conformance additionally covers durable consent/profile completion, immutable verified email, tenant-hinted OIDC reauthentication, platform recovery controls, and redacted lifecycle-gap presentation.

2026-08-08 completion: the automated matrix covers duplicate, explicitly expired, revoked, and replayed invitations; stale versions; expired sessions; provider outage and unchanged lifecycle state; bounded error/audit surfaces; cross-tenant and platform denial; semantic headings/landmarks; visible keyboard focus; responsive viewport/mobile tables; provider handoff denial; and desktop/browser positive flows. The full suite passes 115 tests with three provider integration tests skipped when their external service is absent.

T05 - Trigger enterprise federation planning only on demand

id: USER-WP-0021-T05
status: wait
priority: low
state_hub_task_id: "05046780-9625-47c2-8caf-f57e9239c603"

When a tenant requires SAML/OIDC federation, SCIM, directory synchronization, just-in-time provisioning, or customer-owned lifecycle, create a dedicated cross-repository plan against the provider-neutral contracts.

Production rollout (2026-08-08)

Commit 8229c6d passed 115 tests with three external-provider skips, was published as forgejo.coulomb.social/coulomb/user-engine@sha256:cef2fdb19fd001a9d2a64742f58dacdcf2ff5868ce50685c91eaad7880645fd0, and rolled out successfully on Railiance. Public health returns schema 0001_initial, KeyCape login returns a PKCE redirect, and /onboarding, /admin/{tenant}, and /platform are recognized protected routes (403 without a session, rather than 404). The rollout replaces in-memory OIDC sessions, so existing browsers must authenticate again.

2026-08-09 production follow-up: tenant-engine and its dedicated flex-auth policy service are deployed with persistent storage and least-privilege networking. The portal adapter created a tenant successfully and the record survived a tenant-engine restart. The separate user-engine flex-auth policy is also deployed and has live self-service-allow/cross-tenant-deny evidence, but the portal runtime switch remains gated on approved event and mail receivers. T01 remains open only for broader tenant update/retirement operations and the final outbox transport activation.

2026-08-10 rollout evidence: the current source image now fails closed when the required flex-auth and delivery settings are absent. A guarded deployment was restored to the last known-good revision without service loss. Final T01 activation remains blocked on approved OpenBao audit/mail receiver tokens and transactional SMTP credentials; no placeholder or reused credential was added.

2026-08-10 authority check: the deployed tenant-engine contract currently supports tenant creation plus role/plan operations, but exposes no tenant metadata-update or retirement operation. Portal update/retirement routes must remain out until that authority owns the corresponding lifecycle contract; user-engine will not simulate authoritative tenant state locally.

TEN-WP-0005 is now registered and ready in tenant-engine for the authoritative metadata update, retirement, and reactivation contract. This task is waiting on that workplan and on the OpenBao-backed event/mail delivery credentials. The non-secret flex-auth runtime URL is live and verified, removing that item from the rollout gate.

2026-08-13 delivery hardening: audit-core and email-connect are now live as separately scoped receivers. HTTPOutboxDeliveryAdapter therefore accepts distinct event and mail bearer tokens; runtime configuration uses USER_ENGINE_EVENT_TOKEN and USER_ENGINE_MAIL_TOKEN, and mail delivery fails closed when its dedicated token is absent. Tests assert that the two Authorization headers differ. The full suite passes 132 tests with three external-provider skips. Production rollout still waits on governed delivery of both scoped credentials.

2026-08-14 live retry finding: the PostgreSQL adapter excluded every row with failed_at set, while the in-memory contract correctly retains failures until dead_lettered_at. A first receiver error therefore required manual replay instead of receiving the documented bounded automatic retry. The query now selects every undelivered, non-dead-letter event; regression coverage checks that failed rows are not filtered out. The full suite passes 133 tests with three external-provider skips.