---
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
```