agent-comms 9.0.11 → 9.0.12

package/src/core/identity-store.ts

@@ -3,7 +3,9 @@
  *
  * Mesh state stays in memory and on the wire; the only thing on disk is this local credential (plus, now, the tokens minted against it), the same trust model as an SSH key. A lock file holding a PID keeps two live bridges in one slot from sharing an identity, which would put duplicate peer IDs on the mesh; the second bridge runs with an ephemeral identity (the behaviour before persistence) instead. Bridges without a graceful shutdown hook can skip releasing the lock: a stale lock is detected by probing the recorded PID, the same way the coordinator probes for stale agents.
  *
- * Persisting the key material rather than a bare agent ID is what makes restarts work: delivery routing fires when agentId === peerId, and peerId is deviceIdToHex(identity.deviceId), so an ID without its key can never match the running peer. Renewal near certificate expiry currently generates an entirely fresh key pair rather than re-certifying the existing one, which silently rotates the device-id (and so invalidates any persisted room tokens bound to it) -- a real, separately tracked gap (#68), not addressed here.
+ * Persisting the key material rather than a bare agent ID is what makes restarts work: delivery routing fires when agentId === peerId, and peerId is deviceIdToHex(identity.deviceId), so an ID without its key can never match the running peer. Renewal near certificate expiry re-certifies the existing key pair, so the device-id survives it. A slot file that exists but cannot be used is never replaced: loading it throws UnusableIdentityRecordError (issuer-identity-file.ts), because a new key would silently change the peer id and discard every token the file holds. Only a missing file starts a new identity.
+ *
+ * Several processes can write one slot file: the bridge holding the slot lock, a cc-peer front loading the same identity without that lock, and whichever of them is renewing the certificate. Every read-modify-write of the file therefore runs under a short-lived write lock of its own (the slot lock is held for the bridge's whole lifetime, so it cannot serialise them). A bridge that lost the slot lock runs under an identity that is not the file's, so the tokens it mints and holds are kept in its own memory for the life of the process and never read from or written to the file.
  */
 
 import * as fs from "node:fs";
@@ -13,20 +15,20 @@ import {
   type DataDirectoryLocation,
 } from "./data-directory.js";
 import type { CapabilityToken } from "wire-mesh-core/generated/protocol";
-import {
-  generateIdentity,
-  certifyKeyPair,
-  getCertificateFingerprint,
-  deriveDeviceId,
-  CERTIFICATE_VALIDITY_MS,
-} from "./identity.js";
+import { generateIdentity } from "./identity.js";
+import { isIsoTimestamp } from "./iso-timestamp.js";
 import type { PeerIdentity } from "./identity.js";
 import { writeFileAtomic } from "./atomic-file.js";
 import {
-  isPidAlive,
-  readLockPid,
+  loadOrCreateIssuerIdentity,
+  readIssuerRecord,
+  type StoredIssuerKey,
+} from "./issuer-identity-file.js";
+import {
+  liveLockHolder,
   releaseLockFile,
   tryAcquireLock,
+  withWriteLockAsync,
 } from "./pid-lock-file.js";
 
 /** A bridge's identity slot: one persisted identity per harness and cwd. */
@@ -37,15 +39,8 @@ export interface IdentitySlot extends DataDirectoryLocation {
   dir?: string;
 }
 
-/** Renewal margin is one twelfth of the certificate's total validity period. */
-const RENEWAL_MARGIN_FRACTION = 12;
-/** Renew during the final twelfth of the certificate's validity. */
-const RENEWAL_MARGIN_MS = CERTIFICATE_VALIDITY_MS / RENEWAL_MARGIN_FRACTION;
-
 /** A persisted identity/token/trust/ledger file holds real key material or capability tokens, so it is written owner-only. */
 const OWNER_ONLY_RW_PERMISSIONS = 0o600;
-/** One Int32 element's worth of bytes -- sleepSync's own shared buffer needs no more than a single slot for Atomics.wait to block on. */
-const INT32_BYTE_LENGTH = 4;
 
 /** A CapabilityToken (COSE_Sign1: [protected header bytes, unprotected header map, payload bytes or null, signature bytes]) with every byte-string field base64-encoded for JSON storage. Only the two named unprotected-header fields (alg, kid) are round-tripped -- every token minted by wire-mesh-core today leaves the unprotected header empty (alg/kid live in the protected header instead), so the schema's own open catchall for arbitrary extra keys is left unhandled until a real caller actually needs one preserved. */
 export type SerializedCapabilityToken = [
@@ -55,10 +50,8 @@ export type SerializedCapabilityToken = [
   string,
 ];
 
-interface StoredIdentity {
-  privateKey: string;
-  certificate: string;
-  expiresAt: string;
+/** What a slot remembers beside its key material: the tokens it bears or has issued. */
+interface SlotTokenRecords {
   roomTokens?: Record<string, SerializedCapabilityToken>;
   /** The token-id (base64) of each room:member grant this identity has itself issued to another device, keyed by "roomPath::memberDeviceHex" -- the bookkeeping a room owner needs to revoke a specific member's own grant later (kickFromRoom), distinct from roomTokens above (which holds tokens this identity BEARS, not ones it issued). */
   issuedGrants?: Record<string, string>;
@@ -66,6 +59,8 @@ interface StoredIdentity {
   groupTokens?: Record<string, SerializedCapabilityToken>;
 }
 
+interface StoredIdentity extends StoredIssuerKey, SlotTokenRecords {}
+
 /** A COSE_Sign1 tuple always has exactly 4 elements: protected header, unprotected header, payload, signature. */
 const COSE_SIGN1_TUPLE_LENGTH = 4;
 
@@ -197,26 +192,26 @@ export function oplogDirFor(slot: Readonly<IdentitySlot>): string {
   return path.join(dir, base);
 }
 
-function persistIdentity(identityFile: string, identity: PeerIdentity): void {
-  const stored: StoredIdentity = {
-    privateKey: identity.privateKey,
-    certificate: identity.certificate,
-    expiresAt: new Date(Date.now() + CERTIFICATE_VALIDITY_MS).toISOString(),
-  };
-  writeFileAtomic(
-    identityFile,
-    `${JSON.stringify(stored, null, 2)}\n`,
-    OWNER_ONLY_RW_PERMISSIONS,
-  );
+/** The token records of every slot this process runs under an identity that is not the slot file's (it lost the slot lock to another live process), keyed by the slot's file. They are bound to a throw-away device-id, so they live and die with the process: neither written into the winner's file nor read from it. */
+const ephemeralTokenRecords = new Map<string, SlotTokenRecords>();
+
+/** Loads the identity the slot file holds, creating it when the file does not exist, renewing it in place near certificate expiry. Throws UnusableIdentityRecordError, leaving the file untouched, when the file exists but cannot be used. */
+function loadSlotIdentity(
+  paths: Readonly<ReturnType<typeof slotPaths>>,
+): PeerIdentity {
+  return loadOrCreateIssuerIdentity(paths.identityFile, isStoredIdentity);
 }
 
 /**
  * Load the persisted identity for the slot, creating it on first use, and take the slot lock. Returns an ephemeral identity when the slot is already held by another live process.
+ *
+ * Throws UnusableIdentityRecordError when the slot's file exists but cannot be used (damaged, unreadable, or holding a key that cannot be certified again). The file is left untouched, the slot lock is released and no identity is returned: a caller must not join the mesh under a key the user did not choose, so the bridge stops with the error's message, which says what to do.
  */
 export function loadOrCreateIdentity(
   slot: Readonly<IdentitySlot>,
 ): PeerIdentity {
-  const { dir, identityFile, lockFile } = slotPaths(slot);
+  const paths = slotPaths(slot);
+  const { dir, identityFile, lockFile } = paths;
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
 
   const claim = tryAcquireLock(lockFile);
@@ -224,81 +219,38 @@ export function loadOrCreateIdentity(
     console.error(
       `agent-comms: identity slot ${slot.harness} (${slot.cwd}) is held by live pid ${String(claim.heldBy)}; running with an ephemeral identity`,
     );
+    ephemeralTokenRecords.set(identityFile, {});
     return generateIdentity();
   }
-
-  return loadStoredIdentity(identityFile) ?? createIdentity(identityFile);
-}
-
-/**
- * Load and validate the stored key material. A well-formed record nearing certificate expiry is renewed by re-certifying its existing key pair (preserving device-id) rather than replaced -- see `certifyKeyPair`'s own doc comment for why generating a fresh key pair here would be wrong. Returns undefined only when there is no usable existing key pair to renew at all (missing, unparseable, or corrupt), which is the caller's signal to generate an entirely new identity instead.
- */
-function loadStoredIdentity(identityFile: string): PeerIdentity | undefined {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(fs.readFileSync(identityFile, "utf-8"));
-  } catch {
-    return undefined;
-  }
-  if (!isStoredIdentity(parsed)) return undefined;
-
-  const expiresAt = Date.parse(parsed.expiresAt);
-  const needsRenewal =
-    Number.isNaN(expiresAt) || Date.now() > expiresAt - RENEWAL_MARGIN_MS;
+  ephemeralTokenRecords.delete(identityFile);
 
   try {
-    if (needsRenewal) {
-      const renewed = certifyKeyPair(parsed.privateKey);
-      // A plain persistIdentity() call here would silently drop this slot's roomTokens/issuedGrants (it always writes a bare {privateKey, certificate, expiresAt} record) -- write through writeStoredIdentity instead so a renewal preserves everything else already on record, the same way saveRoomToken/saveIssuedRoomGrant already do for their own fields.
-      writeStoredIdentity(identityFile, {
-        ...parsed,
-        privateKey: renewed.privateKey,
-        certificate: renewed.certificate,
-        expiresAt: new Date(Date.now() + CERTIFICATE_VALIDITY_MS).toISOString(),
-      });
-      return renewed;
-    }
-    return {
-      privateKey: parsed.privateKey,
-      certificate: parsed.certificate,
-      fingerprint: getCertificateFingerprint(parsed.certificate),
-      deviceId: deriveDeviceId(parsed.privateKey),
-    };
+    return loadSlotIdentity(paths);
   } catch (err) {
-    console.error(
-      `agent-comms: stored identity at ${identityFile} is unreadable (${err instanceof Error ? err.message : String(err)}); generating a fresh identity`,
-    );
-    return undefined;
+    releaseLockFile(lockFile);
+    throw err;
   }
 }
 
-function createIdentity(identityFile: string): PeerIdentity {
-  const identity = generateIdentity();
-  persistIdentity(identityFile, identity);
-  return identity;
-}
-
 /**
  * Probes a slot's current lock holder without taking it -- the cc-peer front (agent-comms#157) uses this read-only check to decide whether a local Claude Code session already fronts itself (a live agent-comms bridge already holds the slot) before attaching, and to notice a session's own bridge taking the slot over later so the front can yield. Returns the live PID currently holding the slot's lock, or undefined when the slot is unlocked or its recorded holder is no longer alive.
  */
 export function probeSlotOwner(
   slot: Readonly<IdentitySlot>,
 ): number | undefined {
-  const { lockFile } = slotPaths(slot);
-  const heldBy = readLockPid(lockFile);
-  if (heldBy === undefined) return undefined;
-  return isPidAlive(heldBy) ? heldBy : undefined;
+  return liveLockHolder(slotPaths(slot).lockFile);
 }
 
 /**
- * Loads (creating on first use) the persisted identity for a slot without taking its exclusivity lock. The cc-peer front (agent-comms#157) uses this to assume a not-yet-live session's own future identity, so the device-id -- and with it every agent id, room membership, and pending delivery already addressed to it -- carries over unchanged the moment that session's own bridge starts and claims the slot for real. Callers must have already confirmed via probeSlotOwner that no live bridge currently holds the slot; re-probing atomically against a concurrent acquisition isn't possible across the two separate files (identity vs lock) this store keeps, so it's the front's own periodic re-probe, not this function, that detects and reacts to a real bridge taking over afterwards.
+ * Loads (creating on first use) the persisted identity for a slot without taking its exclusivity lock. Throws UnusableIdentityRecordError exactly as loadOrCreateIdentity does, and the front reports it for that session without fronting it. The cc-peer front (agent-comms#157) uses this to assume a not-yet-live session's own future identity, so the device-id, and with it every agent id, room membership, and pending delivery already addressed to it, carries over unchanged the moment that session's own bridge starts and claims the slot for real. Callers must have already confirmed via probeSlotOwner that no live bridge currently holds the slot; re-probing atomically against a concurrent acquisition isn't possible across the two separate files (identity vs lock) this store keeps, so it's the front's own periodic re-probe, not this function, that detects and reacts to a real bridge taking over afterwards.
  */
 export function loadIdentityForFront(
   slot: Readonly<IdentitySlot>,
 ): PeerIdentity {
-  const { dir, identityFile } = slotPaths(slot);
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  return loadStoredIdentity(identityFile) ?? createIdentity(identityFile);
+  const paths = slotPaths(slot);
+  fs.mkdirSync(paths.dir, { recursive: true, mode: 0o700 });
+  ephemeralTokenRecords.delete(paths.identityFile);
+  return loadSlotIdentity(paths);
 }
 
 /**
@@ -308,7 +260,7 @@ export function releaseIdentityLock(slot: Readonly<IdentitySlot>): void {
   releaseLockFile(slotPaths(slot).lockFile);
 }
 
-/** Reads the slot's raw stored identity record, or undefined if the file is missing or unparseable. Used by the room-token functions below to read-modify-write only the roomTokens field, leaving the persisted key material exactly as it is. */
+/** Reads the slot's raw stored identity record, or undefined if the file is missing or unparseable. Only for reads that treat "no usable record" as "no tokens", which grants nothing; every write goes through updateTokenRecords, which refuses an unusable file instead. */
 function readStoredIdentity(identityFile: string): StoredIdentity | undefined {
   let parsed: unknown;
   try {
@@ -330,38 +282,77 @@ function writeStoredIdentity(
   );
 }
 
-// Total time to wait for a concurrent lock holder to finish creating the slot's identity file before giving up. loadOrCreateIdentity always finishes creating the file before any other process can observe its lock as taken (tryAcquireLock is the very first thing it does), so a caller that lost that race and is left holding an ephemeral identity may still reach here before the winner's own createIdentity call (a keygen plus one atomic write) has completed -- 2s is generously above that real cost even on a loaded machine, while still bounded so a holder that crashed mid-creation doesn't wedge this call forever.
+// Total time to wait for a concurrent lock holder to finish creating the slot's identity file before giving up. loadOrCreateIdentity always finishes creating the file before any other process can observe its lock as taken (tryAcquireLock is the very first thing it does), so a caller that lost that race and is left holding an ephemeral identity may still reach here before the winner's own creation (a keygen plus one atomic write) has completed, 2s is generously above that real cost even on a loaded machine, while still bounded so a holder that crashed mid-creation doesn't wedge this call forever.
 const CONCURRENT_CREATE_WAIT_MS = 2000;
 // Poll interval while waiting -- deliberately short, since the wait is expected to resolve in low single-digit milliseconds in the overwhelmingly common case.
 const CONCURRENT_CREATE_POLL_MS = 10;
 
-function sleepSync(ms: number): void {
-  const view = new Int32Array(new SharedArrayBuffer(INT32_BYTE_LENGTH));
-  Atomics.wait(view, 0, 0, ms);
-}
-
 /**
- * Reads the slot's stored identity, waiting briefly for it to appear if it doesn't exist yet but a different live process currently holds the slot's lock -- that process is, by construction, in the middle of creating it (see loadOrCreateIdentity/tryAcquireLock), so a caller racing as this slot's own ephemeral loser should wait for the real winner to finish rather than fail outright. Falls through to the ordinary "missing" result (undefined) once the lock is no longer held by a different live process, or the wait budget runs out -- both signal there is genuinely nothing to wait for.
+ * Waits briefly for the slot's identity file to appear if it doesn't exist yet but a different live process currently holds the slot's lock, that process is, by construction, in the middle of creating it (see loadOrCreateIdentity/tryAcquireLock), so a caller racing as this slot's own loser should wait for the real winner to finish rather than fail outright. Returns once the file exists, or once the lock is no longer held by a different live process, or the wait budget runs out, the last two signal there is genuinely nothing to wait for.
  */
-function readStoredIdentityWaitingForConcurrentCreate(
+async function waitForConcurrentCreate(
   identityFile: string,
   lockFile: string,
-): StoredIdentity | undefined {
+): Promise<void> {
   const deadline = Date.now() + CONCURRENT_CREATE_WAIT_MS;
   for (;;) {
-    const stored = readStoredIdentity(identityFile);
-    if (stored !== undefined) return stored;
+    if (fs.existsSync(identityFile)) return;
 
-    const heldBy = readLockPid(lockFile);
+    const heldBy = liveLockHolder(lockFile);
     const heldByDifferentLiveProcess =
-      heldBy !== undefined && heldBy !== process.pid && isPidAlive(heldBy);
-    // The holder can finish creating the file and exit between the read above and this lock check, so the file is read once more before concluding it was never created.
-    if (!heldByDifferentLiveProcess || Date.now() >= deadline) {
-      return readStoredIdentity(identityFile);
-    }
+      heldBy !== undefined && heldBy !== process.pid;
+    if (!heldByDifferentLiveProcess || Date.now() >= deadline) return;
+
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, CONCURRENT_CREATE_POLL_MS);
+    });
+  }
+}
+
+/** The token records a slot currently holds for this process: its own in-memory records when it runs under an identity that is not the slot file's, otherwise those in the file (none when the file is missing or unusable). */
+function readTokenRecords(identityFile: string): SlotTokenRecords {
+  return (
+    ephemeralTokenRecords.get(identityFile) ??
+    readStoredIdentity(identityFile) ??
+    {}
+  );
+}
 
-    sleepSync(CONCURRENT_CREATE_POLL_MS);
+/**
+ * Applies `change` to the slot's token records and persists the result, leaving the key material exactly as it is. The read and the write happen under the slot file's write lock, so two processes updating different tokens cannot drop each other's update. A slot running under a non-file identity keeps the change in this process's memory only.
+ *
+ * With `requireIdentity`, throws when the slot has no identity file yet (waiting briefly for a concurrent creator first); otherwise a missing file is a no-op. Either way a file that exists but cannot be used throws UnusableIdentityRecordError and is not written.
+ */
+async function updateTokenRecords(
+  slot: Readonly<IdentitySlot>,
+  change: (records: Readonly<SlotTokenRecords>) => SlotTokenRecords | undefined,
+  requireIdentity: boolean,
+): Promise<void> {
+  const { identityFile, lockFile } = slotPaths(slot);
+  const ephemeral = ephemeralTokenRecords.get(identityFile);
+  if (ephemeral !== undefined) {
+    ephemeralTokenRecords.set(identityFile, {
+      ...ephemeral,
+      ...change(ephemeral),
+    });
+    return;
   }
+  if (requireIdentity) await waitForConcurrentCreate(identityFile, lockFile);
+  await withWriteLockAsync(identityFile, () => {
+    const stored = readIssuerRecord(identityFile, isStoredIdentity);
+    if (stored === undefined) {
+      if (requireIdentity) {
+        throw new Error(
+          `no identity persisted for this slot yet, call loadOrCreateIdentity first (${identityFile})`,
+        );
+      }
+      return;
+    }
+    const changed = change(stored);
+    if (changed !== undefined) {
+      writeStoredIdentity(identityFile, { ...stored, ...changed });
+    }
+  });
 }
 
 /**
@@ -371,8 +362,7 @@ export function loadRoomTokens(
   slot: Readonly<IdentitySlot>,
 ): Record<string, CapabilityToken> {
   const { identityFile } = slotPaths(slot);
-  const stored = readStoredIdentity(identityFile);
-  const serialized = stored?.roomTokens ?? {};
+  const serialized = readTokenRecords(identityFile).roomTokens ?? {};
   const tokens: Record<string, CapabilityToken> = {};
   for (const [roomPath, token] of Object.entries(serialized)) {
     tokens[roomPath] = deserializeToken(token);
@@ -381,44 +371,41 @@ export function loadRoomTokens(
 }
 
 /**
- * Persists a capability token for the given room path, surviving a restart the same way the identity it was minted against does. Overwrites any token already saved for that room; leaves every other room's token and the identity's own key material untouched.
+ * Persists a capability token for the given room path, surviving a restart the same way the identity it was minted against does. Overwrites any token already saved for that room; leaves every other room's token and the identity's own key material untouched. A slot running under an ephemeral identity keeps it in this process's memory only.
  */
-export function saveRoomToken(
+export async function saveRoomToken(
   slot: Readonly<IdentitySlot>,
   roomPath: string,
   token: CapabilityToken,
-): void {
-  const { identityFile, lockFile } = slotPaths(slot);
-  const stored = readStoredIdentityWaitingForConcurrentCreate(
-    identityFile,
-    lockFile,
+): Promise<void> {
+  await updateTokenRecords(
+    slot,
+    (records) => ({
+      roomTokens: { ...records.roomTokens, [roomPath]: serializeToken(token) },
+    }),
+    true,
   );
-  if (stored === undefined) {
-    throw new Error(
-      `no identity persisted for this slot yet -- call loadOrCreateIdentity first (${identityFile})`,
-    );
-  }
-  const roomTokens = {
-    ...stored.roomTokens,
-    [roomPath]: serializeToken(token),
-  };
-  writeStoredIdentity(identityFile, { ...stored, roomTokens });
 }
 
 /** Removes the persisted token for one room path, if any. A no-op if none was saved for that path. */
-export function deleteRoomToken(
+export async function deleteRoomToken(
   slot: Readonly<IdentitySlot>,
   roomPath: string,
-): void {
-  const { identityFile } = slotPaths(slot);
-  const stored = readStoredIdentity(identityFile);
-  if (stored?.roomTokens === undefined) return;
-  const roomTokens = Object.fromEntries(
-    Object.entries(stored.roomTokens).filter(
-      ([storedRoomPath]) => storedRoomPath !== roomPath,
-    ),
+): Promise<void> {
+  await updateTokenRecords(
+    slot,
+    (records) =>
+      records.roomTokens === undefined
+        ? undefined
+        : {
+            roomTokens: Object.fromEntries(
+              Object.entries(records.roomTokens).filter(
+                ([storedRoomPath]) => storedRoomPath !== roomPath,
+              ),
+            ),
+          },
+    false,
   );
-  writeStoredIdentity(identityFile, { ...stored, roomTokens });
 }
 
 /**
@@ -428,8 +415,7 @@ export function loadGroupTokens(
   slot: Readonly<IdentitySlot>,
 ): Record<string, CapabilityToken> {
   const { identityFile } = slotPaths(slot);
-  const stored = readStoredIdentity(identityFile);
-  const serialized = stored?.groupTokens ?? {};
+  const serialized = readTokenRecords(identityFile).groupTokens ?? {};
   const tokens: Record<string, CapabilityToken> = {};
   for (const [groupPath, token] of Object.entries(serialized)) {
     tokens[groupPath] = deserializeToken(token);
@@ -440,42 +426,42 @@ export function loadGroupTokens(
 /**
  * Persists this device's own group:member token for the given group path, surviving a restart the same way the identity it was minted against does. Overwrites any token already saved for that group path; leaves every other group's token and the identity's own key material untouched. The device-membership counterpart of saveRoomToken.
  */
-export function saveGroupToken(
+export async function saveGroupToken(
   slot: Readonly<IdentitySlot>,
   groupPath: string,
   token: CapabilityToken,
-): void {
-  const { identityFile, lockFile } = slotPaths(slot);
-  const stored = readStoredIdentityWaitingForConcurrentCreate(
-    identityFile,
-    lockFile,
+): Promise<void> {
+  await updateTokenRecords(
+    slot,
+    (records) => ({
+      groupTokens: {
+        ...records.groupTokens,
+        [groupPath]: serializeToken(token),
+      },
+    }),
+    true,
   );
-  if (stored === undefined) {
-    throw new Error(
-      `no identity persisted for this slot yet -- call loadOrCreateIdentity first (${identityFile})`,
-    );
-  }
-  const groupTokens = {
-    ...stored.groupTokens,
-    [groupPath]: serializeToken(token),
-  };
-  writeStoredIdentity(identityFile, { ...stored, groupTokens });
 }
 
 /** Removes the persisted token for one group path, if any. A no-op if none was saved for that path. The device-membership counterpart of deleteRoomToken. */
-export function deleteGroupToken(
+export async function deleteGroupToken(
   slot: Readonly<IdentitySlot>,
   groupPath: string,
-): void {
-  const { identityFile } = slotPaths(slot);
-  const stored = readStoredIdentity(identityFile);
-  if (stored?.groupTokens === undefined) return;
-  const groupTokens = Object.fromEntries(
-    Object.entries(stored.groupTokens).filter(
-      ([storedGroupPath]) => storedGroupPath !== groupPath,
-    ),
+): Promise<void> {
+  await updateTokenRecords(
+    slot,
+    (records) =>
+      records.groupTokens === undefined
+        ? undefined
+        : {
+            groupTokens: Object.fromEntries(
+              Object.entries(records.groupTokens).filter(
+                ([storedGroupPath]) => storedGroupPath !== groupPath,
+              ),
+            ),
+          },
+    false,
   );
-  writeStoredIdentity(identityFile, { ...stored, groupTokens });
 }
 
 function issuedGrantKey(roomPath: string, memberDeviceHex: string): string {
@@ -491,9 +477,10 @@ export function loadIssuedRoomGrant(
   memberDeviceHex: string,
 ): Uint8Array<ArrayBuffer> | undefined {
   const { identityFile } = slotPaths(slot);
-  const stored = readStoredIdentity(identityFile);
   const encoded =
-    stored?.issuedGrants?.[issuedGrantKey(roomPath, memberDeviceHex)];
+    readTokenRecords(identityFile).issuedGrants?.[
+      issuedGrantKey(roomPath, memberDeviceHex)
+    ];
   return encoded === undefined
     ? undefined
     : Uint8Array.from(Buffer.from(encoded, "base64"));
@@ -502,44 +489,44 @@ export function loadIssuedRoomGrant(
 /**
  * Records the token-id of a room:member grant this identity has just minted for memberDeviceHex in roomPath, surviving a restart the same way roomTokens does. Overwrites any earlier record for the same (roomPath, member) pair -- a fresh join/invite always supersedes the grant it replaces, so only the current token-id is ever worth revoking.
  */
-export function saveIssuedRoomGrant(
+export async function saveIssuedRoomGrant(
   slot: Readonly<IdentitySlot>,
   roomPath: string,
   memberDeviceHex: string,
   tokenId: Uint8Array,
-): void {
-  const { identityFile, lockFile } = slotPaths(slot);
-  const stored = readStoredIdentityWaitingForConcurrentCreate(
-    identityFile,
-    lockFile,
+): Promise<void> {
+  await updateTokenRecords(
+    slot,
+    (records) => ({
+      issuedGrants: {
+        ...records.issuedGrants,
+        [issuedGrantKey(roomPath, memberDeviceHex)]:
+          Buffer.from(tokenId).toString("base64"),
+      },
+    }),
+    true,
   );
-  if (stored === undefined) {
-    throw new Error(
-      `no identity persisted for this slot yet -- call loadOrCreateIdentity first (${identityFile})`,
-    );
-  }
-  const issuedGrants = {
-    ...stored.issuedGrants,
-    [issuedGrantKey(roomPath, memberDeviceHex)]:
-      Buffer.from(tokenId).toString("base64"),
-  };
-  writeStoredIdentity(identityFile, { ...stored, issuedGrants });
 }
 
 /** Removes the recorded token-id for one (roomPath, member) grant, if any -- called once a kick has revoked it, so a later re-join mints and records a genuinely fresh one rather than leaving a stale entry alongside it. A no-op if none was recorded. */
-export function deleteIssuedRoomGrant(
+export async function deleteIssuedRoomGrant(
   slot: Readonly<IdentitySlot>,
   roomPath: string,
   memberDeviceHex: string,
-): void {
-  const { identityFile } = slotPaths(slot);
-  const stored = readStoredIdentity(identityFile);
-  if (stored?.issuedGrants === undefined) return;
+): Promise<void> {
   const key = issuedGrantKey(roomPath, memberDeviceHex);
-  const issuedGrants = Object.fromEntries(
-    Object.entries(stored.issuedGrants).filter(([k]) => k !== key),
+  await updateTokenRecords(
+    slot,
+    (records) =>
+      records.issuedGrants === undefined
+        ? undefined
+        : {
+            issuedGrants: Object.fromEntries(
+              Object.entries(records.issuedGrants).filter(([k]) => k !== key),
+            ),
+          },
+    false,
   );
-  writeStoredIdentity(identityFile, { ...stored, issuedGrants });
 }
 
 /** The trusted-gateway allowlist lives in one JSON file per identity directory, not per bridge slot: who may see and reach this user's agents from another machine is an operator decision about the machine, and every store on it, including each session the default cc-peer front handles, advertises itself under it. It sits beside the identity files rather than inside one, because the trusted set has no dependency on any slot's key material and GatewayTrust can be constructed before an identity is ever loaded. */
@@ -655,6 +642,8 @@ function isStoredConnectionCode(value: unknown): value is StoredConnectionCode {
   if (!("expiresAt" in value) || !("deviceId" in value)) return false;
   if (typeof value.expiresAt !== "string" || typeof value.deviceId !== "string")
     return false;
+  // A record whose expiry names no instant could never be pruned or honoured, so it is not loaded.
+  if (!isIsoTimestamp(value.expiresAt)) return false;
   if ("signature" in value && typeof value.signature !== "string") return false;
   return true;
 }
@@ -693,7 +682,9 @@ export function loadConnectionCodeLedger(
   }
   const redeemed: Record<string, string> = {};
   for (const [nonce, expiresAt] of Object.entries(redeemedRaw)) {
-    if (typeof expiresAt === "string") redeemed[nonce] = expiresAt;
+    if (typeof expiresAt === "string" && isIsoTimestamp(expiresAt)) {
+      redeemed[nonce] = expiresAt;
+    }
   }
   return { issued, redeemed };
 }

package/src/core/index.ts

@@ -33,6 +33,7 @@ export {
   releaseIdentityLock,
 } from "./identity-store.js";
 export type { IdentitySlot } from "./identity-store.js";
+export { UnusableIdentityRecordError } from "./issuer-identity-file.js";
 export type { CommsContext, CommsResult } from "./tool.js";
 export {
   buildAction,

package/src/core/iso-timestamp.ts

@@ -0,0 +1,21 @@
+/**
+ * Timestamps that arrive as text and decide whether something has expired. A text that does not parse must never read as "not yet expired", which is what comparing a failed parse (NaN) against the clock does, so every expiry in text form goes through this one parser and a caller treats `undefined` as invalid.
+ */
+
+/** The shape every timestamp this package writes has (`Date.prototype.toISOString`), and the offset form of ISO 8601 and RFC 3339 beside it: a date, `T`, a time with an optional fraction, then `Z` or a numeric offset. Anything looser (a bare year, a month name, a locale string) is parsed differently by different engines, so it is refused rather than guessed at. */
+const ISO_TIMESTAMP =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * The instant `text` names, in milliseconds since the epoch, or undefined when `text` is not an ISO 8601 timestamp in the form above or names no real instant (a month 13, say).
+ */
+export function parseIsoTimestampMs(text: string): number | undefined {
+  if (!ISO_TIMESTAMP.test(text)) return undefined;
+  const ms = Date.parse(text);
+  return Number.isNaN(ms) ? undefined : ms;
+}
+
+/** Whether `text` is a timestamp parseIsoTimestampMs accepts. */
+export function isIsoTimestamp(text: string): boolean {
+  return parseIsoTimestampMs(text) !== undefined;
+}