---
id: USER-WP-0012
type: workplan
title: "Hats, Realms, Services, Assets, And Access Profiles"
domain: communication
repo: user-engine
status: finished
owner: codex
topic_slug: netkingdom
planning_priority: high
planning_order: 12
created: "2026-06-15"
updated: "2026-06-15"
depends_on:
  - USER-WP-0010
state_hub_workstream_id: "f3cf0d30-eb6b-4734-a0a3-5a755d4cf150"
---

# USER-WP-0012 - Hats, Realms, Services, Assets, And Access Profiles

## Goal

Model how users and groups wear different hats across NetKingdom realms,
services, and assets. Provide access-control facts, profile layers, and
claims-enrichment context that authorization systems and service runtimes can
consume without moving final policy decisions into user-engine.

## Scope Direction

user-engine owns the identity-domain representation of hats, memberships,
access profiles, and active context. Authorization engines own policy decisions
and protected services own runtime enforcement.

## Non-Goals

- Do not implement the final ACL enforcement engine.
- Do not define every service-specific permission in user-engine.
- Do not bypass the authorization port.
- Do not make browser/UI state the source of truth for active access context.

## Tasks

```task
id: USER-WP-0012-T1
status: done
priority: high
state_hub_task_id: "b86f0072-e666-479b-9b90-96d4015bbfa0"
```

Define realm, service area, asset scope, access profile, group, and hat
vocabulary. Map each concept to current user-engine membership, profile, and
canon reference patterns.

```task
id: USER-WP-0012-T2
status: done
priority: high
state_hub_task_id: "66117083-8e85-44e1-9a76-cfd10dd24d23"
```

Add hat selection and active context models. A user should be able to choose an
active hat for a tenant, realm, service, or asset context when allowed.

```task
id: USER-WP-0012-T3
status: done
priority: high
state_hub_task_id: "1dffda4c-f979-480e-9d6d-12ec9576780d"
```

Implement access profile templates that combine memberships, factor assurance
requirements, profile defaults, and claims projection rules.

```task
id: USER-WP-0012-T4
status: done
priority: high
state_hub_task_id: "b07494fe-f301-49e2-8ea8-267a4c5219ee"
```

Extend `identity_context` and claims-enrichment projections with active hat,
realm, service, asset, group, access profile, and evidence references.

```task
id: USER-WP-0012-T5
status: done
priority: medium
state_hub_task_id: "c78e10c4-b245-4a83-a75d-4b46a6073fd2"
```

Add ports for exporting access-control facts to authorization engines or ACL
systems while preserving source-of-truth boundaries.

```task
id: USER-WP-0012-T6
status: done
priority: medium
state_hub_task_id: "f9f32165-3a12-424e-a370-bb2ab8348c21"
```

Add tests for hat selection, cross-tenant denial, missing factor assurance,
group-derived access, service-specific projection, and redacted diagnostics.

## Acceptance Criteria

- Users can have multiple hats without collapsing them into one account state.
- Active hat context is explicit in identity context and projections.
- Access profile facts can be exported to authorization systems.
- Missing tenant, realm, service, asset, factor, or approval context fails
  closed.
- Final policy and ACL enforcement remain outside user-engine.

## Expected Outputs

- Hat and access profile domain model.
- Active context service facade.
- Identity-context and claims projection updates.
- Access-control fact export tests.

## Implementation Notes

Implemented on 2026-06-15:

- Added `AccessScopeType`, `AccessMembershipRequirement`, `AccessProfile`,
  `ActiveAccessContext`, and `AccessControlFact` domain models.
- Added access-profile and active-context persistence to `UserEngineStore` and
  `InMemoryUserEngineStore`, including transaction snapshots and record
  counts.
- Added `UserEngineService` facade methods:
  `register_access_profile`, `list_access_profiles`, `select_active_hat`,
  `export_access_control_facts`, and `access_profile_diagnostics`.
- Added fail-closed active hat selection requiring tenant context, active
  tenant account state, matching membership facts, unexpired factor evidence,
  non-approval-required profile state, and authorization-port approval.
- Extended `identity_context` with active access context, access-control facts,
  canon references for hats/realms/services/assets/groups, and active-hat
  relationship references.
- Extended claims-enrichment projections with service-filtered access context
  while keeping raw factor values out of events and diagnostics.
- Added adapter-neutral access-control fact export for direct memberships,
  group-derived facts, and active-context facts.
- Added `docs/hats-realms-services-assets-access-profiles.md`, public contract
  updates, and tests for active hat selection, cross-tenant denial, missing
  factor assurance, group-derived access, service-specific projections, and
  redacted diagnostics.

Verification:

```text
make test
Ran 61 tests in 0.515s
OK
```