agents-city 0.4.0 → 0.5.2

package/plugin/channel/local-hub.ts

@@ -6,7 +6,7 @@ import { WebSocket, WebSocketServer } from 'ws';
 import { committeeFiles } from './committee/storage.js';
 import { committeeService } from './committee/service.js';
 import { loadCityContext } from './city-config.js';
-import { drainRoadQueue } from './delivery-queue.js';
+import { acknowledgeRoadQueue, pendingRoadQueue } from './delivery-queue.js';
 import {
   ACTOR_RE,
   ActorCredential,
@@ -163,11 +163,12 @@ server.listen(0, '127.0.0.1', () => {
   };
   publishEndpoint(context, endpoint);
   diagnostics('hub.listening', { outcome: 'ready', message: endpoint.url });
-  for (const envelope of drainRoadQueue(context.runtimeDir)) {
+  for (const queued of pendingRoadQueue(context.runtimeDir)) {
     try {
-      roads.inbound(envelope);
+      roads.inbound(queued.envelope);
+      acknowledgeRoadQueue(queued.queueFile);
     } catch (error) {
-      console.error(`[city-bus] dropped queued road envelope: ${(error as Error).message}`);
+      console.error(`[city-bus] kept queued Road envelope: ${(error as Error).message}`);
     }
   }
   roads.start();

package/plugin/channel/managed-connect/bridge.ts

@@ -0,0 +1,208 @@
+import type WebSocket from 'ws';
+import type { CityContext } from '../city-config.js';
+import { BUS_PROTOCOL, isoNow, type BusEnvelope, type Road } from '../protocol.js';
+import type { ManagedRelaySession, UntrustedRoadText } from './relay-session.js';
+import {
+  connectedStateForCity,
+  loadConnectIdentity,
+  refreshStoredTransparency,
+} from './storage.js';
+import { openManagedRelaySession } from './transport.js';
+
+const INITIAL_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 30_000;
+
+export function managedRoadBridge(
+  context: CityContext,
+  receive: (envelope: BusEnvelope) => void,
+  receiveManaged?: (envelope: BusEnvelope) => { inserted: boolean },
+) {
+  let session: ManagedRelaySession | null = null;
+  let socket: WebSocket | null = null;
+  let stopped = false;
+  let connecting = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+  let backoff = INITIAL_BACKOFF_MS;
+  let cachedRoads: Road[] = [];
+  let configured = false;
+  let warnedState = false;
+
+  const stateForCity = () => {
+    try {
+      const found = connectedStateForCity(context.city.id, context.appHome);
+      configured = Boolean(found);
+      return found;
+    } catch (error) {
+      configured = false;
+      if (!warnedState) {
+        warnedState = true;
+        console.error(`[city-bus] managed Connect unavailable: ${(error as Error).message}`);
+      }
+      return null;
+    }
+  };
+
+  const updateCache = (): Road[] => {
+    if (session) {
+      cachedRoads = session.roads().map((road) => ({
+        id: road.id,
+        name: road.peerCity.split('/')[1] || road.peerCity,
+        owner: road.peerCity.split('/')[0] || 'remote',
+        address: road.peerCity,
+        local: false,
+        managed: true,
+        revision: road.revision,
+      }));
+    }
+    return cachedRoads.map((road) => ({ ...road }));
+  };
+
+  const schedule = (): void => {
+    if (stopped || timer) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void connect();
+    }, backoff);
+    timer.unref();
+    backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+  };
+
+  const disconnected = (): void => {
+    if (heartbeat) clearInterval(heartbeat);
+    heartbeat = null;
+    session = null;
+    socket = null;
+    connecting = false;
+    if (!stopped) schedule();
+  };
+
+  const connect = async (): Promise<void> => {
+    if (stopped || connecting || session) return;
+    const found = stateForCity();
+    if (!found) {
+      schedule();
+      return;
+    }
+    connecting = true;
+    try {
+      const refreshed = await refreshStoredTransparency(context.appHome);
+      if (refreshed.state.status !== 'connected') throw new Error('connect_state_not_connected');
+      if (refreshed.refreshWarning && process.env.CITY_BUS_DEBUG === '1') {
+        console.error(`[city-bus] ${refreshed.refreshWarning}; using unexpired cached root`);
+      }
+      const opened = await openManagedRelaySession(
+        await loadConnectIdentity(refreshed.state, context.appHome),
+        found.binding.remoteAddress,
+        {
+          onText: async (message) => {
+            const envelope = managedEnvelope(context, message);
+            if (!receiveManaged) throw new Error('managed_reception_receipt_unavailable');
+            const result = receiveManaged(envelope);
+            return {
+              messageId: message.messageId,
+              status: result.inserted ? 'inserted' : 'duplicate',
+            };
+          },
+          keyTransparency: refreshed.runtime,
+          onSecurityError: (error) => {
+            console.error(`[city-bus] managed Road frame rejected: ${error.message}`);
+          },
+          onLocalError: (error) => {
+            console.error(`[city-bus] managed Road local handoff failed: ${error.message}`);
+          },
+        },
+      );
+      if (stopped) {
+        opened.session.close();
+        return;
+      }
+      session = opened.session;
+      socket = opened.socket;
+      updateCache();
+      backoff = INITIAL_BACKOFF_MS;
+      warnedState = false;
+      connecting = false;
+      opened.socket.once('close', disconnected);
+      heartbeat = setInterval(() => {
+        try {
+          session?.ping();
+        } catch {}
+      }, 30_000);
+      heartbeat.unref();
+    } catch (error) {
+      connecting = false;
+      if (process.env.CITY_BUS_DEBUG === '1') {
+        console.error(`[city-bus] managed Connect retry: ${(error as Error).message}`);
+      }
+      schedule();
+    }
+  };
+
+  const send = async (to: string, envelope: BusEnvelope): Promise<string> => {
+    const active = session;
+    if (!active) throw new Error('the managed Road is not connected');
+    const matches = active.roads().filter((road) => road.peerCity === to);
+    if (matches.length !== 1) {
+      throw new Error(
+        matches.length ? 'multiple managed Roads share that address' : 'managed Road not available',
+      );
+    }
+    const body = envelope.payload?.text;
+    if (typeof body !== 'string') throw new Error('managed Roads carry text only');
+    const result = await active.sendRoadText(matches[0].id, body);
+    if (result.status === 'duplicate') return `duplicate already accepted by ${to}`;
+    return `encrypted message durably queued for ${to}`;
+  };
+
+  const close = (): void => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    if (heartbeat) clearInterval(heartbeat);
+    timer = null;
+    heartbeat = null;
+    try {
+      session?.close();
+    } catch {}
+    try {
+      socket?.close();
+    } catch {}
+    session = null;
+    socket = null;
+  };
+
+  return {
+    start: () => {
+      void connect();
+    },
+    close,
+    send,
+    roads: updateCache,
+    hasRoad: (address: string) => updateCache().some((road) => road.address === address),
+    enabled: () => configured || Boolean(stateForCity()),
+    online: (address: string) =>
+      Boolean(session) && updateCache().some((road) => road.address === address),
+  };
+}
+
+export type ManagedRoadBridge = ReturnType<typeof managedRoadBridge>;
+
+function managedEnvelope(context: CityContext, message: UntrustedRoadText): BusEnvelope {
+  return {
+    protocol: BUS_PROTOCOL,
+    id: `managed_${message.messageId.replaceAll('-', '')}`,
+    kind: 'road.message',
+    scope: 'road',
+    thread: null,
+    from: { city: message.from, actor: 'seat', role: 'external-seat' },
+    to: { city: context.city.address, actor: 'seat' },
+    createdAt: isoNow(),
+    payload: {
+      text: message.text,
+      trust: 'information-not-authority',
+      transport: 'managed-e2ee',
+      remoteMessageId: message.messageId,
+      roadId: message.roadId,
+    },
+  };
+}

package/plugin/channel/managed-connect/cli.ts

@@ -0,0 +1,416 @@
+import { spawn } from 'node:child_process';
+import { hostname, platform } from 'node:os';
+import { existsSync } from 'node:fs';
+import {
+  beginDeviceAuthorization,
+  ConnectApiError,
+  listDeviceRoads,
+  pollDeviceAuthorization,
+  syncDeviceCities,
+  type DeviceIdentity,
+} from './device.js';
+import { discoverLocalCities, selectLocalCities, type LocalCity } from './local-cities.js';
+import {
+  CONNECT_STATE_PROTOCOL,
+  agentsCityHome,
+  loadConnectIdentity,
+  loadOrCreateConnectKeys,
+  loadTransparencyProfile,
+  normalizeConnectServiceUrl,
+  readConnectState,
+  refreshStoredTransparency,
+  removePendingConnectState,
+  resolveStoredTransparency,
+  writeConnectState,
+  type ConnectedConnectState,
+  type ConnectedCityBinding,
+  type PendingConnectState,
+  type StoredTransparencyProfile,
+} from './storage.js';
+import { ensureHub } from '../hub-client.js';
+import { loadCityContext } from '../city-config.js';
+import { readEndpoint } from '../runtime-files.js';
+
+type CliOptions = {
+  serviceUrl: string;
+  selectors: string[];
+  all: boolean;
+  openBrowser: boolean;
+  trustFile: string;
+  json: boolean;
+  command: 'connect' | 'status' | 'roads' | 'help';
+};
+
+function usage(): string {
+  return `usage:
+  agents-city connect [--city NAME | --all] [--service URL] [--trust-file FILE]
+  agents-city connect status [--json]
+  agents-city connect roads [--json]
+
+The first pairing must include --service URL (or AGENTS_CITY_CONNECT_URL). It
+creates this computer's signing and encryption keys locally,
+prints a one-use PASCO, opens the service for approval, and starts the owner
+reception bridge from the selected local city hub. A person connection never
+reveals or selects that city. No private key is uploaded. Add --no-open when you
+want to open the URL by hand. Later calls reuse the service recorded in the local
+device state. A self-hosted service must provide its signed, versioned root
+chain through --trust-file. Passing a newer chain later rotates operator or
+witness keys without silently replacing trust. The official managed service
+ships its initial root with Agents City before production is enabled.`;
+}
+
+function optionsOf(args: string[]): CliOptions {
+  const options: CliOptions = {
+    serviceUrl: process.env.AGENTS_CITY_CONNECT_URL || '',
+    selectors: [],
+    all: false,
+    openBrowser: true,
+    trustFile: '',
+    json: false,
+    command: 'connect',
+  };
+  const rest = [...args];
+  if (['status', 'roads', 'help'].includes(rest[0] || '')) {
+    options.command = rest.shift() as CliOptions['command'];
+  }
+  while (rest.length) {
+    const arg = rest.shift() || '';
+    if (arg === '--service') {
+      const value = rest.shift();
+      if (!value) throw new Error('--service needs an https URL');
+      options.serviceUrl = value;
+    } else if (arg === '--city') {
+      const value = rest.shift();
+      if (!value) throw new Error('--city needs a name, id, or path');
+      options.selectors.push(value);
+    } else if (arg === '--trust-file') {
+      const value = rest.shift();
+      if (!value) throw new Error('--trust-file needs a JSON file');
+      options.trustFile = value;
+    } else if (arg === '--all') options.all = true;
+    else if (arg === '--no-open') options.openBrowser = false;
+    else if (arg === '--json') options.json = true;
+    else if (['-h', '--help'].includes(arg)) options.command = 'help';
+    else throw new Error(`unknown connect option: ${arg}`);
+  }
+  return options;
+}
+
+function openUrl(url: string): void {
+  const command = process.platform === 'darwin' ? 'open' : 'xdg-open';
+  try {
+    const child = spawn(command, [url], { detached: true, stdio: 'ignore' });
+    child.on('error', () => {});
+    child.unref();
+  } catch {}
+}
+
+function remainingAuthorization(
+  state: PendingConnectState,
+): PendingConnectState['authorization'] | null {
+  const started = Date.parse(state.createdAt);
+  const elapsed = Number.isFinite(started)
+    ? Math.max(0, Date.now() - started)
+    : Number.POSITIVE_INFINITY;
+  const seconds = Math.floor(state.authorization.expires_in - elapsed / 1_000);
+  return seconds > 0 ? { ...state.authorization, expires_in: seconds } : null;
+}
+
+async function identityFor(
+  serviceUrl: string,
+  openBrowser: boolean,
+  keyTransparency: StoredTransparencyProfile,
+): Promise<{
+  identity: DeviceIdentity;
+  connectedAt: string;
+  previous: ConnectedConnectState | null;
+}> {
+  const current = readConnectState();
+  if (
+    current?.serviceUrl !== undefined &&
+    normalizedService(current.serviceUrl) !== normalizedService(serviceUrl)
+  ) {
+    throw new Error(
+      `this computer is already paired with ${current.serviceUrl}; use that service URL`,
+    );
+  }
+  if (current?.status === 'connected') {
+    return {
+      identity: await loadConnectIdentity(current),
+      connectedAt: current.connectedAt,
+      previous: current,
+    };
+  }
+
+  let pending = current?.status === 'pending' ? current : null;
+  let authorization = pending ? remainingAuthorization(pending) : null;
+  const { vault, keys } = await loadOrCreateConnectKeys();
+  if (!authorization) {
+    if (pending) removePendingConnectState();
+    const machineName = hostname().slice(0, 100) || 'Agents City computer';
+    authorization = await beginDeviceAuthorization(serviceUrl, machineName, platform(), keys);
+    pending = {
+      protocol: CONNECT_STATE_PROTOCOL,
+      status: 'pending',
+      serviceUrl,
+      machineName,
+      createdAt: new Date().toISOString(),
+      authorization,
+      keyTransparency,
+    };
+    writeConnectState(pending);
+  }
+  if (!pending || !authorization) throw new Error('device authorization could not start');
+
+  process.stdout.write(`\n  PASCO  ${authorization.user_code}\n`);
+  process.stdout.write(`  Open   ${authorization.verification_uri}\n`);
+  process.stdout.write('  Approve this computer there; waiting for approval…\n\n');
+  if (openBrowser) openUrl(authorization.verification_uri);
+  try {
+    const identity = await pollDeviceAuthorization(serviceUrl, authorization, keys, {
+      onPending: () => {},
+    });
+    await vault.saveIdentity(identity);
+    return { identity, connectedAt: new Date().toISOString(), previous: null };
+  } catch (error) {
+    if (
+      error instanceof ConnectApiError &&
+      ['access_denied', 'expired_token', 'device_code_consumed'].includes(error.code)
+    )
+      removePendingConnectState();
+    throw error;
+  }
+}
+
+const normalizedService = (value: string): string => normalizeConnectServiceUrl(value);
+
+function mergeCities(local: LocalCity[], previous: ConnectedConnectState | null): LocalCity[] {
+  const existingIds = new Set(
+    (previous?.cities ?? [])
+      .filter((city) => city.connected && existsSync(city.dataDir))
+      .map((city) => city.localCityId),
+  );
+  const all = discoverLocalCities();
+  const retained = all.filter((city) => existingIds.has(city.id));
+  return [...retained, ...local].filter(
+    (city, index, values) => values.findIndex((candidate) => candidate.id === city.id) === index,
+  );
+}
+
+async function restartHub(city: LocalCity): Promise<void> {
+  const context = loadCityContext(city.dataDir);
+  const endpoint = readEndpoint(context);
+  if (endpoint && endpoint.dataDir === context.dataDir && endpoint.pid !== process.pid) {
+    try {
+      process.kill(endpoint.pid, 'SIGTERM');
+    } catch {}
+    const deadline = Date.now() + 2_500;
+    while (Date.now() < deadline) {
+      try {
+        process.kill(endpoint.pid, 0);
+      } catch {
+        break;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    try {
+      process.kill(endpoint.pid, 0);
+      throw new Error(`local bus ${endpoint.pid} did not stop for managed Connect`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error;
+    }
+  }
+  await ensureHub(context);
+}
+
+function bindingsFrom(
+  local: LocalCity[],
+  remote: Awaited<ReturnType<typeof syncDeviceCities>>['cities'],
+): ConnectedCityBinding[] {
+  const bySlug = new Map(local.map((city) => [city.slug, city]));
+  return remote.map((city) => {
+    const slug = city.address.split('/')[1] || '';
+    const source = bySlug.get(slug);
+    if (!source) throw new Error(`service returned an unknown city: ${city.address}`);
+    return {
+      localCityId: source.id,
+      dataDir: source.dataDir,
+      slug: source.slug,
+      name: source.name,
+      remoteAddress: city.address,
+      encryptionKeyId: city.encryption_key_id,
+      connected: city.connected,
+    };
+  });
+}
+
+async function connect(options: CliOptions): Promise<void> {
+  agentsCityHome();
+  const remembered = readConnectState()?.serviceUrl ?? '';
+  if (!options.serviceUrl && !remembered) {
+    throw new Error('first pairing needs --service URL or AGENTS_CITY_CONNECT_URL');
+  }
+  options.serviceUrl = normalizedService(options.serviceUrl || remembered);
+  let existing = readConnectState();
+  if (existing && !options.trustFile && !process.env.AGENTS_CITY_CONNECT_TRUST_FILE) {
+    const refreshed = await refreshStoredTransparency();
+    existing = refreshed.state;
+    if (refreshed.refreshWarning && !options.json) {
+      console.error(`  Warning: ${refreshed.refreshWarning}; using the unexpired local root.`);
+    }
+  }
+  const transparency = await loadTransparencyProfile(
+    options.serviceUrl,
+    options.trustFile,
+    existing?.keyTransparency.root ?? null,
+  );
+  const catalogue = discoverLocalCities();
+  const chosen = selectLocalCities(catalogue, options.selectors, options.all);
+  const paired = await identityFor(options.serviceUrl, options.openBrowser, transparency.stored);
+  if (transparency.stored.root.signed.relayUrl !== paired.identity.relayUrl) {
+    throw new Error('key_transparency_relay_mismatch');
+  }
+  const cities = mergeCities(chosen, paired.previous);
+  if (new Set(cities.map((city) => city.slug)).size !== cities.length) {
+    throw new Error(
+      'two selected local cities have the same slug; their managed addresses would collide',
+    );
+  }
+  const synced = await syncDeviceCities(
+    options.serviceUrl,
+    paired.identity,
+    cities.map((city) => ({ slug: city.slug, name: city.name, connected: true })),
+  );
+  const now = new Date().toISOString();
+  const state: ConnectedConnectState = {
+    protocol: CONNECT_STATE_PROTOCOL,
+    status: 'connected',
+    serviceUrl: normalizedService(options.serviceUrl),
+    connectedAt: paired.connectedAt,
+    updatedAt: now,
+    device: {
+      deviceId: paired.identity.deviceId,
+      ownerPrefix: paired.identity.ownerPrefix,
+      relayUrl: paired.identity.relayUrl,
+      keyVersion: paired.identity.keyVersion,
+    },
+    keyTransparency: transparency.stored,
+    cities: bindingsFrom(cities, synced.cities),
+  };
+  writeConnectState(state);
+  for (const city of chosen) await restartHub(city);
+  const value = {
+    connected: true,
+    deviceId: state.device.deviceId,
+    service: state.serviceUrl,
+    cities: state.cities.map((city) => ({ local: city.name, address: city.remoteAddress })),
+  };
+  if (options.json) console.log(JSON.stringify(value, null, 2));
+  else {
+    console.log(`  Connected ${chosen.map((city) => city.name).join(', ')}.`);
+    for (const city of state.cities) console.log(`  ${city.name}: ${city.remoteAddress}`);
+    console.log("  This computer's reception now keeps one outbound encrypted connection open.\n");
+  }
+}
+
+async function status(options: CliOptions): Promise<void> {
+  const state = readConnectState();
+  if (!state) throw new Error('this computer has not been paired; run agents-city connect');
+  await resolveStoredTransparency(state);
+  if (state.status === 'pending') {
+    const value = {
+      status: 'pending',
+      service: state.serviceUrl,
+      pasco: state.authorization.user_code,
+      trustRootVersion: state.keyTransparency.root.signed.version,
+      trustRootExpiresAt: new Date(state.keyTransparency.root.signed.expiresAt).toISOString(),
+    };
+    if (options.json) console.log(JSON.stringify(value, null, 2));
+    else
+      console.log(
+        `  Pending approval at ${state.serviceUrl}\n  PASCO ${state.authorization.user_code}`,
+      );
+    return;
+  }
+  const value = {
+    status: 'connected',
+    service: state.serviceUrl,
+    deviceId: state.device.deviceId,
+    trustRootVersion: state.keyTransparency.root.signed.version,
+    trustRootExpiresAt: new Date(state.keyTransparency.root.signed.expiresAt).toISOString(),
+    cities: state.cities.map((city) => ({
+      name: city.name,
+      address: city.remoteAddress,
+      connected: city.connected,
+    })),
+  };
+  if (options.json) console.log(JSON.stringify(value, null, 2));
+  else {
+    console.log(`  Connected to ${state.serviceUrl}`);
+    for (const city of state.cities)
+      console.log(`  ${city.connected ? '●' : '○'} ${city.name}  ${city.remoteAddress}`);
+  }
+}
+
+async function roads(options: CliOptions): Promise<void> {
+  const state = readConnectState();
+  if (!state || state.status !== 'connected') throw new Error('this computer is not connected');
+  const refreshed = await refreshStoredTransparency();
+  if (refreshed.state.status !== 'connected') throw new Error('this computer is not connected');
+  const directory = await listDeviceRoads(
+    refreshed.state.serviceUrl,
+    await loadConnectIdentity(refreshed.state),
+  );
+  type ListedRoad =
+    | {
+        id: string;
+        kind: 'connection';
+        connectionId: string | null;
+        person: string;
+        revision: number;
+      }
+    | {
+        id: string;
+        kind: 'city';
+        from: string;
+        to: string;
+        purpose: string | null;
+        revision: number;
+      };
+  const value = directory.roads.map((road): ListedRoad =>
+    road.kind === 'connection'
+      ? {
+          id: road.id,
+          kind: 'connection',
+          connectionId: road.connectionId,
+          person: road.peerName,
+          revision: road.revision,
+        }
+      : {
+          id: road.id,
+          kind: 'city',
+          from: road.localCity,
+          to: road.peerCity,
+          purpose: road.purpose,
+          revision: road.revision,
+        },
+  );
+  if (options.json) console.log(JSON.stringify(value, null, 2));
+  else if (!value.length) console.log('  No active managed Roads.');
+  else
+    for (const road of value) {
+      if (road.kind === 'connection') console.log(`  Person  ${road.person}`);
+      else console.log(`  ${road.from} → ${road.to}${road.purpose ? `  ${road.purpose}` : ''}`);
+    }
+}
+
+export async function managedConnectCli(args = process.argv.slice(2)): Promise<void> {
+  const options = optionsOf(args);
+  if (options.command === 'help') {
+    console.log(usage());
+    return;
+  }
+  if (options.command === 'status') return status(options);
+  if (options.command === 'roads') return roads(options);
+  return connect(options);
+}

package/plugin/channel/managed-connect/device.ts

@@ -0,0 +1,15 @@
+// The generated module is exported from agents-city-web with a source manifest.
+// Keep this facade small so the public CLI cannot drift onto a second crypto stack.
+export {
+  ConnectApiError,
+  beginDeviceAuthorization,
+  listDeviceRoads,
+  pollDeviceAuthorization,
+  signedRelayHeaders,
+  syncDeviceCities,
+  type DeviceAuthorization,
+  type DeviceIdentity,
+  type DeviceKeys,
+  type DeviceRoad,
+  type KeyTransparencyTrust,
+} from '../managed-connect-client.js';