Keep the device key in the TPM, behind a consent Windows enforces

The last of ADR 0007's three pieces, and it does not implement what that ADR
originally decided — because writing it exposed a flaw in the decision.

The ADR said "a Windows Hello gesture gating a protected blob". That does not
deliver what the rest of the document claims for it: a gate inside the process is
not a gate. A store that showed a prompt and then read a DPAPI blob would be
bypassed by malware that skipped the prompt, read the file and called
CryptUnprotectData itself — which is exactly the attacker the whole decision was
made against, and exactly the reason DPAPI alone was rejected. The presence
requirement has to be a condition of using the key, enforced below the
application, or it is decoration.

So the device key is encrypted to an RSA key created in the Microsoft Platform
Crypto Provider — the TPM — under CngUIProtectionLevels.ProtectKey. Windows
requires consent to use that key, so the prompt is not something this code can be
talked out of showing. Malware can ask for the key; it cannot answer the dialog.
That is strictly stronger than the ADR described, and most of what option D was
being saved for: the wrapping key genuinely never leaves hardware. The X25519
device key still lands in memory to open the wrap, because DSH1 fixes that wrap at
a curve the TPM cannot do — the remaining gap, and now a smaller step than it was.

CngKey is in-box, so this needed no WinRT projection and no Windows target
framework. Which is worth stating plainly because the opposite was planned: the
piece was scoped as "where the Windows TFM lands", and it turned out a platform
guard on one class was enough. Client.App and its two test projects stay on
net10.0.

Two things were measured on real hardware rather than assumed, and the second
changed the shape of the work.

The platform provider works here and holds an RSA key — confirmed by creating and
deleting one before writing anything that depended on it.

And ProtectKey prompts at key *creation*, not only at use. The comment in the
first draft of this file said the opposite, with a confident explanation: sealing
uses only the public half, so it should be silent. It is not. CngKey.Create blocks
on a dialog, because the policy means "protect this key with a PIN" and Windows
asks the user to set that up there and then. Found by writing tests around save
and forget and watching the suite hang for ten minutes waiting for somebody to
type one.

That has two consequences worth knowing before touching this file. SaveAsync is
user-facing code — it belongs on a UI thread, behind a button somebody pressed,
never on a background pass. And almost nothing in the store can be covered
automatically: two tests remain, availability and the empty-blob case, both of
which provably reach no dialog. Disabling the UI policy to make the rest testable
would remove the one property worth having.

The interface offers two things and hides both where they cannot work. "Use
Windows Hello" appears on the unlock screen only when this machine has a cached
wrap and a keystore still willing to release the key; "Use Windows Hello here"
appears in the account bar only when the machine can keep a key and has not
already registered one, so it is spent once used. Absent rather than disabled, in
both cases: a greyed-out button on a machine that never had a TPM reads as
something broken, and the passphrase box beside it is not a fallback — it is the
ordinary way in.

Both unlock paths now share AdoptAsync rather than each opening the known-host
store, building the vault and starting auto-sync. The ordering in there is
load-bearing and a second copy would be a second chance to get it wrong.

The shell's tests drive a fake keystore. Not for speed: the real one prompts on
every save and load, so a suite using it would block forever. What the shell has
to get right is which buttons appear and what happens when one is pressed, and a
fake answers exactly that. It is shared from Client.Session.Tests by source link
rather than reimplemented.

882 tests green, 6 of them new. Zero warnings, dotnet format clean.

Not verified, and not verifiable here: the dialogs. Whether the consent prompt
appears at the right moments, reads sensibly, and returns to a usable window when
declined needs the application run by a person on a machine with a TPM. That is
the remaining half of outstanding item #7, and it is now the only thing between
this feature and being finished.

docs/adr/0007-device-key-protection.md

@@ -33,11 +33,47 @@ leaves hardware" would be false under all of them.
 
 ## Decision
 
-**A Windows Hello gesture gating a protected blob, with the passphrase kept as a permanent fallback.**
+**A TPM-resident key whose use requires the user's consent, with the passphrase kept as a permanent
+fallback.**
 
-The gesture is what carries the security value: it requires **user presence** per unlock. Hello cannot
-decrypt, so it is used to gate release of the wrapping key, and the passphrase path remains available
-unconditionally.
+User presence per unlock is what carries the security value. What changed between this decision and its
+implementation is *who enforces the presence*, and the change was a correction rather than a refinement.
+
+> **Amended 2026-07-30.** This section originally read "a Windows Hello gesture gating a protected blob".
+> That design does not deliver what the rest of this document claims for it, and the flaw is worth keeping
+> on the record: **a gate inside the process is not a gate.** A store that showed a Hello prompt and then
+> read a DPAPI blob would be bypassed by malware that skipped the prompt, read the file and called
+> `CryptUnprotectData` itself. The presence requirement has to be a condition of *using the key*, enforced
+> below the application, or it is decoration.
+
+So the device key is encrypted to an RSA key created in the **Microsoft Platform Crypto Provider** — the
+TPM — under `CngUIProtectionLevels.ProtectKey`. Windows requires consent to use that key, so the prompt is
+not something this code can be talked out of showing. Malware can ask for the key; it cannot answer the
+dialog, and the attempt is visible. `System.Security.Cryptography.CngKey` is in-box, so this needs no WinRT
+projection and **no Windows target framework** — a plain platform guard is enough.
+
+RSA rather than an agreement algorithm because the payload is 32 bytes and OAEP over 2048 bits carries 190.
+That also keeps the DSH1 device wrap unchanged at X25519: the TPM key protects the device key, it does not
+replace it.
+
+Availability is probed by creating a throwaway key and deleting it, not by asking whether the provider is
+registered — it is registered on machines with no usable TPM too, and reports itself present right up to
+the point where creating a key fails.
+
+### What was measured, and what it cost
+
+Two things were verified on real hardware rather than assumed, and one of them changed the design's shape:
+
+- **The platform provider works** and holds an RSA key: confirmed by creating and deleting one.
+- **`ProtectKey` prompts at key *creation*, not only at use.** `CngKey.Create` blocks on a dialog, because
+  the policy means "protect this key with a PIN" and Windows asks the user to set that up there and then.
+
+The second has consequences. Registering a device shows a setup dialog and every unlock shows a consent
+dialog, which is the right shape for an opt-in feature — but it means **`SaveAsync` is user-facing code**
+that belongs on a UI thread behind a button somebody pressed, and it means almost nothing in the store can
+be covered by an automated test. That was found by writing those tests and watching a suite hang for ten
+minutes waiting for a PIN. Two tests remain: availability, and the empty case that provably reaches no
+dialog.
 
 ### Why not DPAPI alone
 
@@ -55,9 +91,14 @@ Neither defends the *local malware* case. The gesture does.
 
 ### Why not extend the spec (yet)
 
-The only option that delivers what the TPM is usually credited with is to add a `SealTo` algorithm over
-a curve the TPM can do — `alg_id = 4` over P-256 — so the device private key never exists in process
-memory at all. That is **the recorded target**, not this decision.
+The device *wrapping* key now genuinely never leaves the TPM, which is most of what option D promised. What
+remains is that the X25519 device key itself is reassembled in process memory to open the wrap, because DSH1
+fixes that wrap at a curve the TPM cannot do.
+
+Closing that last gap means adding a `SealTo` algorithm over a curve the TPM can do — `alg_id = 4` over
+P-256 — so the device key never exists outside hardware at all. That is **the recorded target**, not this
+decision, and it is now a smaller step than it was: the keystore plumbing, the endpoint and the unlock path
+would all be unchanged.
 
 It is cheaper than "change a frozen spec" sounds, because a device wrap row is read only by the device
 that created it: not by another client, and not by the server. The envelope already carries `alg_id`
@@ -97,11 +138,12 @@ would have become false under DPAPI alone. A gesture is still something the atta
 
 ### Operational
 
-- **Hello is not always available.** No biometric hardware falls back to a Hello PIN, which is
-  TPM-bound and rate-limited and still satisfies the presence requirement. Some machines have no Hello
-  at all. The passphrase path is therefore required, not a nicety.
-- **Hello keys are invalidated when the PIN is reset**, so the blob must be treated as losable at any
-  time; losing it degrades to a passphrase prompt and never to a locked-out vault.
+- **A TPM is not always there.** A machine without one gets a store that reports itself unavailable, so
+  unlock keeps asking for the passphrase and neither affordance appears in the interface. The passphrase path
+  is therefore required, not a nicety.
+- **The stored key must be treated as losable at any time** — a reset PIN, a cleared TPM, a replaced key.
+  Every loss degrades to a passphrase prompt and never to a locked-out vault, which is why every failure in
+  the store returns null rather than throwing and why the three unlock statuses all end in the same advice.
 - **Registering a device is a separate act from enrolling one.** `EnrollmentService.AddDevice` runs only
   during enrollment, so every already-enrolled account — which is all of them — needs an endpoint to add
   a device wrap while unlocked. Producing the wrap requires the bundle, so the client proves possession