Implement durable store contract and registration roadmap

2026-06-15 16:33:24 +02:00
parent 05596146c8
commit 2c94b40fc4
16 changed files with 1906 additions and 472 deletions
--- a/docs/netkingdom-registration-onboarding-vision.md
+++ b/docs/netkingdom-registration-onboarding-vision.md
@@ -0,0 +1,259 @@
+# 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:
+
+```text
+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
+
+| 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:
+
+```text
+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.