# 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`