generated from coulomb/repo-seed
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
# 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:
|
|
|
|
```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.
|
|
|
|
## 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.
|