feat(fe): hold a browser key and rotate it on every sign-in

[sea-snake]

Design: #4224. Overview: #4230. Nothing imports this until the sign-in in #4273.

The canister identifies a browser by a key it proves possession of (#4264), so the frontend has to hold one, and rotate it, so a key captured from one sign-in cannot claim that browser at the next.

A non-extractable P-256 keypair in IndexedDB, per identity, plus a successor generated alongside it. A sign-in signs with the current key and announces the successor; the successor is promoted only once the canister has confirmed the sign-in.

Promoting after confirmation rather than before is what survives a lost response. If the reply never arrives, the browser still holds the key the canister has, so its next attempt presents the same one rather than a successor the canister never saw — which the canister would treat as an unknown browser and enrol as a second entry for the same machine.

Sign-ins are serialised with a web lock, because two at once would leave whichever wrote last holding a key the canister never accepted. Where the Web Locks API is missing the calls run unserialised: not blocking sign-in on it is the deliberate trade, and the window is one concurrent sign-in on the same device.

A browser that no longer matches what it registered as signs in as a new one. The description it reported (#4270) is stored beside the key pair, and compared before anything is sent. A registered entry keeps the description it was created with — the canister ignores what a sign-in reports once an entry is being advanced — so a browser whose brand, system, form factor or model has changed would otherwise keep rotating an entry describing something it no longer is. Where it differs, this presents a fresh key pair, which no entry holds and which therefore registers under its own.

Deciding here rather than being told keeps that a purely local operation: nothing has been sent when the comparison happens, so the entry left behind is untouched and a retry hits the same state and takes the same branch. The description is written with the key pair and never on its own, so the comparison is always against what the canister was actually sent.

The private key never leaves IndexedDB and never appears in a delegation chain.

Tests: browser-key.store.test.ts (21), including the successor promoted only after the call succeeds, a lost response leaving the current key in place, concurrent sign-ins serialised, the store working with the lock API absent, and a changed description signing in on a fresh key pair while an unchanged one keeps rotating.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 80c7e09.

Security Overview

• 🔎 Scanned files: 2 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/6d3e3b61-710b-4b2b-9c0b-43458b6314b6?scanId=6cfe67e6-9f53-4a16-9948-b0da62b77e0f&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► src/frontend/src/lib/stores/browser-key.store.ts ▸ Implement browser-key.store with browser key management, signing, rotation, and persistence ► src/frontend/src/lib/stores/browser-key.store.test.ts ▸ Add tests for browser-key.store functionality and behaviors

[Copilot]

🟡 Changes recommended

Lost-response and storage-failure paths can desynchronize local browser records from the canister and prevent correct recovery.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds per-identity browser keys that rotate after confirmed sign-ins.

Changes:

• Stores and rotates non-extractable P-256 key pairs.
• Handles stale keys, browser-description changes, and concurrent sign-ins.
• Adds comprehensive browser-key tests.

File summaries

File	Description
browser-key.store.ts	Implements browser-key persistence, proofs, rotation, and recovery.
browser-key.store.test.ts	Tests signing, rotation, recovery, descriptions, and locking.

Review details

Suppressed comments (2)

src/frontend/src/lib/stores/browser-key.store.ts:160

• A brand-new identity returns undefined here, and the changed-description branch below also creates fresh without description. Consequently, if that registration is accepted but its response is lost, IndexedDB contains the keys but not the description the canister registered. A description change before recovery then reuses/advances that entry and finally records the newer description locally, while the canister keeps the older one. Create the initial record here and persist description alongside every fresh key pair before calling signIn.

  if (
    stored?.description === undefined ||
    sameDescription(stored.description, description)

src/frontend/src/lib/stores/browser-key.store.ts:289

• Promoting a real successor drops the existing browserId and registered description. If this retry fails, the incomplete record remains; a later changed browser description is therefore not detected and the old canister entry is advanced instead of registering a new browser. Preserve those fields when announcedSuccessor exists, while keeping the fresh-key fallback free of the old browser ID.

      const promoted: BrowserKeyRecord = {
        keyPair: stored?.announcedSuccessor ?? (await generate()),
      };

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.