# 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. |
| `EvidenceReferenceExporter` | outbound | Export local audit/review material as identity-canon evidence references without owning the platform audit system. |
| `PolicyControlReferenceResolver` | outbound | Resolve policy, control, review, exception, or waiver references for identity-domain traces. |
| `LifecycleTaskSink` | outbound | Create or link lifecycle, review, remediation, or integration-gap work in a task system. |
| `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.
- Governance, security, and authorization systems own policy, control, review,
  exception, and waiver definitions. user-engine can reference them in identity
  context traces.
- Task systems own lifecycle work queues. user-engine can create or link
  identity-domain work through an explicit task sink.
- 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:

```yaml
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.

## Identity Context Shape

Every domain-facing identity context should be reducible to:

```yaml
actor:
  issuer: string
  subject: string
  tenant: string
  principal_type: human | service | agent
user:
  user_id: string
account:
  account_id: string
  status: string
identity_links:
  - issuer: string
    subject: string
tenant: string
application_id: string | null
memberships:
  - scope_type: string
    scope_id: string
    kind: string
canon_refs:
  entities: object
  relationships: object
  grant_like_refs: object
  evidence_refs: object
gaps: [string]
```

The context is a facade over NetKingdom IAM and security infrastructure. It
does not issue tokens, decide authorization policy, or own credentials.

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