# 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.