agent-comms 9.0.11 → 9.0.13

package/src/core/store.ts

@@ -73,6 +73,16 @@ export function requireDisplayName(raw: string, what: string): string {
   return name;
 }
 
+/** The delivery files already reported by this process, each with the reason given, so a file that stays where it is is reported once and not on every drain. */
+const reportedDeliveryFiles = new Set<string>();
+
+function reportDeliveryFileOnce(filePath: string, problem: string): void {
+  const key = `${filePath}\n${problem}`;
+  if (reportedDeliveryFiles.has(key)) return;
+  reportedDeliveryFiles.add(key);
+  process.stderr.write(`agent-comms: ${filePath} ${problem}\n`);
+}
+
 /** An agent's registered name is its self-asserted name (display-name.ts), so it is held to the same rules as it is registered or changed: requireDisplayName for "An agent name". */
 export function requireAgentName(raw: string): string {
   return requireDisplayName(raw, "An agent name");
@@ -642,35 +652,50 @@ export class FileStore implements CommsStore {
     await this.writeJsonFile(path.join(dir, `${id}.json`), event);
   }
 
+  /**
+   * Returns the events queued for agentId, oldest message first, and removes each from the queue as it is returned. A file that cannot be read or parsed is left in place and reported on stderr with its name, and every other file is still drained, so one bad file never costs the events around it; a file that cannot be removed is reported the same way and its event is not returned, so it is delivered once, on a later drain, not twice. Each file is reported once per process however often the queue is drained, since a file that stays in place would otherwise be reported on every drain.
+   */
   async drainDelivery(agentId: string): Promise<DeliveryEvent[]> {
     const dir = this.deliveryDir(agentId);
+    let files: string[];
     try {
-      const files = await fs.readdir(dir);
-      const events: DeliveryEvent[] = [];
-      for (const file of files) {
-        if (!file.endsWith(".json")) continue;
-        const event = DeliveryEventSchema.parse(
-          await this.readJsonFile(path.join(dir, file)),
-        );
-        events.push(event);
-        await fs.unlink(path.join(dir, file));
-      }
-      // Same fixed timestamp form as readRoomMessages sorts on.
-      events.sort((a, b) => {
-        const ta =
-          a.type === "room_message" || a.type === "dm"
-            ? a.message.timestamp
-            : "";
-        const tb =
-          b.type === "room_message" || b.type === "dm"
-            ? b.message.timestamp
-            : "";
-        return compareCodeUnits(ta, tb);
-      });
-      return events;
+      files = await fs.readdir(dir);
     } catch {
       return [];
     }
+    const events: DeliveryEvent[] = [];
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      const filePath = path.join(dir, file);
+      let event: DeliveryEvent;
+      try {
+        event = DeliveryEventSchema.parse(await this.readJsonFile(filePath));
+      } catch {
+        reportDeliveryFileOnce(
+          filePath,
+          "is not a readable delivery event; it was left in place",
+        );
+        continue;
+      }
+      try {
+        await fs.unlink(filePath);
+      } catch {
+        reportDeliveryFileOnce(
+          filePath,
+          "could not be removed; its event was not returned",
+        );
+        continue;
+      }
+      events.push(event);
+    }
+    events.sort((a, b) => {
+      const ta =
+        a.type === "room_message" || a.type === "dm" ? a.message.timestamp : "";
+      const tb =
+        b.type === "room_message" || b.type === "dm" ? b.message.timestamp : "";
+      return compareCodeUnits(ta, tb);
+    });
+    return events;
   }
 
   private async deliverToMembers(

package/src/core/tool.ts

@@ -36,6 +36,7 @@ import type { CommsStore } from "./comms-store.js";
 import type { CapabilityToken } from "wire-mesh-core/generated/protocol";
 import type { DiscoveryManager } from "./discovery.js";
 import { CommsError } from "./store.js";
+import type { LedgerGaps } from "./account-ledger.js";
 import { getOwnPackageVersion } from "./package-version.js";
 import { describeDeliveryFor } from "./send-outcome.js";
 import {
@@ -178,7 +179,8 @@ export interface MeshOnlyFeatures {
   removeTrustedGatewayMachine?: (deviceHex: string) => void;
   listTrustedGatewayMachines?: () => string[];
   /** Withdraws the dm:send grant issued for bearerId. */
-  revokeAgentDmAccess?: (bearerId: string) => Promise<void>;
+  revokeAgentDmAccess?: (bearerId: string) => Promise<LedgerGaps>;
+
   removeTrustedGatewayPrincipal?: (deviceHex: string) => void;
   listTrustedGatewayPrincipals?: () => string[];
   /** Devices trusted only because a trusted principal or machine vouches for them (a verified membership proof), with that issuer. */
@@ -248,6 +250,8 @@ export interface CommsToolOptions {
   readonly naming?: Naming;
   /** Returns the newest npm release known to be available, or undefined when none is known (no checker wired up, no successful check yet, or this bridge is already current). Wired at bridge construction time by a VersionDriftChecker (see version-check.ts) -- optional so every call site, and every test that has no interest in drift reporting, is unaffected. */
   readonly getNewerVersionIfAny?: () => string | undefined;
+  /** How many stored account ledger entries cannot be read, for whoami; omitted when the store has no account ledger. */
+  readonly getUnreadableLedgerEntries?: () => number;
   /** Fetches a signer's armored PGP public key by fingerprint, used by gateway_redeem_connection_code when the caller supplies a fingerprint but not the key text itself. Defaults to the real keys.openpgp.org lookup (pgp-keyserver.ts); a test that would otherwise trigger real network I/O injects a fake resolver instead, the same reasoning bridge-mesh.ts's own fetchLatestVersion override already establishes for getNewerVersionIfAny above. */
   readonly fetchPgpPublicKeyByFingerprintImpl?: (
     fingerprint: string,
@@ -261,6 +265,7 @@ export class CommsTool {
   private readonly discovery: DiscoveryManager | undefined;
   private readonly naming: Naming | undefined;
   private readonly getNewerVersionIfAny: (() => string | undefined) | undefined;
+  private readonly getUnreadableLedgerEntries: (() => number) | undefined;
   private readonly fetchPgpPublicKeyByFingerprintImpl: (
     fingerprint: string,
   ) => Promise<string>;
@@ -273,11 +278,13 @@ export class CommsTool {
       discovery,
       naming,
       getNewerVersionIfAny,
+      getUnreadableLedgerEntries,
       fetchPgpPublicKeyByFingerprintImpl = fetchPgpPublicKeyByFingerprint,
     } = options ?? {};
     this.discovery = discovery;
     this.naming = naming;
     this.getNewerVersionIfAny = getNewerVersionIfAny;
+    this.getUnreadableLedgerEntries = getUnreadableLedgerEntries;
     this.fetchPgpPublicKeyByFingerprintImpl =
       fetchPgpPublicKeyByFingerprintImpl;
   }
@@ -456,6 +463,12 @@ export class CommsTool {
     const lines = [
       `Updated: name=${agent.name}, visibility=${agent.visibility}, status=${agent.status}, version=${getOwnPackageVersion()}${formatSelfVersionSuffix(this.store.getCcPeerVersion)}`,
     ];
+    const unreadableLedger = this.getUnreadableLedgerEntries?.() ?? 0;
+    if (unreadableLedger > 0) {
+      lines.push(
+        `Account ledger: ${String(unreadableLedger)} unreadable entries; a grant or revocation recorded only in them is not applied here until they are repaired or replaced from another machine's replica`,
+      );
+    }
     const updateAvailable = this.formatUpdateAvailableLine();
     if (updateAvailable !== undefined) lines.push(updateAvailable);
     return {

package/src/core/types.ts

@@ -7,6 +7,7 @@
  */
 
 import { z } from "zod";
+import { isIsoTimestamp } from "./iso-timestamp.js";
 
 // ---------------------------------------------------------------------------
 // Schema-attached type guard helper
@@ -312,11 +313,16 @@ export interface NetworkInterface {
 // ConnectionCode
 // ---------------------------------------------------------------------------
 
-/** A single-use, short-lived artifact bootstrapping GatewayTrust between two devices that have never established a mesh connection (agent-comms#188): `code`/`expiresAt` answer freshness/liveness and are always checked; `signature` is an optional detached PGP signature (armored) over `${code}:${expiresAt}:${deviceId}`, checked only when present, never required -- a device with no PGP identity still generates and redeems a bare code. */
+/** An ISO 8601 timestamp (iso-timestamp.ts): text that names no instant is refused where it enters, so it can never be compared against the clock as if it were one. */
+const IsoTimestampSchema = z
+  .string()
+  .refine(isIsoTimestamp, "must be an ISO 8601 timestamp");
+
+/** A single-use, short-lived artifact bootstrapping GatewayTrust between two devices that have never established a mesh connection (agent-comms#188): `code`/`expiresAt` answer freshness/liveness and are always checked, and `expiresAt` must be an ISO 8601 timestamp; `signature` is an optional detached PGP signature (armored) over `${code}:${expiresAt}:${deviceId}`. An unsigned code is a bearer hint, not authentication of whoever issued it: redeeming one trusts whatever device-id it names. A redeemer who supplies a public key or fingerprint to check it against requires a signature, and the code is refused without one. */
 export const ConnectionCodeSchema = defineSchema(
   z.object({
     code: z.string(),
-    expiresAt: z.string(),
+    expiresAt: IsoTimestampSchema,
     deviceId: z.string(),
     signature: z.string().optional(),
   }),
@@ -529,7 +535,7 @@ export const CommsActionSchema = defineSchema(
     z.object({
       action: z.literal("gateway_redeem_connection_code"),
       code: z.string(),
-      expiresAt: z.string(),
+      expiresAt: IsoTimestampSchema,
       device: z.string(),
       signature: z.string().optional(),
       publicKey: z.string().optional(),

package/src/core/user-identity.ts

@@ -7,6 +7,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { resolveDataDir } from "./data-directory.js";
+import { withWriteLockAsync } from "./pid-lock-file.js";
 import type { AccountContents } from "./account-bundle.js";
 import { certifyKeyPair } from "./identity.js";
 import type { PeerIdentity } from "./identity.js";
@@ -105,21 +106,28 @@ function requireStoredUserIdentity(file: string): StoredUserIdentity {
 }
 
 /** This machine's writer nonce for the account ledger, generated and persisted on first use. Two processes racing to create it can each end up with a different one; that is harmless, since each writes its own writer log and the ledger is the union of every writer log the account key recognises. What must never happen is two machines sharing one, which is why it is not part of an exported account. */
-export function loadOrCreateLedgerWriterNonce(
+export async function loadOrCreateLedgerWriterNonce(
   options: Readonly<UserIdentityOptions> | undefined,
   generate: () => Uint8Array,
-): Uint8Array<ArrayBuffer> {
+): Promise<Uint8Array<ArrayBuffer>> {
   const file = userIdentityFile(options);
-  const stored = requireStoredUserIdentity(file);
-  if (stored.ledgerWriter !== undefined) {
-    return Uint8Array.from(Buffer.from(stored.ledgerWriter, "base64"));
+  const existing = requireStoredUserIdentity(file).ledgerWriter;
+  if (existing !== undefined) {
+    return Uint8Array.from(Buffer.from(existing, "base64"));
   }
-  const nonce = Uint8Array.from(generate());
-  writeStoredUserIdentity(file, {
-    ...stored,
-    ledgerWriter: Buffer.from(nonce).toString("base64"),
+  // Read again under the lock: another process may have stored one meanwhile, and two would each keep its own, forking the writer log.
+  return withWriteLockAsync(file, () => {
+    const stored = requireStoredUserIdentity(file);
+    if (stored.ledgerWriter !== undefined) {
+      return Uint8Array.from(Buffer.from(stored.ledgerWriter, "base64"));
+    }
+    const nonce = Uint8Array.from(generate());
+    writeStoredUserIdentity(file, {
+      ...stored,
+      ledgerWriter: Buffer.from(nonce).toString("base64"),
+    });
+    return nonce;
   });
-  return nonce;
 }
 
 /** One grant a build before the replicated ledger recorded in user-identity.json. */
@@ -172,19 +180,21 @@ function withoutMigrated(
 }
 
 /** Removes exactly the given legacy grants from user-identity.json once they are in the ledger. The file is re-read first, so a grant written meanwhile by an older build still running on this machine stays for the next migration rather than being lost. */
-export function clearLegacyIssuedGrants(
+export async function clearLegacyIssuedGrants(
   options: Readonly<UserIdentityOptions> | undefined,
   migrated: readonly Readonly<LegacyIssuedGrant>[],
-): void {
+): Promise<void> {
   const file = userIdentityFile(options);
-  const { issuedDeviceGrants, issuedDmGrants, ...rest } =
-    requireStoredUserIdentity(file);
-  const device = withoutMigrated(issuedDeviceGrants, "device", migrated);
-  const dm = withoutMigrated(issuedDmGrants, "dm", migrated);
-  writeStoredUserIdentity(file, {
-    ...rest,
-    ...(device === undefined ? {} : { issuedDeviceGrants: device }),
-    ...(dm === undefined ? {} : { issuedDmGrants: dm }),
+  await withWriteLockAsync(file, () => {
+    const { issuedDeviceGrants, issuedDmGrants, ...rest } =
+      requireStoredUserIdentity(file);
+    const device = withoutMigrated(issuedDeviceGrants, "device", migrated);
+    const dm = withoutMigrated(issuedDmGrants, "dm", migrated);
+    writeStoredUserIdentity(file, {
+      ...rest,
+      ...(device === undefined ? {} : { issuedDeviceGrants: device }),
+      ...(dm === undefined ? {} : { issuedDmGrants: dm }),
+    });
   });
 }
 
@@ -196,15 +206,17 @@ export function loadUserDisplayName(
 }
 
 /** Sets (or, given undefined, clears) the name this account asserts for itself, keeping the key material and every other field. Throws if the account has not been created yet. */
-export function saveUserDisplayName(
+export async function saveUserDisplayName(
   options: Readonly<UserIdentityOptions> | undefined,
   displayName: string | undefined,
-): void {
+): Promise<void> {
   const file = userIdentityFile(options);
-  const next: StoredUserIdentity = { ...requireStoredUserIdentity(file) };
-  if (displayName === undefined) delete next.displayName;
-  else next.displayName = displayName;
-  writeStoredUserIdentity(file, next);
+  await withWriteLockAsync(file, () => {
+    const next: StoredUserIdentity = { ...requireStoredUserIdentity(file) };
+    if (displayName === undefined) delete next.displayName;
+    else next.displayName = displayName;
+    writeStoredUserIdentity(file, next);
+  });
 }
 
 /** What an export or a join carries of the account: its PEM private key and the name it asserts for itself, if any. Throws if the principal has never been created. */
@@ -250,10 +262,10 @@ function setAside(
 /**
  * Makes this machine hold the account whose contents are given, the deliberate copy that lets one principal span machines. The key is re-certified here (the device-id, which is the account's identity, depends only on the key). The name the account asserts for itself comes with it; an import carrying none leaves the name of the account already held untouched. This machine's own ledger writer nonce is kept, since it belongs to the machine, not the account. A different account already held here is moved aside to replacedUserIdentityFile first, never overwritten (see setAside for a record already set aside there); importing the account already held changes nothing but that name. Returns the imported identity and, when one was replaced, where the old record now is.
  */
-export function importAccountKey(
+export async function importAccountKey(
   options: Readonly<UserIdentityOptions> | undefined,
   contents: Readonly<AccountContents>,
-): { identity: PeerIdentity; replacedFile?: string } {
+): Promise<{ identity: PeerIdentity; replacedFile?: string }> {
   const file = userIdentityFile(options);
   fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
   const imported = certifyKeyPair(contents.privateKey);
@@ -263,28 +275,30 @@ export function importAccountKey(
       ? {}
       : { displayName: contents.displayName }),
   });
-  const existing = readStoredUserIdentity(file);
-  if (existing === undefined) {
-    writeStoredUserIdentity(file, named(issuerKeyRecord(imported)));
-    return { identity: imported };
-  }
-  const current = issuerPeerIdentity(existing);
-  if (Buffer.from(current.deviceId).equals(Buffer.from(imported.deviceId))) {
-    if (contents.displayName !== undefined) {
-      writeStoredUserIdentity(file, named(existing));
+  return withWriteLockAsync(file, () => {
+    const existing = readStoredUserIdentity(file);
+    if (existing === undefined) {
+      writeStoredUserIdentity(file, named(issuerKeyRecord(imported)));
+      return { identity: imported };
     }
-    return { identity: current };
-  }
-  const replacedFile = replacedUserIdentityFile(options, current);
-  setAside(replacedFile, existing, file);
-  writeStoredUserIdentity(
-    file,
-    named({
-      ...issuerKeyRecord(imported),
-      ...(existing.ledgerWriter === undefined
-        ? {}
-        : { ledgerWriter: existing.ledgerWriter }),
-    }),
-  );
-  return { identity: imported, replacedFile };
+    const current = issuerPeerIdentity(existing);
+    if (Buffer.from(current.deviceId).equals(Buffer.from(imported.deviceId))) {
+      if (contents.displayName !== undefined) {
+        writeStoredUserIdentity(file, named(existing));
+      }
+      return { identity: current };
+    }
+    const replacedFile = replacedUserIdentityFile(options, current);
+    setAside(replacedFile, existing, file);
+    writeStoredUserIdentity(
+      file,
+      named({
+        ...issuerKeyRecord(imported),
+        ...(existing.ledgerWriter === undefined
+          ? {}
+          : { ledgerWriter: existing.ledgerWriter }),
+      }),
+    );
+    return { identity: imported, replacedFile };
+  });
 }