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.

4.1 KiB Raw Blame History