generated from coulomb/repo-seed
Implement durable store contract and registration roadmap
This commit is contained in:
@@ -89,6 +89,24 @@ without emitting outbox events.
|
||||
Local audit records may be exported as identity-canon `Evidence Source`
|
||||
references. Durable platform audit custody remains outside user-engine.
|
||||
|
||||
## Durable Store Contract
|
||||
|
||||
`UserEngineService` depends on the `UserEngineStore` protocol, not the
|
||||
in-memory adapter's concrete collections. Store implementations must expose
|
||||
schema readiness, logical record accessors, audit-log reads, pending-outbox
|
||||
reads, adapter-neutral record counts, and a `transaction` context for atomic
|
||||
mutations.
|
||||
|
||||
Mutating writes happen after validation and authorization, inside the store
|
||||
transaction. Domain changes, local mutation audit records, and outbox events
|
||||
must commit or roll back together. Authorization-denial audit records must
|
||||
remain durable without outbox events, including when a denial occurs inside a
|
||||
composed mutation that rolls back other writes.
|
||||
|
||||
Postgres-specific connection handling, SQL, locks, credentials, tenant
|
||||
isolation primitives, backup, restore, and platform observability remain
|
||||
adapter or provider concerns outside the domain service.
|
||||
|
||||
## Migration Contract
|
||||
|
||||
The isolated store exposes `SCHEMA_VERSION = 0001_initial` and a `migrate`
|
||||
|
||||
259
docs/netkingdom-registration-onboarding-vision.md
Normal file
259
docs/netkingdom-registration-onboarding-vision.md
Normal file
@@ -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.
|
||||
@@ -1,7 +1,7 @@
|
||||
# Postgres Durable Store Consumer Requirements
|
||||
|
||||
Status: requirements
|
||||
Date: 2026-06-05
|
||||
Status: requirements + store contract boundary
|
||||
Date: 2026-06-15
|
||||
Related workplan: USER-WP-0009
|
||||
|
||||
## Purpose
|
||||
@@ -13,6 +13,12 @@ NetKingdom infrastructure repository provides a tenant-aware, security
|
||||
integrated Postgres capability, and `user-engine` consumes that capability
|
||||
through a durable store adapter.
|
||||
|
||||
The consumer-side contract is now represented in code by
|
||||
`user_engine.ports.UserEngineStore`. The protocol is intentionally
|
||||
adapter-neutral: it names the service behavior a durable store must satisfy
|
||||
without adding a Postgres dependency or giving this repository ownership of
|
||||
database provisioning.
|
||||
|
||||
## Consumer Story
|
||||
|
||||
As a `user-engine` consumer, I want the service to persist identity-domain
|
||||
@@ -85,6 +91,22 @@ the isolated store:
|
||||
- Support the same service-level exceptions for not found, conflict,
|
||||
validation, and authorization-denied flows.
|
||||
|
||||
### Store Protocol Boundary
|
||||
|
||||
`UserEngineService` consumes the `UserEngineStore` protocol rather than local
|
||||
in-memory collections. A future Postgres adapter must provide:
|
||||
|
||||
- Schema readiness through `schema_version`, `ready`, and `migrate`.
|
||||
- A `transaction` context that makes each mutating write unit atomic.
|
||||
- Logical read/write methods for users, accounts, tenant accounts, external
|
||||
identities, memberships, applications, bindings, catalogs, family
|
||||
invitations, and profile values.
|
||||
- Audit and outbox append/read methods that preserve write order.
|
||||
- Adapter-neutral record counts for diagnostics and operability snapshots.
|
||||
|
||||
Concrete tables, SQL, connection pools, and row locks remain adapter details.
|
||||
Service and domain code should not depend on Postgres-specific concepts.
|
||||
|
||||
### Identity And Account Constraints
|
||||
|
||||
- `(issuer, subject)` must uniquely identify one external identity link.
|
||||
@@ -157,6 +179,9 @@ the isolated store:
|
||||
them to `ConflictError` where appropriate.
|
||||
- Migration and outbox claiming should use explicit locking strategies that do
|
||||
not require consumers to understand Postgres internals.
|
||||
- Authorization-denial audit records must persist without outbox events even
|
||||
when the denied operation occurs inside a composed transaction that rolls
|
||||
back domain writes.
|
||||
|
||||
### Migration Requirements
|
||||
|
||||
@@ -253,10 +278,16 @@ A future Postgres adapter should pass conformance tests for:
|
||||
|
||||
## First Implementation Follow-Ups
|
||||
|
||||
After this requirements work is accepted, likely follow-up work should be:
|
||||
The first consumer-side follow-up is complete: `UserEngineStore` defines the
|
||||
adapter boundary and the in-memory store acts as the reference implementation
|
||||
for service-level behavior.
|
||||
|
||||
Likely future follow-up work should be:
|
||||
|
||||
- Define the durable store protocol changes, if any.
|
||||
- Add a Postgres adapter behind the existing store boundary.
|
||||
- Add migration files for user-engine tables.
|
||||
- Add provider-backed conformance tests for locking, uniqueness races,
|
||||
migration readiness, outbox claiming, redacted diagnostics, and restore
|
||||
validation.
|
||||
- Add conformance tests that run against both in-memory and Postgres stores.
|
||||
- Integrate the adapter with the future NetKingdom Postgres provider repo.
|
||||
|
||||
Reference in New Issue
Block a user