agent-comms 9.0.10 → 9.0.12

package/src/core/connection-code-tool.ts

@@ -37,7 +37,7 @@ export async function handleGatewayGenerateConnectionCode(
 }
 
 /**
- * Validates a candidate connection code (assembled from action's own code/expiresAt/device/signature fields) and, on success, trusts the device-id it vouches for. When the candidate carries a signature but action supplies a fingerprint with no publicKey, fetches the signer's public key from a keyserver first via fetchPgpPublicKeyByFingerprintImpl -- injected rather than imported directly so a test can supply a fake resolver instead of making a real network call.
+ * Validates a candidate connection code (assembled from action's own code/expiresAt/device/signature fields) and, on success, trusts the device-id it vouches for. An unsigned code is a bearer hint, never authentication: whoever produced the text decided which device-id it names. Supplying a publicKey or fingerprint requires the code to be signed, and an unsigned one is then refused. When the candidate carries a signature but action supplies a fingerprint with no publicKey, fetches the signer's public key from a keyserver first via fetchPgpPublicKeyByFingerprintImpl, injected rather than imported directly so a test can supply a fake resolver instead of making a real network call.
  */
 export async function handleGatewayRedeemConnectionCode(
   store: Readonly<MeshOnlyFeatures>,
@@ -86,7 +86,7 @@ export async function handleGatewayRedeemConnectionCode(
     const fingerprintNote =
       result.fingerprint !== undefined
         ? ` (signature verified, signing key fingerprint ${result.fingerprint})`
-        : " (no signature; freshness only)";
+        : " (unsigned: the code was fresh and unused, which says nothing about who issued it)";
     return `Trusted remote gateway device ${result.deviceId} via connection code${fingerprintNote}.`;
   });
 }

package/src/core/connection-code.ts

@@ -1,7 +1,7 @@
 /**
  * ConnectionCode generation and redemption (agent-comms#188): bootstraps GatewayTrust between two devices that have never established a mesh connection, since GatewayTrust's own deny-by-default, pin-the-key model otherwise requires a device-id to already be known and pasted in by hand (gateway_trust). One artifact, one generation flow, one redemption flow -- never two mechanisms bolted together.
  *
- * `code`/`expiresAt` are the always-checked half: freshness/liveness proof that whoever redeems this was on the other end of this exact exchange, recently. `signature` is the optional half: a detached PGP signature (armored) over `${code}:${expiresAt}:${deviceId}`, checked only when present. Redemption never requires a signature -- a device with no PGP identity still generates and redeems a bare code -- but when one is present, verifying it needs the signer's own public key, supplied by the caller either as a pasted armored block or (see pgp-keyserver.ts) fetched from a keyserver by fingerprint. Either way, a caller who also supplies the fingerprint they already independently trust gets it pinned: the verified key's own computed fingerprint must equal it, or redemption fails.
+ * `code`/`expiresAt` are the always-checked half: freshness/liveness proof that whoever redeems this was on the other end of this exact exchange, recently. `expiresAt` must be an ISO 8601 timestamp; a code whose expiry does not parse is refused as invalid. `signature` is the optional half: a detached PGP signature (armored) over `${code}:${expiresAt}:${deviceId}`. An unsigned code is a bearer hint and authenticates nothing about who issued it: redeeming one trusts whatever device-id it names, so a device with no PGP identity can still generate and redeem a bare code, but only where the redeemer has some other reason to believe it. A redeemer who supplies a public key or a fingerprint is asking for the issuer to be authenticated, so the code must then carry a signature that verifies against that key, and a code without one is refused. Verifying needs the signer's own public key, supplied by the caller either as a pasted armored block or (see pgp-keyserver.ts) fetched from a keyserver by fingerprint. A caller who also supplies the fingerprint they already independently trust gets it pinned: the verified key's own computed fingerprint must equal it, or redemption fails.
  *
  * PGP key material is never generated, stored, or managed by this module or by agent-comms generally -- signing and verification both take key material supplied per call by the caller, exactly as invoking `gpg --sign`/`gpg --verify` directly would. Building a persisted PGP-identity subsystem (key generation, passphrase storage, revocation) is a materially larger, security-sensitive scope the settled design (agent-comms#188) never asked for; a caller who wants a code signed brings whatever real-world PGP identity they already have (git-commit signing key, personal key on a keyserver, etc.) rather than trusting agent-comms to mint and hold a new one on their behalf.
  *
@@ -15,6 +15,7 @@ import {
   saveConnectionCodeLedger,
 } from "./identity-store.js";
 import type { IdentitySlot, StoredConnectionCode } from "./identity-store.js";
+import { parseIsoTimestampMs } from "./iso-timestamp.js";
 import type { ConnectionCode } from "./types.js";
 
 /** Nonce length: longer than nanoid's own 21-character default, since this identifier doubles as the single-use token a redemption check keys off, not merely a display id. */
@@ -35,7 +36,9 @@ export const DEFAULT_CONNECTION_CODE_TTL_MS =
 export type ConnectionCodeInvalidReason =
   | "expired"
   | "already_redeemed"
+  | "invalid_expiry"
   | "signature_required"
+  | "signature_missing"
   | "signature_invalid"
   | "fingerprint_mismatch";
 
@@ -140,9 +143,9 @@ export interface GenerateConnectionCodeOptions {
 }
 
 export interface RedeemConnectionCodeOptions {
-  /** The signer's own armored PGP public key, needed only when the candidate code carries a signature. */
+  /** The signer's own armored PGP public key. Supplying it asks for the code's issuer to be authenticated: a candidate without a signature is refused with "signature_missing", and one with a signature must verify against this key. */
   publicKeyArmored?: string;
-  /** A PGP fingerprint the caller already has independent reason to trust. When supplied alongside a signed code, the verified signing key's own computed fingerprint must equal it (case- and whitespace-insensitive) or redemption fails with "fingerprint_mismatch". When omitted, a present signature is still verified against publicKeyArmored, but nothing pins it to a fingerprint the caller actually recognises. */
+  /** A PGP fingerprint the caller already has independent reason to trust. Supplying it asks for the code's issuer to be authenticated: a candidate without a signature is refused with "signature_missing", and the verified signing key's own computed fingerprint must equal it (case- and whitespace-insensitive) or redemption fails with "fingerprint_mismatch". When omitted, a present signature is still verified against publicKeyArmored, but nothing pins it to a fingerprint the caller actually recognises. */
   expectedFingerprint?: string;
   /** Injectable clock for tests; defaults to Date.now(). */
   now?: number;
@@ -155,8 +158,14 @@ export interface RedeemConnectionCodeResult {
   fingerprint?: string;
 }
 
+/** Whether an expiry given as text has passed at `now`. An expiry that does not parse counts as passed: it can never be compared against the clock, so nothing may rely on it staying valid. */
+function hasExpired(expiresAt: string, now: number): boolean {
+  const expiresAtMs = parseIsoTimestampMs(expiresAt);
+  return expiresAtMs === undefined || expiresAtMs <= now;
+}
+
 /**
- * Generates and redeems ConnectionCode artifacts, enforcing the always-checked freshness/liveness half (expiry, single-use) and the optional PGP-signature half (checked only when a code carries one). Optionally persisted per bridge slot via identity-store.ts's connection-code ledger (see this file's own header comment for what survives a restart and why); constructed with no slot, stays in-memory only, mirroring GatewayTrust's own no-slot fallback.
+ * Generates and redeems ConnectionCode artifacts, enforcing the always-checked freshness/liveness half (expiry, single-use) and the PGP-signature half (verified when a code carries a signature, and required whenever the redeemer supplies a key or fingerprint to check it against). Optionally persisted per bridge slot via identity-store.ts's connection-code ledger (see this file's own header comment for what survives a restart and why); constructed with no slot, stays in-memory only, mirroring GatewayTrust's own no-slot fallback.
  */
 export class ConnectionCodeLedger {
   private readonly issued = new Map<string, StoredConnectionCode>();
@@ -179,10 +188,10 @@ export class ConnectionCodeLedger {
   /** Drops every issued or redeemed entry whose own expiresAt has already passed, so neither map accumulates forever across a long-running process or a slot that survives many restarts. */
   private prune(now: number): void {
     for (const [nonce, record] of this.issued) {
-      if (Date.parse(record.expiresAt) <= now) this.issued.delete(nonce);
+      if (hasExpired(record.expiresAt, now)) this.issued.delete(nonce);
     }
     for (const [nonce, expiresAt] of this.redeemed) {
-      if (Date.parse(expiresAt) <= now) this.redeemed.delete(nonce);
+      if (hasExpired(expiresAt, now)) this.redeemed.delete(nonce);
     }
   }
 
@@ -240,7 +249,13 @@ export class ConnectionCodeLedger {
     const now = options.now ?? Date.now();
     this.prune(now);
 
-    if (Date.parse(candidate.expiresAt) <= now) {
+    if (parseIsoTimestampMs(candidate.expiresAt) === undefined) {
+      throw new ConnectionCodeError(
+        "invalid_expiry",
+        "Connection code expiry is not an ISO 8601 timestamp",
+      );
+    }
+    if (hasExpired(candidate.expiresAt, now)) {
       throw new ConnectionCodeError(
         "expired",
         `Connection code expired at ${candidate.expiresAt}`,
@@ -254,7 +269,18 @@ export class ConnectionCodeLedger {
     }
 
     let fingerprint: string | undefined;
-    if (candidate.signature !== undefined) {
+    if (candidate.signature === undefined) {
+      // The caller supplied something to check the issuer against, and an unsigned code has no issuer to check: accepting it as "freshness only" would pass the pin on nothing.
+      if (
+        options.publicKeyArmored !== undefined ||
+        options.expectedFingerprint !== undefined
+      ) {
+        throw new ConnectionCodeError(
+          "signature_missing",
+          "A public key or fingerprint was supplied to check the issuer against, but this connection code is not signed",
+        );
+      }
+    } else {
       if (options.publicKeyArmored === undefined) {
         throw new ConnectionCodeError(
           "signature_required",

package/src/core/device-membership.ts

@@ -87,6 +87,12 @@ export async function admitDevice(
   return verdict;
 }
 
+/** What removeDevice did: the revocation entries it minted, to broadcast, and how many ledger entries could not be read. When `unreadable` is above zero the removal is incomplete: a grant recorded only in an unreadable entry was not revoked, so a caller must not report the device as removed. */
+export interface RemoveDeviceResult {
+  entries: RevocationEntry[];
+  unreadable: number;
+}
+
 export interface RemoveDeviceOptions {
   /** The user principal's own identity -- only the principal that issued a device's membership may revoke it. */
   userIdentity: IdentityPort;
@@ -98,18 +104,16 @@ export interface RemoveDeviceOptions {
 }
 
 /**
- * Revokes every group:member grant for deviceId that the account's ledger holds as outstanding, whichever machine of the account minted it: mints a revocation-entry for each token-id, records it in the given RevocationView immediately, and appends it to the ledger, so every other machine of the account sees the grant as revoked and a later re-admission starts from nothing outstanding. Returns no entries for a device the account never admitted.
+ * Revokes every group:member grant for deviceId that the account's ledger holds as outstanding, whichever machine of the account minted it: mints a revocation-entry for each token-id, records it in the given RevocationView immediately, and appends it to the ledger, so every other machine of the account sees the grant as revoked and a later re-admission starts from nothing outstanding. Returns no entries for a device the account never admitted. A ledger entry that cannot be read does not stop the removal (account-ledger.ts): every grant the readable entries record is still revoked, and one recorded only in an unreadable entry is not, which the result says.
  *
- * Returns the minted entries so the caller can broadcast them to the mesh (this module has no MeshTransport dependency to do so itself, mirroring the module-level "no assumption about locality" boundary documented above): every other device that might hold one of this device's grants needs the entry to independently start refusing it.
+ * Returns the minted entries, and the number of unreadable ledger entries met, so the caller can broadcast them to the mesh (this module has no MeshTransport dependency to do so itself, mirroring the module-level "no assumption about locality" boundary documented above): every other device that might hold one of this device's grants needs the entry to independently start refusing it.
  */
 export async function removeDevice(
   options: Readonly<RemoveDeviceOptions>,
-): Promise<RevocationEntry[]> {
+): Promise<RemoveDeviceResult> {
   const deviceHex = deviceIdToHex(options.deviceId);
-  const outstanding = await options.accountLedger.outstandingGrants(
-    "device",
-    deviceHex,
-  );
+  const { grants: outstanding, unreadable } =
+    await options.accountLedger.outstandingGrantsChecked("device", deviceHex);
   const entries: RevocationEntry[] = [];
   for (const { tokenId } of outstanding) {
     const entry = await mintRevocationEntry({
@@ -126,5 +130,5 @@ export async function removeDevice(
     );
     entries.push(entry);
   }
-  return entries;
+  return { entries, unreadable };
 }

package/src/core/dm-grant-actions.ts

@@ -64,7 +64,13 @@ export async function dmRevoke(
   action: CommsAction & { action: "dm_revoke" },
 ): Promise<CommsResult> {
   if (!store.revokeAgentDmAccess) return grantsUnavailable();
-  await store.revokeAgentDmAccess(action.target);
+  const { unreadable } = await store.revokeAgentDmAccess(action.target);
+  if (unreadable > 0) {
+    return {
+      content: `Revoked every DM grant for ${action.target} that the readable ledger entries record, but ${String(unreadable)} ledger entries cannot be read, so a grant recorded only in them is still valid. Repair or replace them from another machine's replica of the account, then revoke again.`,
+      isError: true,
+    };
+  }
   return {
     content: `Revoked ${action.target}'s DM grant.`,
     isError: false,

package/src/core/error-reporting.ts

@@ -3,6 +3,7 @@
  */
 
 import { shortId } from "./display-name.js";
+import { UnusableIdentityRecordError } from "./issuer-identity-file.js";
 import { errnoCode, PeerLinkError } from "./peer-link-error.js";
 
 /** The causes of a refused or dropped connection to a peer, which all mean the process behind that address has gone. */
@@ -52,6 +53,10 @@ export function describeMeshError(
   error: Readonly<Error>,
 ): DescribedMeshError | undefined {
   if (error instanceof PeerLinkError) return describePeerLinkError(error);
+  // Already says what happened and what to do. Keyed by file, since the cc-peer front tries to attach a session on every tick and each try meets the same file.
+  if (error instanceof UnusableIdentityRecordError) {
+    return { key: `identity-unusable:${error.file}`, message: error.message };
+  }
   const code = errnoCode(error);
   if (code !== undefined && NO_NETWORK_CODES.has(code)) {
     return {

package/src/core/gateway-trust.ts

@@ -89,7 +89,7 @@ export class GatewayTrust {
     this.load();
   }
 
-  /** Replaces the in-memory sets with whatever the file currently holds, recording the file's stamp. A no-op without a location. Verified members are left alone: they are in memory only and are dropped on their own when their principal stops being trusted. */
+  /** Replaces the in-memory sets with whatever the file currently holds, recording the file's stamp. Identifiers are kept in lower case whatever case the file holds them in, so every lookup and removal, which lower-cases its argument, finds them. A no-op without a location. Verified members are left alone: they are in memory only and are dropped on their own when their principal stops being trusted. */
   private load(): void {
     if (this.location === undefined) return;
     this.checkedAt = this.clock.now();
@@ -99,13 +99,13 @@ export class GatewayTrust {
     this.trustedIssuers.principal.clear();
     this.trustedIssuers.machine.clear();
     for (const deviceHex of loaded.devices) {
-      this.trusted.add(deviceHex);
+      this.trusted.add(deviceHex.toLowerCase());
     }
     for (const principalHex of loaded.principals) {
-      this.trustedIssuers.principal.add(principalHex);
+      this.trustedIssuers.principal.add(principalHex.toLowerCase());
     }
     for (const machineHex of loaded.machines) {
-      this.trustedIssuers.machine.add(machineHex);
+      this.trustedIssuers.machine.add(machineHex.toLowerCase());
     }
   }
 

package/src/core/group-proofs.ts

@@ -166,13 +166,16 @@ export class GroupProofs {
 
   /** Sets (or, given undefined, clears) this machine's self display name and re-mints its claim now rather than on the next refresh. Throws if the store has no identity yet. */
   async saveMachineName(name: string | undefined): Promise<void> {
-    saveMachineDisplayName(this.getIdentity().machineIdentityOptions, name);
+    await saveMachineDisplayName(
+      this.getIdentity().machineIdentityOptions,
+      name,
+    );
     return this.machineName.refresh();
   }
 
   /** Sets (or, given undefined, clears) this account's self display name and re-mints its claim now rather than on the next refresh. Throws if the store has no identity yet. */
   async saveUserName(name: string | undefined): Promise<void> {
-    saveUserDisplayName(this.getIdentity().userIdentityOptions, name);
+    await saveUserDisplayName(this.getIdentity().userIdentityOptions, name);
     return this.principalName.refresh();
   }