From 28da204cf29c0c84e7bebe5d96a3c97c1ea4d75d Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 22 May 2026 19:28:00 +0200 Subject: [PATCH] Add user-engine architecture workplans --- ...59+0200-user-engine-architecture-review.md | 205 ++++++++++++++++++ ...r-engine-preparation-boundary-contracts.md | 153 +++++++++++++ .../NK-WP-0015-user-engine-isolated-mvp.md | 151 +++++++++++++ .../NK-WP-0016-user-engine-multi-tenancy.md | 142 ++++++++++++ ...-user-engine-multi-application-catalogs.md | 143 ++++++++++++ ...8-user-engine-integrated-test-scenarios.md | 140 ++++++++++++ ...WP-0019-user-engine-finalization-polish.md | 142 ++++++++++++ 7 files changed, 1076 insertions(+) create mode 100644 docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md create mode 100644 workplans/NK-WP-0014-user-engine-preparation-boundary-contracts.md create mode 100644 workplans/NK-WP-0015-user-engine-isolated-mvp.md create mode 100644 workplans/NK-WP-0016-user-engine-multi-tenancy.md create mode 100644 workplans/NK-WP-0017-user-engine-multi-application-catalogs.md create mode 100644 workplans/NK-WP-0018-user-engine-integrated-test-scenarios.md create mode 100644 workplans/NK-WP-0019-user-engine-finalization-polish.md diff --git a/docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md b/docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md new file mode 100644 index 0000000..bc9bc1f --- /dev/null +++ b/docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md @@ -0,0 +1,205 @@ +# User Engine Architecture Review + +Timestamp: 2026-05-22T19:19:59+0200 +Reviewer: codex +Subject: `/home/worsch/user-engine/wiki/ArchitectureBlueprint.md` +Context: user-engine integration with NetKingdom IAM Profile, key-cape, +Keycloak, flex-auth, Railiance platform services, and future user-account / +user-manager UI surfaces. + +## Executive Assessment + +The proposed architecture is directionally sound. `user-engine` fills a real +gap: a headless user-domain, profile, preference, membership, catalog, and +projection service that does not try to become an identity provider, MFA +system, authorization engine, runtime secret store, or UI. + +The central improvement area is contract precision at the boundaries. The +architecture has the right separation in prose, but implementation will create +duplicate truths unless we explicitly define how identity claims, user-engine +memberships, flex-auth subject facts, application registrations, OIDC clients, +protected-system registrations, and profile projections relate to each other. + +## Main Findings + +### 1. Membership Ownership Is The Hottest Overlap + +`user-engine` wants to own tenant, application, team, and membership facts. +IAM providers expose groups and roles. flex-auth also models subjects, groups, +teams, and tenants for policy decisions. + +This overlap is healthy only if the source of truth is explicit: + +- IAM owns authentication-time identity facts and coarse claims. +- user-engine owns product-domain memberships and profile facts. +- flex-auth owns policy interpretation and final authorization decisions. +- exported subject facts are read models or policy inputs, not competing + masters. + +Recommended action: create a source-of-truth matrix and a membership +synchronization contract before implementation starts. + +### 2. Application Registration Is Overloaded + +An "application" can mean several things: + +- a user-engine profile consumer; +- an OIDC client in key-cape or Keycloak; +- a flex-auth protected system; +- a catalog namespace owner; +- a deployed workload in Railiance. + +These should not collapse into one record. user-engine should own the profile +consumer record and hold explicit bindings to OIDC clients, flex-auth protected +systems, catalog namespaces, and deployment metadata. + +Recommended action: define an application onboarding contract that maps these +records without merging their ownership. + +### 3. OIDC-Compatible Projections Need A Strong Boundary + +OIDC-compatible profile projections are useful, but user-engine should not +become part of the token issuance critical path by accident. Token issuance +belongs to key-cape or Keycloak. If user-engine profile data is needed in +claims, it should be delivered through an explicit claims-enrichment adapter +with caching, freshness, and failure-mode rules. + +Recommended action: treat claims enrichment as an adapter boundary, not a core +runtime dependency for login. + +### 4. Synchronous Authorization Checks Can Become A Bottleneck + +The flow "user-engine calls flex-auth for every protected action" is clean but +can become expensive for list screens, bulk admin operations, and high-volume +profile reads. + +Recommended mitigations: + +- request-scoped memoization; +- batch authorization checks for list/admin screens; +- short-lived decision caching only where safe; +- explicit fail-closed behavior for sensitive writes; +- local policy fixtures only for standalone development and tests. + +### 5. Effective Profile Resolution Can Become The Hidden Performance Center + +Layered profiles plus catalog defaults plus tenant, application, team, and +admin overrides are powerful, but they are also expensive and easy to +implement as repeated joins or repeated resolver calls. + +Recommended action: design versioned effective-profile materialization or +caching early. Invalidation should be driven by profile, catalog, membership, +and application outbox events. + +### 6. Audit Is Correctly Placed But Needs One Correlation Model + +user-engine audit, flex-auth decision audit, and platform audit sinks all have +valid roles. Without shared correlation IDs, operators will struggle to +reconstruct one administrative action across systems. + +Recommended action: define an audit correlation contract with request ID, +actor identity, user-engine audit ID, flex-auth decision ID, outbox event ID, +tenant, application, and sensitivity-aware redaction rules. + +## Information Flow Assessment + +Good flows: + +- IAM Profile -> user-engine actor envelope: correct abstraction. +- user-engine -> flex-auth authorization check: correct decision boundary. +- user-engine -> outbox -> platform event/audit sinks: correct durability + pattern. +- catalog metadata -> future UIs: correct headless-first UI support. + +Unclear or inefficient flows: + +- user-engine membership facts -> flex-auth subject manifests: source of truth + and freshness need definition. +- user-engine profile projection -> OIDC claims: must not make token issuance + depend synchronously on user-engine. +- admin list/search -> per-row flex-auth checks -> profile resolver: likely + inefficient unless batched and cached. +- catalog activation -> profile migration -> projection invalidation: needs a + versioning and migration flow. + +## Expected Bottlenecks + +| Bottleneck | Why it happens | Mitigation | +| --- | --- | --- | +| flex-auth checks | Per-action synchronous decisions | Batch checks, memoize per request, cache low-risk decisions, keep writes fail-closed | +| Effective profile resolution | Layered scopes and catalog defaults | Materialized effective profiles, version stamps, targeted invalidation | +| Catalog governance | Every app wants custom attributes | Governance tiers, namespace ownership, automated compatibility checks | +| Audit volume | Profile and membership changes can be frequent | Redacted summaries, outbox compaction where allowed, correlation IDs | +| Application onboarding | Crosses IAM, user-engine, flex-auth, Railiance | Application onboarding contract and checklist | +| Claims enrichment | Login path can become dependent on user-engine | Async/cache-backed enrichment and graceful claim omission rules | + +## SWOT Digest + +### Strengths + +- Clear headless product boundary. +- Good separation from identity provider, MFA, secrets, UI, and PDP concerns. +- Strong fit with NetKingdom IAM Profile and flex-auth. +- Catalog-driven profile governance addresses real metadata entropy. +- Supports standalone adoption without abandoning platform integration. + +### Weaknesses + +- Membership, group, role, and subject facts can drift across systems. +- Application registration is currently overloaded. +- Projection freshness and caching rules are not yet defined. +- Standalone mode could grow unsafe auth shortcuts unless constrained. +- Audit correlation is not yet formalized. + +### Opportunities + +- user-engine can become the reusable user-domain/profile layer for many repos. +- Catalog metadata can power `user-account` and `user-manager` without + separate UI-specific backends. +- Subject/membership exports can make flex-auth richer without turning + flex-auth into a profile store. +- A clean app onboarding contract can make multi-application integration + repeatable. +- Agent-context projections can give agentic systems governed user context. + +### Threats + +- Duplicate truth between IAM, user-engine, and flex-auth. +- Login/token flows becoming dependent on user-engine availability. +- Profile data leakage through broad admin or agent projections. +- Catalog approval becoming a central bottleneck. +- Tenant admins accidentally gaining platform-scale authority. + +## Promising Improvements + +1. Add a source-of-truth matrix for identity claims, user records, accounts, + memberships, groups, roles, app registrations, protected systems, catalogs, + profile values, and audit records. +2. Define an application onboarding contract across IAM OIDC client, + user-engine application, flex-auth protected system, catalog namespace, and + deployment metadata. +3. Define a membership synchronization contract with ownership, import, + export, conflict handling, and freshness rules. +4. Split projection definitions into runtime, UI, claims-enrichment, audit, + and agent-context projections. +5. Add an authorization performance model for synchronous checks, batching, + caching, fail-closed writes, and standalone development policy fixtures. +6. Add effective-profile cache/materialization design using catalog/profile + version stamps and outbox-driven invalidation. +7. Define audit correlation across user-engine, flex-auth, and platform audit + sinks. +8. Add catalog governance tiers so low-sensitivity app-owned attributes can + move quickly while sensitive or cross-tenant attributes require review. +9. Make claims enrichment explicitly optional and adapter-owned. +10. Define tenant/admin scope rules before building `user-manager`. + +## Workplan Follow-Up + +The review is translated into the following NetKingdom workplans: + +- `NK-WP-0014` - user-engine preparation and boundary contracts +- `NK-WP-0015` - isolated MVP implementation +- `NK-WP-0016` - multi-tenancy support +- `NK-WP-0017` - multi-application and catalog support +- `NK-WP-0018` - integrated test scenario expansion +- `NK-WP-0019` - implementation assessment, finalization, and polish diff --git a/workplans/NK-WP-0014-user-engine-preparation-boundary-contracts.md b/workplans/NK-WP-0014-user-engine-preparation-boundary-contracts.md new file mode 100644 index 0000000..8074482 --- /dev/null +++ b/workplans/NK-WP-0014-user-engine-preparation-boundary-contracts.md @@ -0,0 +1,153 @@ +--- +id: NK-WP-0014 +type: workplan +title: "User Engine Preparation And Boundary Contracts" +domain: netkingdom +repo: net-kingdom +status: ready +owner: codex +topic_slug: netkingdom +planning_priority: high +planning_order: 14 +created: "2026-05-22" +updated: "2026-05-22" +depends_on: + - NK-WP-0012 + - NK-WP-0013 +state_hub_workstream_id: "b9bf56bc-7ef6-43eb-badc-fa0f4896c63c" +--- + +# NK-WP-0014 - User Engine Preparation And Boundary Contracts + +## Goal + +Prepare implementation of `/home/worsch/user-engine` by turning the current +architecture review into concrete contracts. This workplan must be completed +before production code is started, so the MVP does not duplicate IAM, +authorization, application registration, membership, audit, or deployment +responsibilities already owned by NetKingdom-aligned components. + +## Context + +The user-engine PRD and architecture blueprint define a headless user-domain +service for users, accounts, profiles, preferences, memberships, application +catalogs, projections, audit, and events. + +The architecture review in +`docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md` +identified the main risk: duplicate truth across IAM providers, user-engine, +flex-auth, application registrations, OIDC clients, protected systems, and +profile projections. + +## Scope + +In scope: + +- source-of-truth matrix; +- membership synchronization contract; +- application onboarding contract; +- projection boundary split; +- authorization performance model; +- audit correlation contract; +- user-engine repo preparation artifacts. + +Out of scope: + +- implementing user-engine production code; +- implementing UI repos; +- implementing SCIM or enterprise federation adapters; +- changing the NetKingdom IAM Profile. + +## Tasks + +```task +id: NK-WP-0014-T1 +status: todo +priority: high +state_hub_task_id: "4e941174-ac55-4f6e-8568-40f45b1ed821" +``` + +**Source-of-truth matrix.** Define which system owns each resource kind: +identity claims, human subjects, local user records, account lifecycle, +groups, roles, memberships, tenants, applications, OIDC clients, +flex-auth protected systems, catalog namespaces, profile values, +effective-profile projections, audit records, and events. + +```task +id: NK-WP-0014-T2 +status: todo +priority: high +state_hub_task_id: "5ddc46bb-6238-4944-a023-d8b46b410c76" +``` + +**Membership synchronization contract.** Specify which memberships are mastered +in user-engine, which are imported from IAM or provisioning systems, which are +exported to flex-auth, and how freshness, conflict handling, deletes, and +tenant boundaries are represented. + +```task +id: NK-WP-0014-T3 +status: todo +priority: high +state_hub_task_id: "696bc65b-0f8d-47b5-bccc-65ed285b42e6" +``` + +**Application onboarding contract.** Define the binding between a user-engine +application, IAM OIDC client, flex-auth protected system, catalog namespace, +event/audit identity, and Railiance deployment metadata. Include a checklist +for adding one new application safely. + +```task +id: NK-WP-0014-T4 +status: todo +priority: high +state_hub_task_id: "99ab4535-cbbf-4e13-a2c5-adfc814d5aeb" +``` + +**Projection and claims-enrichment boundaries.** Split projection types into +runtime, self-service UI, admin UI, audit, agent context, and optional claims +enrichment. Explicitly state that user-engine does not issue tokens and that +claims enrichment is adapter-owned and cache/freshness governed. + +```task +id: NK-WP-0014-T5 +status: todo +priority: medium +state_hub_task_id: "d35a1356-a9fe-4cf3-8fb0-6f45cfbbccee" +``` + +**Authorization and audit contracts.** Define the user-engine resource/action +vocabulary for flex-auth, when checks are synchronous, when they may be +batched or cached, and how user-engine audit records correlate with flex-auth +decision IDs and platform audit sinks. + +```task +id: NK-WP-0014-T6 +status: todo +priority: medium +state_hub_task_id: "04fd2f92-3aa4-468d-9e9e-9b092890507e" +``` + +**Prepare the user-engine repo.** Add or update user-engine `SCOPE.md`, +architecture notes, repo layout decision, local development contract, and +initial implementation readiness checklist. Do not add NetKingdom +orchestration relationships to user-engine `INTENT.md`; those belong in +NetKingdom documents per ADR-0010. + +## Acceptance Criteria + +- Boundary contracts exist and are reviewed against the PRD and architecture + review. +- user-engine responsibilities are distinct from key-cape, Keycloak, + flex-auth, OpenBao, Railiance, user-account, and user-manager. +- The first implementation slice can start without unresolved ownership of + memberships, applications, projections, authorization checks, or audit + correlation. +- NetKingdom responsibility-map updates are either applied or explicitly + deferred until user-engine becomes a shared platform service. + +## Dependencies And Sequencing + +- Depends on NK-WP-0012 for IAM Profile consumption rules. +- Depends on NK-WP-0013 for NetKingdom meta-orchestration conventions. +- Gates NK-WP-0015. diff --git a/workplans/NK-WP-0015-user-engine-isolated-mvp.md b/workplans/NK-WP-0015-user-engine-isolated-mvp.md new file mode 100644 index 0000000..31aa013 --- /dev/null +++ b/workplans/NK-WP-0015-user-engine-isolated-mvp.md @@ -0,0 +1,151 @@ +--- +id: NK-WP-0015 +type: workplan +title: "User Engine Isolated MVP" +domain: netkingdom +repo: net-kingdom +status: ready +owner: codex +topic_slug: netkingdom +planning_priority: high +planning_order: 15 +created: "2026-05-22" +updated: "2026-05-22" +depends_on: + - NK-WP-0014 +state_hub_workstream_id: "343e035d-41e1-4fc4-b209-6872e4a5fdc8" +--- + +# NK-WP-0015 - User Engine Isolated MVP + +## Goal + +Implement the smallest useful isolated user-engine in `/home/worsch/user-engine` +with automated tests for all MVP use cases: users, accounts, external identity +links, application registration, customization catalogs, profile values, +effective profile resolution, projections, audit records, and domain events. + +The MVP must run without the full NetKingdom platform while preserving the +same boundaries used by platform mode. + +## Scope + +In scope: + +- repo skeleton and local development workflow; +- domain core independent of HTTP; +- local persistence and migrations; +- headless API for MVP resources; +- local IAM Profile fixture or local-identity integration; +- pluggable flex-auth check interface with a local test adapter; +- audit and transactional outbox; +- automated unit and integration tests. + +Out of scope: + +- multi-tenant production operation beyond one explicit tenant context; +- multi-application governance beyond one or two demo applications; +- SCIM server or enterprise provisioning; +- UI implementation; +- production deployment through Railiance. + +## Tasks + +```task +id: NK-WP-0015-T1 +status: todo +priority: high +state_hub_task_id: "81a88eaa-df2e-4b9f-85f4-a1570c9c9f86" +``` + +**Repo scaffold and implementation stack.** Choose the initial implementation +stack, create the repository layout, define commands for lint/test/run, and +keep the domain core separate from HTTP handlers and infrastructure adapters. + +```task +id: NK-WP-0015-T2 +status: todo +priority: high +state_hub_task_id: "fc4172f7-e7f1-4ad9-98c3-37ccb08c7386" +``` + +**Domain model and persistence.** Implement users, accounts, identity links, +applications, catalogs, attribute definitions, profile values, audit records, +and outbox events with migrations and test fixtures. + +```task +id: NK-WP-0015-T3 +status: todo +priority: high +state_hub_task_id: "8aa5a9e9-3f23-4124-aa3b-01c099ce88bc" +``` + +**Identity and authorization adapters.** Implement an IAM Profile actor +adapter using fixtures or local-identity for isolated mode. Implement a +flex-auth check port with a local deterministic test adapter. Ensure +production code paths can later swap to real flex-auth without changing +domain logic. + +```task +id: NK-WP-0015-T4 +status: todo +priority: high +state_hub_task_id: "cedd6319-e4c2-460c-888c-d0d95d7bdbef" +``` + +**Headless MVP API.** Add API endpoints for health/readiness, `me`, users, +account lifecycle transitions, identity links, application registration, +catalog registration/activation, profile updates, effective profile +resolution, projections, and audit inspection. + +```task +id: NK-WP-0015-T5 +status: todo +priority: high +state_hub_task_id: "62ecafaa-237a-4cae-ac78-1ed79ca881a1" +``` + +**Catalog and profile resolver.** Implement JSON/YAML catalog registration, +attribute validation, default values, global plus application profile layers, +basic precedence rules, and inspectable effective profile resolution. + +```task +id: NK-WP-0015-T6 +status: todo +priority: high +state_hub_task_id: "d627db12-2019-4870-a255-354fc77a1d22" +``` + +**Projection, audit, and event outbox.** Implement self-service, admin, +application runtime, audit, and agent-context projection skeletons with +sensitivity-aware redaction. Persist audit records and outbox events in the +same transaction as mutations. + +```task +id: NK-WP-0015-T7 +status: todo +priority: high +state_hub_task_id: "803e979d-a83a-43d8-a93d-ce97c83015ec" +``` + +**MVP test suite.** Cover user/account lifecycle, identity linking, catalog +validation failures, profile update authorization, effective profile +resolution, projection redaction, audit/outbox atomicity, local issuer +handling, and deny paths from the authorization adapter. + +## Acceptance Criteria + +- The user-engine repo can be checked out and tested in isolation. +- A demo application can register, register a catalog, update profile values, + and request an effective profile projection. +- A current user can read/update allowed self-service profile fields. +- An admin-like actor can perform allowed scoped user operations through the + test authorization adapter. +- Sensitive attributes are redacted from non-eligible projections. +- Mutations produce audit and outbox records atomically. +- Tests cover positive and negative MVP use cases. + +## Dependencies And Sequencing + +- Gated by NK-WP-0014 boundary contracts. +- Enables NK-WP-0016 and NK-WP-0017. diff --git a/workplans/NK-WP-0016-user-engine-multi-tenancy.md b/workplans/NK-WP-0016-user-engine-multi-tenancy.md new file mode 100644 index 0000000..05e3ca9 --- /dev/null +++ b/workplans/NK-WP-0016-user-engine-multi-tenancy.md @@ -0,0 +1,142 @@ +--- +id: NK-WP-0016 +type: workplan +title: "User Engine Multi-Tenancy" +domain: netkingdom +repo: net-kingdom +status: ready +owner: codex +topic_slug: netkingdom +planning_priority: high +planning_order: 16 +created: "2026-05-22" +updated: "2026-05-22" +depends_on: + - NK-WP-0015 +state_hub_workstream_id: "2d592e18-e63d-4856-97a1-f8c3e019e150" +--- + +# NK-WP-0016 - User Engine Multi-Tenancy + +## Goal + +Extend the isolated MVP into a tenant-aware service that follows the +NetKingdom recursive platform model: `tenant:platform` is distinct from +tenant planes such as `tenant:coulomb`, and tenant administration must not +grant platform-root authority. + +## Scope + +In scope: + +- tenant model and context propagation; +- tenant-scoped profiles and memberships; +- tenant admin scopes; +- tenant-aware authorization checks; +- tenant isolation in persistence and APIs; +- tenant-aware audit/events; +- tenant onboarding diagnostics and tests. + +Out of scope: + +- multi-application catalog governance beyond what NK-WP-0017 owns; +- enterprise SCIM provisioning; +- UI implementation; +- changing the NetKingdom tenant claim standard. + +## Tasks + +```task +id: NK-WP-0016-T1 +status: todo +priority: high +state_hub_task_id: "d4bb49a9-dffe-4317-aea2-761d737c5627" +``` + +**Tenant model and context.** Implement tenant identifiers aligned with +NetKingdom conventions, request tenant context resolution, tenant validation, +and explicit platform-vs-tenant plane handling. + +```task +id: NK-WP-0016-T2 +status: todo +priority: high +state_hub_task_id: "4a9083c0-f0bd-4dad-b221-c4563ed53209" +``` + +**Tenant-scoped data model.** Add tenant-scoped account state, tenant profile +values, tenant memberships, and database constraints that prevent accidental +cross-tenant joins or updates. + +```task +id: NK-WP-0016-T3 +status: todo +priority: high +state_hub_task_id: "4fd57616-53dc-4c10-bf95-553319186005" +``` + +**Tenant administration boundary.** Implement scope-admin operations for +tenant users and memberships while denying platform-root operations to tenant +admins. Model break-glass and platform operator paths as separate policy +cases. + +```task +id: NK-WP-0016-T4 +status: todo +priority: high +state_hub_task_id: "dc0fc00a-5228-4b99-9fa1-6a7f6b557aac" +``` + +**flex-auth tenant integration.** Extend authorization requests with tenant, +resource, action, target user, membership, assurance, and scope facts. Add +resource/action manifests or fixtures for tenant user management operations. + +```task +id: NK-WP-0016-T5 +status: todo +priority: medium +state_hub_task_id: "17460786-7af0-4e67-8169-80c2c29934e6" +``` + +**Tenant-aware events and audit.** Ensure audit records and outbox events +carry tenant context, correlation IDs, actor tenant, target tenant, and +redacted change summaries. + +```task +id: NK-WP-0016-T6 +status: todo +priority: high +state_hub_task_id: "a899832f-63e6-4417-bc1d-ca3c5ea89061" +``` + +**Tenant test scenarios.** Add tests for cross-tenant denial, tenant admin +allowed actions, tenant admin platform-root denial, tenant profile precedence, +tenant membership changes, local issuer rejection in production mode, and +audit correlation. + +```task +id: NK-WP-0016-T7 +status: todo +priority: medium +state_hub_task_id: "187cdc5d-7cba-432e-8201-34bb437ba8e8" +``` + +**Tenant onboarding diagnostics.** Add a diagnostic command or endpoint that +reports whether a tenant has required applications, memberships, policy +bindings, catalog scopes, and audit readiness. + +## Acceptance Criteria + +- Tenant context is explicit on every tenant-scoped operation. +- Tenant data is isolated by schema constraints and authorization checks. +- Tenant admins cannot modify platform-root resources or global policy + boundaries. +- Profile resolution includes global and tenant layers deterministically. +- Tenant audit and event records are correlated and redacted. +- Tenant tests include both allowed and denied paths. + +## Dependencies And Sequencing + +- Depends on the isolated MVP in NK-WP-0015. +- Can run partly in parallel with NK-WP-0017 after shared app and catalog + interfaces are stable. diff --git a/workplans/NK-WP-0017-user-engine-multi-application-catalogs.md b/workplans/NK-WP-0017-user-engine-multi-application-catalogs.md new file mode 100644 index 0000000..534b54a --- /dev/null +++ b/workplans/NK-WP-0017-user-engine-multi-application-catalogs.md @@ -0,0 +1,143 @@ +--- +id: NK-WP-0017 +type: workplan +title: "User Engine Multi-Application And Catalog Support" +domain: netkingdom +repo: net-kingdom +status: ready +owner: codex +topic_slug: netkingdom +planning_priority: high +planning_order: 17 +created: "2026-05-22" +updated: "2026-05-22" +depends_on: + - NK-WP-0015 +state_hub_workstream_id: "08398d26-cadf-44bc-97ee-67da790040e6" +--- + +# NK-WP-0017 - User Engine Multi-Application And Catalog Support + +## Goal + +Extend user-engine from a single-app MVP into a governed multi-application +profile and customization service. Applications should be able to register as +profile consumers, own catalog namespaces, publish versioned customization +catalogs, and receive application-specific projections without attribute +collisions or data leakage. + +## Scope + +In scope: + +- application registry and bindings; +- catalog namespace ownership; +- catalog lifecycle and migration checks; +- application-specific profile layers; +- application runtime projections; +- optional claims-enrichment boundary; +- multi-app tests and examples. + +Out of scope: + +- UI implementation; +- full marketplace or plugin ecosystem; +- enterprise SCIM server; +- making user-engine a token issuer. + +## Tasks + +```task +id: NK-WP-0017-T1 +status: todo +priority: high +state_hub_task_id: "9363492d-49af-4929-bb64-576ed8c47ddb" +``` + +**Application registry split.** Implement user-engine application records as +profile-consumer records with explicit bindings to IAM OIDC clients, +flex-auth protected systems, catalog namespaces, event identities, and +deployment metadata. + +```task +id: NK-WP-0017-T2 +status: todo +priority: high +state_hub_task_id: "cd9dff26-d570-4f9f-9ebf-6f20eddf3ef0" +``` + +**Catalog namespace governance.** Implement namespace ownership, catalog +semantic versions, lifecycle states, compatibility checks, sensitivity +downgrade prevention, and activation/deprecation flows. + +```task +id: NK-WP-0017-T3 +status: todo +priority: high +state_hub_task_id: "6bbe4250-a6e7-4ecf-b916-7e79eddd76f6" +``` + +**Application profile layer.** Add application-specific profile values, +preferences, defaults, and effective-profile precedence rules that compose +with global and tenant layers. + +```task +id: NK-WP-0017-T4 +status: todo +priority: high +state_hub_task_id: "29012ed5-f6c2-455f-8999-037a653d14e1" +``` + +**Application runtime projections.** Implement app-specific projection +requests with allowed projection types, attribute-level visibility, +mutability, sensitivity, and redaction rules. + +```task +id: NK-WP-0017-T5 +status: todo +priority: medium +state_hub_task_id: "a3226c20-1278-409e-a49d-965e4783dc7a" +``` + +**Claims-enrichment adapter boundary.** Specify and, if appropriate, prototype +an optional cache-backed projection used by IAM-side claims enrichment. The +implementation must not place user-engine synchronously in the default token +issuance path. + +```task +id: NK-WP-0017-T6 +status: todo +priority: high +state_hub_task_id: "ada5a9f5-19f6-4e9e-a176-b1b47ec36ca7" +``` + +**Multi-app tests.** Add tests for namespace collisions, catalog activation +failure, application-specific profile values, projection redaction, +application access denial, catalog migration checks, and onboarding two demo +applications side by side. + +```task +id: NK-WP-0017-T7 +status: todo +priority: medium +state_hub_task_id: "09f38d5c-af6c-4d95-a570-e5a5c25d7cfe" +``` + +**Developer-facing integration examples.** Provide examples or fixtures that +show how a new application registers, owns a catalog namespace, requests +runtime projections, and handles profile-change events. + +## Acceptance Criteria + +- Multiple applications can register without attribute collisions. +- Catalog ownership and lifecycle are enforced. +- Application-specific profile values resolve consistently with global and + tenant layers. +- Runtime projections expose only eligible attributes. +- Claims enrichment is explicitly optional and adapter-owned. +- Tests cover multi-app positive, negative, and migration paths. + +## Dependencies And Sequencing + +- Depends on NK-WP-0015. +- Coordinates with NK-WP-0016 where application behavior is tenant-scoped. diff --git a/workplans/NK-WP-0018-user-engine-integrated-test-scenarios.md b/workplans/NK-WP-0018-user-engine-integrated-test-scenarios.md new file mode 100644 index 0000000..9c2d438 --- /dev/null +++ b/workplans/NK-WP-0018-user-engine-integrated-test-scenarios.md @@ -0,0 +1,140 @@ +--- +id: NK-WP-0018 +type: workplan +title: "User Engine Integrated Test Scenarios" +domain: netkingdom +repo: net-kingdom +status: ready +owner: codex +topic_slug: netkingdom +planning_priority: high +planning_order: 18 +created: "2026-05-22" +updated: "2026-05-22" +depends_on: + - NK-WP-0016 + - NK-WP-0017 +state_hub_workstream_id: "6f75035a-e056-4eab-8fdb-00a18bacdf87" +--- + +# NK-WP-0018 - User Engine Integrated Test Scenarios + +## Goal + +Extend user-engine test coverage from isolated MVP tests to realistic +standalone, platform, multi-tenant, multi-application, audit, and performance +scenarios. The test suite should prove the architecture boundaries rather than +only individual functions. + +## Scope + +In scope: + +- scenario matrix; +- local identity and IAM Profile fixtures; +- flex-auth authorization harness; +- multi-tenant and multi-application integration tests; +- audit/outbox/correlation tests; +- effective-profile performance tests; +- CI/readiness gates. + +Out of scope: + +- full production Railiance deployment; +- full enterprise SCIM conformance; +- UI end-to-end tests for future UI repos. + +## Tasks + +```task +id: NK-WP-0018-T1 +status: todo +priority: high +state_hub_task_id: "6da86ef6-ea8b-49b9-8897-cbed00f6e61d" +``` + +**Scenario matrix.** Define canonical scenarios: standalone single-app, +standalone denied access, platform local-identity fixture, tenant admin, +platform operator, cross-tenant denial, two applications with separate +catalogs, sensitive projection redaction, and event/audit replay. + +```task +id: NK-WP-0018-T2 +status: todo +priority: high +state_hub_task_id: "e3424148-90d6-4c43-8f15-988f2a21d166" +``` + +**Identity fixtures.** Add IAM Profile claim fixtures for human, service, +agent, delegated agent, tenant admin, platform operator, break-glass, local +development issuer, and invalid/expired/missing-tenant tokens. + +```task +id: NK-WP-0018-T3 +status: todo +priority: high +state_hub_task_id: "23fa4617-e7ce-4cdc-b753-489ec361757b" +``` + +**Authorization harness.** Add a deterministic flex-auth-compatible test +harness that supports allow, deny, obligation, tenant-boundary, assurance, and +bulk decision scenarios. + +```task +id: NK-WP-0018-T4 +status: todo +priority: high +state_hub_task_id: "33c53479-7856-42ee-b9ee-8795aa73c39a" +``` + +**End-to-end domain scenarios.** Test full flows from actor claims through +authorization, mutation, profile resolution, projection, audit write, and +outbox event creation. + +```task +id: NK-WP-0018-T5 +status: todo +priority: medium +state_hub_task_id: "fc2d73e4-1f45-4891-9c31-1a4dc2f3a002" +``` + +**Performance and cache tests.** Add tests or benchmarks for effective-profile +resolution, projection rendering, authorization batching, request-scoped +memoization, and cache invalidation on catalog/profile/membership changes. + +```task +id: NK-WP-0018-T6 +status: todo +priority: high +state_hub_task_id: "26b63aa0-deb6-4b4d-9388-6b7e531bd4ff" +``` + +**Security and privacy negative tests.** Cover local issuer rejection in +production, sensitive attribute leakage, cross-tenant reads/writes, admin +overreach, catalog sensitivity downgrade, namespace hijack, stale membership +facts, and missing audit correlation. + +```task +id: NK-WP-0018-T7 +status: todo +priority: medium +state_hub_task_id: "a46e6e78-71a1-4518-881f-85b39269f4a8" +``` + +**CI and readiness gates.** Add repeatable commands for unit, integration, +scenario, and conformance-style tests. Document what must pass before a +platform deployment or UI consumer can depend on user-engine. + +## Acceptance Criteria + +- The test suite proves standalone, tenant, multi-app, authorization, profile, + projection, audit, and event behavior. +- Negative tests cover the architecture review risks. +- Scenario fixtures are readable enough for future agents and developers to + extend. +- CI/readiness commands are documented and deterministic. + +## Dependencies And Sequencing + +- Depends on NK-WP-0016 and NK-WP-0017. +- Feeds the final implementation assessment in NK-WP-0019. diff --git a/workplans/NK-WP-0019-user-engine-finalization-polish.md b/workplans/NK-WP-0019-user-engine-finalization-polish.md new file mode 100644 index 0000000..7b684f3 --- /dev/null +++ b/workplans/NK-WP-0019-user-engine-finalization-polish.md @@ -0,0 +1,142 @@ +--- +id: NK-WP-0019 +type: workplan +title: "User Engine Implementation Assessment And Polish" +domain: netkingdom +repo: net-kingdom +status: ready +owner: codex +topic_slug: netkingdom +planning_priority: medium +planning_order: 19 +created: "2026-05-22" +updated: "2026-05-22" +depends_on: + - NK-WP-0018 +state_hub_workstream_id: "d2daa8b4-8ecf-4377-b382-492e653735f7" +--- + +# NK-WP-0019 - User Engine Implementation Assessment And Polish + +## Goal + +Assess the implemented user-engine against its PRD, architecture blueprint, +NetKingdom boundary contracts, and integrated test scenarios. Finalize +documentation, operational readiness, release packaging, and handoff criteria +for future `user-account` and `user-manager` UI work. + +## Scope + +In scope: + +- implementation review against PRD and blueprint; +- boundary review against NetKingdom IAM Profile, flex-auth, key-cape, + Keycloak, OpenBao, and Railiance responsibilities; +- API/schema polish; +- operability and documentation polish; +- release readiness; +- State Hub and responsibility-map reconciliation; +- UI handoff readiness. + +Out of scope: + +- building user-account or user-manager UIs; +- adding new major product capabilities; +- enterprise provisioning beyond documented adapter boundaries. + +## Tasks + +```task +id: NK-WP-0019-T1 +status: todo +priority: high +state_hub_task_id: "116b5362-ebbf-4d21-83e8-bbc82e80a71a" +``` + +**Implementation assessment.** Review implemented behavior against +`INTENT.md`, the PRD, the architecture blueprint, the architecture review, +and NK-WP-0014 boundary contracts. Record gaps, accepted deviations, and +follow-up work. + +```task +id: NK-WP-0019-T2 +status: todo +priority: high +state_hub_task_id: "08bd8ca3-dd7e-41c9-b8d2-c9b7c72ceb0a" +``` + +**Boundary and responsibility review.** Verify that user-engine has not +absorbed identity provider, MFA, credential, PDP, UI, or deployment +responsibilities. Update NetKingdom responsibility-map classification if +user-engine is now a shared platform service holding NetKingdom-orchestrated +resources. + +```task +id: NK-WP-0019-T3 +status: todo +priority: medium +state_hub_task_id: "b8ff89a1-cdfb-445a-ae4d-ca4fd4a455eb" +``` + +**API and schema polish.** Stabilize endpoint names, error taxonomy, catalog +descriptor schemas, projection responses, audit event shapes, and migration +contracts. Remove accidental implementation details from public contracts. + +```task +id: NK-WP-0019-T4 +status: todo +priority: medium +state_hub_task_id: "f57d87d7-fdc8-485c-ba93-86c5a8342f04" +``` + +**Operability polish.** Add readiness diagnostics, metrics, structured logs, +audit correlation checks, outbox drain diagnostics, cache status, and +runbooks for common failure modes. + +```task +id: NK-WP-0019-T5 +status: todo +priority: medium +state_hub_task_id: "42a01f4e-c646-4551-bd94-e122c9c16226" +``` + +**Documentation and examples.** Finalize developer docs for standalone setup, +application onboarding, catalog authoring, projection consumption, tenant +administration boundaries, and event/audit integration. + +```task +id: NK-WP-0019-T6 +status: todo +priority: medium +state_hub_task_id: "7838d62b-94eb-437a-8418-7a900cde9716" +``` + +**Release readiness.** Decide versioning, packaging, image/build artifacts, +SBOM/security scan requirements, migration policy, and compatibility +guarantees for future consumers. + +```task +id: NK-WP-0019-T7 +status: todo +priority: low +state_hub_task_id: "19569b30-c8df-441a-b815-c9217a82abaf" +``` + +**UI handoff readiness.** Produce the API, projection, catalog metadata, and +test fixtures needed for future user-account and user-manager repos to start +without inventing separate backends. + +## Acceptance Criteria + +- A final assessment document records what was implemented, what changed, and + what remains open. +- Public API/schema/catalog/projection contracts are coherent and documented. +- Operability and release-readiness checks pass. +- NetKingdom State Hub and responsibility-map records are reconciled. +- Future UI work has a clear backend contract. + +## Dependencies And Sequencing + +- Depends on NK-WP-0018 integrated scenario tests. +- Closes the initial user-engine implementation program and feeds future UI + workplans.