generated from coulomb/repo-seed
154 lines
4.8 KiB
Markdown
154 lines
4.8 KiB
Markdown
---
|
|
id: USER-WP-0012
|
|
type: workplan
|
|
title: "Hats, Realms, Services, Assets, And Access Profiles"
|
|
domain: netkingdom
|
|
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
|
|
```
|