user-engine/workplans/USER-WP-0008-family-dataspace-onboarding.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-0008	workplan	Family Dataspace Onboarding	netkingdom	user-engine	finished	codex	netkingdom	high	8	2026-06-05	2026-06-05	USER-WP-0007	29a39dfe-2693-4336-8e74-29a61530e4a3

USER-WP-0008 - Family Dataspace Onboarding

Goal

Make user-engine convenient for a personal-family use case: represent a family as a NetKingdom identity-domain scope, onboard family members into that scope, register a personal dataspace as a protected application, and provide SSO-ready identity context and profile projections without exposing consumers to IAM, authorization, profile, catalog, audit, or evidence implementation details.

The intended consumer experience is:

Create a family space, invite members, assign family roles, bind a personal
dataspace application, and let NetKingdom SSO receive the claims/profile
context it needs.

Scope Direction

user-engine should orchestrate domain-facing setup and read models. It should not provision the NetKingdom tenant, issue credentials, own the identity provider, or become the protected dataspace runtime. The family scope is a tenant or tenant-backed organization reference owned by NetKingdom infrastructure; user-engine manages local users, accounts, identity links, memberships, profile values, application bindings, projections, audit, and canon-facing identity context for that scope.

Non-Goals

• Do not issue SSO tokens, sessions, passwords, passkeys, or MFA challenges.
• Do not provision the underlying NetKingdom tenant or organization authority.
• Do not become the personal dataspace storage/runtime implementation.
• Do not implement a production UI as part of the first onboarding slice.
• Do not hard-code family relationship policy into authorization decisions; export facts and consume NetKingdom authorization outcomes.
• Do not implement the durable Postgres store in this workplan.

Tasks

id: USER-WP-0008-T1
status: done
priority: high
state_hub_task_id: "0ce15e29-e1e2-4d22-be3c-8cc64e5472bf"

Define the family dataspace vocabulary and mapping. Cover family tenant, family/member scopes, owner, adult, child, guest, delegated caretaker, personal dataspace application, SSO claims enrichment, and identity-canon references. Mark which facts are owned by user-engine and which remain owned by NetKingdom IAM, tenant, policy, audit, or dataspace systems.

id: USER-WP-0008-T2
status: done
priority: high
state_hub_task_id: "bf477973-34af-4720-917c-675c4a18fecb"

Design and implement a headless onboarding facade that composes existing service operations into a convenient use-case API. The facade should accept a NetKingdom-provided family tenant reference, owner actor, dataspace application binding, initial member descriptors, role assignments, and profile defaults.

id: USER-WP-0008-T3
status: done
priority: high
state_hub_task_id: "07dfaa2f-1df2-4a52-984e-41fb1345c854"

Add member invitation and acceptance support. Cover pre-created users, tenant-account lifecycle, invitation status, identity-link acceptance, resend/revoke behavior, and audit/event records. Keep invitation tokens and identity proofing delegated to NetKingdom IAM or a dedicated invite adapter.

id: USER-WP-0008-T4
status: done
priority: high
state_hub_task_id: "4b4dccf3-926f-4d6a-8135-f5d8f46faa85"

Register the personal dataspace application through register_application, bind it to external SSO/protected-system identifiers, and publish a minimal profile catalog for dataspace-specific claims, preferences, and visibility rules.

id: USER-WP-0008-T5
status: done
priority: high
state_hub_task_id: "6032fbdb-2922-440a-9af7-041aa295528b"

Implement family membership templates and fact export. Support owner, adult, child, guest, and delegated roles as scoped memberships while preserving tenant boundaries and authorization-port decisions for privileged actions.

id: USER-WP-0008-T6
status: done
priority: medium
state_hub_task_id: "2ea5c3ac-5fec-49f6-9ea4-d0485756fc63"

Expose SSO-ready context for the personal dataspace. Use identity_context and claims-enrichment projections to provide subject, principal, account, family tenant, role/membership, profile, evidence, and explicit gap references to the NetKingdom SSO adapter.

id: USER-WP-0008-T7
status: done
priority: medium
state_hub_task_id: "9647ae26-1719-4836-8765-1240827c46d4"

Add lifecycle, audit, evidence, and outbox behavior for onboarding. Every family/member/application/profile mutation should produce correlated audit and outbox records, and privileged role grants should be traceable through evidence or explicit evidence-gap references.

id: USER-WP-0008-T8
status: done
priority: medium
state_hub_task_id: "74a12383-eb13-4a79-b1b1-1810bd5334dd"

Add scenario tests and examples for the complete family dataspace flow. Cover owner setup, member invitation, accepted SSO identity link, child/guest membership, dataspace claims enrichment, tenant isolation, and denied cross-family access.

Acceptance Criteria

• A consumer can onboard a family dataspace through one headless facade or a small number of purpose-built commands instead of manually sequencing low level service calls.
• The family scope is represented as a NetKingdom tenant or tenant-backed organization reference, not as a user-engine-owned organization authority.
• Family members have distinct users, accounts, tenant accounts, external identities, and scoped memberships.
• The personal dataspace is registered as an application with a binding to SSO/protected-system identifiers and a minimal catalog for dataspace profile values.
• NetKingdom SSO can consume claims-enrichment projection or identity-context output without knowing user-engine persistence details.
• Owner/adult/child/guest behavior is represented as membership facts and authorization context, not embedded as final policy decisions in user-engine.
• Audit, outbox, evidence references, and lifecycle gaps exist for onboarding and role changes.
• Scenario tests prove happy-path onboarding, SSO context generation, and tenant isolation.

Expected Outputs

• Family dataspace vocabulary and mapping notes.
• Headless onboarding facade or command contract.
• Invitation and member lifecycle model.
• Personal dataspace application/catalog example.
• Family membership templates and fact export behavior.
• Claims-enrichment and identity_context examples for SSO adapters.
• Scenario tests and documentation for the end-to-end use case.

Implementation Notes

Implemented on 2026-06-05:

• Added family-domain roles, invitation status, member specs, onboarding request, and invitation records.
• Added local invitation persistence to the isolated store boundary.
• Added UserEngineService.onboard_family_dataspace(...) as the headless onboarding facade.
• Added invite_family_member, resend_family_invitation, revoke_family_invitation, and accept_family_invitation.
• Registered the personal dataspace as an application with an SSO/protected system binding and a minimal dataspace profile catalog.
• Represented family roles as scoped memberships while preserving authorization-port decisions.
• Returned identity_context and CLAIMS_ENRICHMENT projection outputs for SSO adapters.
• Added audit/outbox events for high-level family onboarding and invitation lifecycle actions.
• Added docs/family-dataspace-onboarding.md, examples, contract updates, and scenario documentation.
• Added scenario tests for owner onboarding, member acceptance, resend/revoke, SSO identity linking, claims projection, and cross-family denial.

Verification:

make test
Ran 39 tests in 0.119s
OK