Skip to content

References — Fleet Dispatch

Technical track. Plain version: docs/plain/learn-more.md.

Links out to the standards, platform APIs, and CLI tools this repo builds on, plus "learn more" notes on the design patterns it uses. Every link is to the primary/official source.

Cryptography

  • HMAC-SHA256 — RFC 2104 (HMAC construction), FIPS 180-4 (SHA-256). Used for both the job signature (JobSigner) and the repo-registry inventory signature (RepoRegistrySigner).
  • System.Security.Cryptography.HMACSHA256 — .NET API docs.
  • CryptographicOperations.FixedTimeEquals — .NET API docs — constant-time comparison, used on every signature and bearer-token check in this repo so a network attacker cannot use response-timing to guess a valid HMAC or bearer byte-by-byte.
  • Timing side channels in string comparison — OWASP: Timing Attack — the general reason ==/string.Equals is never used on a secret-derived value in this codebase.

.NET / runtime

  • .NET 10 — What's new in .NET 10 (all three projects target net10.0).
  • HttpListener — .NET API docs — backs DispatchServer's /health and /dispatch endpoints.
  • System.Text.Json — docs, specifically JsonSerializerDefaults.Web (camelCase, case-insensitive) — the exact options RepoRegistrySigner must byte-for-byte match against fleet-mission-control's reader for signatures to verify.
  • Process / ProcessStartInfo.ArgumentList — .NET API docs — used instead of a single Arguments string specifically to avoid shell-quoting injection when passing a routed model name or prompt to a harness CLI.

Windows platform

  • Windows Task Scheduler — Task Scheduler docs — how the persistent listener is installed (never as a Windows Service; see ARCHITECTURE.md and README's Persistent Listener section for why).
  • HttpListener URL ACL reservations (netsh http add urlacl) — Configuring HTTP.sys — what lets an unprivileged process bind a port that would otherwise require admin rights.
  • Windows Service lifecycle / SCM start timeout — Service Control Manager — background on why a console app registered via sc.exe create gets killed after ~30 seconds (error 1053 / event 7000/7009) instead of running as a service.
  • HKEY_CURRENT_USER\Software\Valve\Steam\RunningAppID — not officially documented by Valve; this is a long-standing community-verified registry value (see e.g. PCGamingWiki: Steam registry keys) that reflects the currently-running game's Steam AppID, 0 when idle. WindowsAvailabilitySignalsProvider reads it unconditionally, with best-effort name resolution from the local appmanifest_<id>.acf file Steam already writes per installed title.
  • Windows Firewall scope (LocalSubnet vs. interface-bound rules) — New-NetFirewallRule docs — the fleet's firewall setup binds the tailnet rule to the Tailscale interface specifically, since a RemoteAddress filter alone is only a source-IP check that a hostile L2 peer could spoof over the physical NIC.

PowerShell

  • PowerShell 7 (pwsh) vs. Windows PowerShell 5.1 — PowerShell docs — RealJobExecutor resolves pwsh.exe off PATH and falls back to powershell.exe when it is absent (not every fleet box has PowerShell 7 installed).
  • Execution Policy — about_Execution_Policies — every shelled-out command in this repo passes -ExecutionPolicy Bypass explicitly rather than relying on the host's configured policy.

CLI tools the executor drives

  • Claude Code CLI — Anthropic docs — kind=claude; the stream-json protocol ClaudeStreamSession speaks is documented under Claude Code's headless/scripting modes.
  • OpenAI Codex CLI (rebranded "ChatGPT" in the MS Store; package/binary names unchanged) — OpenAI Codex docs — kind=codex; CodexAppServerSession uses the CLI's app-server protocol for live turn/steer.
  • Google Antigravity / Gemini CLI (agy) — Google AI docs — kind=agy.
  • xAI Grok CLI (grok) — xAI docs — kind=grok.
  • Ollama — Ollama docs — kind=ollama, local-model inference.

Design patterns used here — learn more

Signed-command file queue

A durable, store-and-forward command channel where the transport (here, a synced OneDrive folder) is untrusted for authenticity but trusted for eventual delivery. Every command is signed at the source and re-verified at the point of execution; the transport only needs to preserve bytes, not guarantee who wrote them. Background reading: message-queue authenticity patterns generally use either a shared-secret MAC (what this repo does — one fleet-wide HMAC key) or asymmetric signing when senders and receivers must not share a secret. See NIST SP 800-107: HMAC recommendations for the tradeoffs.

Canonical-string signing + explicit schema versioning

Signing a delimiter-joined canonical string (rather than, say, signing raw JSON) makes the signed surface explicit and stable independent of JSON serialization quirks (key order, whitespace, Unicode escaping) that would otherwise make two semantically-identical payloads sign differently. The companion discipline — a separate, unsigned schema-version field checked before the signature — lets a receiver distinguish "this sender is newer than me" from "this payload was tampered with," which are different operational problems with different fixes. See Google's guidance on API/wire versioning and general discussion of the "explicit version negotiation vs. silent failure" tradeoff in Postel's Law / robustness principle — this repo deliberately does not apply the robustness principle to schema mismatches; it names the skew instead of trying to be lenient about it, because leniency here previously produced a misleading invalid-hmac report (FLT-70).

Fail-closed gating

A gate that defaults to refuse when its input is missing, malformed, or unrecognized, rather than defaulting to allow. This repo applies it selectively and documents each choice: an unrecognized JobClass fails closed (blocked while unavailable) because the alternative is a heavy job silently slipping through; a corrupt manual-override file fails open (treated as "auto") because the alternative is a single bad local file freezing the whole PC's dispatch capability. General background: OWASP: Fail Securely — note the OWASP framing is itself about picking the right failure mode per resource, not "always deny," which matches the split decision this codebase makes.

Steam RunningAppID presence detection

A registry-poll presence check rather than a hooked/instrumented one — cheap, no injection into the game process, but only as fresh as the poll interval (hence the detector's separate hysteresis layer to avoid publishing a flickery signal). This is the same basic technique Steam-integration tools (overlay injectors, streaming software's "game capture" auto-detect) use as a first-pass signal before falling back to a window-title or process-list heuristic — which is exactly the "P2 fullscreen+GPU heuristic" this repo has documented as a deferred future addition, not built.