talon-agent 5.20.0 → 5.21.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) ────────────────────
@@ -1170,6 +1263,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,11 @@ import {
   normalizeGoos,
   type NodeBinaryResolver,
 } from "./node-binaries.js";
-import { installOneLiner, NodeProvisionStore } from "./node-provision.js";
+import {
+  checkBridgeUrl,
+  installOneLiner,
+  NodeProvisionStore,
+} from "./node-provision.js";
 import {
   DEFAULT_COMPANION_SCOPES,
   NODE_SCOPES,
@@ -56,6 +60,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).
@@ -172,6 +178,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,
@@ -318,17 +325,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();

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

@@ -14,9 +14,17 @@
  * 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,6 +49,8 @@ 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;
@@ -114,46 +124,162 @@ export class NodeProvisionStore {
   }
 }
 
+/**
+ * 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.
+ * 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 +287,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"
 `;
 }