Public Access

Files

T

jaap-jan 6185d74800 Write down the two things a user is promised and does not get

Two plans, both for the same class of defect: a control or a code that a user is told to rely on, backed by
storage and by nothing else. Neither is started; what follows is the reasoning, so that starting is not
where it gets thought about.

── UNLOCKING WITHOUT THE PASSPHRASE ─────────────────────────────────────────────────────────────────────
Every account is issued a recovery code at enrollment. The client generates it, wraps the identity bundle
under KEK_rc, the server stores that wrap as UserKeyWrapKind.Recovery, and both heads work to make sure the
user writes it down — the phone raises FLAG_SECURE for that screen alone and will not let anybody past it.
Nothing can use it. SessionOpener has UnlockAsync and UnlockWithDeviceAsync, and there is no third.

Walk the failure through: forget the passphrase, and the bundle cannot be unwrapped, so no vault key opens
and every item is unreadable. Signing out and back in returns 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 loss is total and permanent, and the thing built to prevent it is inert.

The docs already disagree with each other about this, which is how it surfaced. manual-checks §10.2 calls
the code "the only thing standing between a forgotten passphrase and an unrecoverable vault"; android-port
says losing it *along with* the passphrase is what makes a vault unrecoverable; README says signing out is
the only answer and nothing can recover one. The third is the true one today.

More than half the work is already done and one piece of it was done on purpose: LocalCacheKey derives from
the identity bundle rather than from MK — crypto.md §3.2, changed 2026-07-30 — specifically so an unlock
that never computes MK can still read the cache it wrote. What is missing is an endpoint to serve the wrap,
an unlock path, and a way to set a new passphrase afterwards, without which the account unlocks with a
one-time code forever. That last step is the same re-wrap a change-passphrase feature needs, so it delivers
both.

Two traps are recorded because both would produce a code that verifies nowhere. The derivation uses the
displayed string *including its dashes*, so the unlock must canonicalise to the printed form rather than
strip it; and the recovery wrap uses a different Argon2 profile to the passphrase one (64 MiB against 256),
so it must derive from the parameters served with the wrap rather than from a profile constant.

── REACHING A HOST YOU CANNOT DIAL ──────────────────────────────────────────────────────────────────────
This started as "delete the dead jump-host field" and inverted twice.

HostSecret.JumpHostIds is stored, validated, encoded and three-way merged, and nothing reads it or writes
it — the ssh_config importer looks like the writer and is not; it records ProxyJump as an option and a note
saying DodoSSH cannot honour it. The first draft recommended deleting it. That was wrong twice over. ADR
0004's last consequence had already designed the implementation — a loopback TCP bridge for the relay, and
"the same bridge provides ProxyJump via a SOCKS5 dynamic forward", one mechanism and two features — which
the pinned SSH.NET 2025.1.0 supports through ForwardedPortDynamic and ProxyTypes.Socks5, checked in
Renci.SshNet.xml rather than remembered. And the stored shape is right: an ordered list of host ids is what
a chain is, the merge arm is correct, and the missing schema version is a line to add.

◆ Looking properly found the same shape one field over, where it costs something. RelayEnabled is also
stored, merged and never read by the connect path — but it is user-settable, and both heads draw a checkbox
promising it. Ticking it moves the host's address and port out of the encrypted payload into plaintext
columns, which ADR 0004 calls the single deliberate concession in the design, and then the client dials
directly anyway. The privacy is spent and the feature is not delivered. That is a defect rather than a gap,
and it is step 0.

The comparison the plan turns on: the relay reaches what the *deployment* can reach and the jump host
reaches what a *machine in the keychain* can reach, so they are not substitutes. On a self-hosted box
outside the target's network the relay reaches nothing the laptop could not. And the privacy ordering is
the opposite way round from the ADR's framing — the relay costs a plaintext address, the jump host costs
nothing, because the operator is not in it.

Both documents carry a section on what their own earlier reasoning got wrong, which for the second one is
the load-bearing part: "nothing reads this field" was read as evidence of a mistake when it was evidence of
an unfinished feature — and the same sentence one field over would have found the checkbox that is lying.

2026-08-07 08:44:21 +02:00

13 KiB

Raw Permalink Blame History

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

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

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.
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.
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.
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.
The prose. Below.
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.

13 KiB Raw Permalink Blame History