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
onboard_family_dataspace, invite_family_member, resend_family_invitation, revoke_family_invitation, accept_family_invitation
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.

Family Dataspace Onboarding Contract

onboard_family_dataspace is a convenience facade for personal-family identity-domain setup. It composes existing user, account, tenant-account, membership, application, catalog, profile, audit, outbox, projection, and identity-context operations.

The facade represents a family as a NetKingdom tenant plus a family scope. It does not provision the tenant, issue SSO tokens, own credentials, or implement the protected dataspace runtime. Family roles are scoped membership facts such as owner, adult, child, guest, and delegated-caretaker; authorization systems decide how those facts affect access.

Invitation acceptance requires already-verified claims. user-engine stores local invitation lifecycle, links the verified external identity, activates account state, and returns both identity_context and a CLAIMS_ENRICHMENT projection for SSO adapters.

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.

4.1 KiB Raw Blame History