generated from coulomb/repo-seed
121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
# 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.
|