generated from coulomb/repo-seed
264 lines
11 KiB
Markdown
264 lines
11 KiB
Markdown
# 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
|
|
|
|
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:
|
|
|
|
```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.
|