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

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. Hats, access profiles, and AccessControlFact values are PIP claims. They are not an authorization decision. Compiling them into a local allow or deny before access-engine runs is an early decision (security-layer-model §6.1) and is forbidden.

select_active_hat and export_access_control_facts never return an effect. access-engine remains the only decision point; consumers that need an allow or deny must ask it.

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.