---
id: USER-WP-0010
type: workplan
title: "Registration Identity And Factor Model"
domain: netkingdom
repo: user-engine
status: finished
owner: codex
topic_slug: netkingdom
planning_priority: high
planning_order: 10
created: "2026-06-15"
updated: "2026-06-15"
depends_on:
  - USER-WP-0007
  - USER-WP-0009
state_hub_workstream_id: "0d53560b-2b9d-442b-9328-4b2ce5c5bdae"
---

# USER-WP-0010 - Registration Identity And Factor Model

## Goal

Define and implement the first headless registration domain slice for
NetKingdom users. The slice should let user-engine start and complete a
registration session, establish a stable NetKingdom ID, link verified external
identities, record factor evidence, and return identity context without
becoming an identity provider or factor-proofing service.

## Scope Direction

user-engine owns the registration-domain records and service facade. NetKingdom
IAM, identity providers, eID providers, mail/SMS proofing, credential
lifecycle, sessions, and tokens remain external adapter concerns.

## Non-Goals

- Do not implement password, passkey, session, MFA, SMS, email, or eID proofing
  providers in user-engine.
- Do not issue OIDC/SAML tokens.
- Do not build the registration UI in this workplan.
- Do not implement prepared account claiming, access profiles, or onboarding
  journeys beyond the hooks needed for later workplans.

## Tasks

```task
id: USER-WP-0010-T1
status: done
priority: high
state_hub_task_id: "2a6c93de-e320-41e6-8930-7a4099c5757a"
```

Define NetKingdom ID semantics. Decide whether the public NetKingdom ID is the
existing `User.user_id`, an alias, or a separate mapped identifier. Document
stability, visibility, privacy, and migration expectations.

```task
id: USER-WP-0010-T2
status: done
priority: high
state_hub_task_id: "31ddb44e-b7d1-406e-9114-78c5e7f92478"
```

Add registration session domain models and lifecycle states: started,
factor_pending, factor_verified, completed, abandoned, expired, and rejected.

```task
id: USER-WP-0010-T3
status: done
priority: high
state_hub_task_id: "7441f064-eb49-4e66-8c1d-a2626aae020c"
```

Add identity factor and factor verification models for email, phone, postal
address, eID, invite, and SSO identity evidence. Store assurance metadata and
evidence references without storing secret proofing payloads.

```task
id: USER-WP-0010-T4
status: done
priority: high
state_hub_task_id: "7057afda-d585-48cd-bac1-f0bd0f05fef5"
```

Create factor verification adapter ports. The adapters should accept external
proofing results and return normalized factor evidence for user-engine.

```task
id: USER-WP-0010-T5
status: done
priority: high
state_hub_task_id: "f4f0da38-9810-45e7-ab4e-0619eb45b3c4"
```

Implement a headless registration facade for start, attach verified factor,
complete, abandon, and resume flows.

```task
id: USER-WP-0010-T6
status: done
priority: medium
state_hub_task_id: "c29b31cd-f2b2-41b6-86ee-9c78470abf01"
```

Add audit, outbox, diagnostics, and redaction behavior for registration and
factor lifecycle transitions.

## Acceptance Criteria

- A caller can start and complete a headless registration flow from verified
  factor evidence.
- Completed registration creates or resolves a stable NetKingdom user/account
  and external identity links.
- Factor evidence is inspectable through safe metadata and evidence references,
  not raw proofing secrets.
- Registration failure, expiry, and abandon states are auditable.
- No credential, token, or proofing provider ownership moves into user-engine.

## Expected Outputs

- Registration and factor domain models.
- Registration service facade.
- Factor verification adapter ports.
- Documentation and tests for the basic self-registration flow.

## Implementation Notes

Implemented on 2026-06-15:

- Defined NetKingdom ID semantics as the existing opaque `User.user_id` for
  this first slice.
- Added `RegistrationStatus`, `IdentityFactorType`, `FactorVerification`,
  `IdentityFactor`, and `RegistrationSession` domain models.
- Added registration and factor persistence to `UserEngineStore` and
  `InMemoryUserEngineStore`.
- Added `FactorVerificationAdapter` for normalizing external proofing results
  into safe factor evidence.
- Added `UserEngineService` registration facade methods:
  `start_registration`, `attach_registration_factor`,
  `complete_registration`, `abandon_registration`, `expire_registration`,
  `resume_registration`, and `registration_diagnostics`.
- Added audit/outbox events for registration lifecycle transitions while
  keeping factor values out of event payloads and diagnostics.
- Added `docs/registration-identity-and-factor-model.md` and public contract
  updates.
- Added tests for successful email-backed registration, required-factor
  enforcement, adapter-normalized factor evidence, and abandoned-session
  behavior.

Verification:

```text
make test
Ran 46 tests in 0.162s
OK
```