# Registration Identity And Factor Model

Status: implemented headless slice
Date: 2026-06-15
Related workplan: USER-WP-0010

## Purpose

This document defines the first NetKingdom registration slice in
`user-engine`. The slice lets a caller start a registration session, attach
externally verified identity-factor evidence, complete registration into a
stable NetKingdom user/account, and inspect safe diagnostics.

The design keeps user-engine in its identity-domain lane:

- IAM and proofing providers verify credentials, email, phone, eID, invite, or
  SSO evidence.
- user-engine stores the registration session, normalized factor metadata,
  user/account records, external identity links, audit records, and outbox
  events.
- Authorization systems continue to make final policy and ACL decisions.

## NetKingdom ID

For this slice, the NetKingdom ID is the existing stable `User.user_id`.

That choice keeps the first implementation simple and avoids adding a second
identifier before a concrete public-ID requirement exists. Consumers should
treat the ID as opaque. It must not encode identity-provider issuer/subject
pairs, factor values, tenant names, email addresses, phone numbers, or eID
payloads.

If NetKingdom later needs a public alias, vanity handle, or migration-safe
external identifier, that can be added as a separate mapped identifier without
changing the registration facade's `netkingdom_id` contract.

## Domain Model

`RegistrationSession` tracks the workflow:

- `started`
- `factor_pending`
- `factor_verified`
- `completed`
- `abandoned`
- `expired`
- `rejected`

`FactorVerification` is adapter output from an external proofing system. It is
safe metadata: factor type, normalized value, optional display value, source
system, assurance metadata, evidence references, verification time, and
optional expiry.

`IdentityFactor` is the persisted user-engine record. During registration it
is attached to a registration session. After completion it is also attached to
the canonical user.

Supported factor types are:

- `email`
- `phone`
- `postal_address`
- `eid`
- `invite`
- `sso`

## Public Facade

`UserEngineService` exposes:

- `start_registration(...)`
- `attach_registration_factor(...)`
- `complete_registration(...)`
- `abandon_registration(...)`
- `expire_registration(...)`
- `resume_registration(...)`
- `registration_diagnostics(...)`

The completion result includes the completed session, user, account,
`netkingdom_id`, and `identity_context`.

## Factor Adapter Boundary

`FactorVerificationAdapter` normalizes external proofing results into
`FactorVerification`. A caller may also pass an already-normalized
`FactorVerification` directly.

Adapters must strip secret challenge material, proofing payloads, provider
tokens, and raw documents before data reaches user-engine.

## Audit, Outbox, And Redaction

Registration mutations emit local audit records and outbox events:

- `registration.started`
- `registration.factor_verified`
- `registration.completed`
- `registration.abandoned`
- `registration.expired`

Outbox payloads include registration ids, factor ids, factor types, source
systems, status, and user ids. They deliberately do not include normalized
factor values such as email addresses, phone numbers, postal addresses, or eID
payloads.

Diagnostics report counts by status and total verified factors. They do not
return factor values.

## Follow-On Boundaries

- Prepared account claiming is implemented by USER-WP-0011 and documented in
  `docs/prepared-accounts-and-entitlement-claims.md`.
- Hats, realms, services, assets, and access profiles are implemented by
  USER-WP-0012 and documented in
  `docs/hats-realms-services-assets-access-profiles.md`.
- Welcome protocols and onboarding journeys are implemented by USER-WP-0013
  and documented in `docs/onboarding-journeys-and-welcome-protocols.md`.
- Registration UI contracts are implemented by USER-WP-0014 and documented in
  `docs/registration-and-access-management-ui.md`.
- Provider-backed proofing and credential flows remain external adapters.