talon-agent 5.20.1 → 5.22.0

package/src/core/mesh/links/node-provision.ts

@@ -9,14 +9,28 @@
  *   GET /node/install?provision=<token>   → installer script (once)
  *   GET /node/binary?provision=<token>    → the binary itself (once)
  *
+ * A grant can also be minted WITHOUT a target ("auto"): the one-liner then
+ * reports the host's own `uname -s`/`uname -m` (or PowerShell's
+ * PROCESSOR_ARCHITECTURE) on the script fetch, and the caller resolves the
+ * binary and pins it into the grant before the script is rendered — so the
+ * script still embeds the digest and nothing about integrity changes.
+ *
  * The routes must work pre-auth — the whole point is a host that holds no
  * bridge credential yet — so the grant token IS the authorization, exactly
  * like streamed-transfer tokens (transfers/transfers.ts): random 192-bit, single-use
  * per leg, expiring unused. The script carries the bridge bearer token and
  * pinned TLS fingerprint into the node's config, verifies the downloaded
- * binary against the grant's digest (integrity is the script's own sha256
- * check, not TLS), installs it, and registers the boot service via
- * `talon-node install`.
+ * binary against the grant's digest, installs it, and registers the boot
+ * service via `talon-node install`.
+ *
+ * Over HTTPS both fetches (script and binary) are pinned to the bridge's own
+ * key — curl `--pinnedpubkey`, a certificate SHA-256 check on Windows — so a
+ * man in the middle can neither swap the script nor read the grant's bearer
+ * credential off the wire. Plain HTTP has nothing to pin.
+ *
+ * Every value that lands in generated sh/PowerShell text is validated to a
+ * quote-safe alphabet at the edge ({@link checkBridgeUrl}, device names) and
+ * escaped for its quoting context here anyway.
  */
 
 import { randomBytes } from "node:crypto";
@@ -41,13 +55,29 @@ export type NodeProvisionGrant = {
   bearerToken: string;
   /** Bridge TLS certificate fingerprint to pre-pin (absent over plain HTTP). */
   fingerprint?: string;
+  /** Base64 SHA-256 of the bridge key's SPKI — curl's pin (absent over HTTP). */
+  spkiPin?: string;
   createdAt: number;
   scriptUsed: boolean;
   binaryUsed: boolean;
 };
 
+/** The fields an auto grant is missing until the target host reports in. */
+export type NodeProvisionTarget = Pick<
+  NodeProvisionGrant,
+  "goos" | "goarch" | "binaryPath" | "sha256" | "size" | "version"
+>;
+
+/** An auto grant before its target is known — everything but the binary. */
+export type PendingNodeProvision = Omit<
+  NodeProvisionGrant,
+  keyof NodeProvisionTarget | "scriptUsed" | "binaryUsed"
+>;
+
 export class NodeProvisionStore {
   private readonly grants = new Map<string, NodeProvisionGrant>();
+  /** Auto grants whose target host hasn't fetched the script yet. */
+  private readonly pending = new Map<string, PendingNodeProvision>();
 
   constructor(private readonly ttlMs = GRANT_TTL_MS) {}
 
@@ -60,11 +90,7 @@ export class NodeProvisionStore {
     this.sweep();
     const full: NodeProvisionGrant = {
       ...grant,
-      // Device names are injected into generated shell/PowerShell text —
-      // keep them to characters that can't break out of a quoted string.
-      ...(grant.name
-        ? { name: grant.name.replace(/[^\w .-]+/g, "").slice(0, 64) }
-        : {}),
+      ...sanitizedName(grant.name),
       token: randomBytes(24).toString("base64url"),
       createdAt: Date.now(),
       scriptUsed: false,
@@ -74,6 +100,48 @@ export class NodeProvisionStore {
     return full;
   }
 
+  /**
+   * Mint an auto grant: no target yet. {@link pin} fills it in when the host
+   * fetches the script and reports its own os/arch.
+   */
+  createAuto(
+    grant: Omit<PendingNodeProvision, "token" | "createdAt">,
+  ): PendingNodeProvision {
+    this.sweep();
+    const pending: PendingNodeProvision = {
+      ...grant,
+      ...sanitizedName(grant.name),
+      token: randomBytes(24).toString("base64url"),
+      createdAt: Date.now(),
+    };
+    this.pending.set(pending.token, pending);
+    return pending;
+  }
+
+  /** Whether `token` is a live auto grant still waiting for its target. */
+  isPending(token: string): boolean {
+    this.sweep();
+    return this.pending.has(token);
+  }
+
+  /**
+   * Bind an auto grant to the binary for its host. It becomes an ordinary
+   * grant under the same token (same TTL clock); a second pin is a no-op.
+   */
+  pin(token: string, target: NodeProvisionTarget): boolean {
+    this.sweep();
+    const pending = this.pending.get(token);
+    if (!pending) return false;
+    this.pending.delete(token);
+    this.grants.set(token, {
+      ...pending,
+      ...target,
+      scriptUsed: false,
+      binaryUsed: false,
+    });
+    return true;
+  }
+
   /** Serve the installer script for a live grant — once. */
   openScript(token: string): { script: string; filename: string } | null {
     const grant = this.claim(token, "scriptUsed");
@@ -111,49 +179,216 @@ export class NodeProvisionStore {
     for (const [token, grant] of this.grants) {
       if (grant.createdAt < cutoff) this.grants.delete(token);
     }
+    for (const [token, grant] of this.pending) {
+      if (grant.createdAt < cutoff) this.pending.delete(token);
+    }
+  }
+}
+
+/**
+ * Device names are injected into generated shell/PowerShell text — keep them
+ * to characters that can't break out of a quoted string.
+ */
+function sanitizedName(name: string | undefined): { name?: string } {
+  return name ? { name: name.replace(/[^\w .-]+/g, "").slice(0, 64) } : {};
+}
+
+/**
+ * Anything that could end, expand, or escape inside a quoted sh,
+ * PowerShell, or cmd.exe string: both quote kinds, `$`, backtick,
+ * backslash, `%` (cmd.exe expands `%VAR%` even inside quotes), and
+ * everything outside printable ASCII — whitespace, control characters, and
+ * the Unicode "smart" quotes PowerShell also treats as quotes.
+ */
+const UNSAFE_URL_CHAR = /["'`$\\%]|[^\x21-\x7e]/;
+
+/**
+ * Validate a bridge base URL before it is baked into installer scripts: an
+ * http(s) URL with a host, made only of characters that are inert in every
+ * quoting context the installers use. Returns the URL without trailing
+ * slashes, or why it was refused.
+ */
+export function checkBridgeUrl(
+  raw: string,
+  label = "bridge_url",
+): string | { error: string } {
+  const url = raw.trim().replace(/\/+$/, "");
+  const refused = {
+    error: `${label} must be a plain http(s) URL (no quotes, $, backticks, backslashes, % or whitespace), got ${JSON.stringify(url)}.`,
+  };
+  if (UNSAFE_URL_CHAR.test(url)) return refused;
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return refused;
   }
+  const web = parsed.protocol === "http:" || parsed.protocol === "https:";
+  return web && parsed.hostname ? url : refused;
+}
+
+// ── Quoting ──────────────────────────────────────────────────────────────────
+
+/** Escape for a double-quoted POSIX sh string. */
+function sh(value: string): string {
+  return value.replace(/["$`\\]/g, "\\$&");
 }
 
+/** Escape for a double-quoted PowerShell string (backtick is the escape). */
+function ps(value: string): string {
+  return value.replace(/["$`“”„]/g, "`$&");
+}
+
+/** Escape for a single-quoted PowerShell string (quotes double up). */
+function psq(value: string): string {
+  return value.replace(/['‘’‚‛]/g, "$&$&");
+}
+
+/** Keep a value on one line — for `#` comment lines. */
+function oneLine(value: string): string {
+  return value.replace(/[\r\n]+/g, " ");
+}
+
+// ── Pinning ──────────────────────────────────────────────────────────────────
+
+/**
+ * Pinned fetches for PowerShell, compiled with Add-Type so the certificate
+ * callback is a real .NET delegate: a script-block callback only works on
+ * the pipeline thread (Windows PowerShell 5.1's synchronous iwr), while
+ * pwsh 7's HttpClient calls it from the thread pool, where no runspace
+ * exists. HttpWebRequest's per-request callback exists on .NET Framework
+ * 4.5+ and every .NET Core, so one source serves both shells; -IgnoreWarnings
+ * because pwsh 7 would fail on WebRequest's obsolete warning.
+ *
+ * The check: the presented certificate's SHA-256 (BitConverter's `AB-CD-…`
+ * form) must equal `[TalonPin]::Pin` — the same certificate hash talon-node
+ * pins afterwards. An unset pin fails closed. The source holds no quotes,
+ * `$` or `%`, so it survives a PowerShell single-quoted string inside a
+ * cmd.exe (or PowerShell) double-quoted `-Command` argument.
+ */
+const PIN_TYPE_SOURCE =
+  "using System;using System.IO;using System.Net;using System.Security.Cryptography;" +
+  "public static class TalonPin{public static string Pin;" +
+  "static WebResponse Open(string u){var r=(HttpWebRequest)WebRequest.Create(u);" +
+  "r.ServerCertificateValidationCallback=(s,c,h,e)=>c!=null&&string.Equals(" +
+  "BitConverter.ToString(SHA256.Create().ComputeHash(c.GetRawCertData())),Pin,StringComparison.OrdinalIgnoreCase);" +
+  "return r.GetResponse();}" +
+  "public static string Get(string u){using(var w=Open(u))using(var t=new StreamReader(w.GetResponseStream()))return t.ReadToEnd();}" +
+  "public static void Save(string u,string p){using(var w=Open(u))using(var i=w.GetResponseStream())using(var o=File.Create(p))i.CopyTo(o);}}";
+
+/** `abcd…` → `AB-CD-…`, the form BitConverter.ToString gives a hash. */
+function dashedFingerprint(fingerprint: string): string {
+  return (fingerprint.match(/.{2}/g) ?? []).join("-").toUpperCase();
+}
+
+/** PowerShell statements that load TalonPin and arm it with the pin. */
+function psPinSetup(fingerprint: string): string {
+  return (
+    `if (-not ('TalonPin' -as [type])) { Add-Type -IgnoreWarnings -TypeDefinition '${psq(PIN_TYPE_SOURCE)}' }; ` +
+    `[TalonPin]::Pin = '${psq(dashedFingerprint(fingerprint))}'`
+  );
+}
+
+/**
+ * curl flags for a bridge fetch. With a pin, `-k` stays on purpose: the
+ * bridge cert is self-signed and curl still chain-verifies without `-k`,
+ * even when the pin matches — while `--pinnedpubkey` is enforced with or
+ * without `-k`. So the pin, not the chain, is the real check. Without one
+ * (plain HTTP, nothing to pin) the flags are unchanged.
+ */
+function curlFlags(spkiPin: string | undefined): string {
+  return spkiPin ? `-fsSk --pinnedpubkey "sha256//${sh(spkiPin)}"` : "-fsSk";
+}
+
+// ── Generated commands ───────────────────────────────────────────────────────
+
 /** The command a human (or the model over SSH) runs on the target host. */
 export function installOneLiner(grant: NodeProvisionGrant): string {
   const url = `${grant.bridgeUrl}/node/install?provision=${grant.token}`;
-  if (grant.goos === "windows") {
-    // -k has no iwr flag; trust-all callback covers the self-signed bridge
-    // cert for the two fetches — the binary itself is digest-verified. The
-    // one-liner is meant for cmd.exe / PowerShell, where $true survives the
-    // outer double quotes verbatim.
+  if (grant.goos !== "windows") {
+    return `curl ${curlFlags(grant.spkiPin)} "${sh(url)}" | sh`;
+  }
+  if (grant.fingerprint) {
+    // No `$` anywhere, so the line means the same pasted into cmd.exe or a
+    // PowerShell prompt (whose double quotes would expand variables).
     return (
       `powershell -ExecutionPolicy Bypass -Command "` +
-      `[Net.ServicePointManager]::ServerCertificateValidationCallback={$true}; ` +
-      `iwr -UseBasicParsing '${url}' | Select-Object -ExpandProperty Content | iex"`
+      `${psPinSetup(grant.fingerprint)}; ` +
+      `iex ([TalonPin]::Get('${psq(url)}'))"`
     );
   }
-  return `curl -fsSk "${url}" | sh`;
+  // Plain HTTP: nothing to pin, and the trust-all callback is inert. The
+  // line is meant for cmd.exe, where $true survives the outer double quotes.
+  return (
+    `powershell -ExecutionPolicy Bypass -Command "` +
+    `[Net.ServicePointManager]::ServerCertificateValidationCallback={$true}; ` +
+    `iwr -UseBasicParsing '${psq(url)}' | Select-Object -ExpandProperty Content | iex"`
+  );
 }
 
 /**
- * POSIX installer: fetch the binary over the same grant, verify its digest,
- * install it next to the node's config, and register the boot service. -k on
- * the fetches is deliberate — the bridge cert is self-signed; integrity
- * comes from the embedded sha256 and the fingerprint is pre-pinned into the
- * node's config for every connection after install.
+ * The two commands for an auto grant — one per shell family, pinned exactly
+ * like {@link installOneLiner}. Each appends its host's platform to the
+ * script fetch; the bridge maps `Linux`/`Darwin`, `x86_64`/`aarch64`/
+ * `armv7l`, and PowerShell's `AMD64`/`ARM64` through the same normalizers
+ * the tool arguments use.
+ *
+ * The PowerShell line carries one `$` (`$env:PROCESSOR_ARCHITECTURE`): from
+ * cmd.exe it reaches PowerShell verbatim, and from a PowerShell prompt the
+ * outer double quotes expand it first — the same value either way.
+ */
+export function autoInstallOneLiners(
+  grant: Pick<
+    NodeProvisionGrant,
+    "bridgeUrl" | "token" | "fingerprint" | "spkiPin"
+  >,
+): { posix: string; windows: string } {
+  const url = `${grant.bridgeUrl}/node/install?provision=${grant.token}`;
+  const posix = `curl ${curlFlags(grant.spkiPin)} "${sh(url)}&os=$(uname -s)&arch=$(uname -m)" | sh`;
+  const psUrl = `('${psq(url)}&os=windows&arch=' + $env:PROCESSOR_ARCHITECTURE)`;
+  const windows = grant.fingerprint
+    ? `powershell -ExecutionPolicy Bypass -Command "` +
+      `${psPinSetup(grant.fingerprint)}; ` +
+      `iex ([TalonPin]::Get${psUrl})"`
+    : `powershell -ExecutionPolicy Bypass -Command "` +
+      `[Net.ServicePointManager]::ServerCertificateValidationCallback={$true}; ` +
+      `iwr -UseBasicParsing ${psUrl} | Select-Object -ExpandProperty Content | iex"`;
+  return { posix, windows };
+}
+
+/**
+ * What an auto grant serves when the host's platform has no build or the
+ * binary can't be resolved: a script that fails loudly. Valid as both POSIX
+ * sh and PowerShell, since which shell is piping it isn't known.
+ */
+export function installRefusalScript(reason: string): string {
+  const safe = reason.replace(/["'`$\\%\n\r]+/g, " ").slice(0, 300);
+  return `echo "talon-node install refused: ${safe}"\nexit 1\n`;
+}
+
+/**
+ * POSIX installer: fetch the binary over the same grant (pinned like the
+ * script fetch), verify its digest, install it next to the node's config,
+ * and register the boot service. The certificate fingerprint is pre-pinned
+ * into the node's config for every connection after install.
  */
 function shellInstaller(grant: NodeProvisionGrant): string {
-  const nameFlag = grant.name ? ` --name "${grant.name}"` : "";
+  const nameFlag = grant.name ? ` --name "${sh(grant.name)}"` : "";
   const fpFlag = grant.fingerprint
-    ? ` --fingerprint "${grant.fingerprint}"`
+    ? ` --fingerprint "${sh(grant.fingerprint)}"`
     : "";
+  const target = `${grant.version} (${grant.goos}/${grant.goarch})`;
   return `#!/bin/sh
-# talon-node installer — generated by Talon ${grant.version} for ${grant.goos}/${grant.goarch}
+# talon-node installer — generated by Talon ${oneLine(`${grant.version} for ${grant.goos}/${grant.goarch}`)}
 set -eu
-BRIDGE="${grant.bridgeUrl}"
-SHA="${grant.sha256}"
+BRIDGE="${sh(grant.bridgeUrl)}"
+SHA="${sh(grant.sha256)}"
 if [ "$(id -u)" = "0" ]; then DEST_DIR="\${TALON_NODE_DIR:-/usr/local/bin}"; else DEST_DIR="\${TALON_NODE_DIR:-$HOME/.talon-node/bin}"; fi
 mkdir -p "$DEST_DIR"
 TMP="$(mktemp)"
 trap 'rm -f "$TMP"' EXIT
-echo "Downloading talon-node ${grant.version} (${grant.goos}/${grant.goarch})..."
-curl -fsSk "$BRIDGE/node/binary?provision=${grant.token}" -o "$TMP"
+echo "Downloading talon-node ${sh(target)}..."
+curl ${curlFlags(grant.spkiPin)} "$BRIDGE/node/binary?provision=${sh(grant.token)}" -o "$TMP"
 if command -v sha256sum >/dev/null 2>&1; then GOT="$(sha256sum "$TMP" | cut -d' ' -f1)"; else GOT="$(shasum -a 256 "$TMP" | cut -d' ' -f1)"; fi
 if [ "$GOT" != "$SHA" ]; then echo "talon-node download failed its checksum — refusing to install" >&2; exit 1; fi
 BIN="$DEST_DIR/talon-node"
@@ -161,37 +396,46 @@ mv "$TMP" "$BIN"
 chmod 0755 "$BIN"
 trap - EXIT
 echo "Installed $BIN"
-"$BIN" install --bridge "$BRIDGE" --token "${grant.bearerToken}"${fpFlag}${nameFlag}
+"$BIN" install --bridge "$BRIDGE" --token "${sh(grant.bearerToken)}"${fpFlag}${nameFlag}
 echo "Done — this host is now on the mesh. Check with: $BIN status"
 `;
 }
 
+/** The PowerShell lines that download the binary to `$bin`. */
+function psBinaryFetch(grant: NodeProvisionGrant): string {
+  const url = `"$bridge/node/binary?provision=${ps(grant.token)}"`;
+  return grant.fingerprint
+    ? `${psPinSetup(grant.fingerprint)}\n[TalonPin]::Save(${url}, $bin)`
+    : `[Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }\n` +
+        `Invoke-WebRequest -UseBasicParsing ${url} -OutFile $bin`;
+}
+
 /**
- * PowerShell installer (Windows PowerShell 5+ compatible). The binary lands in
- * the installing user's %LOCALAPPDATA% and `talon-node install` registers a
- * boot task that runs as that same user (never SYSTEM — a SYSTEM task would
+ * PowerShell installer (Windows PowerShell 5.1 and pwsh 7). The binary lands
+ * in the installing user's %LOCALAPPDATA% and `talon-node install` registers
+ * a boot task that runs as that same user (never SYSTEM — a SYSTEM task would
  * run a binary the user can rewrite). Registering a boot task needs an
  * elevated PowerShell.
  */
 function powershellInstaller(grant: NodeProvisionGrant): string {
-  const nameArg = grant.name ? `, "--name", "${grant.name}"` : "";
+  const nameArg = grant.name ? `, "--name", "${ps(grant.name)}"` : "";
   const fpArg = grant.fingerprint
-    ? `, "--fingerprint", "${grant.fingerprint}"`
+    ? `, "--fingerprint", "${ps(grant.fingerprint)}"`
     : "";
-  return `# talon-node installer — generated by Talon ${grant.version} for ${grant.goos}/${grant.goarch}
+  const target = `${grant.version} (${grant.goos}/${grant.goarch})`;
+  return `# talon-node installer — generated by Talon ${oneLine(`${grant.version} for ${grant.goos}/${grant.goarch}`)}
 $ErrorActionPreference = "Stop"
-[Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }
-$bridge = "${grant.bridgeUrl}"
+$bridge = "${ps(grant.bridgeUrl)}"
 $dest = Join-Path $env:LOCALAPPDATA "talon-node"
 New-Item -ItemType Directory -Force -Path $dest | Out-Null
 $bin = Join-Path $dest "talon-node.exe"
-Write-Host "Downloading talon-node ${grant.version} (${grant.goos}/${grant.goarch})..."
-Invoke-WebRequest -UseBasicParsing "$bridge/node/binary?provision=${grant.token}" -OutFile $bin
+Write-Host "Downloading talon-node ${ps(target)}..."
+${psBinaryFetch(grant)}
 $got = (Get-FileHash $bin -Algorithm SHA256).Hash.ToLower()
-if ($got -ne "${grant.sha256}") { Remove-Item $bin; throw "talon-node download failed its checksum - refusing to install" }
+if ($got -ne "${ps(grant.sha256)}") { Remove-Item $bin; throw "talon-node download failed its checksum - refusing to install" }
 Write-Host "Installed $bin"
 Write-Host "Registering the boot task to run as $env:USERDOMAIN\\$env:USERNAME (not SYSTEM)..."
-& $bin install --bridge $bridge --token "${grant.bearerToken}"${fpArg}${nameArg}
+& $bin install --bridge $bridge --token "${ps(grant.bearerToken)}"${fpArg}${nameArg}
 Write-Host "Done - this host is now on the mesh. Check with: $bin status"
 `;
 }

package/src/core/mesh/transfers/device-files.ts

@@ -15,10 +15,11 @@
  */
 
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import type { Readable } from "node:stream";
+import { logDebug } from "../../../util/log.js";
 import { dirs } from "../../../util/paths.js";
 import {
   formatBytes,
@@ -127,6 +128,14 @@ const MAX_CHUNKED_TRANSFER_BYTES = 64 * 1024 * 1024;
  * Resolved lazily (not at module load) so a test that mocks `util/paths`
  * doesn't hit its workspace binding before initialization.
  */
+/**
+ * The opt-in rollback flag for install_apk / update_node. Sent only when set,
+ * so the default command shape is exactly what older devices already accept.
+ */
+function downgradeParam(allow: unknown): { allow_downgrade?: true } {
+  return allow === true ? { allow_downgrade: true } : {};
+}
+
 function pullDir(): string {
   return resolve(dirs.workspace, "mesh-pull");
 }
@@ -202,7 +211,7 @@ export class DeviceFiles {
     // is normally already resolved — the grace window only catches a device
     // that claims success without having streamed anything.
     try {
-      const bytes = await Promise.race([
+      const receipt = await Promise.race([
         done,
         new Promise<never>((_, rej) =>
           setTimeout(
@@ -216,13 +225,83 @@ export class DeviceFiles {
           ).unref?.(),
         ),
       ]);
-      return { bytes };
+      // The device hashed what it sent; the store hashed what arrived.
+      const mismatch = digestMismatch(
+        dispatched.result,
+        receipt.sha256,
+        `pull of ${remote} from ${target.name}`,
+      );
+      if (mismatch) {
+        await rm(dest, { force: true }).catch(() => {});
+        return {
+          error: `Integrity check failed pulling ${remote} from ${target.name}: ${mismatch}. The received copy was discarded.`,
+        };
+      }
+      return { bytes: receipt.bytes };
     } catch (err) {
       this.transfers.cancel(token);
       return { error: (err as Error).message };
     }
   }
 
+  /**
+   * Streamed daemon→device transfer: one command round trip, the body as a
+   * single raw HTTP response. The source's SHA-256 rides along so the device
+   * can refuse to rename a corrupted temp file into place; its reported
+   * digest is checked here too.
+   */
+  private async pushViaStream(
+    target: DeviceInfo,
+    local: string,
+    remote: string,
+  ): Promise<MeshToolResult> {
+    const started = Date.now();
+    // Hashing the source also sizes the budget (a local read, not a mesh
+    // round trip). A source we cannot read still gets a bounded, looser
+    // budget and no digest — this decides a timeout, not whether the
+    // transfer may start.
+    const source = await hashFile(local).catch(() => undefined);
+    const { token } = this.transfers.createPush(target.id, local);
+    const dispatched = await this.host.dispatchCommand(
+      target.id,
+      "download_file",
+      { token, path: remote, ...(source && { sha256: source.sha256 }) },
+      streamTransferTimeoutMs(source?.size),
+    );
+    if ("error" in dispatched) {
+      this.transfers.cancel(token);
+      return { ok: false, text: dispatched.error };
+    }
+    if (!dispatched.result.ok) {
+      this.transfers.cancel(token);
+      return {
+        ok: false,
+        text:
+          dispatched.result.message ??
+          `${target.name} could not download ${local}.`,
+      };
+    }
+    const mismatch =
+      source &&
+      digestMismatch(
+        dispatched.result,
+        source.sha256,
+        `push of ${local} to ${target.name}`,
+      );
+    if (mismatch) {
+      return {
+        ok: false,
+        text: `Integrity check failed pushing ${local} to ${remote} on ${target.name}: ${mismatch}.`,
+      };
+    }
+    const bytes = dispatched.result.data?.bytesWritten;
+    const size = typeof bytes === "number" ? bytes : 0;
+    return {
+      ok: true,
+      text: `Pushed ${formatBytes(size)} to ${remote} on ${target.name} (streamed, ${transferRate(size, started)})`,
+    };
+  }
+
   /**
    * Raw file bytes off a device — the structured primitive under both the
    * human-readable tool below and the native read/edit path (which must not
@@ -381,40 +460,7 @@ export class DeviceFiles {
     if ("error" in resolved) return { ok: false, text: resolved.error };
     const target = resolved.target;
     if (this.canStream(target, "download_file")) {
-      const started = Date.now();
-      // The source is on this host, so sizing the budget costs a local stat
-      // rather than a mesh round trip. A source we cannot stat still gets a
-      // bounded (if looser) budget — this decides a timeout, not whether
-      // the transfer is allowed to start.
-      const localSize = await stat(local)
-        .then((s) => s.size)
-        .catch(() => undefined);
-      const { token } = this.transfers.createPush(target.id, local);
-      const dispatched = await this.host.dispatchCommand(
-        target.id,
-        "download_file",
-        { token, path: remote },
-        streamTransferTimeoutMs(localSize),
-      );
-      if ("error" in dispatched) {
-        this.transfers.cancel(token);
-        return { ok: false, text: dispatched.error };
-      }
-      if (!dispatched.result.ok) {
-        this.transfers.cancel(token);
-        return {
-          ok: false,
-          text:
-            dispatched.result.message ??
-            `${target.name} could not download ${local}.`,
-        };
-      }
-      const bytes = dispatched.result.data?.bytesWritten;
-      const size = typeof bytes === "number" ? bytes : 0;
-      return {
-        ok: true,
-        text: `Pushed ${formatBytes(size)} to ${remote} on ${target.name} (streamed, ${transferRate(size, started)})`,
-      };
+      return this.pushViaStream(target, local, remote);
     }
     let data: Buffer;
     try {
@@ -450,6 +496,7 @@ export class DeviceFiles {
     query: unknown,
     localApkPath: unknown,
     remotePath?: unknown,
+    allowDowngrade?: unknown,
   ): Promise<MeshToolResult> {
     const local =
       typeof localApkPath === "string" && localApkPath.trim()
@@ -496,7 +543,7 @@ export class DeviceFiles {
     const dispatched = await this.host.dispatchCommand(
       target.id,
       "install_apk",
-      { path: remote, sha256 },
+      { path: remote, sha256, ...downgradeParam(allowDowngrade) },
       this.host.commandTimeoutMs,
     );
     if ("error" in dispatched) return { ok: false, text: dispatched.error };
@@ -535,6 +582,7 @@ export class DeviceFiles {
     query: unknown,
     localBinaryPath?: unknown,
     remotePath?: unknown,
+    allowDowngrade?: unknown,
   ): Promise<MeshToolResult> {
     await this.host.load();
     const resolved = this.host.resolveDevice(query);
@@ -604,7 +652,7 @@ export class DeviceFiles {
     const dispatched = await this.host.dispatchCommand(
       target.id,
       "update_node",
-      { path: remote, sha256 },
+      { path: remote, sha256, ...downgradeParam(allowDowngrade) },
       this.host.commandTimeoutMs,
     );
     if ("error" in dispatched) return { ok: false, text: dispatched.error };
@@ -738,6 +786,29 @@ export class DeviceFiles {
   }
 }
 
+/**
+ * Compare the SHA-256 a device reported for a streamed transfer with the one
+ * the daemon holds. Returns a description of a mismatch, or null when they
+ * agree. A device build that predates transfer digests reports none; the
+ * check is then skipped (with a debug line), never failed.
+ */
+function digestMismatch(
+  result: DeviceCommandResult,
+  expected: string,
+  what: string,
+): string | null {
+  const reported = result.data?.sha256;
+  if (typeof reported !== "string" || !reported) {
+    logDebug(
+      "mesh",
+      `${what}: device reported no sha256 (older build) — skipping the integrity check`,
+    );
+    return null;
+  }
+  if (reported.toLowerCase() === expected.toLowerCase()) return null;
+  return `the device reported sha256 ${reported}, the daemon has ${expected}`;
+}
+
 /** "12.4 MB/s in 3.2s" — observability for streamed transfers. */
 function transferRate(bytes: number, startedAtMs: number): string {
   const seconds = Math.max((Date.now() - startedAtMs) / 1000, 0.001);