# Unlocking without the passphrase

Every account here is issued a recovery code at enrollment. It is generated on the client, it wraps the
identity bundle, the server stores that wrap, and both heads go to some trouble to make sure the user writes
it down — the phone raises `FLAG_SECURE` for that screen alone and refuses to let anybody click past it.

**Nothing can use it.** There is no code path in this product that opens a recovery wrap. This document is
the plan for the change that fixes that, and it is written to be picked up cold.

> **Status: planned. None of the six steps below is built.**
>
> | Step | State | Notes |
> | --- | --- | --- |
> | 1. The endpoint that serves the wrap | Not started | `GET /api/v1/me/recovery-wrap`, and deliberately not `/me` |
> | 2. `SessionOpener.UnlockWithRecoveryAsync` | Not started | The unwrap, then the path `UnlockAsync` already takes |
> | 3. Setting a new passphrase | Not started | `PUT /api/v1/me/wrap`. Delivers *change passphrase* as well |
> | 4. Both heads | Not started | A way in from the unlock screen, and a box for the code |
> | 5. The prose that becomes false | Not started | Three shipped claims disagree with each other today |
> | 6. `crypto.md`'s status note | Not started | "One of four ways" is one of two, and will be one of three |

## What is wrong

Walk the failure through, because it is worse than a missing feature.

Forget the passphrase and the identity bundle cannot be unwrapped. No bundle means no vault keys, and no
vault keys means every item in every vault is unreadable. Signing out and back in does not help: the server
hands back the same passphrase wrap. The device key would be the other door, and **sign-out withdraws it** —
which is the advice the unlock screen gives for exactly this situation. The recovery wrap sitting on the
server is the only thing left, and nothing opens it.

So the loss is total and permanent, and the thing built to prevent it is inert.

Meanwhile the product says three things about this, and they do not agree with one another:

| What it says | Where | True today |
| --- | --- | --- |
| "The code is the only thing standing between a forgotten passphrase and an unrecoverable vault" | `docs/manual-checks.md` §10.2 | **No.** It stands between nothing |
| "losing it *along with* the passphrase means the vault is unrecoverable" | `docs/android-port.md`, state 4 | **No.** It implies the code alone is enough |
| "Signing out … is the only answer to a forgotten passphrase — nothing can recover one" | `README.md`, Locking | Yes, and it contradicts both of the above |

The third is the honest one. That is the state this plan changes, and until it does, the first two are the
two sentences in this repository most likely to cost somebody their keychain.

## What already exists

More than half of it, which is why this is worth doing now rather than treating as a feature.

- **The code.** `ClientEnrollment.GenerateRecoveryCode` — 160 bits, base32 over a 32-character alphabet with
  `I`, `L`, `O` and `U` left out so a transcription cannot land on a different valid code, printed as
  32 characters in groups of five.
- **The wrap.** The same class derives `KEK_rc` under `Argon2Profile.RandomSecret` (64 MiB, 3 passes) and
  sends `RecoveryWrappedPrivateKey` and `RecoveryKdfParameters` with the enrollment.
- **The row.** `EnrollmentService` stores it as `UserKeyWrapKind.Recovery`, beside the passphrase and device
  wraps.
- **The specification.** `docs/crypto.md` §2 gives the parameters for `KEK_rc` and §3 puts the wrap in the
  key hierarchy beside the passphrase and device ones. Nothing below needs a spec change.
- **The cache.** `LocalCacheKey` derives from the identity bundle under `dsh1/localcache/v2`, not from `MK`
  — see the changed-2026-07-30 note in `crypto.md` §3.2. That change was made partly *for* this: a recovery
  unlock derives a different `MK` and would otherwise open the identity and then fail to read the cache it
  had itself written. It is already paid for and currently untested from this direction.

## What is missing, exactly

| | Gap | Where it lands |
| --- | --- | --- |
| A | Nothing serves the wrap. `MeResponse` carries `WrappedPrivateKey` and `KdfParameters` — the passphrase pair, and only that | `DodoSSH.Contracts`, `Api/Features/Identity` |
| B | No unlock path. `SessionOpener` has `UnlockAsync` and `UnlockWithDeviceAsync`, and nothing else | `Client.Session` |
| C | No way to set a new passphrase afterwards. No endpoint, no client path, no UI | server + client |
| D | No way in from either unlock screen | `UnlockCard.axaml`, Android `LockedScreen.axaml` |

The device wrap is not a precedent for A: it is cached locally in `StoredUnlockMaterial` at the moment it is
registered, so it never has to be fetched.

## The decisions, and the reasons

**A separate endpoint, not `/me`.** `GET /api/v1/me/recovery-wrap`, called only when somebody has said they
have forgotten their passphrase. `/me` is fetched by every client at every launch, and putting the recovery
wrap in it would hand that blob to anybody holding a stolen OIDC session, permanently, for no benefit. The
wrap's real defence is Argon2id over 160 bits and it does not stop being safe in the response — this is the
cheaper rule of not serving what nothing needs. It answers 404 for an account with no recovery row, which is
every account enrolled by a client that did not send one.

**Online only, and the screen says so.** The wrap is deliberately *not* added to `StoredUnlockMaterial`.
Caching it would put a second door on every laptop, protected by a weaker KDF profile than the passphrase
one, for a case that already requires a network — recovery begins with signing in.

**Setting a new passphrase is part of the flow, not a follow-up.** Without it the account unlocks with a
one-time code forever, and the code is a thing people keep on paper. This is the same re-wrap a *change
passphrase* feature needs, so step 3 delivers both; change-passphrase is then a button, not a project.

**The identity key is not rotated.** Rotating it would invalidate every vault key grant the account holds
and force a rekey of every vault it can read — see [ADR 0010](adr/0010-vault-key-rotation.md) for what one
of those costs, and it is per vault. Nothing about the bundle is compromised by its owner proving possession
of it, so there is nothing to rotate away from. Identity key rotation is M5 and stays there.

**The recovery code is not re-issued after use.** Issuing a new one means asking somebody to write down a
new code at the exact moment they have demonstrated they lose things, and the old code is not weakened by
having been typed. "Issue a new recovery code" is a separate feature with its own screen, and it is the
right place for that question.

**Rate limiting is wanted here and is not a blocker.** This is the first endpoint in the product with a
guessable secret behind it, and `docs/platform-flags.md` records that rate limiting is unimplemented (M2).
Argon2id at 64 MiB is the cost that matters — a guessing attack pays it per attempt — so this ships without
and the endpoint is the reason to do the M2 item next.

## The work, in order

Each step compiles with the whole suite green before the next begins.

1. **The endpoint.** `GET /api/v1/me/recovery-wrap`, returning the wrap and its `KdfParameters`, or 404. A
   contract type, an entry in `PublicAPI.Unshipped.txt`, and a `SyncEndpointTests`-style refusal test for an
   account without one.
2. **The unlock.** `SessionOpener.UnlockWithRecoveryAsync(string code)`: canonicalise the code, derive
   `KEK_rc` from the served parameters, unwrap the bundle, and then join the path `UnlockAsync` already
   takes from the moment it holds one. Nothing after the unwrap should be new code — if it is, the two
   unlocks have diverged and one of them is wrong.
3. **The re-wrap.** `PUT /api/v1/me/wrap` taking a new passphrase wrap and its parameters, and the client
   half that derives the new `KEK_pp` and calls it. Forced as the last step of a recovery: the session is
   open, so refusing to go further until a passphrase is set costs nothing and is the only moment the user
   is certainly present.
4. **Both heads.** A "forgotten your passphrase?" route from `UnlockCard` and from Android's
   `LockedScreen`, a box that accepts the code as printed, and the new-passphrase form after it. The phone's
   version has to survive the keyboard covering the box — `docs/manual-checks.md` §10.3 lists the five boxes
   that already do, and this is a sixth.
5. **The prose.** Below.
6. **`crypto.md`.** A status note, not a spec change — see the last section.

## Traps already known

**◆ The code is derived from the string exactly as displayed, dashes included.** `GenerateRecoveryCode`
says so where it builds the groups: the separators are not decoration to be stripped before hashing, they
are part of the input. So step 2 must *canonicalise to the printed form* rather than normalise it away —
up-case, then re-group in fives — and it must not simply strip dashes and hash what is left. Getting this
wrong produces a code that verifies nowhere and an error message that says the code is wrong.

**The alphabet has holes in it.** `I`, `L`, `O` and `U` are not in it. A user who writes `O` for `0` should
be met with a code that works, so the canonicaliser should fold the four missing letters onto their
look-alikes before deriving. That is a deliberate leniency and belongs beside the alphabet's own comment.

**The two KDF profiles are not the same, and the stored parameters are what to use.** The passphrase wrap is
`PassphraseDefault` (256 MiB, 4 passes) and the recovery wrap is `RandomSecret` (64 MiB, 3), which is
correct — 160 random bits do not need the same stretching as a chosen phrase. Derive from the parameters the
server served with the wrap, never from a profile constant, or an account enrolled by a client with
different settings will refuse a valid code.

**The cache property is untested from this direction.** A recovery unlock derives a different `MK` and must
still read a cache written under a passphrase unlock. That works today because `LocalCacheKey` hangs off the
bundle, and no test asserts it, because nothing could reach the state. Assert it in step 2 rather than
trusting the note in `crypto.md`.

**Sign-out is the neighbouring path and must stay reachable.** The unlock screen offers signing out as the
answer to a forgotten passphrase. It stays: recovery needs the code, and somebody without it still needs a
way to hand a laptop on. What changes is that it stops being the *only* answer, so the copy on both screens
has to place them beside each other rather than replacing one with the other.

## Tests

- Round trip: enrol, recover, unlock, set a new passphrase, unlock again with it.
- The old passphrase stops working after step 3, and the recovery code still does.
- A wrong code is refused without disclosing whether the account has a recovery wrap at all.
- The cache written under a passphrase unlock is readable after a recovery unlock — the `localcache/v2`
  property, asserted rather than assumed.
- An account with no recovery row: the endpoint 404s and the screen says the code was never issued rather
  than that it is wrong.
- One `SystemTests` pass against the real API, because this is a two-endpoint flow and that suite is the one
  that consumes the artefacts that ship.
- Mutations to confirm each test can fail: reverse the canonicalisation so dashes are stripped; derive from
  `Argon2Profile.RandomSecret` instead of from the served parameters; and skip the forced re-wrap in step 3.

## Prose that becomes false

Not a tidy-up. Each of these currently tells a user something that this change makes wrong in the other
direction, and two of them are wrong right now.

- `docs/manual-checks.md` §10.2 — "the only thing standing between a forgotten passphrase and an
  unrecoverable vault". True once this ships, false today. It also needs a new check: typing a code from
  paper, which is the one part of this no test can perform.
- `docs/android-port.md`, state 4 — "losing it along with the passphrase means the vault is unrecoverable".
- `README.md`, Locking — "Signing out … is the only answer to a forgotten passphrase — nothing can recover
  one." Correct today and the sentence this change exists to falsify.
- `docs/design-import-gaps.md`, Preferences — "a forgotten passphrase — which is unrecoverable by
  construction, so the unlock screen would otherwise be a dead end", which is the stated justification for
  signing out being on that screen. The justification survives; the parenthesis does not.
- Both unlock screens, wherever they name signing out as the answer.

## The spec's "four ways"

`docs/crypto.md` §3.2 says a passphrase is "only one of four ways to open a vault" — passphrase, device,
recovery and escrow. Two exist. This change makes it three; escrow is M5 by decision and has an enum member
and nothing else.

**Do not edit that sentence.** It is normative and it is about the DSH1 format, where four ways is exactly
right. What is missing is a statement about *this build*, so add a short table under §3.2 saying which wrap
kinds this client can create and which it can open, and update it here rather than in the frozen prose. Land
it in the same commit as step 2, so the two can never disagree again.
