user-engine/docs/netkingdom-registration-onboarding-vision.md

NetKingdom Registration And Onboarding Vision

Status: vision and proposed roadmap Date: 2026-06-15 Related workplans: USER-WP-0010 through USER-WP-0015

Purpose

NetKingdom needs a convenient way for people to register, receive a stable NetKingdom identity, claim prepared rights, choose the role or "hat" they are acting under, and enter services through guided onboarding journeys.

user-engine can support this as the identity-domain and user-domain system behind a registration UI. It should not become the identity provider, credential system, MFA provider, final authorization policy engine, or runtime ACL enforcer. Instead, it should provide the domain model, orchestration facades, profile and membership facts, identity context, audit/outbox events, and optional UI/API contracts that NetKingdom IAM, authorization, and service runtimes can consume.

Product Vision

A new user should be able to arrive at NetKingdom, establish the required identity factors, receive or claim a NetKingdom ID, and immediately see the services, realms, groups, and assets they may access. If the user is expected before registration, an administrator, tenant owner, family owner, or upstream system should be able to prepare the account and rights in advance. During registration, verified factors such as email, phone, postal address, or eID can match those preparations and attach the waiting access package to the new account.

The end state is:

People register once with NetKingdom.
NetKingdom links verified factors and external identities to one canonical user.
Prepared rights can be claimed safely when factor evidence matches.
Users choose an active hat for the context they are entering.
Applications receive claims, profile projections, and membership facts.
Authorization systems evaluate ACLs and policy from explicit facts.
Subsystem onboarding is driven by events, welcome protocols, and journeys.

Answer: Can user-engine Provide A UI?

Yes, but the UI should be an optional NetKingdom registration and onboarding surface backed by user-engine service contracts. The repo's current intent is "headless first" and "optional UI, not UI-driven". That means user-engine can own a small registration UI or UI contract when it is the most convenient way to operate the domain, as long as source-of-truth boundaries stay explicit:

• NetKingdom IAM verifies credentials and proofing factors.
• user-engine stores users, accounts, identity links, memberships, profiles, prepared-account claims, role context, and onboarding state.
• Authorization systems make final access decisions.
• Service runtimes enforce ACLs for their own resources.
• Audit, evidence, and lifecycle systems receive exported records and events.

Key Concepts

NetKingdom ID

The NetKingdom ID should be a stable canonical identifier for the person in the NetKingdom identity domain. It should not expose raw identity-provider issuer/subject pairs. user-engine can mint or map this identifier through the User record and ExternalIdentity links, while IAM continues to authenticate the subject.

Registration Session

A registration session is a short-lived onboarding workflow. It tracks the actor, verified factor evidence, selected tenant or realm context, consent, prepared-account matches, requested roles, and completion state. It should be auditable and resumable without storing secret credential material.

Identity Factors

Factors are evidence that help establish or link identity:

• email address;
• phone number;
• postal address;
• eID or government-backed identity;
• organization-issued invite;
• existing SSO identity;
• recovery or delegated caretaker evidence.

user-engine should store factor references, verification status, assurance level, expiry, source system, and evidence references. It should not perform the proofing itself unless a later adapter explicitly owns a local development mock.

Prepared Accounts And Rights

Prepared accounts allow NetKingdom to create pending user-account intent before the person registers. A prepared account can contain:

• expected factor match rules;
• tenant, group, family, realm, service, or asset scope;
• initial account state;
• role or hat templates;
• profile defaults;
• customer-journey steps;
• approval requirements;
• expiry and revocation rules.

When a registering user proves the required factors, user-engine can link the prepared account to the real user and convert prepared rights into explicit memberships, profile values, and onboarding tasks.

Hats, Roles, And Profiles

A "hat" is the active context a user chooses when entering NetKingdom or a service. Examples include family owner, child, tenant admin, employee, contractor, service operator, customer, vendor, or agent delegate.

In user-engine, hats should be represented through tenant-scoped memberships, role labels, profile layers, and application projections. A user may have many hats, but only a subset should be active in a given realm, service, or asset context.

Realms, Services, Assets, And ACLs

user-engine should efficiently manage identity-domain access facts for users and groups against realms, services, and assets. It should not become the final ACL enforcement engine. The recommended split is:

• user-engine owns user, group, membership, role, profile, and access-intent facts;
• authorization systems evaluate policy and ACLs from those facts;
• services enforce decisions at runtime;
• user-engine exports identity context and claims-enrichment projections for the active hat.

Target Flows

Self Registration

1. User opens the NetKingdom registration UI.
2. IAM verifies one or more required factors.
3. user-engine creates or resolves the canonical user and account.
4. user-engine links verified external identities and factor evidence.
5. user-engine evaluates prepared-account matches.
6. User accepts terms, chooses initial tenant or realm, and selects available hats.
7. user-engine emits audit and outbox events for downstream onboarding.
8. Services receive identity context and claims projections.

Prepared Account Claim

1. Admin, family owner, tenant admin, HR feed, service owner, or invite source prepares an account package.
2. The package declares required factor matches and planned roles/profiles.
3. User registers and proves the required factors.
4. user-engine links the preparation to the canonical user.
5. Prepared memberships, profile defaults, and onboarding tasks are activated.
6. Any sensitive or privileged role waits for approval if policy requires it.

Hat Selection

1. User signs in and sees available hats for the current tenant, realm, or service.
2. User selects an active hat.
3. user-engine returns identity_context and a claims-enrichment projection for that context.
4. IAM or a gateway issues service-facing claims.
5. Authorization and service runtimes evaluate ACLs and policy.

Welcome Protocols

1. Registration or prepared-account claim emits onboarding events.
2. Journey definitions map events to subsystem steps.
3. Welcome protocols send the user to profile completion, family setup, tenant selection, app tour, evidence collection, approval, or service activation.
4. Each subsystem reports completion, failure, or required manual follow-up.

UI Surface

The first UI should be functional, quiet, and workflow-oriented. It should support:

• registration start and resume;
• factor verification status;
• prepared-account claim review;
• terms and consent capture;
• role or hat selection;
• profile completion;
• welcome journey timeline;
• access request and pending approval status;
• administrator views for prepared accounts, invitations, groups, realms, service bindings, and onboarding diagnostics.

The UI should call stable service/application APIs. It should not embed IAM, authorization, proofing, or service-specific ACL logic in browser code.

Domain Additions Needed

The current domain already has users, accounts, tenant accounts, external identities, memberships, profiles, applications, catalogs, invitations, audit, outbox, and identity context. The registration vision needs additional concepts:

• RegistrationSession
• NetKingdomIdentity or public NetKingdom ID alias
• IdentityFactor
• FactorVerification
• PreparedAccount
• PreparedEntitlement
• Hat or active role context
• Realm
• ServiceArea
• AssetScope
• AccessProfile
• AccessIntent
• OnboardingJourney
• WelcomeProtocol
• OnboardingTask

These should be introduced incrementally through workplans rather than all at once.

Security And Governance

• Factor values must be minimized, normalized, and redacted in diagnostics.
• High-assurance factors such as eID should be represented by evidence references and assurance metadata, not raw proofing payloads.
• Prepared rights must expire, be revocable, and show who prepared them.
• Privileged hats require explicit evidence, approval, or policy/control references.
• Users should see why a prepared account or role is available before claiming it.
• Access to realms, services, and assets must fail closed when tenant, hat, or factor context is missing.
• All lifecycle transitions should be auditable and emit outbox events.

Recommended Workplans

As of 2026-06-15, USER-WP-0010, USER-WP-0011, USER-WP-0012, USER-WP-0013, and USER-WP-0014 are implemented as user-engine slices. The later security-conformance workplan remains recommended follow-on work.

Workplan	Title	Purpose
USER-WP-0010	Registration Identity And Factor Model	Add registration sessions, NetKingdom ID semantics, factor evidence, and verification adapter boundaries.
USER-WP-0011	Prepared Accounts And Entitlement Claims	Allow accounts, roles, profiles, and journeys to be prepared before registration and claimed after factor match.
USER-WP-0012	Hats, Realms, Services, Assets, And Access Profiles	Model active hats and access-control facts for users/groups across realms, services, and assets.
USER-WP-0013	Onboarding Journeys And Welcome Protocols	Orchestrate subsystem welcome flows from registration, invitation, and prepared-account events.
USER-WP-0014	Registration And Access Management UI	Build the optional UI/API surface for registration, factor status, prepared rights, hat selection, and admin setup.
USER-WP-0015	Registration Scenario And Security Conformance	Add end-to-end scenarios, threat-oriented negative tests, redaction checks, and adapter conformance for the full flow.

First Milestone

The first useful milestone should not be the full UI. It should be a headless registration facade and scenario tests:

Start registration -> verify email through adapter evidence -> create
NetKingdom user/account -> claim a prepared tenant role -> choose active hat ->
return identity_context and claims projection -> emit onboarding events.

After that is stable, a thin UI can use the same facade without inventing its own registration rules.