coulomb/net-kingdom
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Split user-engine implementation planning

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-22 19:50:12 +02:00
parent 6892dfd758
commit c8e2b142db
9 changed files with 254 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/responsibility-map.md
View File

@@ -92,6 +92,14 @@ and what NetKingdom is responsible for (meta-orchestration).
| **Repo owns** | the authorization registry, control plane, and PDP adapters |
| **NetKingdom orchestrates** | the decision-envelope contract fed by IAM Profile v0.2 claims; platform vs tenant policy boundaries; which protected systems/resources are registered; policy-package import and governance; audit retention; authorization-trust readiness |
### `user-engine` — user-domain/profile service
| | |
| --- | --- |
| **Resources held** | 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 |
---
## Resource Kinds NetKingdom Orchestrates (cross-cutting)
@@ -101,6 +109,9 @@ cross-landscape management of:
- **Identities** — humans, service accounts, agents, groups, tenants,
and assurance evidence as normalized by the IAM Profile
- **User-domain facts** — account state, identity links, profile data,
preferences, memberships, and application catalog ownership as managed by
user-engine
- **Roles, scopes, and policies** — coarse claims through fine-grained
authorization
- **Secrets and credentials** — bootstrap material and runtime secret

19
docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md
View File

@@ -197,9 +197,16 @@ Unclear or inefficient flows:
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
- `NK-WP-0014` - NetKingdom-owned user-engine preparation and boundary
contracts.
The implementation-shaped workplans that were first drafted as
`NK-WP-0015` through `NK-WP-0019` were archived on 2026-05-22 and split into
the `user-engine` repository as:
- `USER-WP-0001` - repo preparation and interface adoption
- `USER-WP-0002` - isolated MVP implementation
- `USER-WP-0003` - multi-tenancy support
- `USER-WP-0004` - multi-application and catalog support
- `USER-WP-0005` - integrated test scenario expansion
- `USER-WP-0006` - implementation assessment, finalization, and polish

148
docs/user-engine-interface-guidance.md Normal file
View File

@@ -0,0 +1,148 @@
# User Engine Interface Guidance
Status: initial interface guidance
Date: 2026-05-22
Owner: NetKingdom
Related:
- `docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md`
- `docs/responsibility-map.md`
- `canon/standards/iam-profile_v0.2.md`
- `/home/worsch/user-engine/wiki/ArchitectureBlueprint.md`
## Purpose
This document defines the cross-repo interface guidance for integrating
`user-engine` into the NetKingdom landscape without duplicating identity,
authorization, deployment, or UI responsibilities.
`user-engine` owns user-domain facts and profile projections. NetKingdom owns
the security and orchestration contracts that decide how those facts relate to
identity, authorization, tenant boundaries, application onboarding, and audit.
## Source Of Truth Matrix
| Resource kind | Source of truth | user-engine relation |
| --- | --- | --- |
| OIDC issuer, login, token lifecycle | key-cape or Keycloak implementation of the IAM Profile | Consumes verified tokens and claim envelopes |
| Local/bootstrap development identity | local-identity | Consumes only in non-production/test contexts |
| Stable identity link | user-engine | Maps `(issuer, subject)` to `user_id` |
| User account record and lifecycle | user-engine | Canonical owner |
| Profile and preference values | user-engine | Canonical owner |
| Application-specific profile catalog | user-engine | Canonical owner, with namespace governance |
| Product-domain memberships | user-engine unless imported by contract | Canonical owner for local membership facts |
| Authentication groups and coarse roles | IAM provider, normalized into IAM Profile claims | Consumed as actor facts, not treated as final authorization |
| Protected systems, resources, actions, policies | flex-auth | user-engine registers/checks against flex-auth contracts |
| Runtime secrets and DB credentials | OpenBao/Railiance platform services | user-engine consumes scoped runtime secrets only |
| Deployment mechanics | Railiance stack | user-engine publishes deployment requirements; Railiance executes |
| Self-service and admin UI experiences | future UI repos/apps | user-engine provides APIs and projections |
| Platform-wide audit retention | NetKingdom/Railiance audit sink | user-engine emits correlated local audit and events |
## Application Onboarding Contract
A platform application must not be represented by one overloaded object. The
onboarding contract binds separate records owned by separate systems:
| Binding | Owner | Required fields |
| --- | --- | --- |
| IAM OIDC client | key-cape or Keycloak | client id, redirect URIs, scopes, allowed issuer |
| user-engine application | user-engine | application id, display name, owner, allowed profile scopes, projection types |
| flex-auth protected system | flex-auth | protected-system id, resource/action vocabulary, policy package binding |
| Catalog namespace | user-engine | namespace, owning application id, versioning policy |
| Deployment metadata | Railiance/application repo | environment, service name, tenant placement, health/readiness endpoints |
| Audit/event identity | user-engine plus platform sink | source application id, correlation id policy, event subject prefix |
Application onboarding is ready when all bindings exist, the app can request a
runtime projection through user-engine, flex-auth can decide its protected
actions, and audit/event correlation works for at least one profile read and
one profile mutation.
## Membership Synchronization Contract
Membership facts are allowed to cross systems only with explicit ownership.
| Flow | Rule |
| --- | --- |
| IAM groups/roles -> user-engine | Import only as identity facts or mapped seed data. Do not silently overwrite user-engine-owned memberships. |
| user-engine memberships -> flex-auth | Export as subject facts/read models for policy input. flex-auth decides, but does not become the membership store. |
| external provisioning -> user-engine | Mark imported records as externally provisioned and preserve source, version, and deletion semantics. |
| user-engine -> IAM | Optional and adapter-owned; used only when IAM needs coarse groups/claims. |
Every membership fact needs:
- source system;
- owning system;
- tenant/scope;
- subject user;
- membership kind;
- freshness/version;
- delete/disable semantics;
- conflict rule.
## Projection Boundaries
Projection types must stay distinct:
- `self_service`: what the current user may inspect or edit.
- `admin`: what a scope admin may inspect or mutate.
- `application_runtime`: what a registered app may consume at runtime.
- `audit`: redacted summaries for traceability.
- `agent_context`: policy-filtered context for delegated or autonomous agents.
- `claims_enrichment`: optional IAM-side enrichment input.
`user-engine` must not issue tokens. If profile data appears in OIDC claims,
the IAM implementation owns the claims-enrichment adapter and its cache,
freshness, and failure-mode rules.
## Authorization Interface
user-engine is a policy enforcement point, not the policy decision point.
Minimum authorization request fields:
- actor envelope from the IAM Profile;
- tenant and scope;
- target user or resource;
- user-engine resource type;
- action;
- assurance evidence;
- application id where applicable;
- correlation id.
Expected resource families:
- `user-engine:user`
- `user-engine:identity-link`
- `user-engine:profile`
- `user-engine:membership`
- `user-engine:application`
- `user-engine:catalog`
- `user-engine:projection`
- `user-engine:audit`
Sensitive writes should fail closed if flex-auth is unavailable. Read-heavy and
list-heavy flows may use request-scoped memoization, batch checks, or short
safe caches where the policy package explicitly allows it.
## Audit Correlation
Each user-engine mutation should produce:
- local user-engine audit record;
- flex-auth decision id or equivalent check correlation;
- outbox event id;
- request id;
- actor identity;
- tenant/application/scope;
- redacted change summary.
Platform audit sinks should receive redacted, correlated summaries rather than
large sensitive profile payloads.
## NetKingdom Workplan Split
NetKingdom owns boundary contracts and interface governance. user-engine owns
the implementation workplans for the service itself.
- NetKingdom: `NK-WP-0014`
- user-engine: `USER-WP-0001` through `USER-WP-0006`

13
workplans/NK-WP-0014-user-engine-preparation-boundary-contracts.md
View File

@@ -39,6 +39,10 @@ identified the main risk: duplicate truth across IAM providers, user-engine,
flex-auth, application registrations, OIDC clients, protected systems, and
profile projections.
NetKingdom keeps this workplan because it owns cross-repo boundary and
orchestration guidance. Implementation work now lives in the `user-engine`
repository as `USER-WP-0001` through `USER-WP-0006`.
## Scope
In scope:
@@ -50,10 +54,12 @@ In scope:
- authorization performance model;
- audit correlation contract;
- user-engine repo preparation artifacts.
- NetKingdom/user-engine interface guidance.
Out of scope:
- implementing user-engine production code;
- implementing user-engine production code, which belongs in the user-engine
repository workplans;
- implementing UI repos;
- implementing SCIM or enterprise federation adapters;
- changing the NetKingdom IAM Profile.
@@ -73,6 +79,9 @@ groups, roles, memberships, tenants, applications, OIDC clients,
flex-auth protected systems, catalog namespaces, profile values,
effective-profile projections, audit records, and events.
Initial guidance lives in `docs/user-engine-interface-guidance.md` and should
be hardened into versioned contracts as implementation feedback arrives.
```task
id: NK-WP-0014-T2
status: todo
@@ -143,6 +152,8 @@ NetKingdom documents per ADR-0010.
- The first implementation slice can start without unresolved ownership of
memberships, applications, projections, authorization checks, or audit
correlation.
- user-engine repo-local workplans carry implementation tasks, while
NetKingdom retains only boundary, orchestration, and responsibility-map work.
- NetKingdom responsibility-map updates are either applied or explicitly
deferred until user-engine becomes a shared platform service.

22
workplans/archived/260522-NK-WP-0015-user-engine-isolated-mvp.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "User Engine Isolated MVP"
domain: netkingdom
repo: net-kingdom
status: ready
status: archived
owner: codex
topic_slug: netkingdom
planning_priority: high
@@ -18,6 +18,12 @@ state_hub_workstream_id: "343e035d-41e1-4fc4-b209-6872e4a5fdc8"
# NK-WP-0015 - User Engine Isolated MVP
## Superseded
This NetKingdom workplan was archived on 2026-05-22 when the implementation
work was moved into the `user-engine` repository. The repo-local successor is
`USER-WP-0002 - User Engine Isolated MVP`.
## Goal
Implement the smallest useful isolated user-engine in `/home/worsch/user-engine`
@@ -53,7 +59,7 @@ Out of scope:
```task
id: NK-WP-0015-T1
status: todo
status: cancelled
priority: high
state_hub_task_id: "81a88eaa-df2e-4b9f-85f4-a1570c9c9f86"
```
@@ -64,7 +70,7 @@ keep the domain core separate from HTTP handlers and infrastructure adapters.
```task
id: NK-WP-0015-T2
status: todo
status: cancelled
priority: high
state_hub_task_id: "fc4172f7-e7f1-4ad9-98c3-37ccb08c7386"
```
@@ -75,7 +81,7 @@ and outbox events with migrations and test fixtures.
```task
id: NK-WP-0015-T3
status: todo
status: cancelled
priority: high
state_hub_task_id: "8aa5a9e9-3f23-4124-aa3b-01c099ce88bc"
```
@@ -88,7 +94,7 @@ domain logic.
```task
id: NK-WP-0015-T4
status: todo
status: cancelled
priority: high
state_hub_task_id: "cedd6319-e4c2-460c-888c-d0d95d7bdbef"
```
@@ -100,7 +106,7 @@ resolution, projections, and audit inspection.
```task
id: NK-WP-0015-T5
status: todo
status: cancelled
priority: high
state_hub_task_id: "62ecafaa-237a-4cae-ac78-1ed79ca881a1"
```
@@ -111,7 +117,7 @@ basic precedence rules, and inspectable effective profile resolution.
```task
id: NK-WP-0015-T6
status: todo
status: cancelled
priority: high
state_hub_task_id: "d627db12-2019-4870-a255-354fc77a1d22"
```
@@ -123,7 +129,7 @@ same transaction as mutations.
```task
id: NK-WP-0015-T7
status: todo
status: cancelled
priority: high
state_hub_task_id: "803e979d-a83a-43d8-a93d-ce97c83015ec"
```

22
workplans/archived/260522-NK-WP-0016-user-engine-multi-tenancy.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "User Engine Multi-Tenancy"
domain: netkingdom
repo: net-kingdom
status: ready
status: archived
owner: codex
topic_slug: netkingdom
planning_priority: high
@@ -18,6 +18,12 @@ state_hub_workstream_id: "2d592e18-e63d-4856-97a1-f8c3e019e150"
# NK-WP-0016 - User Engine Multi-Tenancy
## Superseded
This NetKingdom workplan was archived on 2026-05-22 when the implementation
work was moved into the `user-engine` repository. The repo-local successor is
`USER-WP-0003 - User Engine Multi-Tenancy`.
## Goal
Extend the isolated MVP into a tenant-aware service that follows the
@@ -48,7 +54,7 @@ Out of scope:
```task
id: NK-WP-0016-T1
status: todo
status: cancelled
priority: high
state_hub_task_id: "d4bb49a9-dffe-4317-aea2-761d737c5627"
```
@@ -59,7 +65,7 @@ and explicit platform-vs-tenant plane handling.
```task
id: NK-WP-0016-T2
status: todo
status: cancelled
priority: high
state_hub_task_id: "4a9083c0-f0bd-4dad-b221-c4563ed53209"
```
@@ -70,7 +76,7 @@ cross-tenant joins or updates.
```task
id: NK-WP-0016-T3
status: todo
status: cancelled
priority: high
state_hub_task_id: "4fd57616-53dc-4c10-bf95-553319186005"
```
@@ -82,7 +88,7 @@ cases.
```task
id: NK-WP-0016-T4
status: todo
status: cancelled
priority: high
state_hub_task_id: "dc0fc00a-5228-4b99-9fa1-6a7f6b557aac"
```
@@ -93,7 +99,7 @@ resource/action manifests or fixtures for tenant user management operations.
```task
id: NK-WP-0016-T5
status: todo
status: cancelled
priority: medium
state_hub_task_id: "17460786-7af0-4e67-8169-80c2c29934e6"
```
@@ -104,7 +110,7 @@ redacted change summaries.
```task
id: NK-WP-0016-T6
status: todo
status: cancelled
priority: high
state_hub_task_id: "a899832f-63e6-4417-bc1d-ca3c5ea89061"
```
@@ -116,7 +122,7 @@ audit correlation.
```task
id: NK-WP-0016-T7
status: todo
status: cancelled
priority: medium
state_hub_task_id: "187cdc5d-7cba-432e-8201-34bb437ba8e8"
```

22
workplans/archived/260522-NK-WP-0017-user-engine-multi-application-catalogs.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "User Engine Multi-Application And Catalog Support"
domain: netkingdom
repo: net-kingdom
status: ready
status: archived
owner: codex
topic_slug: netkingdom
planning_priority: high
@@ -18,6 +18,12 @@ state_hub_workstream_id: "08398d26-cadf-44bc-97ee-67da790040e6"
# NK-WP-0017 - User Engine Multi-Application And Catalog Support
## Superseded
This NetKingdom workplan was archived on 2026-05-22 when the implementation
work was moved into the `user-engine` repository. The repo-local successor is
`USER-WP-0004 - User Engine Multi-Application And Catalog Support`.
## Goal
Extend user-engine from a single-app MVP into a governed multi-application
@@ -49,7 +55,7 @@ Out of scope:
```task
id: NK-WP-0017-T1
status: todo
status: cancelled
priority: high
state_hub_task_id: "9363492d-49af-4929-bb64-576ed8c47ddb"
```
@@ -61,7 +67,7 @@ deployment metadata.
```task
id: NK-WP-0017-T2
status: todo
status: cancelled
priority: high
state_hub_task_id: "cd9dff26-d570-4f9f-9ebf-6f20eddf3ef0"
```
@@ -72,7 +78,7 @@ downgrade prevention, and activation/deprecation flows.
```task
id: NK-WP-0017-T3
status: todo
status: cancelled
priority: high
state_hub_task_id: "6bbe4250-a6e7-4ecf-b916-7e79eddd76f6"
```
@@ -83,7 +89,7 @@ with global and tenant layers.
```task
id: NK-WP-0017-T4
status: todo
status: cancelled
priority: high
state_hub_task_id: "29012ed5-f6c2-455f-8999-037a653d14e1"
```
@@ -94,7 +100,7 @@ mutability, sensitivity, and redaction rules.
```task
id: NK-WP-0017-T5
status: todo
status: cancelled
priority: medium
state_hub_task_id: "a3226c20-1278-409e-a49d-965e4783dc7a"
```
@@ -106,7 +112,7 @@ issuance path.
```task
id: NK-WP-0017-T6
status: todo
status: cancelled
priority: high
state_hub_task_id: "ada5a9f5-19f6-4e9e-a176-b1b47ec36ca7"
```
@@ -118,7 +124,7 @@ applications side by side.
```task
id: NK-WP-0017-T7
status: todo
status: cancelled
priority: medium
state_hub_task_id: "09f38d5c-af6c-4d95-a570-e5a5c25d7cfe"
```

22
workplans/archived/260522-NK-WP-0018-user-engine-integrated-test-scenarios.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "User Engine Integrated Test Scenarios"
domain: netkingdom
repo: net-kingdom
status: ready
status: archived
owner: codex
topic_slug: netkingdom
planning_priority: high
@@ -19,6 +19,12 @@ state_hub_workstream_id: "6f75035a-e056-4eab-8fdb-00a18bacdf87"
# NK-WP-0018 - User Engine Integrated Test Scenarios
## Superseded
This NetKingdom workplan was archived on 2026-05-22 when the implementation
work was moved into the `user-engine` repository. The repo-local successor is
`USER-WP-0005 - User Engine Integrated Test Scenarios`.
## Goal
Extend user-engine test coverage from isolated MVP tests to realistic
@@ -48,7 +54,7 @@ Out of scope:
```task
id: NK-WP-0018-T1
status: todo
status: cancelled
priority: high
state_hub_task_id: "6da86ef6-ea8b-49b9-8897-cbed00f6e61d"
```
@@ -60,7 +66,7 @@ catalogs, sensitive projection redaction, and event/audit replay.
```task
id: NK-WP-0018-T2
status: todo
status: cancelled
priority: high
state_hub_task_id: "e3424148-90d6-4c43-8f15-988f2a21d166"
```
@@ -71,7 +77,7 @@ development issuer, and invalid/expired/missing-tenant tokens.
```task
id: NK-WP-0018-T3
status: todo
status: cancelled
priority: high
state_hub_task_id: "23fa4617-e7ce-4cdc-b753-489ec361757b"
```
@@ -82,7 +88,7 @@ bulk decision scenarios.
```task
id: NK-WP-0018-T4
status: todo
status: cancelled
priority: high
state_hub_task_id: "33c53479-7856-42ee-b9ee-8795aa73c39a"
```
@@ -93,7 +99,7 @@ outbox event creation.
```task
id: NK-WP-0018-T5
status: todo
status: cancelled
priority: medium
state_hub_task_id: "fc2d73e4-1f45-4891-9c31-1a4dc2f3a002"
```
@@ -104,7 +110,7 @@ memoization, and cache invalidation on catalog/profile/membership changes.
```task
id: NK-WP-0018-T6
status: todo
status: cancelled
priority: high
state_hub_task_id: "26b63aa0-deb6-4b4d-9388-6b7e531bd4ff"
```
@@ -116,7 +122,7 @@ facts, and missing audit correlation.
```task
id: NK-WP-0018-T7
status: todo
status: cancelled
priority: medium
state_hub_task_id: "a46e6e78-71a1-4518-881f-85b39269f4a8"
```

22
workplans/archived/260522-NK-WP-0019-user-engine-finalization-polish.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "User Engine Implementation Assessment And Polish"
domain: netkingdom
repo: net-kingdom
status: ready
status: archived
owner: codex
topic_slug: netkingdom
planning_priority: medium
@@ -18,6 +18,12 @@ state_hub_workstream_id: "d2daa8b4-8ecf-4377-b382-492e653735f7"
# NK-WP-0019 - User Engine Implementation Assessment And Polish
## Superseded
This NetKingdom workplan was archived on 2026-05-22 when the implementation
work was moved into the `user-engine` repository. The repo-local successor is
`USER-WP-0006 - User Engine Implementation Assessment And Polish`.
## Goal
Assess the implemented user-engine against its PRD, architecture blueprint,
@@ -48,7 +54,7 @@ Out of scope:
```task
id: NK-WP-0019-T1
status: todo
status: cancelled
priority: high
state_hub_task_id: "116b5362-ebbf-4d21-83e8-bbc82e80a71a"
```
@@ -60,7 +66,7 @@ follow-up work.
```task
id: NK-WP-0019-T2
status: todo
status: cancelled
priority: high
state_hub_task_id: "08bd8ca3-dd7e-41c9-b8d2-c9b7c72ceb0a"
```
@@ -73,7 +79,7 @@ resources.
```task
id: NK-WP-0019-T3
status: todo
status: cancelled
priority: medium
state_hub_task_id: "b8ff89a1-cdfb-445a-ae4d-ca4fd4a455eb"
```
@@ -84,7 +90,7 @@ contracts. Remove accidental implementation details from public contracts.
```task
id: NK-WP-0019-T4
status: todo
status: cancelled
priority: medium
state_hub_task_id: "f57d87d7-fdc8-485c-ba93-86c5a8342f04"
```
@@ -95,7 +101,7 @@ runbooks for common failure modes.
```task
id: NK-WP-0019-T5
status: todo
status: cancelled
priority: medium
state_hub_task_id: "42a01f4e-c646-4551-bd94-e122c9c16226"
```
@@ -106,7 +112,7 @@ administration boundaries, and event/audit integration.
```task
id: NK-WP-0019-T6
status: todo
status: cancelled
priority: medium
state_hub_task_id: "7838d62b-94eb-437a-8418-7a900cde9716"
```
@@ -117,7 +123,7 @@ guarantees for future consumers.
```task
id: NK-WP-0019-T7
status: todo
status: cancelled
priority: low
state_hub_task_id: "19569b30-c8df-441a-b815-c9217a82abaf"
```