generated from coulomb/repo-seed
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# Public Contracts
|
|
|
|
## Headless Service Surface
|
|
|
|
`UserEngineService` is the stable in-process API for the current MVP. Future
|
|
HTTP or RPC adapters should preserve these operation names:
|
|
|
|
- `health`, `readiness`, `operability_snapshot`, `outbox_diagnostics`
|
|
- `me`, `create_user`, `set_account_status`, `link_identity`
|
|
- `resolve_tenant_context`, `set_tenant_account_status`, `add_membership`,
|
|
`tenant_diagnostics`
|
|
- `register_application`, `publish_catalog`
|
|
- `set_profile_value`, `effective_profile`, `projection`, `identity_context`
|
|
- `audit_records`, `outbox_events`
|
|
|
|
## Identity Context Contract
|
|
|
|
`identity_context` is the first canon-facing read model for NetKingdom
|
|
identity-domain consumers. It resolves a verified actor into the local user,
|
|
account, external identity links, tenant scope, memberships, optional
|
|
application scope, optional effective profile, canon entity references,
|
|
relationship references, grant-like membership facts, and evidence references.
|
|
|
|
The method keeps these concepts distinct:
|
|
|
|
- user-engine `User` record;
|
|
- operational `Account`;
|
|
- external `Identity Record` and scoped issuer/subject identifier;
|
|
- `Actor` from verified claims;
|
|
- `Authenticated Subject` projected from issuer and subject;
|
|
- `Authorization Principal` projected for policy evaluation;
|
|
- `Tenant`, `Team`, `Scope`, `Membership Relationship`, and `Role` references.
|
|
|
|
Evidence references are currently derived from local audit records. External
|
|
policy, control, access-review, exception, and lifecycle task references belong
|
|
to adapter contracts and remain non-owned unless a later workplan assigns
|
|
source-of-truth responsibility to user-engine.
|
|
|
|
## Error Taxonomy
|
|
|
|
- `ValidationError`: caller supplied an invalid shape, state transition, or
|
|
catalog/profile value.
|
|
- `AuthorizationDenied`: the authorization port or tenant boundary denied the
|
|
operation.
|
|
- `NotFoundError`: a requested user, account, or active attribute is missing.
|
|
- `ConflictError`: uniqueness or ownership would be violated.
|
|
|
|
## Catalog Contract
|
|
|
|
Catalogs are active by namespace and owning application. Attribute keys must
|
|
use the namespace prefix. Active namespace ownership cannot move to another
|
|
application. Catalog updates cannot move versions backwards or downgrade
|
|
attribute sensitivity.
|
|
|
|
## Projection Contract
|
|
|
|
Application runtime, agent-context, and claims-enrichment projections require
|
|
an `application_id` and are filtered to that application's active catalogs.
|
|
Sensitive and secret values are redacted outside admin, audit, and
|
|
self-service projections.
|
|
|
|
## Audit And Event Contract
|
|
|
|
Every mutating service operation appends an audit record and outbox event with
|
|
the same correlation id and resolved tenant. Authorization denials are audited
|
|
without emitting outbox events.
|
|
|
|
Local audit records may be exported as identity-canon `Evidence Source`
|
|
references. Durable platform audit custody remains outside user-engine.
|
|
|
|
## Migration Contract
|
|
|
|
The isolated store exposes `SCHEMA_VERSION = 0001_initial` and a `migrate`
|
|
hook. Database-backed stores must expose equivalent readiness semantics before
|
|
they are accepted by platform adapters.
|