--- id: NK-WP-0023 type: workplan title: "Integrate and deploy the user-engine onboarding portal" domain: infotech repo: net-kingdom status: finished owner: codex topic_slug: netkingdom created: "2026-07-27" updated: "2026-07-30" depends_on: - USER-WP-0020 - KEY-WP-0004 state_hub_workstream_id: "fdb3deee-06c3-5d12-91ce-9c50b2ac0618" --- # NK-WP-0023 - user-engine portal platform integration Provide the NetKingdom-owned adapters and production integration required by `USER-WP-0020`, using the Binky tenant-admin onboarding from `KEY-WP-0004-T02` as the first acceptance case. ## T01 - Define source-of-truth and provisioning contracts ```task id: NK-WP-0023-T01 status: done priority: high state_hub_task_id: "05d69347-ec34-59b7-a107-80db015ef0e6" ``` Ratify lifecycle sequencing and compensation across user-engine, LLDAP, KeyCape, privacyIDEA, flex-auth, email verification, audit, and outbox delivery. user-engine owns user-domain and membership intent; NetKingdom IAM owns credentials, authentication factors, coarse authentication claims, and provider subjects. Define externally-provisioned/federated ownership metadata now so later enterprise directories do not require a domain rewrite. ## T02 - Implement the NetKingdom identity provisioning adapter ```task id: NK-WP-0023-T02 status: done priority: high state_hub_task_id: "22113719-905b-54df-9ecb-0a0c456e0d35" ``` Implement idempotent create/link/suspend/reactivate/deprovision operations for the lightweight LLDAP + privacyIDEA stack behind user-engine's `IdentityProvisioningPort`. Use scoped service identity and approved secret transport. Never expose directory admin credentials to the browser or user-engine domain. Add reconciliation, retry, compensation, and drift reporting rather than assuming a distributed transaction. 2026-07-28 implementation evidence: `identity-provisioner` now implements the provider-neutral lifecycle API over LLDAP and runs as a non-root, internal-only service in `sso`. Its directory credential remains confined to that pod; user-engine receives only a namespace-local bearer token. NetworkPolicy allows only user-engine to call it and only LLDAP/DNS egress. A live create/replay/delete conformance run returned `resumed: false`, then `resumed: true`, and removed the disposable subject. Reconciliation, compensation, and drift reporting remain. 2026-07-29 completion: image `identity-provisioner:12cdef5` adds read-only drift inspection, active convergence of adapter-owned tenant groups and suspension state, replay-safe deprovisioning, and best-effort compensation when initial group projection fails. User-engine exposes these operations through its provider-neutral port and retries one transient failure only under the mandatory idempotency key. A disposable live probe proved clean initial state, detected induced suspension drift, reported both the unexpected group and status mismatch, removed the drift, returned to `in_sync`, deprovisioned, and accepted the repeated deletion. The probe identity was removed. ## T03 - Integrate KeyCape login, claims, and MFA handoffs ```task id: NK-WP-0023-T03 status: done priority: high state_hub_task_id: "5721c5f9-6161-522c-a439-95f2613b5460" ``` Register the portal OIDC client with authorization code + PKCE, configure callback/logout routes, verify issuer/audience/tenant/assurance claims, and provide safe password and MFA enrollment/recovery handoffs. Preserve platform-root separation and ensure tenant administration never implies platform authority. 2026-07-27 implementation evidence: `user-engine-portal` is registered as a public static KeyCape client with an exact callback and S256 PKCE. The portal is live at `https://users.92-205-62-239.nip.io`, has a trusted ACME certificate, begins the KeyCape/Authelia flow, and rejects an unregistered callback. KeyCape image `key-cape:e8b4ede` maps an unambiguous `tenant:::users|admins` directory group envelope into the tenant and coarse tenant-admin claims while refusing ambiguous multi-tenant mapping. 2026-07-28 update: KeyCape image `key-cape:909bb32` fails closed for directory subjects in `netkingdom-suspended`: authorization-code exchange consumes the code and returns a safety rejection, while `/userinfo` rejects previously issued tokens. Unit and profile suites pass. Live Binky MFA acceptance remains. 2026-07-28 password-handoff evidence: NetKingdom now serves a short-lived, single-use password setup form at the canonical KeyCape host. The portal receives only an opaque HTTPS handoff URL and offers both initial creation and renewal for linked identities; it never handles or stores the password. A live disposable-user run proved prior-link revocation (400), current-link rendering (200), non-consuming validation failure (400 then 200), successful OPAQUE password registration and LLDAP login (200), replay denial (400), and cleanup. The helper image is digest-pinned and the service is non-root, read-only, and NetworkPolicy restricted. Binky's user-chosen password and MFA acceptance remain. 2026-07-29 correction: live platform-root access exposed that the established `net-kingdom-admins` bootstrap group was not mapped into the newer IAM envelope. KeyCape `90a2078` now maps that group explicitly to `tenant:platform` plus `platform-operator`, with regression coverage, while tenant-admin mappings remain tenant scoped. The fixed image is Ready on railiance01. The subsequent live MFA callback exposed a missing destination-side NetworkPolicy: user-engine allowed egress to KeyCape, but the SSO default deny had no matching ingress. Commit `8e7229a` adds the namespace-and-pod-scoped `:8080` rule plus verifier coverage. After applying it, an in-pod discovery request from user-engine to KeyCape returns HTTP 200. 2026-07-29 complete: the live Binky browser flow verified the canonical issuer/audience, Binky-only tenant/groups, tenant-admin role, AAL2 password-plus-OTP assurance, and denial of platform/Coulomb administration. Password and MFA handoffs remain on NetKingdom-owned surfaces. The live journey also exposed uid-only first-factor input. Authelia now uses its documented LLDAP filter accepting either `uid` or `mail` while continuing to resolve the stable uid identity. The updated ConfigMap passed server-side validation and the restarted deployment is Ready without configuration errors, so future users may enter either `bernd.worsch` or the full email. ## T04 - Integrate authorization, email, audit, and events ```task id: NK-WP-0023-T04 status: done priority: high state_hub_task_id: "efad8829-5d75-5ea1-9564-1618b1846525" ``` Define and implement flex-auth resources/actions for self, tenant-admin, and platform-admin operations; route verification/invitation email without making mailbox ownership an authorization fact; correlate user-engine, IAM, authorization, and platform audit records; and connect durable outbox delivery with replay and dead-letter evidence. ## T05 - Deploy on reef-railiance ```task id: NK-WP-0023-T05 status: done priority: high state_hub_task_id: "0c454447-c14f-586b-835b-4f00d43943d0" ``` Package the portal as a managed platform workload on the default `rail-kubernetes` path on `reef-railiance`, with Postgres, OpenBao-backed runtime references, NetworkPolicies, TLS ingress, backups, observability, resource limits, rollout/rollback, and availability evidence. Do not place this stateful platform control surface on scale-to-zero Knative. Implementation evidence (2026-07-27): the internal-only portal foundation is running on `reef-railiance` as `Deployment/user-engine` with dedicated healthy `Cluster/user-engine-pg`, default-deny NetworkPolicies, immutable directly imported image `user-engine:portal-c27012a`, and successful `/readyz` probes. Public ingress remains intentionally absent until T03 supplies the verified KeyCape OIDC edge. Forgejo OCI publication is pending restoration of the OpenBao package-publisher capability; no credential was bypassed or exposed. 2026-07-28 update: public TLS ingress and KeyCape OIDC are active. The current `user-engine:portal-e23674d` deployment is healthy with the dedicated CNPG cluster, and the companion `identity-provisioner:dbf7cfd` deployment is healthy behind namespace-scoped credentials and default-deny policy. Registry publication, backup/restore evidence, metrics, and automated rollback remain. 2026-07-29 operability increment: deployed protected Prometheus metrics in `user-engine:portal-2bcda7f`; an unmarked request is denied with 403 while the trusted workload marker receives readiness plus 18 aggregate record series without identity values. Added a daily atomic `pg_dump` schedule using the existing CNPG application Secret, a restricted backup PVC, checksum/catalog validation, and seven-day retention. The isolated restore drill verified the latest archive in an ephemeral PostgreSQL instance with four public tables and one migration row. `verify-operability.sh --exercise-rollback` rolled back to `portal-746bf21`, verified readiness, and restored the declared image. Machine-readable evidence is in `docs/evidence/user-engine-operability-2026-07-29.json`. The remaining production gaps are registry publication and an independently custodied/off-node backup copy; the current PVC shares reef-railiance's single failure domain, so T05 remains in progress. 2026-07-30 follow-up: both former gaps are implemented. The activity-core ExternalSecret boundary published the portal and provisioner images to `forgejo.coulomb.social` without exposing the package credential. Anonymous digest inspection passed, and both live Deployments now pull immutable public digests. The prior verified portal image is also published by digest; rollback/roll-forward passed without node-local image reliance. The established Option A activity-core lane produced and uploaded `user-engine-pg-user_engine-20260729T220653Z.dump.age` to independent Nextcloud custody. The plaintext dump was removed immediately and only non-secret sizes and the artifact name were recorded. The local isolated restore drill already proves the same logical dump/restore path. 2026-07-30 completion: the approved ops-mason construction plan established the exact OpenBao KV path `platform/workloads/user-engine/runtime`, an exact-path read policy, and separate bounded AppRoles for the `user-engine` and `sso` External Secrets consumers. Namespace-restricted stores and three ExternalSecrets preserve the existing application Secret interfaces. A coordinated rotation rehearsal changed both runtime values at the authoritative path, waited for all three derived Secrets to converge, and returned both Deployments to Ready. Post-rotation checks proved matching provisioner tokens, exact-path `read`, sibling-path `deny`, and a complete disposable provision/drift/reconcile/deprovision lifecycle. No credential value entered recorded output. All T05 acceptance criteria are complete. ## T06 - Prove role-scoped administration and failure safety ```task id: NK-WP-0023-T06 status: done priority: high state_hub_task_id: "f5f0d5d0-09fa-59de-b83f-7a6d4ff736a8" ``` Run end-to-end conformance for registration, login, MFA, tenant creation, first-admin bootstrap, invitations, suspension/reactivation, cross-tenant denial, platform-admin-only actions, provider outages, replay/idempotency, backup restore, and reconciliation after partial failure. 2026-07-28 evidence: deployed-path health, service authentication, directory creation, replay-safe linking, tenant user/admin group creation, and cleanup passed. The test also detected and corrected newline handling for mounted Kubernetes secrets before any identity was created. The broader negative, outage, suspension, restore, and browser/MFA matrix remains. 2026-07-29 increment: provider-path conformance now also covers machine-readable drift detection, automated repair, compensation semantics, transient retry, and replay-safe deletion. The broader browser, authorization, provider-outage, and restore matrix remains open. 2026-07-29 operability evidence adds an isolated database restore and a reversible deployment rollback/roll-forward cycle. Backup and metrics access are secret-free in recorded evidence. Independent disaster-recovery custody and the remaining browser/provider-outage matrix keep T06 open. ## T07 - Complete KEY-WP-0004 through the reusable portal ```task id: NK-WP-0023-T07 status: done priority: high state_hub_task_id: "04664946-c38d-50e8-bc3f-5533801494d8" ``` Use the production portal to onboard `bernd.worsch@binky-hedgehog.com` into `tenant:friendly:binky`, complete OIDC/PKCE + MFA, and verify the Binky-only tenant-admin token and lifecycle controls. Publish only non-secret evidence to `KEY-WP-0004-T02/T07`, then finish that workplan. 2026-07-28: the deployed versioned portal API created the Binky tenant-admin user and membership and provisioned/linked its LLDAP identity. The provider correctly reports `password_setup_required`. During this flow a newline in the mounted trusted-proxy Secret proved HTTP-incompatible; user-engine `0ef2ae5` normalizes runtime transport whitespace, has 105 passing tests, and is live. LLDAP SMTP is not configured, so first-password handoff and MFA/claim acceptance remain rather than falling back to an operator-set password. 2026-07-29 complete: the reusable portal issued the password handoff, the Binky user selected the password and enrolled TOTP, and a fresh login produced Binky-only groups, roles `user` + `tenant-admin`, and AAL2 `pwd` + `otp`. Administration of both `tenant:platform` and `tenant:coulomb` was denied. ## T08 - Document enterprise integration extension points ```task id: NK-WP-0023-T08 status: done priority: medium state_hub_task_id: "83a00e26-aab9-51f1-afb4-cb5d354ab436" ``` Document later adapters for customer IdPs/directories, SAML/OIDC federation, SCIM, JIT provisioning, directory group mapping, customer-owned offboarding, and conflict/freshness rules. Keep `NK-WP-0011` demand-triggered; this task defines compatibility seams, not enterprise implementation. 2026-07-29: added `docs/user-engine-enterprise-identity-extension-points.md`, covering OIDC/SAML federation, SCIM, JIT, group mapping, provenance, source ownership, conflict/freshness rules, offboarding, failure behavior, and demand triggers without starting the demand-gated enterprise implementation. ## Milestone closure (2026-07-30) The live Binky MVP consumes verified KeyCape claims, enforces tenant/platform role separation through user-engine's authorization port, correlates durable audit/outbox records, and keeps password and MFA interactions on NetKingdom-owned surfaces. Role-scoped administration, platform and unrelated tenant denial, AAL2 login, drift/reconciliation, replay-safe deletion, restore, rollback, secret rotation, and dependency failure/recovery are proven. Replacing the pre-production authorization adapter with a deployed flex-auth policy package, invitation mail, operated outbox replay/dead-letter delivery, and the broader integration failure matrix transfer explicitly to `NK-WP-0024`; they are not claimed as part of this completed milestone.