[Feature Request] Opt-in account recovery (social recovery / key escrow) — design doc for review

Hi Code PDX 👋 — this comes from Shelter Now, the Portland nonprofit lined up to run alpha testing of PASS with 10–20 unhoused testers (participants are paid stipends). Our Lived Experience Council and Village Federation groups reviewed the document-locker concept, and their clearest, most urgent ask was: "what happens when I forget my password or lose my phone?" — because today the honest answer is "your documents are gone."

Below is a draft design doc for an opt-in account recovery layer. Nothing here weakens the default posture — a user who doesn't opt in keeps exactly today's behavior. We'd love maintainer feedback before anyone writes code; Shelter Now will run paid lived-experience review sessions on whatever design direction the maintainers prefer, and we're happy to discuss on Discord or at a meetup too. (Full disclosure: drafting was AI-assisted; the requirements come from the lived-experience sessions and the repo was read closely — file references below are to Development.)

Two sibling asks from the same sessions will follow as separate issues once this one has a direction: encrypted storage of passwords/critical info, and an opt-in self-assessment → service-navigation flow.

---

PASS Design Doc — Feature 1: Opt-in Account Recovery

Status: DRAFT for Code PDX + lived-experience review · Date: 2026-07-16
Origin: Shelter Now Lived Experience Council + Village Federation feedback sessions
Audience: Code PDX maintainers, Shelter Now program staff, alpha testers

---

1. The problem, in plain language

If you forget your PASS password or lose your phone, your documents are gone.
For most apps that's an annoyance. For someone sleeping outside, losing a birth
certificate or immigration paper again — this time inside the app that promised
to keep it safe — is catastrophic and destroys trust in the whole program.

Today PASS delegates identity entirely to the Solid pod provider. Signup
creates a Community Solid Server v7 account with an email + password
(src/components/Signup/podSignupHelpers/registerPod.js); login is standard
Solid OIDC (src/contexts/SessionContext.jsx). There is no recovery path in
PASS itself — a lost credential means the pod is unreachable — and the target
population often has no stable email for a provider-side reset either. A
repo-wide search finds no recovery, key-management, or crypto code; the closest
prior issue is #650 (password-mismatch UX at pod creation).

Goal: an opt-in recovery layer so that a person who loses their password
and/or device can get back into their documents with help from people/orgs they
chose in advance — without weakening the default posture for anyone who doesn't
opt in.

2. Who this is for (design constraints)

• Users on basic phones or borrowed devices; phone numbers and emails change often.
• Passwords are frequently forgotten or written down and lost.
• Many users are undocumented or fleeing abuse: a recovery path must never
  become a way for an abuser, or a subpoena-happy third party, to quietly gain access.
• Reading level ~6th grade; consent must be genuinely legible, not a wall of text.
• Old browsers/devices: recovery enrollment and use must work on low-end Android
  and shared library terminals (Web Crypto API is the ceiling; no native apps).
• Opt-in only. A user who declines keeps exactly today's behavior.

3. What "recovery" means in PASS's architecture

Two distinct things can be lost, and they need different mechanisms:

1. The login credential (pod-provider password). Recovering this restores
   access to the pod.
2. Any future encryption keys. Today PASS does not encrypt client-side
   (pods are protected by WebACL only), so #1 is the whole problem. But
   Feature 2 (encrypted credential storage) introduces a client-held key, and
   any recovery design must not paint that future work into a corner.

This doc therefore designs recovery around a recovery secret: today it can
reset/re-bind the pod credential; later the same enrollment can escrow a key-
encryption key for Feature 2 data. One consent moment, one mental model.

4. Candidate schemes

Scheme A — Single-org escrow (Shelter Now holds a recovery key)

At enrollment, the client generates a recovery secret and hands one encrypted
copy to a designated org (e.g., Shelter Now). Recovery = walk into the org,
prove who you are to a caseworker (photo, in-person recognition — this
population usually is personally known to staff), caseworker MFA-authorizes a
release, user resets their credential.

• Pros: simplest to build and to explain ("Shelter Now can help me get back
  in"). Matches how this population already recovers everything else (mail,
  benefits) — through a trusted org. Works with zero user-held artifacts.
• Cons: the org becomes a single point of compromise and a subpoena target;
  a malicious or coerced insider could act alone. Custodial liability
  concentrates on one nonprofit.
• What the user must understand: "Shelter Now can help you get back in.
  That also means Shelter Now could be forced to open your account. You can
  turn this off any time."

Scheme B — 2-of-3 Shamir split across separated parties (recommended)

The recovery secret is split with Shamir's Secret Sharing (audited
shamir-secret-sharing lib, GF(256)) into three shares:

• Share 1 — the user: printed QR card (wallet-size, laminated), or stored
  on-device for smartphone users.
• Share 2 — the deployment operator (e.g., PASS instance database).
• Share 3 — a second, organizationally separate trust domain (e.g., Shelter
  Now-administered vault service with capability-scoped release tokens —
  design pattern and reference implementation already exist from Shelter Now's
  locker work: separate project/account, PUT/GET/DELETE under distinct
  bearer material, release gated on caseworker MFA + an active time-boxed grant).

Any two shares reconstruct. Normal recovery paths:

• User has their card → card + operator share (org helps, but one org alone can't act).

• User lost everything → operator share + vault share, released only in a
  caseworker-MFA'd, audited, time-boxed session (this is named escrow — the
  two orgs together can act without the user, and the consent says so plainly).

• Pros: no single credential/insider/subpoena on one org yields the secret;
  degrades gracefully (lost card ≠ lockout); the same machinery later supports
  Feature 2's key escrow. Every release is written to an append-only, hash-
  chained audit log the user can view.

• Cons: most moving parts; requires two administratively separate parties
  (deployment operator + vault org) and an ops runbook; the honest claim is
  "the two orgs together could open this" — must be said out loud in consent.

• What the user must understand: "Three keys. You hold one. Two different
  organizations each hold one. Any two together can help you get back in.
  That means those two organizations acting together could also get in
  without you — every use is recorded, and you can see the record."

Scheme C — Social recovery (trusted contacts / guardians)

User designates 2–3 trusted people (friend, family member, caseworker as
peers); K-of-N of them approve a recovery request (Bitwarden Emergency
Access-style state machine: request → waiting period with veto → release).

• Pros: most decentralized; no org custody or liability; waiting-period +
  veto is a strong anti-coercion control.
• Cons: poor population fit as the only mechanism — trusted contacts in
  this community also lose phones/accounts, relationships churn, and an abuser
  is often inside the social graph. Guardians need working devices/accounts.
  Waiting periods conflict with urgent needs ("my housing appointment is today").
• Verdict: offer later as an additional guardian type inside Scheme B
  (a trusted person can hold Share 1 instead of a card), not as the base.

5. Comparison

	A: Single-org escrow	B: 2-of-3 Shamir (rec.)	C: Social recovery
Lost password + lost card/device	✅ recoverable	✅ recoverable (escrow path)	⚠️ only if guardians reachable
One compromised org/insider can act alone	❌ yes (fatal)	✅ no	✅ no
Subpoena resistance	❌ single target	⚠️ requires two orgs	✅ strong
Abuser-adjacent risk	low (org gatekeeps)	low (org gatekeeps + audit)	❌ high (abuser in graph)
Works with no user device/artifact	✅	✅	❌
Build + ops complexity	low	medium-high	medium
Custodial liability	concentrated	shared, gated, audited	minimal
Plain-language explainability	easiest	moderate (tested phrasing above)	moderate

Recommendation: Scheme B, with Scheme A as the degenerate deployment mode
(a small deployment may start with both non-user shares under one org — worse,
but honest if consent says so) and Scheme C folded in later as an alternate
Share-1 holder. Rationale: it is the only option that simultaneously survives
"user lost everything," resists single-org compromise/coercion, and reuses an
already-designed, reference-implemented pattern (Shelter Now escrow-vault
design: capability-scoped vault, MFA + grant-gated release, tamper-evident
audit, crypto-shred that purges all shares on account deletion).

6. Threat model (Scheme B)

Threat	Mitigation
Stolen/coerced staff account	One share only; release needs MFA + active grant; audit
Operator DB breach	Share 2 alone is useless
Vault credential breach	Share 3 alone is useless; release/delete tokens separated
Both orgs collude / legal compulsion of both	Accepted, named risk — disclosed in consent; audit trail; user can opt out or shred
Abuser impersonates user at front desk	In-person identity check by staff who know the client + MFA + logged; optional per-user "require my card" flag disables the no-card path
Lost card	Escrow path; card reissue (old Share 1 invalidated by re-split)
User wants out	Opt-out = shred Shares 2+3 (idempotent, fail-stop, audited); account returns to unrecoverable-by-design
Reconstruction leakage	Combine only in volatile browser memory; zeroize; never logged/sent

7. UX flow (plain language, to be tested with LEC/VF)

Enrollment (opt-in, at signup or any time):

1. "If you forget your password, do you want help getting back in?" [Yes / No, I understand no one can recover it]
2. Plain-language consent screen (target ≤6th grade, translated, read-aloud
   button): who holds what, what they can/can't do, that every use is recorded.
3. Print/save the card (Share 1). Skippable ("I can't keep a card safe") —
   consent then names the two-org escrow path explicitly.

Recovery:

1. User comes to a participating org. Staff verify identity (procedure doc, not code).
2. Caseworker (MFA) opens a recovery session; grant is time-boxed.
3. Card path: scan card + operator share → reset. No-card path: operator +
   vault shares → reset. Either way the user sets a new password on the spot
   and gets a new card; the event appears in their visible history.

8. Custodial liability (for org review before build)

• Written custodianship agreement between deployment operator and vault org:
  release procedure, identity-verification standard, breach notification,
  subpoena/warrant handling (notify user unless legally barred), insurance.
• Data minimization: vault stores share bytes + opaque person ID only — no
  names, no documents.
• Retention: shares deleted on opt-out, account deletion, or N months of
  program inactivity (policy TBD with counsel).
• This section needs review by Shelter Now counsel and Code PDX before any code merges.

9. Interaction with Features 2 & 3

• Feature 2 (encrypted credentials store): recovered account ⇒ recovered
  passwords. This is intentional and must be named in consent ("people who
  help you recover could, together, reach your saved passwords too"). Optionally
  Feature 2 supports a per-item "extra lock" excluded from recovery.
• Feature 3 (assessment): no interaction; assessment data lives outside the
  recovery secret's scope and is separately deletable.

10. Prototype plan (after design review)

1. src/utils/recovery/ module: split/reconstruct via the audited
   shamir-secret-sharing package, QR card render (reuse react-qr-code +
   the existing QR pattern from src/components/Profile/CreateQRCode.jsx),
   zeroization tests. Plain JS + JSDoc to match the codebase (no TS migration).
2. Enrollment UI + consent capture behind a VITE_ENABLE_RECOVERY env flag
   (matching the existing env.template config style), components under
   src/components/Recovery/ with desktop/mobile split and Vitest +
   Testing Library behavior tests, per repo conventions.
3. Reference vault with capability-scoped endpoints (adapted from Shelter Now's
   vaultClient.ts interface contract) — in-memory for the prototype.
4. Caseworker recovery session demo on the dev CSS instance.
5. Lived-experience testing script: can testers correctly answer "who can get
   into your account?" after enrollment. That comprehension test is the merge gate.

11. Open questions for Code PDX

1. Where should credential re-binding live? PASS already drives the CSS v7
   account JSON API (registerPod.js uses password.create /
   password.login controls); the same API surface can support a
   recovery-gated password reset on CSS deployments. External OIDC providers
   (opencommons.net, inrupt.com, …) can't participate — is recovery a
   CSS-deployment-only feature at first? (We think yes.)
2. Is a small companion service (the Share-3 vault) acceptable alongside the
   CSS instance in compose.yaml, or should Share 3 live in a second Solid
   pod controlled by a different org?
3. Should the recovery secret double as the future key-encryption key if PASS
   adds client-side encryption (see issue #259's verifiable-credentials
   direction and the sharing-model issues #705/#342)? We designed for that but
   want maintainer input.
4. Does Code PDX prefer this iterated as a GitHub issue thread, a Discussion,
   or an RFC doc under docs/? We're also happy to bring it to the Discord /
   a Code PDX meetup — Shelter Now can coordinate paid lived-experience
   testing sessions for whatever design lands.

Start by reading src/components/Signup/podSignupHelpers/registerPod.js and src/contexts/SessionContext.jsx to understand current signup and Solid OIDC login, then review the proposed recovery schemes and their operational constraints. Done means maintainers and the named stakeholders agree on a recovery design and scope before implementation begins.