talon-agent 5.20.1 → 5.22.0

package/src/core/mesh/credentials/store.ts

@@ -253,7 +253,11 @@ export class DeviceCredentialStore {
       });
     }
     const records = this.activeRecordsFor(deviceId);
-    for (const record of records) record.scopes = next;
+    const at = this.now();
+    for (const record of records) {
+      record.scopes = next;
+      record.scopesSetAt = at;
+    }
     if (records.length > 0) {
       await this.persist();
       this.emit(records.map((r) => r.id));
@@ -261,6 +265,29 @@ export class DeviceCredentialStore {
     return records.map(publicView);
   }
 
+  /**
+   * Move every live credential still holding exactly `from` to `to`, unless
+   * its scopes were set by hand — for when a default widens, so devices
+   * issued the old default get the new one. Returns how many changed.
+   */
+  async adoptDefaultScopes(
+    from: readonly MeshScope[],
+    to: readonly MeshScope[],
+  ): Promise<number> {
+    await this.load();
+    const was = normalizeScopes(from).join(",");
+    const next = normalizeScopes(to);
+    let changed = 0;
+    for (const record of this.records.values()) {
+      if (!this.isActive(record) || record.scopesSetAt !== undefined) continue;
+      if (record.scopes.join(",") !== was) continue;
+      record.scopes = [...next];
+      changed++;
+    }
+    if (changed > 0) await this.persist();
+    return changed;
+  }
+
   /** Subscribe to revocations (the bridge drops matching sessions). */
   onRevoked(listener: RevocationListener): () => void {
     this.listeners.add(listener);
@@ -313,11 +340,13 @@ export class DeviceCredentialStore {
     }
     const minted = mintCredentialToken();
     const at = this.now();
+    const scopesSetAt = this.handSetScopes(input.deviceId, scopes);
     const record: DeviceCredentialRecord = {
       id: minted.id,
       deviceId: input.deviceId,
       tokenHash: minted.tokenHash,
       scopes,
+      ...(scopesSetAt !== undefined ? { scopesSetAt } : {}),
       origin: input.origin,
       createdAt: at,
       ...(input.deviceId === null ? { expiresAt: at + UNBOUND_TTL_MS } : {}),
@@ -327,6 +356,18 @@ export class DeviceCredentialStore {
     return { token: minted.token, credential: publicView(record) };
   }
 
+  /** A re-issue keeps the mark of scopes an operator set by hand. */
+  private handSetScopes(
+    deviceId: string | null,
+    scopes: readonly MeshScope[],
+  ): number | undefined {
+    if (deviceId === null) return undefined;
+    const key = scopes.join(",");
+    return this.activeRecordsFor(deviceId).find(
+      (r) => r.scopesSetAt !== undefined && r.scopes.join(",") === key,
+    )?.scopesSetAt;
+  }
+
   private isActive(record: DeviceCredentialRecord): boolean {
     if (record.revokedAt !== undefined) return false;
     return record.expiresAt === undefined || this.now() < record.expiresAt;

package/src/core/mesh/credentials/types.ts

@@ -7,7 +7,7 @@
  * the secret plus the metadata below; the plaintext exists once, in the reply
  * or link that hands it to the device.
  *
- * Scopes (least privilege — see docs/mesh-credentials.md):
+ * Scopes (see docs/mesh-credentials.md):
  *
  *   device    register/heartbeat/report as ITSELF, receive and answer its
  *             own commands, move the files the daemon asked it to move.
@@ -22,10 +22,24 @@
 const MESH_SCOPES = ["device", "client", "operator"] as const;
 export type MeshScope = (typeof MESH_SCOPES)[number];
 
-/** What a paired or upgraded companion gets unless the operator widens it. */
+/**
+ * What a paired or upgraded companion gets unless the operator narrows it
+ * (`native.companionScopes`): everything, as with the shared token.
+ */
 export const DEFAULT_COMPANION_SCOPES: readonly MeshScope[] = [
   "device",
   "client",
+  "operator",
+];
+
+/**
+ * The companion default before `operator` joined it. Credentials still
+ * holding exactly this (and never set by hand) are moved to the current
+ * default on startup — see `DeviceCredentialStore.adoptDefaultScopes`.
+ */
+export const FORMER_COMPANION_SCOPES: readonly MeshScope[] = [
+  "device",
+  "client",
 ];
 
 /** A headless talon-node is a device and nothing else. */
@@ -55,6 +69,11 @@ export type DeviceCredentialRecord = {
   /** Hex SHA-256 of the whole token. */
   tokenHash: string;
   scopes: MeshScope[];
+  /**
+   * When an operator last set this device's scopes by hand (`talon mesh
+   * scopes`). Such a credential keeps its scopes when a default changes.
+   */
+  scopesSetAt?: number;
   origin: CredentialOrigin;
   createdAt: number;
   lastUsedAt?: number;

package/src/core/mesh/devices/service.ts

@@ -50,6 +50,15 @@ import {
   type NodeBinaryResolver,
 } from "../links/node-binaries.js";
 import { MeshRegistry } from "./registry.js";
+import {
+  auditErrorText,
+  auditIssuer,
+  hashCommandArgs,
+  MeshAuditLog,
+  type MeshAuditEntry,
+  type MeshAuditQuery,
+} from "../audit.js";
+import { logWarn } from "../../../util/log.js";
 import {
   DeviceCredentialStore,
   type CredentialAdminContext,
@@ -97,6 +106,12 @@ export type MeshServiceOptions = {
    * without one (tests, embedders) links carry the shared bridge token.
    */
   credentials?: DeviceCredentialStore;
+  /**
+   * Where every dispatched command is recorded (who, which device, which
+   * command, an args hash, outcome, duration). Absent (tests, embedders) =
+   * nothing is recorded.
+   */
+  audit?: MeshAuditLog;
 };
 
 const DEFAULT_FRESH_FIX_TIMEOUT_MS = 8_000;
@@ -143,6 +158,8 @@ export class MeshService {
   private loading: Promise<void> | null = null;
   /** Per-device credentials (null = shared-token-only mesh). */
   readonly credentials: DeviceCredentialStore | null;
+  /** The command audit (null = commands are not recorded). */
+  private readonly audit: MeshAuditLog | null;
   /** `native.legacySharedToken` as the bridge last reported it. */
   private legacySharedToken = true;
 
@@ -167,6 +184,7 @@ export class MeshService {
       resolveNode: this.resolveNode,
     });
     this.credentials = options.credentials ?? null;
+    this.audit = options.audit ?? null;
     const store = this.credentials;
     this.links = new BridgeLinks(
       this.resolveNode,
@@ -354,13 +372,76 @@ export class MeshService {
   /**
    * Push one command to a device and await its result (or time out). The
    * low-level primitive under every command tool; exposed for tests and
-   * future tools.
+   * future tools. Every dispatch lands in the command audit.
    */
   sendCommand(
     device: DeviceInfo,
     name: string,
     params: Record<string, unknown> = {},
     timeoutMs = this.commandTimeoutMs,
+  ): Promise<DeviceCommandResult> {
+    const finishAudit = this.beginAudit(device, name, params);
+    const pending = this.deliverCommand(device, name, params, timeoutMs);
+    if (!finishAudit) return pending;
+    // The delivery promise only ever resolves, so this adds no rejection.
+    return pending.then((result) => {
+      finishAudit(result);
+      return result;
+    });
+  }
+
+  /**
+   * Open the audit record for one dispatch. The issuer is read now, while
+   * the issuing turn's scope is live. Returns the completion hook, or null
+   * when nothing is audited. Never throws: a broken audit must not stop a
+   * command.
+   */
+  private beginAudit(
+    device: DeviceInfo,
+    name: string,
+    params: Record<string, unknown>,
+  ): ((result: DeviceCommandResult) => void) | null {
+    const audit = this.audit;
+    if (!audit) return null;
+    try {
+      const startedAt = Date.now();
+      const base = {
+        time: new Date(startedAt).toISOString(),
+        issuer: auditIssuer(),
+        deviceId: device.id,
+        deviceName: device.name,
+        command: name,
+        argsHash: hashCommandArgs(params),
+      };
+      return (result) => {
+        try {
+          audit.record({
+            ...base,
+            ok: result.ok,
+            ...(result.ok ? {} : { error: auditErrorText(result.message) }),
+            durationMs: Date.now() - startedAt,
+          });
+        } catch (err) {
+          logWarn("mesh", `mesh.audit event=record_failed err=${String(err)}`);
+        }
+      };
+    } catch (err) {
+      logWarn("mesh", `mesh.audit event=record_failed err=${String(err)}`);
+      return null;
+    }
+  }
+
+  /** `talon mesh audit`: the newest recorded dispatches, oldest first. */
+  readAudit(query: MeshAuditQuery = {}): Promise<MeshAuditEntry[]> {
+    return this.audit ? this.audit.read(query) : Promise.resolve([]);
+  }
+
+  /** Deliver one command; resolves with its result, a timeout, or a loss. */
+  private deliverCommand(
+    device: DeviceInfo,
+    name: string,
+    params: Record<string, unknown>,
+    timeoutMs: number,
   ): Promise<DeviceCommandResult> {
     const command: DeviceCommand = {
       id: randomUUID(),
@@ -732,8 +813,14 @@ export class MeshService {
     query: unknown,
     localApkPath: unknown,
     remotePath?: unknown,
+    allowDowngrade?: unknown,
   ): Promise<MeshToolResult> {
-    return this.files.updateDeviceApp(query, localApkPath, remotePath);
+    return this.files.updateDeviceApp(
+      query,
+      localApkPath,
+      remotePath,
+      allowDowngrade,
+    );
   }
 
   /** `update_node`: remote self-update for a headless talon-node. */
@@ -741,8 +828,14 @@ export class MeshService {
     query: unknown,
     localBinaryPath?: unknown,
     remotePath?: unknown,
+    allowDowngrade?: unknown,
   ): Promise<MeshToolResult> {
-    return this.files.updateNodeBinary(query, localBinaryPath, remotePath);
+    return this.files.updateNodeBinary(
+      query,
+      localBinaryPath,
+      remotePath,
+      allowDowngrade,
+    );
   }
 
   // ── Provisioning + pairing (see links/bridge-links.ts) ────────────────────
@@ -784,8 +877,12 @@ export class MeshService {
   }
 
   /** GET /node/install — serve a grant's installer script (single-use). */
-  openNodeInstall(token: string): { script: string; filename: string } | null {
-    return this.links.openNodeInstall(token);
+  openNodeInstall(
+    token: string,
+    os?: string | null,
+    arch?: string | null,
+  ): Promise<{ script: string; filename: string } | null> {
+    return this.links.openNodeInstall(token, os, arch);
   }
 
   /** GET /node/binary — serve a grant's binary (single-use). */
@@ -1170,6 +1267,7 @@ let instance: MeshService | null = null;
 export function getMeshService(): MeshService {
   instance ??= new MeshService(undefined, {
     credentials: new DeviceCredentialStore(),
+    audit: new MeshAuditLog(),
   });
   return instance;
 }

package/src/core/mesh/links/bridge-links.ts

@@ -23,7 +23,13 @@ import {
   normalizeGoos,
   type NodeBinaryResolver,
 } from "./node-binaries.js";
-import { installOneLiner, NodeProvisionStore } from "./node-provision.js";
+import {
+  autoInstallOneLiners,
+  checkBridgeUrl,
+  installOneLiner,
+  installRefusalScript,
+  NodeProvisionStore,
+} from "./node-provision.js";
 import {
   DEFAULT_COMPANION_SCOPES,
   NODE_SCOPES,
@@ -56,6 +62,8 @@ export type MeshBridgeInfo = {
   token?: string;
   /** TLS certificate SHA-256 (absent over plain HTTP). */
   fingerprint?: string;
+  /** Base64 SHA-256 of the TLS key's SPKI, curl's pin (absent over HTTP). */
+  spkiPin?: string;
   /**
    * The operator's `native.publicUrl`: what devices dial when the bind
    * address isn't reachable as-is (containers, NAT, proxies).
@@ -135,9 +143,10 @@ export class BridgeLinks {
     name?: unknown,
     bridgeUrl?: unknown,
   ): Promise<MeshToolResult> {
+    const auto = isBlank(os) && isBlank(arch);
     const goos = normalizeGoos(os);
     const goarch = normalizeGoarch(arch);
-    if (!goos || !goarch) {
+    if (!auto && (!goos || !goarch)) {
       return { ok: false, text: unknownTargetText(os, arch) };
     }
     const info = this.bridgeInfo;
@@ -155,6 +164,33 @@ export class BridgeLinks {
     }
     const base = this.bridgeBaseUrl(info, bridgeUrl);
     if (typeof base !== "string") return { ok: false, text: base.error };
+    if (auto || !goos || !goarch) {
+      const pending = this.provision.createAuto({
+        ...(typeof name === "string" && name.trim()
+          ? { name: name.trim() }
+          : {}),
+        bridgeUrl: base,
+        bearerToken: this.linkCredential(info.token, NODE_SCOPES, "install"),
+        ...(info.fingerprint ? { fingerprint: info.fingerprint } : {}),
+        ...(info.spkiPin ? { spkiPin: info.spkiPin } : {}),
+      });
+      const cmd = autoInstallOneLiners(pending);
+      return {
+        ok: true,
+        text: [
+          "Run ONE of these on the new host — it reports its own OS and CPU, and the bridge picks the matching talon-node:",
+          "",
+          "Linux / macOS:",
+          `  ${cmd.posix}`,
+          "",
+          "Windows (elevated PowerShell or cmd):",
+          `  ${cmd.windows}`,
+          "",
+          `It installs talon-node (sha256-verified), pins the bridge certificate, and registers a boot service — the host appears on the mesh within a minute. Supported: ${NODE_TARGETS.map((t) => `${t.goos}/${t.goarch}`).join(", ")}.`,
+          `Single-use link, expires in 30 minutes. The host must be able to reach ${base}.`,
+        ].join("\n"),
+      };
+    }
     let bin;
     try {
       bin = await this.resolveNode(goos, goarch);
@@ -172,6 +208,7 @@ export class BridgeLinks {
       bridgeUrl: base,
       bearerToken: this.linkCredential(info.token, NODE_SCOPES, "install"),
       ...(info.fingerprint ? { fingerprint: info.fingerprint } : {}),
+      ...(info.spkiPin ? { spkiPin: info.spkiPin } : {}),
     });
     return {
       ok: true,
@@ -298,7 +335,46 @@ export class BridgeLinks {
   }
 
   /** GET /node/install — serve a grant's installer script (single-use). */
-  openNodeInstall(token: string): { script: string; filename: string } | null {
+  /**
+   * An auto grant is pinned here first, from the os/arch its one-liner
+   * reported; a host with no build gets a failing script and the grant
+   * stays unspent.
+   */
+  async openNodeInstall(
+    token: string,
+    os?: string | null,
+    arch?: string | null,
+  ): Promise<{ script: string; filename: string } | null> {
+    if (this.provision.isPending(token)) {
+      const goos = normalizeGoos(os);
+      const goarch = normalizeGoarch(arch);
+      if (!goos || !goarch) {
+        return {
+          script: installRefusalScript(
+            `no talon-node build for os=${os ?? ""} arch=${arch ?? ""}`,
+          ),
+          filename: "install-talon-node.txt",
+        };
+      }
+      try {
+        const bin = await this.resolveNode(goos, goarch);
+        this.provision.pin(token, {
+          goos,
+          goarch,
+          binaryPath: bin.path,
+          sha256: bin.sha256,
+          size: bin.size,
+          version: bin.version,
+        });
+      } catch (err) {
+        return {
+          script: installRefusalScript(
+            `could not resolve talon-node for ${goos}/${goarch}: ${(err as Error).message}`,
+          ),
+          filename: "install-talon-node.txt",
+        };
+      }
+    }
     return this.provision.openScript(token);
   }
 
@@ -318,17 +394,17 @@ export class BridgeLinks {
     info: MeshBridgeInfo,
     explicit?: unknown,
   ): string | { error: string } {
+    // Both URLs end up inside generated installer scripts, so they are held
+    // to a quote-safe alphabet (checkBridgeUrl), not just "looks like a URL".
     if (typeof explicit === "string" && explicit.trim()) {
-      const url = explicit.trim().replace(/\/+$/, "");
-      if (!/^https?:\/\/\S+$/.test(url)) {
-        return { error: `bridge_url must be an http(s) URL, got "${url}".` };
-      }
-      return url;
+      return checkBridgeUrl(explicit);
     }
     // Inside a container the "first external IPv4" is the container's own
     // bridge-network address, which no phone can reach — the operator's
     // public URL is the only right answer there.
-    if (info.publicUrl) return info.publicUrl.trim().replace(/\/+$/, "");
+    if (info.publicUrl) {
+      return checkBridgeUrl(info.publicUrl, "native.publicUrl");
+    }
     let host = info.host;
     if (host === "0.0.0.0" || host === "::") {
       const external = firstExternalIPv4();
@@ -348,6 +424,15 @@ export class BridgeLinks {
   }
 }
 
+/** An omitted tool argument: absent, or an empty/whitespace string. */
+function isBlank(value: unknown): boolean {
+  return (
+    value === undefined ||
+    value === null ||
+    (typeof value === "string" && !value.trim())
+  );
+}
+
 /** Error text for an os/arch pair outside the talon-node build matrix. */
 function unknownTargetText(os: unknown, arch: unknown): string {
   return `No talon-node target for os="${String(os)}", arch="${String(arch)}". Supported: ${NODE_TARGETS.map(