generated from coulomb/repo-seed
107 lines
4.1 KiB
Markdown
107 lines
4.1 KiB
Markdown
# 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.
|