NetKingdom Integration Interfaces

Status: initial implementation guidance Date: 2026-05-22

Purpose

This document translates the NetKingdom user-engine interface guidance into repo-local implementation boundaries. It is intentionally practical: these are the ports, adapters, and data contracts the implementation should preserve.

See also the cross-repo assessment in the net-kingdom repo: /home/worsch/net-kingdom/docs/user-engine-netkingdom-integration-assessment.md (for current intent/scope fit, gaps, and recommendations as of 2026-06-03).

Required Ports

Port	Direction	Purpose
`IdentityClaimsAdapter`	inbound	Accept a verified identity envelope and map `(issuer, subject)` to a local `user_id`.
`AuthorizationCheckPort`	outbound	Ask an authorization service whether an actor may perform a user-engine action.
`ApplicationBindingStore`	local	Bind a user-engine application to external OIDC clients, protected systems, catalog namespaces, and event identities.
`MembershipFactExporter`	outbound	Export user-engine-owned membership facts as read models for authorization systems.
`EventOutbox`	outbound	Publish durable lifecycle/profile/catalog/membership events after commit.
`AuditWriter`	local/outbound	Persist local audit and provide redacted summaries for platform audit sinks.
`SecretProvider`	inbound	Load runtime secrets through environment/local config in standalone mode and scoped secret providers in platform mode.

Source-Of-Truth Rules

user-engine is the source of truth for user records, account lifecycle, identity links, profile values, preferences, memberships it creates, catalog definitions, and projections.
Identity providers are the source of truth for authentication-time subject, issuer, assurance, coarse role, and group claims.
Authorization systems decide whether an actor may perform an action.
Event sinks and audit stores consume user-engine events; they do not become profile stores.

Authorization Request Shape

Every protected operation should be reducible to:

actor:
  issuer: string
  subject: string
  tenant: string
  principal_type: human | service | agent
  roles: [string]
  groups: [string]
  scopes: [string]
  assurance: object
resource:
  type: user-engine:user | user-engine:profile | user-engine:membership | user-engine:application | user-engine:catalog | user-engine:projection | user-engine:audit
  id: string
action: string
context:
  tenant: string
  application_id: string | null
  target_user_id: string | null
  correlation_id: string

The domain layer should depend on this port, not on a concrete authorization client.

Projection Types

self_service: current-user view and allowed mutations.
admin: scope-admin view and allowed mutations.
application_runtime: data a registered application may consume.
audit: redacted operational trace.
agent_context: policy-filtered context for agentic systems.
claims_enrichment: optional adapter-owned input for identity systems.

user-engine must not issue tokens. Claims enrichment is optional and must be cache/freshness governed by the identity-side adapter.

Implementation Implications

Keep domain logic independent of HTTP, database, and authorization clients.
Validate catalog ownership before accepting attribute values.
Resolve effective profiles deterministically and expose resolution metadata.
Persist audit and outbox events in the same transaction as mutations.
Use request-scoped memoization and batch authorization checks for list views.
Fail closed for sensitive writes when authorization cannot be determined.

3.6 KiB Raw Blame History