net-kingdom/workplans/NK-WP-0023-user-engine-portal-platform-integration.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on	state_hub_workstream_id
NK-WP-0023	workplan	Integrate and deploy the user-engine onboarding portal	infotech	net-kingdom	active	codex	netkingdom	2026-07-27	2026-07-28	USER-WP-0020 KEY-WP-0004	c652e4ba-6520-4b30-966f-4fb5659439db

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

id: NK-WP-0023-T01
status: done
priority: high
state_hub_task_id: "8d96aa5e-9801-4d76-9140-d6076a4f2942"

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

id: NK-WP-0023-T02
status: progress
priority: high
state_hub_task_id: "89fe51aa-f351-4763-a358-3eec79f28350"

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.

T03 - Integrate KeyCape login, claims, and MFA handoffs

id: NK-WP-0023-T03
status: progress
priority: high
state_hub_task_id: "76289890-6e6e-45ea-90dc-d3d58eee8b62"

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:<kind>:<slug>: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.

T04 - Integrate authorization, email, audit, and events

id: NK-WP-0023-T04
status: wait
priority: high
state_hub_task_id: "6ce33c92-031a-4f23-8ee2-108451b394fe"

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

id: NK-WP-0023-T05
status: progress
priority: high
state_hub_task_id: "4ef00e05-1259-4c76-a8ef-ec40b5facd1c"

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.

T06 - Prove role-scoped administration and failure safety

id: NK-WP-0023-T06
status: wait
priority: high
state_hub_task_id: "96a7cd2b-6cab-47ab-a899-44bc0f6da58c"

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.

T07 - Complete KEY-WP-0004 through the reusable portal

id: NK-WP-0023-T07
status: done
priority: high
state_hub_task_id: "a574dcec-f7cd-417b-aeaa-5392a7428241"

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

id: NK-WP-0023-T08
status: wait
priority: medium
state_hub_task_id: "7ef8e1f5-1a0e-4a34-9535-708e3146ae72"

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.