agent-comms 9.0.11 → 9.0.13

package/src/bridges/user/web/dist/sw.js

@@ -1 +1 @@
-(function(){var e=`agent-comms-v1`,t=[{"revision":"66fb8e407d25a3d34fd7df939ebd2e96","url":"mesh-worker.js"},{"revision":"f1ee3afb8c9e8f0d7315fd93d6457316","url":"index.html"},{"revision":"aef2de9b9f0ed47024e02762fc047436","url":"bundle.js"}].map(e=>e.url);self.addEventListener(`install`,n=>{n.waitUntil(self.caches.open(e).then(async e=>e.addAll(t)).then(async()=>self.skipWaiting()))}),self.addEventListener(`activate`,t=>{t.waitUntil(self.caches.keys().then(async t=>Promise.all(t.filter(t=>t!==e).map(async e=>self.caches.delete(e)))))});var n=200,r=300;function i(e,t){return e.method===`GET`&&t.status>=n&&t.status<r}self.addEventListener(`fetch`,t=>{if(new URL(t.request.url).pathname.startsWith(`/api/`)){t.respondWith(fetch(t.request).then(n=>{if(i(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n}).catch(async()=>self.caches.open(e).then(async e=>e.match(t.request)).then(e=>e??new Response(`Offline`,{status:503}))));return}t.respondWith(self.caches.open(e).then(async e=>e.match(t.request)).then(async n=>n||fetch(t.request).then(n=>{if(i(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n})))})})();
+(function(){var e=`agent-comms-v2`,t=[{"revision":"fa356ca4b2a4b6ec4a929516b593a3e4","url":"mesh-worker.js"},{"revision":"053013aa131ee0e62e4492d27f4beb90","url":"index.html"},{"revision":"acb589210914ac93762291f24b3f6492","url":"bundle.js"}].map(e=>e.url);self.addEventListener(`install`,n=>{n.waitUntil(self.caches.open(e).then(async e=>e.addAll(t)).then(async()=>self.skipWaiting()))});var n=`agent-comms-`;self.addEventListener(`activate`,t=>{t.waitUntil(self.caches.keys().then(async t=>Promise.all(t.filter(t=>t.startsWith(n)&&t!==e).map(async e=>self.caches.delete(e)))))});var r=200,i=300;function a(e,t){return e.method===`GET`&&t.status>=r&&t.status<i}function o(e){return e.type===`basic`&&e.status>=r&&e.status<i&&(e.headers.get(`content-type`)??``).startsWith(`text/html`)}var s=500,c=new URL(`index.html`,self.location.href).href;self.addEventListener(`fetch`,t=>{let n=new URL(t.request.url);if(t.request.mode===`navigate`){t.respondWith(fetch(t.request,{cache:`no-cache`}).then(n=>{if(t.request.method===`GET`&&o(n)){let t=n.clone();self.caches.open(e).then(async e=>e.put(c,t))}return n}).then(async t=>t.status<s?t:await(await self.caches.open(e)).match(c)??t).catch(async()=>self.caches.open(e).then(async e=>e.match(c)).then(e=>e??new Response(`Offline`,{status:503}))));return}if(n.pathname.startsWith(`/api/`)){t.respondWith(fetch(t.request).then(n=>{if(a(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n}).catch(async()=>self.caches.open(e).then(async e=>e.match(t.request)).then(e=>e??new Response(`Offline`,{status:503}))));return}t.respondWith(self.caches.open(e).then(async e=>e.match(t.request)).then(async n=>n||fetch(t.request).then(n=>{if(a(t.request,n)){let r=n.clone();self.caches.open(e).then(async e=>e.put(t.request,r))}return n})))})})();

package/src/bridges/user/web/hosted-dashboard.ts

@@ -0,0 +1,11 @@
+/**
+ * Where the hosted dashboard is served from. One definition, imported by everything that names the hosted origin: the bridge's admission of it (web-access.ts) and the tests that stand in for it.
+ *
+ * The origin is the unit a browser keeps storage apart by, so it is also the line between the dashboard and every other page that shares a host with it.
+ */
+
+/** The origin of the dashboard deployed to GitHub Pages. It discovers a bridge's server by probing loopback ports and then opens its `/ws/mesh` socket cross-origin, so its Origin is admitted from a client on this machine; every other foreign origin is refused. */
+export const HOSTED_DASHBOARD_ORIGIN = "https://exadev.github.io";
+
+/** The address a person opens to reach the hosted dashboard: its origin and the path its site is published under. */
+export const HOSTED_DASHBOARD_URL = `${HOSTED_DASHBOARD_ORIGIN}/agent-comms/`;

package/src/bridges/user/web/web-access.ts

@@ -7,6 +7,7 @@
 import * as crypto from "node:crypto";
 import * as net from "node:net";
 import * as os from "node:os";
+import { HOSTED_DASHBOARD_ORIGIN } from "./hosted-dashboard.js";
 
 /** The environment variable that opts the web server into binding beyond loopback. Its value is an IP address literal to bind: `0.0.0.0` or `::` for every interface, or one interface's own address. */
 export const WEB_HOST_ENV = "AGENT_COMMS_WEB_HOST";
@@ -38,9 +39,6 @@ const HTTP_FOUND = 302;
 /** The authentication scheme of an `Authorization` header carrying the token. Scheme names are case-insensitive (RFC 9110 section 11.1). */
 const BEARER_SCHEME = "bearer";
 
-/** The origin of the dashboard deployed to GitHub Pages. It discovers a bridge's server by probing loopback ports and then opens its `/ws/mesh` socket cross-origin, so its Origin is admitted from a client on this machine; every other foreign origin is refused. */
-export const HOSTED_DASHBOARD_ORIGIN = "https://exadev.github.io";
-
 /** How long the address sets derived from the machine's interfaces and hostname are reused. Reading them costs a system call per interface, which every request would otherwise pay; this bounds how long a newly attached interface waits to be recognised. */
 const INTERFACE_CACHE_MS = 5000;
 

package/src/cli-main.ts

@@ -35,6 +35,7 @@ import { runTui } from "./bridges/user/tui.js";
 import { runCli } from "./bridges/user/cli.js";
 import { readHiddenLine, runAccountCommand } from "./account-cli.js";
 import { openMachineAccountStore } from "./account-join-cli.js";
+import { UnusableIdentityRecordError } from "./core/issuer-identity-file.js";
 
 // ---------------------------------------------------------------------------
 // Zod schemas for config files
@@ -289,10 +290,13 @@ function runBridge(
     );
     process.exit(1);
   }
-  Promise.resolve(bridge.run(options)).catch((err: unknown) => {
-    console.error(err);
-    process.exit(1);
-  });
+  Promise.resolve(bridge.run(options)).catch(exitWithError);
+}
+
+/** Prints why a command could not start and exits non-zero. An unusable identity file's message already says what to do about it, so it is printed without the stack trace that would bury it. */
+function exitWithError(err: unknown): never {
+  console.error(err instanceof UnusableIdentityRecordError ? err.message : err);
+  process.exit(1);
 }
 
 function parseNameArg(args: readonly string[]): {
@@ -314,18 +318,12 @@ function parseNameArg(args: readonly string[]): {
 
 function runChat(args: readonly string[]): void {
   const { name } = parseNameArg(args);
-  runTui(name).catch((err: unknown) => {
-    console.error(err);
-    process.exit(1);
-  });
+  runTui(name).catch(exitWithError);
 }
 
 function runUserCli(cliCommand: string, args: readonly string[]): void {
   const { name, rest } = parseNameArg(args);
-  runCli(cliCommand, rest, name).catch((err: unknown) => {
-    console.error(err);
-    process.exit(1);
-  });
+  runCli(cliCommand, rest, name).catch(exitWithError);
 }
 
 // ---------------------------------------------------------------------------

package/src/core/account-bundle.ts

@@ -30,6 +30,8 @@ const SALT_BYTES = 16;
 const KEY_BYTES = 32;
 /** GCM's specified IV length. */
 const IV_BYTES = 12;
+/** GCM's full-length authentication tag. A shorter tag is weaker evidence that the ciphertext is untouched, and Node accepts one unless the length is pinned, so the length is checked wherever a tag comes from outside. */
+const TAG_BYTES = 16;
 /** The shortest passphrase an export accepts. Twelve characters is the length NCSC and NIST guidance treat as the floor for a passphrase protecting something offline-attackable; the scrypt cost above does the rest. */
 export const MIN_ACCOUNT_PASSPHRASE_LENGTH = 12;
 
@@ -38,6 +40,22 @@ const BUNDLE_AAD = Buffer.from(ACCOUNT_BUNDLE_PREFIX);
 
 const base64url = z.string().regex(/^[A-Za-z0-9_-]*$/);
 
+/** Base64url text that decodes to exactly `bytes` bytes. */
+function base64urlBytes(bytes: number): z.ZodType<string> {
+  return base64url.refine(
+    (text) => Buffer.from(text, "base64url").length === bytes,
+    `must decode to ${String(bytes)} bytes`,
+  );
+}
+
+/** The parts of an envelope sealed with AES-256-GCM, each at the length `seal` writes and GCM specifies. */
+const gcmFields = {
+  iv: base64urlBytes(IV_BYTES),
+  tag: base64urlBytes(TAG_BYTES),
+  /** The ciphertext: its length is whatever the plaintext was. */
+  ct: base64url,
+};
+
 /** What an account export or a join carries: the PEM private key and the name the account asserts for itself, if it has one. */
 export interface AccountContents {
   privateKey: string;
@@ -80,19 +98,16 @@ function parseContents(plaintext: string, damaged: string): AccountContents {
 const passphraseEnvelopeSchema = z
   .object({
     kdf: z.literal("scrypt"),
-    n: z.number().int().positive(),
-    r: z.number().int().positive(),
-    p: z.number().int().positive(),
-    salt: base64url,
-    iv: base64url,
-    tag: base64url,
-    ct: base64url,
+    // Exactly what this build writes. Above it, reading a bundle would cost more time and memory than writing one. Below it, a bundle would be accepted at a cost that does not protect the passphrase: every released version has written these parameters and no others, so nothing older is refused by requiring them, and a bundle sealed at a lower cost by another tool is refused.
+    n: z.literal(SCRYPT_COST),
+    r: z.literal(SCRYPT_BLOCK_SIZE),
+    p: z.literal(SCRYPT_PARALLELISM),
+    salt: base64urlBytes(SALT_BYTES),
+    ...gcmFields,
   })
   .strict();
 
-const inviteEnvelopeSchema = z
-  .object({ iv: base64url, tag: base64url, ct: base64url })
-  .strict();
+const inviteEnvelopeSchema = z.object(gcmFields).strict();
 
 function seal(
   key: Buffer,
@@ -109,19 +124,20 @@ function seal(
   };
 }
 
-/** The plaintext of a sealed envelope, or undefined if the key is wrong or the envelope was altered. */
+/** The plaintext of a sealed envelope, or undefined if the key is wrong or the envelope was altered. The envelope's iv and tag have already been checked to be the lengths `seal` writes, and the cipher is set to accept only a full-length tag as well, so a shortened one cannot authenticate. */
 function open(
   key: Buffer,
   envelope: Readonly<{ iv: string; tag: string; ct: string }>,
 ): string | undefined {
-  const decipher = createDecipheriv(
-    "aes-256-gcm",
-    key,
-    Buffer.from(envelope.iv, "base64url"),
-  );
-  decipher.setAAD(BUNDLE_AAD);
-  decipher.setAuthTag(Buffer.from(envelope.tag, "base64url"));
   try {
+    const decipher = createDecipheriv(
+      "aes-256-gcm",
+      key,
+      Buffer.from(envelope.iv, "base64url"),
+      { authTagLength: TAG_BYTES },
+    );
+    decipher.setAAD(BUNDLE_AAD);
+    decipher.setAuthTag(Buffer.from(envelope.tag, "base64url"));
     return Buffer.concat([
       decipher.update(Buffer.from(envelope.ct, "base64url")),
       decipher.final(),
@@ -166,7 +182,7 @@ export function sealAccountBundle(
   return `${ACCOUNT_BUNDLE_PREFIX}${Buffer.from(JSON.stringify(envelope)).toString("base64url")}`;
 }
 
-/** The account contents a bundle holds. Throws INVALID_BUNDLE for text that is not a bundle this build can read, and WRONG_PASSPHRASE when the passphrase does not open it. The cost parameters are read from the bundle but capped at this build's own, so a crafted bundle cannot make an import run for hours. */
+/** The account contents a bundle holds. Throws INVALID_BUNDLE for text that is not a bundle this build can read (including one whose cost parameters, salt, iv or authentication tag are not in the form this build writes), and WRONG_PASSPHRASE when the passphrase does not open it. The cost parameters in the bundle must be exactly the ones this build writes, so reading a bundle costs no more than writing one, no weak derivation is accepted, and nothing fails with a raw error. */
 export function openAccountBundle(
   bundle: string,
   passphrase: string,
@@ -187,12 +203,7 @@ export function openAccountBundle(
     throw new CommsError("The account bundle is damaged", "INVALID_BUNDLE");
   }
   const envelope = passphraseEnvelopeSchema.safeParse(decoded);
-  if (
-    !envelope.success ||
-    envelope.data.n > SCRYPT_COST ||
-    envelope.data.r > SCRYPT_BLOCK_SIZE ||
-    envelope.data.p > SCRYPT_PARALLELISM
-  ) {
+  if (!envelope.success) {
     throw new CommsError("The account bundle is damaged", "INVALID_BUNDLE");
   }
   const key = passphraseKey(

package/src/core/account-join.ts

@@ -26,6 +26,7 @@ import {
 import type { GatewayTrust } from "./gateway-trust.js";
 import type { MeshStoreIdentity } from "./mesh-store-shared.js";
 import { parseDisplayName } from "./display-name.js";
+import { parseIsoTimestampMs } from "./iso-timestamp.js";
 import { isDeviceIdHex } from "./room-path.js";
 import { CommsError, requireDisplayName } from "./store.js";
 import type { MeshTransport } from "./transport.js";
@@ -187,7 +188,8 @@ export class AccountJoin {
   private pruneExpired(): void {
     const now = this.deps.requireIdentity().clock.now();
     for (const [nonce, invite] of this.invites) {
-      if (Date.parse(invite.secret.expiresAt) > now) continue;
+      const expiresAtMs = parseIsoTimestampMs(invite.secret.expiresAt);
+      if (expiresAtMs !== undefined && expiresAtMs > now) continue;
       this.invites.delete(nonce);
       invite.settle("expired");
     }
@@ -232,7 +234,7 @@ export class AccountJoin {
     }
     const contents = openAccountKeyFromInvite(sealed, candidate);
     const current = this.deps.requireIdentity();
-    const { identity, replacedFile } = importAccountKey(
+    const { identity, replacedFile } = await importAccountKey(
       current.userIdentityOptions,
       contents,
     );
@@ -243,6 +245,7 @@ export class AccountJoin {
         userIdentityOptions: current.userIdentityOptions,
         userIdentity: identity,
         clock: current.clock,
+        onDamagedEntry: current.accountLedger.reportDamagedEntry,
       }),
     });
     this.trustOwnAccount();

package/src/core/account-ledger-crypto.ts

@@ -138,7 +138,10 @@ export function openLedgerEntry(
   }
   const iv = sealed.subarray(VERSION_BYTES, VERSION_BYTES + IV_BYTES);
   const tag = sealed.subarray(VERSION_BYTES + IV_BYTES, headerBytes);
-  const decipher = createDecipheriv("aes-256-gcm", keys.entryKey, iv);
+  // The tag is the fixed TAG_BYTES slice above; pinning the length as well means Node can never accept a shortened one if the layout changes.
+  const decipher = createDecipheriv("aes-256-gcm", keys.entryKey, iv, {
+    authTagLength: TAG_BYTES,
+  });
   decipher.setAAD(associatedData(logId, seq));
   decipher.setAuthTag(tag);
   try {

package/src/core/account-ledger-store.ts

@@ -7,7 +7,10 @@ import { createNodeFsStorage } from "wire-mesh-core/adapters/node-fs-storage";
 import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
 import type { Clock } from "wire-mesh-core/ports/clock";
 import { generateWriterNonce } from "./account-ledger-crypto.js";
-import { AccountLedger } from "./account-ledger.js";
+import {
+  AccountLedger,
+  type LedgerEntryDamagedError,
+} from "./account-ledger.js";
 import type { PeerIdentity } from "./identity.js";
 import { createFileLedgerLock } from "./ledger-lock.js";
 import {
@@ -24,6 +27,8 @@ export interface OpenAccountLedgerOptions {
   /** The account's identity as loadOrCreateUserIdentity returned it. */
   userIdentity: Readonly<PeerIdentity>;
   clock: Clock;
+  /** Where an unreadable ledger entry is reported; see AccountLedgerDeps.onDamagedEntry. */
+  onDamagedEntry?: ((error: LedgerEntryDamagedError) => void) | undefined;
 }
 
 /** The directory an account's ledger is stored in on this machine. Named by the account's device-id, so a machine that imports a different account starts that account's ledger afresh instead of mixing two accounts' logs. */
@@ -49,18 +54,21 @@ export async function openAccountLedger(
   );
   const ledger = new AccountLedger({
     accountPrivateKey: options.userIdentity.privateKey,
-    writerNonce: loadOrCreateLedgerWriterNonce(
+    writerNonce: await loadOrCreateLedgerWriterNonce(
       options.userIdentityOptions,
       generateWriterNonce,
     ),
     storage: createNodeFsStorage({ dir }),
     lock: createFileLedgerLock(`${dir}.lock`),
     clock: options.clock,
+    ...(options.onDamagedEntry !== undefined && {
+      onDamagedEntry: options.onDamagedEntry,
+    }),
   });
   const legacy = readLegacyIssuedGrants(options.userIdentityOptions);
   if (legacy.length > 0) {
     await ledger.recordGrants(legacy);
-    clearLegacyIssuedGrants(options.userIdentityOptions, legacy);
+    await clearLegacyIssuedGrants(options.userIdentityOptions, legacy);
   }
   return ledger;
 }

package/src/core/account-ledger.ts

@@ -4,6 +4,8 @@
  * Each machine appends to a writer log of its own rather than all of them sharing one: a data-domain log is single-writer, and two machines appending to one log while apart would both write the same sequence number and fork it, silently losing one side's grants. A writer log's id is self-authenticating (account-ledger-crypto.ts), so any account holder recognises every writer log it is offered without a roster, and the ledger is the union of all of them.
  *
  * Holding a replica grants no authority: an entry is sealed under a key derived from the account key, so a replica held by anyone else is ciphertext they can neither read nor forge, and minting or revoking still needs the account's private key.
+ *
+ * A single entry that cannot be read never blocks the rest of the ledger. Revoking is the operation the ledger exists for, and storage can lose or damage an entry, so an unreadable entry that stopped listing and revoking would turn one damaged file into a permanent inability to revoke anything for that account. Each unreadable entry is instead skipped, and a skipped entry is never silent: it is reported once per ledger as a LedgerEntryDamagedError (to `onDamagedEntry`, stderr by default), naming its log and position, listed by `unreadableEntries()` for `whoami`, and counted in the result of every read that met it (`outstandingGrantsChecked` and `revocations`), so a caller that revokes can tell its outcome is incomplete. An unreadable entry may hold a grant or a revocation: a grant recorded only in it is not listed, so it is not revoked, and a revocation recorded only in it is not applied by this machine, until the entry is repaired or replaced from another machine's replica. Revocations in the readable entries are still applied, and a revocation announced over the mesh still reaches the store.
  */
 
 import {
@@ -101,6 +103,36 @@ export interface AccountLedgerDeps {
   /** Serialises every read and write of `storage` across every bridge sharing it: appends to this machine's writer log, replicated entries stored for another machine's, and every read of either. The store's writes are not atomic (a file is truncated, then written), so a read racing another bridge's write could see an empty head and treat a log as empty. */
   lock: LedgerLock;
   clock: Clock;
+  /** Called once for each ledger entry that could not be read. Defaults to a line on stderr. */
+  onDamagedEntry?: (error: LedgerEntryDamagedError) => void;
+}
+
+/** Why an entry that opened under the account key is unreadable. Fixed text: the decoder's own message can quote the entry's content, and the report is printed whole. */
+export const UNDECODABLE_REASON =
+  "its content is not a record this build can decode";
+
+/** A ledger entry that is stored but cannot be read: it does not open under the account's key for its log and position, or what it holds is not a record this build can decode. */
+export class LedgerEntryDamagedError extends Error {
+  constructor(
+    /** The writer log the entry belongs to, as hex. */
+    public readonly log: string,
+    /** The entry's position in that log, counting from one. */
+    public readonly seq: number,
+    /** Why it could not be read. */
+    public readonly reason: string,
+  ) {
+    super(
+      `account ledger entry ${String(seq)} of writer log ${log} cannot be read (${reason}); it was skipped, so a grant or a revocation recorded only in it is not read: such a grant is not listed or revoked, and such a revocation is not applied here, until the entry is repaired or replaced from another machine's replica of this account`,
+    );
+    this.name = "LedgerEntryDamagedError";
+  }
+}
+
+/** The default place an unreadable ledger entry is reported: one line on stderr. */
+export function reportDamagedEntryToStderr(
+  error: Readonly<LedgerEntryDamagedError>,
+): void {
+  process.stderr.write(`agent-comms: ${error.message}\n`);
 }
 
 /** Answers and stores the data-domain frames for the account's writer logs; what a transport needs of the ledger to replicate it. */
@@ -113,16 +145,36 @@ export interface AccountLedgerReplica {
   ) => Promise<DataHaveFrame | DataRequestFrame | DataEntriesFrame | null>;
   /** A data-have for every account log this machine holds, to offer peers. */
   announcements: () => Promise<DataHaveFrame[]>;
+  /** The stored entries that could not be read, as far as reads so far have found. */
+  unreadableEntries: () => readonly LedgerEntryDamagedError[];
+}
+
+/** What a read of the ledger could not read: the number of stored entries that were skipped because they cannot be opened or decoded. Zero means the read was complete. */
+export interface LedgerGaps {
+  unreadable: number;
 }
 
 const versionProbeSchema = z.object({ v: z.number() });
 
 const HEAD_KEY_PATTERN = /^data\/([0-9a-f]+)\/head$/;
 
+/** Where a store's unreadable ledger entries are reported: its own error handler once it has one, otherwise stderr, since a handler that is not assigned yet or not at all must not make an entry that can hide a grant go unreported. `getOnError` is read on every report. */
+export function damagedEntryReporter(
+  getOnError: () => ((error: Error) => void) | undefined,
+): (error: LedgerEntryDamagedError) => void {
+  return (error) => {
+    (getOnError() ?? reportDamagedEntryToStderr)(error);
+  };
+}
+
 export class AccountLedger implements AccountLedgerReplica {
   /** This machine's own writer log. */
   readonly writerLog: DeviceId;
+  /** Where this ledger reports an entry it cannot read; also what a ledger opened for another account on the same machine is given, so the destination follows the store and not the account. */
+  readonly reportDamagedEntry: (error: LedgerEntryDamagedError) => void;
   private readonly keys: AccountLedgerKeys;
+  /** Every entry a read has found unreadable, keyed by log and position, each reported once. */
+  private readonly damaged = new Map<string, LedgerEntryDamagedError>();
   private readonly revocationListeners = new Set<
     (entry: RevocationEntry) => void
   >();
@@ -130,6 +182,7 @@ export class AccountLedger implements AccountLedgerReplica {
   constructor(private readonly deps: Readonly<AccountLedgerDeps>) {
     this.keys = deriveAccountLedgerKeys(deps.accountPrivateKey);
     this.writerLog = writerLogId(this.keys, deps.writerNonce);
+    this.reportDamagedEntry = deps.onDamagedEntry ?? reportDamagedEntryToStderr;
   }
 
   /** Records that the principal minted `tokenId` for `subjectHex`. */
@@ -191,14 +244,23 @@ export class AccountLedger implements AccountLedgerReplica {
     ]);
   }
 
-  /** Every grant of `kind` for `subjectHex` that some machine of the account recorded and none has revoked, oldest first. */
+  /** Every grant of `kind` for `subjectHex` that some machine of the account recorded and none has revoked, oldest first, among the entries that can be read. A caller that goes on to revoke uses outstandingGrantsChecked, which also says whether entries were skipped. */
   async outstandingGrants(
     kind: IssuedGrantKind,
     subjectHex: string,
   ): Promise<OutstandingGrant[]> {
+    return (await this.outstandingGrantsChecked(kind, subjectHex)).grants;
+  }
+
+  /** outstandingGrants with the number of entries the read had to skip: when it is above zero, a grant recorded only in a skipped entry is not in `grants`, and revoking `grants` does not make the subject safe. */
+  async outstandingGrantsChecked(
+    kind: IssuedGrantKind,
+    subjectHex: string,
+  ): Promise<{ grants: OutstandingGrant[] } & LedgerGaps> {
     const granted = new Map<string, OutstandingGrant>();
     const revoked = new Set<string>();
-    for (const record of await this.records()) {
+    const { records, unreadable } = await this.records();
+    for (const record of records) {
       if (record.kind !== kind || record.subject !== subjectHex) continue;
       const key = Buffer.from(record.tokenId).toString("hex");
       if (record.op === "revoke") {
@@ -210,17 +272,28 @@ export class AccountLedger implements AccountLedgerReplica {
         });
       }
     }
-    return [...granted]
-      .filter(([key]) => !revoked.has(key))
-      .map(([, grant]) => grant)
-      .sort((a, b) => a.at - b.at);
+    return {
+      grants: [...granted]
+        .filter(([key]) => !revoked.has(key))
+        .map(([, grant]) => grant)
+        .sort((a, b) => a.at - b.at),
+      unreadable,
+    };
   }
 
-  /** Every revocation entry the ledger holds, from every machine, for a RevocationView to learn at start-up. */
-  async revocations(): Promise<RevocationEntry[]> {
-    return (await this.records()).flatMap((record) =>
-      record.op === "revoke" ? [record.revocation] : [],
-    );
+  /** Every revocation entry the readable part of the ledger holds, from every machine, for a RevocationView to learn at start-up, and how many entries were skipped: a revocation recorded only in one of those is not in `entries`. */
+  async revocations(): Promise<{ entries: RevocationEntry[] } & LedgerGaps> {
+    const { records, unreadable } = await this.records();
+    return {
+      entries: records.flatMap((record) =>
+        record.op === "revoke" ? [record.revocation] : [],
+      ),
+      unreadable,
+    };
+  }
+
+  unreadableEntries(): readonly LedgerEntryDamagedError[] {
+    return [...this.damaged.values()];
   }
 
   ownsLog(peer: DeviceId): boolean {
@@ -274,8 +347,12 @@ export class AccountLedger implements AccountLedgerReplica {
       handleDataEntries(storage, frame),
     );
     if (!stored.ok) return null;
-    for (const plaintext of plaintexts) {
-      const record = decodeRecord(plaintext);
+    for (const [index, plaintext] of plaintexts.entries()) {
+      const record = this.decodeOrReport(
+        frame.peer,
+        firstSeq + index,
+        plaintext,
+      );
       if (record?.op !== "revoke") continue;
       for (const listener of this.revocationListeners) {
         listener(record.revocation);
@@ -316,8 +393,34 @@ export class AccountLedger implements AccountLedgerReplica {
     return logs;
   }
 
-  /** Every record in every held writer log. Throws on an entry that does not open: handleDataFrame and append never store one, so it means the storage was damaged outside the ledger, and carrying on would hide grants that can then never be revoked. */
-  private async records(): Promise<LedgerRecord[]> {
+  /** The record an entry holds, or undefined after noting why it cannot be read (or, silently, for a record of a later format version). */
+  private decodeOrReport(
+    log: DeviceId,
+    seq: number,
+    plaintext: Uint8Array,
+  ): LedgerRecord | undefined {
+    try {
+      return decodeRecord(plaintext);
+    } catch {
+      this.noteDamaged(log, seq, UNDECODABLE_REASON);
+      return undefined;
+    }
+  }
+
+  /** Remembers an unreadable entry and reports it the first time it is met. */
+  private noteDamaged(log: DeviceId, seq: number, reason: string): void {
+    const hex = deviceIdToHex(log);
+    const key = `${hex}:${String(seq)}`;
+    if (this.damaged.has(key)) return;
+    const error = new LedgerEntryDamagedError(hex, seq, reason);
+    this.damaged.set(key, error);
+    this.reportDamagedEntry(error);
+  }
+
+  /** Every readable record in every held writer log, in the order stored, and how many entries were skipped. An entry that cannot be read is noted and skipped (see the module comment for why that is not a failure). handleDataFrame and append never store one, so it means the storage was damaged outside the ledger or a holder of the account key wrote one this build cannot decode. */
+  private async records(): Promise<
+    { records: LedgerRecord[] } & { unreadable: number }
+  > {
     const held = await this.deps.lock.run(async () =>
       Promise.all(
         (await this.heldLogs()).map(async (log) => ({
@@ -327,20 +430,32 @@ export class AccountLedger implements AccountLedgerReplica {
       ),
     );
     const records: LedgerRecord[] = [];
+    let unreadable = 0;
     for (const { log, entries } of held) {
       entries.forEach((sealed, index) => {
         const seq = index + 1;
         const plaintext = openLedgerEntry(this.keys, log, seq, sealed);
         if (plaintext === undefined) {
-          throw new Error(
-            `account ledger entry ${String(seq)} of writer log ${deviceIdToHex(log)} does not open under this account's key`,
+          this.noteDamaged(
+            log,
+            seq,
+            "it does not open under this account's key",
           );
+          unreadable += 1;
+          return;
+        }
+        let record: LedgerRecord | undefined;
+        try {
+          record = decodeRecord(plaintext);
+        } catch {
+          this.noteDamaged(log, seq, UNDECODABLE_REASON);
+          unreadable += 1;
+          return;
         }
-        const record = decodeRecord(plaintext);
         if (record !== undefined) records.push(record);
       });
     }
-    return records;
+    return { records, unreadable };
   }
 }
 
@@ -378,8 +493,15 @@ export function followLedgerRevocations(
       }, report);
   };
   const unsubscribe = identity.accountLedger.onReplicatedRevocation(learn);
-  identity.accountLedger.revocations().then((entries) => {
+  identity.accountLedger.revocations().then(({ entries, unreadable }) => {
     entries.forEach(learn);
+    if (unreadable > 0) {
+      report(
+        new Error(
+          `${String(unreadable)} account ledger entries cannot be read, so a revocation recorded only in them is not applied on this machine until they are repaired or replaced from another machine's replica`,
+        ),
+      );
+    }
   }, report);
   return unsubscribe;
 }

package/src/core/bridge-mesh.ts

@@ -24,6 +24,7 @@ import { FIRST_CONTACT_PORT } from "./first-contact.js";
 import { CommsTool } from "./tool.js";
 import { WireMeshTransport } from "./wire-mesh-transport.js";
 import { loadOrCreateIdentity, oplogDirFor } from "./identity-store.js";
+import { damagedEntryReporter } from "./account-ledger.js";
 import { openAccountLedger } from "./account-ledger-store.js";
 import type { IdentitySlot } from "./identity-store.js";
 import { toIdentityPort } from "./wire-mesh-identity.js";
@@ -126,6 +127,8 @@ export function createBridgeMeshSyncFromIdentity(
     discovery: store.discovery,
     naming: store.naming,
     getNewerVersionIfAny: () => versionChecker.getNewerVersionIfAny(),
+    getUnreadableLedgerEntries: () =>
+      store.accountLedger?.unreadableEntries().length ?? 0,
   });
   const revocation = createRevocationView();
   return {
@@ -144,6 +147,7 @@ export function createBridgeMeshSyncFromIdentity(
           userIdentityOptions,
           userIdentity,
           clock,
+          onDamagedEntry: damagedEntryReporter(() => store.onError),
         }),
         userIdentityOptions,
         machineIdentity: await toIdentityPort(machineIdentity),

package/src/core/bridge.ts

@@ -117,19 +117,39 @@ export const MCP_TOOL_PARAMS = z.object({
   /** A remote gateway's own device-id (hex), for gateway_trust/gateway_untrust, for gateway_redeem_connection_code (the code's own embedded deviceId field), and the device-id petname_set/petname_clear label. */
   device: z.string().optional(),
   /** The connection code's own nonce (gateway_redeem_connection_code). */
-  code: z.string().optional(),
+  code: z
+    .string()
+    .optional()
+    .describe(
+      "gateway_redeem_connection_code: the code's nonce. An unsigned connection code is a bearer hint, not authentication: redeeming it trusts whatever device-id its text names, whoever wrote it, so it is not a way to establish trust in a stranger. Supply publicKey or fingerprint to require a signature from a key you already trust.",
+    ),
   /** ISO-8601 expiry for gateway_generate_connection_code's ttlMs override, or the redeemed code's own expiresAt field for gateway_redeem_connection_code. */
   expiresAt: z.string().optional(),
   /** ttlMs override for gateway_generate_connection_code; defaults to DEFAULT_CONNECTION_CODE_TTL_MS when omitted. */
   ttlMs: z.number().optional(),
   /** Armored PGP private key to sign a generated code with (gateway_generate_connection_code), or armored PGP public key to verify a redeemed code's signature against (gateway_redeem_connection_code). Both are supplied per call -- agent-comms never generates, stores, or manages PGP key material itself. */
   privateKey: z.string().optional(),
-  publicKey: z.string().optional(),
+  publicKey: z
+    .string()
+    .optional()
+    .describe(
+      "gateway_redeem_connection_code: armored PGP public key to verify the code's signature against. Supplying it makes an unsigned code refused.",
+    ),
   /** Passphrase for privateKey, if it is passphrase-protected (gateway_generate_connection_code). */
   passphrase: z.string().optional(),
   /** The redeemed code's own signature field (gateway_redeem_connection_code), or a PGP fingerprint the caller already independently trusts, used either to pin a supplied publicKey or to fetch one from a keyserver when publicKey is omitted. */
-  signature: z.string().optional(),
-  fingerprint: z.string().optional(),
+  signature: z
+    .string()
+    .optional()
+    .describe(
+      "gateway_redeem_connection_code: the code's detached PGP signature, when it has one.",
+    ),
+  fingerprint: z
+    .string()
+    .optional()
+    .describe(
+      "gateway_redeem_connection_code: a PGP fingerprint you already trust. Supplying it makes an unsigned code refused, and the signing key must match it.",
+    ),
   /** For gateway_trust/gateway_untrust (and dm_admit, where `target` names it): when true, the id names a user principal (agent-comms#187) rather than a bare remote device-id (agent-comms#193). */
   principal: z.boolean().optional(),
   /** For gateway_trust/gateway_untrust: when true, the id names a machine (agent-comms#343), whose devices (every bridge one OS account runs on that host) are trusted or revoked at once. */