generated from coulomb/repo-seed
119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
# Prepared Accounts And Entitlement Claims
|
|
|
|
Status: implemented headless slice
|
|
Date: 2026-06-15
|
|
Related workplan: USER-WP-0011
|
|
|
|
## Purpose
|
|
|
|
Prepared accounts let a tenant admin, operator, family owner, service owner, or
|
|
upstream system prepare user-domain intent before a person registers. The
|
|
package can name expected factor matches, tenant account state, memberships,
|
|
profile defaults, application bindings, and onboarding journey hints.
|
|
|
|
Prepared accounts are not credentials. A package is claimable only after a
|
|
completed registration presents matching verified factor evidence.
|
|
|
|
## Domain Model
|
|
|
|
`PreparedAccount` stores pending account intent:
|
|
|
|
- tenant
|
|
- required factor matches
|
|
- prepared entitlements
|
|
- status: `pending`, `claimed`, `revoked`, or `expired`
|
|
- preparer subject
|
|
- optional display name and primary email hints
|
|
- optional expiry
|
|
- claim metadata and lifecycle timestamps
|
|
|
|
`PreparedFactorRequirement` stores the factor type and normalized value to
|
|
match against verified registration factors. The model also carries optional
|
|
source-system and evidence references.
|
|
|
|
`PreparedEntitlement` stores the activation intent. Supported kinds are:
|
|
|
|
- `tenant_account`
|
|
- `membership`
|
|
- `profile_value`
|
|
- `application_binding`
|
|
- `onboarding_journey`
|
|
|
|
Entitlements may be marked `requires_approval`. Those packages fail closed in
|
|
the current claim facade until an explicit approval workflow is added.
|
|
|
|
## Public Facade
|
|
|
|
`UserEngineService` exposes:
|
|
|
|
- `prepare_account(...)`
|
|
- `update_prepared_account(...)`
|
|
- `list_prepared_accounts(...)`
|
|
- `revoke_prepared_account(...)`
|
|
- `expire_prepared_account(...)`
|
|
- `claim_prepared_account(...)`
|
|
|
|
Create, update, list, revoke, expire, and claim operations all pass through the
|
|
authorization port. The service depends on `UserEngineStore` protocol methods,
|
|
not the in-memory adapter internals.
|
|
|
|
## Claim Rules
|
|
|
|
Claims are only evaluated for completed registration sessions with a resolved
|
|
canonical user. A prepared account matches when every required factor is
|
|
present as unexpired verified `IdentityFactor` evidence on the registration.
|
|
|
|
The claim facade fails closed when:
|
|
|
|
- the caller names a missing, revoked, expired, claimed, or mismatching package;
|
|
- no prepared account matches the registration factors;
|
|
- multiple pending prepared accounts match the same verified factors;
|
|
- any entitlement in the package requires manual approval;
|
|
- entitlement activation references an invalid profile attribute or
|
|
unregistered application.
|
|
|
|
Factor requirements must include non-empty normalized values. Duplicate
|
|
pending packages with the same tenant and factor-signature are blocked during
|
|
create/update. Expired packages are ignored by duplicate checks and cannot be
|
|
claimed.
|
|
|
|
## Activation
|
|
|
|
Successful claim converts prepared entitlements into user-engine-owned facts:
|
|
|
|
- `TenantAccount` for tenant access state;
|
|
- `Membership` for scoped role facts;
|
|
- `ProfileValue` for catalog-validated profile defaults;
|
|
- `ApplicationBinding` for registered protected-system mappings;
|
|
- `prepared_account.onboarding_requested` outbox events for journey starts.
|
|
|
|
The prepared account is then marked `claimed` with the claiming user and
|
|
registration id.
|
|
|
|
## Audit, Outbox, And Redaction
|
|
|
|
Prepared-account mutations emit audit and outbox records:
|
|
|
|
- `prepared_account.created`
|
|
- `prepared_account.updated`
|
|
- `prepared_account.revoked`
|
|
- `prepared_account.expired`
|
|
- `prepared_account.claimed`
|
|
- `prepared_account.onboarding_requested`
|
|
|
|
Denied claim decisions are audited without outbox events. Outbox payloads use
|
|
ids, counts, factor types, statuses, and journey names. They deliberately avoid
|
|
normalized factor values such as email addresses, phone numbers, postal
|
|
addresses, and eID payloads.
|
|
|
|
## Current Limits
|
|
|
|
- Prepared accounts do not issue credentials, invitations, MFA challenges, or
|
|
tokens.
|
|
- Approval-required entitlement packages are blocked until a later workplan
|
|
adds explicit approval decisions.
|
|
- Final authorization policy and ACL evaluation remains outside user-engine;
|
|
user-engine only activates owned facts for policy systems to consume.
|
|
- Journey orchestration from prepared-account onboarding requests is
|
|
implemented by USER-WP-0013.
|