generated from coulomb/repo-seed
155 lines
6.7 KiB
Markdown
155 lines
6.7 KiB
Markdown
# User Engine Interface Guidance
|
|
|
|
Status: accepted interface guidance
|
|
Date: 2026-05-22
|
|
Owner: NetKingdom
|
|
Canonical contract: `canon/standards/user-engine-boundary-contract_v0.1.md`
|
|
Related:
|
|
|
|
- `canon/standards/user-engine-boundary-contract_v0.1.md`
|
|
- `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`
|
|
- `docs/user-engine-netkingdom-integration-assessment.md` (detailed current-state fit, gaps, and recommendations)
|
|
|
|
## Purpose
|
|
|
|
This document summarizes the cross-repo interface guidance for integrating
|
|
`user-engine` into the NetKingdom landscape without duplicating identity,
|
|
authorization, deployment, audit, or UI responsibilities. The normative
|
|
versioned contract is
|
|
`canon/standards/user-engine-boundary-contract_v0.1.md`; this document remains
|
|
as the shorter implementation-facing guide.
|
|
|
|
`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`
|