normogen/docs/adr/multi-person-sharing.md

ADR: Multi-Person Sharing Under Zero-Knowledge

Status: Decided (not yet implemented) Date: 2026-07-18 Discussion: issue #3 Related: zero-knowledge-encryption.md (the single-user ZK model this extends)

Records the design decision and its rationale ahead of implementation, following the pattern of zero-knowledge-encryption.md. The five original open questions were resolved on 2026-07-18 (see "Open questions" section). Two deferred items remain (pubkey verification mechanism; admin re-key quorum) — neither blocks implementation. All crypto primitives named here are available in the browser's Web Crypto API.

---

Context

Normogen's core product vision (see docs/product/PERSONA_AND_FAMILY_MANAGEMENT.md) is multi-person health data: a parent manages a child's medications and shares them with a spouse or caregiver. The existing zero-knowledge model (zero-knowledge-encryption.md) is single-user: all of a user's data is encrypted under one DEK that only that user can unwrap. There is no mechanism for a second user to decrypt any of it. As called out in issue #3, the current Share model + /api/shares routes store ACL-style permission records but cannot grant decryption access to another account — every medication blob is under the owner's DEK, and the recipient has a different one.

The product requirements that constrain this design (confirmed in issue #3):

1. Parents and spouses have separate logins, and may belong to different families. Divorced parents with their own families must be able to share the profile of their common child and nothing else.
2. Recipients always have Normogen accounts. (One-way document dumps to non-accounts — e.g. a physician via an encrypted PDF — is a separate, simpler feature, out of scope here.)
3. Revocation is a hard requirement. Cutting off a caregiver must take effect.
4. The server operator is fully untrusted. Key exchange cannot rely on the server brokering symmetric secrets.

Additional use cases from issue #3 that the model must accommodate:

• Profile graduation. A child profile eventually becomes an independent user with their own login, who may then revoke the parents' access.
• Pets. A profile may be an animal (medications, labs, etc.), not a human.

Decision

Implement per-profile DEKs with an X25519 asymmetric envelope for sharing, keeping the server a fully blind store. Concretely:

1. Key hierarchy

password KEK ──wraps──▶ account DEK ──wraps each──▶ profile DEK ──encrypts──▶ profile data
                  │                              (one per profile)
                  └──also wraps──▶ account X25519 private key
                                     (account X25519 public key stored plaintext)

• Account DEK: random AES-256-GCM key, wrapped under the password KEK (unchanged from today). At login the client unwraps it and holds it in memory.
• Profile DEK: a new random AES-256-GCM key per profile. All data belonging to a profile (its medications, appointments, etc.) is encrypted under the profile DEK, not the account DEK. Each profile DEK is wrapped under the account DEK and stored on the server, indexed by profileId.
• Account X25519 keypair: generated at registration. The private half is wrapped under the account DEK (so it unlocks at login); the public half is stored in plaintext — public keys are not secret.

This adds one tier to today's flat account DEK → data. Rationale in Consequences (§3-tier vs flat).

2. Ownership and access

• Each profile has exactly one owning account at a time. The owner holds the profile DEK wrapped to their account DEK (the owner share).
• Shared access = the profile DEK wrapped to another account's X25519 public key. Stored on the server as a recipient share, indexed by (profileId, recipientUserId).
• To read a shared profile, the recipient's client (at login) unwraps their X25519 private key, ECDH-derives a wrapping key against the share's ephemeral public key, and unwraps the profile DEK.

This is the standard asymmetric-envelope pattern (cf. Signal, age, Tarsnap). The server only ever stores wrapped blobs and public keys.

3. Sharing flow (owner → recipient)

Client-side only, server untrusted:

1. Owner's client looks up the recipient's X25519 public key (GET /api/users/:id/public-key, new).
2. Owner's client unwraps the target profile's DEK (via their account DEK).
3. Generate an ephemeral X25519 keypair for this share.
4. ECDH(ephemeral priv, recipient pub) → AES-GCM wrapping key.
5. Wrap the profile DEK under that wrapping key → {ciphertext, iv, ephemeralPubKey}.
6. POST /api/profiles/:id/shares with {recipientUserId, wrappedDek, ephemeralPubKey, permissions, expiresAt?}.
7. Server stores the share record. It cannot decrypt it.

4. Revocation

Two layers, in order of strength:

• Soft revoke (cheap): delete or deactivate the recipient share record. The recipient's client no longer receives the wrapped DEK from the server, so it cannot decrypt new reads. Caveat: a malicious client that cached the profile DEK before revocation keeps decrypting data it already fetched.
• Hard revoke / re-key (strong): owner generates a new profile DEK, re-encrypts all of the profile's data under it, re-wraps to the owner share and to all still-valid recipient shares. A revoked recipient's cached old DEK now fails to decrypt any future fetch. Required for the "kid revokes parent" graduation case where you must assume the parent may have cached data.

Hard revocation is the answer to requirement (3). Re-keying is expensive (linear in profile data size) so it is opt-in / triggered explicitly, not the default for every revoke.

5. Profile model changes

To support pets and graduation, the current role: "patient" string becomes:

kind: "human" | "pet"          // distinguishes people from animals
relationship: string           // freeform: "self", "child", "spouse", "pet", ...

Ownership-transfer (graduation) is not new crypto — it is the existing share machinery plus an owner_account_id field swap:

1. New adult account (the graduated child) generates its X25519 keypair.
2. Old owner wraps the profile DEK to the new account's pubkey as a share, and marks that share as the new owner share.
3. Old owner's access is downgraded to (or removed as) a normal recipient share.
4. The new owner can revoke any remaining parent shares via soft/hard revoke.

5b. Use case: elderly parent cared for by children

A key motivation for the profile/account split is that profile ownership and account login are independent. The elderly-care scenario has three setups, all covered:

• Parent self-manages, shares to children. Parent owns their own account and self profile; creates recipient shares to each child. Standard share-to-another-account flow. Any party can revoke.
• Managing child holds a dedicated parent account. A separate account exists for the parent (the identity of record), but the managing child holds or controls the password and shares the profile to siblings. Cleaner than embedding the parent as a profile inside the child's account, and preserves the "take over later" path: if the parent becomes able (or, conversely, passes away), it's the same ownership machinery.
• Parent modeled as a profile inside the managing child's account. No separate login for the parent; the child owns the profile and shares it. Simplest, but the parent has no independent identity and cannot revoke themselves. Recommend against this when the parent is or may become an independent actor.

Death/incapacity of the sole-account owner is the one wrinkle that needs an explicit decision: see "Permissions and the admin-share question" below.

5c. Permissions and the admin-share question

The permissions list on a recipient share (Open question 3) raises a sub-decision: does an admin permission let a recipient act as a quasi-owner without the original owner? Specifically: re-share the profile, re-key it (hard revoke), and add/remove other shares.

This matters for two scenarios:

• Graduation in reverse / death of the owner. If the parent owns the account and becomes incapacitated, no child can write, re-share, or revoke — those require the owner's account DEK, which is gone with the password.
• Operational delegation. A primary caregiver wants to delegate admin tasks without sharing their password.

Decision: support an admin permission tier. An admin share can re-share, re-key, and manage other shares on a profile. This keeps the owner-DEK model intact (the owner share is still special — it can transfer ownership, which admin cannot) while handling the death/incapacity and delegation cases without key escrow. Hard revocation (re-key) by an admin rotates the profile DEK and re-wraps to all still-valid shares, same as owner-initiated re-key.

❓ Open sub-item: when an admin re-keys, do we require a quorum or a second admin's consent? For MVP, no — any admin can act alone, matching how ownership transfer works today. Revisit if multi-party control becomes a requirement.

6. What happens to the current Share model

The existing backend/src/models/share.rs is resource-level ACL (resource_type, resource_id, permissions) and predates encryption. It is incompatible with this design, which shares at the profile level via keys, not at the resource level via permissions.

Per issue #3, profile-level sharing covers the family/caregiver need; the "share one document" need is handled separately (physician PDF feature). So:

• The current Share model and /api/shares routes are retained for now but treated as a placeholder (issue #3). They will be either removed or repurposed; this ADR does not depend on them.
• The new recipient-share records live in a new collection (provisional name profile_shares) keyed by (profileId, recipientUserId). Storing wrapped DEKs, not ACLs.

7. Server surface (new endpoints, indicative)

• GET /api/users/:id/public-key → recipient's X25519 public key (plaintext).
• GET /api/profiles/me/dek → the account-wrapped profile DEK (owner unlock).
• POST /api/profiles → create profile: client generates profile DEK, wraps to account DEK, sends wrapped form. Returns profileId.
• GET /api/profiles/:id/shares → list recipient shares for a profile.
• POST /api/profiles/:id/shares → create a recipient share (wrapped DEK).
• DELETE /api/profiles/:id/shares/:shareId → soft revoke.
• POST /api/profiles/:id/rekey → hard revoke / rotate the profile DEK.

All endpoints store/return opaque blobs or public keys; none expose a DEK or a private key.

---

Consequences

Positive

• Satisfies all four product constraints. Per-profile keys enable the divorced-parents case; hard revoke enables the revocation requirement; the X25519 envelope keeps the server untrusted.
• Profiles become first-class subjects of care — owners, shares, pets, graduation all fall out naturally.
• Server stays a blind store. No new backend crypto; still no aes/crypto crates in Cargo.toml.
• Composition with existing recovery. The account DEK is still recovered via the existing password/recovery wrapped-DEK flow; profile DEKs are wrapped to the account DEK, so recovering the account recovers all profiles.

Negative / costs

• Adds a key tier. Three levels instead of one. Complexity in the client crypto module (crypto/keys.ts will grow X25519 + wrap-to-recipient logic).
• Migration. Today all data is under one account DEK. Splitting into per-profile DEKs requires reading, decrypting, re-encrypting, and re-uploading every document. There is no real user data yet (per zero-knowledge-encryption.md), so this is cheap now and expensive later — strong argument for doing the re-key before launch.
• Hard revocation is expensive. Re-keying a profile is O(profile data size). Mitigation: soft revoke by default, hard revoke only when the owner explicitly requires it (e.g. graduation, suspected compromise).
• Recipient must have an account (constraint 2). No magic-link sharing in this design — deferred to the physician-PDF feature.

Security notes

• Ephemeral keys per share prevent cross-share correlation and give forward secrecy within a share's lifetime (re-keying rotates the DEK).
• ECDH + AES-GCM is the Web Crypto idiom; X25519 keys are 32 bytes, shares are small.
• Public keys are not authenticated by the server. The owner must trust that GET /users/:id/public-key returns the right key. Since the server is untrusted, this is an accepted risk: a malicious server could swap the key and force a re-share, but cannot decrypt. ❓ Decide whether to add a key fingerprint the recipient verifies out-of-band.

Open questions (❓) — resolved 2026-07-18

1. Key hierarchy depth. ✅ Decided: 3-tier (account DEK → profile DEK → data). Rationale: account DEK is recovered via the existing wrapped-DEK recovery flow, so password change only re-wraps the account DEK (O(1)), not every profile DEK. Profile DEKs are re-wrapped only on profile-level events (share/revoke/rekey), which are rare.

2. Public-key trust. ✅ Decided: accept key-swap as DoS-only for now. A malicious server can swap a recipient's public key and force a failed share (DoS) but cannot decrypt. Future enhancement (not blocking): add a mechanism for out-of-band pubkey verification. Candidate approaches to evaluate when we get there:

   • Key fingerprint / safety number. Display a short hash of a user's pubkey that two parties can compare out-of-band (cf. Signal safety numbers). Cheap, requires user action.
   • Pubkey in recovery phrase / account export. Derive or include the pubkey fingerprint in something the user already verifies.
   • Web-of-trust / TOFU. First-seen pubkey is pinned client-side; a change triggers a user-visible warning. These are additive — none changes the core envelope design, so they can ship later without a migration.

3. Share record schema. ✅ Decided: profile_shares collection, schema as proposed, permissions included. Fields: {profileId, recipientUserId, ephemeralPubKey, wrappedDek, iv, permissions, expiresAt, active, createdAt}. permissions is a list (e.g. ["read"], ["read","write"], ["read","write","admin"]); the server enforces write/admin server-side by checking the share record (the owner always implicitly has admin via the owner share). See §"Permissions and the admin-share question" below for the semantics of admin.

4. Migration. ✅ Decided: no migration — wipe the database. There is no real user data, and the re-key cost is unjustified. Phase A therefore includes a clean-cutover step rather than a per-document migration. (This also removes any legacy single-DEK documents that would otherwise need special-casing.)

5. Existing Share model fate. ✅ Decided: remove entirely. backend/src/models/share.rs, the /api/shares routes, and the permissions/check endpoint are deleted; the new profile_shares collection and /api/profiles/:id/shares endpoints replace them. The future per-resource physician-share feature will be built from scratch on its own model when prioritized (it's a different access pattern — one-way document dump, not ongoing profile access).

Phasing (proposal)

• Phase A — key tiers without sharing. Introduce per-profile DEKs and the account X25519 keypair; migrate existing data; no sharing endpoints yet. Unblocks multi-profile-within-account (the parent/child single-login case).
• Phase B — profile sharing. The POST/GET/DELETE /profiles/:id/shares endpoints and soft revoke.
• Phase C — hard revoke / re-key. The /profiles/:id/rekey endpoint and owner-driven DEK rotation.
• Phase D — graduation / ownership transfer. Owner-share swap UI + endpoint.

Each phase is independently shippable and independently testable.

---

References

• Issue: #3
• Predecessor ADR: zero-knowledge-encryption.md
• Current client crypto: web/normogen-web/src/crypto/keys.ts, cipher.ts
• Profile model: backend/src/models/profile.rs
• (Incompatible) current share model: backend/src/models/share.rs
• Web Crypto API: X25519 via generateKey({name:"ECDH", namedCurve:"X25519"}), deriveBits for ECDH, wrapKey/unwrapKey or manual AES-GCM for the envelope.