generated from coulomb/repo-seed
tegwick
9c6ad74f6b
- Align agent files with on-disk workplan prefixes (infer from workplan ids) - Set workplan domain to registered domain_slug; add topic_slug where applicable - Repair frontmatter delimiter formatting; migrate legacy task status literals - Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
218 lines
7.7 KiB
Markdown
218 lines
7.7 KiB
Markdown
---
|
|
id: USER-WP-0008
|
|
type: workplan
|
|
title: "Family Dataspace Onboarding"
|
|
domain: communication
|
|
repo: user-engine
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: netkingdom
|
|
planning_priority: high
|
|
planning_order: 8
|
|
created: "2026-06-05"
|
|
updated: "2026-06-05"
|
|
depends_on:
|
|
- USER-WP-0007
|
|
state_hub_workstream_id: "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:
|
|
|
|
```text
|
|
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
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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:
|
|
|
|
```text
|
|
make test
|
|
Ran 39 tests in 0.119s
|
|
OK
|
|
```
|