user-engine/docs/registration-identity-and-factor-model.md

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.

Current Limits

• Prepared account claiming is intentionally left to USER-WP-0011.
• Hats, realms, services, assets, and access profiles are left to USER-WP-0012.
• Welcome protocols and onboarding journeys are left to USER-WP-0013.
• Registration UI is left to USER-WP-0014.
• Provider-backed proofing and credential flows remain external adapters.