feat: implement access profiles and hats

docs/hats-realms-services-assets-access-profiles.md

@@ -0,0 +1,106 @@
+# Hats, Realms, Services, Assets, And Access Profiles
+
+Status: implemented headless slice
+Date: 2026-06-15
+Related workplan: USER-WP-0012
+
+## Purpose
+
+This slice models how a NetKingdom user can wear different hats across tenant,
+realm, service, asset, and group contexts. It gives authorization systems and
+service runtimes explicit access-control facts and claims-enrichment context
+without moving final policy decisions into user-engine.
+
+## Vocabulary
+
+The USER-WP-0012 vocabulary maps onto existing user-engine facts:
+
+- tenant: isolation boundary and tenant account state;
+- realm: broad domain or community scope represented by membership scope
+  `realm`;
+- service: protected application or service scope represented by membership
+  scope `service` or an access profile `service_id`;
+- asset: protected resource scope represented by membership scope `asset` or
+  an access profile `asset_id`;
+- group: group membership represented by membership scope `group`;
+- hat: active role persona selected from an access profile;
+- access profile: template that combines membership requirements, factor
+  requirements, profile defaults, and projection claim rules.
+
+## Domain Model
+
+`AccessProfile` defines a claimable hat for a tenant context. It stores the
+hat name, scope type/id, optional realm/service/asset ids, required membership
+facts, required factor types, profile defaults, claims, group ids, and an
+approval flag.
+
+`ActiveAccessContext` records the user's currently selected hat for a tenant.
+It stores the selected access profile, active scope, matched membership ids,
+verified factor ids, group ids, projection claims, and profile defaults.
+
+`AccessControlFact` is the export shape for policy and ACL systems. Facts can
+represent direct user memberships, group-derived facts, and active-context
+facts over realm, service, or asset scopes.
+
+## Public Facade
+
+`UserEngineService` exposes:
+
+- `register_access_profile(...)`
+- `list_access_profiles(...)`
+- `select_active_hat(...)`
+- `export_access_control_facts(...)`
+- `access_profile_diagnostics(...)`
+
+All mutating and read/export operations pass through the authorization port.
+
+## Selection Rules
+
+Hat selection fails closed unless all of these are true:
+
+- the actor is allowed to operate in the tenant context;
+- the target user has an active tenant account;
+- the access profile belongs to the tenant and is not approval-required;
+- every profile membership requirement is satisfied by existing memberships;
+- every required factor type has unexpired verified user evidence;
+- the authorization port allows the active-context selection.
+
+Selecting a hat records an `ActiveAccessContext`, emits
+`active_access_context.selected`, and keeps raw factor values out of events and
+projections.
+
+## Identity Context And Projections
+
+`identity_context` now includes:
+
+- `active_access_context`;
+- `access_control_facts`;
+- canon references for active hat, access profile, realm, service area, asset
+  scope, and groups;
+- relationship references such as `wears_hat` and
+  `selected_access_profile`.
+
+Claims-enrichment projections include an `access_context` mapping when the
+active context applies to the requested application/service. Service-specific
+contexts are omitted from projections for other applications.
+
+## Export Boundary
+
+`export_access_control_facts` returns an adapter-neutral manifest plus facts.
+External authorization engines or ACL systems can consume these facts, but
+they remain responsible for final policy decisions and runtime enforcement.
+
+## Redaction And Diagnostics
+
+Diagnostics report counts, required factor types, and approval-required issues.
+They deliberately do not return profile default values, projection claim
+values, factor values, phone numbers, postal addresses, eID payloads, or other
+proofing data.
+
+## Current Limits
+
+- user-engine does not implement a policy engine or ACL evaluator.
+- Approval workflows for privileged hats remain a later slice.
+- Access profile profile-default values are carried into active context and
+  projections, but this slice does not persist them as catalog profile values.
+- UI selection flows are left to USER-WP-0014.