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

The canister identifies a browser by a key it proves possession of, so the
frontend has to hold one. A non-extractable P-256 keypair in IndexedDB, per
identity, and a successor generated alongside it: the sign-in signs with the
current key and announces the successor, and the successor is promoted only once
the canister confirms the sign-in.

Promoting after confirmation rather than before is what survives a lost
response: 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.

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, which is the accepted cost of
not blocking sign-in on it.

Nothing imports this yet; the sign-in that uses it lands two PRs up.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: sea-snake

src/frontend/src/lib/stores/browser-key.store.test.ts

@@ -0,0 +1,225 @@
+import "fake-indexeddb/auto";
+import { beforeEach, describe, expect, it } from "vitest";
+import { clear, createStore } from "idb-keyval";
+import { currentDeviceId, withBrowserProof } from "./browser-key.store";
+
+/// Names the same store the module under test writes to, so a test can wipe it.
+const BROWSER_KEY_STORE = createStore("ii-browser-keys", "keys");
+
+const SIGNATURE_DOMAIN = new TextEncoder().encode("ii-session-device-key");
+const SUCCESSOR_SIGNATURE_DOMAIN = new TextEncoder().encode(
+  "ii-session-device-successor",
+);
+
+const signedMessage = (
+  domain: Uint8Array,
+  sessionKey: Uint8Array,
+  otherKey: Uint8Array,
+): Uint8Array => {
+  const message = new Uint8Array(
+    domain.length + sessionKey.length + otherKey.length,
+  );
+  message.set(domain);
+  message.set(sessionKey, domain.length);
+  message.set(otherKey, domain.length + sessionKey.length);
+  return message;
+};
+
+const verify = async (
+  publicKey: Uint8Array,
+  signature: Uint8Array,
+  message: Uint8Array,
+): Promise<boolean> => {
+  const key = await crypto.subtle.importKey(
+    "spki",
+    new Uint8Array(publicKey),
+    { name: "ECDSA", namedCurve: "P-256" },
+    true,
+    ["verify"],
+  );
+  return crypto.subtle.verify(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    new Uint8Array(signature),
+    new Uint8Array(message),
+  );
+};
+
+const sessionKey = (seed: number) => new Uint8Array(62).fill(seed);
+
+const IDENTITY = BigInt(10_000);
+
+/** Signs in and rotates, the way a successful ceremony does. */
+const signIn = (identityNumber: bigint, seed: number, deviceId = 1) =>
+  withBrowserProof(identityNumber, sessionKey(seed), async (proof) => {
+    await proof.accept(deviceId);
+    return proof;
+  });
+
+/** Signs in without accepting, the way a call that fails or never returns leaves it. */
+const attempt = (identityNumber: bigint, seed: number) =>
+  withBrowserProof(identityNumber, sessionKey(seed), (proof) =>
+    Promise.resolve(proof),
+  );
+
+/** jsdom has no Web Locks, so this is what serialisation is tested against. */
+const stubLockApi = (): void => {
+  let tail: Promise<unknown> = Promise.resolve();
+  Object.defineProperty(navigator, "locks", {
+    configurable: true,
+    value: {
+      request: (_name: string, run: () => Promise<unknown>) => {
+        const next = tail.then(run);
+        tail = next.then(
+          () => undefined,
+          () => undefined,
+        );
+        return next;
+      },
+    },
+  });
+};
+
+const withoutLockApi = (): void => {
+  Object.defineProperty(navigator, "locks", {
+    configurable: true,
+    value: undefined,
+  });
+};
+
+describe("browser key", () => {
+  beforeEach(async () => {
+    await clear(BROWSER_KEY_STORE);
+    withoutLockApi();
+  });
+
+  it("signs the session key and the successor under the domain the canister verifies", async () => {
+    const key = sessionKey(1);
+
+    const proof = await attempt(IDENTITY, 1);
+
+    await expect(
+      verify(
+        proof.publicKey,
+        proof.signature,
+        signedMessage(SIGNATURE_DOMAIN, key, proof.nextPublicKey),
+      ),
+    ).resolves.toBe(true);
+  });
+
+  it("does not sign the session key alone", async () => {
+    const proof = await attempt(IDENTITY, 1);
+
+    await expect(
+      verify(proof.publicKey, proof.signature, sessionKey(1)),
+    ).resolves.toBe(false);
+  });
+
+  it("announces a successor it does not yet use", async () => {
+    const proof = await attempt(IDENTITY, 1);
+
+    expect(proof.nextPublicKey).not.toEqual(proof.publicKey);
+  });
+
+  it("rotates to the successor once a sign-in is accepted", async () => {
+    const first = await signIn(IDENTITY, 1);
+
+    const second = await attempt(IDENTITY, 2);
+
+    expect(second.publicKey).toEqual(first.nextPublicKey);
+  });
+
+  it("keeps the current key when a sign-in is not accepted", async () => {
+    const first = await attempt(IDENTITY, 1);
+
+    const second = await attempt(IDENTITY, 2);
+
+    expect(second.publicKey).toEqual(first.publicKey);
+    expect(second.nextPublicKey).not.toEqual(first.nextPublicKey);
+  });
+
+  it("holds a separate key per identity", async () => {
+    const first = await attempt(IDENTITY, 1);
+
+    const second = await attempt(BigInt(10_001), 1);
+
+    expect(second.publicKey).not.toEqual(first.publicKey);
+  });
+
+  it("registers a fresh key once storage is cleared", async () => {
+    const before = await signIn(IDENTITY, 1);
+    await clear(BROWSER_KEY_STORE);
+
+    const after = await attempt(IDENTITY, 1);
+
+    expect(after.publicKey).not.toEqual(before.publicKey);
+    expect(after.publicKey).not.toEqual(before.nextPublicKey);
+  });
+
+  it("serialises concurrent sign-ins, so the second builds on the first", async () => {
+    stubLockApi();
+
+    const [first, second] = await Promise.all([
+      signIn(IDENTITY, 1),
+      signIn(IDENTITY, 2),
+    ]);
+
+    expect(second.publicKey).toEqual(first.nextPublicKey);
+  });
+
+  it("still signs in on a browser without the lock API", async () => {
+    const proof = await attempt(IDENTITY, 1);
+
+    expect(proof.publicKey.length).toBe(91);
+  });
+
+  it("exports the keys in the encoding the canister parses", async () => {
+    const proof = await attempt(IDENTITY, 1);
+
+    expect(proof.publicKey.length).toBe(91);
+    expect(proof.nextPublicKey.length).toBe(91);
+    expect(proof.signature.length).toBe(64);
+  });
+
+  it("remembers which browser the canister said this is", async () => {
+    await signIn(IDENTITY, 1, 7);
+
+    await expect(currentDeviceId(IDENTITY)).resolves.toBe(7);
+  });
+
+  it("knows of no browser before a sign-in is accepted", async () => {
+    await attempt(IDENTITY, 1);
+
+    await expect(currentDeviceId(IDENTITY)).resolves.toBeUndefined();
+  });
+
+  it("has the successor sign for itself, so an unheld key cannot be announced", async () => {
+    const key = sessionKey(1);
+
+    const proof = await attempt(IDENTITY, 1);
+
+    await expect(
+      verify(
+        proof.nextPublicKey,
+        proof.nextSignature,
+        signedMessage(SUCCESSOR_SIGNATURE_DOMAIN, key, proof.publicKey),
+      ),
+    ).resolves.toBe(true);
+  });
+
+  it("keeps the two signatures in their own roles", async () => {
+    const key = sessionKey(1);
+
+    const proof = await attempt(IDENTITY, 1);
+
+    // The successor's signature must not verify as the current key's, or one could be
+    // replayed as the other.
+    await expect(
+      verify(
+        proof.publicKey,
+        proof.nextSignature,
+        signedMessage(SIGNATURE_DOMAIN, key, proof.nextPublicKey),
+      ),
+    ).resolves.toBe(false);
+  });
+});

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

@@ -0,0 +1,160 @@
+import { createStore, get as idbGet, set as idbSet } from "idb-keyval";
+
+/**
+ * The key this browser proves itself with when it creates a session, and the id the
+ * canister attributed it to.
+ *
+ * The key never leaves this origin: it appears in no delegation chain and in nothing an app
+ * receives, which is what lets it identify the browser without letting two apps recognise
+ * it. It is replaced at every sign-in, so a copy of it taken off disk stops working as soon
+ * as this browser signs in again.
+ */
+interface BrowserKeyRecord {
+  keyPair: CryptoKeyPair;
+  /** Absent until a sign-in has told us which browser we are. */
+  deviceId?: number;
+}
+
+const BROWSER_KEY_STORE = createStore("ii-browser-keys", "keys");
+
+/** Must match the domains the canister verifies the two signatures under. */
+const SIGNATURE_DOMAIN = new TextEncoder().encode("ii-session-device-key");
+const SUCCESSOR_SIGNATURE_DOMAIN = new TextEncoder().encode(
+  "ii-session-device-successor",
+);
+
+/**
+ * One key per identity, so nothing stored here links two of the user's identities to the
+ * same browser.
+ */
+const storageKey = (identityNumber: bigint): string =>
+  identityNumber.toString();
+
+const generate = (): Promise<CryptoKeyPair> =>
+  crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, false, [
+    "sign",
+    "verify",
+  ]) as Promise<CryptoKeyPair>;
+
+const read = async (
+  identityNumber: bigint,
+): Promise<BrowserKeyRecord | undefined> => {
+  try {
+    return await idbGet<BrowserKeyRecord>(
+      storageKey(identityNumber),
+      BROWSER_KEY_STORE,
+    );
+  } catch {
+    return undefined;
+  }
+};
+
+const write = async (
+  identityNumber: bigint,
+  record: BrowserKeyRecord,
+): Promise<void> => {
+  try {
+    await idbSet(storageKey(identityNumber), record, BROWSER_KEY_STORE);
+  } catch {
+    // A browser that cannot keep its key signs in as a new one next time, which the
+    // identity sees as a new browser rather than as a failure.
+  }
+};
+
+const exported = (key: CryptoKey): Promise<Uint8Array> =>
+  crypto.subtle.exportKey("spki", key).then((spki) => new Uint8Array(spki));
+
+const signed = async (
+  key: CryptoKey,
+  domain: Uint8Array,
+  sessionKey: Uint8Array,
+  otherKey: Uint8Array,
+): Promise<Uint8Array> => {
+  const message = new Uint8Array(
+    domain.length + sessionKey.length + otherKey.length,
+  );
+  message.set(domain);
+  message.set(sessionKey, domain.length);
+  message.set(otherKey, domain.length + sessionKey.length);
+  return new Uint8Array(
+    await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key, message),
+  );
+};
+
+export interface BrowserProof {
+  publicKey: Uint8Array;
+  nextPublicKey: Uint8Array;
+  signature: Uint8Array;
+  /** By the successor itself, so a key the browser does not hold cannot be announced. */
+  nextSignature: Uint8Array;
+  /** Rotates to the successor. Called once the canister has accepted the sign-in. */
+  accept: (deviceId: number) => Promise<void>;
+}
+
+/** Serialises sign-ins for one identity: two at once would leave us holding a key the
+ *  canister never accepted, which reads as a different browser. */
+const exclusively = async <T>(
+  identityNumber: bigint,
+  run: () => Promise<T>,
+): Promise<T> => {
+  const locks = navigator.locks;
+  if (locks === undefined) {
+    return run();
+  }
+  // Awaited, because `request` types its callback's return as the value it resolves to,
+  // so the promise `run` returns would otherwise nest.
+  return await locks.request(`ii-browser-key:${identityNumber}`, run);
+};
+
+/**
+ * Proves possession of this browser's key and announces the successor it rotates to.
+ *
+ * The proof covers the session key, which is fresh for every session, so it is good for
+ * exactly one sign-in. `accept` is what advances this browser to the successor, and until
+ * it is called the current key stays in place — so a call that never comes back leaves both
+ * sides on the key the canister still holds.
+ */
+export const withBrowserProof = <T>(
+  identityNumber: bigint,
+  sessionKey: Uint8Array,
+  signIn: (proof: BrowserProof) => Promise<T>,
+): Promise<T> =>
+  exclusively(identityNumber, async () => {
+    const stored = await read(identityNumber);
+    let keyPair = stored?.keyPair;
+    if (keyPair === undefined) {
+      // Kept before the call, not after: a first sign-in whose response is lost has still
+      // registered this key, and coming back with a different one would enrol us twice.
+      keyPair = await generate();
+      await write(identityNumber, { keyPair });
+    }
+    const successor = await generate();
+    const [publicKey, nextPublicKey] = await Promise.all([
+      exported(keyPair.publicKey),
+      exported(successor.publicKey),
+    ]);
+
+    const [signature, nextSignature] = await Promise.all([
+      signed(keyPair.privateKey, SIGNATURE_DOMAIN, sessionKey, nextPublicKey),
+      signed(
+        successor.privateKey,
+        SUCCESSOR_SIGNATURE_DOMAIN,
+        sessionKey,
+        publicKey,
+      ),
+    ]);
+
+    return signIn({
+      publicKey,
+      nextPublicKey,
+      signature,
+      nextSignature,
+      accept: (deviceId) =>
+        write(identityNumber, { keyPair: successor, deviceId }),
+    });
+  });
+
+/** Which browser the canister knows this one as, for the settings list to mark it. */
+export const currentDeviceId = async (
+  identityNumber: bigint,
+): Promise<number | undefined> => (await read(identityNumber))?.deviceId;