From 1721226427211599881b21697ac66abaa664f3fa Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 3 Jun 2026 10:33:31 +0200 Subject: [PATCH] docs: persist user-engine vs net-kingdom integration assessment (new doc + cross-references in SCOPE, boundary contract, guidance, responsibility map, 0018/0019 workplans). Also updated user-engine integration doc to reference it. --- SCOPE.md | 2 + .../user-engine-boundary-contract_v0.1.md | 1 + docs/responsibility-map.md | 2 + docs/user-engine-interface-guidance.md | 1 + ...ngine-netkingdom-integration-assessment.md | 185 ++++++++++++++++++ ...tstrap-automation-and-rebuild-readiness.md | 2 + ...-adjacent-user-lifecycle-dry-run-polish.md | 2 + 7 files changed, 195 insertions(+) create mode 100644 docs/user-engine-netkingdom-integration-assessment.md diff --git a/SCOPE.md b/SCOPE.md index ea833fa..d8b50f9 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -126,6 +126,8 @@ keywords: [bootstrap, local-identity, oidc, minimal, dev, sandbox] - Entry points: `workplans/NK-WP-0001-sso-mfa-platform.md` and `NK-WP-0002-local-identity.md` for current work - User-domain boundary contract: `canon/standards/user-engine-boundary-contract_v0.1.md` +- User-engine integration assessment (intent/scope fit, gaps, and recommendations): + `docs/user-engine-netkingdom-integration-assessment.md` - Bootstrap/custody entry points: `docs/platform-root-custody.md`, `docs/security-bootstrap-use-cases.md`, diff --git a/canon/standards/user-engine-boundary-contract_v0.1.md b/canon/standards/user-engine-boundary-contract_v0.1.md index 61483d3..50b05fd 100644 --- a/canon/standards/user-engine-boundary-contract_v0.1.md +++ b/canon/standards/user-engine-boundary-contract_v0.1.md @@ -16,6 +16,7 @@ related: - docs/responsibility-map.md - docs/user-engine-interface-guidance.md - docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md + - docs/user-engine-netkingdom-integration-assessment.md (current intent/scope fit, gaps, and recommendations) --- # NetKingdom User Engine Boundary Contract v0.1 diff --git a/docs/responsibility-map.md b/docs/responsibility-map.md index ac3d75d..eb1201c 100644 --- a/docs/responsibility-map.md +++ b/docs/responsibility-map.md @@ -100,6 +100,8 @@ and what NetKingdom is responsible for (meta-orchestration). | **Repo owns** | the headless user-domain service, profile/catalog resolver, projection APIs, local persistence, outbox events, and implementation tests | | **NetKingdom orchestrates** | source-of-truth boundaries with IAM and flex-auth; tenant/platform administration boundaries; application onboarding bindings; membership synchronization rules; projection and claims-enrichment boundaries; audit correlation requirements | +See `docs/user-engine-netkingdom-integration-assessment.md` for current implementation status, gaps, and recommendations on integration. + --- ## Resource Kinds NetKingdom Orchestrates (cross-cutting) diff --git a/docs/user-engine-interface-guidance.md b/docs/user-engine-interface-guidance.md index 5f683b0..492c7f8 100644 --- a/docs/user-engine-interface-guidance.md +++ b/docs/user-engine-interface-guidance.md @@ -11,6 +11,7 @@ Related: - `docs/responsibility-map.md` - `canon/standards/iam-profile_v0.2.md` - `/home/worsch/user-engine/wiki/ArchitectureBlueprint.md` +- `docs/user-engine-netkingdom-integration-assessment.md` (detailed current-state fit, gaps, and recommendations) ## Purpose diff --git a/docs/user-engine-netkingdom-integration-assessment.md b/docs/user-engine-netkingdom-integration-assessment.md new file mode 100644 index 0000000..40a40a0 --- /dev/null +++ b/docs/user-engine-netkingdom-integration-assessment.md @@ -0,0 +1,185 @@ +# User-Engine and NetKingdom Integration Assessment + +**Date:** 2026-06-03 +**Author:** codex (persisted assessment) +**Context:** Assessment performed during net-kingdom session focused on NET-WP-0017/0018/0019 user lifecycle and bootstrap work. +**Related:** +- `canon/standards/user-engine-boundary-contract_v0.1.md` +- `docs/user-engine-interface-guidance.md` +- `docs/responsibility-map.md` +- `docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md` +- `SCOPE.md` (net-kingdom) +- `/home/worsch/user-engine/INTENT.md`, `SCOPE.md`, `wiki/ArchitectureBlueprint.md`, `docs/final-assessment.md`, `docs/interfaces/netkingdom-integration.md` +- NET-WP-0018 (Bootstrap Automation), NET-WP-0019 (T06-adjacent Polish for user lifecycle dry-run) + +--- + +## 1. user-engine Intent and Current Implemented Scope + +**Intent** (from `/home/worsch/user-engine/INTENT.md` — aspirational and stable): + +`user-engine` exists to provide a reusable, headless user-domain service for products and platforms that need account, profile, preference, membership, and application-specific user attribute management without coupling those concerns to a particular identity provider, authorization engine, or user interface. + +It manages: +- users and account state; +- external identity links; +- profile and preference data; +- tenant, application, and team memberships; +- application-registered customization attributes; +- catalog-driven profile schemas; +- profile projections for consuming applications; +- lifecycle and profile-change events. + +**Strategic Role:** Separates user-domain management from authentication, authorization, credential lifecycle, and UI experience concerns. + +**Product Boundaries:** It is the headless backend and domain service. It does **not** aim to be a full identity provider, password/MFA/session system, fine-grained authorization engine, directory server, or UI application. + +**Design Principles:** headless first; optional UI; standalone-friendly; enterprise-integratable; identity-provider agnostic; authorization-engine agnostic; catalog-driven customization; explicit ownership/visibility/mutability/sensitivity of attributes; layered profiles; deterministic effective profile resolution. + +**Success Definition:** A repository or application can add robust user-domain capabilities with minimal coupling while keeping a clear path from simple local setup to governed multi-tenant, multi-application deployment. + +**Scope** (from `/home/worsch/user-engine/SCOPE.md`): + +- **In Scope:** user and account records; account lifecycle state; external identity links; global/tenant/application/membership profile values; preference values; tenant/application/team/scope memberships; application registry for profile consumers; customization catalog registry and validation; effective profile resolution; projection APIs (self-service, admin, application runtime, audit, agent contexts); audit records and lifecycle/profile-change events; local standalone development mode; integration ports for identity claims, authorization checks, events, and runtime secrets. +- **Out Of Scope:** login and authentication flows; password/passkey/session/MFA lifecycle; OIDC/SAML token issuance; final authorization policy decisions; runtime secret custody; UI implementation; full SCIM server or enterprise directory replacement (initial product). +- **Boundary Rule:** user-engine owns user-domain facts and projections. Other systems may provide identity, authorization, deployment, event transport, or UI surfaces, but they must integrate through explicit interfaces rather than becoming hidden sources of profile truth. + +**Current Planning:** Implementation work tracked in `workplans/USER-WP-0001` through `USER-WP-0006`. + +**Currently Implemented** (from workplans USER-WP-0001–0006 *all marked "finished"*, `docs/final-assessment.md`, `src/` structure): + +- Headless service API (`UserEngineService`) for users, accounts, identity links, applications, catalogs, profiles, projections, audit records, and outbox events. +- Domain models (User, Account, TenantAccount, ExternalIdentity, Application + Binding, Catalog + AttributeDefinition, ProfileValue (scoped), Membership with owner/source/freshness, Actor from claims, AuthorizationRequest/Decision, EffectiveProfile, Projection, etc.). +- In-memory adapter (`InMemoryUserEngineStore`) with explicit schema/migration (MVP + multi-tenancy + multi-application catalogs). +- Ports: `IdentityClaimsAdapter` (normalize claims → Actor), `AuthorizationCheckPort`, membership exporter, event outbox, audit writer, secret provider. +- Features: Tenant context enforcement, layered effective profiles, catalog ownership/namespace governance/validation, app-scoped projections, claims-enrichment projection + caching, redaction, audit/outbox correlation. +- Testing: scenario fixtures and conformance tests for positive/negative standalone, tenant, multi-app, redaction, audit, event, cache paths. +- Explicit boundary respect in docs: does not issue tokens, verify MFA, store credentials, act as PDP, own deployment, or provide UI. Consumes verified claims and asks authorization. +- Local-only: in-memory persistence, in-process Python API (no durable DB, no HTTP/RPC yet, no production platform adapters). + +`.custodian-brief.md` (user-engine): Stale (2026-05-22), "no active workstreams — repo may need first-session setup". Domain listed as netkingdom. + +The netkingdom integration guidance doc exists and aligns with the contract. + +## 2. NetKingdom's View and Governance Role + +**Net-kingdom SCOPE** (one-liner + in-scope): + +Platform domain for NetKingdom identity and security services — owns the IAM Profile specification, SSO/MFA platform (Keycloak), and bootstrap local-identity infrastructure for Kubernetes deployments. + +- **In Scope (relevant to user-engine):** NetKingdom IAM Profile specification (versioned OIDC/PKCE contract); SSO/MFA Platform; Local Identity (bootstrap); **User Engine Boundary Contract** (source-of-truth, membership, application-onboarding, projection, authorization, and audit contracts for `user-engine` integration) via `canon/standards/user-engine-boundary-contract_v0.1.md`; Security bootstrapping (credentials, SOPS/age, platform-root custody, OpenBao). +- **Out of Scope:** k8s runtime (railiance-cluster); platform services (railiance-platform); app deployments (railiance-apps); key-cape details (separate repo). + +**The Boundary Contract** (`canon/standards/user-engine-boundary-contract_v0.1.md`, accepted 2026-05-22, created in response to the architecture review): + +- **user-engine owns:** user account records, external identity links, profile and preference values (layered by global/tenant/application/membership scopes), tenant/application/team memberships, application profile catalogs, projections (with version/freshness/redaction metadata), user-domain audit + lifecycle events/outbox. +- **NetKingdom orchestrates (meta-orchestration):** source-of-truth boundaries with IAM and flex-auth; tenant/platform administration boundaries; application onboarding bindings (user-engine app record binds *but does not own* IAM OIDC client + flex-auth protected system + catalog namespace + deployment ref); membership synchronization rules (every cross-boundary fact carries `owner_system`/`source_system` + freshness + `delete_semantics` + `conflict_rule`; "owner wins" default); projection and claims-enrichment boundaries (claims_enrichment is *optional adapter-owned* on IAM side; user-engine must *not* issue tokens); audit correlation (must link request/actor/decision/user_engine_audit/outbox_event). + +Detailed artifacts: source-of-truth matrix, membership envelope/contract, application onboarding checklist, projection types, authz contract (user-engine = PEP; flex-auth = PDP; fail-closed for sensitive writes), audit correlation bundle. + +**Responsibility Map** (`docs/responsibility-map.md`): + +`user-engine` is classified as **orchestrated** by NetKingdom (not just a dependency). + +- **Resources held (by user-engine):** user account records, external identity links, profile and preference values, tenant/application/team memberships, application profile catalogs, projections, user-domain audit and lifecycle events. +- **Repo owns:** the headless user-domain service, profile/catalog resolver, projection APIs, local persistence, outbox events, and implementation tests. +- **NetKingdom orchestrates:** source-of-truth boundaries with IAM and flex-auth; tenant/platform administration boundaries; application onboarding bindings; membership synchronization rules; projection and claims-enrichment boundaries; audit correlation requirements. + +NetKingdom is responsible for coherent cross-landscape management of: Identities (IAM Profile), **User-domain facts** (as managed by user-engine), Roles/scopes/policies, Secrets/credentials, Infrastructure resources. + +**Architecture Review** (2026-05-22): Identified potential overlaps (memberships, app registration, claims enrichment, authz checks, audit correlation, effective profile performance) and recommended the boundary contract, source-of-truth matrix, membership sync contract, and application onboarding contract — all of which now exist and are referenced. + +**Net-kingdom .custodian-brief** (recent, synced 2026-06-03): Shows active workstreams including NET-WP-0018 (Bootstrap Automation And Rebuild Readiness, 1/9 done) and NET-WP-0019 (T06-adjacent Polish: Non-Root User Lifecycle Dry-Run Automation..., 6/6 done). No direct active "user-engine" workstream listed beyond the polish. + +## 3. How It Fits Overall + +**Clean architectural fit:** Layered separation of concerns. + +- Net-kingdom = IAM orchestration + authn/coarse claims (via IAM Profile) + bootstrap + secrets (OpenBao) + contract governance + meta-orchestration of user-domain facts. +- user-engine = reusable headless user-domain backend for *product* facts/profiles/memberships/catalogs/projections (consumes Actor from claims via adapter, delegates authz checks via port, exports read models/projections/events). +- flex-auth = fine-grained PDP. +- This matches "orchestration vs. dependency" (ADR-0010) and self-coherent intents. + +user-engine's current implementation (MVP + multi-tenancy + catalogs, "finished" per its workplans, in-memory local adapter) is the "headless core" that the boundary contract assumes. + +Net-kingdom's bootstrap work (NET-WP-0015/0016/0017/0019, including T06 dry-runs using direct LLDAP/Keycloak for platform-root, break-glass, and test non-root users) is explicitly allowed for bootstrap/local/non-prod scenarios (contract + guidance: production adapters must reject local/loopback issuers; bootstrap identities are IAM-side). + +Projections (esp. claims_enrichment + cache) + ports are designed for loose coupling (IAM-side adapter owns cache/freshness/failure; user-engine never in token critical path). + +Net-kingdom's 0018 (automation/readiness) + 0019 (user lifecycle dry-run polish) are the natural home for *orchestration* of the user lifecycle flow (onboard/lock/offboard/review via the contracts), tests/validations for UI sections/runbooks, and control-surface alignment. 0019 explicitly cross-references the dry-run as proof of the T05 flow. + +**No shared code** (no direct imports of user_engine in net-kingdom Python; integration is claims/contracts/adapters). user-engine tests have claims normalization hooks (mocks for netkingdom-style). + +**Net-kingdom .custodian-brief** (recent) lists 0018 + 0019 polish; user-engine brief is stale (May 22). + +## 4. Conflicts in Intent and Scope? (Gaps and Risks, Not Hard Breaks) + +**No fundamental intent conflicts** — the design (contract + map + blueprints) is deliberately explicit to prevent them. Both repos' INTENT/SCOPE/responsibility statements align on the separation. Old "user-engine" workplans were archived/moved out of net-kingdom (NK-WP-00xx → user-engine's USER-WP-00xx). + +**Real areas that need sorting (mostly "not yet implemented" + potential drift):** + +1. **Missing Platform Integration Adapters (biggest gap):** + Contract/integration doc require concrete adapters in user-engine (or net-kingdom-side): `IdentityClaimsAdapter` (from key-cape/Keycloak claims), `AuthorizationCheckPort` (to flex-auth), `SecretProvider` (OpenBao), `EventOutbox` (to platform sink), `AuditWriter` (to net-kingdom/Railiance), `ApplicationBindingStore`, `MembershipFactExporter`. + Current user-engine: only local/in-memory + mock ports in tests. No durable store, no net-kingdom adapters. + Net-kingdom side: bootstrap/T06 dry-runs + key-cape OIDC config still do direct LLDAP lookups/groups for user facts (see history of keycape LLDAP OU fixes, create-user.sh in sso-mfa/k8s/lldap, net-kingdom-users/admins groups). Claims enrichment is not yet routed through user-engine's `claims_enrichment` projection + cache. + Risk: duplicate truths or accidental coupling if not enforced. + +2. **Bootstrap/Platform Users vs. Governed user-engine Lifecycle:** + Net-kingdom creates platform-root, break-glass, "net-kingdom-*" groups, and T06 test non-root users *directly in LLDAP* (IAM side) during bootstrap (0015–0017/0019 polish). + Per contract: IAM owns auth-time identity + coarse groups/roles (consumed as facts); user-engine owns domain records/memberships (with `owning_system`/`externally_provisioned` etc.). + "net-kingdom-admins/users" in LLDAP are treated as IAM facts today. When does a "real" tenant/platform admin or non-root user become a user-engine `Membership` (with source/owning semantics) vs. staying an IAM group? + The 0017 T06 dry-run "proves" the lifecycle *using the IAM stack*. The 0019 polish automates tooling around *that*. Transition plan to user-engine-backed lifecycle for production onboarding is not explicit yet. + local-identity (net-kingdom bootstrap) vs. user-engine local mode: contract says user-engine local only for non-prod; production must reject. + +3. **Application Onboarding and "Application" Concept:** + Net-kingdom/key-cape does heavy OIDC client + secret creation/registration for apps. + Contract: user-engine owns the *profile consumer* "application" record + bindings (to OIDC client id, flex-auth protected_system_id, catalog namespace, etc.). Separate records, not merged. + Risk of overloaded "application" if not strictly followed in practice (e.g., in 0018 automation or sso-mfa scripts). + +4. **Membership / Group Overlap and "net-kingdom" Tenant:** + LLDAP groups (`net-kingdom-admins/users`) vs. user-engine `Membership` (scope_type=tenant/application/etc., with owner/source). + Contract has detailed sync envelope + conflict rules ("owner wins", freshness, externally_provisioned vs. user_engine_mastered). Not yet exercised end-to-end in platform flows. + For the "platform" tenant itself, where do coarse net-kingdom groups live? + +5. **Governance / Workplan / Brief Split:** + Net-kingdom owns the *contract* (referenced NK-WP-0014) + orchestration (0018 tasks for control surface alignment, runbook tests/validations — now explicitly cross-linked to 0019 dry-run polish in the 0018 file). + user-engine owns impl workplans (finished at MVP scope). + 0019 (the polish for dry-run automation/claims/UI exposure) is tracked under netkingdom domain in brief. This is orchestration, which is correct, but the line "NetKingdom keeps only boundary and orchestration responsibilities" (stated in contract) vs. active net-kingdom workplans doing "user lifecycle" tooling needs to stay crisp. + user-engine brief is very stale and lists Domain=netkingdom (potentially confusing). + +6. **Claims Enrichment Path (current code drift risk):** + Contract: IAM-side adapter owns cache/freshness/failure; never synchronous hard dep on user-engine for privileged logins; user-engine never issues tokens. + Net-kingdom/key-cape currently has direct LLDAP resolution in OIDC paths (for OpenBao admin etc.). The polish work done in 0019/earlier T06 used LLDAP directly. + Once user-engine is deployed with real adapters, this must switch or it violates the "claims_enrichment is adapter-owned" + "user-engine must not be in token critical path" rules. + +7. **Other Minor:** + - Audit/event correlation: contract requires shared IDs across user-engine/flex-auth/platform sinks. Current bootstrap audit is separate (some split to audit-core). + - Tenant "platform:root" special case in user-engine service vs. net-kingdom platform admin. + - No production user-engine deployment yet in net-kingdom flows (still LLDAP/Keycloak direct for users during bootstrap). + +## 5. Summary Recommendation + +**Strong overall fit with no *intent* conflicts** — the separation is well-designed, documented, and consistent across repos (user-engine = domain facts/profiles; net-kingdom = IAM authn/orchestration + boundaries). The May 22 review drove exactly the contracts now in place. Current code-level separation is holding (no shared impl yet). + +**The work is mostly "integration gap" rather than active conflict:** + +- Prioritize **net-kingdom-specific adapters** in user-engine (or symmetric ports) + wiring in key-cape/net-kingdom OIDC/claims paths. This is the blocker to making user-engine the "canonical" for user facts. +- Explicit **bootstrap-to-governed transition rules** for platform/tenant users (e.g., "IAM groups seed externally_provisioned memberships in user-engine; LLDAP remains auth source of truth; net-kingdom-* groups stay IAM-side for platform admin"). +- Use 0018 (automation) + 0019 (dry-run polish) to drive the integration tests, control-surface alignment, and "real" user-engine-backed dry-run (beyond the IAM-stack test done for T06). +- Refresh user-engine .custodian-brief and consider whether 0019 tasks should move or stay as orchestration. +- Perhaps a joint "integration readiness review" decision doc. +- Audit current key-cape/net-kingdom OIDC config for direct LLDAP profile access; route enrichment via the defined claims_enrichment port when user-engine is deployed. +- For platform users (like tenant admins created via net-kingdom flows), decide if they are "externally_provisioned" in user-engine or stay IAM-only. + +This separation enables net-kingdom to focus on secure identity bootstrap/orchestration while user-engine provides the reusable user-domain backend for apps. + +--- + +**Next Steps (Suggested):** +- Add this doc to the boundary contract's "related" section and update the architecture review to reference it as follow-up. +- In NET-WP-0018 T07/T08, explicitly call out adapter implementation + dry-run through user-engine (leveraging 0019). +- Create a small stub for the netkingdom IdentityClaimsAdapter in user-engine. +- Re-run `make fix-consistency REPO=net-kingdom` (and equivalent for user-engine) after edits. +- Consider moving 0019 tasks or creating corresponding USER-WP entries if implementation work lands in user-engine. + +This assessment is persisted as the canonical record of current state and risks. \ No newline at end of file diff --git a/workplans/NET-WP-0018-bootstrap-automation-and-rebuild-readiness.md b/workplans/NET-WP-0018-bootstrap-automation-and-rebuild-readiness.md index 6ae3567..878ddc8 100644 --- a/workplans/NET-WP-0018-bootstrap-automation-and-rebuild-readiness.md +++ b/workplans/NET-WP-0018-bootstrap-automation-and-rebuild-readiness.md @@ -208,6 +208,8 @@ impossible state. **Note (NET-WP-0019 polish):** Include tests for the user-lifecycle dry-run (T06 from 0017/0019): the orchestrator script, onboarding-dry-run console command, claims verification (T05), cleanup helper, and evidence validators. See NET-WP-0019 workplan and sso-mfa/k8s/lldap/dry-run-nonroot-user.sh . This cross-links the T06-adjacent polish into 0018's automation goals. +See also `docs/user-engine-netkingdom-integration-assessment.md` for the broader intent/scope fit, gaps (esp. adapters), and recommendations. + ### T08 - Integrate Validations Into The UI State Model ```task diff --git a/workplans/NET-WP-0019-t06-adjacent-user-lifecycle-dry-run-polish.md b/workplans/NET-WP-0019-t06-adjacent-user-lifecycle-dry-run-polish.md index 6d6f420..822a507 100644 --- a/workplans/NET-WP-0019-t06-adjacent-user-lifecycle-dry-run-polish.md +++ b/workplans/NET-WP-0019-t06-adjacent-user-lifecycle-dry-run-polish.md @@ -13,6 +13,8 @@ depends_on: - NET-WP-0017 - NET-WP-0018 state_hub_workstream_id: "75d388b6-7ec1-4e1b-8c87-6ff44f953210" +related: + - docs/user-engine-netkingdom-integration-assessment.md (broader user-engine vs net-kingdom fit, gaps, and recommendations) --- # NET-WP-0019 - T06-adjacent Polish: Non-Root User Lifecycle Dry-Run Automation And Control Surface Improvements