diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 9e448469ad..cfad7ef9df 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -186,7 +186,7 @@ It adds no state name, command, or flag: - The daemon arms the recording under that ID, which `open` and `close` name in `scriptPublicationId`. After each successful request that records into the ARMED recording, the daemon writes the recording so far, without a terminal `close`, and returns it as a `session-script` artifact with the ID and a growing `scriptRevision`. The close-time write is the final version and has the highest revision; close takes it from the close-time write itself, so a capture that close stops first never hides recorded actions. - Each version, the final one included, is a fresh 0600 file in a 0700 directory under the daemon's sessions directory, and is downloaded once. + Each version, the final one included, is a fresh 0600 file in a 0700 directory under the daemon's sessions directory, and is downloaded once. That directory is written only when the daemon's own state chain was established as private ground; a version the chain cannot claim is a failed delivery, not a file elsewhere (see the state-mode rule below). It registers for download for the tenant that opened the recording, whatever the tenant, capture filters, or network marker of the request that recorded it. - The client writes a version only to the destination of a record that matches its ID and scope, and only when its revision is newer than the last published one. The `savedScript` field and the `session-script` type are reserved for this path, so a script artifact under another field writes nothing. @@ -207,7 +207,40 @@ It adds no state name, command, or flag: A batch whose steps would close an armed remote recording is refused before any step runs (`remote_script_batch_close_unsupported`), because a batch delivers no script versions from its steps. - The daemon reports the `script-artifacts` capability in `/health`, through a proxy in its upstream health; the client refuses a remote `--save-script` before dispatch without it. -The destination keeps local `--save-script` semantics: the client creates a missing parent directory and checks no ancestor ownership, so another local user who can write an ancestor directory can redirect the file, locally and remotely alike (#4565). +Both routes resolve an absolute destination before asking host-kit, and host-kit refuses a relative one at its entry, on every platform including Windows: the chain it judges is the chain that gets created. It owns parent creation as ONE call — walk, refuse, create what is missing at 0700 inside the judged directory, judge again, answer with the judged directory and its identity — and both the local writer and the remote client make that one call before staging. The identity travels with the answer, so the remote client stages each version inside the directory that answer named instead of walking the destination a second time. The rule closes the window with PERMISSIONS, not with timing. +A destination is accepted only when no other non-root local user can modify any directory the publish traverses. Each directory must be owned by the current user or by root, and its mode must keep its contents closed to others. Once that holds, nobody can swap a component out or plant one, so the path that was judged is the path the publish reaches; nothing depends on when a directory was judged. +The walk emulates the kernel's own path resolution, because that is the set of directories that has to be safe. It starts at `/` with the parent's components on a queue, and takes one component at a time: `.` is skipped; `..` moves to the parent of the directory PHYSICALLY stood in, never to the parent of the spelled string; any other component is looked up with `lstat` inside that directory. A directory is judged and entered. A symbolic link is judged where it physically stands and its target's components go on the front of the queue, restarting from `/` for an absolute target and continuing from the directory that holds the link for a relative one. An absent component ends the walk, and the walk reports that it stopped SHORT of the directory the entry is created in, rather than presenting the nearest ancestor as if it were that directory. Nothing calls `realpath`: it answers only with the final directory, so every directory stepped through on the way can disappear from the answer, and a JS `realpath` simplifies `..` lexically while the kernel applies it to the link's target. +Because the walk ends at the first component that does not exist, what it judged before any creation is exactly the chain that already stands, and a destination the rule refuses leaves no directories behind. The missing tail is then created at 0700 inside the judged directory, ONE LEVEL AT A TIME, and the walk runs again over the now-complete chain. One `mkdir` per name is what keeps the creation inside ground the walk stopped in: a recursive `mkdir` resolves the whole tail as text, so a link another local user plants at one of those absent names while the walk is still running carries the creation to the far side of it, where it leaves a directory behind and, run as root, creates one with privileges. A name that was absent when the walk looked and exists by the time `mkdir` reaches it is JUDGED, not refused and not trusted: two processes saving into the same new directory meet there, so refusing it (which an earlier shape did, as `entry_appeared`) failed a routine concurrent save. The entry under the name is read by the same single `lstat` every other step is read by and judged by the same rule, which adopts a private directory this user owns and refuses one another user owns, one the group or others can write, and a link. An appeared level is also asked whether other local users could add a name inside it, which a directory this call created itself is not: below one they can write, they can make the destination's own name first. Where nothing was missing, the first walk already judged the directory the entry is created in, and its answer is the answer. Every directory a script publish creates must itself pass the check it is judged by, under any umask: under umask 002 a mode-less creation is 0775, and the check that follows it would refuse the very directory the publish just made. The second question is where "could other local users add a name inside that directory" is asked, because below the first one the directories are the caller's own to create, at 0700. +Creating what is missing does not make every spelling resolvable. A `..` queued BEHIND the absent component is refused as `unresolvable_parent` before anything is created: the kernel cannot apply that step until the name before it exists, while a `mkdir` of the same spelling resolves it as text and builds what stands on the far side of it — `private/missing/../../shared/recordings` never gets `shared` judged, and the creation lands `shared/recordings` in ground any local user can write, beside a `private/missing` of its own. A `..` over directories that all exist is applied one step at a time, exactly as the kernel applies it. After creation, publishing proceeds only where the second walk ARRIVED at the directory the entry is created in; stopping short is a refusal (`unreachable_parent`), never a write into the nearest ancestor. +A RELATIVE destination is refused at entry (`relative_destination`). Both routes expand the caller's path to absolute before asking, and walking a relative name would mean walking the process's working directory too — whose NAME Node answers from the first query after the last `chdir`, so it can be stale while the process stands elsewhere. Refusing at the entry keeps that question out of the rule. +Shapes this closes, each of which an earlier shape of the rule accepted: +- A plain directory under a shared one can hold a link into a private destination, so the destination looks private while the ground it stands on is shared: `rec -> shared/relay/sub`, `shared` at 0777 and not sticky, `shared/relay -> chosen`. Judging each lookup catches `shared`. +- A link inside a link target hides its own directory, and a followed link's owner was never asked: `~/rec -> /tmp/relay -> ~/chosen`, `relay` another user's file in sticky `/tmp`. Every followed link is judged with `untrustedLinkExposure` against the directory that holds it, at any depth, so spelling the target directly and arriving through a link answer the same way. +- `..` applies to the directory the walk is in: with `home/work -> priv/x` and `priv/y` at 0777, `home/work/../y` lands in `priv/y`, not in the private `home/y` the normalized spelling names. +- A target may be spelled relative to the link that holds it, which is how `ln -s ../team/rec rec` is written, and it may contain a `..`. Both are applied one component at a time to the physical directory the walk reaches, never joined as text: `path.join` folds a `..` away, and the folded answer is a different directory. +- A relative destination would put the working directory into the judged chain, and a stale cwd name judges a directory the process is not in while the kernel resolves the destination in the moved one. Host-kit refuses relative destinations at its entry instead of emulating that resolution. +The walk ANSWERS with the physical directory the entry is created in, and that answer is used as it stands. Both publishers stage inside it and create the entry inside it, spelled from it; neither hands the spelled destination back to the filesystem. `path.dirname` and `path.join` of the spelled destination answer a different directory wherever the walk turned aside, and a temp or staging file in that directory is one another local user can list, reach, and put their own bytes behind before the publish renames it. Asking the kernel to resolve the spelled destination a second time, at the moment of the link or rename, resolves it through whatever stands on the path by then. Each entry is read from the host once per visit, by `lstat` and never by `stat`: `lstat` judges the ENTRY a name holds, while `stat` resolves the same name a second time and answers whatever it points at by then. A name a walk reaches twice, through a `..` or an alias, is judged again from a fresh `lstat` and reaches the same judgment; the walk keeps no memory of ground it stood on and no second identity check of it. An earlier shape kept such a memory and compared an identity on every re-visit and before every creation, refusing `parent_replaced`; it is CUT, because the ownership rule already excludes anyone who could make that swap — a directory the walk stands in is one this user or root owns that others cannot write in, or a sticky one where this user's entry cannot be replaced. The judgment a step rests on is the single `lstat` of that step: a symbolic link is judged as a link, against the directory that holds it, and the walk goes on to its target one component at a time rather than asking `stat` what the name resolves to. +A link hop count is kept and refused at `link_loop_exceeded` below the limit the kernel applies (macOS 32, Linux 40), so a walk that ran out of hops is a refusal rather than a pass, and a loop can never be trusted. A component that is neither a directory nor a link is refused as `not_a_directory`: the kernel cannot travel through it either. Root-owned system aliases (macOS `/tmp` to `/private/tmp`, `/var` to `/private/var`) keep working. +The sticky bit excuses a directory the walk passes THROUGH, when this user or root owns it, because it stops anyone but an entry's owner or root from replacing that entry; a sticky directory another user owns is refused, because those bits shield other users from that owner rather than the reverse. It never excuses creating the destination inside that directory, because anyone could create that name first. The link's own mode is never consulted: a link's bits say nothing about access on Linux, so what is judged is the directory the walk lands in, plus the ownership of the link and of the directory that holds it. +A group-writable directory is refused (`shared_group_writable`, with a `chmod g-w` hint), with the one exception of the sticky bit for passing THROUGH. An earlier shape of this rule carried a private-group exception, which read `/etc/group`, `/etc/passwd` and `/etc/nsswitch.conf` to admit a group-writable directory whose group was proven to hold no other user, and it is DROPPED. Membership cannot be proven on the platform that motivated it: stock Ubuntu and Debian ship `passwd: files systemd` and `group: files systemd`, a name service can hold a member no file shows, and no reading of those files closes that gap — the exception admitted nothing exactly where it was written to help, and every host it did admit could say the same thing by its mode instead. What replaces it: directories a script publish creates are created 0700, which covers every new directory under any umask, and an existing 0775 checkout is refused with a hint to `chmod g-w` it. The rule reads no account database, and its answer does not depend on which name services the host runs. The daemon's own state directories are part of that chain on both routes: the daemon creates and repairs the state directory, its `sessions/` directory and `remote-scripts/` at 0700 rather than leaving them to a mode-less `mkdir`, because under umask 002 a stock host would make `sessions/` 0775 and the rule above would then refuse the daemon's own default recordings and every remote-delivered version. That repair judges ground the way the walk does, and never through the NAME: the mode is forced through a descriptor opened `O_DIRECTORY | O_NOFOLLOW`, and only once the `fstat` of THAT DESCRIPTOR says this uid owns the entry. A repair given the name resolves it again, and a root daemon asked to repair a legacy state directory another user could write would reach through a `sessions` they left as a LINK and strip access from an owner who never ran the daemon. `O_NOFOLLOW` guards only the LAST name of that open, so the repair does not judge the requested level alone: it walks DOWN from the state base, `lstat`s each level under its own name, and repairs a level only when every level above it passed. A level that is a link, is not a directory, or belongs to another uid stops the descent, and that level and every level beneath it are left as they are. What the entry IS is asked before its mode, because on a host where a link carries its own mode a link at 0700 answers the mode question with the private mode and would pass unjudged. +Judging DOWN from the base is not the whole judgment, because the descent never questions the ground the base stands on. A local user who can write an ancestor ABOVE the base can rename the base and leave a link at its name between two of the repair's calls, and every level below then resolves on the far side of a link nothing judged; as root, the repair forces a mode there and reports the chain private. So the ancestry above the state base is asked FIRST, by the same rule a script destination is walked by (`untrustedDirectoryAncestry` is that rule's own walk over the base's parent), and this ADR carries no second version of it. It is asked of what is ABOVE the base only: the base and the levels under it are what the repair exists to make private, so a `sessions/` left at 0775 by umask 002 is repaired rather than refused. Where that rule refuses, nothing below is repaired, `daemon_state_mode_repair_skipped` names the ancestor and its exposure, and the chain answers not private. A sticky ancestor this user or root owns is passed through, because the destination rule passes it through: the sticky bit stops anyone but an entry's owner or root from renaming that entry, which is exactly the swap this closes. The consequence for a host whose state sits under a shared, non-sticky directory is that it delivers no daemon-picked recordings, on the same `state_chain_untrusted` refusal, startup and every other command unaffected. + +A state-mode repair NEVER decides whether the daemon starts, and it is not a second destination rule. It forces 0700 on a directory entry this uid owns, reached without following a link, and on nothing else; every other shape — a link, a name that is not a directory, a level another uid owns, or an error from any step it takes — changes nothing and emits `daemon_state_mode_repair_skipped`. The whole repair is wrapped, so `EACCES` on a directory this user cannot read, `ENOENT` on one that disappears meanwhile, and `EIO` on the `close` that ends it are all reported the same way and stop there rather than reaching startup; only creation keeps its own failures. Creation is BEST-EFFORT too, and it happens BEFORE any chain is judged: one recursive `mkdir` builds the whole tail, which is what keeps a base that is a link working, so a chain the repair stops on can be left with an EMPTY directory beyond the level it stopped at. Nothing is validated before that creation, and nothing is ever written into what it leaves. This is the rule `repairStateMode` already applied to the log file: the repair is best-effort hygiene for a host the daemon owns, not a gate on a host it does not. +What the repair ANSWERS is a second thing from what it forces. It reports whether the whole chain from the state base down to the requested level is private ground: a real directory, this uid's, standing 0700, reached without following a link. Startup ignores that answer and starts either way, so a state directory on a bind-mounted CI volume, a `~/.agent-device` symlinked to another disk, and a container whose `sessions/` belongs to the mounted uid all still start with every command working. A SCRIPT DOES NOT ignore it. A destination the daemon picks for itself — a default recording under `sessions/`, a remote version under `sessions/remote-scripts/` — is written only on a chain that answered private, and refused otherwise with `state_chain_untrusted` and a hint naming that host shape and its fix. So the host whose state tree belongs to another uid keeps a working daemon and loses its daemon-picked recordings: an owner this process is not can replace that level at any moment, so it is not ground to publish a recording on. That refusal is the CHAIN VERDICT's own, not the destination walk's: the walk judges ground, and it ACCEPTS a symbolic link standing in a parent others cannot write, so `sessions -> outside` with `outside` at 0755 and owned by this user passes the walk and would land the version outside the state tree. A caller's `--save-script=` keeps the old behavior on every one of those hosts: that destination is the caller's own, and the walk alone decides it. So the repair skips modes best-effort and never refuses STARTUP, and the only refusals of a RECORDING are the destination walk (a caller's path) and this chain answer (the daemon's own). +The script file is created 0600, locally and remotely alike, so a recording is not world-readable in a directory that is merely shared. +Remote delivery walks a destination TWICE per version where the parent already stands, THREE where a level has to be created, and compares identity ONCE either way. The local writer walks ONCE for the same reason, TWICE with a missing parent, and compares nothing. The first walk happens before staging, and where it stops short it creates the missing levels and walks again before answering; so a destination that has to be built costs one more walk on either route. It answers with the judged directory and that directory's `dev:ino`, and staging is allocated inside the directory that answer names. The second happens under the record lock right after the download, through `confirmScriptDestination`, and it is the one comparison: this walk's identity must be the one the earlier answer carried, or the version is refused (`parent_replaced`) instead of renamed into ground nobody judged. Two walks, not three: an earlier shape walked a third time at allocation to be told a directory the call one line earlier had already answered. One call, exported, owns that confirmation and the refusal it answers with, and the remote route holds no copy of either — a route that hand-rolls the reason, exposure, ancestor and hint drifts from the rule that produced them, and this one did. The local publish walks once and compares nothing, because nothing runs between its judgment and its rename. The ownership rule is what closes the window — anyone able to swap a judged directory was refused at it — so the retained comparison is defense in depth against a host whose modes moved, not what excludes the attacker. +Node exposes no `openat` or `renameat`, so publishing relative to a verified directory handle is not available without native code; the permissions rule is what substitutes for it. + +### What the guarantee does not cover + +The rule judges ownership bits, mode bits and link shape. Three things sit outside it, and no combination of them is a reason to expect confidentiality: + +- **ACLs.** macOS and Linux filesystem ACLs are consulted ahead of the mode bits, and the rule does not read them. A directory at 0700 can still grant `everyone` write through an ACL, letting another user plant or swap a component; a 0600 file can still inherit an `everyone` read entry, so the file's mode is not a promise about who can read it. Checking ACLs is deliberately not implemented. Callers who need that guarantee on such a host choose the destination's permissions and ACLs together. +- **Network filesystems.** NFS, SMB and FUSE mounts answer ownership, mode and link questions however the server pleases, and an unverified server can change any of them while the publish runs. Uids on a mount are usually not the uids on this host either. A script destination on a network mount is outside the guarantee. +- **Bind mounts and mounts in general.** A directory can be mounted over another after the judgment, and the publish writes into whatever stands there. The `dev:ino` comparison notices a replaced destination directory on the same route that captured its identity; it cannot notice a mount that was already there and was never judged. + +So the guarantee is: on a local filesystem with no ACLs on the directories the walk judges, no other non-root local user can steer where the recording is written or create that file. It is not a promise that nobody else can read the file. +A local write fails with `script_ancestor_untrusted`, `script_ancestry_replaced`, or `state_chain_untrusted` (a path the daemon picked itself, on a state chain the repair did not accept); a remote version keeps its command's success and carries that reason as the `scriptDeliveryFailure` cause. Every result that can carry a script version discloses a failed delivery: the SDK result, the CLI human output and `--json`, and the MCP tool result each carry `scriptDeliveryFailure` and the warning, so no caller reads a stale file as current. Known limitation (#4595): a batch delivers no script versions from its steps, so closing an armed remote recording inside a batch stays refused. Rejected: a remote `session save-script` download, because it added a second publication path and a retry protocol. diff --git a/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts b/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts new file mode 100644 index 0000000000..ffedb313a2 --- /dev/null +++ b/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts @@ -0,0 +1,491 @@ +// The daemon forces its own state directories to 0700, because the script-destination rule refuses a +// group-writable directory on the chain (ADR 0016). What this suite pins is the OTHER half: a state level +// whose mode this process may not force, or cannot reach, is SKIPPED with a warning and the call still +// returns. A state repair never decides whether the daemon starts; the destination walk is the only refusal. +// (https://github.com/callstack/agent-device/pull/4584) + +import { afterEach, expect, test, vi } from 'vitest'; +import fs from 'node:fs'; +import path from 'node:path'; +import { FOREIGN_UID, mkdtempForTestSync, serveHostOwnership } from '@agent-device/test-kit'; +import { + countDiagnosticEventsByPhase, + withDiagnosticsScope, +} from '@agent-device/host-kit/diagnostics'; +import { ensurePrivateDaemonStateDir } from './daemon-registration-owner.ts'; + +const skipOnWindows = process.platform === 'win32' ? test.skip : test; +const SKIPPED = ['daemon_state_mode_repair_skipped']; +// Captured before any spy is installed, so a forwarded call reaches the host and not another mock. +const originals = { + lstatSync: fs.lstatSync.bind(fs) as FsCall, + statSync: fs.statSync.bind(fs) as FsCall, + openSync: fs.openSync.bind(fs) as FsCall, + fstatSync: fs.fstatSync.bind(fs) as FsCall, + fchmodSync: fs.fchmodSync.bind(fs) as FsCall, + closeSync: fs.closeSync.bind(fs) as FsCall, +}; + +type FsCall = (...args: unknown[]) => unknown; +type SeamName = keyof typeof originals; + +afterEach(() => { + vi.restoreAllMocks(); +}); + +skipOnWindows('repairs the state chain it owns, whatever mode its levels were created with', () => { + // An older version, or a checkout shared under umask 002, leaves `sessions/` at 0775 and the daemon then + // refuses its own recordings. Repair is what fixes a host it did not create, so it has to work — and a + // per-session call has to reach the level ABOVE the session directory, or every recording is still walked + // through a 0775 `sessions/`. + const base = mkdtempForTestSync('agent-device-state-repair-'); + fs.chmodSync(base, 0o755); + const sessions = path.join(base, 'sessions'); + const remote = path.join(sessions, 'remote-scripts'); + for (const directory of [sessions, remote]) { + fs.mkdirSync(directory); + fs.chmodSync(directory, 0o775); + } + + // How the daemon actually calls it: startup ensures `sessions/` from the state base, the remote writer + // ensures `remote-scripts/`, and each call repairs the chain down to the level it was asked for. + ensurePrivateDaemonStateDir(sessions, base); + const answer = ensurePrivateDaemonStateDir(remote, base); + expect(answer).toEqual({ path: remote, privateChain: true }); + + for (const directory of [base, sessions, remote]) { + expect(modeOf(directory)).toBe(0o700); + } +}); + +skipOnWindows('answers that a chain it stopped on is not private ground', async () => { + // Startup reads this answer and starts anyway; a caller that WRITES under the directory reads the same + // answer and refuses. A chain that stopped at a link leads to ground outside the state tree, and the + // destination rule accepts a link whose parent others cannot write, so the walk would have published + // there. Only a chain that reached its level at 0700 answers `privateChain: true`. + const base = mkdtempForTestSync('agent-device-state-verdict-'); + fs.chmodSync(base, 0o755); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions); + fs.chmodSync(sessions, 0o775); + + expect(ensurePrivateDaemonStateDir(sessions, base)).toEqual({ + path: sessions, + privateChain: true, + }); + + const outside = path.join(base, 'outside'); + fs.mkdirSync(outside); + const planted = path.join(sessions, 'remote-scripts'); + fs.symlinkSync(outside, planted); + expect(ensurePrivateDaemonStateDir(planted, base)).toEqual({ + path: planted, + privateChain: false, + }); + + // A level the chain stopped at is not private either, and neither is one below it. + expect(ensurePrivateDaemonStateDir(path.join(planted, 'session'), base).privateChain).toBe(false); +}); + +skipOnWindows('asks nothing of a chain that already stands private', () => { + // The fast path, and the reason a per-session call is cheap: every level already has the mode the repair + // would force, so none of them is even opened. Dropping the mode check makes this red. + const base = mkdtempForTestSync('agent-device-state-private-'); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions); + for (const directory of [base, sessions]) fs.chmodSync(directory, 0o700); + const open = vi.spyOn(fs, 'openSync'); + + ensurePrivateDaemonStateDir(sessions, base); + + expect(open).not.toHaveBeenCalled(); +}); + +skipOnWindows('stops at an intermediate link and leaves where it leads alone', async () => { + // `O_NOFOLLOW` guards only the LAST name of an open, so judging the leaf is not enough: `sessions` is a + // link to a directory outside the state tree, and the leaf this call is handed resolves on the far side of + // it. A root daemon given that leaf opens the foreign directory and forces its mode — 0755 to 0700 strips + // access from an owner who never ran the daemon. So the chain is judged DOWN from the state base, and a + // link stops the descent before anything below it is opened. + const base = mkdtempForTestSync('agent-device-state-intermediate-link-'); + fs.chmodSync(base, 0o777); + // The directory the link points at, and the child the leaf resolves to on its far side — `/etc/ssh` in + // the reported shape, standing 0755 with an owner who never ran the daemon. + const outside = path.join(base, 'outside'); + const farSide = path.join(outside, 'ssh'); + fs.mkdirSync(farSide, { recursive: true }); + fs.chmodSync(outside, 0o755); + fs.chmodSync(farSide, 0o755); + const sessions = path.join(base, 'sessions'); + fs.symlinkSync(outside, sessions); + + // The shape of the blocker: startup asks for `sessions`, a later session open asks for `sessions/ssh`, + // which is a name on the far side of that link. + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, base))).toBe(1); + expect( + await skipCountFor(() => ensurePrivateDaemonStateDir(path.join(sessions, 'ssh'), base)), + ).toBe(1); + + // The far-side child keeps the mode its owner chose, and neither level was reached at all: repairing that + // leaf through its name is what opened the far side and forced 0700 on it. + expect(modeOf(farSide)).toBe(0o755); + expect(modeOf(outside)).toBe(0o755); + expect(fs.lstatSync(sessions).isSymbolicLink()).toBe(true); +}); + +skipOnWindows('reports a state level that is a LINK CARRYING the private mode', async () => { + // Where the host lets a link carry its own mode, `lchmod` 0700 makes the link answer the mode question + // with the private mode. A repair that asks the mode before it asks what the entry IS returns there and + // passes a link it never judged, so the level-by-level order is the pin: `isDirectory` first, the mode + // second. The far side is not what this shape is about — the silent pass is. + const base = mkdtempForTestSync('agent-device-state-link-mode-'); + fs.chmodSync(base, 0o755); + const outside = path.join(base, 'outside'); + fs.mkdirSync(outside); + fs.chmodSync(outside, 0o755); + const sessions = path.join(base, 'sessions'); + fs.symlinkSync(outside, sessions); + // On a host that gives every link the same mode, the shape below is the ordinary link case and the skip + // has to be answered either way. + try { + fs.lchmodSync(sessions, 0o700); + } catch { + /* this host reports one mode for all links */ + } + + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, base))).toBe(1); + + expect(modeOf(outside)).toBe(0o755); + expect(fs.lstatSync(sessions).isSymbolicLink()).toBe(true); +}); + +skipOnWindows('repairs above a planted link and stops below it', async () => { + // The same stop, judged the other way: `sessions` is a directory this user owns and gets repaired, and + // `remote-scripts` under it is a link. The chain repairs what it may and refuses to follow the name it + // may not, so the target of the link keeps the mode its owner chose. + const base = mkdtempForTestSync('agent-device-state-planted-below-'); + fs.chmodSync(base, 0o755); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions); + fs.chmodSync(sessions, 0o775); + const outside = path.join(base, 'outside'); + fs.mkdirSync(outside); + fs.chmodSync(outside, 0o777); + const remote = path.join(sessions, 'remote-scripts'); + fs.symlinkSync(outside, remote); + + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(remote, base))).toBe(1); + + expect(modeOf(sessions)).toBe(0o700); + expect(modeOf(outside)).toBe(0o777); + expect(fs.readdirSync(outside)).toEqual([]); +}); + +skipOnWindows( + 'skips a directory whose opened descriptor is foreign-owned although lstat reported this UID', + async () => { + // The name can be swapped between the `lstat` and the open, so the ownership that counts is the one the + // DESCRIPTOR answers: the entry the `fchmod` would change. Two things are pinned here — the check itself + // (a descriptor whose uid is foreign is not forced), and that a rejection there STOPS THE DESCENT, so a + // child beneath the rejected level is never opened or forced either. `lstat` says this uid owns both. + const base = mkdtempForTestSync('agent-device-state-descriptor-foreign-'); + // The base already stands private, so `sessions` is the only level with anything to force. + fs.chmodSync(base, 0o700); + const sessions = path.join(base, 'sessions'); + const child = path.join(sessions, 'ssh'); + fs.mkdirSync(child, { recursive: true }); + for (const directory of [sessions, child]) fs.chmodSync(directory, 0o755); + // The fixture owns these mocks (it must map a descriptor back to the name it reached), so it also + // reports what was opened and closed. A level that is FORCEs mode opens and closes; a level that is + // merely judged does neither. So `openedNames` naming only `sessions` says the child below it was never + // reached, and the descriptor `sessions` opened being closed says it did not leak. + const probe = serveHostOwnership({ [sessions]: FOREIGN_UID }, { throughDescriptorOnly: true }); + const fchmod = vi.spyOn(fs, 'fchmodSync'); + + // Asked for the CHILD, so the descent is what the rejection has to stop: the chain is base → sessions → + // ssh, and `sessions` is where the descriptor is refused. Without the stop, the child (this uid's, 0755) + // would be opened and forced next. + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(child, base))).toBe(1); + + // Nothing was forced anywhere on that chain, and both levels keep the owner's mode. + expect(fchmod).not.toHaveBeenCalled(); + expect(modeOf(sessions)).toBe(0o755); + expect(modeOf(child)).toBe(0o755); + // Only the rejected level was opened, and its descriptor was closed. + expect(probe.openedNames()).toEqual([sessions]); + const descriptor = probe.descriptorFor(sessions); + expect(typeof descriptor).toBe('number'); + expect(probe.closedDescriptors()).toContain(descriptor); + }, +); + +skipOnWindows('reports the level that disappeared before the repair reached it', async () => { + // The chain is walked AFTER a recursive `mkdir`, so at rest every level it asks about exists: a name is + // absent only when something removes it between the creation and the `lstat` of the same call. That race + // cannot be set up on disk, so the fixture answers the level ABSENT, which is what `throwIfNoEntry: false` + // really returns for a name that is not there (asserted below against a real absent name, so the injected + // value is the host's own answer and not a made-up shape). What must not happen is a silent stop: an + // operator reading the daemon log has to see where the chain stopped. + const base = mkdtempForTestSync('agent-device-state-absent-level-'); + fs.chmodSync(base, 0o700); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions); + fs.chmodSync(sessions, 0o755); + const realLstat = originals.lstatSync; + vi.spyOn(fs, 'lstatSync').mockImplementation(((target: unknown, options?: unknown) => { + if ( + String(target) === sessions && + (options as { throwIfNoEntry?: boolean })?.throwIfNoEntry === false + ) + return undefined; + return realLstat(target as fs.PathLike, options as never); + }) as typeof fs.lstatSync); + + // The same call, on a name that is truly absent, answers the same way. + expect( + originals.lstatSync(path.join(base, 'no-such-level'), { + bigint: true, + throwIfNoEntry: false, + }), + ).toBeUndefined(); + + // Nothing was changed, and the chain says so for the writer that reads it. + expect(ensurePrivateDaemonStateDir(sessions, base)).toEqual({ + path: sessions, + privateChain: false, + }); + expect(modeOf(sessions)).toBe(0o755); + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, base))).toBe(1); +}); + +skipOnWindows( + 'refuses to repair a chain whose state base stands on ground another user can write', + async () => { + // The blocker: judging DOWN from the state base never questions the ground the base itself stands on. A + // local user who can write that ancestor can rename the base and leave a link at its name between two of + // this function's calls, and every level below then resolves on the far side of a link nothing judged. + // The swap is staged here at the moment the descent looks at the SECOND level, which is what the reported + // host did: the daemon came in with `base/sessions` and `base/sessions/remote-scripts` standing 0755, and + // left the ATTACKER's directories at 0700 while answering `privateChain: true`. + // + // The answer is to judge the ancestry FIRST, with the rule a script destination is walked by, so the race + // is not reachable at all: nothing below is opened, and the chain is not private ground. + const shared = mkdtempForTestSync('agent-device-state-shared-ancestor-'); + fs.chmodSync(shared, 0o777); + const base = path.join(shared, 'agent-device'); + const sessions = path.join(base, 'sessions'); + const remote = path.join(sessions, 'remote-scripts'); + fs.mkdirSync(sessions, { recursive: true, mode: 0o700 }); + fs.chmodSync(base, 0o700); + fs.chmodSync(sessions, 0o755); + // Where the base's name leads once it is swapped: directories this user owns, standing 0755, exactly as a + // directory an attacker's link points at would. + const outside = path.join(shared, 'attacker'); + const farSessions = path.join(outside, 'sessions'); + const farRemote = path.join(farSessions, 'remote-scripts'); + fs.mkdirSync(farRemote, { recursive: true }); + for (const directory of [outside, farSessions, farRemote]) fs.chmodSync(directory, 0o755); + const coUser = swapBaseWhenDescentLooksAt(base, sessions, outside); + + expect(ensurePrivateDaemonStateDir(remote, base)).toEqual({ + path: remote, + privateChain: false, + }); + // Said once, and named for the ground that is not this process's to rely on. + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(remote, base))).toBe(1); + + // The ancestry was judged before any level was opened, so the descent never got as far as the name the + // swap was armed for, and the co-user never had their turn. + expect(coUser.swapped()).toBe(false); + // Nothing was forced anywhere: neither the levels under the base nor the directories its name would have + // led to. The far side keeping 0755 is the whole point — that mode change is the reported exposure. + expect(modeOf(base)).toBe(0o700); + expect(modeOf(sessions)).toBe(0o755); + expect(modeOf(outside)).toBe(0o755); + expect(modeOf(farSessions)).toBe(0o755); + expect(modeOf(farRemote)).toBe(0o755); + expect(fs.readdirSync(outside)).toEqual(['sessions']); + }, +); + +skipOnWindows( + 'repairs a chain whose ancestor is open to others but carries the sticky bit', + async () => { + // The same host shape, minus the one thing that made it unsafe: macOS `/tmp` and a shared CI directory are + // world-writable AND sticky, and this user owns them, so nobody but an entry's owner or root can rename the + // state base. Repair goes ahead. This is the pin that the ancestry is judged by the destination rule and + // not by a stricter copy of it: that rule passes a sticky directory through, so this one does too. + const shared = mkdtempForTestSync('agent-device-state-sticky-ancestor-'); + fs.chmodSync(shared, 0o1777); + const base = path.join(shared, 'agent-device'); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions, { recursive: true }); + for (const directory of [base, sessions]) fs.chmodSync(directory, 0o755); + + expect(ensurePrivateDaemonStateDir(sessions, base)).toEqual({ + path: sessions, + privateChain: true, + }); + + expect(modeOf(base)).toBe(0o700); + expect(modeOf(sessions)).toBe(0o700); + }, +); + +skipOnWindows( + 'refuses a chain whose state base belongs to the ancestor that is another user', + async () => { + // The other way an ancestor can stop this repair: the directory the base stands in belongs to somebody + // else, so they can move the base whenever they like. `serveHostOwnership` reports the ownership the + // account files of this host cannot give a test. + // Resolved, because the ancestry walk resolves the same names the kernel does and reports the physical + // directory it stands on; a fixture keyed by path has to be keyed by that name. + const parent = fs.realpathSync(mkdtempForTestSync('agent-device-state-foreign-ancestor-')); + const base = path.join(parent, 'agent-device'); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions, { recursive: true }); + for (const directory of [base, sessions]) fs.chmodSync(directory, 0o755); + serveHostOwnership({ [parent]: FOREIGN_UID }); + + expect(ensurePrivateDaemonStateDir(sessions, base)).toEqual({ + path: sessions, + privateChain: false, + }); + + // Their directory, their mode: nothing below was forced either. + expect(modeOf(base)).toBe(0o755); + expect(modeOf(sessions)).toBe(0o755); + }, +); + +/** + * Plays the co-user: renames `base` aside and leaves a link at its name pointing at `outside`, at the moment + * the descent `lstat`s `watched` — after the base itself was judged, before anything below it was opened. + * Answers whether that turn ever came, which it does not when the ancestry is judged first. + */ +function swapBaseWhenDescentLooksAt( + base: string, + watched: string, + outside: string, +): Readonly<{ swapped: () => boolean }> { + const realLstat = originals.lstatSync; + let swapped = false; + vi.spyOn(fs, 'lstatSync').mockImplementation(((target: unknown, options?: unknown) => { + if (!swapped && String(target) === watched) { + swapped = true; + fs.renameSync(base, `${base}-moved`); + fs.symlinkSync(outside, base); + } + return realLstat(target as fs.PathLike, options as never); + }) as typeof fs.lstatSync); + return { swapped: () => swapped }; +} + +skipOnWindows('skips a state directory another user owns, and leaves its mode', async () => { + // The container and shared-CI shape: `sessions/` belongs to the uid a volume was mounted with, and the + // daemon runs as root or as somebody else. Ownership is asked of the descriptor the mode would be forced + // through, so the repair reports the level and gets out of the way. Refusing to start here would take a + // working host down over a mode, and a recording under that tree is refused by the walk anyway. + const base = mkdtempForTestSync('agent-device-state-foreign-'); + fs.chmodSync(base, 0o755); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions); + fs.chmodSync(sessions, 0o775); + serveHostOwnership({ [sessions]: FOREIGN_UID }); + + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, base))).toBe(1); + + expect(modeOf(sessions)).toBe(0o775); +}); + +skipOnWindows( + 'skips a chain whose state base is a link, and creates its state anyway', + async () => { + // `~/.agent-device` on another disk: the base ITSELF is a link, so the descent cannot judge it and every + // level under it is out of reach. That is a host the operator set up, not an attack, so creation goes + // through and the repair only reports — a daemon that refused to start here would fail every command. + const target = mkdtempForTestSync('agent-device-state-link-target-'); + const parent = mkdtempForTestSync('agent-device-state-link-'); + const base = path.join(parent, 'agent-device'); + fs.symlinkSync(target, base); + const sessions = path.join(base, 'sessions'); + + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, base))).toBe(1); + + // The state appeared under the directory the link points at, and nothing about the link changed. + expect(fs.lstatSync(sessions).isDirectory()).toBe(true); + expect(fs.lstatSync(base).isSymbolicLink()).toBe(true); + }, +); + +for (const code of ['EACCES', 'ENOENT', 'EIO'] as const) { + skipOnWindows(`skips a state level the host answers ${code} for, and never throws`, async () => { + // Any of the five calls a repair makes can fail: `lstat` on a directory this user cannot read, `open` on + // a mount that will not serve it or a name that went missing meanwhile, `fstat` and `fchmod` on a host + // whose semantics differ, and `close` on a host that cannot release the descriptor. None of them may + // reach the daemon's startup path — this decides a mode, not whether the daemon runs — and every one has + // to say so on the phase a host can see. + for (const seam of ['lstatSync', 'openSync', 'fstatSync', 'fchmodSync', 'closeSync'] as const) { + const base = mkdtempForTestSync('agent-device-state-errno-'); + // The base already stands private, so the only level with something to repair is the one under test. + fs.chmodSync(base, 0o700); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions); + fs.chmodSync(sessions, 0o755); + denyOneSeam(seam, sessions, code); + + // `closeSync` comes last, so the mode it is closing was already forced when the close fails. + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, base))).toBe(1); + expect(modeOf(sessions)).toBe(seam === 'closeSync' ? 0o700 : 0o755); + vi.restoreAllMocks(); + } + }); +} + +/** + * Makes one filesystem call answer `code` for `target`, and only for it: the path seams are asked by name, + * the descriptor seams by the descriptor `open` returned for that name. Every other call reaches the host. + */ +function denyOneSeam(seam: SeamName, target: string, code: string): void { + const denied = Object.assign(new Error(`test ${code}`), { code }); + // Which descriptors came from `target`: a descriptor seam has to be denied for the same entry the path + // seam would have been denied for, and `open` has to answer before those three can be reached at all. + const openedOnTarget = new Set(); + const realOpen = originals.openSync; + vi.spyOn(fs, 'openSync').mockImplementation(((...args: unknown[]) => { + if (seam === 'openSync' && String(args[0]) === target) throw denied; + const descriptor = realOpen(...args) as number; + if (String(args[0]) === target) openedOnTarget.add(descriptor); + return descriptor; + }) as typeof fs.openSync); + if (seam === 'openSync') return; + if (seam === 'lstatSync') { + denyCall('lstatSync', (argument) => String(argument) === target, denied); + return; + } + denyCall(seam, (argument) => openedOnTarget.has(argument as number), denied); +} + +/** Makes one `fs` call throw for the arguments `named` selects, forwarding every other call to the host. */ +function denyCall(seam: SeamName, named: (argument: unknown) => boolean, error: Error): void { + const real = originals[seam]; + vi.spyOn(fs, seam).mockImplementation(((...args: unknown[]) => { + if (named(args[0])) throw error; + return real(...args); + }) as typeof fs.lstatSync); +} + +function modeOf(target: string): number { + return Number((originals.lstatSync(target) as fs.Stats).mode & 0o777); +} + +/** + * Runs one repair inside its own diagnostics scope and reports how often it said it skipped a level. No + * `logPath`, so the events are tallied and written nowhere. + */ +async function skipCountFor(repair: () => unknown): Promise { + return await withDiagnosticsScope({ session: 'daemon' }, () => { + expect(repair()).toBeDefined(); + return countDiagnosticEventsByPhase(SKIPPED); + }); +} diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index 21862e45e1..f6d8fbd241 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -19,6 +19,7 @@ import { inspectProcessLock, tryAcquireProcessLock, acquireProcessLockAcquisition, + untrustedDirectoryAncestry, type ProcessLockAttempt, type ProcessLockAcquisition, } from '@agent-device/host-kit/file'; @@ -276,6 +277,207 @@ export function createOwnedReplayStateDir(): OwnedReplayStateDir { return owned; } +/** + * Creates one of the daemon's own state directories, and forces the mode of one that exists, to 0700. + * + * Every directory on the chain of a script destination the daemon picks for itself — the state dir, + * `sessions/`, `remote-scripts/` — is judged by the destination-ancestry rule on the way to a recording + * (ADR 0016), and that rule refuses a group-writable directory. A mode-less `mkdir` under the shared-checkout + * umask 002 creates `sessions/` at 0775, so creation carries the mode and the repair forces it for a level + * an older version already left loose. + * + * The repair is BEST-EFFORT and never refuses (#4565): a state directory on a mounted volume, or one another + * uid left at 0755, still gets a daemon that starts. It answers {@link DaemonStateDir}, and a caller that + * WRITES under the directory reads the verdict on the chain; startup ignores it. + * + * `stateBase` is the daemon's state directory that the levels below it are judged from: a level is repaired + * only when every level above it, down from that base, is one this process may judge. {@link + * repairStateChain} says why the whole chain has to be judged rather than the leaf alone. + */ +export function ensurePrivateDaemonStateDir(directory: string, stateBase: string): DaemonStateDir { + // One recursive `mkdir`, BEFORE the chain is judged: it creates the whole tail even on ground the repair + // will stop at, which is what keeps a `~/.agent-device` linked to another disk working. What it can leave + // beyond a rejected level is an empty directory, and no script is published on a chain the verdict refuses. + fs.mkdirSync(directory, { recursive: true, mode: STATE_DIR_MODE }); + return { path: directory, privateChain: repairStateChain(stateBase, directory) }; +} + +/** + * What {@link ensurePrivateDaemonStateDir} leaves behind: the directory it created or repaired, and whether + * every level from the state base down to it is now a real directory this uid owns, standing 0700, reached + * without following a link. `privateChain: false` says the repair STOPPED somewhere on that chain. It does + * not say anything failed — startup proceeds either way — only that a script must not be written there. + */ +export type DaemonStateDir = Readonly<{ path: string; privateChain: boolean }>; + +/** + * {@link ensurePrivateDaemonStateDir} for a caller that writes no script under the directory — startup, or a + * tombstone written beside a session — so it takes the path and leaves the verdict unread. + */ +export function ensureDaemonStateDir(directory: string, stateBase: string): string { + return ensurePrivateDaemonStateDir(directory, stateBase).path; +} + +const STATE_DIR_MODE = 0o700; + +/** + * Forces every state level from `stateBase` down to `directory` to {@link STATE_DIR_MODE}, and never throws. + * + * `O_NOFOLLOW` guards only the LAST name of an open, so judging the leaf alone is not enough: a `sessions` + * left as a link to `/etc` by a user who could write a legacy state directory makes the leaf `sessions/ssh` + * resolve to `/etc/ssh`, and a root daemon repairing that leaf would change the mode of a directory nobody + * asked it to touch. So the chain is walked DOWN from the state base, each level judged by the `lstat` of the + * entry under its name, and the first level that is a link, is not a directory, or belongs to another uid + * stops the descent: that level and every level beneath it are left exactly as they are. + * + * Judging DOWN is not enough either, because the descent never questions the ground the base stands on: a + * user who can write an ancestor above it can rename the base and leave a link at its name between two of + * this function's calls, and every level below then resolves on ground nothing judged. So the ancestry above + * the base is asked FIRST, by {@link untrustedDirectoryAncestry} — the walk a script destination is judged + * by, not a second rule. It is asked of the ANCESTRY only: the levels at and below the base are what this + * repair exists to make private (ADR 0016). + * + * Nothing here decides whether the daemon starts (ADR 0016), so no error is allowed to travel either: the + * `lstat`, the open, the `fstat`, the `fchmod` and the closing `close` are inside one catch, and any of them + * failing — `EACCES` on a directory this user cannot read, `ENOENT` on a name that went missing meanwhile, + * `EIO` on a host that cannot even release the descriptor — is reported as a skipped level and stopped there. + * Creation keeps its own failures, which come from the `mkdir` in the caller. The answer says whether the + * WHOLE chain reached `directory` and stands private; {@link DaemonStateDir} says who reads it. + */ +function repairStateChain(stateBase: string, directory: string): boolean { + // Windows answers access from an ACL, and `chmod` there only toggles the read-only bit. + if (process.platform === 'win32') return true; + const levels = stateLevelsBelow(stateBase, directory); + // A caller that names a directory outside the state base has no chain here to judge it from. + if (levels === undefined) { + skipStateDirMode(directory, 'not_below_state_base'); + return false; + } + if (!stateAncestryIsTrusted(stateBase)) return false; + for (const level of levels) { + try { + if (!repairStateLevel(level)) return false; + } catch (error) { + skipStateDirMode(level, (error as NodeJS.ErrnoException).code ?? 'unknown'); + return false; + } + } + return true; +} + +/** + * Whether `stateBase` stands on ground no other local user can move, asked before a single level is touched. + * + * {@link untrustedDirectoryAncestry} is given the base's PARENT, so it answers about the ancestry above the + * base and leaves the base itself to {@link repairStateLevel}, which can force its mode instead of only + * refusing it. Where the rule refuses, nothing below is repaired and the chain is not private ground. + */ +function stateAncestryIsTrusted(stateBase: string): boolean { + const exposure = untrustedDirectoryAncestry(path.dirname(stateBase)); + if (exposure === undefined) return true; + skipStateDirMode(exposure.ancestor, `state_ancestry_${exposure.exposure}`); + return false; +} + +/** + * Forces one level, and reports whether the chain is intact THROUGH it — the descent may go on beneath it, + * and the level counts as private ground. + * + * `chmod` given the NAME acts on whatever the name resolves to, so the mode goes through a descriptor opened + * `O_DIRECTORY | O_NOFOLLOW`, and only after that descriptor's `fstat` says this uid owns the entry — the + * entry the `fchmod` will change is the one asked about, because a writable parent can swap the name between + * two calls. A LINK or a non-directory is not a level of this tree, and a foreign directory is not this + * process's to judge, so both stop the descent rather than being followed or forced. + */ +function repairStateLevel(level: string): boolean { + const judged = fs.lstatSync(level, { bigint: true, throwIfNoEntry: false }); + // The name is gone: whatever removed it also removed the mode this call came to force, and there is + // nothing below it. Said out loud like every other stop, because the log has to show WHERE it stopped. + if (judged === undefined) { + skipStateDirMode(level, 'absent'); + return false; + } + // Asked BEFORE the mode, never after it: a LINK whose own bits are 0700 answers the mode question with the + // private mode, and a repair that read the mode first would pass that link without judging it at all. + if (!judged.isDirectory()) { + skipStateDirMode(level, 'not_a_directory'); + return false; + } + if (Number(judged.uid) !== (process.getuid?.() ?? -1)) { + skipStateDirMode(level, 'foreign_owned'); + return false; + } + // The fast path: a level that already has the mode needs nothing, and asking nothing of the mount keeps + // the common start free of an open. + if ((Number(judged.mode) & 0o777) === STATE_DIR_MODE) return true; + return forcePrivateStateDir(level); +} + +/** + * Forces one level whose `lstat` passed, through a descriptor that cannot follow a link, and reports whether + * the entry that open REACHED is this process's to keep private. The `lstat` said so a moment ago, and only + * the descriptor says what the `fchmod` changed: a name swapped for a link between the two calls is caught + * here, and a level caught there is NOT private ground, whatever its `lstat` claimed. + */ +function forcePrivateStateDir(level: string): boolean { + let descriptor: number | undefined; + try { + descriptor = fs.openSync( + level, + fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW, + ); + // The entry this open REACHED, asked before the mode is forced: the name can be swapped for a link + // between the `lstat` above and this open, and only the descriptor says what the `fchmod` will change. + if (Number(fs.fstatSync(descriptor, { bigint: true }).uid) !== (process.getuid?.() ?? -1)) { + skipStateDirMode(level, 'foreign_owned'); + return false; + } + fs.fchmodSync(descriptor, STATE_DIR_MODE); + return true; + } finally { + if (descriptor !== undefined) fs.closeSync(descriptor); + } +} + +/** Every level from `stateBase` down to `directory`, base first, or `undefined` if it is not below it. */ +function stateLevelsBelow(stateBase: string, directory: string): readonly string[] | undefined { + const below = path.relative(stateBase, directory); + if (below === '') return [stateBase]; + if (below.startsWith('..') || path.isAbsolute(below)) return undefined; + const names = below.split(path.sep); + return [ + stateBase, + ...names.map((_, index) => path.join(stateBase, ...names.slice(0, index + 1))), + ]; +} + +/** + * Reports the one state level whose mode this repair will not change, and returns nothing: a skip is never a + * refusal, and a caller that cannot reach a level still gets the directory it asked for. + */ +function skipStateDirMode(level: string, reason: string): void { + emitDiagnostic({ + level: 'warn', + phase: 'daemon_state_mode_repair_skipped', + data: { path: level, reason: `state mode repair stopped at this level: ${reason}` }, + }); +} + +/** + * What a mode repair may never fail the daemon on: a host that denies the chmod (`EPERM`, `EROFS`, and the + * two spellings of an unsupported one), a name that cannot open as a directory (`ELOOP`, `ENOTDIR`), and a + * directory that will not open for this user at all (`EACCES`). + */ +const MODE_REPAIR_SKIPPED_CODES = new Set([ + 'EPERM', + 'EROFS', + 'ENOTSUP', + 'EOPNOTSUPP', + 'EACCES', + 'ELOOP', + 'ENOTDIR', +]); + /** * Forces a pre-existing state path to the private mode, whatever mode it had. On Windows, chmod * only toggles the read-only bit, so it cannot make the path private. The repair never decides @@ -294,8 +496,6 @@ function repairStateMode(target: string, mode: number): void { } } -const MODE_REPAIR_SKIPPED_CODES = new Set(['EPERM', 'EROFS', 'ENOTSUP', 'EOPNOTSUPP']); - /** Launches and monitors the actual child before recording its private-directory authority. */ export function launchDaemonProcess( input: Readonly<{ @@ -314,8 +514,7 @@ export function launchDaemonProcess( throw new AppError('COMMAND_FAILED', 'Replay daemon startup admission is closed.', { reason: 'daemon_startup_admission_closed', }); - fs.mkdirSync(input.paths.baseDir, { recursive: true, mode: 0o700 }); - repairStateMode(input.paths.baseDir, 0o700); + ensureDaemonStateDir(input.paths.baseDir, input.paths.baseDir); const logFd = fs.openSync(input.paths.logPath, 'a', 0o600); try { repairStateMode(input.paths.logPath, 0o600); diff --git a/packages/daemon/src/__tests__/support/script-staging-failure.ts b/packages/daemon/src/__tests__/support/script-staging-failure.ts new file mode 100644 index 0000000000..55ec96a61d --- /dev/null +++ b/packages/daemon/src/__tests__/support/script-staging-failure.ts @@ -0,0 +1,27 @@ +import fs from 'node:fs'; +import { vi } from 'vitest'; +import { isAtomicPublishTemporaryPath } from '@agent-device/host-kit/file'; + +/** + * Makes the staging write of a script publication fail, and only that write. + * + * A publication stages the recording in a private temp sibling of the destination and moves it into place, + * so the seam where the filesystem can refuse a script is that one write. `host-kit`'s temp-path predicate + * says which write it is, so the fixture does not have to know how the name is built. + * + * This replaces a fixture that made the destination's directory `0500`. That one asked the HOST whether a + * write into it is allowed, and a caller the mode bits do not bind — root — writes straight through it, so + * the write succeeded and the test that expected a failure failed with it. The failure injected here is the + * fixture's own, which makes the outcome the same for every caller. + */ +export function failScriptStagingWrite(destination: string): void { + const failure: NodeJS.ErrnoException = Object.assign( + new Error(`EACCES: permission denied, open '${destination}'`), + { code: 'EACCES', errno: -13, syscall: 'open', path: destination }, + ); + const realWriteFileSync = fs.writeFileSync; + vi.spyOn(fs, 'writeFileSync').mockImplementation(((file: fs.PathLike | number, ...rest) => { + if (isAtomicPublishTemporaryPath(file, destination)) throw failure; + return (realWriteFileSync as (...args: unknown[]) => unknown)(file, ...rest); + }) as typeof fs.writeFileSync); +} diff --git a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts new file mode 100644 index 0000000000..e5bb1dd42a --- /dev/null +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -0,0 +1,610 @@ +import { afterEach, expect, test, vi } from 'vitest'; +import fs from 'node:fs'; +import path from 'node:path'; +import { + FOREIGN_UID, + createLiveTestHostEnvironment, + mkdtempForTestSync, + serveHostOwnership, +} from '@agent-device/test-kit'; +import { SessionScriptWriter } from '../session-script-writer.ts'; +import { SessionStore } from '../session-store.ts'; +import { remoteScriptVersionDelivery } from '../session-script-publication-capability.ts'; +import { + authoringPublication, + makeAuthoringSession, +} from '../../__tests__/support/session-factories.ts'; + +const hostCwd = createLiveTestHostEnvironment().cwd; +const skipOnWindows = process.platform === 'win32' ? test.skip : test; + +/** This process's ids. Windows has neither, and every test that uses them is skipped there. */ +const currentUid = process.getuid?.() ?? -1; +const currentGid = process.getgid?.() ?? -1; + +afterEach(() => { + vi.restoreAllMocks(); +}); + +function action(command: string): { + ts: number; + command: string; + positionals: string[]; + flags: Record; +} { + return { ts: Date.now(), command, positionals: ['Demo'], flags: {} }; +} + +function recordingTo(destination: string) { + return makeAuthoringSession('journey', { + scriptPublication: { + kind: 'authoring', + status: 'armed', + target: { kind: 'explicit', path: destination, force: false }, + }, + actions: [action('open')], + }); +} + +/** A remote-armed recording: the route that writes a version of its own under `remote-scripts/`. */ +function remoteRecording() { + return makeAuthoringSession('journey', { + scriptPublication: authoringPublication('armed', { remote: true }), + actions: [action('open')], + }); +} + +function root(): string { + return fs.realpathSync(mkdtempForTestSync('agent-device-script-ancestry-')); +} + +function sharedDirectory(directory: string, mode: number): string { + fs.mkdirSync(directory); + fs.chmodSync(directory, mode); + return directory; +} + +/** A scratch directory in this host's own primary group, at `mode`. */ +function homeDirectory(directory: string, mode: number): string { + fs.mkdirSync(directory); + fs.chownSync(directory, currentUid, currentGid); + fs.chmodSync(directory, mode); + return directory; +} + +function writerFor(directory: string): SessionScriptWriter { + return new SessionScriptWriter(path.join(directory, 'sessions'), hostCwd); +} + +function refusal(result: ReturnType): Record { + expect(result.written).toBe(false); + if (result.written || !result.error) throw new Error('expected a refused write'); + return result.error.details as Record; +} + +skipOnWindows('an ordinary recording saves under a chain only this user can write', () => { + const directory = root(); + const destination = path.join(directory, 'workflows', 'journey.ad'); + + const result = writerFor(directory).write(recordingTo(destination)); + + expect(result.written).toBe(true); + expect(fs.readFileSync(destination, 'utf8')).toContain('open'); +}); + +skipOnWindows('a recording saves a script no other local user can read', () => { + const directory = root(); + const destination = path.join(directory, 'workflows', 'journey.ad'); + + const result = writerFor(directory).write(recordingTo(destination)); + + expect(result.written).toBe(true); + expect(fs.lstatSync(destination).mode & 0o777).toBe(0o600); +}); + +skipOnWindows('a recording refuses a destination under a world-writable directory', () => { + const directory = root(); + const shared = sharedDirectory(path.join(directory, 'shared'), 0o777); + const destination = path.join(shared, 'journey.ad'); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + }); + expect(fs.existsSync(destination)).toBe(false); +}); + +skipOnWindows('a refused destination with a missing parent leaves no directories behind', () => { + // `close --save-script /shared/recordings/journey.ad` where `recordings` is absent. Creating the missing + // parent is what the caller asked for, so it cannot be judged only once it exists: a `mkdir -p` that runs + // first leaves `recordings` standing in the open directory after the publish refuses, which is a + // directory this user made in ground another local user owns the naming of. The chain that exists is + // therefore asked about BEFORE anything is created, and again afterwards. + const directory = root(); + const shared = sharedDirectory(path.join(directory, 'shared'), 0o777); + const destination = path.join(shared, 'recordings', 'journey.ad'); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + ancestor: shared, + }); + expect(fs.readdirSync(shared)).toEqual([]); +}); + +skipOnWindows( + 'a recording that steps back out of a missing directory leaves no directories behind', + () => { + // `/missing/../../shared/recordings/journey.ad`. The walk ends at `missing`, so `shared` is + // never judged, and the `mkdir -p` this route runs resolves the two steps up as TEXT and builds + // `/shared/recordings` — the entry would be created in a world-writable directory the rule saw + // nothing of. The kernel is no better here: it applies those steps only once `missing` exists, which + // is a directory this call would have to create first. Refusing before the first `mkdir` is what keeps + // the promise that a refused destination leaves no directories behind. + const directory = root(); + const privateDir = path.join(directory, 'private'); + fs.mkdirSync(privateDir); + fs.chmodSync(privateDir, 0o700); + const shared = sharedDirectory(path.join(directory, 'shared'), 0o777); + const destination = `${privateDir}/missing/../../shared/recordings/journey.ad`; + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'unresolvable_parent', + }); + expect(fs.readdirSync(privateDir)).toEqual([]); + expect(fs.readdirSync(shared)).toEqual([]); + }, +); + +skipOnWindows('a recording refuses a destination inside a directory another user owns', () => { + // The fixture says WHOSE directory it is, so this is the real question — a second local user's + // directory, mode 0755 and readable, judged by a rule that runs as THIS user. Moving the caller's uid + // instead would make every directory in the scratch tree foreign and refuse for the wrong reason. + const directory = root(); + const foreign = path.join(directory, 'foreign'); + fs.mkdirSync(foreign); + fs.chmodSync(foreign, 0o755); + const destination = path.join(foreign, 'journey.ad'); + serveHostOwnership({ [foreign]: FOREIGN_UID }); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'foreign_owned', + ancestor: foreign, + }); + expect(fs.existsSync(destination)).toBe(false); +}); + +skipOnWindows('a recording refuses a directory another user made sticky and owns', () => { + // `chmod 1777` on a directory of THEIRS: the sticky bit keeps me from clearing their entries, and does + // nothing to stop them renaming the component my path runs through. + const directory = root(); + const team = path.join(directory, 'team'); + fs.mkdirSync(team); + fs.chmodSync(team, 0o1777); + const destination = path.join(team, 'journey.ad'); + serveHostOwnership({ [team]: FOREIGN_UID }); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'foreign_owned', + ancestor: team, + }); + expect(fs.readdirSync(team)).toEqual([]); +}); + +skipOnWindows('a recording refuses a shared directory another user claimed first', () => { + // The `mkdir -p /recordings` shape in a sticky shared directory: whoever creates it owns it, + // and the owner can swap it for one of their own whenever they like. Only `recordings` is theirs: the + // sticky `tmp` above it is this user's, so the refusal has to name the claimed directory and not the + // scratch root above it. + const directory = root(); + const tmp = path.join(directory, 'tmp'); + fs.mkdirSync(tmp); + fs.chmodSync(tmp, 0o1777); + const recordings = path.join(tmp, 'recordings'); + fs.mkdirSync(recordings); + fs.chmodSync(recordings, 0o755); + const destination = path.join(recordings, 'journey.ad'); + serveHostOwnership({ [recordings]: FOREIGN_UID }); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'foreign_owned', + ancestor: recordings, + }); + expect(fs.readdirSync(recordings)).toEqual([]); +}); + +skipOnWindows('a recording refuses an ancestor swapped out for a symbolic link', () => { + const directory = root(); + const shared = sharedDirectory(path.join(directory, 'shared'), 0o777); + const attacker = path.join(directory, 'attacker'); + fs.mkdirSync(attacker); + fs.symlinkSync(attacker, path.join(shared, 'work')); + const destination = path.join(shared, 'work', 'journey.ad'); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + // The shared ground itself is the first exposure: anyone can rename `work` aside there, sticky or not. + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + }); + expect(fs.readdirSync(attacker)).toEqual([]); +}); + +skipOnWindows('a recording refuses an ancestor whose target is a writable directory', () => { + const directory = root(); + const shared = sharedDirectory(path.join(directory, 'shared'), 0o777); + const privateWork = path.join(shared, 'private'); + fs.mkdirSync(privateWork); + fs.symlinkSync(privateWork, path.join(directory, 'link')); + const destination = path.join(directory, 'link', 'journey.ad'); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + ancestor: shared, + }); + expect(fs.readdirSync(privateWork)).toEqual([]); +}); + +skipOnWindows('a recording refuses an ancestor swapped out for a writable directory', () => { + const directory = root(); + const work = path.join(directory, 'work'); + fs.mkdirSync(work); + const destination = path.join(work, 'journey.ad'); + // Another local user replaces the destination directory by name before this write runs. + fs.rmSync(work, { recursive: true }); + fs.mkdirSync(work); + fs.chmodSync(work, 0o777); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + }); + expect(fs.readdirSync(work)).toEqual([]); +}); + +skipOnWindows('a recording refuses a private link standing on shared ground two levels up', () => { + // `/shared` is 0777 and not sticky, `/shared/mine` is 0700, and `mine/rec` links to a + // private directory. Every directory the destination's real path names is private, so only judging + // each prefix the kernel traverses sees that another local user owns the ground under `mine` and `rec`. + const directory = root(); + const shared = path.join(directory, 'shared'); + fs.mkdirSync(shared); + fs.chmodSync(shared, 0o777); + const mine = path.join(shared, 'mine'); + fs.mkdirSync(mine); + fs.chmodSync(mine, 0o700); + const privateWork = path.join(directory, 'private'); + fs.mkdirSync(privateWork); + fs.symlinkSync(privateWork, path.join(mine, 'rec')); + const destination = path.join(mine, 'rec', 'journey.ad'); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + ancestor: shared, + }); + expect(fs.readdirSync(privateWork)).toEqual([]); +}); + +skipOnWindows('a recording refuses a chain that leaves a shared directory through a link', () => { + // `~/rec -> /srv/team/relay -> ~/chosen`. The team ground is 0777, and any teammate can swap the + // `relay` link for a target of their own, though the destination's real path never names it. + const directory = root(); + const home = path.join(directory, 'home'); + fs.mkdirSync(home); + const team = path.join(directory, 'srv', 'team'); + fs.mkdirSync(team, { recursive: true }); + fs.chmodSync(team, 0o777); + const chosen = path.join(directory, 'chosen'); + fs.mkdirSync(chosen); + fs.chmodSync(chosen, 0o700); + fs.symlinkSync(chosen, path.join(team, 'relay')); + fs.symlinkSync(path.join(team, 'relay'), path.join(home, 'rec')); + const destination = path.join(home, 'rec', 'journey.ad'); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + ancestor: team, + }); + expect(fs.readdirSync(chosen)).toEqual([]); +}); + +skipOnWindows('a recording stages inside the directory the entry is created in', () => { + // `home/work -> priv/x`, `priv/y` is private and `home/y` is open to others. The entry lands in + // `priv/y`. `path.dirname` + `path.join` of the SAME spelling answers `home/y`, because `path.join` + // folds `work/..` away, so a writer that stages beside the spelled parent puts a file it is about to + // publish into ground no rule judged — where anyone who can list it can put their own bytes behind that + // name before the rename. The staging directory has to be the directory the walk judged. + const directory = root(); + const home = path.join(directory, 'home'); + fs.mkdirSync(home); + fs.chmodSync(home, 0o700); + const sharedY = path.join(home, 'y'); + fs.mkdirSync(sharedY); + fs.chmodSync(sharedY, 0o777); + const priv = path.join(directory, 'priv'); + const privX = path.join(priv, 'x'); + fs.mkdirSync(privX, { recursive: true }); + const privY = path.join(priv, 'y'); + fs.mkdirSync(privY); + fs.chmodSync(privY, 0o700); + fs.symlinkSync(privX, path.join(home, 'work')); + const destination = `${home}/work/../y/journey.ad`; + const staged: string[] = []; + const realWriteFileSync = fs.writeFileSync; + vi.spyOn(fs, 'writeFileSync').mockImplementation(((file: unknown, ...rest: unknown[]) => { + if (typeof file === 'string' && file.endsWith('.tmp')) staged.push(path.dirname(file)); + return (realWriteFileSync as (...args: unknown[]) => unknown)(file, ...rest); + }) as typeof fs.writeFileSync); + + expect(writerFor(directory).write(recordingTo(destination)).written).toBe(true); + + expect(staged).toEqual([privY]); + expect(fs.readFileSync(path.join(privY, 'journey.ad'), 'utf8')).toContain('Demo'); + expect(fs.readdirSync(sharedY)).toEqual([]); +}); + +skipOnWindows('a recording refuses the directory a .. steps back into', () => { + // `home/work -> priv/x`, and `priv/y` at 0777 while `home/y` is private. Normalizing the spelling first + // answers `home/y`, so it accepts a write that the kernel lands in `priv/y`, where any local user can + // take the recording. + const directory = root(); + const home = path.join(directory, 'home'); + fs.mkdirSync(home); + fs.chmodSync(home, 0o700); + const priv = path.join(directory, 'priv'); + const privX = path.join(priv, 'x'); + fs.mkdirSync(privX, { recursive: true }); + const privY = path.join(priv, 'y'); + fs.mkdirSync(privY); + fs.chmodSync(privY, 0o777); + fs.mkdirSync(path.join(home, 'y')); + fs.symlinkSync(privX, path.join(home, 'work')); + const destination = `${home}/work/../y/journey.ad`; + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + ancestor: privY, + }); + expect(fs.readdirSync(privY)).toEqual([]); +}); + +skipOnWindows('a recording refuses the ground a link target crosses on the way in', () => { + // `home/rec -> /shared/relay/sub`, with `shared` at 0777 and not sticky and `shared/relay` a link + // into a directory of mine. Every directory at the destination looks private; only walking the target + // component by component shows that getting there crossed `shared`, where any other local user can swap + // `relay` for one of their own. + const directory = root(); + const shared = sharedDirectory(path.join(directory, 'shared'), 0o777); + const relayTarget = path.join(directory, 'chosen'); + fs.mkdirSync(relayTarget); + fs.chmodSync(relayTarget, 0o700); + fs.symlinkSync(relayTarget, path.join(shared, 'relay')); + const sub = path.join(relayTarget, 'sub'); + fs.mkdirSync(sub); + const home = path.join(directory, 'home'); + fs.mkdirSync(home); + fs.chmodSync(home, 0o700); + fs.symlinkSync(path.join(shared, 'relay', 'sub'), path.join(home, 'rec')); + const destination = path.join(home, 'rec', 'journey.ad'); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + ancestor: shared, + }); + expect(fs.readdirSync(relayTarget)).toEqual(['sub']); +}); + +skipOnWindows('a recording refuses a link another local user owns on the way in', () => { + // `~/rec -> /tmp/relay -> ~/chosen`, with `relay` another user's file in a sticky shared + // directory: they can unlink it and leave one of their own, and the second hop is theirs to choose. + const directory = root(); + const home = path.join(directory, 'home'); + fs.mkdirSync(home); + const chosen = path.join(directory, 'chosen'); + fs.mkdirSync(chosen); + const relay = path.join(directory, 'relay'); + fs.symlinkSync(chosen, relay); + const tmp = path.join(directory, 'tmp'); + fs.mkdirSync(tmp); + fs.chmodSync(tmp, 0o1777); + fs.renameSync(relay, path.join(tmp, 'relay')); + fs.symlinkSync(path.join(tmp, 'relay'), path.join(home, 'rec')); + const destination = path.join(home, 'rec', 'journey.ad'); + serveHostOwnership({ [path.join(tmp, 'relay')]: FOREIGN_UID }); + + const details = refusal(writerFor(directory).write(recordingTo(destination))); + + expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'planted_link' }); + expect(fs.readdirSync(chosen)).toEqual([]); +}); + +skipOnWindows('a recording refuses a group-writable home and says how to close it', () => { + // The stock shared-checkout shape on Ubuntu and Debian: the project directory is 0775 and its group is + // this user's own. ADR 0016 carries no private-group exception, because membership cannot be proven + // from the host's account files, so the mode alone refuses it and the hint names the fix. + const directory = root(); + const home = homeDirectory(path.join(directory, 'home'), 0o775); + + const details = refusal(writerFor(directory).write(recordingTo(path.join(home, 'journey.ad')))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'shared_group_writable', + ancestor: home, + }); + expect(String(details.hint)).toContain(`chmod g-w ${home}`); + expect(fs.readdirSync(home)).toEqual([]); +}); + +skipOnWindows('a recording creates a missing parent at 0700 on a shared umask', () => { + // The umask of a shared checkout: a mode-less creation is 0775, which is the mode the check right after + // it refuses, so the save both fails and leaves the directory it made standing in the project. host-kit + // creates at 0700 and a recursive mkdir applies that to every level, so the new parent passes the check + // it is judged by and the save goes through. + const directory = root(); + const home = homeDirectory(path.join(directory, 'home'), 0o700); + const destination = path.join(home, 'workflows', 'recordings', 'journey.ad'); + const previous = process.umask(0o002); + let result: ReturnType; + try { + result = writerFor(directory).write(recordingTo(destination)); + } finally { + process.umask(previous); + } + + expect(result.written).toBe(true); + expect(fs.readFileSync(destination, 'utf8')).toContain('open'); + expect(fs.lstatSync(path.join(home, 'workflows')).mode & 0o777).toBe(0o700); + expect(fs.lstatSync(path.join(home, 'workflows', 'recordings')).mode & 0o777).toBe(0o700); +}); + +skipOnWindows.each(['sessions', 'remote-scripts'] as const)( + 'a remote version refuses to follow a state link at %s, and writes nothing outside the state tree', + (linkLevel) => { + // The destination rule judges ground, not ownership of a name, and it ACCEPTS a link standing in a + // parent others cannot write: `sessions -> outside` with `outside` at 0755 owned by this user passes the + // walk. For a caller's `--save-script` path that is the caller's business. For a path the DAEMON picked + // for itself — every remote version — a chain that the state repair stopped on at a link leads outside + // the state tree, and the daemon must not publish through it. Startup still starts (the repair stays + // best-effort); this is the write half of that answer (ADR 0016). + const stateDir = root(); + const outside = path.join(stateDir, 'outside'); + fs.mkdirSync(outside); + fs.chmodSync(outside, 0o755); + const sessions = path.join(stateDir, 'sessions'); + const remote = path.join(sessions, 'remote-scripts'); + const link = linkLevel === 'sessions' ? sessions : remote; + if (linkLevel === 'remote-scripts') fs.mkdirSync(sessions); + fs.symlinkSync(outside, link); + + const result = writerFor(stateDir).write(remoteRecording()); + + expect(refusal(result)).toMatchObject({ reason: 'state_chain_untrusted' }); + // No version was published on the far side of the link. The empty level the recursive `mkdir` may leave + // there is the disclosed creation behavior (#4584 review); what must not appear is the RECORDING, and + // the destination walk refuses any publication under that tree anyway. + expect(scriptFilesIn(outside)).toEqual([]); + expect(fs.lstatSync(link).isSymbolicLink()).toBe(true); + }, +); + +skipOnWindows( + 'a daemon-picked recording refuses state sitting under a directory another user can write', + () => { + // The accepted consequence of judging the ancestry: state that sits inside a directory other local users + // can write is not ground the daemon can call its own, because they can move the whole state tree out + // from under it. Every daemon-picked destination — the default recording here, and every remote version — + // is then refused with the state-chain reason, while a destination the CALLER named stays the walk's + // business alone (the tests above). Startup is unaffected: this refusal is the write half of the answer. + const stateDir = root(); + const shared = sharedDirectory(path.join(stateDir, 'shared'), 0o777); + const base = path.join(shared, 'agent-device'); + + const result = writerFor(base).write(remoteRecording()); + + expect(refusal(result)).toMatchObject({ reason: 'state_chain_untrusted' }); + // The repair never went below the shared ancestor: the state chain was created at its own private modes, + // and the shared directory nobody owns keeps the mode its owner chose. + expect(fs.lstatSync(path.join(base, 'sessions')).mode & 0o777).toBe(0o700); + expect(fs.lstatSync(path.join(base, 'sessions', 'remote-scripts')).mode & 0o777).toBe(0o700); + expect(fs.lstatSync(shared).mode & 0o777).toBe(0o777); + expect(scriptFilesIn(path.join(base, 'sessions', 'remote-scripts'))).toEqual([]); + }, +); + +skipOnWindows('a default recording refuses to follow a state link at `sessions` too', () => { + // Same answer for the other daemon-picked destination: a default recording lives under `sessions/`, so a + // skipped chain there is refused the same way, and the far-side directory gets no file. + const stateDir = root(); + const outside = path.join(stateDir, 'outside'); + fs.mkdirSync(outside); + fs.chmodSync(outside, 0o755); + fs.symlinkSync(outside, path.join(stateDir, 'sessions')); + + const result = writerFor(stateDir).write( + makeAuthoringSession('journey', { + scriptPublication: authoringPublication('armed', {}), + actions: [action('open')], + }), + ); + + expect(refusal(result)).toMatchObject({ reason: 'state_chain_untrusted' }); + expect(scriptFilesIn(outside)).toEqual([]); +}); + +skipOnWindows( + 'a refused remote version is disclosed through the capability as a delivery failure', + () => { + // The capability is what a remote caller sees: the ACTION keeps its success, and the response carries + // `scriptDeliveryFailure` (ADR 0016). The state-chain refusal has to travel that path and not surface as + // a failed action or a silent success, with its typed reason as the failure's cause. + const stateDir = root(); + const outside = path.join(stateDir, 'outside'); + fs.mkdirSync(outside); + fs.chmodSync(outside, 0o755); + const sessions = path.join(stateDir, 'sessions'); + fs.symlinkSync(outside, sessions); + const store = new SessionStore(sessions, createLiveTestHostEnvironment()); + const ref = store.publish( + 'journey', + makeAuthoringSession('journey', { + scriptPublication: authoringPublication('armed', { remote: true }), + actions: [action('open')], + }), + ); + const deliver = remoteScriptVersionDelivery(store, 'journey'); + ref.session.actions.push(action('click')); + + const response = deliver({ ok: true, data: {} }); + if (!response.ok) throw new Error('a failed version keeps the action successful'); + + expect(response.data?.scriptDeliveryFailure).toMatchObject({ + reason: 'script_delivery_failed', + publicationId: 'publication-0001', + cause: 'state_chain_untrusted', + }); + expect(response.data?.warnings).toHaveLength(1); + expect(scriptFilesIn(outside)).toEqual([]); + }, +); + +/** Every file under `directory`, at any depth: what a refused publication must not have left behind. */ +function scriptFilesIn(directory: string): string[] { + return fs.readdirSync(directory, { recursive: true }).filter((name) => { + return fs.statSync(path.join(directory, String(name))).isFile(); + }) as string[]; +} diff --git a/packages/daemon/src/core/__tests__/session-script-writer.test.ts b/packages/daemon/src/core/__tests__/session-script-writer.test.ts index 054b1ce2e0..7b96959e5d 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer.test.ts @@ -15,6 +15,7 @@ import { markRepairTransactionComplete } from '../session-replay-transaction.ts' import { NO_SCRIPT_PUBLICATION, scriptTargetPath } from '../session-script-publication-state.ts'; import { parseReplayScriptDetailed, resolveReplayAction } from '@agent-device/ad-script'; import { createLiveTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; +import { failScriptStagingWrite } from '../../__tests__/support/script-staging-failure.ts'; const hostCwd = createLiveTestHostEnvironment().cwd; @@ -554,7 +555,10 @@ test('write(session) without { force: true } still refuses, even when a prior wr // concurrent race correctly without any lock — first writer wins, the loser // sees `EEXIST` and is refused. test('two writers racing on the SAME ABSENT target: exactly one linkSync wins, the other is refused (no lock involved)', () => { - const root = mkdtempForTestSync('agent-device-script-writer-race-'); + // Realpath'ed because the publish creates the entry in the directory the ancestry walk ANSWERED, and on + // macOS `mkdtemp` spells the scratch root through the `/var` alias: this spy compares the entry's path + // with the one it expects to see. + const root = fs.realpathSync(mkdtempForTestSync('agent-device-script-writer-race-')); const writer = new SessionScriptWriter(path.join(root, 'sessions'), hostCwd); const healedPath = path.join(root, 'flows', 'login.healed.ad'); fs.mkdirSync(path.dirname(healedPath), { recursive: true }); @@ -696,9 +700,12 @@ test('an ordinary (non-repair) recording now refuses an existing target too (beh test('an ordinary recording returns a filesystem write failure as a typed error, never a quiet skip', () => { const root = mkdtempForTestSync('agent-device-script-writer-ordinary-fs-failure-'); const writer = new SessionScriptWriter(path.join(root, 'sessions'), hostCwd); - const blocker = path.join(root, 'blocker'); - fs.writeFileSync(blocker, ''); - const outPath = path.join(blocker, 'flow.ad'); + // The staging write of the publication is made to fail, so the failure the caller sees is the + // filesystem's own and not an ancestry verdict. A directory the mode bits deny this user is not used + // for that: mode bits do not bind root, so under a root caller the write would succeed and this test + // would be reporting the host's permission model instead of the writer's error handling. + const outPath = path.join(root, 'flow.ad'); + failScriptStagingWrite(outPath); const session = makeAuthoringSession('default', { scriptPublication: authoringPublication('armed', { path: outPath }), actions: [action({ command: 'click', positionals: ['id="new"'] })], diff --git a/packages/daemon/src/core/__tests__/session-store-teardown-script.test.ts b/packages/daemon/src/core/__tests__/session-store-teardown-script.test.ts index 7bff2bfb17..fc64a4a5de 100644 --- a/packages/daemon/src/core/__tests__/session-store-teardown-script.test.ts +++ b/packages/daemon/src/core/__tests__/session-store-teardown-script.test.ts @@ -1,7 +1,17 @@ import { expect, test, vi } from 'vitest'; import fs from 'node:fs'; import path from 'node:path'; -import { createLiveTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; +import { + FOREIGN_UID, + createLiveTestHostEnvironment, + mkdtempForTestSync, + serveHostOwnership, +} from '@agent-device/test-kit'; +import { ensurePrivateDaemonStateDir } from '@agent-device/daemon-contracts/daemon-registration-owner'; +import { + countDiagnosticEventsByPhase, + withDiagnosticsScope, +} from '@agent-device/host-kit/diagnostics'; import { SessionStore } from '../session-store.ts'; import { authoringPublication, @@ -81,7 +91,155 @@ test.skipIf(process.platform === 'win32')( expect(fs.statSync(result.path).mode & 0o777).toBe(0o600); } expect(localWrite).toMatchObject({ written: true, path: local }); - const umask = process.umask(); - expect(fs.statSync(local).mode & 0o777).toBe(0o666 & ~umask); + // A recording is a transcript of what someone did on this machine, so the caller's own file is + // private too, whatever the umask would have allowed (#4565). + expect(fs.statSync(local).mode & 0o777).toBe(0o600); + }, +); + +test.skipIf(process.platform === 'win32')( + 'on a umask-002 host the daemon creates and repairs its own state directories at 0700', + () => { + // A stock Ubuntu login runs umask 002, and the daemon creates `sessions/` itself: a mode-less `mkdir` + // there is 0775. Every script path the daemon picks for itself is walked through that directory, and a + // group-writable directory on the way is refused, so the daemon would refuse its own default recordings + // and every remote-delivered version. `ensureSessionDir` runs on `open`, so this is the first thing a + // session does. (ADR 0016) + const root = mkdtempForTestSync('agent-device-shared-umask-'); + // What the daemon's own state dir is forced to on startup, whatever created it. + fs.chmodSync(root, 0o700); + const store = new SessionStore(path.join(root, 'sessions'), createLiveTestHostEnvironment()); + const session = (name: string, remote: boolean) => + store.publish( + name, + makeAuthoringSession(name, { + scriptPublication: authoringPublication('armed', { remote }), + actions: [{ ts: 1, command: 'open', positionals: ['Demo'], flags: {} }], + }), + ); + const previous = process.umask(0o002); + let defaultPath: ReturnType; + let version: ReturnType; + try { + store.ensureSessionDir('journey'); + defaultPath = store.writeSessionLog(session('journey', false)); + version = store.writeRemoteScriptVersion(session('download', true)); + } finally { + process.umask(previous); + } + + if (!defaultPath.written) throw new Error(`default recording refused: ${refusal(defaultPath)}`); + if (!version.written) throw new Error(`remote version refused: ${refusal(version)}`); + expect(path.dirname(defaultPath.path)).toBe(path.join(root, 'sessions')); + expect(path.dirname(version.path)).toBe(path.join(root, 'sessions', 'remote-scripts')); + for (const directory of [ + path.join(root, 'sessions'), + path.join(root, 'sessions', 'journey'), + path.join(root, 'sessions', 'remote-scripts'), + ]) { + expect(fs.lstatSync(directory).mode & 0o777).toBe(0o700); + } }, ); + +test.skipIf(process.platform === 'win32')( + 'repairs state directories a legacy version or a shared checkout created at 0775', + () => { + // The test above starts from fresh 0700 directories, so it would pass even with the repair disabled: + // only the creation carries the mode. What a host already has is the other half — an older release, or + // a checkout shared under umask 002, leaves `sessions/` and `remote-scripts/` at 0775, and the rule + // refuses a recording walked through one. (ADR 0016) + const root = mkdtempForTestSync('agent-device-legacy-state-'); + fs.chmodSync(root, 0o755); + const sessions = path.join(root, 'sessions'); + const remote = path.join(sessions, 'remote-scripts'); + for (const directory of [sessions, remote]) { + fs.mkdirSync(directory); + fs.chmodSync(directory, 0o775); + } + const store = new SessionStore(sessions, createLiveTestHostEnvironment()); + const session = (name: string, remoteDelivery: boolean) => + store.publish( + name, + makeAuthoringSession(name, { + scriptPublication: authoringPublication('armed', { remote: remoteDelivery }), + actions: [{ ts: 1, command: 'open', positionals: ['Demo'], flags: {} }], + }), + ); + + // How the daemon reaches this state: startup forces `sessions/` private, an `open` then ensures its own + // session directory, and the remote route is the one that puts `remote-scripts/` in place. + ensurePrivateDaemonStateDir(sessions, root); + store.ensureSessionDir('journey'); + expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o700); + expect(fs.lstatSync(path.join(sessions, 'journey')).mode & 0o777).toBe(0o700); + + const defaultPath = store.writeSessionLog(session('journey', false)); + const version = store.writeRemoteScriptVersion(session('download', true)); + if (!defaultPath.written) throw new Error(`default recording refused: ${refusal(defaultPath)}`); + if (!version.written) throw new Error(`remote version refused: ${refusal(version)}`); + expect(fs.lstatSync(remote).mode & 0o777).toBe(0o700); + }, +); + +test.skipIf(process.platform === 'win32')( + 'skips a `sessions` directory another user owns, and changes nothing there', + async () => { + // Repair is what fixes a host the daemon did not create, so the repair is itself the dangerous step: a + // `chmod` given the NAME acts on whatever that name answers. Simulated root ownership (state an older + // release left owned by another uid) makes this process foreign to `sessions/`, as it is on that host. + // The mode is therefore applied through an `O_NOFOLLOW` descriptor whose `fstat` says whose entry it is, + // and a foreign one is left as its owner set it — the daemon still starts, and the destination walk is + // what refuses a recording under that tree. + const root = mkdtempForTestSync('agent-device-foreign-state-'); + fs.chmodSync(root, 0o755); + const sessions = path.join(root, 'sessions'); + fs.mkdirSync(sessions); + fs.chmodSync(sessions, 0o775); + serveHostOwnership({ [sessions]: FOREIGN_UID }); + + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, root))).toBe(1); + + // Nothing was touched: the owner's directory keeps the mode they set for it. + expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o775); + }, +); + +test.skipIf(process.platform === 'win32')( + 'skips a planted `sessions` link under state another user can write, and leaves where it leads alone', + async () => { + // The shape of the blocker: `sessions` is writable by another local user, they leave a link at that + // name, and a root daemon forcing its own state private is handed the name. Repairing it by pathname + // travels through the link and changes the mode of the attacker's directory — as root, with privileges. + // The mode comes from a descriptor that cannot follow a link, so this call reports the level and starts. + const root = mkdtempForTestSync('agent-device-planted-state-'); + fs.chmodSync(root, 0o777); + const planted = path.join(root, 'attacker'); + fs.mkdirSync(planted); + fs.chmodSync(planted, 0o777); + const sessions = path.join(root, 'sessions'); + fs.symlinkSync(planted, sessions); + + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, root))).toBe(1); + + expect(fs.lstatSync(planted).mode & 0o777).toBe(0o777); + expect(fs.readdirSync(planted)).toEqual([]); + expect(fs.lstatSync(sessions).isSymbolicLink()).toBe(true); + }, +); + +/** Why a write that had to succeed did not, from the typed reason the writer returned. */ +function refusal(result: object): string { + return JSON.stringify(result); +} + +/** + * Runs one state repair inside its own diagnostics scope and reports how often it said it skipped a level. + * No `logPath`, so the events are tallied and written nowhere. + */ +async function skipCountFor(repair: () => unknown): Promise { + return await withDiagnosticsScope({ session: 'daemon' }, () => { + expect(repair()).toBeDefined(); + return countDiagnosticEventsByPhase(['daemon_state_mode_repair_skipped']); + }); +} diff --git a/packages/daemon/src/core/session-script-publication-capability.ts b/packages/daemon/src/core/session-script-publication-capability.ts index b6418f80dc..e36fd66f4e 100644 --- a/packages/daemon/src/core/session-script-publication-capability.ts +++ b/packages/daemon/src/core/session-script-publication-capability.ts @@ -6,6 +6,7 @@ import type { ScriptDeliveryFailure, } from '@agent-device/kernel/contracts'; import { readResponseWarnings } from '@agent-device/kernel/success-text'; +import type { AppError } from '@agent-device/kernel/errors'; import type { SessionStore } from './session-store.ts'; import { asDaemonDeliveredArtifact } from './capture-output-ownership.ts'; import type { SessionState } from './session-state.ts'; @@ -226,7 +227,9 @@ export function isSessionScriptPublished(session: SessionState): boolean { */ type RemoteScriptVersion = | Readonly<{ path: string }> - | Readonly<{ failure: Readonly<{ message: string; hint: string }> }>; + | Readonly<{ + failure: Readonly<{ message: string; hint: string; cause?: string }>; + }>; /** What a close delivers for a remote recording: the recording it ended and its final version. */ export type RemoteCloseScript = Readonly<{ @@ -310,11 +313,15 @@ export function remoteScriptVersionDelivery( return withRemoteScriptVersion(response, stamped, { path: result.path }); } if (!result.error) return response; - // The daemon diagnostic keeps the cause; its daemon-host path stays out of the response. + // The daemon diagnostic keeps the cause; its daemon-host path stays out of the response. The typed + // reason travels as the failure's `cause`, so a client can tell which refusal this was (ADR 0016). return withRemoteScriptVersion(response, delivery, { failure: { message: 'The action succeeded, but the daemon could not write the remote recording.', hint: 'The --save-script file keeps the previous version. The next recorded action or close delivers the full recording again.', + ...(typeof result.error.details?.reason === 'string' + ? { cause: result.error.details.reason } + : {}), }, }); }; @@ -324,18 +331,32 @@ export function remoteScriptVersionDelivery( * Reads what a close of a remote recording delivers from the session that the close-time write * just marked, because teardown may have replaced the session object before that write. A * published final version is stamped after every earlier version, so it replaces the last one. + * + * `writeFailure` is the close write's own error, and its typed reason travels as the failure's + * `cause`: a close refused for the daemon's state chain is a different recovery than a full disk, + * and the client sees which without reading prose (ADR 0016). */ export function remoteCloseScript( session: SessionState, - writeFailed: boolean, + writeFailure: AppError | undefined, ): RemoteCloseScript | undefined { const state = session.scriptPublication; if (state?.kind !== 'authoring' || !state.remoteDelivery) return undefined; const delivery = state.remoteDelivery; - if (writeFailed) { + if (writeFailure) { const message = 'The session was closed, but the daemon could not write its final script.'; const hint = 'The --save-script file keeps the version from the last recorded action.'; - return { delivery, version: { failure: { message, hint } } }; + const reason = writeFailure.details?.reason; + return { + delivery, + version: { + failure: { + message, + hint, + ...(typeof reason === 'string' ? { cause: reason } : {}), + }, + }, + }; } const writtenPath = state.status === 'published' ? scriptTargetPath(state) : undefined; if (!writtenPath) return { delivery }; diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index be5050e645..de56f2707b 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -1,11 +1,11 @@ import type { SessionAction } from '@agent-device/contracts/session'; import crypto from 'node:crypto'; -import fs from 'node:fs'; import path from 'node:path'; import { publicPlatformString } from '@agent-device/kernel/device'; import { dragGesturePayloadFromPositionals } from '@agent-device/contracts/gesture-normalization'; import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { AppError } from '@agent-device/kernel/errors'; +import { ensurePrivateDaemonStateDir } from '@agent-device/daemon-contracts/daemon-registration-owner'; import { inferFillText, appendScriptSeriesFlags, @@ -19,7 +19,7 @@ import { stripRecordedRefGeneration, } from '@agent-device/ad-script'; import { expandSessionPath, safeSessionName } from '@agent-device/host-kit/session-paths'; -import { publishFileSync } from '@agent-device/host-kit/file'; +import { publishScriptFileSync } from '@agent-device/host-kit/file'; import type { SessionState } from './session-state.ts'; import { NO_SCRIPT_PUBLICATION, @@ -131,20 +131,21 @@ export class SessionScriptWriter { activePublication, }); const remote = - session.scriptPublication?.kind === 'authoring' && session.scriptPublication.remoteDelivery; - scriptPath = remote ? this.remoteScriptPath() : this.resolveScriptPath(session); - const scriptDir = path.dirname(scriptPath); - if (!fs.existsSync(scriptDir)) fs.mkdirSync(scriptDir, { recursive: true }); + session.scriptPublication?.kind === 'authoring' && + session.scriptPublication.remoteDelivery !== undefined; + const destination = this.resolveScriptDestination(session, remote); + scriptPath = destination.path; + if (destination.pickedByDaemon && !destination.privateChain) { + throw daemonStateUntrustedFailure(destination.path); + } // #1258: `options.force` is the caller's already-merged decision // (`effectiveWriteForce` — a live flag or the per-target grant), not // read from `session` directly here, so this stays a pure // formatting+publish step. - publishHealedScriptAtomically({ - scriptPath, - script: prepared.script, - force: options?.force, - ...(remote ? { mode: 0o600 } : {}), - }); + // host-kit owns the rest (#4565): the publisher walks the chain, refuses a destination another + // local user can steer BEFORE creating anything, creates what is missing at 0700 inside the + // directory it judged, and judges that completed chain before the entry is created. + publishHealedScriptAtomically({ scriptPath, script: prepared.script, force: options?.force }); // COMMITTED: idempotent guard above + teardown's abort/tombstone routing. if (repairArmed) { session.scriptPublication = commitRepair( @@ -164,25 +165,46 @@ export class SessionScriptWriter { } /** - * A remote recording's caller downloads each version once, so every version, the close-time - * script included, gets a fresh private (0600) file in a private (0700) directory that only the - * daemon user can read. + * Where this write's script goes, and whether the daemon picked that path itself. + * + * A caller's `--save-script=` is the caller's own destination, and the destination rule in host-kit + * is what judges it. Everything else is a path the daemon picked for itself — a default recording under + * `sessions/`, or a remote version under `sessions/remote-scripts/`, each a fresh file in a private (0700) + * directory. Ensuring that directory answers whether the chain from the state base is private ground, which + * is what the refusal below is for. Startup keeps going either way (#4565). */ - private remoteScriptPath(): string { - const directory = path.join(this.sessionsDir, 'remote-scripts'); - fs.mkdirSync(directory, { recursive: true, mode: 0o700 }); - fs.chmodSync(directory, 0o700); - return path.join(directory, `${crypto.randomUUID()}.ad`); - } - - private resolveScriptPath(session: SessionState): string { + private resolveScriptDestination( + session: SessionState, + remote: boolean, + ): { path: string; pickedByDaemon: boolean; privateChain: boolean } { + const stateBase = path.dirname(this.sessionsDir); + if (remote) { + const directory = ensurePrivateDaemonStateDir( + path.join(this.sessionsDir, 'remote-scripts'), + stateBase, + ); + return { + ...directory, + pickedByDaemon: true, + path: path.join(directory.path, `${crypto.randomUUID()}.ad`), + }; + } const targetPath = scriptTargetPath(session.scriptPublication ?? NO_SCRIPT_PUBLICATION); if (targetPath) { - return expandSessionPath(targetPath, this.hostCwd); + return { + path: expandSessionPath(targetPath, this.hostCwd), + pickedByDaemon: false, + privateChain: true, + }; } const safeName = safeSessionName(session.name); const timestamp = new Date(session.createdAt).toISOString().replaceAll(/[:.]/g, '-'); - return path.join(this.sessionsDir, `${safeName}-${timestamp}.ad`); + const own = ensurePrivateDaemonStateDir(this.sessionsDir, stateBase); + return { + ...own, + pickedByDaemon: true, + path: path.join(own.path, `${safeName}-${timestamp}.ad`), + }; } } @@ -231,21 +253,63 @@ function handleSessionScriptWriteFailure(params: { return { written: false, error: toOrdinaryWriteFailure(error, scriptPath) }; } -function toOrdinaryWriteFailure(error: unknown, scriptPath: string | undefined): AppError { - if (error instanceof AppError) return error; +/** + * A filesystem failure that has to reach the caller as its own typed error: an ordinary recording + * carries `script_write_failed` with the path it could not be written to, and both name what was being + * written, because the same writer publishes a recording and a healed repair. + */ +function toScriptWriteFailure( + error: unknown, + scriptPath: string | undefined, + subject: Readonly<{ noun: string; hint: string; reportsPath?: boolean }>, +): AppError { const detail = error instanceof Error ? error.message : String(error); + const where = scriptPath === undefined ? '' : ` to ${scriptPath}`; return new AppError( 'COMMAND_FAILED', - `Failed to write the session script${scriptPath ? ` to ${scriptPath}` : ''}: ${detail}`, + `Failed to write the ${subject.noun}${where}: ${detail}`, { - reason: 'script_write_failed', - ...(scriptPath ? { path: scriptPath } : {}), - hint: 'Check the target path and its permissions, then re-record with open --save-script.', + ...(subject.reportsPath === true && scriptPath !== undefined + ? { reason: 'script_write_failed' as const, path: scriptPath } + : {}), + hint: subject.hint, }, error, ); } +/** + * Refusal for a script the daemon was about to write on a state chain the repair did not accept: a path + * the daemon picked for itself, on ground it could not establish as its own. The destination walk is not + * what refuses it — the walk ACCEPTS a link whose parent others cannot write (ADR 0016). + */ +function daemonStateUntrustedFailure(scriptPath: string): AppError { + return new AppError( + 'COMMAND_FAILED', + `The recording was not written: the daemon's own state directory is not private ground, so ${scriptPath} does not name a directory this daemon owns.`, + { + reason: 'state_chain_untrusted', + path: scriptPath, + hint: + 'A level of the daemon state chain, or a directory above it, is a symbolic link, is owned by ' + + 'another user, or is open to other users, so the daemon cannot call it private ground. This is the ' + + 'shape of a bind-mounted CI volume, a container image that leaves the state directory to another ' + + 'uid, or a state directory inside a shared directory anyone can write. Make the daemon own that ' + + 'tree (chown -R the state directory to the daemon user), or point AGENT_DEVICE_STATE_DIR at a ' + + 'directory it owns, then re-record. A recording to an explicit --save-script path is unaffected.', + }, + ); +} + +function toOrdinaryWriteFailure(error: unknown, scriptPath: string | undefined): AppError { + if (error instanceof AppError) return error; + return toScriptWriteFailure(error, scriptPath, { + noun: 'session script', + reportsPath: true, + hint: 'Check the target path and its permissions, then re-record with open --save-script.', + }); +} + /** * ADR 0012 decision 6 (BLOCKER 2c): normalizes a repair-commit failure into a * distinct, surfaceable AppError. A no-clobber refusal or a bare-`@ref` failure @@ -255,14 +319,10 @@ function toOrdinaryWriteFailure(error: unknown, scriptPath: string | undefined): */ function toRepairCommitFailure(error: unknown, scriptPath: string | undefined): AppError { if (error instanceof AppError) return error; - const detail = error instanceof Error ? error.message : String(error); - return new AppError( - 'COMMAND_FAILED', - `Failed to write the healed script${scriptPath ? ` to ${scriptPath}` : ''}: ${detail}`, - { - hint: 'The repair transaction completed but the healed .ad could not be published; check the target path and permissions, then retry close --save-script.', - }, - ); + return toScriptWriteFailure(error, scriptPath, { + noun: 'healed script', + hint: 'The repair transaction completed but the healed .ad could not be published; check the target path and permissions, then retry close --save-script.', + }); } /** @@ -301,15 +361,13 @@ function publishHealedScriptAtomically(params: { scriptPath: string; script: string; force?: boolean; - mode?: number; }): void { - const { scriptPath, script, force, mode } = params; + const { scriptPath, script, force } = params; try { - publishFileSync({ + publishScriptFileSync({ destination: scriptPath, contents: script, publish: force ? 'replace' : 'link-exclusive', - ...(mode === undefined ? {} : { mode }), }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; diff --git a/packages/daemon/src/core/session-store.ts b/packages/daemon/src/core/session-store.ts index 203d1277c2..3d3967fa1a 100644 --- a/packages/daemon/src/core/session-store.ts +++ b/packages/daemon/src/core/session-store.ts @@ -4,6 +4,7 @@ import { resolveSessionAppLogPidPath, } from '@agent-device/daemon-contracts/session-artifact-paths'; import { DAEMON_SHUTTING_DOWN_REASON } from '@agent-device/daemon-contracts/daemon-resolution'; +import { ensureDaemonStateDir } from '@agent-device/daemon-contracts/daemon-registration-owner'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; import path from 'node:path'; import fs from 'node:fs'; @@ -369,8 +370,7 @@ export class SessionStore { const session = this.resolveCurrent(ref); if (!session) return; try { - const dir = this.resolveSessionDir(ref.address); - fs.mkdirSync(dir, { recursive: true }); + ensureDaemonStateDir(this.resolveSessionDir(ref.address), this.resolveDaemonStateDir()); const tombstone: RepairSessionTombstone = { owner: ref.address, reapedAt: Date.now(), @@ -439,7 +439,7 @@ export class SessionStore { */ writeIdleExpiryTombstone(sessionName: string, tombstone: IdleSessionTombstone): void { try { - fs.mkdirSync(this.resolveSessionDir(sessionName), { recursive: true }); + ensureDaemonStateDir(this.resolveSessionDir(sessionName), this.resolveDaemonStateDir()); fs.writeFileSync( resolveIdleSessionTombstonePath(this.resolveSessionDir(sessionName)), `${JSON.stringify(tombstone)}\n`, @@ -520,10 +520,10 @@ export class SessionStore { return path.dirname(this.sessionsDir); } + // The daemon-paths owner creates and repairs each level (ADR 0016): under the shared-checkout umask a + // mode-less creation is 0775, and the script-destination rule then refuses the daemon's own recordings. ensureSessionDir(sessionName: string): string { - const sessionDir = this.resolveSessionDir(sessionName); - fs.mkdirSync(sessionDir, { recursive: true }); - return sessionDir; + return ensureDaemonStateDir(this.resolveSessionDir(sessionName), this.resolveDaemonStateDir()); } /** Path to session-scoped app log file. Agent can grep this for token-efficient debugging. */ diff --git a/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts b/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts index 5629f2cc37..84a5d57d70 100644 --- a/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts +++ b/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts @@ -23,7 +23,7 @@ const PROCESS_LOCK_SOURCE = new URL( test('simple same-directory publishers use the shared atomic publish owner', () => { for (const sourcePath of SIMPLE_PUBLISHERS) { const source = fs.readFileSync(sourcePath, 'utf8'); - assert.match(source, /publishFileSync/); + assert.match(source, /publish(?:Script)?FileSync/); assert.doesNotMatch(source, /fs\.(?:writeFileSync|renameSync)\s*\(/); } }); diff --git a/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts b/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts new file mode 100644 index 0000000000..2668437912 --- /dev/null +++ b/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts @@ -0,0 +1,178 @@ +// Startup, not the first `open`, is what makes the daemon's own state chain private. Both are on the chain +// of every recording the daemon picks a path for, and the destination-ancestry rule refuses a group-writable +// directory on it (ADR 0016), so a state directory an older release left at 0775 has to be forced before a +// session is ever created. What startup may NOT do is refuse a level whose mode it may not force: that +// decision belongs to the walk, per recording, and a host whose state it does not own still gets a daemon. +// (https://github.com/callstack/agent-device/pull/4584) + +import fs from 'node:fs'; +import path from 'node:path'; +import { expect, test } from 'vitest'; +import { + createTestHostEnvironment, + FOREIGN_UID, + mkdtempForTestSync, + serveHostOwnership, +} from '@agent-device/test-kit'; +import { + countDiagnosticEventsByPhase, + withDiagnosticsScope, +} from '@agent-device/host-kit/diagnostics'; +import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; +import { SessionStore } from '../../core/session-store.ts'; +import { + authoringPublication, + makeAuthoringSession, +} from '../../__tests__/support/session-factories.ts'; +import { daemonRuntimeDepsFixture } from '../../__tests__/support/daemon-runtime-deps-fixture.ts'; +import { startDaemonRuntime } from './daemon-runtime.ts'; + +const silent = { stderr: { write: () => {} }, stdout: { write: () => {} } }; + +test.skipIf(process.platform === 'win32')( + 'startup repairs a state chain a legacy release or a shared checkout left group-writable', + async () => { + // A host that ran an older version, or a checkout shared under the umask 002, stands at 0775. Nothing + // else forces those levels: `sessions/` is created by a per-session `mkdir` at the mode the umask gives + // it. Deleting the two `ensurePrivateDaemonStateDir` calls from startup turns this red. + const stateDir = mkdtempForTestSync('agent-device-startup-state-'); + const { baseDir, sessionsDir } = resolveDaemonPaths(stateDir); + fs.mkdirSync(sessionsDir, { mode: 0o755 }); + fs.chmodSync(baseDir, 0o775); + fs.chmodSync(sessionsDir, 0o775); + + const runtime = await startDaemonRuntime({ + host: hostFor(stateDir), + ...silent, + composeDeps: daemonRuntimeDepsFixture({}), + }); + try { + expect(modeOf(baseDir)).toBe(0o700); + expect(modeOf(sessionsDir)).toBe(0o700); + + // The point of the repair: a default recording walked through `sessions/` is now accepted. Before it, + // every one of these was refused `script_ancestor_untrusted` / `shared_group_writable`. + const store = new SessionStore(sessionsDir, createTestHostEnvironment()); + const written = store.writeSessionLog( + store.publish( + 'journey', + makeAuthoringSession('journey', { + scriptPublication: authoringPublication('armed', {}), + actions: [{ ts: 1, command: 'open', positionals: ['Demo'], flags: {} }], + }), + ), + ); + if (!written.written) + throw new Error(`startup left the chain untrusted: ${JSON.stringify(written)}`); + } finally { + await runtime.close(); + } + }, +); + +test.skipIf(process.platform === 'win32')( + 'startup starts on state another user owns, warns, and refuses only the recording under it', + async () => { + // A `sessions/` owned by a different uid at 0755 — a container whose volume belongs to the uid the mount + // came with, or a machine where one user ran the daemon as root — logged `daemon_state_mode_repair_skipped` + // and started. Refusing to start here would fail EVERY command over a mode, and the daemon takes nothing + // it does not own either way: the walk is what refuses a recording under that tree, with its own reason. + const stateDir = fs.realpathSync(mkdtempForTestSync('agent-device-startup-state-foreign-')); + const { sessionsDir } = resolveDaemonPaths(stateDir); + fs.mkdirSync(sessionsDir, { mode: 0o755 }); + fs.chmodSync(sessionsDir, 0o755); + serveHostOwnership({ [sessionsDir]: FOREIGN_UID }); + + // The scope is only there to see the warning; the runtime is closed inside it, so nothing outlives it. + const { runtime, skipped } = await withDiagnosticsScope({ session: 'daemon' }, async () => ({ + runtime: await startDaemonRuntime({ + host: hostFor(stateDir), + ...silent, + composeDeps: daemonRuntimeDepsFixture({}), + }), + skipped: countDiagnosticEventsByPhase(['daemon_state_mode_repair_skipped']), + })); + try { + expect(skipped).toBe(1); + // Nothing was taken from the owner: the directory stands as they left it. + expect(modeOf(sessionsDir)).toBe(0o755); + + // The refusal the host DOES get names the daemon's own state chain: a default recording is a path the + // daemon picks for itself, and it writes one only on ground it established as its own. The destination + // walk is what refuses a CALLER's path; here the chain never reached the walk (ADR 0016). + const store = new SessionStore(sessionsDir, createTestHostEnvironment()); + const refused = store.writeSessionLog( + store.publish( + 'journey', + makeAuthoringSession('journey', { + scriptPublication: authoringPublication('armed', {}), + actions: [{ ts: 1, command: 'open', positionals: ['Demo'], flags: {} }], + }), + ), + ); + expect(refusalOf(refused)).toMatchObject({ reason: 'state_chain_untrusted' }); + expect(String(refusalOf(refused).path).startsWith(sessionsDir + path.sep)).toBe(true); + // This host shape is what the hint has to name: this uid is not the owner of that tree, and the two + // ways out are chown and AGENT_DEVICE_STATE_DIR. + expect(String(refusalOf(refused).hint)).toContain('chown'); + expect(String(refusalOf(refused).hint)).toContain('AGENT_DEVICE_STATE_DIR'); + // Nothing was written under the foreign directory. + expect(fs.readdirSync(sessionsDir)).toEqual([]); + } finally { + await runtime.close(); + } + }, +); + +test.skipIf(process.platform === 'win32')( + 'startup starts when the state directory is a link, and leaves where it leads alone', + async () => { + // The other setup that must keep starting: `~/.agent-device` linked to another disk. The repair will not + // force a mode through a name that resolves somewhere else, so it skips that level with a warning — and + // the daemon still uses the state where the link points, exactly as it did before this rule existed. + const target = mkdtempForTestSync('agent-device-startup-state-target-'); + const parent = mkdtempForTestSync('agent-device-startup-state-link-'); + const linked = path.join(parent, 'state'); + fs.symlinkSync(target, linked); + + const { runtime, skipped } = await withDiagnosticsScope({ session: 'daemon' }, async () => ({ + runtime: await startDaemonRuntime({ + host: hostFor(linked), + ...silent, + composeDeps: daemonRuntimeDepsFixture({}), + }), + skipped: countDiagnosticEventsByPhase(['daemon_state_mode_repair_skipped']), + })); + try { + // The repair skipped the levels it could not reach by descriptor, and changed nothing else: the link is + // still a link and the state appeared under the directory it points at. + expect(skipped).toBeGreaterThanOrEqual(1); + expect(fs.lstatSync(linked).isSymbolicLink()).toBe(true); + expect(fs.existsSync(path.join(target, 'sessions'))).toBe(true); + } finally { + await runtime.close(); + } + }, +); + +function hostFor(stateDir: string) { + return createTestHostEnvironment({ + env: { + ...process.env, + AGENT_DEVICE_STATE_DIR: stateDir, + AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS: '0', + AGENT_DEVICE_DAEMON_SERVER_MODE: 'http', + }, + }); +} + +function modeOf(target: string): number { + return Number(fs.lstatSync(target).mode & 0o777); +} + +/** Why a recording was not saved, from the typed reason the writer returned it in. */ +function refusalOf(result: ReturnType): Record { + expect(result.written).toBe(false); + if (result.written || !result.error) throw new Error('expected a refused recording'); + return result.error.details as Record; +} diff --git a/packages/daemon/src/server/http/daemon-runtime.ts b/packages/daemon/src/server/http/daemon-runtime.ts index 7054039ae3..130cd98184 100644 --- a/packages/daemon/src/server/http/daemon-runtime.ts +++ b/packages/daemon/src/server/http/daemon-runtime.ts @@ -84,6 +84,7 @@ import { resolveDaemonCodeSignature, } from './server-lifecycle.ts'; import { + ensureDaemonStateDir, tryAcquireDaemonRegistration, DAEMON_STARTUP_EXIT_CODES, type DaemonRegistrationOwner, @@ -207,6 +208,12 @@ async function startDaemonRuntimeOnHost( } = await import('./daemon-startup-diagnostics.ts'); const daemonPaths = resolveDaemonPaths(env.AGENT_DEVICE_STATE_DIR, { env, cwd: host.cwd }); const { baseDir, infoPath, logPath, sessionsDir } = daemonPaths; + // The daemon's own state dirs are on the chain of every recording it picks a path for, and a + // destination under a group-writable directory is refused (ADR 0016). Both are created and forced to 0700 + // here, because a state dir an older version made under umask 002 stands at 0775 and `sessions/` is + // otherwise only ever created as a side effect of a per-session mkdir. + ensureDaemonStateDir(baseDir, baseDir); + ensureDaemonStateDir(sessionsDir, baseDir); const daemonServerMode = resolveDaemonServerMode(env.AGENT_DEVICE_DAEMON_SERVER_MODE); const retainArtifacts = isEnvTruthy(env.AGENT_DEVICE_RETAIN_ARTIFACTS); // ADR 0029: a policy that cannot be read or validated stops startup; the daemon never runs diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-close-script.test.ts b/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-close-script.test.ts index 0b38fb0b83..8a6a9394f1 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-close-script.test.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-close-script.test.ts @@ -14,8 +14,10 @@ import { commitRepairScriptBeforeClose, finalizeOrdinaryCloseScript, } from '../session-close-script.ts'; +import { remoteCloseScriptDelivery } from '../../../../core/session-script-publication-capability.ts'; import { createLiveTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; import { flushSessionEventLogWrites } from '@agent-device/session-journal/session-event-log'; +import { failScriptStagingWrite } from '../../../../__tests__/support/script-staging-failure.ts'; const roots: string[] = []; @@ -91,6 +93,37 @@ test('repair close failure keeps normalized metadata and is explicitly retriable }); }); +test('a refused remote close write keeps its typed reason as the delivery failure cause', () => { + // #4584: a remote recording's close discloses a failed final write instead of failing, and the + // disclosure has to say WHICH failure it was. `state_chain_untrusted` — the daemon's own state chain + // is not private ground — is a different recovery from a full disk, and a client cannot tell them + // apart from prose. The reason comes from the write error, so it has to travel with it. + const { req, ref, sessionStore } = setup('remote-ordinary'); + sessionStore.requireCurrent(ref).scriptPublication = authoringPublication('armed', { + remote: true, + }); + const failure = new AppError('COMMAND_FAILED', 'state chain is not private ground', { + reason: 'state_chain_untrusted', + hint: 'Make the daemon own that tree.', + }); + vi.spyOn(sessionStore, 'writeSessionLog').mockReturnValue({ written: false, error: failure }); + + const { remote } = finalizeOrdinaryCloseScript({ + req, + ref, + sessionStore, + platformCloseError: undefined, + }); + + const delivered = remoteCloseScriptDelivery({ ok: true, data: {} }, remote); + if (!delivered.ok) throw new Error('a failed remote version keeps the close successful'); + expect(delivered.data?.scriptDeliveryFailure).toMatchObject({ + reason: 'script_delivery_failed', + publicationId: 'publication-0001', + cause: 'state_chain_untrusted', + }); +}); + test('ordinary publication failure retains its close action after making the error non-retriable', () => { const { req, ref, session, sessionStore } = setup('ordinary'); const failure = new AppError('COMMAND_FAILED', 'target exists', { @@ -195,10 +228,12 @@ test('#1533: an ordinary armed authoring session still publishes on bare close', test('ordinary close reports a filesystem failure of its script write instead of a quiet success', () => { const root = mkdtempForTestSync('agent-device-session-close-script-fs-'); roots.push(root); - // A regular file where the target directory must be: publishing into it fails with ENOTDIR. - const blocker = path.join(root, 'blocker'); - fs.writeFileSync(blocker, ''); - const targetPath = path.join(blocker, 'flow.ad'); + // The publication's staging write is made to fail, so the caller sees the filesystem's own failure and + // not an ancestry refusal. A directory whose mode denies this user is not used for that: mode bits do + // not bind root, so under a root caller the write would succeed and this test would be measuring the + // host's permission model instead of what close does with a failure. + const targetPath = path.join(root, 'flow.ad'); + failScriptStagingWrite(targetPath); const { req, ref, sessionStore } = setup( 'fs-failure', makeIosSession('fs-failure', { diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-close-script.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-close-script.ts index cd9407d53d..a3aa25e73f 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-close-script.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-close-script.ts @@ -109,7 +109,7 @@ export function finalizeOrdinaryCloseScript(params: { if (result.written) markCloseGeneratedPublicationDone(session, result.path); const error = !result.written && result.error ? toOrdinaryCloseSaveScriptFailure(result.error) : undefined; - const remote = remoteCloseScript(session, error !== undefined); + const remote = remoteCloseScript(session, error); return remote ? { remote } : { error }; } diff --git a/packages/host-kit/src/file.ts b/packages/host-kit/src/file.ts index fd0b251e09..7bdba1f70f 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -1,11 +1,17 @@ export { + confirmScriptDestination, + scriptAncestryReason, isAtomicPublishTemporaryPath, + lstatIfPresent, + prepareScriptDestination, publishDurableFileSync, publishFileSync, + publishScriptFileSync, + untrustedDirectoryAncestry, type DurableFilePublishMode, + type ScriptDestination, } from './internal/atomic-file.ts'; export { - lstatIfPresent, NOT_REGULAR_FILE_HINT, openVerifiedFileForAppend, openVerifiedFileForRead, diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts new file mode 100644 index 0000000000..2e8bc249fd --- /dev/null +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -0,0 +1,877 @@ +import { afterEach, expect, test, vi } from 'vitest'; +import fs from 'node:fs'; +import path from 'node:path'; +import { AppError } from '@agent-device/kernel/errors'; +import { + FOREIGN_UID, + ancestryRoot as root, + directoryWith, + expectUntrusted, + expectUntrustedReplaced, + modeOf, + publish, +} from './atomic-file-host.fixtures.ts'; +import { + confirmScriptDestination, + prepareScriptDestination, + untrustedDirectoryAncestry, + MAX_SCRIPT_PATH_LINK_HOPS, +} from './atomic-file.ts'; +import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; + +/** + * Where the rule says an entry is created, and nothing more. + * + * `prepareScriptDestination` is the call both routes make before they stage anything, so asking it is what a + * route sees: it walks, judges, and answers the directory. Every ground this suite builds already stands, so + * the creation it also owns never runs here. + */ +function judgedDirectory(destination: string): string { + return prepareScriptDestination(destination).directory; +} + +const skipOnWindows = process.platform === 'win32' ? test.skip : test; + +afterEach(() => { + vi.restoreAllMocks(); +}); + +/** The unmocked lookups, so serving an owner never wraps a previously served one. */ +const realLstatSync = fs.lstatSync.bind(fs); +const realStatSync = fs.statSync.bind(fs); + +/** + * Reports `owners` for the named paths and the real host for everything else, so the ownership rule is + * the fixture's and not the CI image's directory tree. Only the ids move: modes and inode numbers stay + * what they are on disk. Both lookups are served, because the walk `lstat`s an entry to learn whether it + * is a link and `stat`s the directory it stands in. + */ +function serveOwnership(owners: Readonly>): void { + const withUid = (stats: fs.Stats, pathname: string): fs.Stats => { + const uid = owners[pathname]; + if (uid === undefined || stats.uid === uid) return stats; + return Object.assign(Object.create(Object.getPrototypeOf(stats)), stats, { uid }) as fs.Stats; + }; + vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: never, ...rest: never[]) => + withUid(realLstatSync(pathname, ...rest), String(pathname))) as typeof fs.lstatSync); + vi.spyOn(fs, 'statSync').mockImplementation(((pathname: never, ...rest: never[]) => + withUid(realStatSync(pathname, ...rest), String(pathname))) as typeof fs.statSync); +} + +// --- a directory another user owns, or that others can write, is refused --- + +skipOnWindows('publishes to a chain only this user can write', () => { + const workflows = path.join(root(), 'workflows'); + fs.mkdirSync(workflows); + + publish(path.join(workflows, 'journey.ad')); + + expect(fs.readFileSync(path.join(workflows, 'journey.ad'), 'utf8')).toBe('context\n'); +}); + +skipOnWindows('creates the script so that only this user can read it', () => { + const workflows = path.join(root(), 'workflows'); + fs.mkdirSync(workflows); + const destination = path.join(workflows, 'journey.ad'); + + publish(destination); + + expect(modeOf(destination)).toBe(0o600); +}); + +skipOnWindows('refuses a destination under a world-writable directory', () => { + const shared = directoryWith(path.join(root(), 'shared'), 0o777); + const destination = path.join(shared, 'journey.ad'); + + expectUntrusted(() => publish(destination), 'world_writable', shared); + expect(fs.existsSync(destination)).toBe(false); +}); + +skipOnWindows('refuses a destination created inside a directory others can add entries to', () => { + const shared = directoryWith(path.join(root(), 'shared'), 0o777 | 0o1000); + + expectUntrusted(() => judgedDirectory(path.join(shared, 'journey.ad')), 'shared_parent', shared); + expect(fs.existsSync(path.join(shared, 'journey.ad'))).toBe(false); +}); + +skipOnWindows('refuses a destination under a group-writable shared directory', () => { + const team = directoryWith(path.join(root(), 'team'), 0o775); + const sub = path.join(team, 'sub'); + fs.mkdirSync(sub); + + expectUntrusted(() => publish(path.join(sub, 'journey.ad')), 'shared_group_writable', team); + expect(fs.readdirSync(sub)).toEqual([]); +}); + +// --- ownership decides, not the mode alone --- + +skipOnWindows('refuses a directory another user owns, whatever the mode', () => { + const work = directoryWith(path.join(root(), 'foreign'), 0o755); + serveOwnership({ [work]: FOREIGN_UID }); + + expectUntrusted(() => judgedDirectory(path.join(work, 'journey.ad')), 'foreign_owned', work); +}); + +skipOnWindows( + 'refuses a sticky directory another user owns, since both bits shield others from them', + () => { + // The reviewer's case: a teammate runs `chmod 1777` on a directory of THEIRS. The sticky bit keeps me + // from deleting their entries; it does nothing to stop them replacing mine. + const team = directoryWith(path.join(root(), 'team'), 0o1777); + serveOwnership({ [team]: FOREIGN_UID }); + const work = path.join(team, 'work'); + fs.mkdirSync(work); + + expectUntrusted(() => judgedDirectory(path.join(work, 'journey.ad')), 'foreign_owned', team); + }, +); + +skipOnWindows( + 'refuses a recordings directory another local user created first in a sticky /tmp', + () => { + // `mkdir -p /tmp/recordings` is the shape: `/tmp` is sticky so nobody can touch anyone else's entry, + // and whoever creates that directory first owns it. The owner can rename it aside and put their own in + // place, whatever its mode says, so the destination has to be refused. + const systemTmp = directoryWith(path.join(root(), 'tmp'), 0o1777); + const recordings = path.join(systemTmp, 'recordings'); + fs.mkdirSync(recordings); + fs.chmodSync(recordings, 0o755); + serveOwnership({ [systemTmp]: 0, [recordings]: FOREIGN_UID }); + + expectUntrusted( + () => judgedDirectory(path.join(recordings, 'journey.ad')), + 'foreign_owned', + recordings, + ); + }, +); + +skipOnWindows('refuses a link standing in a private-mode directory another user owns', () => { + // The third input the reviewer names. `/teammate` is theirs at 0755, `link` is a component of my + // path, and the target is a directory of mine nothing could object to. Nothing about the target chain + // looks wrong: the exposure is that the OWNER of the directory the link stands in can rename that + // component and leave one of their own there, pointing wherever they like. + const directory = root(); + const teammate = directoryWith(path.join(directory, 'teammate'), 0o755); + serveOwnership({ [teammate]: FOREIGN_UID }); + const mine = directoryWith(path.join(directory, 'mine'), 0o700); + fs.symlinkSync(mine, path.join(teammate, 'link')); + + expectUntrusted( + () => judgedDirectory(path.join(teammate, 'link', 'journey.ad')), + 'foreign_owned', + teammate, + ); + expect(fs.readdirSync(mine)).toEqual([]); +}); + +skipOnWindows('refuses a private link standing on shared ground two levels up', () => { + // `/shared` is 0777 and not sticky, `/shared/mine` is mine at 0700, and `mine/rec` is a + // link to my private directory. The final chain is all mine, and the link stands in ground only I can + // write, so neither the link rule nor the resolved-final-chain rule sees anything wrong. What they miss + // is that another local user owns the ground `mine` and `rec` stand on: they rename `mine` aside and + // put their own there, with a `rec` of their choosing. + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const mine = directoryWith(path.join(shared, 'mine'), 0o700); + const privateWork = directoryWith(path.join(directory, 'private'), 0o700); + fs.symlinkSync(privateWork, path.join(mine, 'rec')); + + expectUntrusted( + () => judgedDirectory(path.join(mine, 'rec', 'journey.ad')), + 'world_writable', + shared, + ); + expect(fs.readdirSync(privateWork)).toEqual([]); +}); + +skipOnWindows('refuses a chain that leaves a shared directory through an intermediate link', () => { + // `~/rec -> /srv/team/relay`, and `relay` is a link back into a directory of mine. Every directory the + // final chain names is trusted; the walk still passes through `/srv/team`, which the team can write, + // and its owner — or any teammate — can swap `relay` for a target of their own. + const directory = root(); + const home = path.join(directory, 'home'); + fs.mkdirSync(home); + const srv = path.join(directory, 'srv'); + const team = path.join(srv, 'team'); + fs.mkdirSync(team, { recursive: true }); + fs.chmodSync(team, 0o777); + const chosen = directoryWith(path.join(directory, 'chosen'), 0o700); + fs.symlinkSync(chosen, path.join(team, 'relay')); + fs.symlinkSync(path.join(team, 'relay'), path.join(home, 'rec')); + + expectUntrusted( + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), + 'world_writable', + team, + ); + expect(fs.readdirSync(chosen)).toEqual([]); +}); + +skipOnWindows('judges the directory a .. steps back into', () => { + // `/private/link` points at `/elsewhere/dir`, and the caller spells `/link/../x`. + // The kernel walks `link` into its target and steps back from THERE, so the entry is created in + // `/elsewhere`, not in `/private`. Normalizing the spelling first would answer + // `/private/x` and judge the wrong directory: `` is open to others, `` is not. + const directory = root(); + const privateHome = directoryWith(path.join(directory, 'private'), 0o700); + const elsewhere = directoryWith(path.join(directory, 'elsewhere'), 0o777); + const dir = path.join(elsewhere, 'dir'); + fs.mkdirSync(dir); + fs.symlinkSync(dir, path.join(privateHome, 'link')); + + expectUntrusted( + () => judgedDirectory(`${privateHome}/link/../x/journey.ad`), + 'world_writable', + elsewhere, + ); + expect(fs.readdirSync(dir)).toEqual([]); +}); + +skipOnWindows('refuses the ground under a link that leads into a shared directory', () => { + // `/shared` is 0777 and not sticky, `/home/rec` is a link spelled `shared/mine/relay/subdir` + // whose `relay` is a link back into a private directory. Nothing at the destination looks wrong: the + // final chain is `/shared/mine/chosen/subdir`, and every one of those is private-looking. What + // the walk sees is that getting there crossed `/shared`, where any other local user can rename + // `mine` aside and put their own `relay` under it. + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const mine = directoryWith(path.join(shared, 'mine'), 0o700); + const chosen = directoryWith(path.join(directory, 'chosen'), 0o700); + fs.symlinkSync(chosen, path.join(mine, 'relay')); + const home = directoryWith(path.join(directory, 'home'), 0o700); + fs.symlinkSync(path.join(shared, 'mine', 'relay', 'subdir'), path.join(home, 'rec')); + + expectUntrusted( + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), + 'world_writable', + shared, + ); + expect(fs.readdirSync(chosen)).toEqual([]); +}); + +skipOnWindows( + 'refuses a link whose target is spelled relative to the directory that holds it', + () => { + // `ln -s ../team/rec rec` in a private home is the ordinary way a link gets written. The target is + // resolved from the directory that HOLDS the link, so the walk leaves the home, crosses `shared` at + // 0777, and arrives at the destination. Every directory of the answer is private-looking; the ground + // crossed on the way is not. + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const mine = directoryWith(path.join(shared, 'mine'), 0o700); + const chosen = directoryWith(path.join(directory, 'chosen'), 0o700); + fs.symlinkSync(chosen, path.join(mine, 'relay')); + const sub = path.join(chosen, 'sub'); + fs.mkdirSync(sub); + const home = directoryWith(path.join(directory, 'home'), 0o700); + fs.symlinkSync(path.join('..', 'shared', 'mine', 'relay', 'sub'), path.join(home, 'rec')); + + expectUntrusted( + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), + 'world_writable', + shared, + ); + expect(fs.readdirSync(sub)).toEqual([]); + }, +); + +skipOnWindows( + 'stages the temp file inside the directory the walk judged, not the spelled parent', + () => { + // `work -> priv/x`, `priv/y` is private and `home/y` is open to others. The kernel walks `work` into its + // target and steps back from THERE, so the entry is created in `priv/y`. `path.dirname` of the same + // spelling answers `home/y`, so a publisher that stages beside the spelled parent writes its temp file + // into ground the rule never judged — where anyone can list it and put their own bytes behind that name + // before the rename. The staging directory has to be the walk's answer. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const sharedY = directoryWith(path.join(home, 'y'), 0o777); + const priv = directoryWith(path.join(directory, 'priv'), 0o700); + const privX = path.join(priv, 'x'); + fs.mkdirSync(privX); + const privY = directoryWith(path.join(priv, 'y'), 0o700); + fs.symlinkSync(privX, path.join(home, 'work')); + const destination = `${home}/work/../y/journey.ad`; + + const staged: string[] = []; + const realWriteFileSync = fs.writeFileSync; + vi.spyOn(fs, 'writeFileSync').mockImplementation(((file: unknown, ...rest: unknown[]) => { + if (typeof file === 'string') staged.push(path.dirname(file)); + return (realWriteFileSync as (...args: unknown[]) => unknown)(file, ...rest); + }) as typeof fs.writeFileSync); + publish(destination); + + expect(staged).toEqual([privY]); + expect(fs.readFileSync(path.join(privY, 'journey.ad'), 'utf8')).toBe('context\n'); + expect(fs.readdirSync(sharedY)).toEqual([]); + }, +); + +skipOnWindows( + 'judges every step from lstat alone, however many routes lead back to one directory', + () => { + // `a` and `b` are two names for ONE directory, and the spelling enters through `a`, steps back with `..` + // and enters again through `b`, so the walk crosses `sub` twice and finishes below it. Where it ends is + // the assertion that both routes were really taken: a walk that gave up on the second name would answer + // `home` here instead. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const sub = directoryWith(path.join(home, 'sub'), 0o700); + const below = path.join(sub, 'below'); + fs.mkdirSync(below); + fs.symlinkSync(sub, path.join(home, 'a')); + fs.symlinkSync(sub, path.join(home, 'b')); + const lstatPaths: string[] = []; + const realLstatSync = fs.lstatSync; + vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + lstatPaths.push(String(pathname)); + return (realLstatSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.lstatSync); + const statPaths: string[] = []; + const realStatSync = fs.statSync; + vi.spyOn(fs, 'statSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + statPaths.push(String(pathname)); + return (realStatSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.statSync); + + expect(judgedDirectory(`${home}/a/../b/below/journey.ad`)).toBe(below); + + // Every step is an `lstat` of the ENTRY. `stat` would resolve the same name a second time and answer + // whatever stands there by then, which is the window the walk exists to close. + expect(statPaths).toEqual([]); + // Both aliases were followed, and the directory they name was judged on each route into it. + expect(lstatPaths).toContain(path.join(home, 'a')); + expect(lstatPaths).toContain(path.join(home, 'b')); + expect(lstatPaths.filter((read) => read === sub)).toHaveLength(2); + }, +); + +skipOnWindows( + 'refuses a destination that is not absolute, before judging or creating anything', + () => { + // Both routes hand host-kit an absolute path, so a relative name is refused at the entry rather than + // emulated. Walking one would mean walking the process's working directory, whose NAME Node answers + // from the first query after the last `chdir`: move that directory and a walk of the remembered + // spelling judges the directory standing at the old path while the kernel resolves the name in the + // moved one. Refusing at the entry keeps the stale-name question out of the rule entirely. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const previous = process.cwd(); + try { + process.chdir(home); + + expectUntrusted(() => publish('journey.ad'), 'relative_destination', '.'); + expectUntrusted(() => judgedDirectory('work/journey.ad'), 'relative_destination', 'work'); + // Refused at the entry, so nothing below the working directory was created either. + expect(fs.readdirSync(home)).toEqual([]); + } finally { + process.chdir(previous); + } + }, +); + +skipOnWindows('refuses a relative target that lands in ground others can write', () => { + // The target names a plain name, and the directory it names is open to others. Spelling that directory + // out is refused, so arriving at it through a link has to answer the same way. + const home = directoryWith(path.join(root(), 'home'), 0o700); + const open = directoryWith(path.join(home, 'open'), 0o777); + fs.symlinkSync('open', path.join(home, 'rel')); + + expectUntrusted( + () => judgedDirectory(path.join(home, 'rel', 'journey.ad')), + 'world_writable', + open, + ); + expect(fs.readdirSync(open)).toEqual([]); +}); + +skipOnWindows('applies a .. inside a target to the directory the walk reached', () => { + // `rel -> priv/../x`. Folded as text, that is `home/x`, which is private and would be accepted. The + // kernel steps into `priv`, which is itself a link into `shared/inside`, and applies `..` THERE: the + // walk is standing in `shared`, and `x` is created in it. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const inside = path.join(shared, 'inside'); + fs.mkdirSync(inside); + fs.symlinkSync(inside, path.join(home, 'priv')); + // Spelled by hand: `path.join` would fold the `..` away before the link ever existed. + fs.symlinkSync('priv/../x', path.join(home, 'rel')); + + expectUntrusted( + () => judgedDirectory(path.join(home, 'rel', 'journey.ad')), + 'world_writable', + shared, + ); + expect(fs.readdirSync(shared)).toEqual(['inside']); +}); + +skipOnWindows('follows a relative target that stays inside ground only this user can write', () => { + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const real = directoryWith(path.join(directory, 'outside'), 0o700); + fs.symlinkSync(path.join('..', 'outside'), path.join(home, 'rel')); + + publish(path.join(home, 'rel', 'journey.ad')); + + expect(fs.readFileSync(path.join(real, 'journey.ad'), 'utf8')).toBe('context\n'); +}); + +skipOnWindows('refuses the spelled spelling of a link the walk also follows', () => { + // The same target reached two ways has to answer the same way: spelling the shared directory out is + // refused, so arriving at it through a link cannot be accepted. + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const work = path.join(home, 'work'); + fs.mkdirSync(work); + fs.symlinkSync(shared, path.join(home, 'rec')); + + expectUntrusted( + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), + 'world_writable', + shared, + ); + expectUntrusted(() => judgedDirectory(path.join(shared, 'journey.ad')), 'world_writable', shared); +}); + +skipOnWindows('applies .. to the directory the walk is in, not to the spelling', () => { + // `home/work -> priv/x`, `priv/y` is open to others, `home/y` is private. A lexical simplification of + // the spelling answers `home/y`, which is safe, so it accepts a write that lands in `priv/y`, where any + // local user can take the file. The kernel steps into the link and steps back from its TARGET. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const priv = directoryWith(path.join(directory, 'priv'), 0o700); + const privX = path.join(priv, 'x'); + fs.mkdirSync(privX); + const privY = directoryWith(path.join(priv, 'y'), 0o777); + fs.mkdirSync(path.join(home, 'y')); + fs.symlinkSync(privX, path.join(home, 'work')); + + expectUntrusted(() => judgedDirectory(`${home}/work/../y/journey.ad`), 'world_writable', privY); + expect(fs.readdirSync(privY)).toEqual([]); +}); + +skipOnWindows('refuses a link whose target stands in ground another local user owns', () => { + // `~/rec -> /tmp/relay -> ~/chosen`, and `relay` is another user's file in a sticky shared + // directory. Sticky or not, they can unlink it and put one of their own there, so the second hop is + // theirs to choose. The judgment the expanded hop used to skip is the one on the link itself. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const chosen = directoryWith(path.join(directory, 'chosen'), 0o700); + const tmp = directoryWith(path.join(directory, 'tmp'), 0o1777); + const relay = path.join(tmp, 'relay'); + fs.symlinkSync(chosen, relay); + serveOwnership({ [tmp]: 0, [relay]: FOREIGN_UID }); + fs.symlinkSync(relay, path.join(home, 'rec')); + + expectUntrusted( + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), + 'planted_link', + relay, + ); + expect(fs.readdirSync(chosen)).toEqual([]); +}); + +skipOnWindows('follows a link whatever mode it carries, judging the directory it lands in', () => { + // A link's own mode means nothing for access: the kernel reads its target. An alias at 0777 leading to + // a directory only this user can write is therefore safe, and the refusal has to come from the + // directory, not from the link's bits. + const directory = root(); + const real = directoryWith(path.join(directory, 'real'), 0o700); + const alias = path.join(directory, 'current'); + fs.symlinkSync(real, alias); + // `lchmod` on a link is what a mode-carrying alias looks like; where the host reports one mode for all + // links, as Linux does, the walk has to be moved by the directory it lands in either way. + try { + fs.lchmodSync(alias, 0o777); + } catch { + /* this host gives every link the same mode */ + } + + publish(path.join(alias, 'journey.ad')); + + expect(fs.readFileSync(path.join(real, 'journey.ad'), 'utf8')).toBe('context\n'); +}); + +skipOnWindows('refuses a link loop instead of trusting where the walk ran out', () => { + const directory = root(); + const work = directoryWith(path.join(directory, 'work'), 0o700); + const loop = path.join(work, 'loop'); + fs.symlinkSync(loop, loop); + + expectUntrusted(() => judgedDirectory(path.join(loop, 'journey.ad')), 'link_loop_exceeded', loop); + expect(fs.readdirSync(work)).toEqual(['loop']); +}); + +skipOnWindows('follows thirty link hops, and refuses the thirty-first', () => { + // Both counts are written out rather than derived from MAX_SCRIPT_PATH_LINK_HOPS, and the reason is + // that a derived test cannot fail: a constant lowered from 30 to 29 rebuilds its own inputs and stays + // green while every chain of 30 links that used to publish now refuses. The limit sits below what the + // kernels apply themselves (macOS 32, Linux 40), so 30 is a number this rule owns — and the last line + // is what ties the number written above to the one the walk enforces. + const directory = root(); + const work = directoryWith(path.join(directory, 'work'), 0o700); + const real = directoryWith(path.join(directory, 'real'), 0o700); + // `link0 -> link1 -> ... -> `: the walk expands `count` links to reach the destination. + const chain = (count: number): string => { + let next = real; + for (let hop = count - 1; hop >= 0; hop -= 1) { + const link = path.join(work, `link${hop}`); + fs.rmSync(link, { force: true }); + fs.symlinkSync(next, link); + next = link; + } + return next; + }; + + publish(path.join(chain(30), 'journey.ad')); + expect(fs.existsSync(path.join(real, 'journey.ad'))).toBe(true); + fs.rmSync(path.join(real, 'journey.ad'), { force: true }); + + expectUntrusted( + () => judgedDirectory(path.join(chain(31), 'journey.ad')), + 'link_loop_exceeded', + path.join(work, 'link30'), + ); + expect(fs.readdirSync(real)).toEqual([]); + expect(MAX_SCRIPT_PATH_LINK_HOPS).toBe(30); +}); + +skipOnWindows('refuses a path component that cannot carry a publish', () => { + const directory = root(); + const work = directoryWith(path.join(directory, 'work'), 0o700); + const blocker = path.join(work, 'blocker'); + fs.writeFileSync(blocker, 'not a directory\n'); + + expectUntrusted( + () => judgedDirectory(path.join(blocker, 'journey.ad')), + 'not_a_directory', + blocker, + ); +}); + +// --- a group-writable directory is refused, whoever owns the group (ADR 0016) --- + +skipOnWindows('refuses a group-writable 0775 directory with the hint to close the group', () => { + // The stock shape on a shared Linux checkout: the project directory is 0775 and its group is this + // user's own. Membership of that group cannot be proven from the host's account files, so the rule + // refuses on the mode alone and tells the caller how to make the destination acceptable. + const home = directoryWith(path.join(root(), 'home'), 0o775); + let hint = ''; + try { + publish(path.join(home, 'journey.ad')); + } catch (error) { + hint = String((error as AppError).details?.hint); + } + + expectUntrusted(() => publish(path.join(home, 'journey.ad')), 'shared_group_writable', home); + expect(hint).toContain(`chmod g-w ${home}`); + expect(fs.readdirSync(home)).toEqual([]); +}); + +skipOnWindows('refuses a setgid group-writable directory on the same mode', () => { + // setgid changes who inherits the group, not who belongs to it, so it changes nothing here. + const home = directoryWith(path.join(root(), 'home'), 0o2775); + + expectUntrusted(() => publish(path.join(home, 'journey.ad')), 'shared_group_writable', home); +}); + +// --- a link is judged as the link it is, and its target is judged too --- + +skipOnWindows('follows a symbolic link inside a directory only this user can write', () => { + const directory = root(); + const real = path.join(directory, 'real'); + fs.mkdirSync(real); + fs.symlinkSync(real, path.join(directory, 'link')); + + publish(path.join(directory, 'link', 'journey.ad')); + + expect(fs.existsSync(path.join(real, 'journey.ad'))).toBe(true); +}); + +skipOnWindows('refuses a link planted in a directory others can add entries to', () => { + // The shared ground is refused where the walk enters it, one step before the link inside it: that + // directory is itself the exposure, since anyone can rename `work` aside as well as plant it. + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const attacker = path.join(directory, 'attacker'); + fs.mkdirSync(attacker); + fs.symlinkSync(attacker, path.join(shared, 'work')); + + expectUntrusted( + () => judgedDirectory(path.join(shared, 'work', 'journey.ad')), + 'world_writable', + shared, + ); + expect(fs.readdirSync(attacker)).toEqual([]); +}); + +skipOnWindows('refuses a private link whose target chain is a shared directory', () => { + // `~/rec -> /srv/team/rec`, with `/srv/team` open to the team. The link itself is this user's own in + // their own home, so nothing about it looks wrong; only the resolved chain shows the destination + // would sit in ground the whole team can write. + const directory = root(); + const home = path.join(directory, 'home'); + fs.mkdirSync(home); + const srv = path.join(directory, 'srv'); + const team = path.join(srv, 'team'); + fs.mkdirSync(team, { recursive: true }); + fs.chmodSync(team, 0o777); + const rec = path.join(team, 'rec'); + fs.mkdirSync(rec); + fs.symlinkSync(rec, path.join(home, 'rec')); + + expectUntrusted( + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), + 'world_writable', + team, + ); +}); + +skipOnWindows('refuses a symbolic link whose target is a directory others can write', () => { + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const privateWork = path.join(shared, 'private'); + fs.mkdirSync(privateWork); + fs.symlinkSync(privateWork, path.join(directory, 'link')); + + expectUntrusted( + () => judgedDirectory(path.join(directory, 'link', 'journey.ad')), + 'world_writable', + shared, + ); +}); + +skipOnWindows( + 'refuses a symbolic link another local user owns in a sticky shared directory', + () => { + // The link's OWNER is the whole question, so it is the fixture's: root holds the sticky directory and + // somebody else owns the link. Moving only the caller's uid would decide the test by the accident of + // who runs the suite, and would say nothing when the suite runs as root. + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o1777); + const attacker = path.join(directory, 'attacker'); + fs.mkdirSync(attacker); + const link = path.join(shared, 'work'); + fs.symlinkSync(attacker, link); + serveOwnership({ [shared]: 0, [link]: FOREIGN_UID }); + + expectUntrusted( + () => judgedDirectory(path.join(shared, 'work', 'journey.ad')), + 'planted_link', + link, + ); + expect(fs.readdirSync(attacker)).toEqual([]); + }, +); + +skipOnWindows('keeps working through a root-owned alias whose target is sticky', () => { + // The `/tmp` shape with every ownership the real one has: the alias stands in a sticky directory ANY + // local user may add names in, and both that directory and the link belong to root. An alias owned by + // whoever runs the suite would still pass a rule that refused EVERY root-owned link, which is the + // macOS `/tmp` to `/private/tmp` shape this case exists to keep working. + const directory = root(); + const shared = directoryWith(path.join(directory, 'tmp'), 0o1777); + const target = path.join(directory, 'private-tmp'); + fs.mkdirSync(target); + fs.chmodSync(target, 0o1777); + const alias = path.join(shared, 'alias'); + fs.symlinkSync(target, alias); + const work = path.join(alias, 'work'); + fs.mkdirSync(work); + fs.chmodSync(work, 0o700); + serveOwnership({ [shared]: 0, [alias]: 0, [target]: 0, [work]: 0 }); + + publish(path.join(work, 'journey.ad')); + + expect(fs.readFileSync(path.join(target, 'work', 'journey.ad'), 'utf8')).toBe('context\n'); +}); + +skipOnWindows('publishes under the host root-owned system temporary directory', () => { + // macOS reaches `/private/tmp` through `/tmp`, Linux mounts `/tmp` directly. Both are sticky and + // root-owned, and the script is created in a private directory under it, so neither spelling may + // stop the publish. + const work = fs.mkdtempSync('/tmp/agent-device-ancestry-'); + fs.chmodSync(work, 0o700); + const destination = path.join(work, 'journey.ad'); + try { + publish(destination); + expect(fs.readFileSync(destination, 'utf8')).toBe('context\n'); + } finally { + fs.rmSync(work, { recursive: true, force: true }); + } +}); + +skipOnWindows('publishes to a path spelled through an alias of the directory that holds it', () => { + // The caller passes a path whose parent is a link, in a chain only this user can write. The alias + // leads somewhere legal, so the publish follows it instead of refusing it. + const directory = root(); + const real = path.join(directory, 'workflows'); + fs.mkdirSync(real); + fs.symlinkSync(real, path.join(directory, 'current')); + const destination = path.join(directory, 'current', 'journey.ad'); + + publish(destination); + + expect(fs.readFileSync(path.join(real, 'journey.ad'), 'utf8')).toBe('context\n'); +}); + +skipOnWindows('publishes to a scratch path exactly as the host spelled it', () => { + // The scratch root keeps the host's own spelling of its temporary directory: an alias on macOS, where + // `/var` stands for `/private/var`, and no alias at all on Linux. Neither spelling may stop a publish, + // so this asserts the outcome rather than what the host happens to name. + const directory = mkdtempForTestSync('host-kit-ancestry-spelled-'); + const destination = path.join(directory, 'journey.ad'); + + publish(destination); + + expect(fs.readFileSync(destination, 'utf8')).toBe('context\n'); +}); + +// --- the destination directory swapped out while the file was staged --- + +// Only a caller that holds an answer from an earlier walk confirms it: the remote client does, because a +// download runs between the walk that judged the directory and the rename that creates the entry. The local +// publisher asks for no comparison of its own - the ownership rule is what excludes anyone who could make +// that swap - so these two cover the one comparison this rule keeps. + +skipOnWindows('refuses a parent replaced by name while the file was staged', () => { + const directory = root(); + const staged = path.join(directory, 'work'); + fs.mkdirSync(staged); + const destination = path.join(staged, 'journey.ad'); + const prepared = prepareScriptDestination(destination); + // The replacement is a link to another real directory. Removing the directory and creating the same name + // again is not enough to make the two differ: a filesystem may hand back the inode it just freed, and the + // identity would match by luck. + const elsewhere = path.join(directory, 'elsewhere'); + fs.mkdirSync(elsewhere); + fs.rmSync(staged, { recursive: true }); + fs.symlinkSync(elsewhere, staged); + + // The refusal names the directory the entry would really have been created in, which is where the link + // leads. The spelled name is a pointer, not a place. + expectUntrustedReplaced(() => confirmScriptDestination(destination, prepared), elsewhere); + expect(fs.existsSync(path.join(elsewhere, 'journey.ad'))).toBe(false); +}); + +skipOnWindows( + 'confirms the directory an earlier answer named, and reports where to create the entry', + () => { + const directory = root(); + const staged = path.join(directory, 'work'); + fs.mkdirSync(staged); + const destination = path.join(staged, 'journey.ad'); + const prepared = prepareScriptDestination(destination); + + expect(confirmScriptDestination(destination, prepared)).toBe(staged); + }, +); + +// --- a step swapped out while the walk is still running --- + +skipOnWindows( + 'identifies an entry by its bigint inode, so two large inodes do not collapse', + () => { + // Directory identities are compared for equality by `confirmScriptDestination`, so they are read as + // BIGINT. A numeric `ino` cannot hold every inode a filesystem hands out: 2^53 + 1 and 2^53 answer the + // same Number, and a swap between the two would then look like the same directory. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const work = path.join(home, 'work'); + fs.mkdirSync(work); + const LOW = 2n ** 53n; + const realLstatSync = fs.lstatSync; + let look = 0; + vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: unknown, options?: unknown) => { + const stats = (realLstatSync as (...args: unknown[]) => unknown)( + pathname, + options, + ) as fs.Stats; + if (String(pathname) !== work) return stats; + // Two distinct entries, one per look: the inode the walk answers, then the one the name holds when + // the staged version is confirmed. + const ino = look++ === 0 ? LOW : LOW + 1n; + const bigint = (options as { bigint?: boolean } | undefined)?.bigint === true; + return Object.assign(Object.create(Object.getPrototypeOf(stats)), stats, { + ino: bigint ? ino : Number(ino), + }); + }) as typeof fs.lstatSync); + + // A numeric read would answer Number(2^53 + 1n) === Number(2^53n), and the swap would pass. + expect(Number(LOW + 1n)).toBe(Number(LOW)); + const destination = path.join(work, 'journey.ad'); + const prepared = prepareScriptDestination(destination); + expectUntrustedReplaced(() => confirmScriptDestination(destination, prepared), work); + }, +); + +// --- the same rule, asked of a directory a caller is about to CHANGE (#4584) --- +// +// `untrustedDirectoryAncestry` is the walk above, over a directory instead of over a file about to be +// written: the daemon's state repair asks it before it forces a single mode. It has to be THIS rule and not a +// copy of it, so what it answers is pinned here, where the rule lives. + +skipOnWindows('the standing-on judgment accepts a chain only this user can move', () => { + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const base = path.join(home, 'agent-device'); + fs.mkdirSync(base); + + expect(untrustedDirectoryAncestry(base)).toBeUndefined(); + // The directory itself was stood on, and asking created nothing. + expect(fs.readdirSync(home)).toEqual(['agent-device']); +}); + +skipOnWindows('the standing-on judgment names an ancestor another user can write', () => { + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const base = path.join(shared, 'agent-device'); + fs.mkdirSync(base); + + expect(untrustedDirectoryAncestry(base)).toEqual({ + ancestor: shared, + exposure: 'world_writable', + }); +}); + +skipOnWindows('the standing-on judgment passes a sticky ancestor through, as the walk does', () => { + // The one mode exception this rule carries, and the reason it cannot be restated more strictly elsewhere: + // the sticky bit stops anyone but an entry's owner or root from renaming that entry, which is the swap the + // judgment exists to rule out. + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o1777); + const base = path.join(shared, 'agent-device'); + fs.mkdirSync(base); + + expect(untrustedDirectoryAncestry(base)).toBeUndefined(); +}); + +skipOnWindows('the standing-on judgment refuses a chain it cannot resolve', () => { + // An absent name above the directory means the walk never reached it, so there is no judgment to report: + // the answer names the last directory it did stand on and says the rest has nowhere to be resolved from. + // The destination rule refuses that shape; so does this, instead of answering "trusted" about ground it + // never saw. A `..` behind the absent name is the same stop with a different word (`unresolvable_parent`), + // and the state-repair suite pins that spelling where the caller decides what to do with it. + const directory = root(); + const base = path.join(directory, 'missing', 'agent-device'); + + expect(untrustedDirectoryAncestry(base)).toEqual({ + ancestor: directory, + exposure: 'unreachable_parent', + }); +}); + +skipOnWindows('the standing-on judgment refuses a chain a `..` cannot resolve either', () => { + // Spelled without `path.join`, which would fold the `..` away: this is the shape where the name the walk + // stops at is absent AND a step back is queued behind it, so creating cannot finish the resolution. + const directory = root(); + const base = `${directory}/missing/../agent-device`; + + expect(untrustedDirectoryAncestry(base)).toEqual({ + ancestor: directory, + exposure: 'unresolvable_parent', + }); +}); diff --git a/packages/host-kit/src/internal/atomic-file-decisions.test.ts b/packages/host-kit/src/internal/atomic-file-decisions.test.ts new file mode 100644 index 0000000000..374674b352 --- /dev/null +++ b/packages/host-kit/src/internal/atomic-file-decisions.test.ts @@ -0,0 +1,119 @@ +// The three decisions the destination-ancestry rule makes about ground it has already found: whether a +// directory is safe to publish inside, which link on the path belongs to somebody else, and where another +// local user could claim the entry. Each is a judgment over the fields of one `lstat`, so they are judged +// here on their values rather than through a filesystem. + +import { expect, test } from 'vitest'; +import { + othersCreateEntriesIn, + untrustedAncestryExposure, + untrustedLinkExposure, + type DirectoryAuthority, +} from './atomic-file.ts'; + +const currentUid = process.getuid?.() ?? -1; + +// --- what makes one directory unsafe to publish inside --- + +const OWN = { uid: currentUid, mode: 0o755 }; +const TRUST = { uid: currentUid }; + +function directoryOf(overrides: Partial): DirectoryAuthority { + return { ...OWN, ...overrides }; +} + +test('refuses a directory another user owns, whatever its mode', () => { + expect(untrustedAncestryExposure(directoryOf({ uid: 65534, mode: 0o700 }), TRUST)).toBe( + 'foreign_owned', + ); + expect(untrustedAncestryExposure(directoryOf({ uid: 65534, mode: 0o755 }), TRUST)).toBe( + 'foreign_owned', + ); +}); + +test('refuses a directory that is world-writable', () => { + expect(untrustedAncestryExposure(directoryOf({ mode: 0o777 }), TRUST)).toBe('world_writable'); +}); + +test('refuses a directory that is group-writable, whoever owns the group', () => { + // ADR 0016 carries no private-group exception: proving a group holds no other user means reading the + // host's account files, which cannot be settled on a host whose name service answers membership from + // somewhere else. The mode alone decides, which is why the rule does not read a `gid` at all. + expect(untrustedAncestryExposure(directoryOf({ mode: 0o775 }), TRUST)).toBe( + 'shared_group_writable', + ); + expect(untrustedAncestryExposure(directoryOf({ uid: 0, mode: 0o2770 }), TRUST)).toBe( + 'shared_group_writable', + ); +}); + +test('accepts a root-owned directory and a directory this user owns', () => { + expect(untrustedAncestryExposure(directoryOf({ uid: 0 }), TRUST)).toBeUndefined(); + expect(untrustedAncestryExposure(directoryOf({}), TRUST)).toBeUndefined(); +}); + +test('accepts a sticky directory this user or root owns for passing through', () => { + expect(untrustedAncestryExposure(directoryOf({ uid: 0, mode: 0o1777 }), TRUST)).toBeUndefined(); + expect(untrustedAncestryExposure(directoryOf({ mode: 0o1777 }), TRUST)).toBeUndefined(); +}); + +test('refuses a sticky directory another user owns, since both bits shield others FROM that owner', () => { + expect(untrustedAncestryExposure(directoryOf({ uid: 65534, mode: 0o1777 }), TRUST)).toBe( + 'foreign_owned', + ); + expect(untrustedAncestryExposure(directoryOf({ uid: 65534, mode: 0o2775 }), TRUST)).toBe( + 'foreign_owned', + ); +}); + +// --- untrustedLinkExposure: which link on the path belongs to somebody else --- + +test('accepts a link in a directory only this user or root can add entries to', () => { + const link = { uid: currentUid }; + expect(untrustedLinkExposure(link, directoryOf({ mode: 0o755 }), TRUST)).toBeUndefined(); + expect(untrustedLinkExposure(link, directoryOf({ uid: 0, mode: 0o755 }), TRUST)).toBeUndefined(); +}); + +test('refuses a link in a group-writable directory, which is ground others can write', () => { + expect(untrustedLinkExposure({ uid: currentUid }, directoryOf({ mode: 0o775 }), TRUST)).toBe( + 'planted_link', + ); +}); + +test('refuses a link in a shared directory unless the sticky bit and its owner hold it in place', () => { + expect(untrustedLinkExposure({ uid: currentUid }, directoryOf({ mode: 0o777 }), TRUST)).toBe( + 'planted_link', + ); + expect(untrustedLinkExposure({ uid: 65534 }, directoryOf({ mode: 0o1777 }), TRUST)).toBe( + 'planted_link', + ); +}); + +test('accepts a link this user or root owns in a sticky shared directory', () => { + const sticky = directoryOf({ mode: 0o1777 }); + expect(untrustedLinkExposure({ uid: currentUid }, sticky, TRUST)).toBeUndefined(); + expect(untrustedLinkExposure({ uid: 0 }, sticky, TRUST)).toBeUndefined(); +}); + +// --- othersCreateEntriesIn: where another local user could claim the entry --- + +test('names a directory others can add entries in, sticky bit or no sticky bit', () => { + expect(othersCreateEntriesIn(directoryOf({ mode: 0o777 }), TRUST)).toBe(true); + expect(othersCreateEntriesIn(directoryOf({ mode: 0o1777 }), TRUST)).toBe(true); + expect(othersCreateEntriesIn(directoryOf({ mode: 0o775 }), TRUST)).toBe(true); +}); + +test('names no directory that keeps its contents closed to the group', () => { + expect(othersCreateEntriesIn(directoryOf({ mode: 0o755 }), TRUST)).toBe(false); + expect(othersCreateEntriesIn(directoryOf({ mode: 0o1755 }), TRUST)).toBe(false); +}); + +test('names a directory another user owns, whatever its mode', () => { + expect(othersCreateEntriesIn(directoryOf({ uid: 65534, mode: 0o755 }), TRUST)).toBe(true); + expect(othersCreateEntriesIn(directoryOf({ uid: 65534, mode: 0o1777 }), TRUST)).toBe(true); +}); + +test('names no directory this user or root owns that others cannot write', () => { + expect(othersCreateEntriesIn(directoryOf({ uid: 0, mode: 0o755 }), TRUST)).toBe(false); + expect(othersCreateEntriesIn(directoryOf({ uid: 0, mode: 0o1777 }), TRUST)).toBe(true); +}); diff --git a/packages/host-kit/src/internal/atomic-file-durable.test.ts b/packages/host-kit/src/internal/atomic-file-durable.test.ts index cde045fb2c..be372c751c 100644 --- a/packages/host-kit/src/internal/atomic-file-durable.test.ts +++ b/packages/host-kit/src/internal/atomic-file-durable.test.ts @@ -109,6 +109,51 @@ test('preserves a file fsync error when descriptor cleanup also fails', () => { expect(temporaryPaths(root, destination)).toEqual([]); }); +test('recognizes a temp sibling reached through a .. that steps back from a link', () => { + // `home/work -> priv/x`, and the destination is `home/work/../y/journey.ad`. The entry is created in + // `priv/y`, because `..` steps back from the link's TARGET, so the temp file sits beside it. The + // destination's own spelling resolves elsewhere — `home/y` — and applying a spelled `..` textually, as + // `lstat` or `realpathSync` do, answers exactly that. The real temp sibling is then somebody else's file + // and a planted look-alike beside `home/y` is one of ours. + const root = fixtureRoot('dotdot'); + const home = path.join(root, 'home'); + fs.mkdirSync(home); + const homeY = path.join(home, 'y'); + fs.mkdirSync(homeY); + const privX = path.join(root, 'priv', 'x'); + fs.mkdirSync(privX, { recursive: true }); + const privY = path.join(root, 'priv', 'y'); + fs.mkdirSync(privY); + fs.symlinkSync(privX, path.join(home, 'work')); + const destination = `${home}/work/../y/journey.ad`; + const named = `.journey.ad.${process.pid}-0000.tmp`; + const realSibling = path.join(privY, named); + const lookAlike = path.join(homeY, named); + + expect(isAtomicPublishTemporaryPath(realSibling, destination)).toBe(true); + expect(isAtomicPublishTemporaryPath(lookAlike, destination)).toBe(false); +}); + +test('recognizes a temp path spelled through the directory the entry is really created in', () => { + // The temp file is a sibling of the destination AS THE FILESYSTEM RESOLVES IT, because that is where the + // entry is created. A destination spelled through a symbolic link (`/var` on macOS) therefore has its + // temp file one directory over in text, and a caller that compared the two spellings as strings would + // call every one of those temp files somebody else's. + const root = fixtureRoot('alias'); + const physical = path.join(root, 'physical'); + fs.mkdirSync(physical); + const alias = path.join(root, 'alias'); + fs.symlinkSync(physical, alias); + const destination = path.join(alias, 'report.json'); + const staged = path.join(fs.realpathSync(physical), `.report.json.${process.pid}-0000.tmp`); + + expect(isAtomicPublishTemporaryPath(staged, destination)).toBe(true); + // Still one directory's worth of names: a sibling that is not this destination's temp file is not it. + expect( + isAtomicPublishTemporaryPath(path.join(fs.realpathSync(physical), '.other.1.tmp'), destination), + ).toBe(false); +}); + function fixtureRoot(label: string): string { const root = mkdtempForTestSync(`agent-device-durable-file-${label}-`); roots.push(root); diff --git a/packages/host-kit/src/internal/atomic-file-host.fixtures.ts b/packages/host-kit/src/internal/atomic-file-host.fixtures.ts new file mode 100644 index 0000000000..a3e98a3a5b --- /dev/null +++ b/packages/host-kit/src/internal/atomic-file-host.fixtures.ts @@ -0,0 +1,72 @@ +// The host this suite's destinations are judged against: the directory owners a test chooses, and the +// scratch directories it builds them in. The ancestry rule reads the real host for its own identity, so a +// test that leaves that alone is asserting against whatever account the machine it runs on happens to have. + +import { expect } from 'vitest'; +import fs from 'node:fs'; +import { AppError } from '@agent-device/kernel/errors'; +import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; +import { publishScriptFileSync } from './atomic-file.ts'; + +/** This process's uid. Windows has none, and every test that uses it is skipped there. */ +export const currentUid = process.getuid?.() ?? -1; +const currentGid = process.getgid?.() ?? -1; + +/** Some other local user, not this one and not root. */ +export const FOREIGN_UID = 65534; + +/** A scratch root, spelled the way the kernel spells it, so a link's answer and a test's agree. */ +export function ancestryRoot(): string { + return fs.realpathSync(mkdtempForTestSync('host-kit-ancestry-')); +} + +/** + * A directory carrying `mode`, owned by this user. The ownership is set explicitly because a scratch + * directory inherits one from its parent, not necessarily this user's. + */ +export function directoryWith(directory: string, mode: number): string { + fs.mkdirSync(directory); + fs.chownSync(directory, currentUid, currentGid); + fs.chmodSync(directory, mode); + return directory; +} + +/** A publication of fixed contents, so a test says which destination and not what bytes. */ +export function publish(destination: string): void { + publishScriptFileSync({ destination, contents: 'context\n' }); +} + +/** Runs `run` under `process.umask(0o002)` — the umask of a shared checkout that breaks a mode-less `mkdir`. */ +export function withSharedUmask(run: () => void): void { + const previous = process.umask(0o002); + try { + run(); + } finally { + process.umask(previous); + } +} + +export function expectUntrusted(run: () => void, exposure: string, ancestor: string): void { + expectRefusal(run, 'script_ancestor_untrusted', exposure, ancestor); +} + +export function expectUntrustedReplaced(run: () => void, ancestor: string): void { + expectRefusal(run, 'script_ancestry_replaced', 'parent_replaced', ancestor); +} + +/** Asserts the typed refusal a destination earns, naming the directory at fault. */ +function expectRefusal(run: () => void, reason: string, exposure: string, ancestor: string): void { + let details: Record | undefined; + try { + run(); + } catch (error) { + expect(error).toBeInstanceOf(AppError); + details = (error as AppError).details as Record; + } + expect(details).toMatchObject({ reason, exposure, ancestor }); +} + +/** The permission bits of an entry, with the type and set-id bits cut off. */ +export function modeOf(pathname: string): number { + return fs.lstatSync(pathname).mode & 0o777; +} diff --git a/packages/host-kit/src/internal/atomic-file-parent.test.ts b/packages/host-kit/src/internal/atomic-file-parent.test.ts new file mode 100644 index 0000000000..58708b7713 --- /dev/null +++ b/packages/host-kit/src/internal/atomic-file-parent.test.ts @@ -0,0 +1,280 @@ +// Whether a destination's parent can be RESOLVED at all, what host-kit creates on the way to it, and what +// a publish does when the walk stops short of it (#4565). Every name the path spells is resolved one step +// at a time the way the kernel walks it, so a `..` is only answerable once the directory it steps back +// from exists. +import { afterEach, expect, test, vi } from 'vitest'; +import fs from 'node:fs'; +import path from 'node:path'; +import { + ancestryRoot as root, + directoryWith, + expectUntrusted, + FOREIGN_UID, + modeOf, + publish, + withSharedUmask, +} from './atomic-file-host.fixtures.ts'; +import { confirmScriptDestination, prepareScriptDestination } from './atomic-file.ts'; + +const skipOnWindows = process.platform === 'win32' ? test.skip : test; + +afterEach(() => { + vi.restoreAllMocks(); +}); + +skipOnWindows( + 'refuses a destination that steps back out of a missing directory, and creates none', + () => { + // The walk ends at `missing`, with two steps up still queued. The kernel cannot apply them until + // `missing` exists, while a recursive `mkdir` resolves the same spelling as text and builds + // `/shared/recordings` — a directory the walk never judged, where any local user can write. So a + // destination that would be resolved by creating it is refused BEFORE anything is created, which is the + // promise the docs make for a refused destination. + const directory = root(); + const privateDir = directoryWith(path.join(directory, 'private'), 0o700); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + // Spelled by hand, because `path.join` folds a `..` away and the folded name is a DIFFERENT + // destination: `/shared/recordings`, which the kernel reaches without ever looking at `private`. + const destination = `${privateDir}/missing/../../shared/recordings/journey.ad`; + + expectUntrusted(() => publish(destination), 'unresolvable_parent', privateDir); + expectUntrusted(() => prepareScriptDestination(destination), 'unresolvable_parent', privateDir); + expect(fs.readdirSync(privateDir)).toEqual([]); + expect(fs.readdirSync(shared)).toEqual([]); + }, +); + +skipOnWindows('accepts a destination that steps back over directories that all exist', () => { + // The other half of the rule: a `..` the kernel CAN apply is applied, and the directory it lands in is + // judged on its own. `here/nested` stands, so both steps up resolve and the sibling `there` is entered + // and published into. + const directory = root(); + const here = directoryWith(path.join(directory, 'here'), 0o700); + fs.mkdirSync(path.join(here, 'nested')); + const there = directoryWith(path.join(directory, 'there'), 0o700); + + publish(`${here}/nested/../../there/journey.ad`); + + expect(fs.readFileSync(path.join(there, 'journey.ad'), 'utf8')).toBe('context\n'); + expect(fs.readdirSync(here)).toEqual(['nested']); +}); + +skipOnWindows('creates a missing parent at 0700 on a shared umask and publishes into it', () => { + // The shape that used to refuse itself: on a umask-002 host a mode-less `mkdir` makes the new parent + // 0775, and the check that judges it then refuses the very directory the publish just created, with the + // directory left behind. host-kit creates at 0700 and a recursive `mkdir` applies that mode to every + // level it makes, so each new directory passes the check it is judged by. + const home = directoryWith(path.join(root(), 'home'), 0o700); + const recordings = path.join(home, 'workflows', 'recordings'); + const destination = path.join(recordings, 'journey.ad'); + + withSharedUmask(() => publish(destination)); + + expect(fs.readFileSync(destination, 'utf8')).toBe('context\n'); + expect(modeOf(path.join(home, 'workflows'))).toBe(0o700); + expect(modeOf(recordings)).toBe(0o700); +}); + +skipOnWindows('answers the created directory as the one to publish into', () => { + // The creation call answers the directory the SECOND walk judged, spelled from that directory: under the + // shared umask, that answer is what a caller that stages its own bytes must stage in. + const home = directoryWith(path.join(root(), 'home'), 0o700); + const destination = path.join(home, 'nested', 'deeper', 'journey.ad'); + + let judged = ''; + withSharedUmask(() => { + judged = prepareScriptDestination(destination).directory; + }); + + expect(judged).toBe(path.join(home, 'nested', 'deeper')); + expect(modeOf(path.join(home, 'nested'))).toBe(0o700); + expect(modeOf(judged)).toBe(0o700); +}); + +skipOnWindows('refuses a destination whose parent is gone by the time the answer is used', () => { + // The one walk that creates is host-kit's own, so what this pins is the other half: an ANSWER is only + // usable while the chain it named still stands. `missing` goes away after the answer was given, so there + // is no directory the entry belongs in. Answering the nearest ancestor that did stand would write + // `root/journey.ad` for a destination spelling `root/missing/journey.ad` — a file nobody asked for, in a + // directory whose permissions were never what the answer promised. + const directory = root(); + const missing = path.join(directory, 'missing'); + const destination = path.join(missing, 'journey.ad'); + const prepared = prepareScriptDestination(destination); + + fs.rmSync(missing, { recursive: true, force: true }); + + expectUntrusted( + () => confirmScriptDestination(destination, prepared), + 'unreachable_parent', + directory, + ); + expect(fs.readdirSync(directory)).toEqual([]); +}); + +skipOnWindows( + 'adopts a missing level another process created, and creates the rest below it', + () => { + // Two sessions saving into the same new directory meet HERE: one wins `mkdir`, and the other finds the + // name taken. Refusing that (which an earlier shape did, with `entry_appeared`) made a routine + // concurrent save fail. The appeared entry is therefore JUDGED the way every other step is judged, by + // the single `lstat` of the name, and this user's own private directory is the ordinary answer (ADR 0016). + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const appeared = path.join(home, 'recordings'); + const realMkdirSync = fs.mkdirSync; + vi.spyOn(fs, 'mkdirSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + // The other process creates the level the instant this call reaches for the missing name. + if (String(pathname) === appeared && !fs.existsSync(appeared)) { + realMkdirSync(appeared, { mode: 0o700 }); + } + return (realMkdirSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.mkdirSync); + + const destination = path.join(appeared, 'journey.ad'); + + expect(prepareScriptDestination(destination).directory).toBe(appeared); + publish(destination); + expect(fs.readFileSync(path.join(appeared, 'journey.ad'), 'utf8')).toBe('context\n'); + }, +); + +skipOnWindows( + 'refuses a missing level that appeared as another user directory, and creates nothing below it', + () => { + // Judged, not trusted: an appeared name is NOT this call's creation, so it cannot be taken on faith + // that it was made at the private mode. Ownership is asked of the same `lstat` the walk judges ground + // with, and a directory another local user owns is theirs to repopulate or replace, whatever its mode. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const appeared = path.join(home, 'recordings'); + const realMkdirSync = fs.mkdirSync; + vi.spyOn(fs, 'mkdirSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + if (String(pathname) === appeared && !fs.existsSync(appeared)) { + realMkdirSync(appeared, { mode: 0o700 }); + fs.chmodSync(appeared, 0o700); + } + return (realMkdirSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.mkdirSync); + // Seen as it appears, and judged foreign by the walk and by the creation alike. + const seen = serveOwnership(appeared, FOREIGN_UID); + + const destination = path.join(appeared, 'journey.ad'); + + expectUntrusted(() => prepareScriptDestination(destination), 'foreign_owned', appeared); + expect(seen()).toBeGreaterThan(0); + expect(fs.existsSync(path.join(appeared, 'journey.ad'))).toBe(false); + }, +); + +skipOnWindows( + 'refuses a missing level that appeared group-writable, rather than adopting it', + () => { + // The mode decides, because membership cannot be proven (ADR 0016): an appeared directory at 0775 is one + // the group can add names in, so the destination's own name can be made there by another member first. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const appeared = path.join(home, 'recordings'); + const realMkdirSync = fs.mkdirSync; + vi.spyOn(fs, 'mkdirSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + if (String(pathname) === appeared && !fs.existsSync(appeared)) { + realMkdirSync(appeared, { mode: 0o775 }); + fs.chmodSync(appeared, 0o775); + } + return (realMkdirSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.mkdirSync); + + const destination = path.join(appeared, 'journey.ad'); + + expectUntrusted(() => prepareScriptDestination(destination), 'shared_group_writable', appeared); + }, +); + +skipOnWindows( + 'refuses a missing level that appeared sticky and world-writable, where any user can name the entry', + () => { + // The sticky bit is what lets the rule PASS THROUGH such a directory: it holds the entries already there + // in place. It cannot refuse a NEW entry by name, so a level that appeared open to the world is refused + // for the entry the destination spells, even though this user owns it. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const appeared = path.join(home, 'recordings'); + const realMkdirSync = fs.mkdirSync; + vi.spyOn(fs, 'mkdirSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + if (String(pathname) === appeared && !fs.existsSync(appeared)) { + realMkdirSync(appeared, { mode: 0o777 }); + fs.chmodSync(appeared, 0o1777); + } + return (realMkdirSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.mkdirSync); + + const destination = path.join(appeared, 'journey.ad'); + + expectUntrusted(() => prepareScriptDestination(destination), 'shared_parent', appeared); + }, +); + +/** Reports `uid` for one path from this point on, and how many times the rule looked at it. */ +function serveOwnership(target: string, uid: number): () => number { + const realLstatSync = fs.lstatSync.bind(fs); + let looks = 0; + vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + const stats = realLstatSync(pathname as never, ...(rest as never[])); + if (String(pathname) !== target || stats === undefined) return stats; + looks += 1; + return Object.assign(Object.create(Object.getPrototypeOf(stats)), stats, { uid }); + }) as typeof fs.lstatSync); + return () => looks; +} + +skipOnWindows('refuses a missing level planted as a link, and creates nothing beyond it', () => { + // The walk stops at `new`, which does not exist yet, so the parent it stopped in is sticky and open to + // other local users adding names. In that window they can put a LINK at `new`: a recursive `mkdir` + // resolves the whole tail as text and follows it, so the publish creates a directory on the far side of + // a link nobody judged — and as root it would do so with privileges. Creating one name at a time inside + // the directory this call established finds the name taken instead, and refuses. + const directory = root(); + const sticky = directoryWith(path.join(directory, 'sticky'), 0o1777); + const elsewhere = path.join(directory, 'elsewhere'); + fs.mkdirSync(elsewhere); + fs.chmodSync(elsewhere, 0o700); + const planted = path.join(sticky, 'new'); + const realMkdirSync = fs.mkdirSync; + vi.spyOn(fs, 'mkdirSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + // The attacker plants the link the instant this call reaches for the missing name. + if (String(pathname) === planted && !fs.existsSync(planted)) { + fs.symlinkSync(elsewhere, planted); + } + return (realMkdirSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.mkdirSync); + + const destination = path.join(sticky, 'new', 'tail', 'journey.ad'); + + expectUntrusted(() => prepareScriptDestination(destination), 'entry_appeared', planted); + expect(fs.readdirSync(elsewhere)).toEqual([]); + expect(fs.readdirSync(sticky)).toEqual(['new']); +}); + +test('refuses a destination that is not absolute on every platform, and creates nothing', () => { + // Not skipped on Windows: there the ancestry walk is a no-op, so the walk that would otherwise catch a + // relative name never runs, and a relative destination would reach `mkdir` outright. The check therefore + // has to happen before the platform branch, which is what this test pins. Walking a relative name would + // mean judging the process's working directory by the NAME Node answers after the last `chdir`, while the + // kernel resolves the write in the moved one. + const relative = path.join('recordings', 'journey.ad'); + + expectUntrusted( + () => prepareScriptDestination(relative), + 'relative_destination', + path.join('recordings'), + ); + // The confirm call refuses from the same check, before its platform branch: on Windows no walk runs at + // all, so a relative name cannot be left to the walk to catch. + expectUntrusted( + () => confirmScriptDestination(relative, { directory: relative, identity: undefined }), + 'relative_destination', + path.join('recordings'), + ); + // Nothing was created for a destination that was refused at the entry. + expect(fs.existsSync('recordings')).toBe(false); +}); diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index bb00b26944..509994c272 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -1,6 +1,7 @@ import crypto from 'node:crypto'; import fs from 'node:fs'; import path from 'node:path'; +import { AppError } from '@agent-device/kernel/errors'; import { emitDiagnostic } from './diagnostics.ts'; export type AtomicPublishMode = 'replace' | 'link-exclusive'; @@ -42,6 +43,126 @@ export function publishFileSync(options: { }); } +/** + * Publishes a session script, and nothing else, from a same-directory temporary sibling. + * + * This is `publishFileSync` plus the destination-ancestry rule (#4565), asked through + * {@link prepareScriptDestination}: it creates what the destination is missing and answers with the + * directory to create the entry in. The chain is judged once here, and the file is private, because a + * recording is a transcript of what someone did on this machine. + */ +export function publishScriptFileSync(options: { + destination: string; + contents: string; + publish?: AtomicPublishMode; +}): void { + let temporaryPath: string | undefined; + try { + // The directory the entry is created in is the walk's ANSWER and never `path.dirname` of the + // spelling: a `..` or a link sends the entry elsewhere, and a temp file staged where the text points + // is one another local user can reach and put their bytes behind. + const judged = prepareScriptDestination(options.destination).directory; + temporaryPath = createAtomicPublishTempPath(judged, options.destination); + fs.writeFileSync(temporaryPath, options.contents, { encoding: 'utf8', mode: SCRIPT_FILE_MODE }); + // The entry is created in the directory the walk ANSWERED, spelled from it, never through the + // destination's own spelling: the kernel would resolve that a second time, against whatever stands on + // the path by then, and land the entry in ground the rule never reached. + const entry = path.join(judged, path.basename(options.destination)); + if (options.publish === 'link-exclusive') { + fs.linkSync(temporaryPath, entry); + } else { + fs.renameSync(temporaryPath, entry); + } + } finally { + removeTempBestEffort(options.destination, temporaryPath); + } +} + +/** + * The canonical temp path for a destination: a sibling of the name, inside the directory the publish will + * create the entry in — the walk's answer for a script destination, `path.dirname` for every other one. + */ +function createAtomicPublishTempPath(directory: string, destination: string): string { + return path.join( + directory, + `.${path.basename(destination)}.${process.pid}-${crypto.randomUUID()}.tmp`, + ); +} + +function removeTempBestEffort(destination: string, temporaryPath: string | undefined): void { + if (temporaryPath === undefined) return; + try { + fs.rmSync(temporaryPath, { force: true }); + } catch (error) { + emitDiagnostic({ + level: 'warn', + phase: 'atomic_file_cleanup_failed', + data: { + destination, + temporaryPath, + error: error instanceof Error ? error.message : String(error), + }, + }); + } +} + +/** A recording holds literals a `fill` did not parameterize (ADR 0017), so it is written private. */ +const SCRIPT_FILE_MODE = 0o600; + +/** + * A directory a script publish creates is itself judged on the way to a later version, so it is created + * at 0700: the mode the rule accepts under every umask, including the shared-checkout 002 that would + * otherwise leave a new directory 0775 and then refuse it. + */ +const SCRIPT_DIR_MODE = 0o700; + +/** + * Readies a script destination and reports the PHYSICAL directory to create the entry in (#4565). + * + * One call owns the sequence, because the ORDER is what makes "a refused destination leaves no directories + * behind" true: the chain is walked, a refused destination is refused BEFORE anything is created, what is + * missing is created at {@link SCRIPT_DIR_MODE} inside the judged directory, and the completed chain is + * walked AGAIN before the answer. Only the second walk asks the CREATION question — whether other local + * users could add the destination's own name where the entry lands — because below the first walk the + * missing directories are this call's own to create at 0700, which is what keeps + * `mkdir -p /recordings` acceptable. {@link createMissingLevels} says why each level is + * created on its own, and why a `..` queued behind an absent name is refused by the FIRST walk. + * + * On Windows access is an ACL rather than a mode, so the walk is a no-op and the parent is the answer — but + * the destination still has to be absolute first, on every platform. + */ +export function prepareScriptDestination(destination: string): ScriptDestination { + const spelled = spelledParent(destination); + if (process.platform === 'win32') { + fs.mkdirSync(spelled, { recursive: true, mode: SCRIPT_DIR_MODE }); + return { directory: spelled, identity: publishDirectoryIdentity(spelled) }; + } + const trust = scriptTrust(); + const walked = walkSpelledParent(spelled, destination, trust); + if (walked.ended === 'refused') throw walked.reject; + // A walk that stopped short at an absent name creates that tail inside the directory it judged, and asks + // the completed chain again. A short walk with a `..` queued behind the absent name creates nothing: no + // amount of creating resolves a step back out of a directory that is not there. + if (walked.ended === 'short' && !walked.unresolvable) { + createMissingLevels(destination, walked.deepest, walked.missing, trust); + return publishableDestination( + destination, + walkSpelledParent(spelled, destination, trust), + trust, + ); + } + return publishableDestination(destination, walked, trust); +} + +/** + * Where a script entry is created: the PHYSICAL directory the rule judged, and that directory's identity as + * the walk's own `lstat` answered it — what {@link confirmScriptDestination} compares before a rename. + */ +export type ScriptDestination = Readonly<{ + directory: string; + identity: string | undefined; +}>; + export type DurableFilePublishMode = 'replace' | 'link-exclusive'; /** Publishes complete UTF-8 contents with a durable file and directory fence. */ @@ -96,23 +217,11 @@ export function withAtomicPublishTempPathSync( destination: string, publish: (temporaryPath: string) => T, ): T { - const temporaryPath = createAtomicPublishTempPath(destination); + const temporaryPath = createAtomicPublishTempPath(path.dirname(destination), destination); try { return publish(temporaryPath); } finally { - try { - fs.rmSync(temporaryPath, { force: true }); - } catch (error) { - emitDiagnostic({ - level: 'warn', - phase: 'atomic_file_cleanup_failed', - data: { - destination, - temporaryPath, - error: error instanceof Error ? error.message : String(error), - }, - }); - } + removeTempBestEffort(destination, temporaryPath); } } @@ -132,20 +241,703 @@ function syncDirectoryBestEffort(directory: string): void { } } -/** Returns the canonical same-directory temp path used by atomic publishers. */ -function createAtomicPublishTempPath(destination: string): string { - return path.join( - path.dirname(destination), - `.${path.basename(destination)}.${process.pid}-${crypto.randomUUID()}.tmp`, - ); +/** + * `lstat` that treats absence as `undefined`; every other errno propagates. Owned here rather than in a + * module of its own: this file sits on the daemon's startup path, where a new module is eager code every + * entry that publishes a file pays for (ADR 0019), and the verified-file guards are on this path already. + */ +export function lstatIfPresent(pathname: string): fs.Stats | undefined { + try { + return fs.lstatSync(pathname); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; + throw error; + } } -/** Identifies a temp path produced for a particular destination. */ +/** + * Identifies a temp path produced for a particular destination. + * + * The temp file is a sibling of the directory the entry is CREATED in, which is not the directory the + * destination's spelling names: `home/work/../y` with `work` a link names `home/y` as text while the entry + * lands beside the link's target. The two are therefore compared as device and inode, because `lstat` or + * `realpathSync` applies a spelled `..` textually and answers the wrong directory. + */ export function isAtomicPublishTemporaryPath(value: unknown, destination: string): boolean { if (typeof value !== 'string') return false; - if (path.dirname(value) !== path.dirname(destination)) return false; const name = path.basename(value); - return name.startsWith(`.${path.basename(destination)}.`) && name.endsWith('.tmp'); + if (!name.startsWith(`.${path.basename(destination)}.`) || !name.endsWith('.tmp')) return false; + return sameDirectory(path.dirname(value), path.dirname(destination)); +} + +/** Whether two directory spellings name one directory, by device and inode rather than by path text. */ +function sameDirectory(left: string, right: string): boolean { + if (left === right) return true; + const here = statOrNull(left); + const there = statOrNull(right); + return ( + here !== undefined && there !== undefined && here.dev === there.dev && here.ino === there.ino + ); +} + +/** `stat` where any failure is "cannot tell": a temp file nobody can point at is treated as foreign. */ +function statOrNull(pathname: string): fs.Stats | undefined { + try { + return fs.statSync(pathname); + } catch { + return undefined; + } +} + +/** + * Confirms a destination host-kit ANSWERED earlier, and reports the directory to create the entry in. + * + * One call, for the one check a caller that stages bytes owes: a download or a long upload can run between + * the walk that judged the directory and the rename that creates the entry, so the chain is asked again + * before the entry is made, and an ancestor pointed at a link meanwhile is caught. Every `parent_replaced` + * refusal comes from {@link scriptAncestryFailure} — the reason, exposure, ancestor and hint a route would + * have to copy, and would drift from. Nothing re-judges ground the walk already owns: the ownership rule is + * what excludes anyone who could move a judged directory in the first place (ADR 0016). + */ +export function confirmScriptDestination(destination: string, prepared: ScriptDestination): string { + const current = scriptDestination(destination); + if (current.identity !== prepared.identity) { + throw scriptAncestryFailure(destination, current.directory, 'parent_replaced'); + } + return current.directory; +} + +/** + * Walks a destination that has to stand as it is, creating nothing, and judges the answer: refuses unless + * every directory the kernel looks a name up in is one no other non-root local user can change (#4565). + * {@link prepareScriptDestination} is the same rule for a caller that also needs the missing tail created, + * and everything written there about how ground is judged, and about the window being closed by PERMISSIONS + * rather than by timing, applies here too. Because nothing is created, a walk that stopped short at an + * absent name has no answer to give and refuses as `unreachable_parent`. + */ +function scriptDestination(destination: string): ScriptDestination { + const spelled = spelledParent(destination); + if (process.platform === 'win32') { + return { directory: spelled, identity: publishDirectoryIdentity(spelled) }; + } + const trust = scriptTrust(); + const walk = walkSpelledParent(spelled, destination, trust); + if (walk.ended === 'refused') throw walk.reject; + return publishableDestination(destination, walk, trust); +} + +/** + * Judges a finished walk and answers where the entry is created, with the identity THIS walk read so a + * caller that stages bytes beside it can confirm the ground one time before its rename. + * + * Only an ARRIVED walk has that answer. A walk that stopped short at an absent name has no directory to + * report: the name it stopped at is not one the entry can be created in, and the nearest ancestor it did + * reach is a file under a name nobody asked for. A `..` queued behind that absent name says creating could + * not resolve the chain either, which is the reason the caller that creates gets instead. + */ +function publishableDestination( + destination: string, + walk: WalkOutcome, + trust: ScriptDestinationTrust, +): ScriptDestination { + if (walk.ended === 'refused') throw walk.reject; + if (walk.ended === 'short') { + throw scriptAncestryFailure( + destination, + walk.deepest, + walk.unresolvable ? 'unresolvable_parent' : 'unreachable_parent', + ); + } + // Where other local users can add entries here, one of them can add this entry first and the + // recording is theirs. + if (othersCreateEntriesIn(walk.authority, trust)) { + throw scriptAncestryFailure(destination, walk.deepest, 'shared_parent'); + } + return { directory: walk.deepest, identity: walk.identity }; +} + +/** + * The parent of `destination` exactly as the caller spells it, refusing a RELATIVE destination at the entry + * ON EVERY PLATFORM, Windows included, where no walk runs to catch it. Walking a relative name would put + * the process's working directory into the judged chain — a name Node answers from the first query after the + * last `chdir`, so it can name a directory the process no longer stands in while the kernel resolves the + * destination in the moved one (ADR 0016). + */ +function spelledParent(destination: string): string { + const parent = path.dirname(destination); + if (!path.isAbsolute(parent)) { + throw scriptAncestryFailure(destination, parent, 'relative_destination'); + } + return parent; +} + +/** + * Where the walk stands: a directory it judged and physically reached, the identity that directory had as + * the walk's own `lstat` answered it, and the names still to resolve. + */ +type WalkState = Readonly<{ + deepest: string; + authority: DirectoryAuthority; + identity: string; + /** Path components left to resolve, nearest first. */ + queue: readonly string[]; + /** Link targets expanded so far. */ + hops: number; +}>; + +type WalkStep = + | Readonly<{ kind: 'reject'; path: string; exposure: ScriptAncestryExposure }> + | Readonly<{ + kind: 'short'; + deepest: string; + /** The spelled names below the judged directory, the first of them absent. */ + missing: readonly string[]; + /** Whether a `..` is queued behind the name that stopped the walk. */ + behindUpwardStep: boolean; + }> + | Readonly<{ kind: 'stand'; state: WalkState }>; + +/** + * Where a walk ended. Only a walk that ARRIVED reached the directory the entry is created in, and it carries + * that directory together with the authority and identity it was judged under, so the caller never asks the + * host again about ground the walk has already read. A walk that stopped SHORT reports the nearest directory + * it did judge and the spelled tail below it, which is what a caller that creates needs in order to create + * below judged ground only. A walk that REFUSED carries the failure it stopped on. + * + * A walk that stopped short has no answer for a publisher: the name it stopped at is not a directory the + * entry can be created in, and publishing under the nearest ancestor writes a file nobody named. Its + * `unresolvable` says a `..` is queued behind that name, so creating cannot finish the resolution either. + */ +type WalkOutcome = + | Readonly<{ + ended: 'arrived'; + /** The PHYSICAL directory the entry is created in. */ + deepest: string; + authority: DirectoryAuthority; + /** That directory's identity, as this walk's `lstat` of it answered. */ + identity: string; + }> + | Readonly<{ + ended: 'short'; + /** The nearest directory the walk did judge; the destination's name is absent below it. */ + deepest: string; + /** The spelled names below `deepest`, the first of them absent. */ + missing: readonly string[]; + /** Whether a `..` is queued behind that name, so creating cannot resolve the chain. */ + unresolvable: boolean; + }> + | Readonly<{ + ended: 'refused'; + /** The step the walk could not stand on, and the way it is unsafe. */ + ancestor: string; + exposure: ScriptAncestryExposure; + /** The same judgment, worded for a caller that is saving a script. */ + reject: AppError; + }>; + +/** + * Judges the ground `directory` STANDS ON, and `directory` itself: every directory the kernel looks one of its + * names up in, from the root down. Asks the destination walk what a name INSIDE `directory` would resolve by, + * and creates nothing — the probe name below it is never looked up. + * + * A caller that CHANGES something below `directory` has to ask this first: `O_NOFOLLOW` guards the LAST name of + * an open and nothing above it, so an ancestor another local user can write lets them rename `directory` and + * leave a link at its name between two of that caller's calls, and every level below then resolves on ground + * nobody judged. Where every ancestor is closed to other users nobody can make that swap, so the window is + * closed by PERMISSIONS — as it is for a script destination, whose rule this is rather than a copy of it, + * sticky-bit exception included (ADR 0016). + * + * Answers `undefined` for a chain this user may rely on: the walk ARRIVED, standing on `directory` itself, + * having judged it. Otherwise it answers the step it could not stand on, and the way that is unsafe. + */ +export function untrustedDirectoryAncestry( + directory: string, +): Readonly<{ ancestor: string; exposure: ScriptAncestryExposure }> | undefined { + // Spelled by hand, NOT with `path.join`: join folds a `..` out of the caller's own spelling, and the kernel + // resolves that step against the directory physically stood in, not against the text. + // Refused here rather than thrown by the walk's own entry check: a caller that asks before it CHANGES + // something needs an answer it can act on, and a relative name cannot be judged without putting the + // process's working directory into the chain. + if (!path.isAbsolute(directory)) return { ancestor: directory, exposure: 'relative_destination' }; + if (process.platform === 'win32') return undefined; + // Spelled by hand, NOT with `path.join`: join folds a `..` out of the caller's own spelling, and the kernel + // resolves that step against the directory physically stood in, not against the text. + const probed = `${directory}/${CHAIN_PROBE_NAME}`; + const spelled = spelledParent(probed); + const walked = walkSpelledParent(spelled, probed, scriptTrust()); + if (walked.ended === 'refused') return { ancestor: walked.ancestor, exposure: walked.exposure }; + // ARRIVED is the trusted answer. STOPPED SHORT says a name above `directory` is absent, so the walk has no + // judgment for the chain beyond it, and a `..` queued behind that name is its other spelling. + if (walked.ended === 'arrived') return undefined; + return { + ancestor: walked.deepest, + exposure: walked.unresolvable ? 'unresolvable_parent' : 'unreachable_parent', + }; +} + +/** The name {@link untrustedDirectoryAncestry} asks the walk about, which it never creates. */ +const CHAIN_PROBE_NAME = '.agent-device-ancestry-probe'; + +/** + * Walks the spelled parent exactly as the kernel resolves a path, judging every step, and refuses at the + * first step another local user could steer. The directory it reports is where the entry gets created. + * + * No `realpath` is involved anywhere: `realpathSync` answers only with the FINAL directory, so every + * directory stepped through can vanish from the answer, and from the judgment, whenever a link leads on + * to another link. Each component is resolved against the directory physically reached instead: + * + * - `.` is skipped; `..` moves to the parent of the directory physically stood in, which is judged like + * any other directory. Neither one is a name that has to exist. + * - Any other component is lstat'ed in that directory. An absent one ENDS the walk at the nearest + * directory the walk did reach, and the outcome says so: `ended` is `short`, `missing` is the tail + * below that point, and `unresolvable` is true when a `..` is queued behind that name. + * - A directory is judged and entered. Each path is read from the host once per walk, so a `..` back over + * ground already crossed, or an alias of it, does not ask the host again. + * - A symbolic link is judged itself, against the directory that physically holds it, and its target's + * RAW components go in front of the queue — restarting from `/` for an absolute target, continuing from + * the link's own directory for a relative one. Hops are counted against + * {@link MAX_SCRIPT_PATH_LINK_HOPS}, and crossing it is refused rather than trusted. + * - A component that is neither a directory nor a link cannot carry a publish, and is refused. + * + * `parent` is the caller's own spelling, which is what both this walk and any creation it authorizes + * resolve. `destination` appears only in refusals, which name the path the caller passed. + */ +function walkSpelledParent( + parent: string, + destination: string, + trust: ScriptDestinationTrust, +): WalkOutcome { + let step = startWalk(parent, trust); + // Every step consumes a component, and every link hop counts against a fixed limit, so this ends. + for (;;) { + if (step.kind === 'reject') { + return { + ended: 'refused', + ancestor: step.path, + exposure: step.exposure, + reject: scriptAncestryFailure(destination, step.path, step.exposure), + }; + } + if (step.kind === 'short') { + return { + ended: 'short', + deepest: step.deepest, + missing: step.missing, + unresolvable: step.behindUpwardStep, + }; + } + const { state } = step; + const [component, ...rest] = state.queue; + // The only ending that ARRIVES: an empty queue, every name the parent spelled resolved and judged. + if (component === undefined) { + return { + ended: 'arrived', + deepest: state.deepest, + authority: state.authority, + identity: state.identity, + }; + } + step = stepThrough(state, component, rest, trust); + } +} + +/** The first state: the root, with every component of the parent still to resolve. */ +function startWalk(parent: string, trust: ScriptDestinationTrust): WalkStep { + return standOn('/', pathComponents(parent), trust, 0); +} + +/** + * Stands the walk on `directory`, judged from this call's own `lstat` of it, or refuses it. + * + * A name come back around through a `..` or an alias is judged again from a fresh `lstat`, and reaches the + * judgment it had on the first visit. The rule keeps no memory of ground it already owned, because a + * directory it stands in is one this user or root owns that others cannot write in, or a sticky one where an + * entry of this user's cannot be replaced (ADR 0016). + */ +function standOn( + directory: string, + queue: readonly string[], + trust: ScriptDestinationTrust, + hops: number, +): WalkStep { + const stats = lstatEntry(directory); + if (stats === undefined || !stats.isDirectory()) { + return { kind: 'reject', path: directory, exposure: 'not_a_directory' }; + } + const authority = directoryAuthority(stats); + const exposure = untrustedAncestryExposure(authority, trust); + if (exposure) return { kind: 'reject', path: directory, exposure }; + return { + kind: 'stand', + state: { deepest: directory, authority, identity: identityOf(stats), queue, hops }, + }; +} + +/** The fields this rule reads off one `lstat` answer: owner and mode of the ENTRY. */ +function directoryAuthority(stats: fs.BigIntStats): DirectoryAuthority { + return { uid: Number(stats.uid), mode: Number(stats.mode) }; +} + +/** + * The device and inode an `lstat` answer names. + * + * BIGINT stats: a numeric `ino` cannot hold every inode a filesystem hands out, so two distinct large inodes + * would collapse onto one identity, the collision the one retained comparison exists to catch. + */ +function identityOf(stats: fs.BigIntStats): string { + return `${stats.dev}:${stats.ino}`; +} + +/** `lstat` with bigint ids, treating absence as `undefined`: the only lookup this rule makes. */ +function lstatEntry(pathname: string): fs.BigIntStats | undefined { + return fs.lstatSync(pathname, { bigint: true, throwIfNoEntry: false }); +} + +/** The names of `directory`, with every `.` resolved away the way the kernel resolves it. */ +function pathComponents(directory: string): string[] { + return directory.split('/').filter((component) => component.length > 0 && component !== '.'); +} + +/** + * Advances one component of the queue, which the caller knows to be non-empty: an empty queue is where a + * walk arrives, and {@link walkSpelledParent} answers that itself. + */ +function stepThrough( + state: WalkState, + component: string, + rest: readonly string[], + trust: ScriptDestinationTrust, +): WalkStep { + // `..` is the parent of the directory PHYSICALLY stood in, not of the spelling: where `work` is a link, + // `.../work/../x` steps back from the link's target and lands beside it. + if (component === '..') { + return standOn(path.dirname(state.deepest), rest, trust, state.hops); + } + return stepIntoEntry(state, component, rest, trust); +} + +/** Resolves one named entry inside the directory the walk stands in. */ +function stepIntoEntry( + state: WalkState, + component: string, + rest: readonly string[], + trust: ScriptDestinationTrust, +): WalkStep { + const entry = path.join(state.deepest, component); + const stats = lstatEntry(entry); + // Nothing below here exists yet, so the walk stops at the ground it judged and reports the tail under + // it. A caller that creates makes that tail; a caller that creates nothing refuses. Neither goes on as + // if the name had resolved. + if (stats === undefined) { + return { + kind: 'short', + deepest: state.deepest, + missing: [component, ...rest], + behindUpwardStep: rest.includes('..'), + }; + } + // This lstat IS the judgment: type, owner and mode of the ENTRY the name holds. Asking the same name + // again with `stat` would answer whatever stands there by then, which on a race is a link somebody else + // put there, and the walk would judge the target's permissions while entering on the name. + if (stats.isSymbolicLink()) return stepThroughLink(state, entry, stats, rest, trust); + if (!stats.isDirectory()) return { kind: 'reject', path: entry, exposure: 'not_a_directory' }; + const authority = directoryAuthority(stats); + const exposure = untrustedAncestryExposure(authority, trust); + if (exposure) return { kind: 'reject', path: entry, exposure }; + return { + kind: 'stand', + state: { + deepest: entry, + authority, + identity: identityOf(stats), + queue: rest, + hops: state.hops, + }, + }; +} + +/** + * One hop. The link is judged where it physically stands, and its target's components enter the queue, + * because the kernel steps into them next. + */ +function stepThroughLink( + state: WalkState, + link: string, + stats: fs.BigIntStats, + rest: readonly string[], + trust: ScriptDestinationTrust, +): WalkStep { + const exposure = untrustedLinkExposure({ uid: Number(stats.uid) }, state.authority, trust); + if (exposure) return { kind: 'reject', path: link, exposure }; + if (state.hops >= MAX_SCRIPT_PATH_LINK_HOPS) { + return { kind: 'reject', path: link, exposure: 'link_loop_exceeded' }; + } + const target = fs.readlinkSync(link); + // A relative target continues from the directory that HOLDS the link, not from where the walk happens + // to stand, and its components are queued RAW. `path.join` would fold a `..` inside the target away, + // which is the one simplification this walk may not make: the kernel applies that `..` to the physical + // directory it reaches after the components before it. + const home = path.isAbsolute(target) ? '/' : path.dirname(link); + return standOn(home, [...pathComponents(target), ...rest], trust, state.hops + 1); +} + +/** + * How many link targets one destination walk expands before it refuses. + * + * Kept BELOW the smallest limit the supported kernels apply to a path (macOS 32, Linux 40), so this rule + * reaches its own limit first and answers with its own reason. Running out of hops has NOT established + * where the entry lands, which is a refusal rather than a pass. + */ +export const MAX_SCRIPT_PATH_LINK_HOPS = 30; + +/** One directory's identity, so a route that runs no walk on Windows can still answer with one. */ +function publishDirectoryIdentity(directory: string): string | undefined { + if (process.platform === 'win32') return 'windows'; + const stats = lstatEntry(directory); + return stats ? identityOf(stats) : undefined; +} + +/** + * What this process may rely on when it judges ground: who it is, as the kernel answers. Nothing else — + * the rule reads no account database, so its answer does not depend on which name services run (ADR 0016). + */ +export type ScriptDestinationTrust = Readonly<{ uid: number }>; + +/** What this process may rely on when it judges ground. */ +function scriptTrust(): ScriptDestinationTrust { + return { uid: process.getuid?.() ?? -1 }; +} + +/** The fields of a directory the ancestry rule reads, so the decision is testable without a filesystem. */ +export type DirectoryAuthority = Readonly<{ uid: number; mode: number }>; + +/** The fields of a symbolic link the ancestry rule reads. */ +export type LinkAuthority = Readonly<{ uid: number }>; + +/** + * The ways a step of the walk can be unsafe: others can change what is in that directory, create the + * entry the destination names, or put the link there, or the step cannot be resolved at all. The two + * `unreachable` and `unresolvable` shapes say a walk that stopped short has no directory to report, and + * `link_loop_exceeded` says a walk that ran out of hops has not established where the entry lands — a + * loop is refused, never trusted. {@link untrustedGroundWording} is what each one tells the caller. + */ +export type ScriptAncestryExposure = + | 'foreign_owned' + | 'world_writable' + | 'shared_group_writable' + | 'shared_parent' + | 'planted_link' + | 'link_loop_exceeded' + | 'not_a_directory' + | 'entry_appeared' + | 'relative_destination' + | 'unresolvable_parent' + | 'unreachable_parent' + | 'parent_replaced'; + +/** + * Whether this directory is one this user can rely on a destination being inside of, and why not if it + * is not. + * + * Ownership is asked first: a directory another user owns is theirs to chmod, empty and repopulate + * whatever its mode says today, and no race is needed. Then the mode, because group- or other-writable + * contents are open to those users directly. A group-writable directory is refused whoever owns the group: + * proving one holds no other user means reading the host's account files, which ADR 0016 declines to do, + * so the mode alone decides and the hint says to `chmod g-w`. The sticky bit is the one mode exception, + * and sound only for PASSING THROUGH: it keeps the entries already on the path in place, but cannot refuse + * a NEW entry by name, so {@link othersCreateEntriesIn} is asked separately before anything is created. + */ +export function untrustedAncestryExposure( + directory: DirectoryAuthority, + trust: ScriptDestinationTrust, +): ScriptAncestryExposure | undefined { + if (directory.uid !== 0 && directory.uid !== trust.uid) return 'foreign_owned'; + if (directory.mode & 0o1000) return undefined; + if (directory.mode & 0o002) return 'world_writable'; + if (directory.mode & 0o020) return 'shared_group_writable'; + return undefined; +} + +/** + * Whether other local users can add an entry here, which is how the destination's own name, or a + * directory below it, becomes theirs. + * + * A directory somebody else owns counts: they can create, rename or replace any entry in it whatever its + * mode says, sticky bit included, since that bit protects other people's entries from them, not their + * own. The sticky bit is otherwise not consulted here — it cannot refuse a NEW entry by name. + */ +export function othersCreateEntriesIn( + directory: DirectoryAuthority, + trust: ScriptDestinationTrust, +): boolean { + if (directory.uid !== 0 && directory.uid !== trust.uid) return true; + if (directory.mode & 0o002) return true; + return Boolean(directory.mode & 0o020); +} + +/** + * Whether a symbolic link on the path is one another local user could have put there, or could replace, + * and whose target is therefore theirs to choose. + * + * Where nobody but this user or root can add entries, a link cannot appear or change behind this rule. + * Where others CAN, the sticky bit is the only thing holding an entry in place, so a link this user or + * root owns stands and one anybody else owns does not — it may be theirs, and any of them can swap it for + * one pointing wherever they like. + * + * A component stepped back over with `..` is asked as a directory, not as a link: there the caller walks + * across it rather than publishing through it, and the directory it lands in is judged on its own. + */ +export function untrustedLinkExposure( + link: LinkAuthority, + home: DirectoryAuthority, + trust: ScriptDestinationTrust, +): ScriptAncestryExposure | undefined { + if (!othersCreateEntriesIn(home, trust)) return undefined; + if (home.mode & 0o1000 && (link.uid === 0 || link.uid === trust.uid)) return undefined; + return 'planted_link'; +} + +/** Why each exposure makes that ground unsafe, in the caller's terms. */ +const untrustedGroundWording: Record = { + foreign_owned: 'another local user owns that part of the path.', + world_writable: 'any local user can write that part of the path.', + shared_group_writable: + 'the group can write that part of the path, and agent-device cannot tell who else belongs to that group.', + shared_parent: 'another local user could create the script file there first.', + planted_link: 'another local user could have put that symbolic link there, or could replace it.', + link_loop_exceeded: + 'that part of the path follows more symbolic links than the system allows, so where the script would land is not established.', + not_a_directory: 'a directory was expected there, and something else stands in the way.', + entry_appeared: + 'a directory the script path needs was missing when the path was checked and appeared before this save could create it.', + relative_destination: + 'the script path has to be absolute, so the directories it names are the ones that get checked.', + unresolvable_parent: + 'the script path names a directory that does not exist and steps back out of it with `..`, so where the script would land is not established.', + unreachable_parent: + 'the directory the script path names does not exist, so the script has nowhere to be written.', + parent_replaced: '', +}; + +/** + * The typed reasons a destination-ancestry refusal answers with. + * + * A caller that reports WHY a script was not saved reads one of these out of the refusal and passes it on; + * they are named here, and not spelled again by whoever reads them, because the refusal is built here. + */ +const SCRIPT_ANCESTRY_REASONS = ['script_ancestor_untrusted', 'script_ancestry_replaced'] as const; + +/** A reason this rule answers with, or `undefined` for an error that came from somewhere else. */ +export function scriptAncestryReason(error: unknown): string | undefined { + if (!(error instanceof AppError)) return undefined; + const reason = error.details?.reason; + return typeof reason === 'string' && + (SCRIPT_ANCESTRY_REASONS as readonly string[]).includes(reason) + ? reason + : undefined; +} + +function scriptAncestryFailure( + destination: string, + ancestor: string, + exposure: ScriptAncestryExposure, +): AppError { + const replaced = exposure === 'parent_replaced'; + const wording = untrustedGroundWording[exposure]; + return new AppError( + 'COMMAND_FAILED', + replaced + ? `The directory for ${destination} changed while the script was staged, so the script was not saved.` + : `Refusing to save the script under ${ancestor}: ${wording}`, + { + reason: replaced ? SCRIPT_ANCESTRY_REASONS[1] : SCRIPT_ANCESTRY_REASONS[0], + exposure, + path: destination, + ancestor, + hint: ancestryHint(exposure, ancestor), + }, + ); +} + +/** + * What to do about it. A group-writable directory is the one refusal the caller can fix in place, because + * the mode alone is what this rule cannot resolve: it cannot tell who else belongs to that group. + */ +function ancestryHint(exposure: ScriptAncestryExposure, ancestor: string): string { + if (exposure === 'parent_replaced') { + return 'Re-record with open --save-script, or save under a directory nobody else can write.'; + } + if (exposure === 'shared_group_writable') { + return `Close the directory to its group with \`chmod g-w ${ancestor}\`, or save the script under a directory only you can write.`; + } + return 'Save the script under a directory you own that only you can write, and keep the path out of directories other users own.'; +} + +/** + * Creates the tail the walk found missing, ONE LEVEL AT A TIME, inside the directory the walk judged. + * + * A recursive `mkdir` cannot be used here even though it takes a mode: it resolves the whole tail as text, so + * a link planted at one of those missing names carries the creation to its far side, where as root it creates + * with privileges. One non-recursive `mkdir` lands inside the directory this call established, nowhere else. + * + * A name that was absent when the walk looked and exists by the time `mkdir` reaches it is JUDGED, not + * refused and not trusted: two processes saving into the same new directory meet here. The entry under the + * name is read by the same single `lstat` every other step is read by and judged by the same rule, which + * accepts a private directory this user owns and refuses a link or a foreign one. A level that passes + * becomes the directory the next name is created in, so creation never follows a name the rule did not take. + */ +function createMissingLevels( + destination: string, + established: string, + missing: readonly string[], + trust: ScriptDestinationTrust, +): void { + let parent = established; + for (const name of missing) { + parent = createMissingLevel(destination, parent, name, trust); + } +} + +/** + * Creates one missing level inside `parent`, or adopts the entry that appeared in its place, and reports the + * directory the next name is created in. + */ +function createMissingLevel( + destination: string, + parent: string, + name: string, + trust: ScriptDestinationTrust, +): string { + const level = path.join(parent, name); + let created = true; + try { + fs.mkdirSync(level, { mode: SCRIPT_DIR_MODE }); + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; + created = false; + } + // The `lstat` of the NAME, taken after the creation attempt, is the judgment either way: what this call + // made and what arrived beside it are read the same way and judged by the same rule. + const seen = lstatEntry(level); + if (seen === undefined || !seen.isDirectory()) { + throw scriptAncestryFailure(destination, level, created ? 'not_a_directory' : 'entry_appeared'); + } + const authority = directoryAuthority(seen); + const exposure = untrustedAncestryExposure(authority, trust); + if (exposure) throw scriptAncestryFailure(destination, level, exposure); + if (created) { + // `mkdir` ANDs its mode with the umask, and a umask can take an OWNER bit away: umask 200 would leave + // this level 0500, where this call could not create the name below it. One `chmod` makes the level the + // mode this rule creates, whatever the host's umask is. + fs.chmodSync(level, SCRIPT_DIR_MODE); + return level; + } + // Somebody else's directory, and the one place this rule asks whether OTHER users could add a name here: + // below a directory they can write, the destination's own name can be made before this call. + if (othersCreateEntriesIn(authority, trust)) { + throw scriptAncestryFailure(destination, level, 'shared_parent'); + } + return level; } function assertSafeDestination(destination: string): void { @@ -159,12 +951,3 @@ function assertSafeDestination(destination: string): void { ); } } - -function lstatIfPresent(pathname: string): fs.Stats | undefined { - try { - return fs.lstatSync(pathname); - } catch (error) { - if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; - throw error; - } -} diff --git a/packages/host-kit/src/internal/verified-file.ts b/packages/host-kit/src/internal/verified-file.ts index 3d0a239074..c692e2b3bb 100644 --- a/packages/host-kit/src/internal/verified-file.ts +++ b/packages/host-kit/src/internal/verified-file.ts @@ -1,5 +1,6 @@ import fs from 'node:fs'; import { AppError } from '@agent-device/kernel/errors'; +import { lstatIfPresent } from './atomic-file.ts'; /** * Both guards are the same failure mode seen from two sides — something other than a plain @@ -132,16 +133,6 @@ function lstatRegularFile(pathname: string): fs.Stats | undefined { return stats; } -/** `lstat` that treats absence as `undefined`; every other errno propagates. */ -export function lstatIfPresent(pathname: string): fs.Stats | undefined { - try { - return fs.lstatSync(pathname); - } catch (error) { - if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; - throw error; - } -} - function sameFile(left: fs.Stats, right: fs.Stats): boolean { return left.dev === right.dev && left.ino === right.ino; } diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts new file mode 100644 index 0000000000..6d1daab97c --- /dev/null +++ b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts @@ -0,0 +1,528 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { expect, test, vi } from 'vitest'; +import type { DaemonResponse } from '@agent-device/kernel/contracts'; +import { FOREIGN_UID, mkdtempForTestSync, serveHostOwnership } from '@agent-device/test-kit'; +import { artifactServer, open } from './support/script-publication-fixtures.ts'; + +// Where a remote recording is allowed to CREATE its file. The daemon answers, the version downloads, and +// the bytes land wherever the destination's own spelling resolves to, so the ground a destination names is +// judged one component at a time the way the kernel walks it (ADR 0016, #4565). A refused destination +// publishes nothing at all: the response is still a success, its script version is not delivered, and no +// file appears in the directory a link led through. What the same rule accepts, and the shape of each +// refusal, is pinned at the walk itself in host-kit's `atomic-file-ancestry.test.ts`; these are the cases +// that only exist once the publication, the download and the record are in the way. + +test.skipIf(process.platform === 'win32')( + 'a remote recording creates a missing parent in a sticky directory and publishes there', + async () => { + // `open --save-script /tmp/rec/journey.ad` with `rec` absent is the ordinary shape, and `/tmp` is + // sticky. Judging the chain before the parent exists asks the question about `/tmp` and refuses a + // recording the local writer accepts, so the parent is created first on both routes (#4565). + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-mkdir-')); + const stateDir = path.join(root, 'state'); + const sticky = path.join(root, 'tmp'); + fs.mkdirSync(sticky); + fs.chmodSync(sticky, 0o1777); + const destination = path.join(sticky, 'recordings', 'journey.ad'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.not.objectContaining({ scriptDeliveryFailure: expect.anything() }), + }), + ); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording creates a missing parent at 0700 on a shared umask', + async () => { + // The umask of a shared checkout: a mode-less creation is 0775, and the check that judges the new + // directory right after the `mkdir` refuses the very directory the route just made, so the save fails + // AND leaves 0775 `recordings` standing where any local user could write. host-kit creates at 0700 and + // a recursive mkdir applies that mode to every level, so the new directory passes the check it is + // judged by and the version lands in it. + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-umask-')); + const stateDir = path.join(root, 'state'); + const home = path.join(root, 'home'); + fs.mkdirSync(home); + fs.chmodSync(home, 0o700); + const recordings = path.join(home, 'workflows', 'recordings'); + const destination = path.join(recordings, 'journey.ad'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + const previous = process.umask(0o002); + let result: Awaited>; + try { + result = await open(baseUrl, stateDir, destination); + } finally { + process.umask(previous); + } + + expect(result.response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.not.objectContaining({ scriptDeliveryFailure: expect.anything() }), + }), + ); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(fs.lstatSync(path.join(home, 'workflows')).mode & 0o777).toBe(0o700); + expect(fs.lstatSync(recordings).mode & 0o777).toBe(0o700); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording creates the entry in the directory the walk judged, not the spelled one', + async () => { + // `home/work -> priv/x`, `priv/y` and `home/elsewhere/y` both private. The version is judged, staged, + // and judged again, and only then does the entry get created: in between, another process may put a + // different directory where `work` stood. Handing the kernel the SPELLD destination for that last + // step asks it to resolve the chain a second time, and it resolves through the new link, so the + // recording lands beside a directory the rule never judged. Creating the entry in the directory the + // walk answered is what keeps it where the judgment said. + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-entry-')); + const stateDir = path.join(root, 'state'); + const home = path.join(root, 'home'); + fs.mkdirSync(home); + fs.chmodSync(home, 0o700); + const privX = path.join(root, 'priv', 'x'); + fs.mkdirSync(privX, { recursive: true }); + fs.chmodSync(path.join(root, 'priv'), 0o700); + const privY = path.join(root, 'priv', 'y'); + fs.mkdirSync(privY); + fs.chmodSync(privY, 0o700); + // `elsewhere/stash` exists so that the SWAPPED link sends `home/work/../y` to `elsewhere/y`: `..` + // applies to the link's target, which is what makes the spelled path answer a different directory + // once `work` points there. + const elsewhere = path.join(home, 'elsewhere'); + fs.mkdirSync(elsewhere); + fs.mkdirSync(path.join(elsewhere, 'stash')); + const elsewhereY = path.join(elsewhere, 'y'); + fs.mkdirSync(elsewhereY); + fs.chmodSync(elsewhere, 0o700); + const link = path.join(home, 'work'); + fs.symlinkSync(privX, link); + const destination = `${home}/work/../y/journey.ad`; + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + // The move happens after the last judgment and before the entry is created: exactly the moment the + // spelled destination would be re-resolved. + const realLinkSync = fs.linkSync; + let moved = false; + vi.spyOn(fs, 'linkSync').mockImplementation(((existing: unknown, newPath: unknown) => { + if (!moved && String(newPath).endsWith('journey.ad')) { + moved = true; + fs.rmSync(link, { force: true }); + fs.symlinkSync(path.join(elsewhere, 'stash'), link); + } + return (realLinkSync as (...args: unknown[]) => unknown)(existing, newPath); + }) as typeof fs.linkSync); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.not.objectContaining({ scriptDeliveryFailure: expect.anything() }), + }), + ); + expect(fs.readdirSync(privY)).toEqual(['journey.ad']); + expect(fs.readdirSync(elsewhereY)).toEqual([]); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording refuses a destination with a missing parent and creates no directories', + async () => { + // The same shape as the case above, with the parent ABSENT: this route creates the missing parent + // itself, so a `mkdir` that runs ahead of the rule leaves `recordings` standing in the open directory + // after the publication refuses — a directory this user made in ground another local user can name + // things in. What exists is asked about before anything is created, so a refused destination publishes + // nothing at all, directories included. + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-stray-')); + const stateDir = path.join(root, 'state'); + const shared = path.join(root, 'shared'); + fs.mkdirSync(shared); + fs.chmodSync(shared, 0o777); + const destination = path.join(shared, 'recordings', 'journey.ad'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ cause: 'script_ancestor_untrusted' }), + }), + }), + ); + expect(fs.readdirSync(shared)).toEqual([]); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording refuses a destination that steps back out of a missing directory', + async () => { + // The walk ends at `missing`, so the world-writable `shared` below it is never judged, and this + // route's `mkdir -p` resolves the two steps up as text and builds `/shared/recordings`. The + // version would then be written into a directory the rule saw nothing of, beside directories left in + // ground another local user owns the naming of. The chain that exists is asked about first, so the + // refusal arrives before the first `mkdir` and nothing is created. + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-upward-')); + const stateDir = path.join(root, 'state'); + const privateDir = path.join(root, 'private'); + fs.mkdirSync(privateDir); + fs.chmodSync(privateDir, 0o700); + const shared = path.join(root, 'shared'); + fs.mkdirSync(shared); + fs.chmodSync(shared, 0o777); + const destination = `${privateDir}/missing/../../shared/recordings/journey.ad`; + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ cause: 'script_ancestor_untrusted' }), + }), + }), + ); + expect(fs.readdirSync(privateDir)).toEqual([]); + expect(fs.readdirSync(shared)).toEqual([]); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording refuses the ground a link target crosses on the way in', + async () => { + // `rec -> /shared/relay/sub`, `shared` at 0777 and not sticky, `shared/relay -> /chosen`. + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-target-')); + const stateDir = path.join(root, 'state'); + const shared = path.join(root, 'shared'); + fs.mkdirSync(shared); + fs.chmodSync(shared, 0o777); + const chosen = path.join(root, 'chosen'); + fs.mkdirSync(chosen); + fs.chmodSync(chosen, 0o700); + fs.symlinkSync(chosen, path.join(shared, 'relay')); + const sub = path.join(chosen, 'sub'); + fs.mkdirSync(sub); + const home = path.join(root, 'home'); + fs.mkdirSync(home); + fs.symlinkSync(path.join(shared, 'relay', 'sub'), path.join(home, 'rec')); + const destination = path.join(home, 'rec', 'journey.ad'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ cause: 'script_ancestor_untrusted' }), + }), + }), + ); + expect(fs.readdirSync(sub)).toEqual([]); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording refuses a target spelled relative to the link that holds it', + async () => { + // `ln -s ../team/rec rec` is how a link is usually written. The target is resolved from the directory + // that holds the link, so the walk leaves the home and crosses `shared` at 0777 on the way in. + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-relative-')); + const stateDir = path.join(root, 'state'); + const shared = path.join(root, 'shared'); + fs.mkdirSync(shared); + fs.chmodSync(shared, 0o777); + const team = path.join(shared, 'team'); + fs.mkdirSync(team); + const chosen = path.join(root, 'chosen'); + fs.mkdirSync(chosen); + fs.chmodSync(chosen, 0o700); + fs.symlinkSync(chosen, path.join(team, 'rec')); + const home = path.join(root, 'home'); + fs.mkdirSync(home); + fs.symlinkSync(path.join('..', 'shared', 'team', 'rec'), path.join(home, 'rec')); + const destination = path.join(home, 'rec', 'journey.ad'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ cause: 'script_ancestor_untrusted' }), + }), + }), + ); + expect(fs.readdirSync(chosen)).toEqual([]); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording stages inside the directory the entry is created in', + async () => { + // `home/work -> priv/x`, `priv/y` private, `home/y` at 0777. The entry lands in `priv/y`, but the + // spelled parent folds to `home`, so staging beside the spelled parent downloads the version into a + // directory the ancestry walk never judged as the entry's, and moves it in by a rename that is no + // longer within one directory. + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-staging-')); + const stateDir = path.join(root, 'state'); + const home = path.join(root, 'home'); + fs.mkdirSync(home); + fs.chmodSync(home, 0o700); + const sharedY = path.join(home, 'y'); + fs.mkdirSync(sharedY); + fs.chmodSync(sharedY, 0o777); + const privX = path.join(root, 'priv', 'x'); + fs.mkdirSync(privX, { recursive: true }); + const privY = path.join(root, 'priv', 'y'); + fs.mkdirSync(privY); + fs.chmodSync(privY, 0o700); + fs.symlinkSync(privX, path.join(home, 'work')); + const destination = `${home}/work/../y/journey.ad`; + const created: string[] = []; + const realMkdtempSync = fs.mkdtempSync; + vi.spyOn(fs, 'mkdtempSync').mockImplementation(((template: string, ...rest: unknown[]) => { + created.push(path.dirname(template)); + return (realMkdtempSync as (...args: unknown[]) => unknown)(template, ...rest); + }) as typeof fs.mkdtempSync); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual(expect.objectContaining({ ok: true })); + expect(created).toEqual([privY]); + expect(fs.readdirSync(sharedY)).toEqual([]); + expect(fs.readFileSync(path.join(privY, 'journey.ad'), 'utf8')).toContain('open Demo'); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording refuses a link another local user owns on the way in', + async () => { + // `~/rec -> /tmp/relay -> ~/chosen`, `relay` another user's file in a sticky shared directory. + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-hopowner-')); + const stateDir = path.join(root, 'state'); + const home = path.join(root, 'home'); + fs.mkdirSync(home); + const chosen = path.join(root, 'chosen'); + fs.mkdirSync(chosen); + const tmp = path.join(root, 'tmp'); + fs.mkdirSync(tmp); + fs.chmodSync(tmp, 0o1777); + const relay = path.join(tmp, 'relay'); + fs.symlinkSync(chosen, relay); + fs.symlinkSync(relay, path.join(home, 'rec')); + serveHostOwnership({ [relay]: FOREIGN_UID }); + const destination = path.join(home, 'rec', 'journey.ad'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ cause: 'script_ancestor_untrusted' }), + }), + }), + ); + expect(fs.readdirSync(chosen)).toEqual([]); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording refuses the directory a .. steps back into', + async () => { + // `home/work -> priv/x`, `priv/y` at 0777: the write lands in `priv/y`, not in the `home/y` the + // normalized spelling names. + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-dotdot-')); + const stateDir = path.join(root, 'state'); + const home = path.join(root, 'home'); + fs.mkdirSync(home); + const priv = path.join(root, 'priv'); + const privX = path.join(priv, 'x'); + fs.mkdirSync(privX, { recursive: true }); + const privY = path.join(priv, 'y'); + fs.mkdirSync(privY); + fs.chmodSync(privY, 0o777); + fs.symlinkSync(privX, path.join(home, 'work')); + const destination = `${home}/work/../y/journey.ad`; + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ cause: 'script_ancestor_untrusted' }), + }), + }), + ); + expect(fs.readdirSync(privY)).toEqual([]); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording refuses a private link standing on shared ground two levels up', + async () => { + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-traverse-')); + const stateDir = path.join(root, 'state'); + const shared = path.join(root, 'shared'); + fs.mkdirSync(shared); + fs.chmodSync(shared, 0o777); + const mine = path.join(shared, 'mine'); + fs.mkdirSync(mine); + fs.chmodSync(mine, 0o700); + const privateWork = path.join(root, 'private'); + fs.mkdirSync(privateWork); + fs.symlinkSync(privateWork, path.join(mine, 'rec')); + const destination = path.join(mine, 'rec', 'journey.ad'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ + cause: 'script_ancestor_untrusted', + }), + }), + }), + ); + expect(fs.readdirSync(privateWork)).toEqual([]); + }, +); + +test.skipIf(process.platform === 'win32')( + 'a remote recording refuses a chain that leaves a shared directory through a link', + async () => { + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-relay-')); + const stateDir = path.join(root, 'state'); + const home = path.join(root, 'home'); + fs.mkdirSync(home); + const team = path.join(root, 'srv', 'team'); + fs.mkdirSync(team, { recursive: true }); + fs.chmodSync(team, 0o777); + const chosen = path.join(root, 'chosen'); + fs.mkdirSync(chosen); + fs.chmodSync(chosen, 0o700); + fs.symlinkSync(chosen, path.join(team, 'relay')); + fs.symlinkSync(path.join(team, 'relay'), path.join(home, 'rec')); + const destination = path.join(home, 'rec', 'journey.ad'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ + cause: 'script_ancestor_untrusted', + }), + }), + }), + ); + expect(fs.readdirSync(chosen)).toEqual([]); + }, +); + +test.skipIf(process.platform === 'win32').each([ + { + name: 'a symbolic link planted where the script should land', + plant: (root: string) => { + const shared = path.join(root, 'shared'); + fs.mkdirSync(shared); + fs.chmodSync(shared, 0o777); + const attacker = path.join(root, 'attacker'); + fs.mkdirSync(attacker); + fs.symlinkSync(attacker, path.join(shared, 'work')); + return { + destination: path.join(shared, 'work', 'journey.ad'), + untouched: attacker, + }; + }, + }, + { + name: 'a world-writable directory', + plant: (root: string) => { + const shared = path.join(root, 'shared'); + fs.mkdirSync(shared); + fs.chmodSync(shared, 0o777); + return { destination: path.join(shared, 'journey.ad'), untouched: shared }; + }, + }, +])('a remote recording refuses a destination under $name', async ({ plant }) => { + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-')); + const stateDir = path.join(root, 'state'); + const { destination, untouched } = plant(root); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ + cause: 'script_ancestor_untrusted', + }), + }), + }), + ); + expect(fs.existsSync(destination)).toBe(false); + expect(fs.readdirSync(untouched)).toEqual([]); +}); + +test.skipIf(process.platform === 'win32')( + 'a remote recording refuses a destination whose directory was swapped while the version downloaded', + async () => { + const root = fs.realpathSync(mkdtempForTestSync('script-ancestry-')); + const stateDir = path.join(root, 'state'); + const work = path.join(root, 'work'); + fs.mkdirSync(work); + const destination = path.join(work, 'journey.ad'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + const realOpen = fs.promises.open.bind(fs.promises); + // The replacement is a private directory, so only the parent's identity can catch it. The swap + // happens once the staged file is open: after the parent's identity was captured. + const spyOpen = vi.spyOn(fs.promises, 'open').mockImplementation(async (file, ...rest) => { + const handle = await realOpen(file as never, ...(rest as unknown as never[])); + fs.rmSync(work, { recursive: true, force: true }); + fs.mkdirSync(work); + return handle; + }); + + let response: DaemonResponse; + try { + response = (await open(baseUrl, stateDir, destination)).response; + } finally { + spyOpen.mockRestore(); + } + + expect(response).toEqual( + expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ cause: 'script_ancestry_replaced' }), + }), + }), + ); + expect(fs.readdirSync(work)).toEqual([]); + }, +); diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts index 49b1aa6789..b1fa15df04 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts @@ -1,61 +1,29 @@ import fs from 'node:fs'; -import http from 'node:http'; import path from 'node:path'; import { afterEach, expect, test, vi } from 'vitest'; -import type { DaemonWireRequest } from '@agent-device/contracts/command'; -import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; +import type { DaemonResponse } from '@agent-device/kernel/contracts'; import * as file from '@agent-device/host-kit/file'; -import { - closeLoopbackServer, - createTestHostEnvironment, - listenOnLoopback, - mkdtempForTestSync, -} from '@agent-device/test-kit'; import { AppError } from '@agent-device/kernel/errors'; -import { materializeRemoteArtifacts } from '../daemon-artifacts.ts'; +import { mkdtempForTestSync } from '@agent-device/test-kit'; import { sendRemoteScriptOpen } from '../session-script-destination.ts'; +import { + answer, + artifactServer, + open, + records, + request, + script, +} from './support/script-publication-fixtures.ts'; vi.mock('@agent-device/host-kit/file', async (importOriginal) => { const actual = await importOriginal(); return { ...actual, publishFileSync: vi.fn(actual.publishFileSync) }; }); -type Served = { body: string; broken?: boolean; endless?: boolean }; -const servers: http.Server[] = []; - -afterEach(async () => { +afterEach(() => { vi.mocked(file.publishFileSync).mockClear(); - await Promise.all(servers.splice(0).map((server) => closeLoopbackServer(server))); }); -async function artifactServer(artifacts: Record): Promise { - const server = http.createServer((req, res) => { - const artifact = artifacts[decodeURIComponent(req.url?.replace(/^\/+artifacts\//, '') ?? '')]; - if (!artifact) { - res.writeHead(404).end(); - return; - } - if (artifact.endless) { - res.writeHead(200); - const write = () => { - if (!res.destroyed) res.write(artifact.body, () => setImmediate(write)); - }; - write(); - return; - } - res.writeHead(200, { 'content-length': Buffer.byteLength(artifact.body) }); - if (!artifact.broken) { - res.end(artifact.body); - return; - } - res.flushHeaders(); - res.write(artifact.body.slice(0, 4)); - setImmediate(() => res.destroy()); - }); - servers.push(server); - return `http://127.0.0.1:${await listenOnLoopback(server)}`; -} - function journey() { // The real path, so a destination names the same file the publication renames into place. const root = fs.realpathSync(mkdtempForTestSync('script-download-')); @@ -63,44 +31,6 @@ function journey() { return { root, stateDir, destination: path.join(root, 'caller', 'journey.ad') }; } -function request(command: string, meta: DaemonWireRequest['meta'] = {}): DaemonWireRequest { - return { token: 't', session: 'journey', command, positionals: [], meta }; -} - -function script(artifactId: string, revision: number, publicationId: string): DaemonArtifact { - return { - field: 'savedScript', - artifactType: 'session-script', - artifactId, - scriptPublicationId: publicationId, - scriptRevision: revision, - }; -} - -function records(stateDir: string): string[] { - const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); - return fs.existsSync(directory) - ? fs.readdirSync(directory).filter((n) => n.endsWith('.json')) - : []; -} - -/** Answers a request the way the daemon does and materializes the answer like the client. */ -function answer( - baseUrl: string, - stateDir: string, - req: DaemonWireRequest, - data: Record, -): Promise { - const info = { baseUrl, token: 't' }; - return materializeRemoteArtifacts( - info, - req, - { ok: true, data }, - createTestHostEnvironment(), - stateDir, - ); -} - /** A successful response whose script version could not be saved on this machine. */ function deliveryFailure(cause: string) { return expect.objectContaining({ @@ -112,35 +42,6 @@ function deliveryFailure(cause: string) { }); } -/** A remote `open --save-script`: the daemon arms the publication it is sent, with version 1. */ -async function open( - baseUrl: string, - stateDir: string, - destination: string, - options: { force?: boolean; respond?: (id: string) => DaemonResponse } = {}, -) { - let sent: DaemonWireRequest | undefined; - let recordsAtSend: string[] = []; - const req = { - ...request('open', { clientArtifactPaths: { savedScript: destination } }), - flags: { saveScript: true, ...(options.force ? { force: true } : {}) }, - }; - const info = { baseUrl, token: 't', capabilities: ['script-artifacts'] }; - const response = await sendRemoteScriptOpen(info, req, stateDir, async (next) => { - sent = next; - recordsAtSend = records(stateDir); - const id = next.meta?.scriptPublicationId as string; - const reply = options.respond?.(id); - if (reply) return reply; - return answer(baseUrl, stateDir, next, { - scriptPublicationId: id, - artifacts: [script('v1', 1, id)], - }); - }); - const id = sent?.meta?.scriptPublicationId as string; - return { id, sent, recordsAtSend, response }; -} - test('an open records its destination before it is sent, and sends only its publication ID', async () => { const { stateDir, destination } = journey(); const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); diff --git a/packages/remote/src/__tests__/support/script-publication-fixtures.ts b/packages/remote/src/__tests__/support/script-publication-fixtures.ts new file mode 100644 index 0000000000..c327c65086 --- /dev/null +++ b/packages/remote/src/__tests__/support/script-publication-fixtures.ts @@ -0,0 +1,127 @@ +import fs from 'node:fs'; +import http from 'node:http'; +import path from 'node:path'; +import { onTestFinished } from 'vitest'; +import type { DaemonWireRequest } from '@agent-device/contracts/command'; +import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; +import { + closeLoopbackServer, + createTestHostEnvironment, + listenOnLoopback, +} from '@agent-device/test-kit'; +import { materializeRemoteArtifacts } from '../../daemon-artifacts.ts'; +import { sendRemoteScriptOpen } from '../../session-script-destination.ts'; + +/** + * The client side of a remote script publication: a daemon that serves versions over HTTP, and the `open` + * that arms a publication and downloads its first version. Shared because two files pin this route — + * `daemon-artifacts-script-download` for what a publication records and delivers, and + * `daemon-artifacts-script-ancestry` for the ground a destination may be created in. + */ + +/** What one artifact route of the fake daemon serves. */ +export type Served = { body: string; broken?: boolean; endless?: boolean }; + +/** + * A daemon that serves script versions over HTTP. Closed when the calling test finishes, so a suite that + * opens several publications leaves no listener behind. + */ +export async function artifactServer(artifacts: Record): Promise { + const server = http.createServer((req, res) => { + const artifact = artifacts[decodeURIComponent(req.url?.replace(/^\/+artifacts\//, '') ?? '')]; + if (!artifact) { + res.writeHead(404).end(); + return; + } + if (artifact.endless) { + res.writeHead(200); + const write = () => { + if (!res.destroyed) res.write(artifact.body, () => setImmediate(write)); + }; + write(); + return; + } + res.writeHead(200, { 'content-length': Buffer.byteLength(artifact.body) }); + if (!artifact.broken) { + res.end(artifact.body); + return; + } + res.flushHeaders(); + res.write(artifact.body.slice(0, 4)); + setImmediate(() => res.destroy()); + }); + onTestFinished(() => closeLoopbackServer(server)); + return `http://127.0.0.1:${await listenOnLoopback(server)}`; +} + +export function request(command: string, meta: DaemonWireRequest['meta'] = {}): DaemonWireRequest { + return { token: 't', session: 'journey', command, positionals: [], meta }; +} + +export function script( + artifactId: string, + revision: number, + publicationId: string, +): DaemonArtifact { + return { + field: 'savedScript', + artifactType: 'session-script', + artifactId, + scriptPublicationId: publicationId, + scriptRevision: revision, + }; +} + +/** The publication records the client has written for this state directory. */ +export function records(stateDir: string): string[] { + const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); + return fs.existsSync(directory) + ? fs.readdirSync(directory).filter((n) => n.endsWith('.json')) + : []; +} + +/** Answers a request the way the daemon does and materializes the answer like the client. */ +export function answer( + baseUrl: string, + stateDir: string, + req: DaemonWireRequest, + data: Record, +): Promise { + const info = { baseUrl, token: 't' }; + return materializeRemoteArtifacts( + info, + req, + { ok: true, data }, + createTestHostEnvironment(), + stateDir, + ); +} + +/** A remote `open --save-script`: the daemon arms the publication it is sent, with version 1. */ +export async function open( + baseUrl: string, + stateDir: string, + destination: string, + options: { force?: boolean; respond?: (id: string) => DaemonResponse } = {}, +) { + let sent: DaemonWireRequest | undefined; + let recordsAtSend: string[] = []; + const req = { + ...request('open', { clientArtifactPaths: { savedScript: destination } }), + flags: { saveScript: true, ...(options.force ? { force: true } : {}) }, + }; + const info = { baseUrl, token: 't', capabilities: ['script-artifacts'] }; + const response = await sendRemoteScriptOpen(info, req, stateDir, async (next) => { + sent = next; + recordsAtSend = records(stateDir); + const id = next.meta?.scriptPublicationId as string; + const reply = options.respond?.(id); + if (reply) return reply; + return answer(baseUrl, stateDir, next, { + scriptPublicationId: id, + artifacts: [script('v1', 1, id)], + }); + }); + const id = sent?.meta?.scriptPublicationId as string; + return { id, sent, recordsAtSend, response }; +} diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 552e455650..fce74da2ab 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -8,9 +8,18 @@ import type { ScriptDeliveryFailure, } from '@agent-device/kernel/contracts'; import { readResponseWarnings } from '@agent-device/kernel/success-text'; +import { AppError } from '@agent-device/kernel/errors'; import { assertScriptArtifactsCapability } from '@agent-device/daemon-contracts/daemon-resolution'; import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; -import { acquireProcessLock, publishFileSync, withProcessLock } from '@agent-device/host-kit/file'; +import { + acquireProcessLock, + confirmScriptDestination, + scriptAncestryReason, + prepareScriptDestination, + publishFileSync, + withProcessLock, + type ScriptDestination, +} from '@agent-device/host-kit/file'; import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; import type { DaemonArtifactEndpoint, downloadRemoteArtifact } from './daemon-artifacts.ts'; @@ -189,14 +198,18 @@ async function publishScriptVersion( return { published: undefined }; } if ((revision as number) <= record.revision) return { published: record.destination }; - const directory = path.dirname(record.destination); const pending = { named: false }; let staging: string | undefined; try { - await fs.promises.mkdir(directory, { recursive: true }); - staging = await withRecordLock(file, async () => allocateStaging(file, directory)); - if (!staging) return { published: undefined }; - const staged = path.join(staging, 'script.ad'); + // host-kit owns the creation sequence (#4565): walk, refuse before anything is created, create what + // is missing at 0700 inside the judged directory, judge the completed chain. A destination this route + // refuses therefore leaves no directories behind in the shared ground it names, and the answer is where + // staging goes, so this route is not walked twice to be told the same directory. + const prepared = prepareScriptDestination(record.destination); + const allocated = await withRecordLock(file, async () => allocateStaging(file, prepared)); + staging = allocated; + if (!allocated) return { published: undefined }; + const staged = path.join(allocated, 'script.ad'); await context.download({ ...endpoint, artifactId: artifactId as string, @@ -204,7 +217,14 @@ async function publishScriptVersion( requestScope: req.meta, privateFile: { maxBytes: MAX_SCRIPT_BYTES }, }); - const version = { revision: revision as number, staging, staged, pending }; + const version = { + revision: revision as number, + staging: allocated, + staged, + // What host-kit answered above, carried for the one confirmation before the rename. + prepared, + pending, + }; return { published: await withRecordLock(file, async () => publishStaged(file, version)) }; } catch (error) { const closing = req.command === 'close'; @@ -221,11 +241,18 @@ async function publishScriptVersion( } } -/** Creates a staging directory and lists it in the record before any script bytes reach it. */ -function allocateStaging(file: string, directory: string): string | undefined { +/** + * Creates a staging directory beside the destination and lists it in the record before any script bytes + * reach it, answering the directory it made, or nothing when the record went away. + * + * Staging sits in the directory the walk JUDGED — its answer, not `path.dirname` of the spelled destination: + * where a `..` or a link leads elsewhere, the spelled parent is ground nobody judged, and a directory in it + * is one another local user can populate before the rename does. + */ +function allocateStaging(file: string, prepared: ScriptDestination): string | undefined { const record = readRecord(file); if (!record) return undefined; - const staging = fs.mkdtempSync(path.join(directory, '.agent-device-script-')); + const staging = fs.mkdtempSync(path.join(prepared.directory, '.agent-device-script-')); try { writeRecord(file, { ...record, staging: [...(record.staging ?? []), staging] }); } catch (error) { @@ -313,10 +340,11 @@ function publishStaged( revision: number; staging: string; staged: string; + prepared: ScriptDestination; pending: { named: boolean }; }>, ): string | undefined { - const { revision, staging, staged, pending } = version; + const { revision, staging, staged, prepared, pending } = version; const record = readRecord(file); if (!record) return undefined; let current = settlePublishing(record); @@ -327,15 +355,24 @@ function publishStaged( current = withoutStaging(current, record.publishing.staging); } if (revision <= current.revision) return current.destination; + // Confirmed here, under the record lock and right before the entry is created, because the download ran + // in between: host-kit walks the destination again and refuses if it now answers a DIFFERENT directory + // than the one staging was allocated in, so bytes are never renamed into ground nobody judged (#4565). + const judged = confirmScriptDestination(current.destination, prepared); const publishing = { revision, file: fileIdentity(staged) ?? 'missing', staging }; // A second name keeps the inode on disk after the rename while the record may name it. fs.linkSync(staged, `${staged}.anchor`); writeRecord(file, { ...current, publishing }); pending.named = true; const exclusive = current.revision === 0 && !current.force; + // The entry is created in the directory THAT ANSWER came back with, spelled from it, and never through + // the destination's own spelling: handing the kernel the spelled destination makes it resolve the chain + // a second time, after the judgment, and `home/work/../y` names a different directory the moment `work` + // is pointed elsewhere. Same rule the local publisher applies. + const entry = path.join(judged, path.basename(current.destination)); try { - if (exclusive) fs.linkSync(staged, current.destination); - else fs.renameSync(staged, current.destination); + if (exclusive) fs.linkSync(staged, entry); + else fs.renameSync(staged, entry); } catch (error) { writeRecord(file, settlePublishing({ ...current, publishing })); pending.named = false; @@ -367,6 +404,19 @@ function scriptDeliveryFailure( ): ScriptDeliveryFailure { // Only the exclusive link of the first version can find an existing entry. const exists = (error as NodeJS.ErrnoException | undefined)?.code === 'EEXIST'; + const refusal = scriptAncestryReason(error); + if (refusal) { + return { + reason: 'script_delivery_failed', + cause: refusal, + publicationId, + message: + error instanceof AppError + ? error.message + : `The remote script could not be saved to ${destination}.`, + hint: error instanceof AppError ? (error.details?.hint ?? '') : '', + }; + } const recovery = closing ? 'The session is closed, so no later version follows.' : 'The next recorded action or close delivers the full recording again.'; diff --git a/packages/test-kit/src/host-ownership.fixtures.ts b/packages/test-kit/src/host-ownership.fixtures.ts new file mode 100644 index 0000000000..51fe1a3ec9 --- /dev/null +++ b/packages/test-kit/src/host-ownership.fixtures.ts @@ -0,0 +1,80 @@ +import fs from 'node:fs'; +import { vi } from 'vitest'; + +/** Some other local user: not the one running the suite, and not root. */ +export const FOREIGN_UID = 65534; + +/** + * Reports the ids in `owners` for the paths named there, and the real host for every other path, so an + * ownership rule is decided by the fixture rather than by the account the suite happens to run under. + * + * A rule that is about to CHANGE an entry asks the id of the DESCRIPTOR it will change, not of the name it + * was handed, so the ids are served through `fstat` too — through which path is recorded at `open` time. + * Only the ids move: modes and inode numbers stay what they are on disk. A real foreign owner needs + * privileges a test does not have — an unprivileged process cannot `chown` — and moving the CALLER's uid + * instead decides the test by which directories the scratch tree happens to sit under. + */ +export function serveHostOwnership( + owners: Readonly>, + moved?: Readonly<{ throughDescriptorOnly: boolean }>, +): HostOwnershipProbe { + // Captured before the spies are installed, so a forwarded call reaches the host and not this fixture. + const real = { + lstat: fs.lstatSync.bind(fs), + stat: fs.statSync.bind(fs), + open: fs.openSync.bind(fs), + fstat: fs.fstatSync.bind(fs), + close: fs.closeSync.bind(fs), + }; + const openedOn = new Map(); + const openedNames: string[] = []; + const closedDescriptors: number[] = []; + // Ids come back as bigint or as numbers depending on the caller, so a moved id keeps that type. + const reuid = (stats: S, pathname: string | undefined): S => { + const uid = pathname === undefined ? undefined : owners[pathname]; + if (uid === undefined || BigInt(stats.uid) === BigInt(uid)) return stats; + return Object.assign(Object.create(Object.getPrototypeOf(stats)), stats, { + uid: typeof stats.uid === 'bigint' ? BigInt(uid) : uid, + }) as S; + }; + // `throughDescriptorOnly` moves the id of the DESCRIPTOR an open reached and nothing else: the shape of + // a name swapped for a foreign entry between the `lstat` and the open, so only what a descriptor answers + // sees it, and the name still answers this process's own id. + if (moved?.throughDescriptorOnly !== true) { + vi.spyOn(fs, 'lstatSync').mockImplementation(((name: never, ...rest: never[]) => + reuid(real.lstat(name, ...rest), String(name))) as typeof fs.lstatSync); + vi.spyOn(fs, 'statSync').mockImplementation(((name: never, ...rest: never[]) => + reuid(real.stat(name, ...rest), String(name))) as typeof fs.statSync); + } + vi.spyOn(fs, 'openSync').mockImplementation(((name: never, ...rest: never[]) => { + const descriptor = Reflect.apply(real.open, fs, [name, ...rest]) as number; + openedOn.set(descriptor, String(name)); + openedNames.push(String(name)); + return descriptor; + }) as typeof fs.openSync); + vi.spyOn(fs, 'fstatSync').mockImplementation(((fd: never, ...rest: never[]) => + reuid( + Reflect.apply(real.fstat, fs, [fd, ...rest]) as fs.Stats, + typeof fd === 'number' ? openedOn.get(fd) : undefined, + )) as typeof fs.fstatSync); + vi.spyOn(fs, 'closeSync').mockImplementation(((fd: never, ...rest: never[]) => { + if (typeof fd === 'number') closedDescriptors.push(fd); + return Reflect.apply(real.close, fs, [fd, ...rest]) as void; + }) as typeof fs.closeSync); + return { + openedNames: () => [...openedNames], + closedDescriptors: () => [...closedDescriptors], + descriptorFor: (target: string) => [...openedOn].find(([, name]) => name === target)?.[0], + }; +} + +/** + * What {@link serveHostOwnership} also watched, for a rule that has to answer about a DESCRIPTOR rather than + * a name: which names were opened, in order, and which descriptors were closed. A caller proves a descent + * stopped by the names that were NOT opened, and proves a descriptor did not leak by finding it closed. + */ +export type HostOwnershipProbe = Readonly<{ + openedNames: () => readonly string[]; + closedDescriptors: () => readonly number[]; + descriptorFor: (target: string) => number | undefined; +}>; diff --git a/packages/test-kit/src/index.ts b/packages/test-kit/src/index.ts index 5d74593d59..609a3c9f50 100644 --- a/packages/test-kit/src/index.ts +++ b/packages/test-kit/src/index.ts @@ -122,6 +122,11 @@ export { unavailableDeploymentSnapshotAndShutdownOperationFacts, } from './runtime-operation-facts.ts'; export { createTestRuntimeStateHandle, type TestRuntimeStateHandle } from './runtime-state.ts'; +export { + FOREIGN_UID, + serveHostOwnership, + type HostOwnershipProbe, +} from './host-ownership.fixtures.ts'; export { buildNodes } from './snapshot-builders.ts'; export { bottomTabsRealCaptureFixture, diff --git a/src/__tests__/daemon-launch-cwd.test.ts b/src/__tests__/daemon-launch-cwd.test.ts index 9c50f689aa..2bb9886731 100644 --- a/src/__tests__/daemon-launch-cwd.test.ts +++ b/src/__tests__/daemon-launch-cwd.test.ts @@ -52,14 +52,21 @@ test.skipIf(process.platform === 'win32').for(['fresh', 'loose'])( ); test.for(['EPERM', 'EROFS'])( - 'a launched daemon starts when chmod on its state paths fails with %s', + 'a launched daemon starts when forcing a mode on its state paths fails with %s', async (code) => { const paths = resolveDaemonPaths( path.join(mkdtempForTestSync('agent-device-launch-chmod-'), 'state'), ); - const chmod = vi.spyOn(fs, 'chmodSync').mockImplementation(() => { + // A state directory an older version left group-writable, so the repair has something to do. + fs.mkdirSync(paths.baseDir, { mode: 0o755 }); + fs.chmodSync(paths.baseDir, 0o775); + // Neither way of forcing a mode works: a mount that refuses chmod, or one whose semantics this host + // does not implement. Startup reports that and starts anyway rather than dying on a host it cannot fix. + const failing = () => { throw Object.assign(new Error(code), { code }); - }); + }; + const chmod = vi.spyOn(fs, 'chmodSync').mockImplementation(failing); + const fchmod = vi.spyOn(fs, 'fchmodSync').mockImplementation(failing); try { const launch = launchDaemonProcess({ env: process.env, @@ -68,13 +75,31 @@ test.for(['EPERM', 'EROFS'])( args: ['-e', ''], serverMode: 'socket', }); + await launch.exited; + + // Each path is asked for the mode in the one way that is safe for it: the state DIRECTORY through a + // descriptor opened on the entry the repair judged, so the mode cannot travel through a planted link, + // and the log FILE by its name. + assert.deepEqual( + fchmod.mock.calls.map(([, mode]) => mode), + [0o700], + ); + assert.deepEqual( + chmod.mock.calls.map(([target]) => target), + [paths.logPath], + ); + assert.deepEqual( + fchmod.mock.calls.map(([, mode]) => mode), + [0o700], + ); assert.deepEqual( chmod.mock.calls.map(([target]) => target), - [paths.baseDir, paths.logPath], + [paths.logPath], ); } finally { chmod.mockRestore(); + fchmod.mockRestore(); } }, ); diff --git a/test/wire-compat/closure-policy.ts b/test/wire-compat/closure-policy.ts index 84a93c1a70..5e1533e455 100644 --- a/test/wire-compat/closure-policy.ts +++ b/test/wire-compat/closure-policy.ts @@ -49,6 +49,8 @@ export const WIRE_CLOSURE_WAIVERS: Readonly> = { 'Server-side narrowing of the listed kernel DaemonRequest; the declaration that fixes the shape is packages/kernel/src/contracts.ts#DaemonRequest.', 'packages/contracts/src/daemon-wire-request.ts#DaemonWireRequest': 'Client-side narrowing of the listed kernel DaemonRequest (token and session required, flags typed as CommandFlags); the declaration that fixes the shape is packages/kernel/src/contracts.ts#DaemonRequest.', + 'packages/remote/src/session-script-destination.ts#PublishOutcome': + "The CLIENT'S OWN result of one publish attempt: the published path, or a failure plus the local error object behind it. Only the failure half is ever serialized, into `data.scriptDeliveryFailure`, and that payload is the listed packages/kernel/src/contracts.ts#ScriptDeliveryFailure; the `error` member is a local unknown thrown value that never reaches the peer.", 'packages/remote/src/upload-stream.ts#UploadStreamProgressOptions': 'Byte-progress callback options for local upload rendering. The bytes counted are digested through the request/response declarations; these options never cross the wire.', 'packages/remote/src/upload-progress.ts#UploadProgressSink': diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index bdabba0ca5..c0ab8688d6 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -214,12 +214,17 @@ "packages/daemon-contracts/src/daemon-resolution.ts#readDaemonCapabilities": "sha256:e410d36be74d307f7e5d8ddae63af5aae77f8eef77951ce9eeb7724f2fefae88", "packages/remote/src/daemon-artifacts.ts#downloadResponseArtifacts": "sha256:42d78f01311e3e0c5f9099ef72e3c6258241e66204747aa176a55cd5191a2145", "packages/remote/src/session-script-destination.ts#SessionScriptDelivery": "sha256:741fafbb8e2b43e2e967b2f4206f1d60017a636f63e3cde68b6258fd4efefa18", - "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:9d6ceb538019c0ce30813fcf98d2484c5abc2d8fd7a3dfdd4141cf6430f086ff", + "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:26dab1cad75b1f8165b1da1d64af2f50d3ff9b7412b45411479f5d7048aaa54b", "packages/remote/src/session-script-destination.ts#PublishOutcome": "sha256:a4ae6fc3298d3c560719591372edddbfa83ce749f4cf3f3e2ed1d8369313bd2d", "packages/remote/src/session-script-destination.ts#sendRemoteScriptOpen": "sha256:10ab07a6f276c7b03996c6b46fa218e03e7b1d21e2c95df5515dfb88095416b6", "packages/remote/src/session-script-destination.ts#RemoteEndpoint": "sha256:9c48e8e0ee14a25b85ebd930243fd263134836b35ecda55fb927919911263c15" }, "compatibleChanges": [ + { + "declaration": "packages/remote/src/session-script-destination.ts#publishScriptVersion", + "digest": "sha256:26dab1cad75b1f8165b1da1d64af2f50d3ff9b7412b45411479f5d7048aaa54b", + "rationale": "#4565 changes only how the caller resolves and stages a destination locally. The route, its request fields, its response fields, its status and its artifact framing are untouched, and so is the download contract this declaration consumes. Host-kit owns the sequence: it walks the destination and refuses it before creating anything, creates each missing level at 0700 inside the directory it judged, and answers with that directory and its identity; the route stages each version inside the directory that answer names and, after the download, confirms it through host-kit's one confirmation call before the rename. The digest has moved twice since that ack was first written, each time for local shape alone: the allocation step now answers the staging directory itself instead of returning the prepared destination back to its caller, and the locals it hands on are named for what they are. Neither is a field, a route or a payload, so a released daemon receives the same request and answers the same way, a released caller resolves the same paths on its own disk, and a skewed peer parses every payload as before." + }, { "declaration": "packages/kernel/src/contracts.ts#DaemonRequestMeta", "digest": "sha256:c2b14225388041f3a6e708c898c512f91b9b20e51a2656a1fa0d5bfa5989fa30", @@ -233,7 +238,7 @@ { "declaration": "packages/remote/src/daemon-artifacts.ts#DownloadRemoteArtifactParams", "digest": "sha256:3b0678250f72dca4ac1709103fd4c540dedd4d488eb3299ace5ce6b7c479676c", - "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state — never serialized, never sent to the daemon — that tells the CLIENT'S OWN download logic to extract a tar body instead of writing it verbatim; the GET /artifacts/:id request and response framing are unchanged. Every existing call site (screenshot, recording) omits it and keeps writing a single file exactly as before. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved. #4511 adds the optional client-local privateFile field, passed through to the downloader. It is never sent, and every existing call site omits it." + "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state \u2014 never serialized, never sent to the daemon \u2014 that tells the CLIENT'S OWN download logic to extract a tar body instead of writing it verbatim; the GET /artifacts/:id request and response framing are unchanged. Every existing call site (screenshot, recording) omits it and keeps writing a single file exactly as before. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved. #4511 adds the optional client-local privateFile field, passed through to the downloader. It is never sent, and every existing call site omits it." }, { "declaration": "packages/remote/src/daemon-artifacts.ts#downloadRemoteArtifact", @@ -308,7 +313,7 @@ { "declaration": "packages/daemon/src/server/http/http-authorization.ts#authorizeAuxiliaryHttpRequest", "digest": "sha256:1c323f97c3cefec8f95633b6abd127342bf75494bfb109d1cc6eadf3ceacaeae", - "rationale": "#2198 context: adds one optional field to the value this DAEMON-INTERNAL gate hands its own route handlers — sessionNamespace, the caller's tenant plus whether the daemon partitioned that caller's session names. Nothing about it is serialized: no request header is read that was not read before, no response field is added, and a refusal keeps the same 401 {ok:false,error,code} REST body sendRestJsonError already sent. What it enables is a refusal DROPPED, never one added — an unattested (client-declared) tenant no longer has the : prefix rule applied to it, because scopeRequestSession never applied that prefix to its sessions either. A released peer that now gets 200 where it got 401 is getting the ndjson record it asked for and already parses." + "rationale": "#2198 context: adds one optional field to the value this DAEMON-INTERNAL gate hands its own route handlers \u2014 sessionNamespace, the caller's tenant plus whether the daemon partitioned that caller's session names. Nothing about it is serialized: no request header is read that was not read before, no response field is added, and a refusal keeps the same 401 {ok:false,error,code} REST body sendRestJsonError already sent. What it enables is a refusal DROPPED, never one added \u2014 an unattested (client-declared) tenant no longer has the : prefix rule applied to it, because scopeRequestSession never applied that prefix to its sessions either. A released peer that now gets 200 where it got 401 is getting the ndjson record it asked for and already parses." }, { "declaration": "packages/daemon/src/server/request-diagnostics-http.ts#RequestDiagnosticsHttpAuthorizer", diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 44cd873478..218f8b5521 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -108,6 +108,11 @@ Outside a macOS app lease, a fresh `open --save-script=` records the sessi your machine. Each response that records an action returns a `session-script` artifact, and the client replaces the file with it. `close` returns the final script. The client writes only to the path that its own `open` named. If the file already exists, `open` fails unless you pass `--force`. +Every directory the write travels through must be one that no other local user can change; see +[Record a replay script](replay-e2e.md#record-a-replay-script). That check reads owners, permission +bits and link shape on your machine, so an access control list, a network mount, or a mount that +appears over a checked directory is outside it: the file is written at mode `0600`, but that is not +a promise that nobody else can read it. Choose a directory only you can write. The daemon must report the `script-artifacts` capability in its `/health` response; through a proxy, the upstream daemon's health response must report it. Otherwise `open --save-script` is refused before the session starts. @@ -119,7 +124,16 @@ than 8 MiB. The command still succeeds, and the file may keep the previous versi action or `close` delivers the full recording again. If `close` cannot deliver the final script, the session still closes and the file keeps the version from the last action. Every result that recorded a version discloses it: the CLI prints a warning and carries a typed -`scriptDeliveryFailure` in `--json`, and the SDK and MCP results carry the same field. +`scriptDeliveryFailure` in `--json`, and the SDK and MCP results carry the same field. Its `cause` +names why: a daemon that cannot call its own state directory private ground refuses every version it +picks a path for with `state_chain_untrusted` — for example one whose state tree a container or a +mounted volume left to another uid, or one whose state directory sits inside a directory other local +users can write. That daemon still starts and answers every other command, and +the fix is on the daemon host: make its user own the state directory and every directory above it, or point +`AGENT_DEVICE_STATE_DIR` at a directory it owns. That check of the daemon's own directories is best +effort, and it runs after they are created rather than before, so a state directory it refuses can +leave an empty directory behind, beyond a link it rejected. No version is ever written into what it +leaves: the refusal above is what stops the delivery. Remote `session save-script`, `close --save-script`, `replay --save-script`, and `--save-script` in batch steps are refused. A `batch` whose steps would close the recording is refused before any step diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index d34e6eb31c..3c79067745 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -70,8 +70,16 @@ To choose the output file, pass a path to `--save-script`: agent-device open Settings --platform ios --session e2e --save-script ./workflows/e2e-settings.ad ``` -- Missing parent directories are created. +- Missing parent directories are created, one at a time, and only once the directories above them pass the check below. Each new directory is created at mode `0700`, whatever your umask, because a new directory has to pass the same check a later recording judges it by: under the usual shared-checkout umask, a plain creation would be `0775` and would then be refused as group-writable. A destination that is refused leaves no new directories behind, even where its parent was missing. A path that steps back out of a directory that does not exist yet (`private/missing/../../shared/recordings`) is refused rather than created into existence: the directories it names would be built by a rule that never judged them. The script file is created at mode `0600`, so its own permissions open it to nobody but you. What those permissions do not settle for you is listed under the limits below. +- Every directory the write travels through must be one that no other local user can change. Each must be owned by you or by root, and its permissions must keep its contents closed to everyone else. Another local user who owns such a directory, or who can write in it, can replace a directory on the path or leave a symbolic link there, and the script then lands where they choose. +- The check follows the path the way the system does, one name at a time, and judges every directory it looks a name up in. So a plain directory that is open to others cannot hide a link into a private destination (`rec -> shared/relay/sub`, where `shared/relay` is itself a link), and a link inside a link cannot hide the directory it crosses. A link written as `ln -s ../team/rec rec` is followed from the directory that holds it, and a `..` inside it is applied one step at a time. A `..` in the path you typed is applied to the directory the walk actually reached, not to the text: where `work` is a link, `work/../x` lands beside the link's target, and that is the directory judged. A relative path such as `./workflows/journey.ad` is expanded against your working directory first, and the whole chain from the root is then checked, so a working directory that sits in ground others can write is refused too. The file is written into that same resolved directory, temp file included, so nothing is staged in a directory the check never reached. Where the check cannot reach the directory your path names, because a name inside it does not exist, the save is refused instead of writing beside the closest directory it did reach. Following more links than the system allows is refused rather than trusted. +- Every symbolic link the path follows is checked wherever it leads, at any depth, not only the ones you typed. A link is refused if another user could have placed it, or could replace it: in a directory where others may add entries, only a link you or root own, held in place by the sticky bit, is trusted. Its own permission bits are not consulted: on Linux every link reports the same mode. Root-owned system links such as macOS `/tmp` and `/var` keep working. +- A directory you or root own may still be passed through when it carries the sticky bit (`chmod +t`) and is open to others, because that bit stops anyone but an entry's owner or root from replacing an entry: macOS `/tmp` works this way. A sticky directory owned by somebody else is refused — both bits shield other users from its owner, not the owner from you. The script is never created *inside* a directory others may add entries to: there, anyone could create your file's name first. A group-writable directory is refused, including one you own whose group is your own private group — the shape Ubuntu and Debian give home directories, and a shared checkout at `0775`. The check cannot tell from the host's own account files who else belongs to that group — a name service can hold a member those files never show — so it refuses on the mode alone and names the fix: `chmod g-w ` closes the directory to its group and makes the destination acceptable. +- Limits. The checks read owners, permission bits and link shape, and three things sit outside them. An access control list is consulted before the permission bits, so a directory at `0700` can still grant everyone write through an ACL, and a file at `0600` can still grant everyone read; the checks do not read ACLs. On a network mount (NFS, SMB, FUSE), ownership and mode are whatever the server answers, and the user ids there are usually not the ones on this machine. A mount can also appear over a checked directory. So these checks mean that no other local user can steer where the recording is written on a local filesystem without ACLs on that path; they are not a promise that nobody else can read the file. On a host like that, choose a directory only you can write. +- A refused destination names the directory at fault. A local `close` fails and keeps its bytes. A remote recording keeps its success and reports `script_ancestor_untrusted` as the `scriptDeliveryFailure` cause, and the next recorded action or `close` repeats the refusal. Choose a directory you own that only you can write. - With a local daemon, the script is written on the daemon host when the session closes. +- When the daemon chooses where a recording goes, it writes only on ground it owns. That is every remote recording version, and a recording you did not name a path for. If your user cannot call the daemon's state directory its own — because a container or a mounted volume left it to another uid, or because it sits inside a directory other local users can write — the daemon still starts and every other command works, but those recordings are not delivered: each one is refused with `state_chain_untrusted`. A path you name with `--save-script` is checked by the rules above and is not affected. Make the daemon's user own the state directory and every directory above it, or point `AGENT_DEVICE_STATE_DIR` at a directory it owns. +- That check of the daemon's own directories is best effort, and it happens after they are created, not before. So a state directory the checks refuse can leave an empty directory behind, beyond a link they rejected. Nothing is ever written into it: the refusal above is what stops the recording, and the rules above refuse any file under that tree. - With a remote daemon, outside a macOS app lease, the path is on your machine. The file appears when `open` returns, and each later recorded action in the session replaces it with the recording so far. `close` writes the final script there. A session that another process closes keeps the version from the last action. - A bare remote `open --save-script` writes `recording-.ad` in your working directory. - If the file already exists, `open` fails unless you pass `--force`. Without `--force`, a file that appears before the first version arrives is kept too: `open` still succeeds, but the script is not saved there, and the result carries a `scriptDeliveryFailure` and a warning. With `--force`, the first version replaces it. After that, the session owns the file and replaces it on each update.