generated from coulomb/repo-seed
Split user-engine implementation planning
This commit is contained in:
148
docs/user-engine-interface-guidance.md
Normal file
148
docs/user-engine-interface-guidance.md
Normal 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`
|
||||
Reference in New Issue
Block a user