# 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 flow contracts are implemented by USER-WP-0014.