Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion docs/adr/0016-active-session-script-publication.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,30 @@ 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).
The destination keeps local `--save-script` semantics (#4565): the client creates a missing parent directory, and neither the daemon nor the client publishes through a directory another local user can change. 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 `/` (or at the process's resolved working directory for a relative spelling) with the spelled 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. An absent component ends the walk, and the directory stood in is where the entry is created. 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.
Three 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 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 the current user owns is accepted when its group is that user's own private group, which is the shape Ubuntu and Debian give home directories. This is the one place the rule reads `/etc/group` and `/etc/passwd`, and it is admitted only where those two files can be shown to be the whole story: `/etc/nsswitch.conf` must exist, be readable, and list `files` as the only source for both `passwd` and `group`. `systemd` is not admitted either, because `systemd-userdbd` answers membership from records those files never show. Otherwise the exception is refused and a group-writable directory is treated as shared. Every group record carrying that numeric gid is then read, because a directory group-writable by gid 1000 is writable by the members of each group that holds the number, however it is named: `ada:x:1000:` beside `team:x:1000:grace` reaches grace.
The script file is created 0600, locally and remotely alike, so a recording is not world-readable in a directory that is merely shared.
The publisher compares the destination directory's captured `dev:ino` before publishing. The ownership rule above already excludes anyone able to swap that directory, so the comparison is defense in depth against a host whose ownership or modes moved during the download, not the check that closes the window.
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` or `script_ancestry_replaced`; a remote version keeps its command's success and carries that reason as the `scriptDeliveryFailure` cause.
Known limitation (#4564): the RPC response is the contract for `scriptDeliveryFailure`; the SDK, CLI, and MCP results do not carry it yet, the SDK close drops its warnings, and a batch delivers no step script versions.
Rejected: a remote `session save-script` download, because it added a second publication path and a retry protocol.
Rejected: delivery only at close, because a session that an external owner closes would lose its recording.
Expand Down
Loading
Loading