user-engine/workplans/USER-WP-0010-registration-identity-and-factor-model.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on	state_hub_workstream_id
USER-WP-0010	workplan	Registration Identity And Factor Model	netkingdom	user-engine	finished	codex	netkingdom	high	10	2026-06-15	2026-06-15	USER-WP-0007 USER-WP-0009	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

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.

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.

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.

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.

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.

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:

make test
Ran 46 tests in 0.162s
OK