Skip to content

0036: Windows semantics for POSIX-shaped contracts

  • Status: accepted
  • Date: 2026-10-07

Context

The first full make check-windows runs (ADR 0024; tickets 01M3D7GD45SEZD7Y0RXWPAC6KF, 01M4BKSMKJ6DTQA5RE39H9AKG1, 01M4BKSMGQ15147H58RJ4XH8XZ, 01M4AGQDC4D2QPBXWV2SQTGSV9) found tests whose assertions were written in POSIX terms and whose production code assumed POSIX error semantics. Each needed a ruling on what the contract means on Windows before a test could pin it; the rulings that change or sharpen a contract are recorded here, the purely test-side fixes only on their tickets.

Decisions

  1. A private key file. "Mode 0600" is the unix statement of a contract: only the current user can read or write the file, from the moment it exists. On Windows the POSIX bits Go applies are advisory (0600 only decides the read-only attribute) and a new file inherits its directory's DACL, which outside the user's profile commonly lets Users or Everyone read. A private file on Windows is therefore one created with an explicit security descriptor, passed at creation (never applied afterwards), whose DACL is protected against inheritance and holds exactly two allow entries: full access for the current user (the process token's user SID) and for SYSTEM. This is the rule the daemon's named pipe already follows (transport.PipeSDDL). Administrators get no entry: they can take ownership anyway, and an explicit grant would let any elevated process read key material without that step. Seam: cli.createPrivateFile, first used by dev key new --out; inject --out and entry edit's temporary file have the same gap and should follow.

  2. A path below a regular file is never "missing". On Windows a path whose parent is a regular file fails with ERROR_PATH_NOT_FOUND, which Go maps to fs.ErrNotExist, where unix reports ENOTDIR. Code that reads not-exist as "nothing here yet" (an empty blob store, an output that does not exist yet, no .gitattributes yet) therefore accepts a file in a directory's place on Windows. The contract on every OS: a missing path is acceptable only when its nearest existing ancestor is a directory; otherwise it is refused as not a directory (backup.ErrUnexpectedFile for the blob store, a plain refusal that is not not-exist for a backup output or data directory and for vault.Init's Options.Dir), and nothing is written first. A missing Options.Dir is now refused by vault.Init's pre-check too (an error wrapping fs.ErrNotExist, before any key file is written), where it used to fail only at the later .gitattributes write; every caller creates the directory first.

  3. A directory entry's cached info is not a stat. On Windows os.ReadDir fills each DirEntry from the listing (FindFirstFile), so DirEntry.Info succeeds for a file removed after listing; on unix it is a lazy lstat that fails. Code that must notice a vanished entry (the backup's blob-store visitor) calls os.Lstat on the path itself.

  4. ? in file names. The SQLite DSN builder (cloud/internal/sqlitedsn) percent-encodes every URI delimiter in a path (?, #, %, space) on every OS; that is pinned by a pure test. Only unix can hold a ? in a file name, so the filesystem round-trip tests use names without it on Windows and keep the rest.

  5. A protocol violation is audited before its answer is readable. add-agent-daemon design.md "Group 5 decisions" 18 promises that a request's audit record exists before the peer can read the answer (the final-byte hook). Violations agentproto.ServerConn.ReadRequest answers itself (unknown-verb, no-session, malformed, hello-required, frame-too-large) were audited after the answer was on the wire, which the named-pipe transport exposed on every run and a loaded linux host intermittently. The ordering is extended to violations rather than the test relaxed: ServerConn.SetViolationHook runs the daemon's hook before any byte of the violation's answer is written, and the daemon writes the violation's audit record there, under the connection's write lock (as its final-byte hook already does for served requests).

  6. Reading a pipe's DACL must tolerate a daemon between accepts. GetNamedSecurityInfo opens the pipe as a client and fails with ERROR_PIPE_BUSY whenever no instance is in the listening state, which with go-winio is the case between Listen and the first Accept and between a client's connect and the next Accept. transport.CheckEndpoint (doctor's endpoint check) waits for a listening instance (WaitNamedPipe, bounded) and retries, as Dial does; a pipe nobody accepts on is reported as busy (wrapping ERROR_PIPE_BUSY), never as insecure or missing. Tests read a pipe's DACL from the server side of an accepted connection (GetSecurityInfo on its handle), which does not race.

  7. Replacing a file that another handle holds open. Windows refuses MoveFileEx over a file any handle has open without FILE_SHARE_DELETE (ERROR_ACCESS_DENIED or ERROR_SHARING_VIOLATION): a concurrent save's own rename, an editor, a backup agent or an antivirus scan does so for milliseconds. The atomic publish in profile (renameFile) treats those as transient and retries for a bounded time; a save never fails on the first refusal.

  8. The run startup budget is native only. The cli spec's "under 50 ms before exec" is the unix figure and stays the native budget (50 ms). TestRunStartupBudget is skipped on Windows pending ticket 01M4C7WA60TM2TT0NG49CRFFVZ: a warm run command starts two git processes there, and on the only Windows host this project tests on, an emulated ARM64 VM, process creation alone (git --version takes over 100 ms) puts it far above any figure that would still catch a doubled path. No Windows budget is set until that ticket profiles the path and removes or justifies the git processes.

  9. A missing program is fs.ErrNotExist on every OS. runner.Run's documented contract. On Windows os/exec resolves a path-qualified program without an extension through %PATHEXT% and reports exec.ErrNotFound ("executable file not found in %PATH%"), which does not wrap fs.ErrNotExist; the runner maps that case (a program named by path that does not exist in any form) to fs.ErrNotExist.

  10. A small write never waits for the reader. A unix socket's kernel buffer absorbs a small frame whether or not the peer is reading; a named pipe created with go-winio's zero buffer sizes completes a write only once the other end reads it. The daemon writes a secret answer while holding respMu's read side, so on Windows a client that stopped reading held a screen lock off for a whole WriteTimeout behind a 70-byte answer (TestQueuedSecretAnswerHoldsNoLock, 2 of 5 and 4 of 8 isolated runs on the VM; diagnosed from a goroutine dump). On every OS a write of up to 4 KiB on a daemon connection, in either direction, completes without the peer reading (transport.TestSmallWriteDoesNotWaitForReader); on Windows that is the listener's pipe buffer sizes.

Consequences

  • cmd/vaultfold/internal/cli.createPrivateFile, core/agentproto.(*ServerConn).SetViolationHook, cmd/vaultfold/internal/procinfo.ReadUTF16CommandLine (the native host's seam, mirrored for procinfo; ticket 01M49T3SQWPY3FAA8DYXZFXQEM) and cli.aceBounds (ticket 01M3EXT3G7HAA7BTMR4KCV883W) are the seams these rulings add; their tests are red until implemented.
  • Tests that pin a Windows-only behaviour live in _windows_test.go files and run only under make check-windows; where a ruling applies to every OS the test is sharpened so it also fails on unix until the production code follows (the blob store below a file, the violation hook, the private file seam).
  • The real cross-user pipe refusal (TestPipeRefusesOtherUser) runs only where the VM's vftest harness exists and passes today; it is the first test of the pipe DACL against another Windows account.