Architecture ADRs: the client's future shape, runtime, identity, and API

[darksidemilk]

Exploratory. Nothing is implemented and no code is changed — four Markdown files under docs/adr/, nothing else. One of the four deliberately carries no recommendation; it is written to be settled here, in review.

fog-client has had no functional commit since March 2023 (v0.13.0) while the server it talks to shipped PKI work this year and still pins FOG_CLIENT_VERSION at 0.13.0. These documents record what turned up when we went looking at why, and what the options actually are.

The number the exploration turned on

find Modules -name '*.cs' -not -name '*.Designer.cs' | xargs cat | wc -l          # 3013
find UniversalInstaller SetupHelper UpdateHelper UpdateWaiter \
     ../zazzles/Zazzles/Modules/Updater ../zazzles/Zazzles/Bus \
     -name '*.cs' | xargs cat | wc -l                                            # 5658

Nearly twice as much code exists to let the agent be a self-updating compiled binary with its own IPC bus as exists to do the work. Of 17,526 lines across this repo and zazzles, roughly 3,000 are the product. Every other observation is downstream of that ratio.

The four ADRs

0001 — How much of FOG belongs on the endpoint — open, no recommendation. Deploy-time provisioning plus signed scripts on native schedulers, against keeping a compiled agent, with a module-by-module feasibility table. It does settle two things: agentless push is rejected in both futures (the server would have to store reusable fleet credentials on arguably the worst-defended box on the network; it cannot route to roaming or NATed clients; and on non-domain-joined Windows both WinRM and schtasks /s need a GPO or an agent to enable the thing meant to replace the agent), and a "thin agent" is a ratchet rather than a compromise — because it is compiled it needs an updater, which needs a second process, which needs a bus. That is not speculation; it is the 5,658 lines above.

Worth knowing before reading: the rename module is already agentless in production. funcs.sh:changeHostname() mounts the deployed NTFS volume and rewrites twenty registry values through reged. The C# path is a fallback.

0002 — The runtime, if a compiled agent survives — conditional on 0001. Recommends the current .NET LTS. Only five language constructs actually block the port (Thread.Abort, AppDomain.CreateDomain, the RSACryptoServiceProvider casts, AesCryptoServiceProvider, ServiceBase.Run), and the per-OS seam the Windows-only packages need already exists — System.Management being Windows-only costs nothing when its callers are already in Windows/ directories. Rejects Go (not worse, but worse from here), Rust (maintainer pool, said plainly), Node (posture for a SYSTEM service), Electron (a service has no window).

0003 — Client identity belongs in the application layer, not the certificate chain — independent of 0001. A per-client Ed25519 keypair plus ordinary platform TLS, over the per-client X.509/mTLS that "issued certs per client" suggests — that would reintroduce an online CA key months after GHSA-94p8-jg9j-99v4 caused one to be taken offline, and its revocation story degrades to a DB allowlist anyway. Covers migration with no machine touches, and the imaging problem at length.

Its Wall 1 was rewritten after finding fogproject ADR-0039 (2026-09-02), which landed SmbiosIdentity and deliberately kept the MAC as the identity. 0039 solved resolution; this is about authentication, which 0039 left untouched.

0004 — The client API is described in FOG's own OpenAPI document — new, independent of all three. Prompted by FOGProject/fog-sdk, created 2026-08-29, which generates PowerShell and Python clients from a pinned snapshot of FOG's live OpenAPI document.

The SDK cannot go on endpoints, and the reason is the useful part: all 380 paths in the snapshot are the administrative CRUD surface — there is no host check-in surface in the document at all — and all three security schemes authenticate a person, with tokens that act with their owner's roles, carry no scope, never expire, and are revocable only in the UI. Shipping one to a thousand workstations is the exact inverse of 0003.

So the SDK isn't the answer; the pipeline behind it is. Define the client protocol as real REST operations in the same document, under a separate hostAuth scheme, and generate the endpoint's HTTP layer instead of hand-writing it. The strongest support came from this project's own tests/openapi-route-coverage.test.php, whose docblock makes the argument unprompted: "a client generated from the document simply has no method for the missing endpoint, and the reasonable conclusion is that the server cannot do it." The host protocol is the largest body of routes entirely outside that guarantee.

Three claims about this codebase that are widely repeated and wrong

Each has been used to argue for a conclusion it does not support:

• AD join is not System.DirectoryServices — it is a netapi32 P/Invoke (NetJoinDomain/NetUnjoinDomain). Any runtime with FFI calls it identically, so this is not an argument for .NET.
• There is no WMI inventory in the client (that is FOS's job). The whole surface is four queries.
• Printer management is mostly shell-outs (rundll32 printui.dll, lpadmin), which lowers the bar for a non-.NET runtime.

And one about the docs: a Let's Encrypt certificate on the vhost does not break fog-client. Both copies of that page are internally inconsistent rather than wrong — the How FOG uses certificates section opens with a callout stating the correct post-zone-split position, while the body and TL;DR still name fog-client as the constraint and recommend step-ca.

A note on scope

0003 mentions a live vulnerability found while writing it and deliberately does not describe it, because this PR is public and the fix is small enough that the diff would disclose it. It's written up separately for the private advisory process in fogproject's SECURITY.md. Those fixes should not wait for any decision here.

Review

The useful thing to push back on is 0001 — that is the point of it being open. The weakest quantitative claim is 0002's 60–90 MB self-contained payload estimate, flagged in the text as an estimate. The LOC figures reproduce with the commands above.

None of these propose a change to fogproject or fog-sdk; references to those repos' ADRs and tests are reading references only.

🤖 Generated with Claude Code

https://claude.ai/code/session_016hejbUjsNJ7PyMdh8Cpet7