net-kingdom/docs/user-engine-interface-guidance.md

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