From ca8aec9665b38211e4a5861305674b439e6d7ddc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 10:30:49 +0100 Subject: [PATCH 01/28] fix(host-kit): refuse a script destination another local user can steer A publish resolved the destination by name, so a second local user who could write any directory on the way to it could replace that component, or leave a symbolic link there before the entry was created, and move the saved script wherever they chose. `publishScriptFileSync` now asks first: `assertPrivateScriptDestination` walks each component with `lstat` and refuses the chain under `script_ancestor_untrusted` when a directory is writable by other, or by a group that is not this user's own private group, unless the sticky bit cancels the exposure. A symbolic link whose own directory others can create entries in is refused whatever it points at. Ubuntu and Debian set up every home directory as group-writable and owned by the user's private group, so that shape is admitted, and `privateGroupIds` is exported so the membership rule is testable on its own. The caller also captures the parent's `dev:ino` before staging, and the publish compares it before the link or rename, so a parent swapped out by name while the file was written refuses under `script_ancestry_replaced` instead of receiving the script. Node exposes no `openat` or `renameat`, so publishing relative to a verified directory handle needs native code; this is the rule that closes the same window without it. Refs #4565 Co-Authored-By: Claude Opus 5.5 --- packages/host-kit/src/file.ts | 3 + .../src/internal/atomic-file-ancestry.test.ts | 315 ++++++++++++++++++ packages/host-kit/src/internal/atomic-file.ts | 250 ++++++++++++++ 3 files changed, 568 insertions(+) create mode 100644 packages/host-kit/src/internal/atomic-file-ancestry.test.ts diff --git a/packages/host-kit/src/file.ts b/packages/host-kit/src/file.ts index fd0b251e09..8779eccfb5 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -1,7 +1,10 @@ export { + assertPrivateScriptDestination, isAtomicPublishTemporaryPath, + publishDirectoryIdentity, publishDurableFileSync, publishFileSync, + publishScriptFileSync, type DurableFilePublishMode, } from './internal/atomic-file.ts'; export { 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..9445f855dc --- /dev/null +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -0,0 +1,315 @@ +import { afterEach, expect, test, vi } from 'vitest'; +import fs from 'node:fs'; +// oxlint-disable-next-line no-restricted-imports -- the fixture's private group is named after os.userInfo()'s user, not a scratch path +import os from 'node:os'; +import path from 'node:path'; +import { AppError } from '@agent-device/kernel/errors'; +import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; +import { + assertPrivateScriptDestination, + privateGroupIds, + publishDirectoryIdentity, + publishScriptFileSync, +} from './atomic-file.ts'; + +const skipOnWindows = process.platform === 'win32' ? test.skip : test; + +/** The group database a test stands in for `/etc/group` and `/etc/passwd`. */ +type Database = Readonly<{ groups: readonly string[]; passwd: readonly string[] }>; + +const realReadFileSync = fs.readFileSync; +const currentUser = os.userInfo().username; + +/** 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(); +}); + +/** + * Serves `database` for the two group files and the real host for everything else, so the + * private-group decision is the fixture's and not the CI image's user list. + */ +function serveGroupDatabase(database: Database): void { + vi.spyOn(fs, 'readFileSync').mockImplementation(((file: unknown, options?: unknown) => { + if (file === '/etc/group') return `${database.groups.join('\n')}\n`; + if (file === '/etc/passwd') return `${database.passwd.join('\n')}\n`; + return realReadFileSync(file as never, options as never) as never; + }) as typeof fs.readFileSync); +} + +/** This host's user with a group of their own, and a team group that holds someone else. */ +function hostDatabase(privateGid: number, sharedGid: number): Database { + return { + groups: ['root:x:0:root', `${currentUser}:x:${privateGid}:`, `team:x:${sharedGid}:ada`], + passwd: [`root:x:0:0`, `${currentUser}:x:${currentUid}:${privateGid}:`], + }; +} + +function root(): string { + return fs.realpathSync(mkdtempForTestSync('host-kit-ancestry-')); +} + +/** A directory carrying `mode` and `gid`, so the rule reads the group the test chose. */ +function directoryWith(directory: string, mode: number, gid = currentGid): string { + fs.mkdirSync(directory); + fs.chownSync(directory, currentUid, gid); + fs.chmodSync(directory, mode); + return directory; +} + +function publish(destination: string, parentIdentity?: string): void { + publishScriptFileSync({ + destination, + contents: 'context\n', + ...(parentIdentity === undefined ? {} : { parentIdentity }), + }); +} + +function expectUntrusted(run: () => void, exposure: string, ancestor: string): void { + expectRefusal(run, 'script_ancestor_untrusted', exposure, ancestor); +} + +function expectUntrustedReplaced(run: () => void, ancestor: string): void { + expectRefusal(run, 'script_ancestry_replaced', 'parent_replaced', ancestor); +} + +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 }); +} + +// --- a chain another local user can act inside is refused --- + +skipOnWindows('publishes to a chain only this user can write', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + 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('refuses a destination under a world-writable directory', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + 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 world-writable ancestor above the parent', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const shared = directoryWith(path.join(root(), 'shared'), 0o777); + const work = path.join(shared, 'work'); + fs.mkdirSync(work); + + expectUntrusted( + () => assertPrivateScriptDestination(path.join(work, 'journey.ad')), + 'world_writable', + shared, + ); +}); + +skipOnWindows('refuses a destination under a group-writable shared directory', () => { + const gid = currentGid; + serveGroupDatabase(hostDatabase(4321, gid)); + const team = directoryWith(path.join(root(), 'team'), 0o775, gid); + 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([]); +}); + +// --- the Ubuntu and Debian private-group home keeps working --- + +skipOnWindows('publishes to a group-writable home directory of a private group', () => { + const gid = currentGid; + serveGroupDatabase(hostDatabase(gid, 4321)); + const home = directoryWith(path.join(root(), 'home'), 0o775, gid); + + publish(path.join(home, 'journey.ad')); + + expect(fs.readFileSync(path.join(home, 'journey.ad'), 'utf8')).toBe('context\n'); +}); + +skipOnWindows("refuses the same mode and group once the group is not the user's own", () => { + const gid = currentGid; + serveGroupDatabase(hostDatabase(4321, gid)); + const home = directoryWith(path.join(root(), 'home'), 0o775, gid); + + expectUntrusted(() => publish(path.join(home, 'journey.ad')), 'shared_group_writable', home); +}); + +skipOnWindows('publishes to a setgid group-writable private-group home', () => { + const gid = currentGid; + serveGroupDatabase(hostDatabase(gid, 4321)); + const home = directoryWith(path.join(root(), 'home'), 0o2775, gid); + + publish(path.join(home, 'journey.ad')); + + expect(fs.existsSync(path.join(home, 'journey.ad'))).toBe(true); +}); + +// --- a sticky shared directory is safe, except through a link planted in it --- + +skipOnWindows('publishes to a destination under a sticky world-writable directory', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const shared = directoryWith(path.join(root(), 'shared'), 0o1777); + + publish(path.join(shared, 'journey.ad')); + + expect(fs.existsSync(path.join(shared, 'journey.ad'))).toBe(true); +}); + +skipOnWindows('refuses a symbolic link planted in a directory others can write', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o1777); + const attacker = path.join(directory, 'attacker'); + fs.mkdirSync(attacker); + fs.symlinkSync(attacker, path.join(shared, 'work')); + + expectUntrusted( + () => assertPrivateScriptDestination(path.join(shared, 'work', 'journey.ad')), + 'planted_link', + path.join(shared, 'work'), + ); + expect(fs.readdirSync(attacker)).toEqual([]); +}); + +skipOnWindows('follows a symbolic link inside a directory only this user can write', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + 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); +}); + +// --- the destination directory swapped out while the file was staged --- + +skipOnWindows('refuses a parent replaced by name while the file was staged', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const directory = root(); + const staged = path.join(directory, 'work'); + fs.mkdirSync(staged); + const parentIdentity = publishDirectoryIdentity(staged); + const destination = path.join(staged, 'journey.ad'); + fs.rmSync(staged, { recursive: true }); + const replaced = path.join(directory, 'work'); + fs.mkdirSync(replaced); + + expectUntrustedReplaced(() => publish(destination, parentIdentity), replaced); + expect(fs.readdirSync(replaced)).toEqual([]); +}); + +skipOnWindows('re-checks the chain after staging the file, before the entry is created', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const directory = root(); + const staged = path.join(directory, 'work'); + fs.mkdirSync(staged); + const destination = path.join(staged, 'journey.ad'); + const writeFileSync = fs.writeFileSync; + // The window a second local user races: the file is staged, the entry is not created yet. + vi.spyOn(fs, 'writeFileSync').mockImplementation(((file: unknown, ...rest: unknown[]) => { + const result = (writeFileSync as (...args: unknown[]) => unknown)(file, ...rest); + fs.rmSync(staged, { recursive: true, force: true }); + fs.mkdirSync(staged); + fs.chmodSync(staged, 0o777); + return result; + }) as typeof fs.writeFileSync); + + expectUntrustedReplaced(() => publish(destination), staged); + expect(fs.readdirSync(staged)).toEqual([]); +}); + +skipOnWindows('publishes into the parent the captured identity still names', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const staged = path.join(root(), 'work'); + fs.mkdirSync(staged); + + publish(path.join(staged, 'journey.ad'), publishDirectoryIdentity(staged)); + + expect(fs.existsSync(path.join(staged, 'journey.ad'))).toBe(true); +}); + +// --- privateGroupIds: the one group shape the exception admits --- + +const ADA = { uid: 1000, name: 'ada' }; + +function database(groups: readonly string[], passwd: readonly string[]) { + return { groups, passwd }; +} + +test('treats the group named after the user, holding only them, as private', () => { + const ids = privateGroupIds( + database(['ada:x:1000:', 'staff:x:20:root'], ['ada:x:1000:1000:', 'root:x:0:0']), + ADA, + ); + expect([...ids]).toEqual([1000]); +}); + +test('treats a group as private when only its primary-group link names the user', () => { + const ids = privateGroupIds( + database(['ada:x:1000:', 'staff:x:20:'], ['root:x:0:0', 'ada:x:1000:1000:']), + ADA, + ); + expect([...ids]).toEqual([1000]); +}); + +test('still treats a group as private with root among its members', () => { + const ids = privateGroupIds( + database(['ada:x:1000:root', 'staff:x:20:'], ['ada:x:1000:1000:', 'root:x:0:0']), + ADA, + ); + expect([...ids]).toEqual([1000]); +}); + +test('treats the group named after the user as shared once another user is a member', () => { + const ids = privateGroupIds( + database( + ['ada:x:1000:grace', 'staff:x:20:'], + ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0'], + ), + ADA, + ); + expect([...ids]).toEqual([]); +}); + +test('treats the group named after the user as shared once another user has it as primary group', () => { + const ids = privateGroupIds( + database(['ada:x:1000:', 'staff:x:20:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), + ADA, + ); + expect([...ids]).toEqual([]); +}); + +test('never treats another group name as private, however few members it lists', () => { + const ids = privateGroupIds(database(['team:x:4321:', 'ada:x:1000:'], ['ada:x:1000:1000:']), ADA); + expect([...ids]).toEqual([1000]); +}); + +test('treats an unreadable group database as having no private group', () => { + expect([...privateGroupIds(database([], []), ADA)]).toEqual([]); +}); + +test('gives a caller without a full identity no private group', () => { + const groups = database(['ada:x:1000:'], ['ada:x:1000:1000:']); + expect([...privateGroupIds(groups, { uid: undefined, name: 'ada' })]).toEqual([]); + expect([...privateGroupIds(groups, { uid: 1000, name: undefined })]).toEqual([]); +}); diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index bb00b26944..f05b8550b3 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -1,6 +1,8 @@ import crypto from 'node:crypto'; import fs from 'node:fs'; +import os from 'node:os'; 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 +44,41 @@ 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): the chain is refused before + * anything is written, and it is checked again immediately before the link or rename, so a directory + * swapped in by another local user while the file was staged never receives the script. + * + * `parentIdentity` is what {@link publishDirectoryIdentity} returned for a parent the caller created or + * checked before it staged this file. + */ +export function publishScriptFileSync(options: { + destination: string; + contents: string; + mode?: number; + publish?: AtomicPublishMode; + parentIdentity?: string; +}): void { + const expected = + options.parentIdentity ?? publishDirectoryIdentity(path.dirname(options.destination)); + withAtomicPublishTempPathSync(options.destination, (temporaryPath) => { + assertPrivateScriptDestination(options.destination, expected); + fs.writeFileSync( + temporaryPath, + options.contents, + options.mode === undefined ? 'utf8' : { encoding: 'utf8', mode: options.mode }, + ); + assertPrivateScriptDestination(options.destination, expected); + if (options.publish === 'link-exclusive') { + fs.linkSync(temporaryPath, options.destination); + } else { + fs.renameSync(temporaryPath, options.destination); + } + }); +} + export type DurableFilePublishMode = 'replace' | 'link-exclusive'; /** Publishes complete UTF-8 contents with a durable file and directory fence. */ @@ -148,6 +185,219 @@ export function isAtomicPublishTemporaryPath(value: unknown, destination: string return name.startsWith(`.${path.basename(destination)}.`) && name.endsWith('.tmp'); } +/** + * Refuses a script destination when another local user can write a directory on the way to it (#4565). + * + * Node exposes no `openat` or `renameat`, so a publisher cannot resolve a destination relative to a + * directory handle. What remains is to refuse every chain a second local user can act inside: a + * directory they can write is one where they can replace a component of this path, or create one before + * this client does, so the script lands where they choose, or they take it from a directory they own. + * + * The rule reads each component with `lstat`, so a symbolic link is judged as the link it is and is + * never mistaken for the directory its target names: + * + * - A component's mode decides. The sticky bit cancels the exposure: it stops anyone but an entry's + * owner or root from removing or replacing that entry, which is how a shared team directory is made + * safe, and why the hint names it. + * - Otherwise a component writable by anyone other than this user is refused, except a group-writable + * one whose group is this user's own private group: Ubuntu and Debian set up every home directory + * that way, often group-writable, and those have to stay usable. + * - A symbolic link whose own directory others can create entries in is refused whatever it points at: + * it may be one they planted, and its target is theirs to choose. The sticky bit does not help here, + * because it guards entries that already exist. + * + * An absent or non-directory component is left alone: the filesystem refuses a publish through it. On + * Windows, access is an ACL rather than a mode, so this is a no-op there. + * + * `parentIdentity` is what {@link publishDirectoryIdentity} returned for the parent the caller created + * or checked before it staged this file. Whoever owns a directory above it can open that directory to + * others, swap the parent for one of their own while the file is staged, and close it again, and only + * the identity catches that. + */ +export function assertPrivateScriptDestination(destination: string, parentIdentity?: string): void { + if (process.platform === 'win32') return; + const parent = path.dirname(path.resolve(destination)); + if (parentIdentity !== undefined && publishDirectoryIdentity(parent) !== parentIdentity) { + throw scriptAncestryFailure(destination, parent, 'parent_replaced'); + } + const privateGids = lazyPrivateGroupIds(); + for (const ancestor of directoryChain(parent)) { + const link = lstatIfPresentSync(ancestor); + if (!link) continue; + if (link.isSymbolicLink() && othersCreateEntriesIn(path.dirname(ancestor), privateGids)) { + throw scriptAncestryFailure(destination, ancestor, 'planted_link'); + } + const directory = link.isSymbolicLink() ? statDirectoryChain(ancestor) : link; + if (!directory?.isDirectory()) continue; + const exposure = untrustedWritableExposure(directory, privateGids()); + if (exposure) throw scriptAncestryFailure(destination, ancestor, exposure); + } +} + +/** + * One directory's identity on its filesystem, for a caller that must publish into the same one it + * created or checked. `undefined` when the directory is absent or is not a directory. + */ +export function publishDirectoryIdentity(directory: string): string | undefined { + if (process.platform === 'win32') return 'windows'; + const stats = statDirectoryChain(directory); + return stats ? `${stats.dev}:${stats.ino}` : undefined; +} + +/** The group and passwd records the private-group exception reads, in `/etc/group` field order. */ +type HostGroupDatabase = Readonly<{ + groups: readonly string[]; + passwd: readonly string[]; +}>; + +/** + * The private group of `current`, in the one shape the exception admits: the group named after them. + * + * Ubuntu and Debian create one group per user, named after them, and set up that user's home directory + * with it, often group-writable. Such a home is shared with no other local user, so it stays a valid + * script destination. Every other group name stays outside the exception: this host's own records + * cannot bound it, because macOS lists only part of `staff` in `/etc/group` while every local user + * holds it, and a name service can add members to a group this machine cannot read. + * + * Membership comes from both places a member can appear: the group's own member list, and the users + * whose primary group is this one. A member who is neither `current` nor root disqualifies the group. + */ +export function privateGroupIds( + database: HostGroupDatabase, + current: Readonly<{ uid: number | undefined; name: string | undefined }>, +): Set { + const privateIds = new Set(); + if (current.uid === undefined || current.name === undefined) return privateIds; + const uidByName = new Map(); + const primaryMembers = new Map(); + for (const line of database.passwd) { + const [name, , rawUid, rawGid] = line.split(':'); + const uid = Number(rawUid); + const gid = Number(rawGid); + if (!name || !Number.isInteger(uid) || !Number.isInteger(gid)) continue; + uidByName.set(name, uid); + primaryMembers.set(gid, [...(primaryMembers.get(gid) ?? []), name]); + } + for (const line of database.groups) { + const [name, , rawGid, rawMembers] = line.split(':'); + const gid = Number(rawGid); + if (name !== current.name || !Number.isInteger(gid)) continue; + const supplementary = (rawMembers ?? '').split(',').filter((member) => member.length > 0); + const ids = [...supplementary, ...(primaryMembers.get(gid) ?? [])].map((member) => + uidByName.get(member), + ); + if (ids.every((id) => id === current.uid || id === 0)) privateIds.add(gid); + } + return privateIds; +} + +/** This host's private groups, read from the group database the first time the chain meets one. */ +function lazyPrivateGroupIds(): () => ReadonlySet { + let cached: ReadonlySet | undefined; + return () => + (cached ??= privateGroupIds( + { groups: readSystemFile('/etc/group'), passwd: readSystemFile('/etc/passwd') }, + { uid: process.getuid?.(), name: readCurrentUser() }, + )); +} + +function readCurrentUser(): string | undefined { + try { + return os.userInfo().username; + } catch { + return undefined; + } +} + +/** Every directory from `directory` up to the filesystem root, nearest first. */ +function directoryChain(directory: string): string[] { + const chain: string[] = []; + let current = directory; + for (;;) { + chain.push(current); + const parent = path.dirname(current); + if (parent === current) return chain; + current = parent; + } +} + +/** Why other local users can write in this directory, or `undefined` when only this user and root can. */ +function untrustedWritableExposure( + stats: fs.Stats, + privateGids: ReadonlySet, +): AncestryExposure | undefined { + if (stats.mode & 0o1000) return undefined; + if (stats.mode & 0o002) return 'world_writable'; + if (stats.mode & 0o020 && !privateGids.has(stats.gid)) return 'shared_group_writable'; + return undefined; +} + +/** Whether other local users can create an entry here: how a component becomes their symbolic link. */ +function othersCreateEntriesIn(directory: string, privateGids: () => ReadonlySet): boolean { + const stats = statDirectoryChain(directory); + if (!stats) return false; + if (stats.mode & 0o002) return true; + return Boolean(stats.mode & 0o020) && !privateGids().has(stats.gid); +} + +type AncestryExposure = + | 'world_writable' + | 'shared_group_writable' + | 'planted_link' + | 'parent_replaced'; + +function scriptAncestryFailure( + destination: string, + ancestor: string, + exposure: AncestryExposure, +): AppError { + const writableByOthers = exposure !== 'parent_replaced'; + return new AppError( + 'COMMAND_FAILED', + writableByOthers + ? `Refusing to save the script under ${ancestor}: another local user can write that part of the path.` + : `The directory for ${destination} changed while the script was staged, so the script was not saved.`, + { + reason: writableByOthers ? 'script_ancestor_untrusted' : 'script_ancestry_replaced', + exposure, + path: destination, + ancestor, + hint: writableByOthers + ? `Save the script under a directory only you can write, or share ${ancestor} safely with the sticky bit (chmod +t) and keep symbolic links out of the path.` + : 'Re-record with open --save-script, or save under a directory nobody else can write.', + }, + ); +} + +function readSystemFile(file: string): string[] { + try { + return fs.readFileSync(file, 'utf8').split('\n'); + } catch { + return []; + } +} + +/** `lstat` where absence is `undefined`; any other failure propagates. */ +function lstatIfPresentSync(pathname: string): fs.Stats | undefined { + try { + return fs.lstatSync(pathname); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; + throw error; + } +} + +/** `stat` of the directory a path names, or `undefined` when it is absent or is not a directory. */ +function statDirectoryChain(pathname: string): fs.Stats | undefined { + let stats: fs.Stats | undefined; + try { + stats = fs.statSync(pathname); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; + throw error; + } + return stats.isDirectory() ? stats : undefined; +} function assertSafeDestination(destination: string): void { const stats = lstatIfPresent(destination); if (stats?.isSymbolicLink()) { From b4340d0cf89d2299d313fd8bb7a217b89d194d7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 10:30:52 +0100 Subject: [PATCH 02/28] fix(daemon): apply the destination rule to a local script save The writer now publishes with `publishScriptFileSync`, and hands it the identity of the directory it created, so a `--save-script` path with a directory another local user can write refuses instead of landing the recording there, and a parent replaced by name while the recording was staged never receives it. A refusal is reported with the reason the rule chose, and a refused destination is created by nothing. Refs #4565 Co-Authored-By: Claude Opus 5.5 --- .../session-script-writer-ancestry.test.ts | 140 ++++++++++++++++++ .../daemon/src/core/session-script-writer.ts | 9 +- 2 files changed, 146 insertions(+), 3 deletions(-) create mode 100644 packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts 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..80198713c3 --- /dev/null +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -0,0 +1,140 @@ +import { expect, test } from 'vitest'; +import fs from 'node:fs'; +// oxlint-disable-next-line no-restricted-imports -- the private-group fixture is named after os.userInfo()'s user, not a scratch path +import os from 'node:os'; +import path from 'node:path'; +import { createLiveTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; +import { SessionScriptWriter } from '../session-script-writer.ts'; +import { makeAuthoringSession } from '../../__tests__/support/session-factories.ts'; + +const hostCwd = createLiveTestHostEnvironment().cwd; +const skipOnWindows = process.platform === 'win32' ? test.skip : test; + +/** The private-group exception is decided by this host's group database. */ +function groupDatabaseMatchesHost(gid: number): boolean { + try { + const name = os.userInfo().username; + const groups = fs.readFileSync('/etc/group', 'utf8').split('\n'); + const passwd = fs.readFileSync('/etc/passwd', 'utf8').split('\n'); + const line = groups.find((entry) => entry.split(':')[0] === name); + if (!line || Number(line.split(':')[2]) !== gid) return false; + const extra = (line.split(':')[3] ?? '').split(',').filter(Boolean); + return ( + extra.every((member) => member === name || member === 'root') && + passwd.every((entry) => { + const [user, , , primary] = entry.split(':'); + return Number(primary) !== gid || user === name || user === 'root'; + }) + ); + } catch { + return false; + } +} + +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')], + }); +} + +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; +} + +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 destination = path.join(root(), 'workflows', 'journey.ad'); + const writer = new SessionScriptWriter(path.join(root(), 'sessions'), hostCwd); + + const result = writer.write(recordingTo(destination)); + + expect(result.written).toBe(true); + expect(fs.readFileSync(destination, 'utf8')).toContain('open'); +}); + +skipOnWindows('a recording refuses a destination under a world-writable directory', () => { + const shared = sharedDirectory(path.join(root(), 'shared'), 0o777); + const destination = path.join(shared, 'journey.ad'); + const writer = new SessionScriptWriter(path.join(root(), 'sessions'), hostCwd); + + const details = refusal(writer.write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + }); + expect(fs.existsSync(destination)).toBe(false); +}); + +skipOnWindows('a recording refuses an ancestor swapped out for a symbolic link', () => { + const directory = root(); + const shared = sharedDirectory(path.join(directory, 'shared'), 0o1777); + 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 writer = new SessionScriptWriter(path.join(directory, 'sessions'), hostCwd); + + const details = refusal(writer.write(recordingTo(destination))); + + expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'planted_link' }); + expect(fs.readdirSync(attacker)).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 writer = new SessionScriptWriter(path.join(directory, 'sessions'), hostCwd); + + const details = refusal(writer.write(recordingTo(destination))); + + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'world_writable', + }); + expect(fs.readdirSync(work)).toEqual([]); +}); + +skipOnWindows('a recording still saves to a group-writable private-group home', () => { + const gid = process.getgid?.(); + if (gid === undefined || !groupDatabaseMatchesHost(gid)) return; + const home = path.join(root(), 'home'); + fs.mkdirSync(home); + fs.chmodSync(home, 0o775); + const writer = new SessionScriptWriter(path.join(root(), 'sessions'), hostCwd); + + const result = writer.write(recordingTo(path.join(home, 'journey.ad'))); + + expect(result.written).toBe(true); +}); diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index be5050e645..c4abbd5618 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -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 { publishDirectoryIdentity, publishScriptFileSync } from '@agent-device/host-kit/file'; import type { SessionState } from './session-state.ts'; import { NO_SCRIPT_PUBLICATION, @@ -143,6 +143,7 @@ export class SessionScriptWriter { scriptPath, script: prepared.script, force: options?.force, + parentIdentity: publishDirectoryIdentity(scriptDir), ...(remote ? { mode: 0o600 } : {}), }); // COMMITTED: idempotent guard above + teardown's abort/tombstone routing. @@ -302,13 +303,15 @@ function publishHealedScriptAtomically(params: { script: string; force?: boolean; mode?: number; + parentIdentity?: string; }): void { - const { scriptPath, script, force, mode } = params; + const { scriptPath, script, force, mode, parentIdentity } = params; try { - publishFileSync({ + publishScriptFileSync({ destination: scriptPath, contents: script, publish: force ? 'replace' : 'link-exclusive', + ...(parentIdentity === undefined ? {} : { parentIdentity }), ...(mode === undefined ? {} : { mode }), }); } catch (error) { From a0b1332ab8681137e944f64cd77f910cef160139 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 10:30:55 +0100 Subject: [PATCH 03/28] fix(remote): refuse an unsafe script destination before it is downloaded A remote recording staged the version beside the destination and renamed it into place, so an ancestor another local user could write steered both the download and the entry. `allocateStaging` now asks the destination rule before it creates anything, so a refused path leaves no directory behind, and it reports the destination directory's identity. `publishStaged` re-asks under the record lock, immediately before the entry is created, so whoever could write an ancestor while the version was downloaded cannot move it now. The command keeps its success and carries the refusal's typed reason as the `scriptDeliveryFailure` cause, so a caller can tell an unsafe destination from a download that failed. Refs #4565 Co-Authored-By: Claude Opus 5.5 --- .../daemon-artifacts-script-download.test.ts | 85 +++++++++++++++++++ .../remote/src/session-script-destination.ts | 78 ++++++++++++++--- test/wire-compat/ledger.json | 2 +- 3 files changed, 154 insertions(+), 11 deletions(-) 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..d9217963d5 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts @@ -465,6 +465,91 @@ test.skipIf(process.platform === 'win32' || process.getuid?.() === 0).each([ }, ); +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, 0o1777); + 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([]); + }, +); + test('retiring a record removes the staging a crashed download left behind', async () => { const { stateDir, destination } = journey(); const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 552e455650..326c74b59c 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -8,9 +8,16 @@ 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, + assertPrivateScriptDestination, + publishDirectoryIdentity, + publishFileSync, + withProcessLock, +} from '@agent-device/host-kit/file'; import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; import type { DaemonArtifactEndpoint, downloadRemoteArtifact } from './daemon-artifacts.ts'; @@ -189,13 +196,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 }; + // Asked before anything is created, so a destination another local user can steer leaves no + // directory behind (#4565). + assertPrivateScriptDestination(record.destination); + await fs.promises.mkdir(path.dirname(record.destination), { recursive: true }); + const allocated = await withRecordLock(file, async () => + allocateStaging(file, record.destination), + ); + staging = allocated?.staging; + if (!staging || !allocated) return { published: undefined }; const staged = path.join(staging, 'script.ad'); await context.download({ ...endpoint, @@ -204,7 +216,13 @@ 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, + staged, + parentIdentity: allocated.parentIdentity, + pending, + }; return { published: await withRecordLock(file, async () => publishStaged(file, version)) }; } catch (error) { const closing = req.command === 'close'; @@ -221,18 +239,29 @@ 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, and reports the destination directory's identity so the publish can confirm it is + * still the same one. Refuses an ancestor another local user can write (#4565), so nothing is + * downloaded into a directory they control. + */ +function allocateStaging( + file: string, + destination: string, +): { staging: string; parentIdentity: string | undefined } | undefined { const record = readRecord(file); if (!record) return undefined; + assertPrivateScriptDestination(destination); + const directory = path.dirname(destination); const staging = fs.mkdtempSync(path.join(directory, '.agent-device-script-')); + const parentIdentity = publishDirectoryIdentity(directory); try { writeRecord(file, { ...record, staging: [...(record.staging ?? []), staging] }); } catch (error) { fs.rmSync(staging, { recursive: true, force: true }); throw error; } - return staging; + return { staging, parentIdentity }; } /** @@ -313,10 +342,11 @@ function publishStaged( revision: number; staging: string; staged: string; + parentIdentity: string | undefined; pending: { named: boolean }; }>, ): string | undefined { - const { revision, staging, staged, pending } = version; + const { revision, staging, staged, parentIdentity, pending } = version; const record = readRecord(file); if (!record) return undefined; let current = settlePublishing(record); @@ -327,6 +357,9 @@ function publishStaged( current = withoutStaging(current, record.publishing.staging); } if (revision <= current.revision) return current.destination; + // Re-asked here, under the record lock and right before the entry is created: whoever could write + // an ancestor while the version was downloaded cannot move it now (#4565). + assertPrivateScriptDestination(current.destination, parentIdentity); 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`); @@ -367,6 +400,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 = scriptAncestryRefusal(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.'; @@ -387,6 +433,18 @@ function scriptDeliveryFailure( }; } +/** + * The typed reason a destination-ancestry refusal reported (#4565), so a caller can tell an unsafe + * destination from a download that failed. Anything else is `undefined`. + */ +function scriptAncestryRefusal(error: unknown): string | undefined { + if (!(error instanceof AppError)) return undefined; + const reason = error.details?.reason; + return reason === 'script_ancestor_untrusted' || reason === 'script_ancestry_replaced' + ? reason + : undefined; +} + function recordPath( stateDir: string, baseUrl: string, diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index bdabba0ca5..2bdb9b848b 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -214,7 +214,7 @@ "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:3406b96e254e85cd3e3f23b8b644f40d8d7268b2066696ff21516dabfa8ca14c", "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" From e26b69800f49e982c9be71a141bcc3ed6a32014b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 10:30:58 +0100 Subject: [PATCH 04/28] docs: say which directories a script save accepts The replay guide states the destination rule for `--save-script`: every directory on the way must be one only the user and root can write, why a sticky shared team directory and a group-writable home of the user's own private group are accepted, and why a symbolic link inside a directory others can write is refused whatever it targets. Each surface's outcome is stated: a local `close` fails and keeps its bytes, a remote recording keeps its success and reports the reason as the `scriptDeliveryFailure` cause, and the next recorded action repeats the refusal. The remote proxy page points at that rule instead of repeating it, and ADR 0016 records the rule, the private-group exception, the parent-identity re-check, and why publishing relative to a directory handle was not available. Refs #4565 Co-Authored-By: Claude Opus 5.5 --- docs/adr/0016-active-session-script-publication.md | 7 ++++++- website/docs/docs/remote-proxy.md | 2 ++ website/docs/docs/replay-e2e.md | 3 +++ 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 9e448469ad..d4a8fa618c 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -207,7 +207,12 @@ 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 write. +Before staging, and again immediately before the link or rename, the publisher walks each component of the destination with `lstat` and refuses it under a typed reason when its mode is writable by group or other without the sticky bit, unless that group is the current user's own private group: Ubuntu and Debian set up every home directory that way, often group-writable, and those keep working. +A symbolic link whose own directory others can create entries in is refused whatever it points at, because that link may be one they planted; the sticky bit does not excuse it, because it guards entries that already exist. +The publisher also captures the destination directory's identity before it stages the file and compares it before publishing, so a parent swapped out by name during the download or the temp write never receives the script. +Node exposes no `openat` or `renameat`, so publishing relative to a verified directory handle is not available without native code; the refusal plus the identity re-check is the non-native rule that closes the same window. +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. 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/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 44cd873478..94b317b64c 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -108,6 +108,8 @@ 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 on the way to that path must be one that only you and root can write; see +[Record a replay script](replay-e2e.md#record-a-replay-script). 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. diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index d34e6eb31c..0e07e1ef20 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -71,6 +71,9 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow ``` - Missing parent directories are created. +- Every directory on the way to the script must be one that only you and root can write. Another local user who can write such a directory can replace a directory on the path, or leave a symbolic link there, before the script is moved into place. The script then lands where they choose. +- A shared team directory is safe once it has the sticky bit (`chmod +t`): it stops anyone but an entry's owner or root from replacing that entry. A group-writable home directory of your own private group, the shape Ubuntu and Debian create, is accepted. A symbolic link inside a directory others can write is refused, whatever it points at. +- 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. Choosing a directory nobody else can write, or adding the sticky bit, clears it. - With a local daemon, the script is written on the daemon host when the session closes. - 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. From cc0b597bcea3338936bec8cd1aa688c1c84766b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 10:50:00 +0100 Subject: [PATCH 05/28] test: carry the script publish through the wire and ownership gates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The daemon RPC manifest reached `PublishOutcome` through `publishScriptVersion` and could not place it, so the outcome type the client builds now carries a waiver naming the payload half it serializes, and `ScriptDeliveryFailure` — the field a peer actually parses — is listed with it. `publishScriptVersion`'s digest moves with the destination rule. The same-directory publisher guard read the shared atomic publish owner by name, so the script writer's new entry point failed it. The guard now accepts either owner and states separately that the session script uses the ancestry-owning one. Co-Authored-By: Claude Opus 5.5 --- .../__tests__/atomic-publish-ownership.test.ts | 12 +++++++++++- test/wire-compat/closure-policy.ts | 2 ++ test/wire-compat/ledger.json | 1 + 3 files changed, 14 insertions(+), 1 deletion(-) 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..17ff81c0fb 100644 --- a/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts +++ b/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts @@ -23,11 +23,21 @@ 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*\(/); } }); +// A session script is published through the ancestry-owning entry point, not the plain one: the plain +// one writes to a destination another local user could have steered (#4565). +test('the session script publisher uses the destination-ancestry owner', () => { + const source = fs.readFileSync( + new URL('../../core/session-script-writer.ts', import.meta.url), + 'utf8', + ); + assert.match(source, /publishScriptFileSync/); +}); + // The process lock publishes a file and reclaims a directory, which are two different // claims of ownership: only the first belongs to the publication owners above. test('the process lock publishes its owner record without publishing files by hand', () => { 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 2bdb9b848b..02301f93b0 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -33,6 +33,7 @@ "packages/kernel/src/contracts.ts#RESPONSE_LEVELS": "sha256:cef29c3b56c299e35a7fee8058b90dc4a6f65a46a420e4f11f77c8ca7d0359c8", "packages/kernel/src/contracts.ts#ResponseCost": "sha256:2a44de54e8b5c886b36da1500e22d634ec7e12961d2c93b689d2b1aa8c15f186", "packages/kernel/src/contracts.ts#ResponseLevel": "sha256:c7329d28e745b5e69b86aa1a686befa314b98248afbe5e0e2d7d395f0d777f9b", + "packages/kernel/src/contracts.ts#ScriptDeliveryFailure": "sha256:186881f8b2e6a0227a6d1a2c802d8f7356fee39d4137800a0c9fa65401aa2765", "packages/kernel/src/contracts.ts#SESSION_ISOLATION_MODES": "sha256:3d4b3048e22bb0ceccc98cf8fd93a87a1a1e2dad96fa03cffff6d0ecedb58689", "packages/kernel/src/contracts.ts#SessionIsolationMode": "sha256:beea941fe57b000902da28af15a27aa18d0c957408209e3ec372fcf7f605fa7c", "packages/kernel/src/contracts.ts#SESSION_RUNTIME_PLATFORMS": "sha256:6164fc8ca226b5beb3ba52a8dddd3c11633a8accec58b9f8972c44c8339a1bf7", From d93ac5d15a788154dbd2349d435603712e997a1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 11:46:17 +0100 Subject: [PATCH 06/28] fix(host-kit): judge a script destination by ownership and its real path Three ways through the destination rule stayed open. Ownership was never asked, so a directory another user owned passed at 0755, and its owner could open it up or replace the subtree whenever they liked; the sticky bit excused a directory whatever its ownership. The rule now requires every directory on the chain to be owned by this user or by root, and keeps the writability rule on top of that. A sticky shared directory is still trusted for passing through, and the link rule requires a link there to be owned by this user or root; nothing is created inside a directory others can add entries to, so a shared parent no longer receives the entry. A symbolic link's target escaped the walk entirely: a link in the user's own home pointing at a world-writable directory was judged only as the link. The existing prefix is now resolved once and the whole resolved chain is judged, so the shared target is refused; root-owned system aliases such as macOS /tmp and /var keep working. The private-group exception assumed a membership it could not prove. It now fails closed: both database files must have been read, the group must be this process's primary group and carry this user's name, its member list may name nobody else, and no other passwd record may hold it as its primary group. A name service that can add a member without touching /etc/passwd is named as the limitation it is. A published script is created 0600 locally as well as remotely, so a recording is not world-readable in a directory that is merely shared. Refs #4565 Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 12 +- .../session-script-writer-ancestry.test.ts | 166 ++++++-- .../session-store-teardown-script.test.ts | 5 +- .../daemon/src/core/session-script-writer.ts | 10 +- packages/host-kit/src/file.ts | 8 + .../src/internal/atomic-file-ancestry.test.ts | 375 ++++++++++++++---- packages/host-kit/src/internal/atomic-file.ts | 347 +++++++++++----- .../daemon-artifacts-script-download.test.ts | 2 +- website/docs/docs/remote-proxy.md | 2 +- website/docs/docs/replay-e2e.md | 9 +- 10 files changed, 699 insertions(+), 237 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index d4a8fa618c..3190810e92 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -207,11 +207,13 @@ 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 (#4565): the client creates a missing parent directory, and neither the daemon nor the client publishes through a directory another local user can write. -Before staging, and again immediately before the link or rename, the publisher walks each component of the destination with `lstat` and refuses it under a typed reason when its mode is writable by group or other without the sticky bit, unless that group is the current user's own private group: Ubuntu and Debian set up every home directory that way, often group-writable, and those keep working. -A symbolic link whose own directory others can create entries in is refused whatever it points at, because that link may be one they planted; the sticky bit does not excuse it, because it guards entries that already exist. -The publisher also captures the destination directory's identity before it stages the file and compares it before publishing, so a parent swapped out by name during the download or the temp write never receives the script. -Node exposes no `openat` or `renameat`, so publishing relative to a verified directory handle is not available without native code; the refusal plus the identity re-check is the non-native rule that closes the same window. +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 on its fully resolved chain. 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 chain is resolved first, so a symbolic link's target is judged under the same rule. A link is refused when another user could have placed it or could replace it: in a directory where others may add entries, only a link owned by the current user or root and held by the sticky bit is trusted. Root-owned system aliases (macOS `/tmp` to `/private/tmp`, `/var` to `/private/var`) keep working. +The sticky bit excuses a directory the chain passes THROUGH, because it stops anyone but an entry's owner or root from replacing that entry; it never excuses creating the destination inside that directory, because anyone could create that name first. 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 fails closed when either file is unreadable. Residual limitation: a name service (LDAP or an NSS module) can add a member holding that primary GID without it appearing in `/etc/passwd`, so such a host can be refused a group-writable directory it appears to own. The fallback is a directory only the user can write. +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. 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. 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. 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 index 80198713c3..b8121b051a 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -1,4 +1,4 @@ -import { expect, test } from 'vitest'; +import { afterEach, expect, test, vi } from 'vitest'; import fs from 'node:fs'; // oxlint-disable-next-line no-restricted-imports -- the private-group fixture is named after os.userInfo()'s user, not a scratch path import os from 'node:os'; @@ -10,25 +10,44 @@ import { makeAuthoringSession } from '../../__tests__/support/session-factories. const hostCwd = createLiveTestHostEnvironment().cwd; const skipOnWindows = process.platform === 'win32' ? test.skip : test; -/** The private-group exception is decided by this host's group database. */ -function groupDatabaseMatchesHost(gid: number): boolean { - try { - const name = os.userInfo().username; - const groups = fs.readFileSync('/etc/group', 'utf8').split('\n'); - const passwd = fs.readFileSync('/etc/passwd', 'utf8').split('\n'); - const line = groups.find((entry) => entry.split(':')[0] === name); - if (!line || Number(line.split(':')[2]) !== gid) return false; - const extra = (line.split(':')[3] ?? '').split(',').filter(Boolean); - return ( - extra.every((member) => member === name || member === 'root') && - passwd.every((entry) => { - const [user, , , primary] = entry.split(':'); - return Number(primary) !== gid || user === name || user === 'root'; - }) - ); - } catch { - return false; - } +const realReadFileSync = fs.readFileSync; +const currentUser = os.userInfo().username; + +/** 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(); +}); + +/** + * Serves `groups` and `passwd` for the two group files and the real host for everything else, so the + * private-group decision is the fixture's and this file's assertions run on every POSIX host instead of + * only on one whose `/etc/group` happens to agree. + */ +function serveGroupDatabase(groups: readonly string[], passwd: readonly string[]): void { + vi.spyOn(fs, 'readFileSync').mockImplementation(((file: unknown, options?: unknown) => { + if (file === '/etc/group') return `${groups.join('\n')}\n`; + if (file === '/etc/passwd') return `${passwd.join('\n')}\n`; + return realReadFileSync(file as never, options as never) as never; + }) as typeof fs.readFileSync); +} + +/** This host's user owning `currentGid` alone, plus a team group that holds someone else. */ +function privateGroupDatabase(): void { + serveGroupDatabase( + ['root:x:0:root', `${currentUser}:x:${currentGid}:`, 'team:x:4321:ada'], + ['root:x:0:0', `${currentUser}:x:${currentUid}:${currentGid}:`], + ); +} + +/** The same ids, with this host's group named after somebody else, so it is not private. */ +function foreignGroupNameDatabase(): void { + serveGroupDatabase( + ['root:x:0:root', `${currentUser}:x:${currentGid + 1}:`, 'team:x:4321:ada'], + ['root:x:0:0', `${currentUser}:x:${currentUid}:${currentGid}:`], + ); } function action(command: string): { @@ -61,6 +80,18 @@ function sharedDirectory(directory: string, mode: number): string { 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'); @@ -68,21 +99,31 @@ function refusal(result: ReturnType): Record { - const destination = path.join(root(), 'workflows', 'journey.ad'); - const writer = new SessionScriptWriter(path.join(root(), 'sessions'), hostCwd); + const directory = root(); + const destination = path.join(directory, 'workflows', 'journey.ad'); - const result = writer.write(recordingTo(destination)); + 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 shared = sharedDirectory(path.join(root(), 'shared'), 0o777); + const directory = root(); + const shared = sharedDirectory(path.join(directory, 'shared'), 0o777); const destination = path.join(shared, 'journey.ad'); - const writer = new SessionScriptWriter(path.join(root(), 'sessions'), hostCwd); - const details = refusal(writer.write(recordingTo(destination))); + const details = refusal(writerFor(directory).write(recordingTo(destination))); expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', @@ -91,21 +132,58 @@ skipOnWindows('a recording refuses a destination under a world-writable director expect(fs.existsSync(destination)).toBe(false); }); +skipOnWindows('a recording refuses a destination inside a directory another user owns', () => { + const directory = root(); + const foreign = path.join(directory, 'foreign'); + fs.mkdirSync(foreign); + fs.chmodSync(foreign, 0o755); + const destination = path.join(foreign, 'journey.ad'); + // The directory is this test user's own, so the rule is run as somebody else: a real second local + // user looking at a directory they cannot own but can read. + vi.spyOn(process, 'getuid').mockReturnValue(currentUid === 65534 ? 65535 : 65534); + + 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 an ancestor swapped out for a symbolic link', () => { const directory = root(); - const shared = sharedDirectory(path.join(directory, 'shared'), 0o1777); + 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 writer = new SessionScriptWriter(path.join(directory, 'sessions'), hostCwd); - const details = refusal(writer.write(recordingTo(destination))); + const details = refusal(writerFor(directory).write(recordingTo(destination))); expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'planted_link' }); 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'); @@ -115,9 +193,8 @@ skipOnWindows('a recording refuses an ancestor swapped out for a writable direct fs.rmSync(work, { recursive: true }); fs.mkdirSync(work); fs.chmodSync(work, 0o777); - const writer = new SessionScriptWriter(path.join(directory, 'sessions'), hostCwd); - const details = refusal(writer.write(recordingTo(destination))); + const details = refusal(writerFor(directory).write(recordingTo(destination))); expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', @@ -127,14 +204,27 @@ skipOnWindows('a recording refuses an ancestor swapped out for a writable direct }); skipOnWindows('a recording still saves to a group-writable private-group home', () => { - const gid = process.getgid?.(); - if (gid === undefined || !groupDatabaseMatchesHost(gid)) return; - const home = path.join(root(), 'home'); - fs.mkdirSync(home); - fs.chmodSync(home, 0o775); - const writer = new SessionScriptWriter(path.join(root(), 'sessions'), hostCwd); + privateGroupDatabase(); + const directory = root(); + const home = homeDirectory(path.join(directory, 'home'), 0o775); + const destination = path.join(home, 'journey.ad'); - const result = writer.write(recordingTo(path.join(home, 'journey.ad'))); + const result = writerFor(directory).write(recordingTo(destination)); expect(result.written).toBe(true); + expect(fs.readFileSync(destination, 'utf8')).toContain('open'); +}); + +skipOnWindows("a recording refuses the same home once the group is not this user's own", () => { + foreignGroupNameDatabase(); + 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, + }); }); 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..b7a4a0ece5 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 @@ -81,7 +81,8 @@ 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); }, ); diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index c4abbd5618..9b60e608aa 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -144,7 +144,6 @@ export class SessionScriptWriter { script: prepared.script, force: options?.force, parentIdentity: publishDirectoryIdentity(scriptDir), - ...(remote ? { mode: 0o600 } : {}), }); // COMMITTED: idempotent guard above + teardown's abort/tombstone routing. if (repairArmed) { @@ -166,8 +165,9 @@ 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. + * script included, gets a fresh file of its own in a private (0700) directory that only the daemon + * user can enter. The file itself is private (0600) like every other published script, which + * `publishScriptFileSync` decides. */ private remoteScriptPath(): string { const directory = path.join(this.sessionsDir, 'remote-scripts'); @@ -302,17 +302,15 @@ function publishHealedScriptAtomically(params: { scriptPath: string; script: string; force?: boolean; - mode?: number; parentIdentity?: string; }): void { - const { scriptPath, script, force, mode, parentIdentity } = params; + const { scriptPath, script, force, parentIdentity } = params; try { publishScriptFileSync({ destination: scriptPath, contents: script, publish: force ? 'replace' : 'link-exclusive', ...(parentIdentity === undefined ? {} : { parentIdentity }), - ...(mode === undefined ? {} : { mode }), }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; diff --git a/packages/host-kit/src/file.ts b/packages/host-kit/src/file.ts index 8779eccfb5..31f9b39988 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -1,11 +1,19 @@ export { assertPrivateScriptDestination, isAtomicPublishTemporaryPath, + othersCreateEntriesIn, + privateGroupId, publishDirectoryIdentity, publishDurableFileSync, publishFileSync, publishScriptFileSync, + untrustedAncestryExposure, + untrustedLinkExposure, + type DirectoryAuthority, type DurableFilePublishMode, + type LinkAuthority, + type ScriptAncestryExposure, + type ScriptDestinationTrust, } from './internal/atomic-file.ts'; export { lstatIfPresent, diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index 9445f855dc..4d624b8a35 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -7,15 +7,22 @@ import { AppError } from '@agent-device/kernel/errors'; import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; import { assertPrivateScriptDestination, - privateGroupIds, + othersCreateEntriesIn, + privateGroupId, publishDirectoryIdentity, publishScriptFileSync, + untrustedAncestryExposure, + untrustedLinkExposure, + type DirectoryAuthority, } from './atomic-file.ts'; const skipOnWindows = process.platform === 'win32' ? test.skip : test; /** The group database a test stands in for `/etc/group` and `/etc/passwd`. */ -type Database = Readonly<{ groups: readonly string[]; passwd: readonly string[] }>; +type Database = Readonly<{ + groups: readonly string[] | undefined; + passwd: readonly string[] | undefined; +}>; const realReadFileSync = fs.readFileSync; const currentUser = os.userInfo().username; @@ -34,8 +41,14 @@ afterEach(() => { */ function serveGroupDatabase(database: Database): void { vi.spyOn(fs, 'readFileSync').mockImplementation(((file: unknown, options?: unknown) => { - if (file === '/etc/group') return `${database.groups.join('\n')}\n`; - if (file === '/etc/passwd') return `${database.passwd.join('\n')}\n`; + if (file === '/etc/group') { + if (!database.groups) throw new Error('simulated unreadable group file'); + return `${database.groups.join('\n')}\n`; + } + if (file === '/etc/passwd') { + if (!database.passwd) throw new Error('simulated unreadable passwd file'); + return `${database.passwd.join('\n')}\n`; + } return realReadFileSync(file as never, options as never) as never; }) as typeof fs.readFileSync); } @@ -48,11 +61,19 @@ function hostDatabase(privateGid: number, sharedGid: number): Database { }; } +/** The database of a host whose group files cannot be read at all. */ +function unreadableDatabases(): Database { + return { groups: undefined, passwd: undefined }; +} + function root(): string { return fs.realpathSync(mkdtempForTestSync('host-kit-ancestry-')); } -/** A directory carrying `mode` and `gid`, so the rule reads the group the test chose. */ +/** + * A directory carrying `mode` and `gid`, so the rule reads the group the test chose. The group is set + * explicitly because a scratch directory inherits one from its parent, not necessarily this user's. + */ function directoryWith(directory: string, mode: number, gid = currentGid): string { fs.mkdirSync(directory); fs.chownSync(directory, currentUid, gid); @@ -60,6 +81,15 @@ function directoryWith(directory: string, mode: number, gid = currentGid): strin return directory; } +/** + * Runs the rule as a different local user, so the ownership checks are exercised against real + * directories owned by this test's actual user. Nothing else about the process moves: the modes stay + * what they are on disk. + */ +function asAnotherLocalUser(): void { + vi.spyOn(process, 'getuid').mockReturnValue(currentUid === 65534 ? 65535 : 65534); +} + function publish(destination: string, parentIdentity?: string): void { publishScriptFileSync({ destination, @@ -87,7 +117,11 @@ function expectRefusal(run: () => void, reason: string, exposure: string, ancest expect(details).toMatchObject({ reason, exposure, ancestor }); } -// --- a chain another local user can act inside is refused --- +function modeOf(pathname: string): number { + return fs.lstatSync(pathname).mode & 0o777; +} + +// --- a directory another user owns, or that others can write, is refused --- skipOnWindows('publishes to a chain only this user can write', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); @@ -99,6 +133,17 @@ skipOnWindows('publishes to a chain only this user can write', () => { expect(fs.readFileSync(path.join(workflows, 'journey.ad'), 'utf8')).toBe('context\n'); }); +skipOnWindows('creates the script so that only this user can read it', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + 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', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); const shared = directoryWith(path.join(root(), 'shared'), 0o777); @@ -108,23 +153,21 @@ skipOnWindows('refuses a destination under a world-writable directory', () => { expect(fs.existsSync(destination)).toBe(false); }); -skipOnWindows('refuses a world-writable ancestor above the parent', () => { +skipOnWindows('refuses a destination created inside a directory others can add entries to', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); - const shared = directoryWith(path.join(root(), 'shared'), 0o777); - const work = path.join(shared, 'work'); - fs.mkdirSync(work); + const shared = directoryWith(path.join(root(), 'shared'), 0o777 | 0o1000); expectUntrusted( - () => assertPrivateScriptDestination(path.join(work, 'journey.ad')), - 'world_writable', + () => assertPrivateScriptDestination(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 gid = currentGid; - serveGroupDatabase(hostDatabase(4321, gid)); - const team = directoryWith(path.join(root(), 'team'), 0o775, gid); + serveGroupDatabase(hostDatabase(4321, currentGid)); + const team = directoryWith(path.join(root(), 'team'), 0o775, currentGid); const sub = path.join(team, 'sub'); fs.mkdirSync(sub); @@ -132,6 +175,36 @@ skipOnWindows('refuses a destination under a group-writable shared directory', ( expect(fs.readdirSync(sub)).toEqual([]); }); +// --- ownership decides, not the mode alone --- + +skipOnWindows('refuses a private-mode directory another user owns, whatever the mode', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const work = directoryWith(path.join(root(), 'foreign'), 0o755); + asAnotherLocalUser(); + + expectUntrusted( + () => assertPrivateScriptDestination(path.join(work, 'journey.ad')), + 'foreign_owned', + work, + ); +}); + +skipOnWindows('refuses a directory its owner opened up while the file was staged', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const work = path.join(root(), 'work'); + fs.mkdirSync(work); + const destination = path.join(work, 'journey.ad'); + const realWriteFileSync = fs.writeFileSync; + vi.spyOn(fs, 'writeFileSync').mockImplementation(((file: unknown, ...rest: unknown[]) => { + const result = (realWriteFileSync as (...args: unknown[]) => unknown)(file, ...rest); + fs.chmodSync(work, 0o777); + return result; + }) as typeof fs.writeFileSync); + + expectUntrusted(() => publish(destination), 'world_writable', work); + expect(fs.readdirSync(work)).toEqual([]); +}); + // --- the Ubuntu and Debian private-group home keeps working --- skipOnWindows('publishes to a group-writable home directory of a private group', () => { @@ -145,9 +218,15 @@ skipOnWindows('publishes to a group-writable home directory of a private group', }); skipOnWindows("refuses the same mode and group once the group is not the user's own", () => { - const gid = currentGid; - serveGroupDatabase(hostDatabase(4321, gid)); - const home = directoryWith(path.join(root(), 'home'), 0o775, gid); + serveGroupDatabase(hostDatabase(4321, currentGid)); + const home = directoryWith(path.join(root(), 'home'), 0o775, currentGid); + + expectUntrusted(() => publish(path.join(home, 'journey.ad')), 'shared_group_writable', home); +}); + +skipOnWindows('refuses the same mode and group once the group database cannot be read', () => { + serveGroupDatabase(unreadableDatabases()); + const home = directoryWith(path.join(root(), 'home'), 0o775, currentGid); expectUntrusted(() => publish(path.join(home, 'journey.ad')), 'shared_group_writable', home); }); @@ -162,21 +241,24 @@ skipOnWindows('publishes to a setgid group-writable private-group home', () => { expect(fs.existsSync(path.join(home, 'journey.ad'))).toBe(true); }); -// --- a sticky shared directory is safe, except through a link planted in it --- +// --- a link is judged as the link it is, and its target is judged too --- -skipOnWindows('publishes to a destination under a sticky world-writable directory', () => { +skipOnWindows('follows a symbolic link inside a directory only this user can write', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); - const shared = directoryWith(path.join(root(), 'shared'), 0o1777); + const directory = root(); + const real = path.join(directory, 'real'); + fs.mkdirSync(real); + fs.symlinkSync(real, path.join(directory, 'link')); - publish(path.join(shared, 'journey.ad')); + publish(path.join(directory, 'link', 'journey.ad')); - expect(fs.existsSync(path.join(shared, 'journey.ad'))).toBe(true); + expect(fs.existsSync(path.join(real, 'journey.ad'))).toBe(true); }); -skipOnWindows('refuses a symbolic link planted in a directory others can write', () => { +skipOnWindows('refuses a symbolic link planted in a directory others can add entries to', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); - const shared = directoryWith(path.join(directory, 'shared'), 0o1777); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); const attacker = path.join(directory, 'attacker'); fs.mkdirSync(attacker); fs.symlinkSync(attacker, path.join(shared, 'work')); @@ -189,18 +271,88 @@ skipOnWindows('refuses a symbolic link planted in a directory others can write', expect(fs.readdirSync(attacker)).toEqual([]); }); -skipOnWindows('follows a symbolic link inside a directory only this user can write', () => { +skipOnWindows('refuses a symbolic link whose target is a directory others can write', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); - const real = path.join(directory, 'real'); - fs.mkdirSync(real); - fs.symlinkSync(real, path.join(directory, 'link')); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const privateWork = path.join(shared, 'private'); + fs.mkdirSync(privateWork); + fs.symlinkSync(privateWork, path.join(directory, 'link')); - publish(path.join(directory, 'link', 'journey.ad')); + expectUntrusted( + () => assertPrivateScriptDestination(path.join(directory, 'link', 'journey.ad')), + 'world_writable', + shared, + ); +}); - expect(fs.existsSync(path.join(real, 'journey.ad'))).toBe(true); +skipOnWindows( + 'refuses a symbolic link another local user owns in a sticky shared directory', + () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const shared = directoryWith(path.join(root(), 'shared'), 0o1777); + const attacker = path.join(root(), 'attacker'); + fs.mkdirSync(attacker); + fs.symlinkSync(attacker, path.join(shared, 'work')); + asAnotherLocalUser(); + + expectUntrusted( + () => assertPrivateScriptDestination(path.join(shared, 'work', 'journey.ad')), + 'planted_link', + path.join(shared, 'work'), + ); + }, +); + +skipOnWindows('keeps working through a root-owned alias whose target is sticky', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const directory = root(); + const alias = path.join(directory, 'alias'); + const target = path.join(directory, 'target'); + fs.mkdirSync(target); + fs.chmodSync(target, 0o1777); + fs.symlinkSync(target, alias); + const work = path.join(alias, 'work'); + fs.mkdirSync(work); + fs.chmodSync(work, 0o700); + + publish(path.join(work, 'journey.ad')); + + expect(fs.existsSync(path.join(target, 'work', 'journey.ad'))).toBe(true); }); +skipOnWindows('publishes through the host root-owned system alias /tmp', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // macOS reaches `/private/tmp` through `/tmp`, and Linux mounts `/tmp` directly. Either way the + // script lands in a sticky root-owned directory, so the alias must not be what ends the publish. + if (!fs.existsSync('/tmp') || !fs.lstatSync('/tmp').isSymbolicLink()) return; + 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 scratch path spelled through a system alias, not resolved away', + () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // The scratch root of `root()` is the resolved path. This one keeps whatever alias the host spells + // its temporary directory with, which is the shape a caller actually passes. + const directory = mkdtempForTestSync('host-kit-ancestry-alias-'); + expect(fs.realpathSync(directory)).not.toBe(directory); + 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 --- skipOnWindows('refuses a parent replaced by name while the file was staged', () => { @@ -225,7 +377,6 @@ skipOnWindows('re-checks the chain after staging the file, before the entry is c fs.mkdirSync(staged); const destination = path.join(staged, 'journey.ad'); const writeFileSync = fs.writeFileSync; - // The window a second local user races: the file is staged, the entry is not created yet. vi.spyOn(fs, 'writeFileSync').mockImplementation(((file: unknown, ...rest: unknown[]) => { const result = (writeFileSync as (...args: unknown[]) => unknown)(file, ...rest); fs.rmSync(staged, { recursive: true, force: true }); @@ -248,68 +399,146 @@ skipOnWindows('publishes into the parent the captured identity still names', () expect(fs.existsSync(path.join(staged, 'journey.ad'))).toBe(true); }); -// --- privateGroupIds: the one group shape the exception admits --- +// --- untrustedAncestryExposure: what makes one directory unsafe to publish inside --- -const ADA = { uid: 1000, name: 'ada' }; +const OWN = { uid: currentUid, gid: currentGid, mode: 0o755 }; +const TRUST = { uid: currentUid, privateGid: currentGid }; -function database(groups: readonly string[], passwd: readonly string[]) { - return { groups, passwd }; +function directoryOf(overrides: Partial): DirectoryAuthority { + return { ...OWN, ...overrides }; } -test('treats the group named after the user, holding only them, as private', () => { - const ids = privateGroupIds( - database(['ada:x:1000:', 'staff:x:20:root'], ['ada:x:1000:1000:', 'root:x:0:0']), - ADA, +test('refuses a directory another user owns even in private mode', () => { + expect(untrustedAncestryExposure(directoryOf({ uid: 65534 }), 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 by a group that is not this user', () => { + expect(untrustedAncestryExposure(directoryOf({ gid: 4321, mode: 0o775 }), TRUST)).toBe( + 'shared_group_writable', ); - expect([...ids]).toEqual([1000]); }); -test('treats a group as private when only its primary-group link names the user', () => { - const ids = privateGroupIds( - database(['ada:x:1000:', 'staff:x:20:'], ['root:x:0:0', 'ada:x:1000:1000:']), - ADA, +test('accepts a directory group-writable by this user', () => { + expect(untrustedAncestryExposure(directoryOf({ mode: 0o775 }), TRUST)).toBeUndefined(); +}); + +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 shared directory for passing through, in any ownership', () => { + expect(untrustedAncestryExposure(directoryOf({ mode: 0o1777 }), TRUST)).toBeUndefined(); + expect(untrustedAncestryExposure(directoryOf({ uid: 65534, mode: 0o1777 }), TRUST)).toBe( + 'foreign_owned', ); - expect([...ids]).toEqual([1000]); }); -test('still treats a group as private with root among its members', () => { - const ids = privateGroupIds( - database(['ada:x:1000:root', 'staff:x:20:'], ['ada:x:1000:1000:', 'root:x:0:0']), - ADA, +// --- 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({ mode: 0o775 }), TRUST)).toBeUndefined(); +}); + +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([...ids]).toEqual([1000]); + 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(); }); -test('treats the group named after the user as shared once another user is a member', () => { - const ids = privateGroupIds( - database( - ['ada:x:1000:grace', 'staff:x:20:'], - ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0'], +// --- 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({ gid: 4321, mode: 0o775 }), TRUST)).toBe(true); +}); + +test('names no directory whose group is this user', () => { + expect(othersCreateEntriesIn(directoryOf({ mode: 0o775 }), TRUST)).toBe(false); + expect(othersCreateEntriesIn(directoryOf({ mode: 0o1775 }), TRUST)).toBe(false); + expect(othersCreateEntriesIn(directoryOf({ mode: 0o755 }), TRUST)).toBe(false); +}); + +// --- privateGroupId: the one group shape the exception admits --- + +const ADA = { uid: 1000, gid: 1000, name: 'ada' }; + +function database(groups: readonly string[] | undefined, passwd: readonly string[] | undefined) { + return { groups, passwd }; +} + +const PRIVATE = ['ada:x:1000:', 'staff:x:20:root']; +const PRIVATE_PASSWD = ['ada:x:1000:1000:', 'root:x:0:0']; + +test('admits the group named after the user, holding only them, as their primary group', () => { + expect(privateGroupId(database(PRIVATE, PRIVATE_PASSWD), ADA)).toBe(1000); +}); + +test('admits it with root named among its members', () => { + expect( + privateGroupId(database(['ada:x:1000:root'], ['ada:x:1000:1000:', 'root:x:0:0']), ADA), + ).toBeUndefined(); +}); + +test('refuses it once another user is a member', () => { + expect( + privateGroupId( + database(['ada:x:1000:grace'], ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0']), + ADA, ), - ADA, - ); - expect([...ids]).toEqual([]); + ).toBeUndefined(); }); -test('treats the group named after the user as shared once another user has it as primary group', () => { - const ids = privateGroupIds( - database(['ada:x:1000:', 'staff:x:20:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), - ADA, - ); - expect([...ids]).toEqual([]); +test('refuses it once another user has it as their primary group', () => { + expect( + privateGroupId(database(['ada:x:1000:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), ADA), + ).toBeUndefined(); +}); + +test('refuses a group that is not the primary group of the user, however few members it lists', () => { + expect(privateGroupId(database(['ada:x:4321:'], ['ada:x:1000:1000:']), ADA)).toBeUndefined(); +}); + +test('refuses a group that does not carry the name of the user', () => { + expect(privateGroupId(database(['team:x:1000:'], ['ada:x:1000:1000:']), ADA)).toBeUndefined(); +}); + +test('refuses it when the group file cannot be read', () => { + expect(privateGroupId(database(undefined, PRIVATE_PASSWD), ADA)).toBeUndefined(); +}); + +test('refuses it when the passwd file cannot be read', () => { + expect(privateGroupId(database(PRIVATE, undefined), ADA)).toBeUndefined(); }); -test('never treats another group name as private, however few members it lists', () => { - const ids = privateGroupIds(database(['team:x:4321:', 'ada:x:1000:'], ['ada:x:1000:1000:']), ADA); - expect([...ids]).toEqual([1000]); +test('refuses it when the user has no passwd record', () => { + expect(privateGroupId(database(PRIVATE, ['root:x:0:0']), ADA)).toBeUndefined(); }); -test('treats an unreadable group database as having no private group', () => { - expect([...privateGroupIds(database([], []), ADA)]).toEqual([]); +test('refuses it when the passwd record names another uid or gid', () => { + const other = { uid: 1002, gid: 1000, name: 'ada' }; + expect(privateGroupId(database(PRIVATE, PRIVATE_PASSWD), other)).toBeUndefined(); }); test('gives a caller without a full identity no private group', () => { - const groups = database(['ada:x:1000:'], ['ada:x:1000:1000:']); - expect([...privateGroupIds(groups, { uid: undefined, name: 'ada' })]).toEqual([]); - expect([...privateGroupIds(groups, { uid: 1000, name: undefined })]).toEqual([]); + const groups = database(PRIVATE, PRIVATE_PASSWD); + expect(privateGroupId(groups, { uid: undefined, gid: 1000, name: 'ada' })).toBeUndefined(); + expect(privateGroupId(groups, { uid: 1000, gid: undefined, name: 'ada' })).toBeUndefined(); + expect(privateGroupId(groups, { uid: 1000, gid: 1000, name: undefined })).toBeUndefined(); }); diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index f05b8550b3..daa90aaf74 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -48,8 +48,8 @@ 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): the chain is refused before - * anything is written, and it is checked again immediately before the link or rename, so a directory - * swapped in by another local user while the file was staged never receives the script. + * anything is staged, and it is judged again immediately before the link or rename. The file is created + * private, because a recording is a transcript of what someone did on this machine. * * `parentIdentity` is what {@link publishDirectoryIdentity} returned for a parent the caller created or * checked before it staged this file. @@ -61,15 +61,12 @@ export function publishScriptFileSync(options: { publish?: AtomicPublishMode; parentIdentity?: string; }): void { + const mode = options.mode ?? 0o600; const expected = options.parentIdentity ?? publishDirectoryIdentity(path.dirname(options.destination)); withAtomicPublishTempPathSync(options.destination, (temporaryPath) => { assertPrivateScriptDestination(options.destination, expected); - fs.writeFileSync( - temporaryPath, - options.contents, - options.mode === undefined ? 'utf8' : { encoding: 'utf8', mode: options.mode }, - ); + fs.writeFileSync(temporaryPath, options.contents, { encoding: 'utf8', mode }); assertPrivateScriptDestination(options.destination, expected); if (options.publish === 'link-exclusive') { fs.linkSync(temporaryPath, options.destination); @@ -186,33 +183,41 @@ export function isAtomicPublishTemporaryPath(value: unknown, destination: string } /** - * Refuses a script destination when another local user can write a directory on the way to it (#4565). + * Refuses a script destination unless every directory on its fully resolved chain is one no other + * non-root local user can change (#4565). * * Node exposes no `openat` or `renameat`, so a publisher cannot resolve a destination relative to a - * directory handle. What remains is to refuse every chain a second local user can act inside: a - * directory they can write is one where they can replace a component of this path, or create one before - * this client does, so the script lands where they choose, or they take it from a directory they own. + * directory handle. The window is closed by PERMISSIONS instead of by timing: once no other non-root + * user can add or remove an entry in any directory on the chain, nobody can swap a component out or + * plant one, so the path this rule judged is the path the publish reaches. Nothing here depends on when + * the directory was judged, and no re-check is what makes the write safe. + * + * The existing prefix of the destination is resolved once, and every directory of that resolved chain + * is judged, so a symbolic link's target is judged too: `/home/me/link` standing for a shared directory + * is refused for the same reason that directory would be if the caller had spelled it out. Each + * directory then has to satisfy: * - * The rule reads each component with `lstat`, so a symbolic link is judged as the link it is and is - * never mistaken for the directory its target names: + * - It is owned by this user or by root. A directory another user owns is theirs to chmod, to empty, and + * to repopulate, whatever its mode says today. + * - Its mode opens its contents to nobody else. The sticky bit is the one exception, and only for + * passing THROUGH a directory: it stops anyone but an entry's owner or root from removing or replacing + * that entry, which is how macOS `/tmp` and `/var` stay usable. It cannot refuse a NEW entry by name, + * so nothing may be created inside a directory others can add entries to; that is asked separately. + * - A symbolic link the path passes through is one others could not have planted or swapped: in a + * directory where they can add entries, it stands there only because the sticky bit and its owner + * hold it in place. * - * - A component's mode decides. The sticky bit cancels the exposure: it stops anyone but an entry's - * owner or root from removing or replacing that entry, which is how a shared team directory is made - * safe, and why the hint names it. - * - Otherwise a component writable by anyone other than this user is refused, except a group-writable - * one whose group is this user's own private group: Ubuntu and Debian set up every home directory - * that way, often group-writable, and those have to stay usable. - * - A symbolic link whose own directory others can create entries in is refused whatever it points at: - * it may be one they planted, and its target is theirs to choose. The sticky bit does not help here, - * because it guards entries that already exist. + * A group-writable directory this user owns stays acceptable when its group is this user's own private + * group, the shape Ubuntu and Debian give every home directory. {@link privateGroupId} says what that + * takes to establish, and what it cannot. * - * An absent or non-directory component is left alone: the filesystem refuses a publish through it. On - * Windows, access is an ACL rather than a mode, so this is a no-op there. + * A component that exists and is neither a directory nor a link is left alone: the filesystem refuses a + * publish through it. On Windows, access is an ACL rather than a mode, so this is a no-op there. * * `parentIdentity` is what {@link publishDirectoryIdentity} returned for the parent the caller created - * or checked before it staged this file. Whoever owns a directory above it can open that directory to - * others, swap the parent for one of their own while the file is staged, and close it again, and only - * the identity catches that. + * or checked before it staged this file. The rule above already excludes anyone who could swap that + * parent, so the comparison is defense in depth against a host whose ownership or modes moved meanwhile; + * it is not what closes the window. */ export function assertPrivateScriptDestination(destination: string, parentIdentity?: string): void { if (process.platform === 'win32') return; @@ -220,20 +225,78 @@ export function assertPrivateScriptDestination(destination: string, parentIdenti if (parentIdentity !== undefined && publishDirectoryIdentity(parent) !== parentIdentity) { throw scriptAncestryFailure(destination, parent, 'parent_replaced'); } - const privateGids = lazyPrivateGroupIds(); + const trust = readScriptTrust(); + assertNoPlantedLink(destination, parent, trust); + const existing = deepestExistingDirectory(parent); + if (existing.real === undefined) return; + const chain = directoryChain(existing.real); + for (const ancestor of chain) { + const stats = statDirectoryChain(ancestor); + if (!stats) continue; + const exposure = untrustedAncestryExposure(stats, trust); + if (exposure) throw scriptAncestryFailure(destination, ancestor, exposure); + } + // The script entry is created inside the deepest directory that exists, or below it through + // directories that do not exist yet. Where other local users can add entries, one of them can add + // this entry first and the recording is theirs, so the creation has to be refused. + const deepest = statDirectoryChain(existing.real); + if (deepest && othersCreateEntriesIn(deepest, trust)) { + throw scriptAncestryFailure(destination, existing.real, 'shared_parent'); + } +} + +/** + * Refuses a symbolic link on the spelled path that another local user could have put there, or could + * replace. The link's target is judged through the resolved chain, so this only asks whether the link + * itself is stable: + * + * - In a directory others cannot add entries in, a link nobody but this user or root can write is not + * something they can plant or swap. + * - In a directory others CAN add entries in, the sticky bit is what protects an entry that already + * exists: it stops anyone but the entry's owner or root from removing or replacing it. Without the + * sticky bit, any of them can unlink this link and plant one pointing wherever they choose. + */ +function assertNoPlantedLink( + destination: string, + parent: string, + trust: ScriptDestinationTrust, +): void { for (const ancestor of directoryChain(parent)) { const link = lstatIfPresentSync(ancestor); - if (!link) continue; - if (link.isSymbolicLink() && othersCreateEntriesIn(path.dirname(ancestor), privateGids)) { - throw scriptAncestryFailure(destination, ancestor, 'planted_link'); - } - const directory = link.isSymbolicLink() ? statDirectoryChain(ancestor) : link; - if (!directory?.isDirectory()) continue; - const exposure = untrustedWritableExposure(directory, privateGids()); + if (!link?.isSymbolicLink()) continue; + const home = lstatIfPresentSync(path.dirname(ancestor)); + if (!home) continue; + const exposure = untrustedLinkExposure( + { uid: link.uid }, + { uid: home.uid, gid: home.gid, mode: home.mode }, + trust, + ); if (exposure) throw scriptAncestryFailure(destination, ancestor, exposure); } } +/** + * The real path of the deepest directory `directory` names or leads to, or `undefined` when nothing of it + * exists to judge. A component that exists but resolves to nothing (a dangling link) is stepped over like + * one that is absent, so the walk never stops with nothing checked. + */ +function deepestExistingDirectory(directory: string): Readonly<{ real: string | undefined }> { + let current = directory; + for (;;) { + if (lstatIfPresentSync(current) !== undefined) { + try { + const real = fs.realpathSync(current); + if (statDirectoryChain(real)) return { real }; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; + } + } + const parent = path.dirname(current); + if (parent === current) return { real: undefined }; + current = parent; + } +} + /** * One directory's identity on its filesystem, for a caller that must publish into the same one it * created or checked. `undefined` when the directory is absent or is not a directory. @@ -246,59 +309,68 @@ export function publishDirectoryIdentity(directory: string): string | undefined /** The group and passwd records the private-group exception reads, in `/etc/group` field order. */ type HostGroupDatabase = Readonly<{ - groups: readonly string[]; - passwd: readonly string[]; + /** `undefined` when the file could not be read, which is not the same as a file with no records. */ + groups: readonly string[] | undefined; + passwd: readonly string[] | undefined; }>; /** - * The private group of `current`, in the one shape the exception admits: the group named after them. + * The single group the private-group exception admits, or `undefined` when nothing was established. * * Ubuntu and Debian create one group per user, named after them, and set up that user's home directory - * with it, often group-writable. Such a home is shared with no other local user, so it stays a valid - * script destination. Every other group name stays outside the exception: this host's own records - * cannot bound it, because macOS lists only part of `staff` in `/etc/group` while every local user - * holds it, and a name service can add members to a group this machine cannot read. + * with it, often group-writable and owned by that user. Such a home is shared with no other local user, + * so it stays a valid script destination. Every other group stays outside the exception, and the rule + * fails closed wherever completeness cannot be established: * - * Membership comes from both places a member can appear: the group's own member list, and the users - * whose primary group is this one. A member who is neither `current` nor root disqualifies the group. + * - Both database files must have been READ. An unreadable file is not an empty one, and an empty + * member list proves nothing. + * - The group must be the one this process holds as its PRIMARY group, which `getgid` answers from the + * kernel rather than from a file, and it must carry this user's name. + * - The group's own member list may name nobody but this user. macOS lists only part of `staff` in + * `/etc/group` while every local user holds it, so a name that is not this user's ends the claim + * rather than being looked up and forgiven. + * - No other record in the passwd file may hold this group as its primary group, and the caller's own + * record must exist there with this uid and this gid. + * + * What this cannot establish: a name service (LDAP, NSS modules) can add a user whose primary group is + * this gid without that user ever appearing in `/etc/passwd`. A host configured that way can still be + * refused a group-writable destination it appears to own, which is the residual limitation the + * documentation names; the caller's fallback is a directory only they can write. */ -export function privateGroupIds( +export function privateGroupId( database: HostGroupDatabase, - current: Readonly<{ uid: number | undefined; name: string | undefined }>, -): Set { - const privateIds = new Set(); - if (current.uid === undefined || current.name === undefined) return privateIds; - const uidByName = new Map(); - const primaryMembers = new Map(); - for (const line of database.passwd) { - const [name, , rawUid, rawGid] = line.split(':'); - const uid = Number(rawUid); - const gid = Number(rawGid); - if (!name || !Number.isInteger(uid) || !Number.isInteger(gid)) continue; - uidByName.set(name, uid); - primaryMembers.set(gid, [...(primaryMembers.get(gid) ?? []), name]); - } - for (const line of database.groups) { - const [name, , rawGid, rawMembers] = line.split(':'); - const gid = Number(rawGid); - if (name !== current.name || !Number.isInteger(gid)) continue; - const supplementary = (rawMembers ?? '').split(',').filter((member) => member.length > 0); - const ids = [...supplementary, ...(primaryMembers.get(gid) ?? [])].map((member) => - uidByName.get(member), - ); - if (ids.every((id) => id === current.uid || id === 0)) privateIds.add(gid); - } - return privateIds; + current: Readonly<{ uid: number | undefined; gid: number | undefined; name: string | undefined }>, +): number | undefined { + const { uid, gid, name } = current; + if (uid === undefined || gid === undefined || name === undefined) return undefined; + if (!database.groups || !database.passwd) return undefined; + const record = database.groups.find((line) => line.split(':')[0] === name); + if (!record) return undefined; + const [, , rawGid, rawMembers = ''] = record.split(':'); + const privateGid = Number(rawGid); + if (!Number.isInteger(privateGid) || privateGid !== gid) return undefined; + const members = rawMembers.split(',').filter((member) => member.length > 0); + if (members.some((member) => member !== name)) return undefined; + const own = database.passwd.find((line) => line.split(':')[0] === name); + if (!own) return undefined; + const [, , ownUid, ownGid] = own.split(':'); + if (Number(ownUid) !== uid || Number(ownGid) !== gid) return undefined; + const sharesPrimary = database.passwd.some((line) => { + const [other, , , otherGid] = line.split(':'); + return other !== name && Number(otherGid) === gid; + }); + return sharesPrimary ? undefined : gid; } -/** This host's private groups, read from the group database the first time the chain meets one. */ -function lazyPrivateGroupIds(): () => ReadonlySet { - let cached: ReadonlySet | undefined; - return () => - (cached ??= privateGroupIds( +/** This process's identity and the private group its host databases establish, if any. */ +function readScriptTrust(): ScriptDestinationTrust { + return { + uid: process.getuid?.() ?? -1, + privateGid: privateGroupId( { groups: readSystemFile('/etc/group'), passwd: readSystemFile('/etc/passwd') }, - { uid: process.getuid?.(), name: readCurrentUser() }, - )); + { uid: process.getuid?.(), gid: process.getgid?.(), name: readCurrentUser() }, + ), + }; } function readCurrentUser(): string | undefined { @@ -321,59 +393,120 @@ function directoryChain(directory: string): string[] { } } -/** Why other local users can write in this directory, or `undefined` when only this user and root can. */ -function untrustedWritableExposure( - stats: fs.Stats, - privateGids: ReadonlySet, -): AncestryExposure | undefined { - if (stats.mode & 0o1000) return undefined; - if (stats.mode & 0o002) return 'world_writable'; - if (stats.mode & 0o020 && !privateGids.has(stats.gid)) return 'shared_group_writable'; +/** + * The two ways a directory can be unsafe for a destination: someone else can change what is in it, or + * someone else can create the entry the destination names. + * + * `foreign_owned` — some other user owns it and can chmod, empty, or repopulate it whatever its mode. + * `world_writable` / `shared_group_writable` — its mode opens its contents to others. + * `shared_parent` — nobody else can change what is in it today, but they can add the missing entry. + * `planted_link` — a symbolic link someone else could have put in place of a directory. + * `parent_replaced` — the directory the caller staged against is not the one it was. + */ +export type ScriptAncestryExposure = + | 'foreign_owned' + | 'world_writable' + | 'shared_group_writable' + | 'shared_parent' + | 'planted_link' + | 'parent_replaced'; + +/** What this process can rely on when it judges a directory: its identity and its private group. */ +export type ScriptDestinationTrust = Readonly<{ + uid: number; + privateGid: number | undefined; +}>; + +/** The fields of a directory the ancestry rule reads, so the decision is testable without a filesystem. */ +export type DirectoryAuthority = Readonly<{ uid: number; gid: number; mode: number }>; + +/** + * 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, to empty, and to + * repopulate whatever its mode says today, and no race is needed to do it. Then the mode, because + * group- or other-writable contents are open to those users directly. The sticky bit is the one mode + * exception, and it is sound only for PASSING THROUGH a directory: it stops anyone but an entry's owner + * or root from removing or replacing that entry, so the entries already on the path hold. It cannot + * refuse a NEW entry by name, so {@link othersCreateEntriesIn} is asked separately before anything is + * created inside. + */ +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 && directory.gid !== trust.privateGid) return 'shared_group_writable'; return undefined; } -/** Whether other local users can create an entry here: how a component becomes their symbolic link. */ -function othersCreateEntriesIn(directory: string, privateGids: () => ReadonlySet): boolean { - const stats = statDirectoryChain(directory); - if (!stats) return false; - if (stats.mode & 0o002) return true; - return Boolean(stats.mode & 0o020) && !privateGids().has(stats.gid); +/** + * Whether other local users can add an entry here, which is how the destination's own name, or a + * directory below it, becomes theirs. The sticky bit is deliberately not consulted: it protects entries + * that already exist and cannot refuse a new one. + */ +export function othersCreateEntriesIn( + directory: DirectoryAuthority, + trust: ScriptDestinationTrust, +): boolean { + if (directory.mode & 0o002) return true; + return Boolean(directory.mode & 0o020) && directory.gid !== trust.privateGid; } -type AncestryExposure = - | 'world_writable' - | 'shared_group_writable' - | 'planted_link' - | 'parent_replaced'; +/** The fields of a symbolic link the ancestry rule reads. */ +export type LinkAuthority = Readonly<{ uid: number }>; + +/** + * 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 add entries, the sticky bit is the only thing holding an existing entry in place: it + * stops anyone but the entry's owner or root from unlinking and replacing it, so a link this user or root + * owns stands, and one anybody else owns does not — it may be theirs, and without the sticky bit any of + * them can swap it for one pointing wherever they like. + */ +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'; +} function scriptAncestryFailure( destination: string, ancestor: string, - exposure: AncestryExposure, + exposure: ScriptAncestryExposure, ): AppError { - const writableByOthers = exposure !== 'parent_replaced'; + const replaced = exposure === 'parent_replaced'; return new AppError( 'COMMAND_FAILED', - writableByOthers - ? `Refusing to save the script under ${ancestor}: another local user can write that part of the path.` - : `The directory for ${destination} changed while the script was staged, so the script was not saved.`, + replaced + ? `The directory for ${destination} changed while the script was staged, so the script was not saved.` + : `Refusing to save the script under ${ancestor}: another local user owns or can write that part of the path.`, { - reason: writableByOthers ? 'script_ancestor_untrusted' : 'script_ancestry_replaced', + reason: replaced ? 'script_ancestry_replaced' : 'script_ancestor_untrusted', exposure, path: destination, ancestor, - hint: writableByOthers - ? `Save the script under a directory only you can write, or share ${ancestor} safely with the sticky bit (chmod +t) and keep symbolic links out of the path.` - : 'Re-record with open --save-script, or save under a directory nobody else can write.', + hint: replaced + ? 'Re-record with open --save-script, or save under a directory nobody else can write.' + : 'Save the script under a directory you own that only you can write, and keep the path out of directories other users own.', }, ); } -function readSystemFile(file: string): string[] { +function readSystemFile(file: string): string[] | undefined { try { return fs.readFileSync(file, 'utf8').split('\n'); } catch { - return []; + return undefined; } } 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 d9217963d5..aafd6276bb 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts @@ -471,7 +471,7 @@ test.skipIf(process.platform === 'win32').each([ plant: (root: string) => { const shared = path.join(root, 'shared'); fs.mkdirSync(shared); - fs.chmodSync(shared, 0o1777); + fs.chmodSync(shared, 0o777); const attacker = path.join(root, 'attacker'); fs.mkdirSync(attacker); fs.symlinkSync(attacker, path.join(shared, 'work')); diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 94b317b64c..009f1b7e97 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -108,7 +108,7 @@ 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 on the way to that path must be one that only you and root can write; see +Every directory on the way to that path must be one that no other local user can change; see [Record a replay script](replay-e2e.md#record-a-replay-script). 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 diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 0e07e1ef20..0f6ded164a 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -70,10 +70,11 @@ 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. -- Every directory on the way to the script must be one that only you and root can write. Another local user who can write such a directory can replace a directory on the path, or leave a symbolic link there, before the script is moved into place. The script then lands where they choose. -- A shared team directory is safe once it has the sticky bit (`chmod +t`): it stops anyone but an entry's owner or root from replacing that entry. A group-writable home directory of your own private group, the shape Ubuntu and Debian create, is accepted. A symbolic link inside a directory others can write is refused, whatever it points at. -- 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. Choosing a directory nobody else can write, or adding the sticky bit, clears it. +- Missing parent directories are created. The script file itself is created so that only you can read it. +- Every directory on the way to the script 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 whole real path is checked, so a symbolic link to a shared directory is refused too. 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. Root-owned system links such as macOS `/tmp` and `/var` keep working. +- A directory may pass through a shared directory that carries the sticky bit (`chmod +t`), because that bit stops anyone but an entry's owner or root from replacing it. The script is never created *inside* such a directory: there, anyone could create your file's name first. A group-writable directory you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories. +- 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. - 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. From 5816981923135ae8e06dafafa172475d14a35c16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 12:14:44 +0100 Subject: [PATCH 07/28] fix(host-kit): keep foreign ground out of a script destination chain Three ways through the ownership rule stayed open, and the identity check was described as the thing that closes a race. Ownership is now asked before the mode. `othersCreateEntriesIn` treats a directory another user owns as theirs whatever its mode, so a link that stands in their private-mode component is refused: they can rename that component and leave one of their own there. A sticky bit excuses a directory only when this user or root owns it, because both the sticky bit and the group bits shield other users FROM an owner rather than the reverse. The chain keeps the `..` segments it was spelled with, so `/shared/work/../x` is judged as the walk the kernel performs, with the link named `work` in it, instead of the directory `path.resolve` names after folding the `..` away; the fold points at a directory that receives nothing. The documentation and the refusal hint now say what the rule does: a directory is accepted when this user or root owns it and its mode keeps its contents closed to others, and the destination is never created where others may add entries. The hint names ownership as well as writability. Three ancestry tests were macOS-only in effect: an assertion that the scratch root must differ from its real path cannot hold where `/tmp` is a real directory, and two identity checks passed only because the filesystem handed back a just-freed inode. The alias case now builds the alias it needs, and a replaced parent is replaced with a directory that really is another one. Refs #4565 Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 2 +- .../src/internal/atomic-file-ancestry.test.ts | 226 +++++++++++++++--- packages/host-kit/src/internal/atomic-file.ts | 54 ++++- website/docs/docs/replay-e2e.md | 2 +- 4 files changed, 245 insertions(+), 39 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 3190810e92..3f92ed4e4c 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -210,7 +210,7 @@ It adds no state name, command, or flag: 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 on its fully resolved chain. 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 chain is resolved first, so a symbolic link's target is judged under the same rule. A link is refused when another user could have placed it or could replace it: in a directory where others may add entries, only a link owned by the current user or root and held by the sticky bit is trusted. Root-owned system aliases (macOS `/tmp` to `/private/tmp`, `/var` to `/private/var`) keep working. -The sticky bit excuses a directory the chain passes THROUGH, because it stops anyone but an entry's owner or root from replacing that entry; it never excuses creating the destination inside that directory, because anyone could create that name first. 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 fails closed when either file is unreadable. Residual limitation: a name service (LDAP or an NSS module) can add a member holding that primary GID without it appearing in `/etc/passwd`, so such a host can be refused a group-writable directory it appears to own. The fallback is a directory only the user can write. +The sticky bit excuses a directory the chain 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. 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 fails closed when either file is unreadable. Residual limitation: a name service (LDAP or an NSS module) can add a member holding that primary GID without it appearing in `/etc/passwd`, so such a host can be refused a group-writable directory it appears to own. The fallback is a directory only the user can write. 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. diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index 4d624b8a35..efdb75704d 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -26,6 +26,9 @@ type Database = Readonly<{ const realReadFileSync = fs.readFileSync; const currentUser = os.userInfo().username; +/** The unmocked `stat` calls, so a second fixture here never wraps the first one's mock. */ +const realLstatSync = fs.lstatSync.bind(fs); +const realStatSync = fs.statSync.bind(fs); /** This process's ids. Windows has neither, and every test that uses them is skipped there. */ const currentUid = process.getuid?.() ?? -1; @@ -66,6 +69,26 @@ function unreadableDatabases(): Database { return { groups: undefined, passwd: undefined }; } +/** + * 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. A real foreign owner would need privileges this test does not have. + */ +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); +} + +/** Some other local user, not this one and not root. */ +const FOREIGN_UID = 65534; + function root(): string { return fs.realpathSync(mkdtempForTestSync('host-kit-ancestry-')); } @@ -177,10 +200,10 @@ skipOnWindows('refuses a destination under a group-writable shared directory', ( // --- ownership decides, not the mode alone --- -skipOnWindows('refuses a private-mode directory another user owns, whatever the mode', () => { +skipOnWindows('refuses a directory another user owns, whatever the mode', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); const work = directoryWith(path.join(root(), 'foreign'), 0o755); - asAnotherLocalUser(); + serveOwnership({ [work]: FOREIGN_UID }); expectUntrusted( () => assertPrivateScriptDestination(path.join(work, 'journey.ad')), @@ -189,6 +212,87 @@ skipOnWindows('refuses a private-mode directory another user owns, whatever the ); }); +skipOnWindows( + 'refuses a sticky directory another user owns, since both bits shield others from them', + () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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( + () => assertPrivateScriptDestination(path.join(work, 'journey.ad')), + 'foreign_owned', + team, + ); + }, +); + +skipOnWindows( + 'refuses a recordings directory another local user created first in a sticky /tmp', + () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `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( + () => assertPrivateScriptDestination(path.join(recordings, 'journey.ad')), + 'foreign_owned', + recordings, + ); + }, +); + +skipOnWindows('refuses a link standing in a private-mode directory another user owns', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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( + () => assertPrivateScriptDestination(path.join(teammate, 'link', 'journey.ad')), + 'planted_link', + path.join(teammate, 'link'), + ); + expect(fs.readdirSync(mine)).toEqual([]); +}); + +skipOnWindows('judges the directories a .. in the path walks through', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `/shared/work/../x/journey.ad` is a path a caller can pass. Resolving it first answers + // `/shared/x/journey.ad`, which is a DIFFERENT directory from the one that receives the file: + // the kernel walks `work` into the link's target and steps back from THERE, so the entry is created + // beside that target. The rule has to judge the components it walked, so the link is refused here. + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const published = directoryWith(path.join(directory, 'published'), 0o700); + const attacker = path.join(published, 'attacker'); + fs.mkdirSync(attacker); + fs.symlinkSync(attacker, path.join(shared, 'work')); + + expectUntrusted( + () => assertPrivateScriptDestination(`${shared}/work/../x/journey.ad`), + 'planted_link', + path.join(shared, 'work'), + ); + expect(fs.readdirSync(attacker)).toEqual([]); +}); + skipOnWindows('refuses a directory its owner opened up while the file was staged', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); const work = path.join(root(), 'work'); @@ -271,6 +375,29 @@ skipOnWindows('refuses a symbolic link planted in a directory others can add ent expect(fs.readdirSync(attacker)).toEqual([]); }); +skipOnWindows('refuses a private link whose target chain is a shared directory', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `~/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( + () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), + 'world_writable', + team, + ); +}); + skipOnWindows('refuses a symbolic link whose target is a directory others can write', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); @@ -321,11 +448,11 @@ skipOnWindows('keeps working through a root-owned alias whose target is sticky', expect(fs.existsSync(path.join(target, 'work', 'journey.ad'))).toBe(true); }); -skipOnWindows('publishes through the host root-owned system alias /tmp', () => { +skipOnWindows('publishes under the host root-owned system temporary directory', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); - // macOS reaches `/private/tmp` through `/tmp`, and Linux mounts `/tmp` directly. Either way the - // script lands in a sticky root-owned directory, so the alias must not be what ends the publish. - if (!fs.existsSync('/tmp') || !fs.lstatSync('/tmp').isSymbolicLink()) return; + // 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'); @@ -337,21 +464,33 @@ skipOnWindows('publishes through the host root-owned system alias /tmp', () => { } }); -skipOnWindows( - 'publishes to a scratch path spelled through a system alias, not resolved away', - () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - // The scratch root of `root()` is the resolved path. This one keeps whatever alias the host spells - // its temporary directory with, which is the shape a caller actually passes. - const directory = mkdtempForTestSync('host-kit-ancestry-alias-'); - expect(fs.realpathSync(directory)).not.toBe(directory); - const destination = path.join(directory, 'journey.ad'); +skipOnWindows('publishes to a path spelled through an alias of the directory that holds it', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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); + publish(destination); - expect(fs.readFileSync(destination, 'utf8')).toBe('context\n'); - }, -); + expect(fs.readFileSync(path.join(real, 'journey.ad'), 'utf8')).toBe('context\n'); +}); + +skipOnWindows('publishes to a scratch path exactly as the host spelled it', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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 --- @@ -362,12 +501,16 @@ skipOnWindows('refuses a parent replaced by name while the file was staged', () fs.mkdirSync(staged); const parentIdentity = publishDirectoryIdentity(staged); const destination = path.join(staged, 'journey.ad'); + // 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 }); - const replaced = path.join(directory, 'work'); - fs.mkdirSync(replaced); + fs.symlinkSync(elsewhere, staged); - expectUntrustedReplaced(() => publish(destination, parentIdentity), replaced); - expect(fs.readdirSync(replaced)).toEqual([]); + expectUntrustedReplaced(() => publish(destination, parentIdentity), staged); + expect(fs.readdirSync(elsewhere)).toEqual([]); }); skipOnWindows('re-checks the chain after staging the file, before the entry is created', () => { @@ -376,17 +519,20 @@ skipOnWindows('re-checks the chain after staging the file, before the entry is c const staged = path.join(directory, 'work'); fs.mkdirSync(staged); const destination = path.join(staged, 'journey.ad'); + const attacker = path.join(directory, 'attacker'); + fs.mkdirSync(attacker); const writeFileSync = fs.writeFileSync; vi.spyOn(fs, 'writeFileSync').mockImplementation(((file: unknown, ...rest: unknown[]) => { const result = (writeFileSync as (...args: unknown[]) => unknown)(file, ...rest); + // The directory the file was staged in is gone and its name is somebody else's now. A filesystem + // hands back a freed inode, so the swap has to be to a directory that is really another one. fs.rmSync(staged, { recursive: true, force: true }); - fs.mkdirSync(staged); - fs.chmodSync(staged, 0o777); + fs.symlinkSync(attacker, staged); return result; }) as typeof fs.writeFileSync); expectUntrustedReplaced(() => publish(destination), staged); - expect(fs.readdirSync(staged)).toEqual([]); + expect(fs.readdirSync(attacker)).toEqual([]); }); skipOnWindows('publishes into the parent the captured identity still names', () => { @@ -408,8 +554,13 @@ function directoryOf(overrides: Partial): DirectoryAuthority return { ...OWN, ...overrides }; } -test('refuses a directory another user owns even in private mode', () => { - expect(untrustedAncestryExposure(directoryOf({ uid: 65534 }), TRUST)).toBe('foreign_owned'); +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', () => { @@ -431,11 +582,18 @@ test('accepts a root-owned directory and a directory this user owns', () => { expect(untrustedAncestryExposure(directoryOf({}), TRUST)).toBeUndefined(); }); -test('accepts a sticky shared directory for passing through, in any ownership', () => { +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 --- @@ -475,6 +633,16 @@ test('names no directory whose group is this user', () => { expect(othersCreateEntriesIn(directoryOf({ mode: 0o755 }), 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); +}); + // --- privateGroupId: the one group shape the exception admits --- const ADA = { uid: 1000, gid: 1000, name: 'ada' }; diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index daa90aaf74..ce61e0b9f3 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -198,7 +198,8 @@ export function isAtomicPublishTemporaryPath(value: unknown, destination: string * directory then has to satisfy: * * - It is owned by this user or by root. A directory another user owns is theirs to chmod, to empty, and - * to repopulate, whatever its mode says today. + * to repopulate, whatever its mode says today, and both the sticky bit and the group bits shield other + * users FROM that owner rather than the reverse. * - Its mode opens its contents to nobody else. The sticky bit is the one exception, and only for * passing THROUGH a directory: it stops anyone but an entry's owner or root from removing or replacing * that entry, which is how macOS `/tmp` and `/var` stay usable. It cannot refuse a NEW entry by name, @@ -221,7 +222,7 @@ export function isAtomicPublishTemporaryPath(value: unknown, destination: string */ export function assertPrivateScriptDestination(destination: string, parentIdentity?: string): void { if (process.platform === 'win32') return; - const parent = path.dirname(path.resolve(destination)); + const parent = spelledParent(destination); if (parentIdentity !== undefined && publishDirectoryIdentity(parent) !== parentIdentity) { throw scriptAncestryFailure(destination, parent, 'parent_replaced'); } @@ -229,8 +230,7 @@ export function assertPrivateScriptDestination(destination: string, parentIdenti assertNoPlantedLink(destination, parent, trust); const existing = deepestExistingDirectory(parent); if (existing.real === undefined) return; - const chain = directoryChain(existing.real); - for (const ancestor of chain) { + for (const ancestor of directoryChain(existing.real)) { const stats = statDirectoryChain(ancestor); if (!stats) continue; const exposure = untrustedAncestryExposure(stats, trust); @@ -245,6 +245,20 @@ export function assertPrivateScriptDestination(destination: string, parentIdenti } } +/** + * The parent of `destination` as it was spelled, made absolute but never normalized. + * + * `path.resolve` folds a `..` away, which is the one simplification this rule may not make: the kernel + * does not make it either, so `.../work/../x` lands an entry beside the target of a link named `work`. + * The chain that walk produces is what gets judged. + */ +function spelledParent(destination: string): string { + if (path.isAbsolute(destination)) return parentDirectory(destination); + // A relative destination reaches the filesystem through the working directory, the same way + // `path.resolve` names it, and the walk above is what the kernel performs from there. + return parentDirectory(path.resolve(destination)); +} + /** * Refuses a symbolic link on the spelled path that another local user could have put there, or could * replace. The link's target is judged through the resolved chain, so this only asks whether the link @@ -291,7 +305,7 @@ function deepestExistingDirectory(directory: string): Readonly<{ real: string | if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; } } - const parent = path.dirname(current); + const parent = parentDirectory(current); if (parent === current) return { real: undefined }; current = parent; } @@ -387,12 +401,27 @@ function directoryChain(directory: string): string[] { let current = directory; for (;;) { chain.push(current); - const parent = path.dirname(current); + const parent = parentDirectory(current); if (parent === current) return chain; current = parent; } } +/** + * The parent of `directory`, as the kernel sees it, or the same path when there is no parent. + * + * `path.dirname` is not usable here: it normalizes, so it folds a `..` segment away. That is the one + * simplification this rule may not make. Where `work` is a symbolic link, `.../work/../x` is a real + * path that lands beside the link's TARGET, so the rule has to see `.../work` in the chain and judge + * the link that stands there. Only a trailing separator is dropped, in linear time. + */ +function parentDirectory(directory: string): string { + const trimmed = directory.endsWith('/') ? directory.slice(0, -1) : directory; + const separator = trimmed.lastIndexOf('/'); + if (separator < 0) return trimmed; + return separator === 0 ? '/' : trimmed.slice(0, separator); +} + /** * The two ways a directory can be unsafe for a destination: someone else can change what is in it, or * someone else can create the entry the destination names. @@ -445,13 +474,18 @@ export function untrustedAncestryExposure( /** * Whether other local users can add an entry here, which is how the destination's own name, or a - * directory below it, becomes theirs. The sticky bit is deliberately not consulted: it protects entries - * that already exist and cannot refuse a new one. + * 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 both of those protect other people's entries from them, not + * their own. The sticky bit is otherwise deliberately 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) && directory.gid !== trust.privateGid; } @@ -468,6 +502,10 @@ export type LinkAuthority = Readonly<{ uid: number }>; * stops anyone but the entry's owner or root from unlinking and replacing it, so a link this user or root * owns stands, and one anybody else owns does not — it may be theirs, and without the sticky bit any of * them can swap it for one pointing wherever they like. + * + * A component the path steps back over with `..` is asked as a directory rather than as a link: there + * the caller is not publishing through it, only walking across it, and the directory it lands in is + * judged on its own. */ export function untrustedLinkExposure( link: LinkAuthority, diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 0f6ded164a..1addd832b8 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -73,7 +73,7 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow - Missing parent directories are created. The script file itself is created so that only you can read it. - Every directory on the way to the script 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 whole real path is checked, so a symbolic link to a shared directory is refused too. 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. Root-owned system links such as macOS `/tmp` and `/var` keep working. -- A directory may pass through a shared directory that carries the sticky bit (`chmod +t`), because that bit stops anyone but an entry's owner or root from replacing it. The script is never created *inside* such a directory: there, anyone could create your file's name first. A group-writable directory you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories. +- 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories. - 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. - 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. From 35fb969723b7a1a7921c4607e1b2acb891cf02b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 12:22:50 +0100 Subject: [PATCH 08/28] test(daemon): refuse a recording under a directory another user owns Two shapes the rule has to refuse at the writer, not only in the rule itself: a directory its owner made sticky with `chmod 1777`, where the sticky bit shields other users from that owner rather than the reverse, and a shared directory somebody else created first under `mkdir -p`. Both run as a second local user, because handing a directory to another uid needs privileges a test does not have. Refs #4565 Co-Authored-By: Claude Opus 5.5 --- .../session-script-writer-ancestry.test.ts | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) 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 index b8121b051a..38e579911e 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -152,6 +152,49 @@ skipOnWindows('a recording refuses a destination inside a directory another user expect(fs.existsSync(destination)).toBe(false); }); +skipOnWindows('a recording refuses a directory another user made sticky and owns', () => { + const directory = root(); + // `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 team = path.join(directory, 'team'); + fs.mkdirSync(team); + fs.chmodSync(team, 0o1777); + const destination = path.join(team, 'journey.ad'); + vi.spyOn(process, 'getuid').mockReturnValue(currentUid === 65534 ? 65535 : 65534); + + 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', () => { + const directory = root(); + // 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. + 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'); + vi.spyOn(process, 'getuid').mockReturnValue(currentUid === 65534 ? 65535 : 65534); + + 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); From 1540984376c93eb85c9f91e805dea3f4651d26ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 13:11:42 +0100 Subject: [PATCH 09/28] fix(host-kit): judge every directory a script destination walks through A destination was judged only along the real path of its deepest existing ancestor, so a plain directory under a shared one hid a link into a private destination, and one link into another link named none of the ground it crossed. Every existing prefix is now expanded link by link and each directory it steps into is judged. The remote route creates the missing parent before it asks, so both routes answer about the directory the entry is really made in. The private-group exception now reads every group record carrying that gid, because all of their members hold write. Access control lists, network filesystems and mounts are named as outside the guarantee. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 17 +- .../session-script-writer-ancestry.test.ts | 52 ++++++ .../atomic-publish-ownership.test.ts | 13 +- packages/host-kit/src/file.ts | 8 - .../src/internal/atomic-file-ancestry.test.ts | 80 +++++++- packages/host-kit/src/internal/atomic-file.ts | 176 +++++++++++++----- .../daemon-artifacts-script-download.test.ts | 93 +++++++++ .../remote/src/session-script-destination.ts | 6 +- test/wire-compat/ledger.json | 2 +- website/docs/docs/remote-proxy.md | 7 +- website/docs/docs/replay-e2e.md | 8 +- 11 files changed, 382 insertions(+), 80 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 3f92ed4e4c..18dfda51f5 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -208,12 +208,23 @@ It adds no state name, command, or flag: - 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 (#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 on its fully resolved chain. 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 chain is resolved first, so a symbolic link's target is judged under the same rule. A link is refused when another user could have placed it or could replace it: in a directory where others may add entries, only a link owned by the current user or root and held by the sticky bit is trusted. Root-owned system aliases (macOS `/tmp` to `/private/tmp`, `/var` to `/private/var`) keep working. -The sticky bit excuses a directory the chain 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. 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 fails closed when either file is unreadable. Residual limitation: a name service (LDAP or an NSS module) can add a member holding that primary GID without it appearing in `/etc/passwd`, so such a host can be refused a group-writable directory it appears to own. The fallback is a directory only the user can write. +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. +Every directory the kernel traverses is judged, not only the final chain. Each existing prefix of the spelled path is expanded link by link, and the directory holding each link target is judged with it. Resolving only the final path is not enough: a plain directory under a shared one can hold a link to a private destination, so the final chain looks private while the ground the link stands on is shared, and a link whose target is another link never names the directory stepped through in between. Both are refused. A `..` component is judged too: it leaves a directory that is on the traversed chain whatever path it ends up spelling. +A symbolic link is refused when another user could have placed it or could replace it: in a directory where others may add entries, only a link owned by the current user or root and held by the sticky bit is trusted. Root-owned system aliases (macOS `/tmp` to `/private/tmp`, `/var` to `/private/var`) keep working. +The sticky bit excuses a directory the chain 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. 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 fails closed when either file is unreadable. EVERY group record carrying that numeric gid is 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. Residual limitation, stated plainly because it cuts both ways: the two files are only this machine's own view, so a name service (LDAP or an NSS module) can hold a member of that gid, or a second group with the number, that never appears in them. Such a host can be refused a group-writable directory it genuinely owns, and it can also be accepted for one the name service has opened to someone else, because the rule cannot see that member. The fallback on such a host is a directory only the user can write, at any mode. 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 traversed directories, 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. 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. 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 index 38e579911e..5ffbde82a9 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -246,6 +246,58 @@ skipOnWindows('a recording refuses an ancestor swapped out for a writable direct 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 still saves to a group-writable private-group home', () => { privateGroupDatabase(); const directory = root(); 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 17ff81c0fb..9acb41916d 100644 --- a/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts +++ b/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts @@ -28,15 +28,10 @@ test('simple same-directory publishers use the shared atomic publish owner', () } }); -// A session script is published through the ancestry-owning entry point, not the plain one: the plain -// one writes to a destination another local user could have steered (#4565). -test('the session script publisher uses the destination-ancestry owner', () => { - const source = fs.readFileSync( - new URL('../../core/session-script-writer.ts', import.meta.url), - 'utf8', - ); - assert.match(source, /publishScriptFileSync/); -}); +// Which entry point the session script publisher dispatches through is proven by behaviour, not by its +// source text: `packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts` drives a real +// write and expects the typed ancestry refusals and the 0600 file, which only the destination-ancestry +// owner (`publishScriptFileSync`, #4565) produces. // The process lock publishes a file and reclaims a directory, which are two different // claims of ownership: only the first belongs to the publication owners above. diff --git a/packages/host-kit/src/file.ts b/packages/host-kit/src/file.ts index 31f9b39988..8779eccfb5 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -1,19 +1,11 @@ export { assertPrivateScriptDestination, isAtomicPublishTemporaryPath, - othersCreateEntriesIn, - privateGroupId, publishDirectoryIdentity, publishDurableFileSync, publishFileSync, publishScriptFileSync, - untrustedAncestryExposure, - untrustedLinkExposure, - type DirectoryAuthority, type DurableFilePublishMode, - type LinkAuthority, - type ScriptAncestryExposure, - type ScriptDestinationTrust, } from './internal/atomic-file.ts'; export { lstatIfPresent, diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index efdb75704d..fb08a57f3b 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -272,6 +272,51 @@ skipOnWindows('refuses a link standing in a private-mode directory another user expect(fs.readdirSync(mine)).toEqual([]); }); +skipOnWindows('refuses a private link standing on shared ground two levels up', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `/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( + () => assertPrivateScriptDestination(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', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `~/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( + () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), + 'world_writable', + team, + ); + expect(fs.readdirSync(chosen)).toEqual([]); +}); + skipOnWindows('judges the directories a .. in the path walks through', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); // `/shared/work/../x/journey.ad` is a path a caller can pass. Resolving it first answers @@ -658,9 +703,42 @@ test('admits the group named after the user, holding only them, as their primary expect(privateGroupId(database(PRIVATE, PRIVATE_PASSWD), ADA)).toBe(1000); }); -test('admits it with root named among its members', () => { +test('admits root named among the members, the account the whole rule trusts', () => { expect( privateGroupId(database(['ada:x:1000:root'], ['ada:x:1000:1000:', 'root:x:0:0']), ADA), + ).toBe(1000); +}); + +test('refuses a second group carrying the same gid when it lists another user', () => { + // `ada:x:1000:` looks private on its own, and the group named after the user is the only one the + // exception used to read. A directory group-writable by gid 1000 is writable by grace too, because + // `team` carries the same number. + expect( + privateGroupId( + database( + ['ada:x:1000:', 'team:x:1000:grace'], + ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0'], + ), + ADA, + ), + ).toBeUndefined(); +}); + +test('admits a second group carrying the same gid when it reaches nobody else', () => { + expect( + privateGroupId( + database(['ada:x:1000:', 'ada-alias:x:1000:'], ['ada:x:1000:1000:', 'root:x:0:0']), + ADA, + ), + ).toBe(1000); +}); + +test('refuses it once a second group sharing the gid has another user as its primary group', () => { + expect( + privateGroupId( + database(['ada:x:1000:', 'team:x:1000:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), + ADA, + ), ).toBeUndefined(); }); diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index ce61e0b9f3..8917796e6b 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -228,20 +228,101 @@ export function assertPrivateScriptDestination(destination: string, parentIdenti } const trust = readScriptTrust(); assertNoPlantedLink(destination, parent, trust); - const existing = deepestExistingDirectory(parent); - if (existing.real === undefined) return; - for (const ancestor of directoryChain(existing.real)) { - const stats = statDirectoryChain(ancestor); + const traversed = traversedDirectories(parent); + if (traversed.paths.length === 0) return; + for (const directory of traversed.paths) { + const stats = statDirectoryChain(directory); if (!stats) continue; const exposure = untrustedAncestryExposure(stats, trust); - if (exposure) throw scriptAncestryFailure(destination, ancestor, exposure); + if (exposure) throw scriptAncestryFailure(destination, directory, exposure); } // The script entry is created inside the deepest directory that exists, or below it through // directories that do not exist yet. Where other local users can add entries, one of them can add // this entry first and the recording is theirs, so the creation has to be refused. - const deepest = statDirectoryChain(existing.real); + const deepest = statDirectoryChain(traversed.deepest); if (deepest && othersCreateEntriesIn(deepest, trust)) { - throw scriptAncestryFailure(destination, existing.real, 'shared_parent'); + throw scriptAncestryFailure(destination, traversed.deepest, 'shared_parent'); + } +} + +/** Link hops one destination walk expands before it stops, in step with the kernel's own limit. */ +const MAX_SYMLINK_HOPS = 40; + +/** + * Every directory the kernel traverses to reach `parent`, judged nearest-first, without duplicates, and + * the deepest one that exists. + * + * Resolving only the deepest existing ancestor is not enough, and neither is one `realpath` of a path + * that runs through links: + * + * - A component that is a plain directory is traversed as it stands, so a link inside it can lead + * anywhere, and the directories above that plain component are reached by the publish even though the + * final chain looks entirely private: `/shared` at 0777 with `/shared/mine` at 0700 and + * `mine/rec` a link to a private directory names only trusted directories at its destination, while + * another local user owns the ground `mine` and `rec` stand on and can rename `mine` aside. So EVERY + * existing prefix of the spelled path is resolved, and the chain under each resolution is judged. + * - Where one link leads into another, `realpathSync` answers with the LAST target and names none of the + * directories stepped through on the way: `~/rec -> /srv/team/relay -> ~/chosen` reaches a private + * directory, and the team ground `relay` stands on never appears in the answer, though any teammate + * can swap that link for a target of their own. So a link hop also judges the directory holding its + * target, and the walk continues into the target. + */ +function traversedDirectories( + parent: string, +): Readonly<{ paths: readonly string[]; deepest: string }> { + const seen = new Set(); + const paths: string[] = []; + let deepest: string | undefined; + for (const prefix of directoryChain(parent)) { + let current = prefix; + // Each hop replaces one link with its target, so a link cycle cannot run the walk forever. The + // operating system applies a limit of the same order and refuses the publish when it is exceeded. + for (let hop = 0; hop <= MAX_SYMLINK_HOPS; hop += 1) { + const stats = lstatIfPresentSync(current); + if (stats === undefined) break; + if (!stats.isSymbolicLink()) { + const real = resolvedDirectory(current); + if (real === undefined) break; + deepest ??= real; + for (const ancestor of directoryChain(real)) { + if (seen.has(ancestor)) continue; + seen.add(ancestor); + paths.push(ancestor); + } + break; + } + const target = linkTarget(current); + // The kernel steps INTO the directory the target names, so that directory and everything above it + // are traversed whatever this link eventually resolves to. + const home = resolvedDirectory(parentDirectory(target)); + if (home !== undefined) { + for (const ancestor of directoryChain(home)) { + if (seen.has(ancestor)) continue; + seen.add(ancestor); + paths.push(ancestor); + } + } + current = target; + } + } + return { paths, deepest: deepest ?? parent }; +} + +/** Where a symbolic link points, made absolute the way the kernel reads it. */ +function linkTarget(link: string): string { + const target = fs.readlinkSync(link); + return path.isAbsolute(target) ? target : `${parentDirectory(link)}/${target}`; +} + +/** The directory `path` names once every link in it is expanded, or `undefined` when it is absent. */ +function resolvedDirectory(pathname: string): string | undefined { + if (lstatIfPresentSync(pathname) === undefined) return undefined; + try { + const real = fs.realpathSync(pathname); + return statDirectoryChain(real) ? real : undefined; + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; + throw error; } } @@ -278,7 +359,7 @@ function assertNoPlantedLink( for (const ancestor of directoryChain(parent)) { const link = lstatIfPresentSync(ancestor); if (!link?.isSymbolicLink()) continue; - const home = lstatIfPresentSync(path.dirname(ancestor)); + const home = lstatIfPresentSync(parentDirectory(ancestor)); if (!home) continue; const exposure = untrustedLinkExposure( { uid: link.uid }, @@ -289,28 +370,6 @@ function assertNoPlantedLink( } } -/** - * The real path of the deepest directory `directory` names or leads to, or `undefined` when nothing of it - * exists to judge. A component that exists but resolves to nothing (a dangling link) is stepped over like - * one that is absent, so the walk never stops with nothing checked. - */ -function deepestExistingDirectory(directory: string): Readonly<{ real: string | undefined }> { - let current = directory; - for (;;) { - if (lstatIfPresentSync(current) !== undefined) { - try { - const real = fs.realpathSync(current); - if (statDirectoryChain(real)) return { real }; - } catch (error) { - if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; - } - } - const parent = parentDirectory(current); - if (parent === current) return { real: undefined }; - current = parent; - } -} - /** * One directory's identity on its filesystem, for a caller that must publish into the same one it * created or checked. `undefined` when the directory is absent or is not a directory. @@ -338,18 +397,22 @@ type HostGroupDatabase = Readonly<{ * * - Both database files must have been READ. An unreadable file is not an empty one, and an empty * member list proves nothing. - * - The group must be the one this process holds as its PRIMARY group, which `getgid` answers from the - * kernel rather than from a file, and it must carry this user's name. - * - The group's own member list may name nobody but this user. macOS lists only part of `staff` in - * `/etc/group` while every local user holds it, so a name that is not this user's ends the claim - * rather than being looked up and forgiven. - * - No other record in the passwd file may hold this group as its primary group, and the caller's own - * record must exist there with this uid and this gid. + * - The gid must be the one this process holds as its PRIMARY group, which `getgid` answers from the + * kernel rather than from a file, and at least one record carrying that gid must bear this user's name. + * - EVERY record carrying that gid is read, because a directory group-writable by gid 1000 is writable + * by the members of each group holding the number, however they are named: `ada:x:1000:` beside + * `team:x:1000:grace` reaches grace. Any of them naming a member who is neither this user nor root + * ends the claim, without lookup or forgiveness — macOS lists only part of `staff` in `/etc/group` + * while every local user holds it. + * - No other passwd record may hold this gid as its primary group, and the caller's own record must + * exist there with this uid and this gid. * - * What this cannot establish: a name service (LDAP, NSS modules) can add a user whose primary group is - * this gid without that user ever appearing in `/etc/passwd`. A host configured that way can still be - * refused a group-writable destination it appears to own, which is the residual limitation the - * documentation names; the caller's fallback is a directory only they can write. + * What this cannot establish, stated plainly because it cuts BOTH ways: the two files are only this + * machine's own view. A name service (LDAP, an NSS module) can hold a member of this gid, or a second + * group with the number, that never appears in `/etc/passwd` or `/etc/group`. Such a host can be + * refused a group-writable directory it genuinely owns, and it can also be ACCEPTED for one the name + * service has opened to someone else — this rule cannot see that member and so cannot refuse it. The + * caller's answer on a name-service host is a directory only they can write, at any mode. */ export function privateGroupId( database: HostGroupDatabase, @@ -358,24 +421,37 @@ export function privateGroupId( const { uid, gid, name } = current; if (uid === undefined || gid === undefined || name === undefined) return undefined; if (!database.groups || !database.passwd) return undefined; - const record = database.groups.find((line) => line.split(':')[0] === name); - if (!record) return undefined; - const [, , rawGid, rawMembers = ''] = record.split(':'); - const privateGid = Number(rawGid); - if (!Number.isInteger(privateGid) || privateGid !== gid) return undefined; - const members = rawMembers.split(',').filter((member) => member.length > 0); - if (members.some((member) => member !== name)) return undefined; const own = database.passwd.find((line) => line.split(':')[0] === name); if (!own) return undefined; const [, , ownUid, ownGid] = own.split(':'); if (Number(ownUid) !== uid || Number(ownGid) !== gid) return undefined; + // EVERY record carrying this gid decides together: a directory group-writable by gid 1000 is writable + // by the members of each of them, however they are named. A group named after the user buys the + // exception only while no other record sharing the number reaches another user. + let namedForUser = false; + for (const line of database.groups) { + const [groupName, , rawGid, rawMembers = ''] = line.split(':'); + const recordGid = Number(rawGid); + if (rawGid === '' || !Number.isInteger(recordGid) || recordGid !== gid) continue; + if (groupName === name) namedForUser = true; + const members = rawMembers.split(',').filter((member) => member.length > 0); + if (members.some((member) => !memberIsTrusted(member, database, name))) return undefined; + } + if (!namedForUser) return undefined; const sharesPrimary = database.passwd.some((line) => { - const [other, , , otherGid] = line.split(':'); - return other !== name && Number(otherGid) === gid; + const [other, , rawOtherUid, rawOtherGid] = line.split(':'); + return other !== name && Number(rawOtherGid) === gid && Number(rawOtherUid) !== 0; }); return sharesPrimary ? undefined : gid; } +/** Whether a member of a candidate private group is the user or root, the two accounts the rule trusts. */ +function memberIsTrusted(member: string, database: HostGroupDatabase, name: string): boolean { + if (member === name) return true; + const record = database.passwd?.find((line) => line.split(':')[0] === member); + return record !== undefined && Number(record.split(':')[2]) === 0; +} + /** This process's identity and the private group its host databases establish, if any. */ function readScriptTrust(): ScriptDestinationTrust { return { 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 aafd6276bb..bdf3aea2df 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts @@ -465,6 +465,99 @@ test.skipIf(process.platform === 'win32' || process.getuid?.() === 0).each([ }, ); +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 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', diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 326c74b59c..fc9dac0070 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -199,9 +199,9 @@ async function publishScriptVersion( const pending = { named: false }; let staging: string | undefined; try { - // Asked before anything is created, so a destination another local user can steer leaves no - // directory behind (#4565). - assertPrivateScriptDestination(record.destination); + // The missing parent is created first, so this route judges the chain at the same point the local + // writer does: the rule needs the directory the entry is really created in, which does not exist + // until this line has run (#4565). await fs.promises.mkdir(path.dirname(record.destination), { recursive: true }); const allocated = await withRecordLock(file, async () => allocateStaging(file, record.destination), diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 02301f93b0..d70f639661 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -215,7 +215,7 @@ "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:3406b96e254e85cd3e3f23b8b644f40d8d7268b2066696ff21516dabfa8ca14c", + "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:cc3b263e1a19cb76256217395f81f54e4fffa6a5755693e1efef1e5e931d50f6", "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" diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 009f1b7e97..7eabfc7c00 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -108,8 +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 on the way to that path must be one that no other local user can change; see -[Record a replay script](replay-e2e.md#record-a-replay-script). +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. diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 1addd832b8..ad640be4d5 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -70,10 +70,12 @@ 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. The script file itself is created so that only you can read it. -- Every directory on the way to the script 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. +- Missing parent directories are created. 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. +- Directories between the path you typed and where it ends are checked too, not only the final result. A plain directory that is open to others can hold a link into a private directory, so the destination looks private while the ground the link stands on is shared, and a link that points at another link passes through a directory the final path never names. Both are refused. A `..` segment is checked too, including the directory it steps back out of. - The whole real path is checked, so a symbolic link to a shared directory is refused too. 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. 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories. +- 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories. Every group carrying that group number is considered, so a second group with the same number that lists somebody else closes this exception. +- 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. - 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. From 5901614af0a21c860c022eb7e5ee9c2d0bbe569b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 14:10:29 +0100 Subject: [PATCH 10/28] fix(host-kit): walk a script destination the way the kernel resolves it The destination rule resolved each existing prefix with `realpathSync` and judged the chains it got back, so a directory the resolution stepped through could leave the answer: a link in the middle of a target hid its directory, a followed link's owner was never asked, and a `..` was applied to the spelling rather than to the link's target. `assertNoPlantedLink` covered only the links in the spelled path, so an expanded hop skipped the check. One walker now replaces `traversedDirectories`, `assertNoPlantedLink`, `resolvedDirectory`, `linkTarget`, `parentDirectory` and every `realpath` call. It starts at `/`, or at the process's resolved working directory for a relative spelling, and resolves the spelled components one at a time: `.` is skipped, `..` moves to the parent of the directory physically stood in, any other name is lstat'ed there. A directory is judged and entered; a link is judged itself against the directory that holds it, and its target's components go on the front of the queue. Hop count is refused as `link_loop_exceeded` below the kernel's own limit, so a walk that ran out of hops is a refusal, and a step that cannot be travelled through is refused as `not_a_directory`. The private-group exception now fails closed: it is admitted only when `/etc/nsswitch.conf` exists, is readable, and lists `files` as the only source for `passwd` and `group`, because a name service can hold a member the two files never show. `systemd` is refused for the same reason. The account name is read from the passwd database the rule judges rather than from a second host lookup, and the script file mode is fixed at `0600`. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 13 +- .../session-script-writer-ancestry.test.ts | 119 ++++- .../__tests__/session-script-writer.test.ts | 5 +- .../daemon/src/core/session-script-writer.ts | 43 +- .../atomic-publish-ownership.test.ts | 5 - .../__tests__/session-close-script.test.ts | 6 +- .../src/internal/atomic-file-ancestry.test.ts | 354 ++++++++----- .../atomic-file-private-group.test.ts | 134 +++++ packages/host-kit/src/internal/atomic-file.ts | 499 +++++++++++------- .../daemon-artifacts-script-download.test.ts | 104 ++++ .../test-kit/src/host-ownership.fixtures.ts | 27 + packages/test-kit/src/index.ts | 1 + website/docs/docs/replay-e2e.md | 6 +- 13 files changed, 937 insertions(+), 379 deletions(-) create mode 100644 packages/host-kit/src/internal/atomic-file-private-group.test.ts create mode 100644 packages/test-kit/src/host-ownership.fixtures.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 18dfda51f5..f990c79b41 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -209,9 +209,14 @@ It adds no state name, command, or flag: 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. -Every directory the kernel traverses is judged, not only the final chain. Each existing prefix of the spelled path is expanded link by link, and the directory holding each link target is judged with it. Resolving only the final path is not enough: a plain directory under a shared one can hold a link to a private destination, so the final chain looks private while the ground the link stands on is shared, and a link whose target is another link never names the directory stepped through in between. Both are refused. A `..` component is judged too: it leaves a directory that is on the traversed chain whatever path it ends up spelling. -A symbolic link is refused when another user could have placed it or could replace it: in a directory where others may add entries, only a link owned by the current user or root and held by the sticky bit is trusted. Root-owned system aliases (macOS `/tmp` to `/private/tmp`, `/var` to `/private/var`) keep working. -The sticky bit excuses a directory the chain 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. 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 fails closed when either file is unreadable. EVERY group record carrying that numeric gid is 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. Residual limitation, stated plainly because it cuts both ways: the two files are only this machine's own view, so a name service (LDAP or an NSS module) can hold a member of that gid, or a second group with the number, that never appears in them. Such a host can be refused a group-writable directory it genuinely owns, and it can also be accepted for one the name service has opened to someone else, because the rule cannot see that member. The fallback on such a host is a directory only the user can write, at any mode. +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. @@ -224,7 +229,7 @@ The rule judges ownership bits, mode bits and link shape. Three things sit outsi - **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 traversed directories, 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. +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. 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. 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 index 5ffbde82a9..19578d277a 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -1,9 +1,12 @@ import { afterEach, expect, test, vi } from 'vitest'; import fs from 'node:fs'; -// oxlint-disable-next-line no-restricted-imports -- the private-group fixture is named after os.userInfo()'s user, not a scratch path -import os from 'node:os'; 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 { SessionScriptWriter } from '../session-script-writer.ts'; import { makeAuthoringSession } from '../../__tests__/support/session-factories.ts'; @@ -11,7 +14,8 @@ const hostCwd = createLiveTestHostEnvironment().cwd; const skipOnWindows = process.platform === 'win32' ? test.skip : test; const realReadFileSync = fs.readFileSync; -const currentUser = os.userInfo().username; +/** The account the fixtures name for this process, the same one the rule reads back out of passwd. */ +const currentUser = process.env.USER ?? ''; /** This process's ids. Windows has neither, and every test that uses them is skipped there. */ const currentUid = process.getuid?.() ?? -1; @@ -30,6 +34,8 @@ function serveGroupDatabase(groups: readonly string[], passwd: readonly string[] vi.spyOn(fs, 'readFileSync').mockImplementation(((file: unknown, options?: unknown) => { if (file === '/etc/group') return `${groups.join('\n')}\n`; if (file === '/etc/passwd') return `${passwd.join('\n')}\n`; + // The private-group exception is admitted only where the host's own databases are the whole story. + if (file === '/etc/nsswitch.conf') return 'passwd: files\ngroup: files\n'; return realReadFileSync(file as never, options as never) as never; }) as typeof fs.readFileSync); } @@ -144,11 +150,7 @@ skipOnWindows('a recording refuses a destination inside a directory another user const details = refusal(writerFor(directory).write(recordingTo(destination))); - expect(details).toMatchObject({ - reason: 'script_ancestor_untrusted', - exposure: 'foreign_owned', - ancestor: foreign, - }); + expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'foreign_owned' }); expect(fs.existsSync(destination)).toBe(false); }); @@ -164,11 +166,7 @@ skipOnWindows('a recording refuses a directory another user made sticky and owns const details = refusal(writerFor(directory).write(recordingTo(destination))); - expect(details).toMatchObject({ - reason: 'script_ancestor_untrusted', - exposure: 'foreign_owned', - ancestor: team, - }); + expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'foreign_owned' }); expect(fs.readdirSync(team)).toEqual([]); }); @@ -187,11 +185,7 @@ skipOnWindows('a recording refuses a shared directory another user claimed first const details = refusal(writerFor(directory).write(recordingTo(destination))); - expect(details).toMatchObject({ - reason: 'script_ancestor_untrusted', - exposure: 'foreign_owned', - ancestor: recordings, - }); + expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'foreign_owned' }); expect(fs.readdirSync(recordings)).toEqual([]); }); @@ -205,7 +199,11 @@ skipOnWindows('a recording refuses an ancestor swapped out for a symbolic link', const details = refusal(writerFor(directory).write(recordingTo(destination))); - expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'planted_link' }); + // 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([]); }); @@ -298,6 +296,87 @@ skipOnWindows('a recording refuses a chain that leaves a shared directory throug expect(fs.readdirSync(chosen)).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 still saves to a group-writable private-group home', () => { privateGroupDatabase(); const directory = root(); 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..7d0ae670d3 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer.test.ts @@ -696,8 +696,11 @@ 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); + // A directory this user owns but cannot write: the ancestry rule has nothing to refuse there, so the + // failure the caller sees is the filesystem's own, not an ancestry verdict. const blocker = path.join(root, 'blocker'); - fs.writeFileSync(blocker, ''); + fs.mkdirSync(blocker); + fs.chmodSync(blocker, 0o500); const outPath = path.join(blocker, 'flow.ad'); const session = makeAuthoringSession('default', { scriptPublication: authoringPublication('armed', { path: outPath }), diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index 9b60e608aa..0d26cfed63 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -232,21 +232,40 @@ 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, ); } +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 @@ -256,14 +275,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.', + }); } /** 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 9acb41916d..84a5d57d70 100644 --- a/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts +++ b/packages/daemon/src/server/__tests__/atomic-publish-ownership.test.ts @@ -28,11 +28,6 @@ test('simple same-directory publishers use the shared atomic publish owner', () } }); -// Which entry point the session script publisher dispatches through is proven by behaviour, not by its -// source text: `packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts` drives a real -// write and expects the typed ancestry refusals and the 0600 file, which only the destination-ancestry -// owner (`publishScriptFileSync`, #4565) produces. - // The process lock publishes a file and reclaims a directory, which are two different // claims of ownership: only the first belongs to the publication owners above. test('the process lock publishes its owner record without publishing files by hand', () => { 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..42466b9f80 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 @@ -195,9 +195,11 @@ 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. + // A directory this user owns but cannot write: publishing into it fails with EACCES, and the ancestry + // rule has nothing to refuse there, so the caller sees the filesystem's own failure. const blocker = path.join(root, 'blocker'); - fs.writeFileSync(blocker, ''); + fs.mkdirSync(blocker); + fs.chmodSync(blocker, 0o500); const targetPath = path.join(blocker, 'flow.ad'); const { req, ref, sessionStore } = setup( 'fs-failure', diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index fb08a57f3b..54314a81ac 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -1,18 +1,16 @@ import { afterEach, expect, test, vi } from 'vitest'; import fs from 'node:fs'; -// oxlint-disable-next-line no-restricted-imports -- the fixture's private group is named after os.userInfo()'s user, not a scratch path -import os from 'node:os'; import path from 'node:path'; import { AppError } from '@agent-device/kernel/errors'; import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; import { assertPrivateScriptDestination, othersCreateEntriesIn, - privateGroupId, publishDirectoryIdentity, publishScriptFileSync, untrustedAncestryExposure, untrustedLinkExposure, + MAX_SCRIPT_PATH_LINK_HOPS, type DirectoryAuthority, } from './atomic-file.ts'; @@ -22,10 +20,16 @@ const skipOnWindows = process.platform === 'win32' ? test.skip : test; type Database = Readonly<{ groups: readonly string[] | undefined; passwd: readonly string[] | undefined; + /** `undefined` means "only files"; an empty array means "the file cannot be read". */ + nsswitch?: readonly string[] | undefined; }>; const realReadFileSync = fs.readFileSync; -const currentUser = os.userInfo().username; +/** + * The account the fixture's databases name for this process. `readCurrentUser()` reads it from + * `passwdFile` below, so the fixture and the rule agree without a second host lookup. + */ +const currentUser = process.env.USER ?? ''; /** The unmocked `stat` calls, so a second fixture here never wraps the first one's mock. */ const realLstatSync = fs.lstatSync.bind(fs); const realStatSync = fs.statSync.bind(fs); @@ -52,15 +56,24 @@ function serveGroupDatabase(database: Database): void { if (!database.passwd) throw new Error('simulated unreadable passwd file'); return `${database.passwd.join('\n')}\n`; } + if (file === '/etc/nsswitch.conf') return nsswitchContents(database.nsswitch); return realReadFileSync(file as never, options as never) as never; }) as typeof fs.readFileSync); } +/** The name-service lines of the fixture host: `files` only, unless the test asks for more. */ +function nsswitchContents(sources: readonly string[] | undefined): string { + if (sources === undefined) return 'passwd: files\ngroup: files\n'; + if (sources.length === 0) throw new Error('simulated unreadable nsswitch.conf'); + return `${sources.join('\n')}\n`; +} + /** This host's user with a group of their own, and a team group that holds someone else. */ function hostDatabase(privateGid: number, sharedGid: number): Database { return { groups: ['root:x:0:root', `${currentUser}:x:${privateGid}:`, `team:x:${sharedGid}:ada`], passwd: [`root:x:0:0`, `${currentUser}:x:${currentUid}:${privateGid}:`], + nsswitch: undefined, }; } @@ -104,15 +117,6 @@ function directoryWith(directory: string, mode: number, gid = currentGid): strin return directory; } -/** - * Runs the rule as a different local user, so the ownership checks are exercised against real - * directories owned by this test's actual user. Nothing else about the process moves: the modes stay - * what they are on disk. - */ -function asAnotherLocalUser(): void { - vi.spyOn(process, 'getuid').mockReturnValue(currentUid === 65534 ? 65535 : 65534); -} - function publish(destination: string, parentIdentity?: string): void { publishScriptFileSync({ destination, @@ -266,8 +270,8 @@ skipOnWindows('refuses a link standing in a private-mode directory another user expectUntrusted( () => assertPrivateScriptDestination(path.join(teammate, 'link', 'journey.ad')), - 'planted_link', - path.join(teammate, 'link'), + 'foreign_owned', + teammate, ); expect(fs.readdirSync(mine)).toEqual([]); }); @@ -317,25 +321,196 @@ skipOnWindows('refuses a chain that leaves a shared directory through an interme expect(fs.readdirSync(chosen)).toEqual([]); }); -skipOnWindows('judges the directories a .. in the path walks through', () => { +skipOnWindows('judges the directory a .. steps back into', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); - // `/shared/work/../x/journey.ad` is a path a caller can pass. Resolving it first answers - // `/shared/x/journey.ad`, which is a DIFFERENT directory from the one that receives the file: - // the kernel walks `work` into the link's target and steps back from THERE, so the entry is created - // beside that target. The rule has to judge the components it walked, so the link is refused here. + // `/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( + () => assertPrivateScriptDestination(`${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', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `/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 published = directoryWith(path.join(directory, 'published'), 0o700); - const attacker = path.join(published, 'attacker'); - fs.mkdirSync(attacker); - fs.symlinkSync(attacker, path.join(shared, 'work')); + 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( + () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), + 'world_writable', + shared, + ); + expect(fs.readdirSync(chosen)).toEqual([]); +}); + +skipOnWindows('refuses the spelled spelling of a link the walk also follows', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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( + () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), + 'world_writable', + shared, + ); + expectUntrusted( + () => assertPrivateScriptDestination(path.join(shared, 'journey.ad')), + 'world_writable', + shared, + ); +}); + +skipOnWindows('applies .. to the directory the walk is in, not to the spelling', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `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( - () => assertPrivateScriptDestination(`${shared}/work/../x/journey.ad`), + () => assertPrivateScriptDestination(`${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', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `~/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( + () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), 'planted_link', - path.join(shared, 'work'), + relay, + ); + expect(fs.readdirSync(chosen)).toEqual([]); +}); + +skipOnWindows('follows a link whatever mode it carries, judging the directory it lands in', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const directory = root(); + const work = directoryWith(path.join(directory, 'work'), 0o700); + const loop = path.join(work, 'loop'); + fs.symlinkSync(loop, loop); + + expectUntrusted( + () => assertPrivateScriptDestination(path.join(loop, 'journey.ad')), + 'link_loop_exceeded', + loop, + ); + expect(fs.readdirSync(work)).toEqual(['loop']); +}); + +skipOnWindows('follows exactly as many link hops as the walk allows, and refuses one more', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + const directory = root(); + const work = directoryWith(path.join(directory, 'work'), 0o700); + const real = directoryWith(path.join(directory, 'real'), 0o700); + // `link0 -> link1 -> ... -> `, so 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(MAX_SCRIPT_PATH_LINK_HOPS), 'journey.ad')); + expect(fs.existsSync(path.join(real, 'journey.ad'))).toBe(true); + fs.rmSync(path.join(real, 'journey.ad'), { force: true }); + + expectUntrusted( + () => + assertPrivateScriptDestination(path.join(chain(MAX_SCRIPT_PATH_LINK_HOPS + 1), 'journey.ad')), + 'link_loop_exceeded', + path.join(work, `link${MAX_SCRIPT_PATH_LINK_HOPS}`), + ); + expect(fs.readdirSync(real)).toEqual([]); +}); + +skipOnWindows('refuses a path component that cannot carry a publish', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + 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( + () => assertPrivateScriptDestination(path.join(blocker, 'journey.ad')), + 'not_a_directory', + blocker, ); - expect(fs.readdirSync(attacker)).toEqual([]); }); skipOnWindows('refuses a directory its owner opened up while the file was staged', () => { @@ -404,8 +579,10 @@ skipOnWindows('follows a symbolic link inside a directory only this user can wri expect(fs.existsSync(path.join(real, 'journey.ad'))).toBe(true); }); -skipOnWindows('refuses a symbolic link planted in a directory others can add entries to', () => { +skipOnWindows('refuses a link planted in a directory others can add entries to', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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'); @@ -414,8 +591,8 @@ skipOnWindows('refuses a symbolic link planted in a directory others can add ent expectUntrusted( () => assertPrivateScriptDestination(path.join(shared, 'work', 'journey.ad')), - 'planted_link', - path.join(shared, 'work'), + 'world_writable', + shared, ); expect(fs.readdirSync(attacker)).toEqual([]); }); @@ -462,17 +639,23 @@ skipOnWindows( 'refuses a symbolic link another local user owns in a sticky shared directory', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); - const shared = directoryWith(path.join(root(), 'shared'), 0o1777); - const attacker = path.join(root(), 'attacker'); + // 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); - fs.symlinkSync(attacker, path.join(shared, 'work')); - asAnotherLocalUser(); + const link = path.join(shared, 'work'); + fs.symlinkSync(attacker, link); + serveOwnership({ [shared]: 0, [link]: FOREIGN_UID }); expectUntrusted( () => assertPrivateScriptDestination(path.join(shared, 'work', 'journey.ad')), 'planted_link', - path.join(shared, 'work'), + link, ); + expect(fs.readdirSync(attacker)).toEqual([]); }, ); @@ -687,104 +870,3 @@ 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); }); - -// --- privateGroupId: the one group shape the exception admits --- - -const ADA = { uid: 1000, gid: 1000, name: 'ada' }; - -function database(groups: readonly string[] | undefined, passwd: readonly string[] | undefined) { - return { groups, passwd }; -} - -const PRIVATE = ['ada:x:1000:', 'staff:x:20:root']; -const PRIVATE_PASSWD = ['ada:x:1000:1000:', 'root:x:0:0']; - -test('admits the group named after the user, holding only them, as their primary group', () => { - expect(privateGroupId(database(PRIVATE, PRIVATE_PASSWD), ADA)).toBe(1000); -}); - -test('admits root named among the members, the account the whole rule trusts', () => { - expect( - privateGroupId(database(['ada:x:1000:root'], ['ada:x:1000:1000:', 'root:x:0:0']), ADA), - ).toBe(1000); -}); - -test('refuses a second group carrying the same gid when it lists another user', () => { - // `ada:x:1000:` looks private on its own, and the group named after the user is the only one the - // exception used to read. A directory group-writable by gid 1000 is writable by grace too, because - // `team` carries the same number. - expect( - privateGroupId( - database( - ['ada:x:1000:', 'team:x:1000:grace'], - ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0'], - ), - ADA, - ), - ).toBeUndefined(); -}); - -test('admits a second group carrying the same gid when it reaches nobody else', () => { - expect( - privateGroupId( - database(['ada:x:1000:', 'ada-alias:x:1000:'], ['ada:x:1000:1000:', 'root:x:0:0']), - ADA, - ), - ).toBe(1000); -}); - -test('refuses it once a second group sharing the gid has another user as its primary group', () => { - expect( - privateGroupId( - database(['ada:x:1000:', 'team:x:1000:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), - ADA, - ), - ).toBeUndefined(); -}); - -test('refuses it once another user is a member', () => { - expect( - privateGroupId( - database(['ada:x:1000:grace'], ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0']), - ADA, - ), - ).toBeUndefined(); -}); - -test('refuses it once another user has it as their primary group', () => { - expect( - privateGroupId(database(['ada:x:1000:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), ADA), - ).toBeUndefined(); -}); - -test('refuses a group that is not the primary group of the user, however few members it lists', () => { - expect(privateGroupId(database(['ada:x:4321:'], ['ada:x:1000:1000:']), ADA)).toBeUndefined(); -}); - -test('refuses a group that does not carry the name of the user', () => { - expect(privateGroupId(database(['team:x:1000:'], ['ada:x:1000:1000:']), ADA)).toBeUndefined(); -}); - -test('refuses it when the group file cannot be read', () => { - expect(privateGroupId(database(undefined, PRIVATE_PASSWD), ADA)).toBeUndefined(); -}); - -test('refuses it when the passwd file cannot be read', () => { - expect(privateGroupId(database(PRIVATE, undefined), ADA)).toBeUndefined(); -}); - -test('refuses it when the user has no passwd record', () => { - expect(privateGroupId(database(PRIVATE, ['root:x:0:0']), ADA)).toBeUndefined(); -}); - -test('refuses it when the passwd record names another uid or gid', () => { - const other = { uid: 1002, gid: 1000, name: 'ada' }; - expect(privateGroupId(database(PRIVATE, PRIVATE_PASSWD), other)).toBeUndefined(); -}); - -test('gives a caller without a full identity no private group', () => { - const groups = database(PRIVATE, PRIVATE_PASSWD); - expect(privateGroupId(groups, { uid: undefined, gid: 1000, name: 'ada' })).toBeUndefined(); - expect(privateGroupId(groups, { uid: 1000, gid: undefined, name: 'ada' })).toBeUndefined(); - expect(privateGroupId(groups, { uid: 1000, gid: 1000, name: undefined })).toBeUndefined(); -}); diff --git a/packages/host-kit/src/internal/atomic-file-private-group.test.ts b/packages/host-kit/src/internal/atomic-file-private-group.test.ts new file mode 100644 index 0000000000..440c702e31 --- /dev/null +++ b/packages/host-kit/src/internal/atomic-file-private-group.test.ts @@ -0,0 +1,134 @@ +// privateGroupId: the one group shape the destination-ancestry rule admits, and what a name service +// does to that claim. Both are pure decisions over host account records, so they are judged here rather +// than through a filesystem. + +import { expect, test } from 'vitest'; +import { nameServiceListsOnlyFiles, privateGroupId } from './atomic-file.ts'; + +const ADA = { uid: 1000, gid: 1000, name: 'ada' }; + +const FILES = ['passwd: files', 'group: files']; + +function database(groups: readonly string[] | undefined, passwd: readonly string[] | undefined) { + return { groups, passwd, nsswitch: FILES }; +} + +const PRIVATE = ['ada:x:1000:', 'staff:x:20:root']; +const PRIVATE_PASSWD = ['ada:x:1000:1000:', 'root:x:0:0']; + +test('admits the group named after the user, holding only them, as their primary group', () => { + expect(privateGroupId(database(PRIVATE, PRIVATE_PASSWD), ADA)).toBe(1000); +}); + +test('admits root named among the members, the account the whole rule trusts', () => { + expect( + privateGroupId(database(['ada:x:1000:root'], ['ada:x:1000:1000:', 'root:x:0:0']), ADA), + ).toBe(1000); +}); + +test('refuses a second group carrying the same gid when it lists another user', () => { + // `ada:x:1000:` looks private on its own, and the group named after the user is the only one the + // exception used to read. A directory group-writable by gid 1000 is writable by grace too, because + // `team` carries the same number. + expect( + privateGroupId( + database( + ['ada:x:1000:', 'team:x:1000:grace'], + ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0'], + ), + ADA, + ), + ).toBeUndefined(); +}); + +test('admits a second group carrying the same gid when it reaches nobody else', () => { + expect( + privateGroupId( + database(['ada:x:1000:', 'ada-alias:x:1000:'], ['ada:x:1000:1000:', 'root:x:0:0']), + ADA, + ), + ).toBe(1000); +}); + +test('refuses it once a second group sharing the gid has another user as its primary group', () => { + expect( + privateGroupId( + database(['ada:x:1000:', 'team:x:1000:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), + ADA, + ), + ).toBeUndefined(); +}); + +test('refuses it once another user is a member', () => { + expect( + privateGroupId( + database(['ada:x:1000:grace'], ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0']), + ADA, + ), + ).toBeUndefined(); +}); + +test('refuses it once another user has it as their primary group', () => { + expect( + privateGroupId(database(['ada:x:1000:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), ADA), + ).toBeUndefined(); +}); + +test('refuses a group that is not the primary group of the user, however few members it lists', () => { + expect(privateGroupId(database(['ada:x:4321:'], ['ada:x:1000:1000:']), ADA)).toBeUndefined(); +}); + +test('refuses a group that does not carry the name of the user', () => { + expect(privateGroupId(database(['team:x:1000:'], ['ada:x:1000:1000:']), ADA)).toBeUndefined(); +}); + +test('refuses it when the group file cannot be read', () => { + expect(privateGroupId(database(undefined, PRIVATE_PASSWD), ADA)).toBeUndefined(); +}); + +test('refuses it when the passwd file cannot be read', () => { + expect(privateGroupId(database(PRIVATE, undefined), ADA)).toBeUndefined(); +}); + +test('refuses it when the user has no passwd record', () => { + expect(privateGroupId(database(PRIVATE, ['root:x:0:0']), ADA)).toBeUndefined(); +}); + +test('refuses it when the passwd record names another uid or gid', () => { + const other = { uid: 1002, gid: 1000, name: 'ada' }; + expect(privateGroupId(database(PRIVATE, PRIVATE_PASSWD), other)).toBeUndefined(); +}); + +test('refuses it when /etc/nsswitch.conf cannot be read', () => { + expect( + privateGroupId({ groups: PRIVATE, passwd: PRIVATE_PASSWD, nsswitch: undefined }, ADA), + ).toBeUndefined(); +}); + +test('refuses it when nsswitch.conf adds a name service to either database', () => { + const withNameService = (databaseLines: string[]) => + privateGroupId({ groups: PRIVATE, passwd: PRIVATE_PASSWD, nsswitch: databaseLines }, ADA); + + expect(withNameService(['passwd: files ldap', 'group: files'])).toBeUndefined(); + expect(withNameService(['passwd: files', 'group: files sss'])).toBeUndefined(); + // `systemd` is the default on some distributions and is still refused: userdbd answers membership from + // records these two files never show. + expect(withNameService(['passwd: files systemd', 'group: files systemd'])).toBeUndefined(); + expect(withNameService(['passwd: files', 'group:'])).toBeUndefined(); + expect(withNameService(['# no database lines here'])).toBeUndefined(); +}); + +test('admits a name service line that names only files, actions and comments aside', () => { + expect( + nameServiceListsOnlyFiles(['passwd: [NOTFOUND=return] files # local only', 'group: files']), + ).toBe(true); + expect(nameServiceListsOnlyFiles(['passwd: files', 'group: files db'])).toBe(false); + expect(nameServiceListsOnlyFiles(undefined)).toBe(false); +}); + +test('gives a caller without a full identity no private group', () => { + const groups = database(PRIVATE, PRIVATE_PASSWD); + expect(privateGroupId(groups, { uid: undefined, gid: 1000, name: 'ada' })).toBeUndefined(); + expect(privateGroupId(groups, { uid: 1000, gid: undefined, name: 'ada' })).toBeUndefined(); + expect(privateGroupId(groups, { uid: 1000, gid: 1000, name: undefined })).toBeUndefined(); +}); diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index 8917796e6b..1adabb0a20 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -1,6 +1,5 @@ import crypto from 'node:crypto'; import fs from 'node:fs'; -import os from 'node:os'; import path from 'node:path'; import { AppError } from '@agent-device/kernel/errors'; import { emitDiagnostic } from './diagnostics.ts'; @@ -57,16 +56,14 @@ export function publishFileSync(options: { export function publishScriptFileSync(options: { destination: string; contents: string; - mode?: number; publish?: AtomicPublishMode; parentIdentity?: string; }): void { - const mode = options.mode ?? 0o600; const expected = options.parentIdentity ?? publishDirectoryIdentity(path.dirname(options.destination)); withAtomicPublishTempPathSync(options.destination, (temporaryPath) => { assertPrivateScriptDestination(options.destination, expected); - fs.writeFileSync(temporaryPath, options.contents, { encoding: 'utf8', mode }); + fs.writeFileSync(temporaryPath, options.contents, { encoding: 'utf8', mode: SCRIPT_FILE_MODE }); assertPrivateScriptDestination(options.destination, expected); if (options.publish === 'link-exclusive') { fs.linkSync(temporaryPath, options.destination); @@ -76,6 +73,9 @@ export function publishScriptFileSync(options: { }); } +/** A recording holds literals a `fill` did not parameterize (ADR 0017), so it is written private. */ +const SCRIPT_FILE_MODE = 0o600; + export type DurableFilePublishMode = 'replace' | 'link-exclusive'; /** Publishes complete UTF-8 contents with a durable file and directory fence. */ @@ -227,149 +227,184 @@ export function assertPrivateScriptDestination(destination: string, parentIdenti throw scriptAncestryFailure(destination, parent, 'parent_replaced'); } const trust = readScriptTrust(); - assertNoPlantedLink(destination, parent, trust); - const traversed = traversedDirectories(parent); - if (traversed.paths.length === 0) return; - for (const directory of traversed.paths) { - const stats = statDirectoryChain(directory); - if (!stats) continue; - const exposure = untrustedAncestryExposure(stats, trust); - if (exposure) throw scriptAncestryFailure(destination, directory, exposure); - } - // The script entry is created inside the deepest directory that exists, or below it through + const walk = walkParent(destination, trust); + if (walk.reject !== undefined) throw walk.reject; + // The script entry is created inside the deepest directory the walk reached, or below it through // directories that do not exist yet. Where other local users can add entries, one of them can add // this entry first and the recording is theirs, so the creation has to be refused. - const deepest = statDirectoryChain(traversed.deepest); + const deepest = statDirectoryChain(walk.deepest); if (deepest && othersCreateEntriesIn(deepest, trust)) { - throw scriptAncestryFailure(destination, traversed.deepest, 'shared_parent'); + throw scriptAncestryFailure(destination, walk.deepest, 'shared_parent'); } } -/** Link hops one destination walk expands before it stops, in step with the kernel's own limit. */ -const MAX_SYMLINK_HOPS = 40; +/** + * The parent of `destination`, made absolute but never normalized. + * + * `path.resolve` folds a `..` away, which is the one simplification this may not make: the kernel does + * not make it either, so `.../work/../x` lands its entry beside the target of the link named `work`. The + * spelled components are what the walk resolves; a relative destination keeps its relative spelling and + * starts from the working directory, which is how it reaches the filesystem. + */ +function spelledParent(destination: string): string { + if (path.isAbsolute(destination)) return path.dirname(destination); + const parent = path.dirname(destination); + return parent === '.' ? '' : parent; +} + +/** + * Where the walk stands: a directory it has already judged and physically reached, plus the names still + * to resolve. `deepest` is the directory the entry is created in when the walk stops here. + */ +type WalkState = Readonly<{ + deepest: string; + authority: DirectoryAuthority; + /** 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: 'stop'; deepest: string }> + | Readonly<{ kind: 'stand'; state: WalkState }>; + +/** A walk that ended: the deepest directory reached, or the typed refusal. */ +type WalkOutcome = Readonly<{ reject: AppError | undefined; deepest: string }>; /** - * Every directory the kernel traverses to reach `parent`, judged nearest-first, without duplicates, and - * the deepest one that exists. + * 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. * - * Resolving only the deepest existing ancestor is not enough, and neither is one `realpath` of a path - * that runs through links: + * No `realpath` is involved anywhere. `realpathSync` answers only with the FINAL directory, so any + * directory the resolution stepped through can vanish from the answer, and from the judgment, whenever a + * link leads on to another link, or a spelled prefix names a plain directory whose ground is shared. + * Instead each component is resolved against the directory physically reached: * - * - A component that is a plain directory is traversed as it stands, so a link inside it can lead - * anywhere, and the directories above that plain component are reached by the publish even though the - * final chain looks entirely private: `/shared` at 0777 with `/shared/mine` at 0700 and - * `mine/rec` a link to a private directory names only trusted directories at its destination, while - * another local user owns the ground `mine` and `rec` stand on and can rename `mine` aside. So EVERY - * existing prefix of the spelled path is resolved, and the chain under each resolution is judged. - * - Where one link leads into another, `realpathSync` answers with the LAST target and names none of the - * directories stepped through on the way: `~/rec -> /srv/team/relay -> ~/chosen` reaches a private - * directory, and the team ground `relay` stands on never appears in the answer, though any teammate - * can swap that link for a target of their own. So a link hop also judges the directory holding its - * target, and the walk continues into the target. + * - `.` 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 component ends the walk, because the + * publish creates what is missing below here. + * - A directory is judged and entered. + * - A symbolic link is judged itself, against the directory that physically holds it, and its target's + * components go in front of the queue — restarting from `/` for an absolute target. 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. + * + * A relative destination starts from the process's resolved working directory: the caller already stands + * there, and the walk cannot step above it. */ -function traversedDirectories( - parent: string, -): Readonly<{ paths: readonly string[]; deepest: string }> { - const seen = new Set(); - const paths: string[] = []; - let deepest: string | undefined; - for (const prefix of directoryChain(parent)) { - let current = prefix; - // Each hop replaces one link with its target, so a link cycle cannot run the walk forever. The - // operating system applies a limit of the same order and refuses the publish when it is exceeded. - for (let hop = 0; hop <= MAX_SYMLINK_HOPS; hop += 1) { - const stats = lstatIfPresentSync(current); - if (stats === undefined) break; - if (!stats.isSymbolicLink()) { - const real = resolvedDirectory(current); - if (real === undefined) break; - deepest ??= real; - for (const ancestor of directoryChain(real)) { - if (seen.has(ancestor)) continue; - seen.add(ancestor); - paths.push(ancestor); - } - break; - } - const target = linkTarget(current); - // The kernel steps INTO the directory the target names, so that directory and everything above it - // are traversed whatever this link eventually resolves to. - const home = resolvedDirectory(parentDirectory(target)); - if (home !== undefined) { - for (const ancestor of directoryChain(home)) { - if (seen.has(ancestor)) continue; - seen.add(ancestor); - paths.push(ancestor); - } - } - current = target; - } +function walkParent(destination: string, trust: ScriptDestinationTrust): WalkOutcome { + let step = startWalk(spelledParent(destination), trust); + // Every step consumes a component, and every link hop counts against a fixed limit, so this ends. + for (;;) { + if (step.kind === 'reject') return { reject: refusalAt(destination, step), deepest: '/' }; + if (step.kind === 'stop') return { reject: undefined, deepest: step.deepest }; + const { state } = step; + if (state.queue.length === 0) return { reject: undefined, deepest: state.deepest }; + step = stepWalk(state, trust); } - return { paths, deepest: deepest ?? parent }; } -/** Where a symbolic link points, made absolute the way the kernel reads it. */ -function linkTarget(link: string): string { - const target = fs.readlinkSync(link); - return path.isAbsolute(target) ? target : `${parentDirectory(link)}/${target}`; +function refusalAt( + destination: string, + step: Readonly<{ path: string; exposure: ScriptAncestryExposure }>, +): AppError { + return scriptAncestryFailure(destination, step.path, step.exposure); } -/** The directory `path` names once every link in it is expanded, or `undefined` when it is absent. */ -function resolvedDirectory(pathname: string): string | undefined { - if (lstatIfPresentSync(pathname) === undefined) return undefined; - try { - const real = fs.realpathSync(pathname); - return statDirectoryChain(real) ? real : undefined; - } catch (error) { - if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; - throw error; - } +/** The first state: `/` for an absolute spelling, the resolved working directory otherwise. */ +function startWalk(parent: string, trust: ScriptDestinationTrust): WalkStep { + const queue = pathComponents(parent); + // A relative destination starts from the working directory as the kernel sees it, symlink-free: the + // caller already stands there, so it is where the walk starts rather than a step it has to earn. + if (parent !== '' && !path.isAbsolute(parent)) return standIn(path.resolve(''), queue, trust, 0); + return standIn('/', queue, trust, 0); } -/** - * The parent of `destination` as it was spelled, made absolute but never normalized. - * - * `path.resolve` folds a `..` away, which is the one simplification this rule may not make: the kernel - * does not make it either, so `.../work/../x` lands an entry beside the target of a link named `work`. - * The chain that walk produces is what gets judged. - */ -function spelledParent(destination: string): string { - if (path.isAbsolute(destination)) return parentDirectory(destination); - // A relative destination reaches the filesystem through the working directory, the same way - // `path.resolve` names it, and the walk above is what the kernel performs from there. - return parentDirectory(path.resolve(destination)); +/** Judges `directory` and stands the walk there, or refuses it. */ +function standIn( + directory: string, + queue: readonly string[], + trust: ScriptDestinationTrust, + hops: number, +): WalkStep { + const stats = statDirectoryChain(directory); + if (stats === undefined) return { kind: 'reject', path: directory, exposure: 'not_a_directory' }; + const authority: DirectoryAuthority = { uid: stats.uid, gid: stats.gid, mode: stats.mode }; + const exposure = untrustedAncestryExposure(authority, trust); + if (exposure) return { kind: 'reject', path: directory, exposure }; + return { kind: 'stand', state: { deepest: directory, authority, queue, hops } }; +} + +/** 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. */ +function stepWalk(state: WalkState, trust: ScriptDestinationTrust): WalkStep { + const [component, ...rest] = state.queue; + if (component === undefined) return { kind: 'stop', deepest: state.deepest }; + // `..` 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 standIn(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 = lstatIfPresentSync(entry); + // Nothing below here exists yet, so the publish creates it inside the directory the walk reached. + if (stats === undefined) return { kind: 'stop', deepest: state.deepest }; + if (stats.isSymbolicLink()) return stepThroughLink(state, entry, stats, rest, trust); + return standIn(entry, rest, trust, state.hops); } /** - * Refuses a symbolic link on the spelled path that another local user could have put there, or could - * replace. The link's target is judged through the resolved chain, so this only asks whether the link - * itself is stable: - * - * - In a directory others cannot add entries in, a link nobody but this user or root can write is not - * something they can plant or swap. - * - In a directory others CAN add entries in, the sticky bit is what protects an entry that already - * exists: it stops anyone but the entry's owner or root from removing or replacing it. Without the - * sticky bit, any of them can unlink this link and plant one pointing wherever they choose. + * One hop. The link is judged where it physically stands: inside a directory others may add entries to, + * only a link this user or root owns, held by the sticky bit, is theirs to keep. Its target's components + * then enter the queue, because the kernel steps into them next. */ -function assertNoPlantedLink( - destination: string, - parent: string, +function stepThroughLink( + state: WalkState, + link: string, + stats: fs.Stats, + rest: readonly string[], trust: ScriptDestinationTrust, -): void { - for (const ancestor of directoryChain(parent)) { - const link = lstatIfPresentSync(ancestor); - if (!link?.isSymbolicLink()) continue; - const home = lstatIfPresentSync(parentDirectory(ancestor)); - if (!home) continue; - const exposure = untrustedLinkExposure( - { uid: link.uid }, - { uid: home.uid, gid: home.gid, mode: home.mode }, - trust, - ); - if (exposure) throw scriptAncestryFailure(destination, ancestor, exposure); +): WalkStep { + const exposure = untrustedLinkExposure({ uid: 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); + const queue = [ + ...pathComponents(path.isAbsolute(target) ? target : path.join(state.deepest, target)), + ...rest, + ]; + // An absolute target restarts the walk at the root; a relative one continues from where the walk is. + const home = path.isAbsolute(target) ? '/' : state.deepest; + return standIn(home, queue, 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 of their own (macOS 32, Linux 40), + * so this rule always reaches its own limit first and answers with its own typed reason. The walk counts + * hops rather than letting the kernel answer `ELOOP`, because a walk that ran out of hops has NOT + * established where the entry lands, and that is a refusal, not a pass. + */ +export const MAX_SCRIPT_PATH_LINK_HOPS = 30; + /** * One directory's identity on its filesystem, for a caller that must publish into the same one it * created or checked. `undefined` when the directory is absent or is not a directory. @@ -380,11 +415,75 @@ export function publishDirectoryIdentity(directory: string): string | undefined return stats ? `${stats.dev}:${stats.ino}` : undefined; } -/** The group and passwd records the private-group exception reads, in `/etc/group` field order. */ +/** The host files the private-group exception reads, in `/etc/group` field order. */ type HostGroupDatabase = Readonly<{ /** `undefined` when the file could not be read, which is not the same as a file with no records. */ groups: readonly string[] | undefined; passwd: readonly string[] | undefined; + /** `/etc/nsswitch.conf`, which says whether the two files above are the whole story. */ + nsswitch: readonly string[] | undefined; +}>; + +/** One `group:` or `passwd:` line of `/etc/nsswitch.conf`, or `undefined` when none was found. */ +type NsswitchLine = Readonly<{ database: string; sources: readonly string[] }>; + +/** + * Whether `/etc/nsswitch.conf` establishes that the group and passwd files are the whole story. + * + * `files` is the only source admitted. `systemd` is deliberately NOT admitted, even though it is the + * default on some distributions: `systemd-userdbd` answers group membership from user records the two + * files never see, which is exactly the member this rule could not read. Bracketed actions such as + * `[NOTFOUND=return]` steer a lookup and add no source, so they are ignored. A missing line, an + * unparseable line, or an unreadable file establishes nothing, and the exception is refused. + */ +export function nameServiceListsOnlyFiles(nsswitch: readonly string[] | undefined): boolean { + if (nsswitch === undefined) return false; + for (const database of ['passwd', 'group']) { + const line = nsswitchLine(nsswitch, database); + if (line === undefined) return false; + if (!line.sources.every((source) => source === 'files')) return false; + if (line.sources.length === 0) return false; + } + return true; +} + +function nsswitchLine(lines: readonly string[], database: string): NsswitchLine | undefined { + for (const raw of lines) { + const source = (raw.split('#')[0] ?? '').trimStart(); + const [name, ...rest] = source.split(/[\s:]+/); + if (name !== database) continue; + // A bracketed action steers a lookup and lists no source. + const sources = rest.filter((token) => token.length > 0 && !token.startsWith('[')); + return { database, sources }; + } + return undefined; +} + +/** One `/etc/group` record. A line without a numeric gid cannot be used to judge membership. */ +type GroupRecord = Readonly<{ name: string; gid: number; members: readonly string[] }>; + +/** One `/etc/passwd` record. */ +type PasswdRecord = Readonly<{ name: string; uid: number; gid: number }>; + +function parseGroupRecord(line: string): GroupRecord | undefined { + const [name, , rawGid, rawMembers = ''] = line.split(':'); + const gid = Number(rawGid); + if (name === undefined || name === '' || rawGid === '' || !Number.isInteger(gid)) + return undefined; + return { name, gid, members: rawMembers.split(',').filter((member) => member.length > 0) }; +} + +function parsePasswdRecord(line: string): PasswdRecord | undefined { + const [name, , rawUid, rawGid] = line.split(':'); + if (name === undefined || name === '') return undefined; + return { name, uid: Number(rawUid), gid: Number(rawGid) }; +} + +/** This process's own account: the uid and primary gid the kernel reports, and the name it maps to. */ +type CurrentAccount = Readonly<{ + uid: number | undefined; + gid: number | undefined; + name: string | undefined; }>; /** @@ -395,6 +494,9 @@ type HostGroupDatabase = Readonly<{ * so it stays a valid script destination. Every other group stays outside the exception, and the rule * fails closed wherever completeness cannot be established: * + * - `/etc/nsswitch.conf` must exist, be readable, and name `files` as the ONLY source for both `passwd` + * and `group`. Otherwise a name service could hold a member no file shows, and nothing here could see + * it. {@link nameServiceListsOnlyFiles} says what a name service may say. * - Both database files must have been READ. An unreadable file is not an empty one, and an empty * member list proves nothing. * - The gid must be the one this process holds as its PRIMARY group, which `getgid` answers from the @@ -406,106 +508,113 @@ type HostGroupDatabase = Readonly<{ * while every local user holds it. * - No other passwd record may hold this gid as its primary group, and the caller's own record must * exist there with this uid and this gid. - * - * What this cannot establish, stated plainly because it cuts BOTH ways: the two files are only this - * machine's own view. A name service (LDAP, an NSS module) can hold a member of this gid, or a second - * group with the number, that never appears in `/etc/passwd` or `/etc/group`. Such a host can be - * refused a group-writable directory it genuinely owns, and it can also be ACCEPTED for one the name - * service has opened to someone else — this rule cannot see that member and so cannot refuse it. The - * caller's answer on a name-service host is a directory only they can write, at any mode. */ export function privateGroupId( database: HostGroupDatabase, - current: Readonly<{ uid: number | undefined; gid: number | undefined; name: string | undefined }>, + current: CurrentAccount, ): number | undefined { + if (!nameServiceListsOnlyFiles(database.nsswitch)) return undefined; + const records = parseHostGroupDatabase(database); + if (records === undefined) return undefined; + return admittedPrivateGid(records, current); +} + +/** The host's two databases, parsed, or `undefined` when either file could not be read. */ +type HostAccounts = Readonly<{ + groups: readonly GroupRecord[]; + passwd: readonly PasswdRecord[]; +}>; + +function parseHostGroupDatabase(database: HostGroupDatabase): HostAccounts | undefined { + if (!database.groups || !database.passwd) return undefined; + return { + groups: database.groups.flatMap((line) => { + const record = parseGroupRecord(line); + return record === undefined ? [] : [record]; + }), + passwd: database.passwd.flatMap((line) => { + const record = parsePasswdRecord(line); + return record === undefined ? [] : [record]; + }), + }; +} + +/** The decision the parsed databases allow: this gid, when it is the caller's own private group. */ +function admittedPrivateGid(accounts: HostAccounts, current: CurrentAccount): number | undefined { const { uid, gid, name } = current; if (uid === undefined || gid === undefined || name === undefined) return undefined; - if (!database.groups || !database.passwd) return undefined; - const own = database.passwd.find((line) => line.split(':')[0] === name); - if (!own) return undefined; - const [, , ownUid, ownGid] = own.split(':'); - if (Number(ownUid) !== uid || Number(ownGid) !== gid) return undefined; + const own = accounts.passwd.find((record) => record.name === name); + if (own === undefined || own.uid !== uid || own.gid !== gid) return undefined; + const carrying = accounts.groups.filter((record) => record.gid === gid); + if (!carrying.some((record) => record.name === name)) return undefined; // EVERY record carrying this gid decides together: a directory group-writable by gid 1000 is writable - // by the members of each of them, however they are named. A group named after the user buys the - // exception only while no other record sharing the number reaches another user. - let namedForUser = false; - for (const line of database.groups) { - const [groupName, , rawGid, rawMembers = ''] = line.split(':'); - const recordGid = Number(rawGid); - if (rawGid === '' || !Number.isInteger(recordGid) || recordGid !== gid) continue; - if (groupName === name) namedForUser = true; - const members = rawMembers.split(',').filter((member) => member.length > 0); - if (members.some((member) => !memberIsTrusted(member, database, name))) return undefined; - } - if (!namedForUser) return undefined; - const sharesPrimary = database.passwd.some((line) => { - const [other, , rawOtherUid, rawOtherGid] = line.split(':'); - return other !== name && Number(rawOtherGid) === gid && Number(rawOtherUid) !== 0; - }); + // by the members of each of them, however they are named. + const reachesAnybodyElse = carrying.some((record) => + record.members.some((member) => !memberIsTrusted(member, accounts, name)), + ); + if (reachesAnybodyElse) return undefined; + const sharesPrimary = accounts.passwd.some( + (record) => record.name !== name && record.gid === gid && record.uid !== 0, + ); return sharesPrimary ? undefined : gid; } /** Whether a member of a candidate private group is the user or root, the two accounts the rule trusts. */ -function memberIsTrusted(member: string, database: HostGroupDatabase, name: string): boolean { +function memberIsTrusted(member: string, accounts: HostAccounts, name: string): boolean { if (member === name) return true; - const record = database.passwd?.find((line) => line.split(':')[0] === member); - return record !== undefined && Number(record.split(':')[2]) === 0; + const record = accounts.passwd.find((other) => other.name === member); + return record !== undefined && record.uid === 0; +} + +/** + * The account name this process's uid maps to, read from the host account database. The name comes from + * the same file the group records come from, so a caller standing in for that file and this name stays in + * agreement. No `os.userInfo()`: that answers from a different source than the records being judged. + */ +function readCurrentUser( + passwd: readonly string[] | undefined, + uid: number | undefined, +): string | undefined { + if (passwd === undefined || uid === undefined) return undefined; + for (const line of passwd) { + const record = parsePasswdRecord(line); + if (record?.uid === uid) return record.name; + } + return undefined; } /** This process's identity and the private group its host databases establish, if any. */ function readScriptTrust(): ScriptDestinationTrust { + const passwd = readSystemFile('/etc/passwd'); + const uid = process.getuid?.(); return { - uid: process.getuid?.() ?? -1, + uid: uid ?? -1, privateGid: privateGroupId( - { groups: readSystemFile('/etc/group'), passwd: readSystemFile('/etc/passwd') }, - { uid: process.getuid?.(), gid: process.getgid?.(), name: readCurrentUser() }, + { + groups: readSystemFile('/etc/group'), + passwd, + nsswitch: readSystemFile(NSSWITCH_FILE), + }, + { uid, gid: process.getgid?.(), name: readCurrentUser(passwd, uid) }, ), }; } -function readCurrentUser(): string | undefined { - try { - return os.userInfo().username; - } catch { - return undefined; - } -} - -/** Every directory from `directory` up to the filesystem root, nearest first. */ -function directoryChain(directory: string): string[] { - const chain: string[] = []; - let current = directory; - for (;;) { - chain.push(current); - const parent = parentDirectory(current); - if (parent === current) return chain; - current = parent; - } -} - -/** - * The parent of `directory`, as the kernel sees it, or the same path when there is no parent. - * - * `path.dirname` is not usable here: it normalizes, so it folds a `..` segment away. That is the one - * simplification this rule may not make. Where `work` is a symbolic link, `.../work/../x` is a real - * path that lands beside the link's TARGET, so the rule has to see `.../work` in the chain and judge - * the link that stands there. Only a trailing separator is dropped, in linear time. - */ -function parentDirectory(directory: string): string { - const trimmed = directory.endsWith('/') ? directory.slice(0, -1) : directory; - const separator = trimmed.lastIndexOf('/'); - if (separator < 0) return trimmed; - return separator === 0 ? '/' : trimmed.slice(0, separator); -} +/** The file that says which sources the host looks in for accounts and groups. */ +const NSSWITCH_FILE = '/etc/nsswitch.conf'; /** - * The two ways a directory can be unsafe for a destination: someone else can change what is in it, or - * someone else can create the entry the destination names. + * The ways a step of the walk can be unsafe: somebody else can change what is in that directory, they + * can create the entry the destination names, they can put the link there, or the step cannot be trusted + * at all. * * `foreign_owned` — some other user owns it and can chmod, empty, or repopulate it whatever its mode. * `world_writable` / `shared_group_writable` — its mode opens its contents to others. * `shared_parent` — nobody else can change what is in it today, but they can add the missing entry. - * `planted_link` — a symbolic link someone else could have put in place of a directory. + * `planted_link` — a symbolic link another user could have put in place of a directory, or could replace. + * `link_loop_exceeded` — the walk expanded as many links as the kernel allows, so where it lands is not + * established. A loop is refused, never trusted. + * `not_a_directory` — a step of the path is something a publish cannot travel through. * `parent_replaced` — the directory the caller staged against is not the one it was. */ export type ScriptAncestryExposure = @@ -514,6 +623,8 @@ export type ScriptAncestryExposure = | 'shared_group_writable' | 'shared_parent' | 'planted_link' + | 'link_loop_exceeded' + | 'not_a_directory' | 'parent_replaced'; /** What this process can rely on when it judges a directory: its identity and its private group. */ 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 bdf3aea2df..7663568bd4 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts @@ -6,10 +6,12 @@ import type { DaemonWireRequest } from '@agent-device/contracts/command'; import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; import * as file from '@agent-device/host-kit/file'; import { + FOREIGN_UID, closeLoopbackServer, createTestHostEnvironment, listenOnLoopback, mkdtempForTestSync, + serveHostOwnership, } from '@agent-device/test-kit'; import { AppError } from '@agent-device/kernel/errors'; import { materializeRemoteArtifacts } from '../daemon-artifacts.ts'; @@ -491,6 +493,108 @@ test.skipIf(process.platform === 'win32')( }, ); +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 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 () => { 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..ae945c1966 --- /dev/null +++ b/packages/test-kit/src/host-ownership.fixtures.ts @@ -0,0 +1,27 @@ +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. + * + * 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` to another uid — 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>): void { + const realLstat = fs.lstatSync.bind(fs); + const realStat = fs.statSync.bind(fs); + const reuid = (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[]) => + reuid(realLstat(pathname, ...rest), String(pathname))) as typeof fs.lstatSync); + vi.spyOn(fs, 'statSync').mockImplementation(((pathname: never, ...rest: never[]) => + reuid(realStat(pathname, ...rest), String(pathname))) as typeof fs.statSync); +} diff --git a/packages/test-kit/src/index.ts b/packages/test-kit/src/index.ts index 5d74593d59..fbd6c01e3e 100644 --- a/packages/test-kit/src/index.ts +++ b/packages/test-kit/src/index.ts @@ -122,6 +122,7 @@ export { unavailableDeploymentSnapshotAndShutdownOperationFacts, } from './runtime-operation-facts.ts'; export { createTestRuntimeStateHandle, type TestRuntimeStateHandle } from './runtime-state.ts'; +export { FOREIGN_UID, serveHostOwnership } from './host-ownership.fixtures.ts'; export { buildNodes } from './snapshot-builders.ts'; export { bottomTabsRealCaptureFixture, diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index ad640be4d5..2a39c69f57 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -72,9 +72,9 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow - Missing parent directories are created. 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. -- Directories between the path you typed and where it ends are checked too, not only the final result. A plain directory that is open to others can hold a link into a private directory, so the destination looks private while the ground the link stands on is shared, and a link that points at another link passes through a directory the final path never names. Both are refused. A `..` segment is checked too, including the directory it steps back out of. -- The whole real path is checked, so a symbolic link to a shared directory is refused too. 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. 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories. Every group carrying that group number is considered, so a second group with the same number that lists somebody else closes this exception. +- 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 `..` is applied to the directory the walk actually reached, not to the text you typed: where `work` is a link, `work/../x` lands beside the link's target, and that is the directory judged. 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories, and only where `/etc/nsswitch.conf` shows that `/etc/group` and `/etc/passwd` are the whole story: a name service could hold a member those files never show. Every group carrying that group number is considered, so a second group with the same number that lists somebody else closes this exception. - 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. From 352adcc018d1fc909ac5dd2b63da1454a4536b59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 15:37:59 +0100 Subject: [PATCH 11/28] fix(host-kit): resolve a link target relative to the directory that holds it A relative link target was joined onto the directory the walk stood in, which made it absolute, and the walk then continued from the link's own directory. The lookup missed the target and the walk stopped, so the target and the directories on the way to it were never judged: `ln -s ../team/rec rec` reopened #4565. `path.join` also folded a `..` inside a target away. Targets are now queued as RAW components, restarting at `/` for an absolute target and continuing from the directory that holds the link for a relative one. The same folding let a publisher escape the judged directory. Staging used `path.join` on the spelled destination, which answers a DIFFERENT directory wherever the walk turned aside, so the temp file was written into ground nobody judged and renamed into the judged one from outside it. `assertPrivateScriptDestination` now returns the physical directory it verified, and both the local publisher and the remote client stage inside it. The parent identity is taken from that directory too, so a `..` destination no longer reports a replacement that never happened, and the refusal names the directory the entry would really have been created in. A relative destination with no directory in it had the working directory as its parent rather than nothing, so the walk started there instead of at `/`. Each physical directory is judged once per walk and each path is read once, so an alias or a `..` back over ground already crossed costs nothing. The private-group exception also reads `initgroups:`, the database glibc answers SUPPLEMENTARY membership from: an explicit line has to be files-only, and an absent one inherits the verified `group` setting. `lstatIfPresent` is imported from the module that owns it, the two local copies are gone, and the message says what a link-loop or a non-directory refusal actually found. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 6 +- .../session-script-writer-ancestry.test.ts | 35 ++ .../daemon/src/core/session-script-writer.ts | 15 +- .../src/internal/atomic-file-ancestry.test.ts | 255 ++++++++------ .../internal/atomic-file-decisions.test.ts | 113 +++++++ .../atomic-file-private-group.test.ts | 23 ++ packages/host-kit/src/internal/atomic-file.ts | 312 +++++++++++------- .../daemon-artifacts-script-download.test.ts | 75 +++++ .../remote/src/session-script-destination.ts | 15 +- website/docs/docs/replay-e2e.md | 4 +- 10 files changed, 615 insertions(+), 238 deletions(-) create mode 100644 packages/host-kit/src/internal/atomic-file-decisions.test.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index f990c79b41..bf6360d1e9 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -214,11 +214,13 @@ 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 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. +The walk ANSWERS with the physical directory the entry is created in, and the publishers stage inside it. `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. Each physical directory is judged once per walk and each path is read once, so an alias or a `..` back over ground already crossed costs nothing. 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. +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 `passwd`, for `group`, and for `initgroups` — the database glibc reads SUPPLEMENTARY membership from, which those two files say nothing about. An absent `initgroups:` line inherits the verified `group` setting, as the kernel does. `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. +The publisher compares the judged 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 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 index 19578d277a..91bdec0d3d 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -296,6 +296,41 @@ skipOnWindows('a recording refuses a chain that leaves a shared directory throug 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 diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index 0d26cfed63..2b6c6fa541 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -19,7 +19,7 @@ import { stripRecordedRefGeneration, } from '@agent-device/ad-script'; import { expandSessionPath, safeSessionName } from '@agent-device/host-kit/session-paths'; -import { publishDirectoryIdentity, publishScriptFileSync } 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, @@ -139,12 +139,9 @@ export class SessionScriptWriter { // (`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, - parentIdentity: publishDirectoryIdentity(scriptDir), - }); + // No parent identity travels with this call: the publisher judges the directory the entry is + // created in, and that is the one its identity is worth comparing. + publishHealedScriptAtomically({ scriptPath, script: prepared.script, force: options?.force }); // COMMITTED: idempotent guard above + teardown's abort/tombstone routing. if (repairArmed) { session.scriptPublication = commitRepair( @@ -317,15 +314,13 @@ function publishHealedScriptAtomically(params: { scriptPath: string; script: string; force?: boolean; - parentIdentity?: string; }): void { - const { scriptPath, script, force, parentIdentity } = params; + const { scriptPath, script, force } = params; try { publishScriptFileSync({ destination: scriptPath, contents: script, publish: force ? 'replace' : 'link-exclusive', - ...(parentIdentity === undefined ? {} : { parentIdentity }), }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index 54314a81ac..32e25eeef2 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -5,13 +5,9 @@ import { AppError } from '@agent-device/kernel/errors'; import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; import { assertPrivateScriptDestination, - othersCreateEntriesIn, publishDirectoryIdentity, publishScriptFileSync, - untrustedAncestryExposure, - untrustedLinkExposure, MAX_SCRIPT_PATH_LINK_HOPS, - type DirectoryAuthority, } from './atomic-file.ts'; const skipOnWindows = process.platform === 'win32' ? test.skip : test; @@ -365,6 +361,153 @@ skipOnWindows('refuses the ground under a link that leads into a shared director expect(fs.readdirSync(chosen)).toEqual([]); }); +skipOnWindows( + 'refuses a link whose target is spelled relative to the directory that holds it', + () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `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( + () => assertPrivateScriptDestination(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', + () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `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('reads each directory it stands in once, however many routes lead back to it', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `a` and `b` are two aliases of the same directory, and the spelling passes through both with a `..` + // between them, so the walk returns over ground it already crossed — the scratch root three times here, + // and the alias's target once for each route. A directory's judgment does not depend on the route taken + // to it, so each path is read once and each physical directory is judged once. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const target = directoryWith(path.join(directory, 'target'), 0o700); + const sub = path.join(target, 'sub'); + fs.mkdirSync(sub); + fs.symlinkSync(target, path.join(home, 'a')); + fs.symlinkSync(target, path.join(home, 'b')); + const reads: string[] = []; + const realStatSync = fs.statSync; + vi.spyOn(fs, 'statSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + reads.push(String(pathname)); + return (realStatSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.statSync); + + assertPrivateScriptDestination(`${home}/a/../b/sub/journey.ad`); + + expect(new Set(reads).size).toBe(reads.length); +}); + +skipOnWindows('starts a destination with no directory in it at the working directory', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `journey.ad` names the working directory as its parent, which is where the entry is created. Treated + // as having NO parent, the walk starts at `/` instead, and a caller that reported the identity of `.` + // is told its parent was replaced. + const cwd = path.resolve(''); + const identity = publishDirectoryIdentity('.'); + + expect(identity).toBeDefined(); + expect(assertPrivateScriptDestination('journey.ad', identity)).toBe(cwd); +}); + +skipOnWindows('refuses a relative target that lands in ground others can write', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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( + () => assertPrivateScriptDestination(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', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `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( + () => assertPrivateScriptDestination(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', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + 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', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); // The same target reached two ways has to answer the same way: spelling the shared directory out is @@ -737,7 +880,9 @@ skipOnWindows('refuses a parent replaced by name while the file was staged', () fs.rmSync(staged, { recursive: true }); fs.symlinkSync(elsewhere, staged); - expectUntrustedReplaced(() => publish(destination, parentIdentity), 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(() => publish(destination, parentIdentity), elsewhere); expect(fs.readdirSync(elsewhere)).toEqual([]); }); @@ -759,7 +904,7 @@ skipOnWindows('re-checks the chain after staging the file, before the entry is c return result; }) as typeof fs.writeFileSync); - expectUntrustedReplaced(() => publish(destination), staged); + expectUntrustedReplaced(() => publish(destination), attacker); expect(fs.readdirSync(attacker)).toEqual([]); }); @@ -772,101 +917,3 @@ skipOnWindows('publishes into the parent the captured identity still names', () expect(fs.existsSync(path.join(staged, 'journey.ad'))).toBe(true); }); - -// --- untrustedAncestryExposure: what makes one directory unsafe to publish inside --- - -const OWN = { uid: currentUid, gid: currentGid, mode: 0o755 }; -const TRUST = { uid: currentUid, privateGid: currentGid }; - -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 by a group that is not this user', () => { - expect(untrustedAncestryExposure(directoryOf({ gid: 4321, mode: 0o775 }), TRUST)).toBe( - 'shared_group_writable', - ); -}); - -test('accepts a directory group-writable by this user', () => { - expect(untrustedAncestryExposure(directoryOf({ mode: 0o775 }), TRUST)).toBeUndefined(); -}); - -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({ mode: 0o775 }), TRUST)).toBeUndefined(); -}); - -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({ gid: 4321, mode: 0o775 }), TRUST)).toBe(true); -}); - -test('names no directory whose group is this user', () => { - expect(othersCreateEntriesIn(directoryOf({ mode: 0o775 }), TRUST)).toBe(false); - expect(othersCreateEntriesIn(directoryOf({ mode: 0o1775 }), TRUST)).toBe(false); - expect(othersCreateEntriesIn(directoryOf({ mode: 0o755 }), 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-decisions.test.ts b/packages/host-kit/src/internal/atomic-file-decisions.test.ts new file mode 100644 index 0000000000..196db606cc --- /dev/null +++ b/packages/host-kit/src/internal/atomic-file-decisions.test.ts @@ -0,0 +1,113 @@ +// 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; +const currentGid = process.getgid?.() ?? -1; + +// --- what makes one directory unsafe to publish inside --- + +const OWN = { uid: currentUid, gid: currentGid, mode: 0o755 }; +const TRUST = { uid: currentUid, privateGid: currentGid }; + +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 by a group that is not this user', () => { + expect(untrustedAncestryExposure(directoryOf({ gid: 4321, mode: 0o775 }), TRUST)).toBe( + 'shared_group_writable', + ); +}); + +test('accepts a directory group-writable by this user', () => { + expect(untrustedAncestryExposure(directoryOf({ mode: 0o775 }), TRUST)).toBeUndefined(); +}); + +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({ mode: 0o775 }), TRUST)).toBeUndefined(); +}); + +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({ gid: 4321, mode: 0o775 }), TRUST)).toBe(true); +}); + +test('names no directory whose group is this user', () => { + expect(othersCreateEntriesIn(directoryOf({ mode: 0o775 }), TRUST)).toBe(false); + expect(othersCreateEntriesIn(directoryOf({ mode: 0o1775 }), TRUST)).toBe(false); + expect(othersCreateEntriesIn(directoryOf({ mode: 0o755 }), 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-private-group.test.ts b/packages/host-kit/src/internal/atomic-file-private-group.test.ts index 440c702e31..4abfe9ae69 100644 --- a/packages/host-kit/src/internal/atomic-file-private-group.test.ts +++ b/packages/host-kit/src/internal/atomic-file-private-group.test.ts @@ -118,6 +118,29 @@ test('refuses it when nsswitch.conf adds a name service to either database', () expect(withNameService(['# no database lines here'])).toBeUndefined(); }); +test('refuses it when initgroups names a service, the database supplementary membership comes from', () => { + // glibc reads SUPPLEMENTARY group membership from `initgroups:`. `passwd: files` and `group: files` + // say nothing about it, so a service there can hold a member of this gid that neither file shows. + const withInitgroups = (line: string) => + privateGroupId( + { + groups: PRIVATE, + passwd: PRIVATE_PASSWD, + nsswitch: ['passwd: files', 'group: files', line], + }, + ADA, + ); + + expect(withInitgroups('initgroups: sss')).toBeUndefined(); + expect(withInitgroups('initgroups: ldap files')).toBeUndefined(); + expect(withInitgroups('initgroups: systemd')).toBeUndefined(); + // An absent line inherits the `group` setting, which is what the kernel does and what was verified. + expect(privateGroupId({ groups: PRIVATE, passwd: PRIVATE_PASSWD, nsswitch: FILES }, ADA)).toBe( + 1000, + ); + expect(withInitgroups('initgroups: files')).toBe(1000); +}); + test('admits a name service line that names only files, actions and comments aside', () => { expect( nameServiceListsOnlyFiles(['passwd: [NOTFOUND=return] files # local only', 'group: files']), diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index 1adabb0a20..519321ea7a 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -3,6 +3,7 @@ import fs from 'node:fs'; import path from 'node:path'; import { AppError } from '@agent-device/kernel/errors'; import { emitDiagnostic } from './diagnostics.ts'; +import { lstatIfPresent } from './verified-file.ts'; export type AtomicPublishMode = 'replace' | 'link-exclusive'; @@ -59,18 +60,57 @@ export function publishScriptFileSync(options: { publish?: AtomicPublishMode; parentIdentity?: string; }): void { - const expected = - options.parentIdentity ?? publishDirectoryIdentity(path.dirname(options.destination)); - withAtomicPublishTempPathSync(options.destination, (temporaryPath) => { - assertPrivateScriptDestination(options.destination, expected); + // The directory the entry is created in is the walk's ANSWER, asked for inside this call and twice: + // never `path.dirname` of the spelled destination, because a `..` or a link in the destination sends the + // entry somewhere else, and a temp file staged there is one another local user can reach, list, and + // put their own bytes behind before the publish does. + let temporaryPath: string | undefined; + try { + const judged = assertPrivateScriptDestination(options.destination); + const expected = options.parentIdentity ?? publishDirectoryIdentity(judged); + temporaryPath = createAtomicPublishTempPath(judged, options.destination); fs.writeFileSync(temporaryPath, options.contents, { encoding: 'utf8', mode: SCRIPT_FILE_MODE }); - assertPrivateScriptDestination(options.destination, expected); + const stillJudged = assertPrivateScriptDestination(options.destination, expected); + if (stillJudged !== judged) { + throw scriptAncestryFailure(options.destination, stillJudged, 'parent_replaced'); + } if (options.publish === 'link-exclusive') { fs.linkSync(temporaryPath, options.destination); } else { fs.renameSync(temporaryPath, options.destination); } - }); + } finally { + removeTempBestEffort(options.destination, temporaryPath); + } +} + +/** + * The canonical temp path for a destination: a private sibling of the name, inside the directory the + * publish will create the entry in. That directory is the walk's answer for a script destination, and + * `path.dirname` for every other publisher. + */ +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. */ @@ -130,23 +170,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); } } @@ -166,14 +194,6 @@ 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`, - ); -} - /** Identifies a temp path produced for a particular destination. */ export function isAtomicPublishTemporaryPath(value: unknown, destination: string): boolean { if (typeof value !== 'string') return false; @@ -183,19 +203,21 @@ export function isAtomicPublishTemporaryPath(value: unknown, destination: string } /** - * Refuses a script destination unless every directory on its fully resolved chain is one no other - * non-root local user can change (#4565). + * Refuses a script destination unless every directory the kernel looks a name up in is one no other + * non-root local user can change (#4565), and reports the PHYSICAL directory the entry is created in. * * Node exposes no `openat` or `renameat`, so a publisher cannot resolve a destination relative to a * directory handle. The window is closed by PERMISSIONS instead of by timing: once no other non-root - * user can add or remove an entry in any directory on the chain, nobody can swap a component out or - * plant one, so the path this rule judged is the path the publish reaches. Nothing here depends on when - * the directory was judged, and no re-check is what makes the write safe. + * user can add or remove an entry in any directory on the walk, nobody can swap a component out or plant + * one, so the path this rule judged is the path the publish reaches. Nothing here depends on when a + * directory was judged, and no re-check is what makes the write safe. * - * The existing prefix of the destination is resolved once, and every directory of that resolved chain - * is judged, so a symbolic link's target is judged too: `/home/me/link` standing for a shared directory - * is refused for the same reason that directory would be if the caller had spelled it out. Each - * directory then has to satisfy: + * The return value is part of the rule, not a convenience. The caller stages the temp file IN THAT + * DIRECTORY: a `..` or a symbolic link in the spelled destination means the directory the entry really + * lands in is not `path.dirname` of the spelling, and staging outside the judged directory would hand + * another local user the temp file they then get published. + * + * What the walk asks of every directory it enters ({@link walkParent} for the resolution itself): * * - It is owned by this user or by root. A directory another user owns is theirs to chmod, to empty, and * to repopulate, whatever its mode says today, and both the sticky bit and the group bits shield other @@ -203,53 +225,60 @@ export function isAtomicPublishTemporaryPath(value: unknown, destination: string * - Its mode opens its contents to nobody else. The sticky bit is the one exception, and only for * passing THROUGH a directory: it stops anyone but an entry's owner or root from removing or replacing * that entry, which is how macOS `/tmp` and `/var` stay usable. It cannot refuse a NEW entry by name, - * so nothing may be created inside a directory others can add entries to; that is asked separately. - * - A symbolic link the path passes through is one others could not have planted or swapped: in a - * directory where they can add entries, it stands there only because the sticky bit and its owner - * hold it in place. + * so nothing may be created inside a directory others can add entries to; that is asked separately, of + * the directory the walk ended in. + * - Every symbolic link the walk follows is judged itself, against the directory that physically holds + * it, at any depth: in a directory where others can add entries, it stands there only because the + * sticky bit and its owner hold it in place. A link's own mode is never consulted, because on Linux + * every link reports the same one. * * A group-writable directory this user owns stays acceptable when its group is this user's own private * group, the shape Ubuntu and Debian give every home directory. {@link privateGroupId} says what that * takes to establish, and what it cannot. * - * A component that exists and is neither a directory nor a link is left alone: the filesystem refuses a - * publish through it. On Windows, access is an ACL rather than a mode, so this is a no-op there. + * A component that is neither a directory nor a link is refused as `not_a_directory`: the kernel cannot + * travel through it either. On Windows, access is an ACL rather than a mode, so this rule is a no-op + * there and answers the parent it was given. * * `parentIdentity` is what {@link publishDirectoryIdentity} returned for the parent the caller created * or checked before it staged this file. The rule above already excludes anyone who could swap that * parent, so the comparison is defense in depth against a host whose ownership or modes moved meanwhile; * it is not what closes the window. */ -export function assertPrivateScriptDestination(destination: string, parentIdentity?: string): void { - if (process.platform === 'win32') return; - const parent = spelledParent(destination); - if (parentIdentity !== undefined && publishDirectoryIdentity(parent) !== parentIdentity) { - throw scriptAncestryFailure(destination, parent, 'parent_replaced'); - } +export function assertPrivateScriptDestination( + destination: string, + parentIdentity?: string, +): string { + if (process.platform === 'win32') return path.dirname(path.resolve(destination)); const trust = readScriptTrust(); const walk = walkParent(destination, trust); if (walk.reject !== undefined) throw walk.reject; + // The identity is asked of the directory the entry is created in, which is the walk's answer and NOT + // `path.dirname` of the spelling: where a `..` or a link leads elsewhere, the spelled parent is a + // different directory and comparing against it reports a replacement that never happened. + if (parentIdentity !== undefined && publishDirectoryIdentity(walk.deepest) !== parentIdentity) { + throw scriptAncestryFailure(destination, walk.deepest, 'parent_replaced'); + } // The script entry is created inside the deepest directory the walk reached, or below it through // directories that do not exist yet. Where other local users can add entries, one of them can add - // this entry first and the recording is theirs, so the creation has to be refused. - const deepest = statDirectoryChain(walk.deepest); - if (deepest && othersCreateEntriesIn(deepest, trust)) { + // this entry first and the recording is theirs, so the creation has to be refused. The authority the + // walk read there is reused rather than read again. + if (walk.authority !== undefined && othersCreateEntriesIn(walk.authority, trust)) { throw scriptAncestryFailure(destination, walk.deepest, 'shared_parent'); } + return walk.deepest; } /** - * The parent of `destination`, made absolute but never normalized. + * The parent of `destination`, cut at its last separator and never normalized. * * `path.resolve` folds a `..` away, which is the one simplification this may not make: the kernel does * not make it either, so `.../work/../x` lands its entry beside the target of the link named `work`. The - * spelled components are what the walk resolves; a relative destination keeps its relative spelling and - * starts from the working directory, which is how it reaches the filesystem. + * spelled components are what the walk resolves. A destination with no directory in it, `journey.ad`, + * has the working directory as its parent, which `path.dirname` already answers as `.`. */ function spelledParent(destination: string): string { - if (path.isAbsolute(destination)) return path.dirname(destination); - const parent = path.dirname(destination); - return parent === '.' ? '' : parent; + return path.dirname(destination); } /** @@ -263,19 +292,40 @@ type WalkState = Readonly<{ queue: readonly string[]; /** Link targets expanded so far. */ hops: number; + /** What this walk already learned about the ground it stands on. */ + ground: WalkGround; +}>; + +/** + * One walk's memory of the ground it has stood on: the modes it has read, keyed by path, and the + * directories whose judgment it already has, keyed by device and inode. A path that comes back around, + * through a `..` or through an alias of a directory already entered, is therefore asked of the host once, + * and one walk sees the host the same way throughout. + */ +type WalkGround = Readonly<{ + stats: Map; + judged: Set; }>; type WalkStep = | Readonly<{ kind: 'reject'; path: string; exposure: ScriptAncestryExposure }> - | Readonly<{ kind: 'stop'; deepest: string }> + | Readonly<{ kind: 'stop'; deepest: string; authority: DirectoryAuthority }> | Readonly<{ kind: 'stand'; state: WalkState }>; -/** A walk that ended: the deepest directory reached, or the typed refusal. */ -type WalkOutcome = Readonly<{ reject: AppError | undefined; deepest: string }>; +/** + * A walk that ended: the typed refusal, or the directory the entry is created in together with the + * authority it was judged with. The authority travels with the answer, so the caller never asks the host + * about ground the walk has already read. + */ +type WalkOutcome = Readonly<{ + reject: AppError | undefined; + deepest: string; + authority: DirectoryAuthority | undefined; +}>; /** * 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. + * 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 any * directory the resolution stepped through can vanish from the answer, and from the judgment, whenever a @@ -286,10 +336,12 @@ type WalkOutcome = Readonly<{ reject: AppError | undefined; deepest: string }>; * any other directory. Neither one is a name that has to exist. * - Any other component is lstat'ed in that directory. An absent component ends the walk, because the * publish creates what is missing below here. - * - A directory is judged and entered. + * - A directory is judged and entered. Each physical directory is judged once and each path is read from + * the host once per walk, so a `..` back over ground already crossed, or an alias of it, costs nothing. * - A symbolic link is judged itself, against the directory that physically holds it, and its target's - * components go in front of the queue — restarting from `/` for an absolute target. Hops are counted - * against {@link MAX_SCRIPT_PATH_LINK_HOPS}, and crossing it is refused rather than trusted. + * 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. * * A relative destination starts from the process's resolved working directory: the caller already stands @@ -299,10 +351,16 @@ function walkParent(destination: string, trust: ScriptDestinationTrust): WalkOut let step = startWalk(spelledParent(destination), trust); // Every step consumes a component, and every link hop counts against a fixed limit, so this ends. for (;;) { - if (step.kind === 'reject') return { reject: refusalAt(destination, step), deepest: '/' }; - if (step.kind === 'stop') return { reject: undefined, deepest: step.deepest }; + if (step.kind === 'reject') { + return { reject: refusalAt(destination, step), deepest: '/', authority: undefined }; + } + if (step.kind === 'stop') { + return { reject: undefined, deepest: step.deepest, authority: step.authority }; + } const { state } = step; - if (state.queue.length === 0) return { reject: undefined, deepest: state.deepest }; + if (state.queue.length === 0) { + return { reject: undefined, deepest: state.deepest, authority: state.authority }; + } step = stepWalk(state, trust); } } @@ -314,13 +372,14 @@ function refusalAt( return scriptAncestryFailure(destination, step.path, step.exposure); } -/** The first state: `/` for an absolute spelling, the resolved working directory otherwise. */ +/** The first state: `/` for an absolute spelling, the resolved working directory for a relative one. */ function startWalk(parent: string, trust: ScriptDestinationTrust): WalkStep { const queue = pathComponents(parent); - // A relative destination starts from the working directory as the kernel sees it, symlink-free: the - // caller already stands there, so it is where the walk starts rather than a step it has to earn. - if (parent !== '' && !path.isAbsolute(parent)) return standIn(path.resolve(''), queue, trust, 0); - return standIn('/', queue, trust, 0); + // The caller already stands in the working directory, so it is where a relative walk starts rather + // than a step it has to earn. `path.resolve('')` answers it the way the kernel sees it. + const ground: WalkGround = { stats: new Map(), judged: new Set() }; + if (!path.isAbsolute(parent)) return standIn(path.resolve(''), queue, trust, 0, ground); + return standIn('/', queue, trust, 0, ground); } /** Judges `directory` and stands the walk there, or refuses it. */ @@ -329,13 +388,29 @@ function standIn( queue: readonly string[], trust: ScriptDestinationTrust, hops: number, + ground: WalkGround, ): WalkStep { - const stats = statDirectoryChain(directory); + const stats = readGround(ground, directory); if (stats === undefined) return { kind: 'reject', path: directory, exposure: 'not_a_directory' }; const authority: DirectoryAuthority = { uid: stats.uid, gid: stats.gid, mode: stats.mode }; - const exposure = untrustedAncestryExposure(authority, trust); - if (exposure) return { kind: 'reject', path: directory, exposure }; - return { kind: 'stand', state: { deepest: directory, authority, queue, hops } }; + // Ground this walk has already judged is safe to stand on again, however it was reached: a `..` back to + // a directory it passed, or an alias of one. A directory's judgment does not depend on the route. + const identity = `${stats.dev}:${stats.ino}`; + if (!ground.judged.has(identity)) { + const exposure = untrustedAncestryExposure(authority, trust); + if (exposure) return { kind: 'reject', path: directory, exposure }; + ground.judged.add(identity); + } + return { kind: 'stand', state: { deepest: directory, authority, queue, hops, ground } }; +} + +/** The `stat` of a directory this walk stands in, read from the host at most once per path. */ +function readGround(ground: WalkGround, directory: string): fs.Stats | undefined { + const known = ground.stats.get(directory); + if (known !== undefined) return known; + const stats = statDirectoryChain(directory); + if (stats !== undefined) ground.stats.set(directory, stats); + return stats; } /** The names of `directory`, with every `.` resolved away the way the kernel resolves it. */ @@ -346,10 +421,14 @@ function pathComponents(directory: string): string[] { /** Advances one component of the queue. */ function stepWalk(state: WalkState, trust: ScriptDestinationTrust): WalkStep { const [component, ...rest] = state.queue; - if (component === undefined) return { kind: 'stop', deepest: state.deepest }; + if (component === undefined) { + return { kind: 'stop', deepest: state.deepest, authority: state.authority }; + } // `..` 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 standIn(path.dirname(state.deepest), rest, trust, state.hops); + if (component === '..') { + return standIn(path.dirname(state.deepest), rest, trust, state.hops, state.ground); + } return stepIntoEntry(state, component, rest, trust); } @@ -361,11 +440,13 @@ function stepIntoEntry( trust: ScriptDestinationTrust, ): WalkStep { const entry = path.join(state.deepest, component); - const stats = lstatIfPresentSync(entry); + const stats = lstatIfPresent(entry); // Nothing below here exists yet, so the publish creates it inside the directory the walk reached. - if (stats === undefined) return { kind: 'stop', deepest: state.deepest }; + if (stats === undefined) { + return { kind: 'stop', deepest: state.deepest, authority: state.authority }; + } if (stats.isSymbolicLink()) return stepThroughLink(state, entry, stats, rest, trust); - return standIn(entry, rest, trust, state.hops); + return standIn(entry, rest, trust, state.hops, state.ground); } /** @@ -386,13 +467,12 @@ function stepThroughLink( return { kind: 'reject', path: link, exposure: 'link_loop_exceeded' }; } const target = fs.readlinkSync(link); - const queue = [ - ...pathComponents(path.isAbsolute(target) ? target : path.join(state.deepest, target)), - ...rest, - ]; - // An absolute target restarts the walk at the root; a relative one continues from where the walk is. - const home = path.isAbsolute(target) ? '/' : state.deepest; - return standIn(home, queue, trust, state.hops + 1); + // 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 standIn(home, [...pathComponents(target), ...rest], trust, state.hops + 1, state.ground); } /** @@ -438,13 +518,18 @@ type NsswitchLine = Readonly<{ database: string; sources: readonly string[] }>; */ export function nameServiceListsOnlyFiles(nsswitch: readonly string[] | undefined): boolean { if (nsswitch === undefined) return false; - for (const database of ['passwd', 'group']) { - const line = nsswitchLine(nsswitch, database); - if (line === undefined) return false; - if (!line.sources.every((source) => source === 'files')) return false; - if (line.sources.length === 0) return false; - } - return true; + const databases = ['passwd', 'group', 'initgroups'].map((database) => + database === 'initgroups' + ? // glibc reads SUPPLEMENTARY membership from `initgroups:`. A line that is absent inherits the + // `group` setting, which is what the kernel does, so the verified `group` line covers it. + (nsswitchLine(nsswitch, 'initgroups') ?? nsswitchLine(nsswitch, 'group')) + : nsswitchLine(nsswitch, database), + ); + return databases.every((line) => line !== undefined && listsOnlyFiles(line)); +} + +function listsOnlyFiles(line: NsswitchLine): boolean { + return line.sources.length > 0 && line.sources.every((source) => source === 'files'); } function nsswitchLine(lines: readonly string[], database: string): NsswitchLine | undefined { @@ -704,17 +789,31 @@ export function untrustedLinkExposure( 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: 'another local user can write that part of the path.', + 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.', + parent_replaced: '', +}; + 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}: another local user owns or can write that part of the path.`, + : `Refusing to save the script under ${ancestor}: ${wording}`, { reason: replaced ? 'script_ancestry_replaced' : 'script_ancestor_untrusted', exposure, @@ -735,16 +834,6 @@ function readSystemFile(file: string): string[] | undefined { } } -/** `lstat` where absence is `undefined`; any other failure propagates. */ -function lstatIfPresentSync(pathname: string): fs.Stats | undefined { - try { - return fs.lstatSync(pathname); - } catch (error) { - if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; - throw error; - } -} - /** `stat` of the directory a path names, or `undefined` when it is absent or is not a directory. */ function statDirectoryChain(pathname: string): fs.Stats | undefined { let stats: fs.Stats | undefined; @@ -767,12 +856,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/remote/src/__tests__/daemon-artifacts-script-download.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts index 7663568bd4..62527445a7 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts @@ -528,6 +528,81 @@ test.skipIf(process.platform === 'win32')( }, ); +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 () => { diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index fc9dac0070..9cffa2f3f2 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -244,6 +244,11 @@ async function publishScriptVersion( * bytes reach it, and reports the destination directory's identity so the publish can confirm it is * still the same one. Refuses an ancestor another local user can write (#4565), so nothing is * downloaded into a directory they control. + * + * Staging sits in the directory the ancestry walk JUDGED, which is the destination's parent as the + * kernel resolves it — not `path.dirname` of the spelled destination. Where a `..` or a link in the + * destination leads elsewhere, the spelled parent is a directory nobody judged, and a staging directory + * in it is a directory another local user can populate before the rename does. */ function allocateStaging( file: string, @@ -251,8 +256,7 @@ function allocateStaging( ): { staging: string; parentIdentity: string | undefined } | undefined { const record = readRecord(file); if (!record) return undefined; - assertPrivateScriptDestination(destination); - const directory = path.dirname(destination); + const directory = assertPrivateScriptDestination(destination); const staging = fs.mkdtempSync(path.join(directory, '.agent-device-script-')); const parentIdentity = publishDirectoryIdentity(directory); try { @@ -357,8 +361,11 @@ function publishStaged( current = withoutStaging(current, record.publishing.staging); } if (revision <= current.revision) return current.destination; - // Re-asked here, under the record lock and right before the entry is created: whoever could write - // an ancestor while the version was downloaded cannot move it now (#4565). + // Re-asked here, under the record lock and right before the entry is created: whoever could write an + // ancestor while the version was downloaded cannot move it now (#4565). The identity handed in was taken + // from the directory the walk judged when staging was created, so a walk that now answers a DIFFERENT + // directory — an ancestor swapped for a link meanwhile — fails the comparison instead of renaming bytes + // into ground nobody judged. assertPrivateScriptDestination(current.destination, parentIdentity); 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. diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 2a39c69f57..a0c4bcf7ab 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -72,9 +72,9 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow - Missing parent directories are created. 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 `..` is applied to the directory the walk actually reached, not to the text you typed: where `work` is a link, `work/../x` lands beside the link's target, and that is the directory judged. Following more links than the system allows is refused rather than trusted. +- 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. The file is written into that same resolved directory, temp file included, so nothing is staged in a directory the check never reached. 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories, and only where `/etc/nsswitch.conf` shows that `/etc/group` and `/etc/passwd` are the whole story: a name service could hold a member those files never show. Every group carrying that group number is considered, so a second group with the same number that lists somebody else closes this exception. +- 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories, and only where `/etc/nsswitch.conf` shows that `/etc/group` and `/etc/passwd` are the whole story for accounts, groups and supplementary groups alike: a name service could hold a member those files never show. Every group carrying that group number is considered, so a second group with the same number that lists somebody else closes this exception. - 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. From 239ad680e316a5ae151a05bc75099fa5da98bf08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 16:00:29 +0100 Subject: [PATCH 12/28] fix(host-kit): name a published temp file by the directory it stands in A script's temp file is created beside the destination AS THE FILESYSTEM RESOLVES IT, because that is the directory the entry is created in. So a destination spelled through a symbolic link -- any scratch path under `/var` on macOS -- has its temp file one directory over in TEXT, and `isAtomicPublishTemporaryPath` compared the two spellings as strings. It stopped recognizing temp files it had produced for its own destination: a fault injected at the write went unclaimed, and the cleanup that names those files left them behind. The two directories are now resolved and compared as directories. `lstatIfPresent` moves from `verified-file.ts` to `atomic-file.ts`, which the verified-file guards already sit behind. Importing it the other way round made 64 top-level statements of eager work load from the daemon's startup path, which the no-growth rule in `eager-closure-budgets` refuses: a module the merge-base tree already had cannot be made eager by a split. Co-Authored-By: Claude Opus 5.5 --- packages/host-kit/src/file.ts | 2 +- .../src/internal/atomic-file-durable.test.ts | 20 ++++++++++ packages/host-kit/src/internal/atomic-file.ts | 40 +++++++++++++++++-- .../host-kit/src/internal/verified-file.ts | 11 +---- 4 files changed, 58 insertions(+), 15 deletions(-) diff --git a/packages/host-kit/src/file.ts b/packages/host-kit/src/file.ts index 8779eccfb5..1dc7e8ef19 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -1,6 +1,7 @@ export { assertPrivateScriptDestination, isAtomicPublishTemporaryPath, + lstatIfPresent, publishDirectoryIdentity, publishDurableFileSync, publishFileSync, @@ -8,7 +9,6 @@ export { type DurableFilePublishMode, } from './internal/atomic-file.ts'; export { - lstatIfPresent, NOT_REGULAR_FILE_HINT, openVerifiedFileForAppend, openVerifiedFileForRead, 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..4f07f69df2 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,26 @@ test('preserves a file fsync error when descriptor cleanup also fails', () => { expect(temporaryPaths(root, destination)).toEqual([]); }); +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.ts b/packages/host-kit/src/internal/atomic-file.ts index 519321ea7a..40aab80bc4 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -3,7 +3,6 @@ import fs from 'node:fs'; import path from 'node:path'; import { AppError } from '@agent-device/kernel/errors'; import { emitDiagnostic } from './diagnostics.ts'; -import { lstatIfPresent } from './verified-file.ts'; export type AtomicPublishMode = 'replace' | 'link-exclusive'; @@ -194,12 +193,45 @@ function syncDirectoryBestEffort(directory: string): void { } } -/** Identifies a temp path produced for a particular destination. */ +/** + * `lstat` that treats absence as `undefined`; every other errno propagates. + * + * Owned here, not in a module of its own, because the publish rule sits on the daemon's startup path: a + * new module on that edge makes eager code every entry that publishes a file pays for today. The + * verified-file guards ask the same question, and this module is on their 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. + * + * 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, so a caller that compared the two spellings as strings would call every + * one of those temp files somebody else's. + */ 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, once the filesystem resolves them. */ +function sameDirectory(left: string, right: string): boolean { + if (left === right) return true; + try { + return fs.realpathSync(left) === fs.realpathSync(right); + } catch { + return false; + } } /** 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; } From 43d436c8c305a504b746eac0c0b7310ec14cf5d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 16:31:30 +0100 Subject: [PATCH 13/28] fix(host-kit): judge a relative destination from the root down `cd /shared/mine` under a `/shared` at 0777 and not sticky, then save a script to `journey.ad`: the destination names no directory, so the walk started IN the working directory, judged it, and never looked above it. `mine` is a name in `/shared`, and anyone who can add an entry there can point it at a directory of their own between the check and the rename -- the swap this rule exists to refuse, reached through the exported publisher. A relative destination is now walked from `/` over the resolved working directory's components with the destination's own components following them raw, so every ancestor is judged. `isAtomicPublishTemporaryPath` resolved the destination's spelling to compare it with the temp file's directory, and a JS path resolution applies a spelled `..` lexically. For `home/work/../y` with `work` a link, that answers `home/y` while the entry is created in `priv/y`, so the real temp sibling was called someone else's and a look-alike beside `home/y` was called ours. Both directories are asked of the filesystem and compared as device and inode. `publishScriptFileSync` no longer takes a `parentIdentity`: it takes the identity from the directory the walk judged, so an outside caller cannot steer what the comparison is against, and only the remote client still passes one, captured before its download. The externally captured identity is tested against `assertPrivateScriptDestination`, which is what compares it. Three writer tests moved the caller's uid, which made the whole scratch tree foreign, so they could not tell a leaf refusal from a root refusal and did not run under root. They now report the ownership of the one directory at issue and assert the ancestor named. The alias test entered through one link and stopped, so it passed with the read cache removed: both names are now traversed, and the walk's own answer is asserted. `atomic-file-ancestry.test.ts` gained enough cases to pass its cap, so the ancestry cases for a remote publication move to `daemon-artifacts-script-ancestry.test.ts`, sharing the client and the fake daemon with the download suite through a support module. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 6 +- .../session-script-writer-ancestry.test.ts | 37 +- .../src/internal/atomic-file-ancestry.test.ts | 102 +++- .../src/internal/atomic-file-durable.test.ts | 25 + packages/host-kit/src/internal/atomic-file.ts | 59 ++- .../daemon-artifacts-script-ancestry.test.ts | 369 ++++++++++++++ .../daemon-artifacts-script-download.test.ts | 478 +----------------- .../support/script-publication-fixtures.ts | 127 +++++ website/docs/docs/replay-e2e.md | 2 +- 9 files changed, 680 insertions(+), 525 deletions(-) create mode 100644 packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts create mode 100644 packages/remote/src/__tests__/support/script-publication-fixtures.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index bf6360d1e9..d555ddf9aa 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -209,12 +209,14 @@ It adds no state name, command, or flag: 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: +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 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. +A RELATIVE destination is walked from `/` too, over the resolved working directory's components with the destination's own components following them raw. Standing the walk in the working directory instead would judge that directory and nothing above it, and the working directory is a name in its parent. +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 destination may name no directory at all, `journey.ad`, so its parent is the working directory: `cd /shared/mine` under a `/shared` at 0777 and not sticky, and the working directory itself is a name another local user can point elsewhere. Judging the working directory alone accepts this; the walk starts at `/` over its components, so `/shared` is judged too. The walk ANSWERS with the physical directory the entry is created in, and the publishers stage inside it. `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. Each physical directory is judged once per walk and each path is read once, so an alias or a `..` back over ground already crossed costs nothing. 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. 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 index 91bdec0d3d..a1c6213342 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -139,41 +139,52 @@ skipOnWindows('a recording refuses a destination under a world-writable director }); 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'); - // The directory is this test user's own, so the rule is run as somebody else: a real second local - // user looking at a directory they cannot own but can read. - vi.spyOn(process, 'getuid').mockReturnValue(currentUid === 65534 ? 65535 : 65534); + serveHostOwnership({ [foreign]: FOREIGN_UID }); const details = refusal(writerFor(directory).write(recordingTo(destination))); - expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'foreign_owned' }); + 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', () => { - const directory = root(); // `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'); - vi.spyOn(process, 'getuid').mockReturnValue(currentUid === 65534 ? 65535 : 65534); + serveHostOwnership({ [team]: FOREIGN_UID }); const details = refusal(writerFor(directory).write(recordingTo(destination))); - expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'foreign_owned' }); + 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', () => { - const directory = root(); // 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. + // 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); @@ -181,11 +192,15 @@ skipOnWindows('a recording refuses a shared directory another user claimed first fs.mkdirSync(recordings); fs.chmodSync(recordings, 0o755); const destination = path.join(recordings, 'journey.ad'); - vi.spyOn(process, 'getuid').mockReturnValue(currentUid === 65534 ? 65535 : 65534); + serveHostOwnership({ [recordings]: FOREIGN_UID }); const details = refusal(writerFor(directory).write(recordingTo(destination))); - expect(details).toMatchObject({ reason: 'script_ancestor_untrusted', exposure: 'foreign_owned' }); + expect(details).toMatchObject({ + reason: 'script_ancestor_untrusted', + exposure: 'foreign_owned', + ancestor: recordings, + }); expect(fs.readdirSync(recordings)).toEqual([]); }); diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index 32e25eeef2..db43771513 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -113,12 +113,8 @@ function directoryWith(directory: string, mode: number, gid = currentGid): strin return directory; } -function publish(destination: string, parentIdentity?: string): void { - publishScriptFileSync({ - destination, - contents: 'context\n', - ...(parentIdentity === undefined ? {} : { parentIdentity }), - }); +function publish(destination: string): void { + publishScriptFileSync({ destination, contents: 'context\n' }); } function expectUntrusted(run: () => void, exposure: string, ancestor: string): void { @@ -423,17 +419,19 @@ skipOnWindows( skipOnWindows('reads each directory it stands in once, however many routes lead back to it', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); - // `a` and `b` are two aliases of the same directory, and the spelling passes through both with a `..` - // between them, so the walk returns over ground it already crossed — the scratch root three times here, - // and the alias's target once for each route. A directory's judgment does not depend on the route taken - // to it, so each path is read once and each physical directory is judged once. + // `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, and the reads would not include `sub` twice as a path. A directory's judgment + // does not depend on the route taken to it, so each path is read once per walk and each physical + // directory is judged once. const directory = root(); const home = directoryWith(path.join(directory, 'home'), 0o700); - const target = directoryWith(path.join(directory, 'target'), 0o700); - const sub = path.join(target, 'sub'); - fs.mkdirSync(sub); - fs.symlinkSync(target, path.join(home, 'a')); - fs.symlinkSync(target, path.join(home, 'b')); + 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 reads: string[] = []; const realStatSync = fs.statSync; vi.spyOn(fs, 'statSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { @@ -441,9 +439,13 @@ skipOnWindows('reads each directory it stands in once, however many routes lead return (realStatSync as (...args: unknown[]) => unknown)(pathname, ...rest); }) as typeof fs.statSync); - assertPrivateScriptDestination(`${home}/a/../b/sub/journey.ad`); + expect(assertPrivateScriptDestination(`${home}/a/../b/below/journey.ad`)).toBe(below); + // The shared prefix, `home`, `sub` and `below`: no path is read a second time, so neither is the ground + // the two aliases share judged a second time. expect(new Set(reads).size).toBe(reads.length); + expect(reads.filter((read) => read === sub)).toHaveLength(1); + expect(reads.filter((read) => read === home)).toHaveLength(1); }); skipOnWindows('starts a destination with no directory in it at the working directory', () => { @@ -458,6 +460,49 @@ skipOnWindows('starts a destination with no directory in it at the working direc expect(assertPrivateScriptDestination('journey.ad', identity)).toBe(cwd); }); +skipOnWindows( + 'refuses a relative destination whose working directory sits in shared ground', + () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // `cd /shared/mine && publish journey.ad` where `/shared` is 0777 and NOT sticky. The destination names + // no directory at all, so the tempting answer is to start the walk in the working directory and judge + // it. That judges `mine` and nothing above it, and `mine` is a name in `/shared`: anyone who can add an + // entry there can point `mine` at a directory of their own before the rename, which is the swap this + // rule exists to refuse. So a relative destination is walked from the root, over the working + // directory's own components, and `/shared` is judged like any other ancestor. + const directory = root(); + const shared = directoryWith(path.join(directory, 'shared'), 0o777); + const mine = directoryWith(path.join(shared, 'mine'), 0o700); + const previous = path.resolve(''); + try { + process.chdir(mine); + + expectUntrusted(() => assertPrivateScriptDestination('journey.ad'), 'world_writable', shared); + expect(fs.readdirSync(mine)).toEqual([]); + } finally { + process.chdir(previous); + } + }, +); + +skipOnWindows('answers the working directory for a relative destination over a safe chain', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // The same shape with every ancestor private: the answer is the ABSOLUTE working directory, which is + // what the publisher stages in, and the identity a caller captured for `.` matches it. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const mine = directoryWith(path.join(home, 'mine'), 0o700); + const previous = path.resolve(''); + try { + process.chdir(mine); + const identity = publishDirectoryIdentity('.'); + + expect(assertPrivateScriptDestination('journey.ad', identity)).toBe(mine); + } finally { + process.chdir(previous); + } +}); + skipOnWindows('refuses a relative target that lands in ground others can write', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); // The target names a plain name, and the directory it names is open to others. Spelling that directory @@ -865,6 +910,11 @@ skipOnWindows('publishes to a scratch path exactly as the host spelled it', () = // --- the destination directory swapped out while the file was staged --- +// The identity a caller captures before it stages something is handed back to +// `assertPrivateScriptDestination`, which is what compares them. The script publisher takes it from the +// directory the walk judged, so only a caller who captured it EARLIER — the remote client, across a +// download — passes one from outside. These two are that comparison. + skipOnWindows('refuses a parent replaced by name while the file was staged', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); @@ -882,8 +932,11 @@ skipOnWindows('refuses a parent replaced by name while the file was 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(() => publish(destination, parentIdentity), elsewhere); - expect(fs.readdirSync(elsewhere)).toEqual([]); + expectUntrustedReplaced( + () => assertPrivateScriptDestination(destination, parentIdentity), + elsewhere, + ); + expect(fs.existsSync(path.join(elsewhere, 'journey.ad'))).toBe(false); }); skipOnWindows('re-checks the chain after staging the file, before the entry is created', () => { @@ -908,12 +961,15 @@ skipOnWindows('re-checks the chain after staging the file, before the entry is c expect(fs.readdirSync(attacker)).toEqual([]); }); -skipOnWindows('publishes into the parent the captured identity still names', () => { +skipOnWindows('accepts the identity a caller captured for the directory the walk answers', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); - const staged = path.join(root(), 'work'); + const directory = root(); + const staged = path.join(directory, 'work'); fs.mkdirSync(staged); + const destination = path.join(staged, 'journey.ad'); - publish(path.join(staged, 'journey.ad'), publishDirectoryIdentity(staged)); - - expect(fs.existsSync(path.join(staged, 'journey.ad'))).toBe(true); + expect(assertPrivateScriptDestination(destination, publishDirectoryIdentity(staged))).toBe( + staged, + ); + expect(assertPrivateScriptDestination(destination)).toBe(staged); }); 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 4f07f69df2..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,31 @@ 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 diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index 40aab80bc4..b7fe7cb4c3 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -57,7 +57,6 @@ export function publishScriptFileSync(options: { destination: string; contents: string; publish?: AtomicPublishMode; - parentIdentity?: string; }): void { // The directory the entry is created in is the walk's ANSWER, asked for inside this call and twice: // never `path.dirname` of the spelled destination, because a `..` or a link in the destination sends the @@ -66,7 +65,7 @@ export function publishScriptFileSync(options: { let temporaryPath: string | undefined; try { const judged = assertPrivateScriptDestination(options.destination); - const expected = options.parentIdentity ?? publishDirectoryIdentity(judged); + const expected = publishDirectoryIdentity(judged); temporaryPath = createAtomicPublishTempPath(judged, options.destination); fs.writeFileSync(temporaryPath, options.contents, { encoding: 'utf8', mode: SCRIPT_FILE_MODE }); const stillJudged = assertPrivateScriptDestination(options.destination, expected); @@ -212,10 +211,12 @@ export function lstatIfPresent(pathname: string): fs.Stats | undefined { /** * Identifies a temp path produced for a particular destination. * - * 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, so a caller that compared the two spellings as strings would call every - * one of those temp files somebody else's. + * 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 directories are therefore asked of the filesystem and + * compared as device and inode. `lstat` or `realpathSync` would apply a spelled `..` textually and answer + * the wrong one, which rejects the real temp sibling and accepts a look-alike planted beside the + * directory the text names. */ export function isAtomicPublishTemporaryPath(value: unknown, destination: string): boolean { if (typeof value !== 'string') return false; @@ -224,13 +225,22 @@ export function isAtomicPublishTemporaryPath(value: unknown, destination: string return sameDirectory(path.dirname(value), path.dirname(destination)); } -/** Whether two directory spellings name one directory, once the filesystem resolves them. */ +/** 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.realpathSync(left) === fs.realpathSync(right); + return fs.statSync(pathname); } catch { - return false; + return undefined; } } @@ -302,15 +312,24 @@ export function assertPrivateScriptDestination( } /** - * The parent of `destination`, cut at its last separator and never normalized. + * The parent of `destination` as a chain of components from the root, never normalized. * * `path.resolve` folds a `..` away, which is the one simplification this may not make: the kernel does * not make it either, so `.../work/../x` lands its entry beside the target of the link named `work`. The - * spelled components are what the walk resolves. A destination with no directory in it, `journey.ad`, - * has the working directory as its parent, which `path.dirname` already answers as `.`. + * spelled components are what the walk resolves. + * + * A RELATIVE destination is resolved against the working directory, but it is not made absolute by + * joining the two: the working directory's OWN components are queued first and the destination's follow + * them raw. Standing the walk in the cwd instead would judge the cwd and nothing above it, and a caller + * who cannot write `/shared` can still swap the `/shared/mine` the cwd names, which is the entry this + * rule exists to refuse. `path.resolve('')` answers the cwd the way the kernel sees it. */ -function spelledParent(destination: string): string { - return path.dirname(destination); +function absoluteParent(destination: string): string { + const parent = path.dirname(destination); + if (path.isAbsolute(parent)) return parent; + // `path.resolve('')` is the cwd; `path.dirname` of it is its parent, and the components of both, in + // order, are what the walk has to walk. `path.resolve(destination)` must NOT be used: it folds. + return `${path.resolve('')}/${parent === '.' ? '' : parent}`; } /** @@ -376,11 +395,12 @@ type WalkOutcome = Readonly<{ * {@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. * - * A relative destination starts from the process's resolved working directory: the caller already stands - * there, and the walk cannot step above it. + * A relative destination is walked from the root too, over the resolved working directory's components + * first: the caller stands in the working directory, but that directory is still a name in its parent, + * and the parent is judged like any other. */ function walkParent(destination: string, trust: ScriptDestinationTrust): WalkOutcome { - let step = startWalk(spelledParent(destination), trust); + let step = startWalk(absoluteParent(destination), trust); // Every step consumes a component, and every link hop counts against a fixed limit, so this ends. for (;;) { if (step.kind === 'reject') { @@ -404,13 +424,10 @@ function refusalAt( return scriptAncestryFailure(destination, step.path, step.exposure); } -/** The first state: `/` for an absolute spelling, the resolved working directory for a relative one. */ +/** The first state: the root, with every component of the parent still to resolve. */ function startWalk(parent: string, trust: ScriptDestinationTrust): WalkStep { const queue = pathComponents(parent); - // The caller already stands in the working directory, so it is where a relative walk starts rather - // than a step it has to earn. `path.resolve('')` answers it the way the kernel sees it. const ground: WalkGround = { stats: new Map(), judged: new Set() }; - if (!path.isAbsolute(parent)) return standIn(path.resolve(''), queue, trust, 0, ground); return standIn('/', queue, trust, 0, ground); } 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..ceb4f40149 --- /dev/null +++ b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts @@ -0,0 +1,369 @@ +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 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 62527445a7..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,63 +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 { - FOREIGN_UID, - closeLoopbackServer, - createTestHostEnvironment, - listenOnLoopback, - mkdtempForTestSync, - serveHostOwnership, -} 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-')); @@ -65,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({ @@ -114,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' } }); @@ -467,361 +366,6 @@ test.skipIf(process.platform === 'win32' || process.getuid?.() === 0).each([ }, ); -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 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([]); - }, -); - test('retiring a record removes the staging a crashed download left behind', 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/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index a0c4bcf7ab..754859422b 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -72,7 +72,7 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow - Missing parent directories are created. 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. The file is written into that same resolved directory, temp file included, so nothing is staged in a directory the check never reached. Following more links than the system allows is refused rather than trusted. +- 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 name such as `journey.ad` is checked the same way, from the root down through your working directory, 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. 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories, and only where `/etc/nsswitch.conf` shows that `/etc/group` and `/etc/passwd` are the whole story for accounts, groups and supplementary groups alike: a name service could hold a member those files never show. Every group carrying that group number is considered, so a second group with the same number that lists somebody else closes this exception. - 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. From 844021334f3a61422935737762960420dbb5bd29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 17:25:14 +0100 Subject: [PATCH 14/28] fix(host-kit): judge a script destination before creating its parent Both routes created the missing parent before the ancestry rule was asked, so a destination under a world-writable directory left the directories its `mkdir -p` made standing in that shared ground, even though the publish that followed was refused. The same walk now runs over the prefix that already exists, refuses, and runs again after the `mkdir` once the directory the entry lands in exists. Only the second question asks whether others could create the name inside it, because below the first question the directories are the caller's own to create: that is what keeps `mkdir -p /recordings` acceptable. A relative destination walked the working directory Node remembers, which is the path the first query after `chdir` returned. Move that directory and put another at its old path and the walk judges a directory the process is not in, while the kernel resolves the destination in the moved one. The remembered spelling is confirmed against `.` by `dev:ino`, and the entry is created in the directory the walk answered rather than by handing the kernel the destination back. `ground.judged` is gone: the once-per-inode judgment it held could be deleted with every test green, and only the per-path `stat` cache is observable. The hop test stopped deriving its inputs from the production constant, which let a limit of 29 pass as 30, and now builds a 30-link chain and a 31-link chain. Two tests that made a destination directory `0500` now fail the staging write directly: mode bits do not bind root, so those two reported the host's permission model instead of the writer's error handling under a root caller. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 7 +- .../support/script-staging-failure.ts | 27 +++ .../session-script-writer-ancestry.test.ts | 20 ++ .../__tests__/session-script-writer.test.ts | 18 +- .../daemon/src/core/session-script-writer.ts | 9 +- .../__tests__/session-close-script.test.ts | 13 +- packages/host-kit/src/file.ts | 1 + .../src/internal/atomic-file-ancestry.test.ts | 218 ++++++++---------- .../src/internal/atomic-file-host.fixtures.ts | 119 ++++++++++ packages/host-kit/src/internal/atomic-file.ts | 100 ++++++-- .../daemon-artifacts-script-ancestry.test.ts | 30 +++ .../remote/src/session-script-destination.ts | 9 +- website/docs/docs/replay-e2e.md | 2 +- 13 files changed, 407 insertions(+), 166 deletions(-) create mode 100644 packages/daemon/src/__tests__/support/script-staging-failure.ts create mode 100644 packages/host-kit/src/internal/atomic-file-host.fixtures.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index d555ddf9aa..d959c1cf79 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -207,17 +207,18 @@ 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 (#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. +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 directories that already exist are judged before that `mkdir` runs, so a destination the rule refuses leaves no directories behind. 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 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. -A RELATIVE destination is walked from `/` too, over the resolved working directory's components with the destination's own components following them raw. Standing the walk in the working directory instead would judge that directory and nothing above it, and the working directory is a name in its parent. +Because the walk ends at the first component that does not exist, a caller that creates missing parents asks the same walk twice: once over the prefix that is already there, before the `mkdir`, and once after it, when the directory the entry lands in exists. Only the second question includes whether other local users could add a name inside that directory, because below the first question the directories are the caller's own to create, at its own mode. Deferring it is what keeps `mkdir -p /recordings` acceptable. +A RELATIVE destination is walked from `/` too, over the resolved working directory's components with the destination's own components following them raw. Standing the walk in the working directory instead would judge that directory and nothing above it, and the working directory is a name in its parent. That spelling is confirmed to be the directory the process stands in, by `dev:ino` against `.`: Node answers the working directory with the path the first query after `chdir` returned, so the name goes stale when the directory it names is moved, and a walk of the stale name judges a directory the process is not in while the kernel resolves the destination in the moved one. 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 destination may name no directory at all, `journey.ad`, so its parent is the working directory: `cd /shared/mine` under a `/shared` at 0777 and not sticky, and the working directory itself is a name another local user can point elsewhere. Judging the working directory alone accepts this; the walk starts at `/` over its components, so `/shared` is judged too. -The walk ANSWERS with the physical directory the entry is created in, and the publishers stage inside it. `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. Each physical directory is judged once per walk and each path is read once, so an alias or a `..` back over ground already crossed costs nothing. +The walk ANSWERS with the physical directory the entry is created in, and the publishers stage inside it AND create the entry inside it, spelled from it. `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. Each path is read from the host once per walk, so an alias or a `..` back over ground already crossed does not ask the host again. 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 `passwd`, for `group`, and for `initgroups` — the database glibc reads SUPPLEMENTARY membership from, which those two files say nothing about. An absent `initgroups:` line inherits the verified `group` setting, as the kernel does. `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. 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 index a1c6213342..d6f703404a 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -138,6 +138,26 @@ skipOnWindows('a recording refuses a destination under a world-writable director 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 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 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 7d0ae670d3..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,12 +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); - // A directory this user owns but cannot write: the ancestry rule has nothing to refuse there, so the - // failure the caller sees is the filesystem's own, not an ancestry verdict. - const blocker = path.join(root, 'blocker'); - fs.mkdirSync(blocker); - fs.chmodSync(blocker, 0o500); - 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/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index 2b6c6fa541..164d6dc23c 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -19,7 +19,10 @@ import { stripRecordedRefGeneration, } from '@agent-device/ad-script'; import { expandSessionPath, safeSessionName } from '@agent-device/host-kit/session-paths'; -import { publishScriptFileSync } from '@agent-device/host-kit/file'; +import { + assertPrivateScriptDestinationPrefix, + publishScriptFileSync, +} from '@agent-device/host-kit/file'; import type { SessionState } from './session-state.ts'; import { NO_SCRIPT_PUBLICATION, @@ -134,6 +137,10 @@ export class SessionScriptWriter { session.scriptPublication?.kind === 'authoring' && session.scriptPublication.remoteDelivery; scriptPath = remote ? this.remoteScriptPath() : this.resolveScriptPath(session); const scriptDir = path.dirname(scriptPath); + // Asked BEFORE the parent is created, and again by the publisher once it exists: a `mkdir -p` into + // ground another local user can write would otherwise leave the directories it made behind them, + // even though the publish that follows is refused (#4565). + assertPrivateScriptDestinationPrefix(scriptPath); if (!fs.existsSync(scriptDir)) fs.mkdirSync(scriptDir, { recursive: true }); // #1258: `options.force` is the caller's already-merged decision // (`effectiveWriteForce` — a live flag or the per-target grant), not 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 42466b9f80..dfae250f43 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 @@ -16,6 +16,7 @@ import { } from '../session-close-script.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[] = []; @@ -195,12 +196,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 directory this user owns but cannot write: publishing into it fails with EACCES, and the ancestry - // rule has nothing to refuse there, so the caller sees the filesystem's own failure. - const blocker = path.join(root, 'blocker'); - fs.mkdirSync(blocker); - fs.chmodSync(blocker, 0o500); - 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/host-kit/src/file.ts b/packages/host-kit/src/file.ts index 1dc7e8ef19..f49c06a68b 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -1,5 +1,6 @@ export { assertPrivateScriptDestination, + assertPrivateScriptDestinationPrefix, isAtomicPublishTemporaryPath, lstatIfPresent, publishDirectoryIdentity, diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index db43771513..2a71e4e509 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -1,82 +1,35 @@ 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 { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; +import { + FOREIGN_UID, + ancestryRoot as root, + currentGid, + directoryWith, + expectUntrusted, + expectUntrustedReplaced, + hostDatabase, + modeOf, + publish, + serveGroupDatabase, + unreadableDatabases, +} from './atomic-file-host.fixtures.ts'; import { assertPrivateScriptDestination, publishDirectoryIdentity, - publishScriptFileSync, MAX_SCRIPT_PATH_LINK_HOPS, } from './atomic-file.ts'; +import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; const skipOnWindows = process.platform === 'win32' ? test.skip : test; -/** The group database a test stands in for `/etc/group` and `/etc/passwd`. */ -type Database = Readonly<{ - groups: readonly string[] | undefined; - passwd: readonly string[] | undefined; - /** `undefined` means "only files"; an empty array means "the file cannot be read". */ - nsswitch?: readonly string[] | undefined; -}>; - -const realReadFileSync = fs.readFileSync; -/** - * The account the fixture's databases name for this process. `readCurrentUser()` reads it from - * `passwdFile` below, so the fixture and the rule agree without a second host lookup. - */ -const currentUser = process.env.USER ?? ''; -/** The unmocked `stat` calls, so a second fixture here never wraps the first one's mock. */ -const realLstatSync = fs.lstatSync.bind(fs); -const realStatSync = fs.statSync.bind(fs); - -/** 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(); }); -/** - * Serves `database` for the two group files and the real host for everything else, so the - * private-group decision is the fixture's and not the CI image's user list. - */ -function serveGroupDatabase(database: Database): void { - vi.spyOn(fs, 'readFileSync').mockImplementation(((file: unknown, options?: unknown) => { - if (file === '/etc/group') { - if (!database.groups) throw new Error('simulated unreadable group file'); - return `${database.groups.join('\n')}\n`; - } - if (file === '/etc/passwd') { - if (!database.passwd) throw new Error('simulated unreadable passwd file'); - return `${database.passwd.join('\n')}\n`; - } - if (file === '/etc/nsswitch.conf') return nsswitchContents(database.nsswitch); - return realReadFileSync(file as never, options as never) as never; - }) as typeof fs.readFileSync); -} - -/** The name-service lines of the fixture host: `files` only, unless the test asks for more. */ -function nsswitchContents(sources: readonly string[] | undefined): string { - if (sources === undefined) return 'passwd: files\ngroup: files\n'; - if (sources.length === 0) throw new Error('simulated unreadable nsswitch.conf'); - return `${sources.join('\n')}\n`; -} - -/** This host's user with a group of their own, and a team group that holds someone else. */ -function hostDatabase(privateGid: number, sharedGid: number): Database { - return { - groups: ['root:x:0:root', `${currentUser}:x:${privateGid}:`, `team:x:${sharedGid}:ada`], - passwd: [`root:x:0:0`, `${currentUser}:x:${currentUid}:${privateGid}:`], - nsswitch: undefined, - }; -} - -/** The database of a host whose group files cannot be read at all. */ -function unreadableDatabases(): Database { - return { groups: undefined, passwd: undefined }; -} +/** 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 @@ -95,51 +48,6 @@ function serveOwnership(owners: Readonly>): void { withUid(realStatSync(pathname, ...rest), String(pathname))) as typeof fs.statSync); } -/** Some other local user, not this one and not root. */ -const FOREIGN_UID = 65534; - -function root(): string { - return fs.realpathSync(mkdtempForTestSync('host-kit-ancestry-')); -} - -/** - * A directory carrying `mode` and `gid`, so the rule reads the group the test chose. The group is set - * explicitly because a scratch directory inherits one from its parent, not necessarily this user's. - */ -function directoryWith(directory: string, mode: number, gid = currentGid): string { - fs.mkdirSync(directory); - fs.chownSync(directory, currentUid, gid); - fs.chmodSync(directory, mode); - return directory; -} - -function publish(destination: string): void { - publishScriptFileSync({ destination, contents: 'context\n' }); -} - -function expectUntrusted(run: () => void, exposure: string, ancestor: string): void { - expectRefusal(run, 'script_ancestor_untrusted', exposure, ancestor); -} - -function expectUntrustedReplaced(run: () => void, ancestor: string): void { - expectRefusal(run, 'script_ancestry_replaced', 'parent_replaced', ancestor); -} - -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 }); -} - -function modeOf(pathname: string): number { - return fs.lstatSync(pathname).mode & 0o777; -} - // --- a directory another user owns, or that others can write, is refused --- skipOnWindows('publishes to a chain only this user can write', () => { @@ -422,9 +330,8 @@ skipOnWindows('reads each directory it stands in once, however many routes lead // `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, and the reads would not include `sub` twice as a path. A directory's judgment - // does not depend on the route taken to it, so each path is read once per walk and each physical - // directory is judged once. + // `home` here instead. Each path is read from the host once per walk, so ground come back to by a `..` + // or by an alias of it is not asked for a second time. const directory = root(); const home = directoryWith(path.join(directory, 'home'), 0o700); const sub = directoryWith(path.join(home, 'sub'), 0o700); @@ -441,8 +348,8 @@ skipOnWindows('reads each directory it stands in once, however many routes lead expect(assertPrivateScriptDestination(`${home}/a/../b/below/journey.ad`)).toBe(below); - // The shared prefix, `home`, `sub` and `below`: no path is read a second time, so neither is the ground - // the two aliases share judged a second time. + // The shared prefix, `home`, `sub` and `below`: no path is read a second time, including the one the + // two aliases both name. expect(new Set(reads).size).toBe(reads.length); expect(reads.filter((read) => read === sub)).toHaveLength(1); expect(reads.filter((read) => read === home)).toHaveLength(1); @@ -477,7 +384,7 @@ skipOnWindows( try { process.chdir(mine); - expectUntrusted(() => assertPrivateScriptDestination('journey.ad'), 'world_writable', shared); + expectUntrusted(() => publish('journey.ad'), 'world_writable', shared); expect(fs.readdirSync(mine)).toEqual([]); } finally { process.chdir(previous); @@ -503,6 +410,70 @@ skipOnWindows('answers the working directory for a relative destination over a s } }); +skipOnWindows( + 'refuses a relative destination whose working directory has been moved out from under it', + () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // Node answers the working directory with the path getcwd handed it the first time anything asked, so + // that spelling goes stale the moment the directory it names is moved — the process keeps working, and + // only the two answers disagree. `cd `, ASK the working directory (which is what settling the + // cache means, and what any caller that resolves a path does), then move `` and plant another + // private directory at its old path. A walk of the remembered spelling judges the planted directory, + // finds it publishable, and stages in it; the kernel then resolves `journey.ad` in the MOVED one, so + // the entry is created in ground the rule never reached. Comparing the remembered spelling with `.` is + // what refuses this, and publishing through the judged directory is what would stop the entry moving + // even if the comparison were skipped. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const mine = directoryWith(path.join(home, 'mine'), 0o700); + const previous = process.cwd(); + try { + process.chdir(mine); + const remembered = path.resolve(''); + const moved = path.join(home, 'moved'); + fs.renameSync(mine, moved); + directoryWith(mine, 0o700); + // The attacker's directory is the one the process is really in: open to everyone, and owned by this + // user, so nothing about it looks untrusted from the inside. + fs.chmodSync(moved, 0o777); + + expectUntrustedReplaced(() => publish('journey.ad'), remembered); + expect(fs.readdirSync(mine)).toEqual([]); + expect(fs.readdirSync(moved)).toEqual([]); + } finally { + process.chdir(previous); + } + }, +); + +skipOnWindows('publishes a relative destination into the working directory it judged', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // Nothing is refused here: the working directory is where the process stands, so the spelling the walk + // judged and the directory the kernel resolves are one directory. The entry is still created IN THAT + // DIRECTORY, spelled from it, and not by handing the kernel the relative destination back: the answer + // the walk gave is the one thing this call knows about where the bytes belong, and a relative name asks + // the kernel to answer the question a second time, from whatever the working directory is by then. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const mine = directoryWith(path.join(home, 'mine'), 0o700); + const published: string[] = []; + const realRenameSync = fs.renameSync; + vi.spyOn(fs, 'renameSync').mockImplementation(((existing: unknown, newPath: unknown) => { + published.push(String(newPath)); + return (realRenameSync as (...args: unknown[]) => unknown)(existing, newPath); + }) as typeof fs.renameSync); + const previous = process.cwd(); + try { + process.chdir(mine); + publish('journey.ad'); + } finally { + process.chdir(previous); + } + + expect(published).toEqual([path.join(mine, 'journey.ad')]); + expect(fs.readdirSync(mine)).toEqual(['journey.ad']); +}); + skipOnWindows('refuses a relative target that lands in ground others can write', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); // The target names a plain name, and the directory it names is open to others. Spelling that directory @@ -657,12 +628,17 @@ skipOnWindows('refuses a link loop instead of trusting where the walk ran out', expect(fs.readdirSync(work)).toEqual(['loop']); }); -skipOnWindows('follows exactly as many link hops as the walk allows, and refuses one more', () => { +skipOnWindows('follows thirty link hops, and refuses the thirty-first', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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 -> ... -> `, so the walk expands `count` links to reach the destination. + // `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) { @@ -674,17 +650,17 @@ skipOnWindows('follows exactly as many link hops as the walk allows, and refuses return next; }; - publish(path.join(chain(MAX_SCRIPT_PATH_LINK_HOPS), 'journey.ad')); + 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( - () => - assertPrivateScriptDestination(path.join(chain(MAX_SCRIPT_PATH_LINK_HOPS + 1), 'journey.ad')), + () => assertPrivateScriptDestination(path.join(chain(31), 'journey.ad')), 'link_loop_exceeded', - path.join(work, `link${MAX_SCRIPT_PATH_LINK_HOPS}`), + 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', () => { 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..45b8b26fcb --- /dev/null +++ b/packages/host-kit/src/internal/atomic-file-host.fixtures.ts @@ -0,0 +1,119 @@ +// The host this suite's destinations are judged against: a group and passwd database the test names, +// directory owners the 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 those two alone is asserting against whatever +// accounts and modes the machine it runs on happens to have. + +import { expect, vi } 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'; + +/** The group database a test stands in for `/etc/group` and `/etc/passwd`. */ +export type Database = Readonly<{ + groups: readonly string[] | undefined; + passwd: readonly string[] | undefined; + /** `undefined` means "only files"; an empty array means "the file cannot be read". */ + nsswitch?: readonly string[] | undefined; +}>; + +const realReadFileSync = fs.readFileSync; + +/** + * The account the fixture's databases name for this process. `readCurrentUser()` reads it from + * `passwdFile` below, so the fixture and the rule agree without a second host lookup. + */ +export const currentUser = process.env.USER ?? ''; + +/** This process's ids. Windows has neither, and every test that uses them is skipped there. */ +export const currentUid = process.getuid?.() ?? -1; +export const currentGid = process.getgid?.() ?? -1; + +/** + * Serves `database` for the two group files and the real host for everything else, so the + * private-group decision is the fixture's and not the CI image's user list. + */ +export function serveGroupDatabase(database: Database): void { + vi.spyOn(fs, 'readFileSync').mockImplementation(((file: unknown, options?: unknown) => { + if (file === '/etc/group') { + if (!database.groups) throw new Error('simulated unreadable group file'); + return `${database.groups.join('\n')}\n`; + } + if (file === '/etc/passwd') { + if (!database.passwd) throw new Error('simulated unreadable passwd file'); + return `${database.passwd.join('\n')}\n`; + } + if (file === '/etc/nsswitch.conf') return nsswitchContents(database.nsswitch); + return realReadFileSync(file as never, options as never) as never; + }) as typeof fs.readFileSync); +} + +/** The name-service lines of the fixture host: `files` only, unless the test asks for more. */ +function nsswitchContents(sources: readonly string[] | undefined): string { + if (sources === undefined) return 'passwd: files\ngroup: files\n'; + if (sources.length === 0) throw new Error('simulated unreadable nsswitch.conf'); + return `${sources.join('\n')}\n`; +} + +/** This host's user with a group of their own, and a team group that holds someone else. */ +export function hostDatabase(privateGid: number, sharedGid: number): Database { + return { + groups: ['root:x:0:root', `${currentUser}:x:${privateGid}:`, `team:x:${sharedGid}:ada`], + passwd: [`root:x:0:0`, `${currentUser}:x:${currentUid}:${privateGid}:`], + nsswitch: undefined, + }; +} + +/** The database of a host whose group files cannot be read at all. */ +export function unreadableDatabases(): Database { + return { groups: undefined, passwd: undefined }; +} + +/** 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` and `gid`, so the rule reads the group the test chose. The group is set + * explicitly because a scratch directory inherits one from its parent, not necessarily this user's. + */ +export function directoryWith(directory: string, mode: number, gid = currentGid): string { + fs.mkdirSync(directory); + fs.chownSync(directory, currentUid, gid); + 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' }); +} + +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.ts b/packages/host-kit/src/internal/atomic-file.ts index b7fe7cb4c3..5ecc43a608 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -72,10 +72,15 @@ export function publishScriptFileSync(options: { if (stillJudged !== judged) { throw scriptAncestryFailure(options.destination, stillJudged, 'parent_replaced'); } + // The entry is created in the directory the walk ANSWERED, spelled from it, and never through the + // destination's own spelling: the kernel resolves a relative destination against the process's + // working directory and a spelled `..` against the directories on the way there, so a spelling that + // has drifted from the judged one would 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, options.destination); + fs.linkSync(temporaryPath, entry); } else { - fs.renameSync(temporaryPath, options.destination); + fs.renameSync(temporaryPath, entry); } } finally { removeTempBestEffort(options.destination, temporaryPath); @@ -311,6 +316,26 @@ export function assertPrivateScriptDestination( return walk.deepest; } +/** + * Refuses a script destination whose ALREADY-EXISTING directories another local user can steer, before + * anything is created on the way to it. Callers that create a missing parent run this first, then create, + * then run {@link assertPrivateScriptDestination} once the directory the entry lands in exists. + * + * It is the same walk, not a second rule: the walk stops at the first component that does not exist, so + * asking it before the `mkdir` judges exactly the prefix that is already there. What is NOT asked here is + * the creation question — whether other local users could add a name inside the directory the walk ends in + * — because the directories below are the caller's own to create, at its own mode. Deferring it is what + * keeps `mkdir -p /recordings` acceptable on both routes. + * + * The refusal is the same typed error the full rule raises, so a caller sees one reason for one shape of + * path whichever of the two asked it. + */ +export function assertPrivateScriptDestinationPrefix(destination: string): void { + if (process.platform === 'win32') return; + const walk = walkParent(destination, readScriptTrust()); + if (walk.reject !== undefined) throw walk.reject; +} + /** * The parent of `destination` as a chain of components from the root, never normalized. * @@ -322,14 +347,45 @@ export function assertPrivateScriptDestination( * joining the two: the working directory's OWN components are queued first and the destination's follow * them raw. Standing the walk in the cwd instead would judge the cwd and nothing above it, and a caller * who cannot write `/shared` can still swap the `/shared/mine` the cwd names, which is the entry this - * rule exists to refuse. `path.resolve('')` answers the cwd the way the kernel sees it. + * rule exists to refuse. The working directory's name is first confirmed to be where the process really + * stands ({@link standsIn}), because that name is what the walk queues. */ -function absoluteParent(destination: string): string { +function absoluteParent(destination: string): WalkStart { const parent = path.dirname(destination); - if (path.isAbsolute(parent)) return parent; - // `path.resolve('')` is the cwd; `path.dirname` of it is its parent, and the components of both, in + if (path.isAbsolute(parent)) return { pathname: parent }; + // `path.resolve('')` is the working directory; its components and the destination's own parent, in // order, are what the walk has to walk. `path.resolve(destination)` must NOT be used: it folds. - return `${path.resolve('')}/${parent === '.' ? '' : parent}`; + const cwd = path.resolve(''); + if (!standsIn(cwd)) return { reject: { path: cwd, exposure: 'parent_replaced' } }; + return { pathname: `${cwd}/${parent === '.' ? '' : parent}` }; +} + +/** The spelling to start a walk from, or the refusal that stops it before the first component. */ +type WalkStart = + | Readonly<{ pathname: string; reject?: undefined }> + | Readonly<{ + reject: Readonly<{ path: string; exposure: ScriptAncestryExposure }>; + pathname?: undefined; + }>; + +/** + * Whether the process really stands in the directory `pathname` names as its working directory. + * + * Node answers the working directory from the last `chdir` it made, so its NAME can be stale while the + * process is unbothered: move the directory the name points at and put another one at that path, and a + * walk of the name judges the replacement while the kernel resolves every relative name in the moved one. + * The two are therefore asked of the filesystem and compared as device and inode, the one answer that + * makes both names mean the same directory. + */ +function standsIn(pathname: string): boolean { + const remembered = statOrNull(pathname); + const standing = statOrNull('.'); + return ( + remembered !== undefined && + standing !== undefined && + remembered.dev === standing.dev && + remembered.ino === standing.ino + ); } /** @@ -348,14 +404,12 @@ type WalkState = Readonly<{ }>; /** - * One walk's memory of the ground it has stood on: the modes it has read, keyed by path, and the - * directories whose judgment it already has, keyed by device and inode. A path that comes back around, - * through a `..` or through an alias of a directory already entered, is therefore asked of the host once, - * and one walk sees the host the same way throughout. + * One walk's memory of the ground it has stood on: the `stat` of every path it has read, keyed by that + * path. A path that comes back around, through a `..` or through an alias of a directory already entered, + * is therefore asked of the host once, and one walk sees the host the same way throughout. */ type WalkGround = Readonly<{ stats: Map; - judged: Set; }>; type WalkStep = @@ -387,8 +441,8 @@ type WalkOutcome = Readonly<{ * any other directory. Neither one is a name that has to exist. * - Any other component is lstat'ed in that directory. An absent component ends the walk, because the * publish creates what is missing below here. - * - A directory is judged and entered. Each physical directory is judged once and each path is read from - * the host once per walk, so a `..` back over ground already crossed, or an alias of it, costs nothing. + * - 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 @@ -400,7 +454,11 @@ type WalkOutcome = Readonly<{ * and the parent is judged like any other. */ function walkParent(destination: string, trust: ScriptDestinationTrust): WalkOutcome { - let step = startWalk(absoluteParent(destination), trust); + const start = absoluteParent(destination); + if (start.reject !== undefined) { + return { reject: refusalAt(destination, start.reject), deepest: '/', authority: undefined }; + } + let step = startWalk(start.pathname, trust); // Every step consumes a component, and every link hop counts against a fixed limit, so this ends. for (;;) { if (step.kind === 'reject') { @@ -427,7 +485,7 @@ function refusalAt( /** The first state: the root, with every component of the parent still to resolve. */ function startWalk(parent: string, trust: ScriptDestinationTrust): WalkStep { const queue = pathComponents(parent); - const ground: WalkGround = { stats: new Map(), judged: new Set() }; + const ground: WalkGround = { stats: new Map() }; return standIn('/', queue, trust, 0, ground); } @@ -442,14 +500,8 @@ function standIn( const stats = readGround(ground, directory); if (stats === undefined) return { kind: 'reject', path: directory, exposure: 'not_a_directory' }; const authority: DirectoryAuthority = { uid: stats.uid, gid: stats.gid, mode: stats.mode }; - // Ground this walk has already judged is safe to stand on again, however it was reached: a `..` back to - // a directory it passed, or an alias of one. A directory's judgment does not depend on the route. - const identity = `${stats.dev}:${stats.ino}`; - if (!ground.judged.has(identity)) { - const exposure = untrustedAncestryExposure(authority, trust); - if (exposure) return { kind: 'reject', path: directory, exposure }; - ground.judged.add(identity); - } + const exposure = untrustedAncestryExposure(authority, trust); + if (exposure) return { kind: 'reject', path: directory, exposure }; return { kind: 'stand', state: { deepest: directory, authority, queue, hops, ground } }; } diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts index ceb4f40149..8e5ea7f23a 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts @@ -39,6 +39,36 @@ test.skipIf(process.platform === 'win32')( }, ); +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 the ground a link target crosses on the way in', async () => { diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 9cffa2f3f2..27a588c2fd 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -14,6 +14,7 @@ import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { acquireProcessLock, assertPrivateScriptDestination, + assertPrivateScriptDestinationPrefix, publishDirectoryIdentity, publishFileSync, withProcessLock, @@ -199,9 +200,11 @@ async function publishScriptVersion( const pending = { named: false }; let staging: string | undefined; try { - // The missing parent is created first, so this route judges the chain at the same point the local - // writer does: the rule needs the directory the entry is really created in, which does not exist - // until this line has run (#4565). + // The chain that already exists is refused before anything is created, then the missing parent is + // created, then the full rule is asked again in `allocateStaging`: the rule needs the directory the + // entry is really created in, which does not exist until the `mkdir` has run, and a destination this + // route is going to refuse must leave no directories behind in the shared ground it names (#4565). + assertPrivateScriptDestinationPrefix(record.destination); await fs.promises.mkdir(path.dirname(record.destination), { recursive: true }); const allocated = await withRecordLock(file, async () => allocateStaging(file, record.destination), diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 754859422b..14f96efbf3 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -70,7 +70,7 @@ 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. 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. +- Missing parent directories are created, and only once the directories above them pass the check below. A destination that is refused leaves no new directories behind, even where its parent was missing. 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 name such as `journey.ad` is checked the same way, from the root down through your working directory, 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. 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. From 2af90f4d461ca0d84a8dbb8673c9b459b490e5f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 18:11:30 +0100 Subject: [PATCH 15/28] fix(remote): create a published script in the directory the rule verified `open --save-script /work/../y/journey.ad`, with `work` a link: the destination is judged, the version is downloaded and staged, and the chain is judged a second time before the entry is created. The last step then handed the spelled destination to the kernel, so the path was resolved once more and `home/work/../y` was answered through whatever `work` pointed at by then -- link or rename into a directory the rule had just refused to accept. The entry is now created in the directory that second judgment answers, spelled from it, which is what the local publisher already did. No state has to travel between staging and publishing: the judgment the publish already makes returns the directory. The ledger records the new digest of `publishScriptVersion` with a `compatibleChanges` entry: the call the declaration gained is one more destination check before the `mkdir`, so request, response and artifact framing are byte-for-byte what a released peer sends and parses. --- .../0016-active-session-script-publication.md | 2 +- .../daemon-artifacts-script-ancestry.test.ts | 59 +++++++++++++++++++ .../remote/src/session-script-destination.ts | 11 +++- test/wire-compat/ledger.json | 7 ++- 4 files changed, 74 insertions(+), 5 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index d959c1cf79..c182e5427b 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -218,7 +218,7 @@ Shapes this closes, each of which an earlier shape of the rule accepted: - `..` 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 destination may name no directory at all, `journey.ad`, so its parent is the working directory: `cd /shared/mine` under a `/shared` at 0777 and not sticky, and the working directory itself is a name another local user can point elsewhere. Judging the working directory alone accepts this; the walk starts at `/` over its components, so `/shared` is judged too. -The walk ANSWERS with the physical directory the entry is created in, and the publishers stage inside it AND create the entry inside it, spelled from it. `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. Each path is read from the host once per walk, so an alias or a `..` back over ground already crossed does not ask the host again. +The walk ANSWERS with the physical directory the entry is created in. Both publishers stage inside that directory 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 path is read from the host once per walk, so an alias or a `..` back over ground already crossed does not ask the host again. 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 `passwd`, for `group`, and for `initgroups` — the database glibc reads SUPPLEMENTARY membership from, which those two files say nothing about. An absent `initgroups:` line inherits the verified `group` setting, as the kernel does. `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. diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts index 8e5ea7f23a..2cbb36ad5e 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts @@ -39,6 +39,65 @@ test.skipIf(process.platform === 'win32')( }, ); +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 () => { diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 27a588c2fd..1345d64dc9 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -369,16 +369,21 @@ function publishStaged( // from the directory the walk judged when staging was created, so a walk that now answers a DIFFERENT // directory — an ancestor swapped for a link meanwhile — fails the comparison instead of renaming bytes // into ground nobody judged. - assertPrivateScriptDestination(current.destination, parentIdentity); + const judged = assertPrivateScriptDestination(current.destination, parentIdentity); 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; diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index d70f639661..7c85d492e9 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -215,12 +215,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:cc3b263e1a19cb76256217395f81f54e4fffa6a5755693e1efef1e5e931d50f6", + "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:357bb449fd03596841cede2fcad1589e41b55a806a0c297f10a2320a9b8fb2a7", "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:357bb449fd03596841cede2fcad1589e41b55a806a0c297f10a2320a9b8fb2a7", + "rationale": "#4565 adds one call ahead of the `mkdir` that creates a missing parent: the destination-ancestry rule is asked over the directories that already exist, so a destination it is going to refuse leaves no directories behind. Nothing on the wire changes: no request field is added, removed or renamed, no response field, route, status or artifact framing moves, and the download contract this declaration consumes is untouched. A released daemon receives exactly the same request and answers the same way; a released caller resolves the same paths on its own disk. A skewed peer parses every payload as before." + }, { "declaration": "packages/kernel/src/contracts.ts#DaemonRequestMeta", "digest": "sha256:c2b14225388041f3a6e708c898c512f91b9b20e51a2656a1fa0d5bfa5989fa30", From c5b41a02e64ffc1768ef66280ff04b0572a6319f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 20:01:49 +0100 Subject: [PATCH 16/28] fix(host-kit): refuse a script destination the walk cannot resolve MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three shapes the destination-ancestry rule answered too generously: - `/etc/nsswitch.conf` now answers a database named on TWO lines with no sources, which refuses the private-group exception. glibc appends the sources of every line naming a database and consults them in order, so `group: files` above `group: files sss` really does consult `sss`, and holding to one line judged by a line the lookup never stopped at. - The walk reports whether it ARRIVED at the directory the entry is created in. `publishScriptFileSync` creates nothing, so it now refuses `root/missing/journey.ad` as `unreachable_parent` instead of publishing `root/journey.ad` — a file nobody asked for. - A `..` queued behind the first component that does not exist is refused as `unresolvable_parent` before either route's `mkdir` runs. The kernel cannot apply that step until the name before it exists, while `mkdir -p` resolves the same spelling as text and builds what stands on the far side of it, so `private/missing/../../shared/recordings` used to create a world-writable directory the rule never judged. A `..` over directories that all exist is applied one step at a time, as the kernel applies it. The walk's empty-queue exit moves to the loop that consumes the queue, the one place that sees a finished queue, and the unreachable branch inside a step is gone. The root-owned alias case now serves root for the alias and the directory that holds it: an alias owned by whoever runs the suite passed even if every root-owned link were refused, which is the macOS `/tmp` shape that must keep working. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 5 +- .../session-script-writer-ancestry.test.ts | 27 ++ .../daemon/src/core/session-script-writer.ts | 3 +- .../src/internal/atomic-file-ancestry.test.ts | 15 +- .../src/internal/atomic-file-parent.test.ts | 73 +++ .../atomic-file-private-group.test.ts | 24 + packages/host-kit/src/internal/atomic-file.ts | 418 ++++++++++-------- .../daemon-artifacts-script-ancestry.test.ts | 34 ++ .../remote/src/session-script-destination.ts | 2 + website/docs/docs/replay-e2e.md | 6 +- 10 files changed, 408 insertions(+), 199 deletions(-) create mode 100644 packages/host-kit/src/internal/atomic-file-parent.test.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index c182e5427b..831a3b34fb 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -209,8 +209,9 @@ It adds no state name, command, or flag: 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 directories that already exist are judged before that `mkdir` runs, so a destination the rule refuses leaves no directories behind. 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 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. +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, a caller that creates missing parents asks the same walk twice: once over the prefix that is already there, before the `mkdir`, and once after it, when the directory the entry lands in exists. Only the second question includes whether other local users could add a name inside that directory, because below the first question the directories are the caller's own to create, at its own mode. Deferring it is what keeps `mkdir -p /recordings` acceptable. +A publisher that creates no directories publishes only where the walk ARRIVED: stopping short means the name the caller gave is nowhere the entry can be written, and writing it into the nearest ancestor instead would publish a file nobody asked for. The one shape the pre-`mkdir` question refuses as well is a `..` queued BEHIND the absent component. The kernel cannot apply that step until the name before it exists, while a recursive `mkdir` resolves the same spelling as text and builds what stands on the far side of it: `private/missing/../../shared/recordings` never gets `shared` judged, and the `mkdir` that follows creates `/shared/recordings` in ground any local user can write, beside a `private/missing` of its own. Refusing it before the first `mkdir` is what makes "a refused destination leaves no directories behind" hold for a destination that steps back over ground it would have to create. A `..` over directories that all exist is applied one step at a time, exactly as the kernel applies it. A RELATIVE destination is walked from `/` too, over the resolved working directory's components with the destination's own components following them raw. Standing the walk in the working directory instead would judge that directory and nothing above it, and the working directory is a name in its parent. That spelling is confirmed to be the directory the process stands in, by `dev:ino` against `.`: Node answers the working directory with the path the first query after `chdir` returned, so the name goes stale when the directory it names is moved, and a walk of the stale name judges a directory the process is not in while the kernel resolves the destination in the moved one. 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`. @@ -221,7 +222,7 @@ Shapes this closes, each of which an earlier shape of the rule accepted: The walk ANSWERS with the physical directory the entry is created in. Both publishers stage inside that directory 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 path is read from the host once per walk, so an alias or a `..` back over ground already crossed does not ask the host again. 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 `passwd`, for `group`, and for `initgroups` — the database glibc reads SUPPLEMENTARY membership from, which those two files say nothing about. An absent `initgroups:` line inherits the verified `group` setting, as the kernel does. `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. +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 `passwd`, for `group`, and for `initgroups` — the database glibc reads SUPPLEMENTARY membership from, which those two files say nothing about. A database named on TWO lines establishes nothing either: glibc concatenates the sources of every line naming it and consults them in order, so `group: files` above `group: files sss` really does consult `sss`, and no single line says what the lookup reaches. An absent `initgroups:` line inherits the verified `group` setting, as the kernel does. `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 judged 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. 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 index d6f703404a..1678c0f14e 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -158,6 +158,33 @@ skipOnWindows('a refused destination with a missing parent leaves no directories 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 diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index 164d6dc23c..587e0a3b5f 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -139,7 +139,8 @@ export class SessionScriptWriter { const scriptDir = path.dirname(scriptPath); // Asked BEFORE the parent is created, and again by the publisher once it exists: a `mkdir -p` into // ground another local user can write would otherwise leave the directories it made behind them, - // even though the publish that follows is refused (#4565). + // even though the publish that follows is refused (#4565). The walk covers `scriptDir`'s own + // components, which is where `mkdir -p` would build a directory on the far side of a `..`. assertPrivateScriptDestinationPrefix(scriptPath); if (!fs.existsSync(scriptDir)) fs.mkdirSync(scriptDir, { recursive: true }); // #1258: `options.force` is the caller's already-merged decision diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index 2a71e4e509..f290d3b14d 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -34,7 +34,8 @@ 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. A real foreign owner would need privileges this test does not have. + * 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 => { @@ -825,19 +826,25 @@ skipOnWindows( skipOnWindows('keeps working through a root-owned alias whose target is sticky', () => { serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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 alias = path.join(directory, 'alias'); - const target = path.join(directory, 'target'); + 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.existsSync(path.join(target, 'work', 'journey.ad'))).toBe(true); + expect(fs.readFileSync(path.join(target, 'work', 'journey.ad'), 'utf8')).toBe('context\n'); }); skipOnWindows('publishes under the host root-owned system temporary directory', () => { 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..33bc3476db --- /dev/null +++ b/packages/host-kit/src/internal/atomic-file-parent.test.ts @@ -0,0 +1,73 @@ +// Whether a destination's parent can be RESOLVED at all, and what the 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, + currentGid, + directoryWith, + expectUntrusted, + hostDatabase, + publish, + serveGroupDatabase, +} from './atomic-file-host.fixtures.ts'; +import { assertPrivateScriptDestination } 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', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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. A + // destination that would be resolved by creating it is refused, and nothing is created on the way. + 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( + () => assertPrivateScriptDestination(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', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // 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('refuses a destination whose parent does not exist, and publishes nowhere', () => { + serveGroupDatabase(hostDatabase(currentGid, 4321)); + // This publisher creates no directories, so a walk that stopped at an absent name has no answer to + // publish into. The nearest ancestor it did reach would be a file the caller never asked for: + // `root/journey.ad` instead of `root/missing/journey.ad`. + const directory = root(); + const missing = path.join(directory, 'missing'); + const destination = path.join(missing, 'journey.ad'); + + expectUntrusted(() => publish(destination), 'unreachable_parent', directory); + expect(fs.readdirSync(directory)).toEqual([]); +}); diff --git a/packages/host-kit/src/internal/atomic-file-private-group.test.ts b/packages/host-kit/src/internal/atomic-file-private-group.test.ts index 4abfe9ae69..c74515fc12 100644 --- a/packages/host-kit/src/internal/atomic-file-private-group.test.ts +++ b/packages/host-kit/src/internal/atomic-file-private-group.test.ts @@ -141,12 +141,36 @@ test('refuses it when initgroups names a service, the database supplementary mem expect(withInitgroups('initgroups: files')).toBe(1000); }); +test('refuses it when a database is named twice, whichever order the lines come in', () => { + // glibc CONCATENATES the sources of every line naming a database and consults them in order, so + // `group: files` above `group: files sss` really does consult `sss`. No single line here therefore says + // what the lookup consults, and the exception is refused rather than settled by the first line, the last + // line, or the shorter list. `initgroups:` inherits the `group` setting only when it is ABSENT; a second + // `initgroups:` line is the same concatenation problem. + const withLines = (lines: string[]) => + privateGroupId({ groups: PRIVATE, passwd: PRIVATE_PASSWD, nsswitch: lines }, ADA); + + expect(withLines(['passwd: files', 'group: files', 'group: files sss'])).toBeUndefined(); + // The order that looks harmless from the other end: the refused source comes FIRST, so keeping the last + // line would also admit it. + expect(withLines(['passwd: files', 'group: files sss', 'group: files'])).toBeUndefined(); + expect(withLines(['passwd: files', 'group: files', 'passwd: files ldap'])).toBeUndefined(); + expect( + withLines(['passwd: files', 'group: files', 'initgroups: files', 'initgroups: files sss']), + ).toBeUndefined(); + // Repeating a database with the SAME sources establishes nothing more either: glibc would consult + // `files` twice, and this rule cannot tell that pair apart from the pair above. + expect(withLines(['passwd: files', 'group: files', 'group: files'])).toBeUndefined(); +}); + test('admits a name service line that names only files, actions and comments aside', () => { expect( nameServiceListsOnlyFiles(['passwd: [NOTFOUND=return] files # local only', 'group: files']), ).toBe(true); expect(nameServiceListsOnlyFiles(['passwd: files', 'group: files db'])).toBe(false); expect(nameServiceListsOnlyFiles(undefined)).toBe(false); + // One database, two lines: see the refusal above. A repeated database is refused whoever owns the line. + expect(nameServiceListsOnlyFiles(['passwd: files', 'passwd: files', 'group: files'])).toBe(false); }); test('gives a caller without a full identity no private group', () => { diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index 5ecc43a608..ce07693beb 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -47,8 +47,8 @@ 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): the chain is refused before - * anything is staged, and it is judged again immediately before the link or rename. The file is created - * private, because a recording is a transcript of what someone did on this machine. + * anything is staged and judged again before the link or rename. The file is private, because a recording + * is a transcript of what someone did on this machine. * * `parentIdentity` is what {@link publishDirectoryIdentity} returned for a parent the caller created or * checked before it staged this file. @@ -58,10 +58,9 @@ export function publishScriptFileSync(options: { contents: string; publish?: AtomicPublishMode; }): void { - // The directory the entry is created in is the walk's ANSWER, asked for inside this call and twice: - // never `path.dirname` of the spelled destination, because a `..` or a link in the destination sends the - // entry somewhere else, and a temp file staged there is one another local user can reach, list, and - // put their own bytes behind before the publish does. + // The directory the entry is created in is the walk's ANSWER, asked for twice inside this call 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. let temporaryPath: string | undefined; try { const judged = assertPrivateScriptDestination(options.destination); @@ -72,10 +71,9 @@ export function publishScriptFileSync(options: { if (stillJudged !== judged) { throw scriptAncestryFailure(options.destination, stillJudged, 'parent_replaced'); } - // The entry is created in the directory the walk ANSWERED, spelled from it, and never through the - // destination's own spelling: the kernel resolves a relative destination against the process's - // working directory and a spelled `..` against the directories on the way there, so a spelling that - // has drifted from the judged one would land the entry in ground the rule never reached. + // 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); @@ -88,9 +86,8 @@ export function publishScriptFileSync(options: { } /** - * The canonical temp path for a destination: a private sibling of the name, inside the directory the - * publish will create the entry in. That directory is the walk's answer for a script destination, and - * `path.dirname` for every other publisher. + * 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( @@ -201,7 +198,7 @@ function syncDirectoryBestEffort(directory: string): void { * `lstat` that treats absence as `undefined`; every other errno propagates. * * Owned here, not in a module of its own, because the publish rule sits on the daemon's startup path: a - * new module on that edge makes eager code every entry that publishes a file pays for today. The + * new module on that edge is eager code every entry that publishes a file pays for today (ADR 0019). The * verified-file guards ask the same question, and this module is on their path already. */ export function lstatIfPresent(pathname: string): fs.Stats | undefined { @@ -218,10 +215,9 @@ export function lstatIfPresent(pathname: string): fs.Stats | undefined { * * 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 directories are therefore asked of the filesystem and - * compared as device and inode. `lstat` or `realpathSync` would apply a spelled `..` textually and answer - * the wrong one, which rejects the real temp sibling and accepts a look-alike planted beside the - * directory the text names. + * 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 — which + * rejects the real temp sibling and accepts a look-alike planted beside the directory the text names. */ export function isAtomicPublishTemporaryPath(value: unknown, destination: string): boolean { if (typeof value !== 'string') return false; @@ -259,38 +255,24 @@ function statOrNull(pathname: string): fs.Stats | undefined { * one, so the path this rule judged is the path the publish reaches. Nothing here depends on when a * directory was judged, and no re-check is what makes the write safe. * - * The return value is part of the rule, not a convenience. The caller stages the temp file IN THAT - * DIRECTORY: a `..` or a symbolic link in the spelled destination means the directory the entry really - * lands in is not `path.dirname` of the spelling, and staging outside the judged directory would hand - * another local user the temp file they then get published. + * The return value is part of the rule, not a convenience: the caller stages the temp file IN THAT + * DIRECTORY, because a `..` or a link means the entry lands somewhere `path.dirname` does not name, and + * staging outside the judged directory hands another local user the temp file that gets published. * - * What the walk asks of every directory it enters ({@link walkParent} for the resolution itself): - * - * - It is owned by this user or by root. A directory another user owns is theirs to chmod, to empty, and - * to repopulate, whatever its mode says today, and both the sticky bit and the group bits shield other - * users FROM that owner rather than the reverse. - * - Its mode opens its contents to nobody else. The sticky bit is the one exception, and only for - * passing THROUGH a directory: it stops anyone but an entry's owner or root from removing or replacing - * that entry, which is how macOS `/tmp` and `/var` stay usable. It cannot refuse a NEW entry by name, - * so nothing may be created inside a directory others can add entries to; that is asked separately, of - * the directory the walk ended in. - * - Every symbolic link the walk follows is judged itself, against the directory that physically holds - * it, at any depth: in a directory where others can add entries, it stands there only because the - * sticky bit and its owner hold it in place. A link's own mode is never consulted, because on Linux - * every link reports the same one. - * - * A group-writable directory this user owns stays acceptable when its group is this user's own private - * group, the shape Ubuntu and Debian give every home directory. {@link privateGroupId} says what that - * takes to establish, and what it cannot. + * What it asks of every directory it enters is {@link untrustedAncestryExposure}: ownership first, then + * the mode, with the sticky bit excusing only passing THROUGH. {@link othersCreateEntriesIn} is asked + * separately of the directory the walk ended in, because that bit cannot refuse a NEW entry by name, and + * every followed link is judged by {@link untrustedLinkExposure} against the directory that holds it. + * A group-writable directory stays acceptable when its group is this user's own private group, the shape + * Ubuntu and Debian give home directories; {@link privateGroupId} says what that takes to establish. * * A component that is neither a directory nor a link is refused as `not_a_directory`: the kernel cannot - * travel through it either. On Windows, access is an ACL rather than a mode, so this rule is a no-op - * there and answers the parent it was given. + * travel through it either. On Windows access is an ACL, so this rule is a no-op and answers the parent + * it was given. * * `parentIdentity` is what {@link publishDirectoryIdentity} returned for the parent the caller created - * or checked before it staged this file. The rule above already excludes anyone who could swap that - * parent, so the comparison is defense in depth against a host whose ownership or modes moved meanwhile; - * it is not what closes the window. + * or checked before it staged this file. The rule above already excludes anyone who could swap it, so the + * comparison is defense in depth against a host whose modes moved meanwhile, not what closes the window. */ export function assertPrivateScriptDestination( destination: string, @@ -300,6 +282,15 @@ export function assertPrivateScriptDestination( const trust = readScriptTrust(); const walk = walkParent(destination, trust); if (walk.reject !== undefined) throw walk.reject; + if (walk.unresolvable) { + throw scriptAncestryFailure(destination, walk.deepest, 'unresolvable_parent'); + } + if (!walk.arrived) { + // The walk stopped at a name that does not exist. A publisher that creates no directories has + // nowhere to write, and writing the entry into the nearest ancestor instead would publish it under + // a name the caller never gave it. + throw scriptAncestryFailure(destination, walk.deepest, 'unreachable_parent'); + } // The identity is asked of the directory the entry is created in, which is the walk's answer and NOT // `path.dirname` of the spelling: where a `..` or a link leads elsewhere, the spelled parent is a // different directory and comparing against it reports a replacement that never happened. @@ -317,15 +308,22 @@ export function assertPrivateScriptDestination( } /** - * Refuses a script destination whose ALREADY-EXISTING directories another local user can steer, before - * anything is created on the way to it. Callers that create a missing parent run this first, then create, - * then run {@link assertPrivateScriptDestination} once the directory the entry lands in exists. + * Refuses a script destination before its caller creates anything on the way to it, answering whether + * the caller's `mkdir` may run. Callers that create a missing parent run this first, then create, then + * run {@link assertPrivateScriptDestination} once the directory the entry lands in exists. + * + * It is the same walk, not a second rule: it stops at the first component that does not exist, so asking + * it before the `mkdir` judges exactly the prefix that is already there. Two questions the full rule asks + * are deliberately NOT asked here: the creation question — others adding a name inside the directory the + * walk ends in — because the directories below are the caller's own to create, at its own mode, which is + * what keeps `mkdir -p /recordings` acceptable; and the arrival question, because the + * missing tail is what the `mkdir` is for. * - * It is the same walk, not a second rule: the walk stops at the first component that does not exist, so - * asking it before the `mkdir` judges exactly the prefix that is already there. What is NOT asked here is - * the creation question — whether other local users could add a name inside the directory the walk ends in - * — because the directories below are the caller's own to create, at its own mode. Deferring it is what - * keeps `mkdir -p /recordings` acceptable on both routes. + * A `..` queued BEHIND the absent component stops the `mkdir` anyway. The kernel cannot apply that step + * until the name before it exists, while a recursive `mkdir` resolves the spelling as text and builds + * what stands on the far side of it: `private/missing/../../shared/recordings` never gets `shared` + * judged, and the `mkdir` creates `/shared/recordings` where any local user can write. A `..` over + * directories that all exist resolves for the walk as the kernel resolves it, and stays fine. * * The refusal is the same typed error the full rule raises, so a caller sees one reason for one shape of * path whichever of the two asked it. @@ -334,21 +332,21 @@ export function assertPrivateScriptDestinationPrefix(destination: string): void if (process.platform === 'win32') return; const walk = walkParent(destination, readScriptTrust()); if (walk.reject !== undefined) throw walk.reject; + if (walk.unresolvable) { + throw scriptAncestryFailure(destination, walk.deepest, 'unresolvable_parent'); + } } /** - * The parent of `destination` as a chain of components from the root, never normalized. - * - * `path.resolve` folds a `..` away, which is the one simplification this may not make: the kernel does - * not make it either, so `.../work/../x` lands its entry beside the target of the link named `work`. The - * spelled components are what the walk resolves. + * The parent of `destination` as a chain of components from the root, never normalized: `path.resolve` + * folds a `..` away, which is the one simplification this may not make, because the kernel does not make + * it either — `.../work/../x` lands its entry beside the target of the link named `work`. * - * A RELATIVE destination is resolved against the working directory, but it is not made absolute by - * joining the two: the working directory's OWN components are queued first and the destination's follow - * them raw. Standing the walk in the cwd instead would judge the cwd and nothing above it, and a caller - * who cannot write `/shared` can still swap the `/shared/mine` the cwd names, which is the entry this - * rule exists to refuse. The working directory's name is first confirmed to be where the process really - * stands ({@link standsIn}), because that name is what the walk queues. + * A RELATIVE destination is resolved against the working directory, but not made absolute by joining the + * two: the cwd's OWN components are queued first and the destination's follow them raw. Standing the walk + * in the cwd would judge the cwd and nothing above it, and a caller who cannot write `/shared` can still + * swap the `/shared/mine` the cwd names. That name is first confirmed to be where the process really + * stands ({@link standsIn}), because it is the name the walk queues. */ function absoluteParent(destination: string): WalkStart { const parent = path.dirname(destination); @@ -371,11 +369,10 @@ type WalkStart = /** * Whether the process really stands in the directory `pathname` names as its working directory. * - * Node answers the working directory from the last `chdir` it made, so its NAME can be stale while the - * process is unbothered: move the directory the name points at and put another one at that path, and a - * walk of the name judges the replacement while the kernel resolves every relative name in the moved one. - * The two are therefore asked of the filesystem and compared as device and inode, the one answer that - * makes both names mean the same directory. + * Node answers the working directory from the last `chdir` it made, so its NAME can go stale: move the + * directory it points at and put another at that path, and a walk of the name judges the replacement + * while the kernel resolves every relative name in the moved one. The two are therefore compared as + * device and inode, the one answer that makes both names mean one directory. */ function standsIn(pathname: string): boolean { const remembered = statOrNull(pathname); @@ -389,8 +386,7 @@ function standsIn(pathname: string): boolean { } /** - * Where the walk stands: a directory it has already judged and physically reached, plus the names still - * to resolve. `deepest` is the directory the entry is created in when the walk stops here. + * Where the walk stands: a directory it judged and physically reached, plus the names still to resolve. */ type WalkState = Readonly<{ deepest: string; @@ -404,9 +400,9 @@ type WalkState = Readonly<{ }>; /** - * One walk's memory of the ground it has stood on: the `stat` of every path it has read, keyed by that - * path. A path that comes back around, through a `..` or through an alias of a directory already entered, - * is therefore asked of the host once, and one walk sees the host the same way throughout. + * One walk's memory of the ground it stood on: the `stat` of every path it read, keyed by that path. A + * path that comes back around, through a `..` or an alias, is asked once, so one walk sees the host the + * same way throughout. */ type WalkGround = Readonly<{ stats: Map; @@ -414,33 +410,49 @@ type WalkGround = Readonly<{ type WalkStep = | Readonly<{ kind: 'reject'; path: string; exposure: ScriptAncestryExposure }> - | Readonly<{ kind: 'stop'; deepest: string; authority: DirectoryAuthority }> + | Readonly<{ + kind: 'short'; + deepest: string; + authority: DirectoryAuthority; + /** Whether a `..` is queued behind the name that stopped the walk. */ + behindUpwardStep: boolean; + }> | Readonly<{ kind: 'stand'; state: WalkState }>; /** * A walk that ended: the typed refusal, or the directory the entry is created in together with the * authority it was judged with. The authority travels with the answer, so the caller never asks the host * about ground the walk has already read. + * + * `arrived` says the resolution reached the directory the entry is created in. Otherwise the walk stopped + * at a name that does not exist and reports the nearest ancestor it did reach, which is NOT where the + * entry belongs: publishing there writes a file the caller never named. + * + * `unresolvable` says a `..` is queued behind that absent name, so creating cannot finish the resolution: + * the step up depends on a directory that is not there to be looked up in, and the caller's `mkdir` + * resolves the same spelling as text and lands somewhere else. */ type WalkOutcome = Readonly<{ reject: AppError | undefined; deepest: string; authority: DirectoryAuthority | undefined; + arrived: boolean; + unresolvable: boolean; }>; /** * 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 any - * directory the resolution stepped through can vanish from the answer, and from the judgment, whenever a - * link leads on to another link, or a spelled prefix names a plain directory whose ground is shared. - * Instead each component is resolved against the directory physically reached: + * 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 component ends the walk, because the - * publish creates what is missing below here. + * - 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: `arrived` is false, 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 @@ -449,32 +461,48 @@ type WalkOutcome = Readonly<{ * {@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. * - * A relative destination is walked from the root too, over the resolved working directory's components - * first: the caller stands in the working directory, but that directory is still a name in its parent, - * and the parent is judged like any other. + * A relative destination is walked from the root too, over the working directory's components first: the + * caller stands in that directory, but it is still a name in its parent, and the parent is judged too. */ function walkParent(destination: string, trust: ScriptDestinationTrust): WalkOutcome { const start = absoluteParent(destination); if (start.reject !== undefined) { - return { reject: refusalAt(destination, start.reject), deepest: '/', authority: undefined }; + return refused(refusalAt(destination, start.reject)); } let step = startWalk(start.pathname, trust); // Every step consumes a component, and every link hop counts against a fixed limit, so this ends. for (;;) { - if (step.kind === 'reject') { - return { reject: refusalAt(destination, step), deepest: '/', authority: undefined }; - } - if (step.kind === 'stop') { - return { reject: undefined, deepest: step.deepest, authority: step.authority }; + if (step.kind === 'reject') return refused(refusalAt(destination, step)); + if (step.kind === 'short') { + return { + reject: undefined, + deepest: step.deepest, + authority: step.authority, + arrived: false, + unresolvable: step.behindUpwardStep, + }; } const { state } = step; - if (state.queue.length === 0) { - return { reject: undefined, deepest: state.deepest, authority: state.authority }; + const [component, ...rest] = state.queue; + if (component === undefined) { + // The one way a walk ARRIVES: every name the parent spelled has been resolved and judged. + return { + reject: undefined, + deepest: state.deepest, + authority: state.authority, + arrived: true, + unresolvable: false, + }; } - step = stepWalk(state, trust); + step = stepThrough(state, component, rest, trust); } } +/** A walk that refused has no directory to report, because none of them is established as the entry's. */ +function refused(reject: AppError): WalkOutcome { + return { reject, deepest: '/', authority: undefined, arrived: false, unresolvable: false }; +} + function refusalAt( destination: string, step: Readonly<{ path: string; exposure: ScriptAncestryExposure }>, @@ -519,12 +547,16 @@ function pathComponents(directory: string): string[] { return directory.split('/').filter((component) => component.length > 0 && component !== '.'); } -/** Advances one component of the queue. */ -function stepWalk(state: WalkState, trust: ScriptDestinationTrust): WalkStep { - const [component, ...rest] = state.queue; - if (component === undefined) { - return { kind: 'stop', deepest: state.deepest, authority: state.authority }; - } +/** + * Advances one component of the queue, which the caller knows to be non-empty: an empty queue is where a + * walk arrives, and {@link walkParent} 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 === '..') { @@ -542,18 +574,24 @@ function stepIntoEntry( ): WalkStep { const entry = path.join(state.deepest, component); const stats = lstatIfPresent(entry); - // Nothing below here exists yet, so the publish creates it inside the directory the walk reached. + // Nothing below here exists yet: a caller that creates missing parents stops here and creates inside + // the directory the walk reached; a publisher that creates nothing refuses. Neither may go on as if the + // name had resolved. if (stats === undefined) { - return { kind: 'stop', deepest: state.deepest, authority: state.authority }; + return { + kind: 'short', + deepest: state.deepest, + authority: state.authority, + behindUpwardStep: rest.includes('..'), + }; } if (stats.isSymbolicLink()) return stepThroughLink(state, entry, stats, rest, trust); return standIn(entry, rest, trust, state.hops, state.ground); } /** - * One hop. The link is judged where it physically stands: inside a directory others may add entries to, - * only a link this user or root owns, held by the sticky bit, is theirs to keep. Its target's components - * then enter the queue, because the kernel steps into them next. + * 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, @@ -579,23 +617,34 @@ function stepThroughLink( /** * How many link targets one destination walk expands before it refuses. * - * Kept BELOW the smallest limit the supported kernels apply to a path of their own (macOS 32, Linux 40), - * so this rule always reaches its own limit first and answers with its own typed reason. The walk counts - * hops rather than letting the kernel answer `ELOOP`, because a walk that ran out of hops has NOT - * established where the entry lands, and that is a refusal, not a pass. + * 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 on its filesystem, for a caller that must publish into the same one it - * created or checked. `undefined` when the directory is absent or is not a directory. - */ +/** One directory's identity, for a caller that must publish into the same one it created or checked. */ export function publishDirectoryIdentity(directory: string): string | undefined { if (process.platform === 'win32') return 'windows'; const stats = statDirectoryChain(directory); return stats ? `${stats.dev}:${stats.ino}` : undefined; } +export type ScriptDestinationTrust = Readonly<{ + uid: number; + privateGid: number | undefined; +}>; + +/** The fields of a directory the ancestry rule reads, so the decision is testable without a filesystem. */ +export type DirectoryAuthority = Readonly<{ uid: number; gid: number; mode: number }>; + +/** The fields of a symbolic link the ancestry rule reads. */ +export type LinkAuthority = Readonly<{ uid: number }>; + +/** The file that says which sources the host looks in for accounts and groups. */ +const NSSWITCH_FILE = '/etc/nsswitch.conf'; + /** The host files the private-group exception reads, in `/etc/group` field order. */ type HostGroupDatabase = Readonly<{ /** `undefined` when the file could not be read, which is not the same as a file with no records. */ @@ -611,11 +660,16 @@ type NsswitchLine = Readonly<{ database: string; sources: readonly string[] }>; /** * Whether `/etc/nsswitch.conf` establishes that the group and passwd files are the whole story. * - * `files` is the only source admitted. `systemd` is deliberately NOT admitted, even though it is the - * default on some distributions: `systemd-userdbd` answers group membership from user records the two - * files never see, which is exactly the member this rule could not read. Bracketed actions such as - * `[NOTFOUND=return]` steer a lookup and add no source, so they are ignored. A missing line, an - * unparseable line, or an unreadable file establishes nothing, and the exception is refused. + * `files` is the only source admitted. `systemd` is deliberately NOT admitted, though it is the default + * on some distributions: `systemd-userdbd` answers membership from user records these files never see, + * which is exactly the member this rule could not read. Bracketed actions such as `[NOTFOUND=return]` + * steer a lookup and add no source, so they are ignored. A missing line, an unparseable line, or an + * unreadable file establishes nothing, and the exception is refused. + * + * A database named MORE THAN ONCE establishes nothing either. glibc appends the sources of every line + * naming it and consults them in order, so `group: files` above `group: files sss` really does consult + * `sss`, and keeping one of the two lines — the last, or the first — would judge by a line the lookup + * never stopped at. {@link nsswitchLine} says how a repeated database is answered. */ export function nameServiceListsOnlyFiles(nsswitch: readonly string[] | undefined): boolean { if (nsswitch === undefined) return false; @@ -633,16 +687,26 @@ function listsOnlyFiles(line: NsswitchLine): boolean { return line.sources.length > 0 && line.sources.every((source) => source === 'files'); } +/** + * The sources `/etc/nsswitch.conf` gives `database`, or `undefined` when it says nothing usable. + * + * A database named twice is answered with NO sources, which refuses the exception: the resolver + * concatenates the sources of repeated lines, so no single line says what the lookup consults, and + * {@link listsOnlyFiles} refuses an empty source list. + */ function nsswitchLine(lines: readonly string[], database: string): NsswitchLine | undefined { + let found = 0; + let sources: readonly string[] = []; for (const raw of lines) { const source = (raw.split('#')[0] ?? '').trimStart(); const [name, ...rest] = source.split(/[\s:]+/); if (name !== database) continue; + found += 1; // A bracketed action steers a lookup and lists no source. - const sources = rest.filter((token) => token.length > 0 && !token.startsWith('[')); - return { database, sources }; + sources = rest.filter((token) => token.length > 0 && !token.startsWith('[')); } - return undefined; + if (found === 0) return undefined; + return { database, sources: found > 1 ? [] : sources }; } /** One `/etc/group` record. A line without a numeric gid cannot be used to judge membership. */ @@ -675,25 +739,22 @@ type CurrentAccount = Readonly<{ /** * The single group the private-group exception admits, or `undefined` when nothing was established. * - * Ubuntu and Debian create one group per user, named after them, and set up that user's home directory - * with it, often group-writable and owned by that user. Such a home is shared with no other local user, - * so it stays a valid script destination. Every other group stays outside the exception, and the rule - * fails closed wherever completeness cannot be established: + * Ubuntu and Debian create one group per user, named after them, and set that user's home directory to + * it, often group-writable and owned by them. Such a home is shared with no other local user, so it stays + * a valid destination. Every other group stays outside the exception, and the rule fails closed wherever + * completeness cannot be established: * - * - `/etc/nsswitch.conf` must exist, be readable, and name `files` as the ONLY source for both `passwd` - * and `group`. Otherwise a name service could hold a member no file shows, and nothing here could see - * it. {@link nameServiceListsOnlyFiles} says what a name service may say. + * - {@link nameServiceListsOnlyFiles} must establish that the host's own files answer the question. * - Both database files must have been READ. An unreadable file is not an empty one, and an empty * member list proves nothing. - * - The gid must be the one this process holds as its PRIMARY group, which `getgid` answers from the - * kernel rather than from a file, and at least one record carrying that gid must bear this user's name. + * - The gid must be this process's PRIMARY group, which `getgid` answers from the kernel, and one record + * carrying it must bear this user's name. * - EVERY record carrying that gid is read, because a directory group-writable by gid 1000 is writable - * by the members of each group holding the number, however they are named: `ada:x:1000:` beside - * `team:x:1000:grace` reaches grace. Any of them naming a member who is neither this user nor root - * ends the claim, without lookup or forgiveness — macOS lists only part of `staff` in `/etc/group` - * while every local user holds it. - * - No other passwd record may hold this gid as its primary group, and the caller's own record must - * exist there with this uid and this gid. + * by the members of each group holding the number, however named: `ada:x:1000:` beside + * `team:x:1000:grace` reaches grace. Any of them naming a member who is neither this user nor root ends + * the claim — macOS lists only part of `staff` in `/etc/group` while every local user holds it. + * - No other passwd record may hold this gid as its primary group, and the caller's own must exist there + * with this uid and this gid. */ export function privateGroupId( database: HostGroupDatabase, @@ -753,9 +814,9 @@ function memberIsTrusted(member: string, accounts: HostAccounts, name: string): } /** - * The account name this process's uid maps to, read from the host account database. The name comes from - * the same file the group records come from, so a caller standing in for that file and this name stays in - * agreement. No `os.userInfo()`: that answers from a different source than the records being judged. + * The account name this process's uid maps to, read from the host account database: the same file the + * group records come from, so a fixture serving one serves the other. No `os.userInfo()`, which answers + * from a different source than the records being judged. */ function readCurrentUser( passwd: readonly string[] | undefined, @@ -786,22 +847,20 @@ function readScriptTrust(): ScriptDestinationTrust { }; } -/** The file that says which sources the host looks in for accounts and groups. */ -const NSSWITCH_FILE = '/etc/nsswitch.conf'; +function readSystemFile(file: string): string[] | undefined { + try { + return fs.readFileSync(file, 'utf8').split('\n'); + } catch { + return undefined; + } +} /** - * The ways a step of the walk can be unsafe: somebody else can change what is in that directory, they - * can create the entry the destination names, they can put the link there, or the step cannot be trusted - * at all. - * - * `foreign_owned` — some other user owns it and can chmod, empty, or repopulate it whatever its mode. - * `world_writable` / `shared_group_writable` — its mode opens its contents to others. - * `shared_parent` — nobody else can change what is in it today, but they can add the missing entry. - * `planted_link` — a symbolic link another user could have put in place of a directory, or could replace. - * `link_loop_exceeded` — the walk expanded as many links as the kernel allows, so where it lands is not - * established. A loop is refused, never trusted. - * `not_a_directory` — a step of the path is something a publish cannot travel through. - * `parent_replaced` — the directory the caller staged against is not the one it was. + * 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' @@ -811,28 +870,19 @@ export type ScriptAncestryExposure = | 'planted_link' | 'link_loop_exceeded' | 'not_a_directory' + | 'unresolvable_parent' + | 'unreachable_parent' | 'parent_replaced'; -/** What this process can rely on when it judges a directory: its identity and its private group. */ -export type ScriptDestinationTrust = Readonly<{ - uid: number; - privateGid: number | undefined; -}>; - -/** The fields of a directory the ancestry rule reads, so the decision is testable without a filesystem. */ -export type DirectoryAuthority = Readonly<{ uid: number; gid: number; mode: number }>; - /** * 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, to empty, and to - * repopulate whatever its mode says today, and no race is needed to do it. Then the mode, because - * group- or other-writable contents are open to those users directly. The sticky bit is the one mode - * exception, and it is sound only for PASSING THROUGH a directory: it stops anyone but an entry's owner - * or root from removing or replacing that entry, so the entries already on the path hold. It cannot - * refuse a NEW entry by name, so {@link othersCreateEntriesIn} is asked separately before anything is - * created inside. + * 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. The sticky bit is the one 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 inside. */ export function untrustedAncestryExposure( directory: DirectoryAuthority, @@ -849,10 +899,9 @@ export function untrustedAncestryExposure( * 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 both of those protect other people's entries from them, not - * their own. The sticky bit is otherwise deliberately not consulted here — it cannot refuse a NEW entry - * by name. + * 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, @@ -863,22 +912,17 @@ export function othersCreateEntriesIn( return Boolean(directory.mode & 0o020) && directory.gid !== trust.privateGid; } -/** The fields of a symbolic link the ancestry rule reads. */ -export type LinkAuthority = Readonly<{ uid: number }>; - /** * 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 add entries, the sticky bit is the only thing holding an existing entry in place: it - * stops anyone but the entry's owner or root from unlinking and replacing it, so a link this user or root - * owns stands, and one anybody else owns does not — it may be theirs, and without the sticky bit any of - * them can swap it for one pointing wherever they like. + * 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 the path steps back over with `..` is asked as a directory rather than as a link: there - * the caller is not publishing through it, only walking across it, and the directory it lands in is - * judged on its own. + * 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, @@ -900,6 +944,10 @@ const untrustedGroundWording: Record = { 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.', + 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: '', }; @@ -927,14 +975,6 @@ function scriptAncestryFailure( ); } -function readSystemFile(file: string): string[] | undefined { - try { - return fs.readFileSync(file, 'utf8').split('\n'); - } catch { - return undefined; - } -} - /** `stat` of the directory a path names, or `undefined` when it is absent or is not a directory. */ function statDirectoryChain(pathname: string): fs.Stats | undefined { let stats: fs.Stats | undefined; diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts index 2cbb36ad5e..6194bc490b 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts @@ -128,6 +128,40 @@ test.skipIf(process.platform === 'win32')( }, ); +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 () => { diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 1345d64dc9..4f913f3b6b 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -204,6 +204,8 @@ async function publishScriptVersion( // created, then the full rule is asked again in `allocateStaging`: the rule needs the directory the // entry is really created in, which does not exist until the `mkdir` has run, and a destination this // route is going to refuse must leave no directories behind in the shared ground it names (#4565). + // The walk covers that same spelled parent, which is where a `..` step would otherwise build a + // directory nobody judged. assertPrivateScriptDestinationPrefix(record.destination); await fs.promises.mkdir(path.dirname(record.destination), { recursive: true }); const allocated = await withRecordLock(file, async () => diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 14f96efbf3..fde22c292a 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -70,11 +70,11 @@ 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, and only once the directories above them pass the check below. A destination that is refused leaves no new directories behind, even where its parent was missing. 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. +- Missing parent directories are created, and only once the directories above them pass the check below. 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 name such as `journey.ad` is checked the same way, from the root down through your working directory, 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. Following more links than the system allows is refused rather than trusted. +- 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 name such as `journey.ad` is checked the same way, from the root down through your working directory, 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories, and only where `/etc/nsswitch.conf` shows that `/etc/group` and `/etc/passwd` are the whole story for accounts, groups and supplementary groups alike: a name service could hold a member those files never show. Every group carrying that group number is considered, so a second group with the same number that lists somebody else closes this exception. +- 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories, and only where `/etc/nsswitch.conf` shows that `/etc/group` and `/etc/passwd` are the whole story for accounts, groups and supplementary groups alike: a name service could hold a member those files never show, and a database configured on two lines is not settled by the one that looks safer, because the system consults both. Every group carrying that group number is considered, so a second group with the same number that lists somebody else closes this exception. - 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. From 927b042cc1029de9673a9440f6f25846d1c89498 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 20:35:12 +0100 Subject: [PATCH 17/28] refactor(host-kit): own script destination creation in one call Amends ADR 0016 so the rule is smaller and sits in one owner. A script publish now creates every directory it makes at 0700, so a new directory passes the check a later recording judges it by instead of being refused at 0775 on a shared umask. host-kit owns the whole sequence as `prepareScriptDestination`: walk, refuse before creating anything, create what is missing inside the judged directory, judge again, answer with the judged directory. Both routes call it, and the exported prefix seam plus the two hand-sequenced copies are gone. Where nothing was missing, the first walk already judged the directory the entry is created in, so its answer is the answer and there is no second walk. The private-group exception is dropped. Membership cannot be proven on a host whose name service answers it from outside the account files, so a group-writable directory is refused on the mode alone and the hint names `chmod g-w`. No account database is read. A destination that is not absolute is refused at the entry, and the local publish keeps one walk instead of two. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 14 +- .../session-script-writer-ancestry.test.ts | 77 +-- .../daemon/src/core/session-script-writer.ts | 17 +- packages/host-kit/src/file.ts | 2 +- .../src/internal/atomic-file-ancestry.test.ts | 252 ++------ .../internal/atomic-file-decisions.test.ts | 32 +- .../src/internal/atomic-file-host.fixtures.ts | 75 +-- .../src/internal/atomic-file-parent.test.ts | 106 ++-- .../atomic-file-private-group.test.ts | 181 ------ packages/host-kit/src/internal/atomic-file.ts | 590 +++++++----------- .../daemon-artifacts-script-ancestry.test.ts | 36 ++ .../remote/src/session-script-destination.ts | 14 +- test/wire-compat/ledger.json | 11 +- website/docs/docs/replay-e2e.md | 6 +- 14 files changed, 439 insertions(+), 974 deletions(-) delete mode 100644 packages/host-kit/src/internal/atomic-file-private-group.test.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 831a3b34fb..fd10042b0e 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -207,24 +207,24 @@ 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 (#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 directories that already exist are judged before that `mkdir` runs, so a destination the rule refuses leaves no directories behind. The rule closes the window with PERMISSIONS, not with timing. +Both routes resolve an absolute destination before asking host-kit, and host-kit refuses a relative one at its entry: 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 both the local writer and the remote client make that one call before staging. 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, a caller that creates missing parents asks the same walk twice: once over the prefix that is already there, before the `mkdir`, and once after it, when the directory the entry lands in exists. Only the second question includes whether other local users could add a name inside that directory, because below the first question the directories are the caller's own to create, at its own mode. Deferring it is what keeps `mkdir -p /recordings` acceptable. -A publisher that creates no directories publishes only where the walk ARRIVED: stopping short means the name the caller gave is nowhere the entry can be written, and writing it into the nearest ancestor instead would publish a file nobody asked for. The one shape the pre-`mkdir` question refuses as well is a `..` queued BEHIND the absent component. The kernel cannot apply that step until the name before it exists, while a recursive `mkdir` resolves the same spelling as text and builds what stands on the far side of it: `private/missing/../../shared/recordings` never gets `shared` judged, and the `mkdir` that follows creates `/shared/recordings` in ground any local user can write, beside a `private/missing` of its own. Refusing it before the first `mkdir` is what makes "a refused destination leaves no directories behind" hold for a destination that steps back over ground it would have to create. A `..` over directories that all exist is applied one step at a time, exactly as the kernel applies it. -A RELATIVE destination is walked from `/` too, over the resolved working directory's components with the destination's own components following them raw. Standing the walk in the working directory instead would judge that directory and nothing above it, and the working directory is a name in its parent. That spelling is confirmed to be the directory the process stands in, by `dev:ino` against `.`: Node answers the working directory with the path the first query after `chdir` returned, so the name goes stale when the directory it names is moved, and a walk of the stale name judges a directory the process is not in while the kernel resolves the destination in the moved one. +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 — recursive `mkdir` applies the mode to every level it creates — and the walk runs again over the now-complete chain. 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 destination may name no directory at all, `journey.ad`, so its parent is the working directory: `cd /shared/mine` under a `/shared` at 0777 and not sticky, and the working directory itself is a name another local user can point elsewhere. Judging the working directory alone accepts this; the walk starts at `/` over its components, so `/shared` is judged too. +- 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. Both publishers stage inside that directory 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 path is read from the host once per walk, so an alias or a `..` back over ground already crossed does not ask the host again. 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 `passwd`, for `group`, and for `initgroups` — the database glibc reads SUPPLEMENTARY membership from, which those two files say nothing about. A database named on TWO lines establishes nothing either: glibc concatenates the sources of every line naming it and consults them in order, so `group: files` above `group: files sss` really does consult `sss`, and no single line says what the lookup reaches. An absent `initgroups:` line inherits the verified `group` setting, as the kernel does. `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. +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 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 judged 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. +The remote route captures the judged directory's `dev:ino` when it allocates staging and compares it once, under its record lock, right before the rename, because the download runs in between. That is the ONLY such comparison: the local publish does not repeat it. The ownership rule is what closes the window — anyone able to swap a judged directory was refused at it — and a second re-check would answer for a race the permissions rule already excludes. 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 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 index 1678c0f14e..347eaeeb44 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -13,10 +13,6 @@ import { makeAuthoringSession } from '../../__tests__/support/session-factories. const hostCwd = createLiveTestHostEnvironment().cwd; const skipOnWindows = process.platform === 'win32' ? test.skip : test; -const realReadFileSync = fs.readFileSync; -/** The account the fixtures name for this process, the same one the rule reads back out of passwd. */ -const currentUser = process.env.USER ?? ''; - /** 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; @@ -25,37 +21,6 @@ afterEach(() => { vi.restoreAllMocks(); }); -/** - * Serves `groups` and `passwd` for the two group files and the real host for everything else, so the - * private-group decision is the fixture's and this file's assertions run on every POSIX host instead of - * only on one whose `/etc/group` happens to agree. - */ -function serveGroupDatabase(groups: readonly string[], passwd: readonly string[]): void { - vi.spyOn(fs, 'readFileSync').mockImplementation(((file: unknown, options?: unknown) => { - if (file === '/etc/group') return `${groups.join('\n')}\n`; - if (file === '/etc/passwd') return `${passwd.join('\n')}\n`; - // The private-group exception is admitted only where the host's own databases are the whole story. - if (file === '/etc/nsswitch.conf') return 'passwd: files\ngroup: files\n'; - return realReadFileSync(file as never, options as never) as never; - }) as typeof fs.readFileSync); -} - -/** This host's user owning `currentGid` alone, plus a team group that holds someone else. */ -function privateGroupDatabase(): void { - serveGroupDatabase( - ['root:x:0:root', `${currentUser}:x:${currentGid}:`, 'team:x:4321:ada'], - ['root:x:0:0', `${currentUser}:x:${currentUid}:${currentGid}:`], - ); -} - -/** The same ids, with this host's group named after somebody else, so it is not private. */ -function foreignGroupNameDatabase(): void { - serveGroupDatabase( - ['root:x:0:root', `${currentUser}:x:${currentGid + 1}:`, 'team:x:4321:ada'], - ['root:x:0:0', `${currentUser}:x:${currentUid}:${currentGid}:`], - ); -} - function action(command: string): { ts: number; command: string; @@ -474,20 +439,10 @@ skipOnWindows('a recording refuses a link another local user owns on the way in' expect(fs.readdirSync(chosen)).toEqual([]); }); -skipOnWindows('a recording still saves to a group-writable private-group home', () => { - privateGroupDatabase(); - const directory = root(); - const home = homeDirectory(path.join(directory, 'home'), 0o775); - const destination = path.join(home, 'journey.ad'); - - const result = writerFor(directory).write(recordingTo(destination)); - - expect(result.written).toBe(true); - expect(fs.readFileSync(destination, 'utf8')).toContain('open'); -}); - -skipOnWindows("a recording refuses the same home once the group is not this user's own", () => { - foreignGroupNameDatabase(); +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); @@ -498,4 +453,28 @@ skipOnWindows("a recording refuses the same home once the group is not this user 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); }); diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index 587e0a3b5f..c22f725215 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -19,10 +19,7 @@ import { stripRecordedRefGeneration, } from '@agent-device/ad-script'; import { expandSessionPath, safeSessionName } from '@agent-device/host-kit/session-paths'; -import { - assertPrivateScriptDestinationPrefix, - publishScriptFileSync, -} 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, @@ -136,19 +133,13 @@ export class SessionScriptWriter { const remote = session.scriptPublication?.kind === 'authoring' && session.scriptPublication.remoteDelivery; scriptPath = remote ? this.remoteScriptPath() : this.resolveScriptPath(session); - const scriptDir = path.dirname(scriptPath); - // Asked BEFORE the parent is created, and again by the publisher once it exists: a `mkdir -p` into - // ground another local user can write would otherwise leave the directories it made behind them, - // even though the publish that follows is refused (#4565). The walk covers `scriptDir`'s own - // components, which is where `mkdir -p` would build a directory on the far side of a `..`. - assertPrivateScriptDestinationPrefix(scriptPath); - if (!fs.existsSync(scriptDir)) fs.mkdirSync(scriptDir, { recursive: true }); // #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. - // No parent identity travels with this call: the publisher judges the directory the entry is - // created in, and that is the one its identity is worth comparing. + // 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) { diff --git a/packages/host-kit/src/file.ts b/packages/host-kit/src/file.ts index f49c06a68b..37da1f9af8 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -1,8 +1,8 @@ export { assertPrivateScriptDestination, - assertPrivateScriptDestinationPrefix, isAtomicPublishTemporaryPath, lstatIfPresent, + prepareScriptDestination, publishDirectoryIdentity, publishDurableFileSync, publishFileSync, diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index f290d3b14d..d66c939491 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -1,6 +1,7 @@ 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, @@ -8,11 +9,8 @@ import { directoryWith, expectUntrusted, expectUntrustedReplaced, - hostDatabase, modeOf, publish, - serveGroupDatabase, - unreadableDatabases, } from './atomic-file-host.fixtures.ts'; import { assertPrivateScriptDestination, @@ -52,7 +50,6 @@ function serveOwnership(owners: Readonly>): void { // --- a directory another user owns, or that others can write, is refused --- skipOnWindows('publishes to a chain only this user can write', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const workflows = path.join(root(), 'workflows'); fs.mkdirSync(workflows); @@ -62,7 +59,6 @@ skipOnWindows('publishes to a chain only this user can write', () => { }); skipOnWindows('creates the script so that only this user can read it', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const workflows = path.join(root(), 'workflows'); fs.mkdirSync(workflows); const destination = path.join(workflows, 'journey.ad'); @@ -73,7 +69,6 @@ skipOnWindows('creates the script so that only this user can read it', () => { }); skipOnWindows('refuses a destination under a world-writable directory', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const shared = directoryWith(path.join(root(), 'shared'), 0o777); const destination = path.join(shared, 'journey.ad'); @@ -82,7 +77,6 @@ skipOnWindows('refuses a destination under a world-writable directory', () => { }); skipOnWindows('refuses a destination created inside a directory others can add entries to', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const shared = directoryWith(path.join(root(), 'shared'), 0o777 | 0o1000); expectUntrusted( @@ -94,7 +88,6 @@ skipOnWindows('refuses a destination created inside a directory others can add e }); skipOnWindows('refuses a destination under a group-writable shared directory', () => { - serveGroupDatabase(hostDatabase(4321, currentGid)); const team = directoryWith(path.join(root(), 'team'), 0o775, currentGid); const sub = path.join(team, 'sub'); fs.mkdirSync(sub); @@ -106,7 +99,6 @@ skipOnWindows('refuses a destination under a group-writable shared directory', ( // --- ownership decides, not the mode alone --- skipOnWindows('refuses a directory another user owns, whatever the mode', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const work = directoryWith(path.join(root(), 'foreign'), 0o755); serveOwnership({ [work]: FOREIGN_UID }); @@ -120,7 +112,6 @@ skipOnWindows('refuses a directory another user owns, whatever the mode', () => skipOnWindows( 'refuses a sticky directory another user owns, since both bits shield others from them', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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); @@ -139,7 +130,6 @@ skipOnWindows( skipOnWindows( 'refuses a recordings directory another local user created first in a sticky /tmp', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `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. @@ -158,7 +148,6 @@ skipOnWindows( ); skipOnWindows('refuses a link standing in a private-mode directory another user owns', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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 @@ -178,7 +167,6 @@ skipOnWindows('refuses a link standing in a private-mode directory another user }); skipOnWindows('refuses a private link standing on shared ground two levels up', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `/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 @@ -199,7 +187,6 @@ skipOnWindows('refuses a private link standing on shared ground two levels up', }); skipOnWindows('refuses a chain that leaves a shared directory through an intermediate link', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `~/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. @@ -223,7 +210,6 @@ skipOnWindows('refuses a chain that leaves a shared directory through an interme }); skipOnWindows('judges the directory a .. steps back into', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `/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 @@ -244,7 +230,6 @@ skipOnWindows('judges the directory a .. steps back into', () => { }); skipOnWindows('refuses the ground under a link that leads into a shared directory', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `/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 @@ -269,7 +254,6 @@ skipOnWindows('refuses the ground under a link that leads into a shared director skipOnWindows( 'refuses a link whose target is spelled relative to the directory that holds it', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `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 @@ -296,7 +280,6 @@ skipOnWindows( skipOnWindows( 'stages the temp file inside the directory the walk judged, not the spelled parent', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `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 @@ -327,7 +310,6 @@ skipOnWindows( ); skipOnWindows('reads each directory it stands in once, however many routes lead back to it', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `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 @@ -356,127 +338,35 @@ skipOnWindows('reads each directory it stands in once, however many routes lead expect(reads.filter((read) => read === home)).toHaveLength(1); }); -skipOnWindows('starts a destination with no directory in it at the working directory', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - // `journey.ad` names the working directory as its parent, which is where the entry is created. Treated - // as having NO parent, the walk starts at `/` instead, and a caller that reported the identity of `.` - // is told its parent was replaced. - const cwd = path.resolve(''); - const identity = publishDirectoryIdentity('.'); - - expect(identity).toBeDefined(); - expect(assertPrivateScriptDestination('journey.ad', identity)).toBe(cwd); -}); - skipOnWindows( - 'refuses a relative destination whose working directory sits in shared ground', + 'refuses a destination that is not absolute, before judging or creating anything', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - // `cd /shared/mine && publish journey.ad` where `/shared` is 0777 and NOT sticky. The destination names - // no directory at all, so the tempting answer is to start the walk in the working directory and judge - // it. That judges `mine` and nothing above it, and `mine` is a name in `/shared`: anyone who can add an - // entry there can point `mine` at a directory of their own before the rename, which is the swap this - // rule exists to refuse. So a relative destination is walked from the root, over the working - // directory's own components, and `/shared` is judged like any other ancestor. - const directory = root(); - const shared = directoryWith(path.join(directory, 'shared'), 0o777); - const mine = directoryWith(path.join(shared, 'mine'), 0o700); - const previous = path.resolve(''); - try { - process.chdir(mine); - - expectUntrusted(() => publish('journey.ad'), 'world_writable', shared); - expect(fs.readdirSync(mine)).toEqual([]); - } finally { - process.chdir(previous); - } - }, -); - -skipOnWindows('answers the working directory for a relative destination over a safe chain', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - // The same shape with every ancestor private: the answer is the ABSOLUTE working directory, which is - // what the publisher stages in, and the identity a caller captured for `.` matches it. - const directory = root(); - const home = directoryWith(path.join(directory, 'home'), 0o700); - const mine = directoryWith(path.join(home, 'mine'), 0o700); - const previous = path.resolve(''); - try { - process.chdir(mine); - const identity = publishDirectoryIdentity('.'); - - expect(assertPrivateScriptDestination('journey.ad', identity)).toBe(mine); - } finally { - process.chdir(previous); - } -}); - -skipOnWindows( - 'refuses a relative destination whose working directory has been moved out from under it', - () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - // Node answers the working directory with the path getcwd handed it the first time anything asked, so - // that spelling goes stale the moment the directory it names is moved — the process keeps working, and - // only the two answers disagree. `cd `, ASK the working directory (which is what settling the - // cache means, and what any caller that resolves a path does), then move `` and plant another - // private directory at its old path. A walk of the remembered spelling judges the planted directory, - // finds it publishable, and stages in it; the kernel then resolves `journey.ad` in the MOVED one, so - // the entry is created in ground the rule never reached. Comparing the remembered spelling with `.` is - // what refuses this, and publishing through the judged directory is what would stop the entry moving - // even if the comparison were skipped. + // 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 mine = directoryWith(path.join(home, 'mine'), 0o700); const previous = process.cwd(); try { - process.chdir(mine); - const remembered = path.resolve(''); - const moved = path.join(home, 'moved'); - fs.renameSync(mine, moved); - directoryWith(mine, 0o700); - // The attacker's directory is the one the process is really in: open to everyone, and owned by this - // user, so nothing about it looks untrusted from the inside. - fs.chmodSync(moved, 0o777); - - expectUntrustedReplaced(() => publish('journey.ad'), remembered); - expect(fs.readdirSync(mine)).toEqual([]); - expect(fs.readdirSync(moved)).toEqual([]); + process.chdir(home); + + expectUntrusted(() => publish('journey.ad'), 'relative_destination', '.'); + expectUntrusted( + () => assertPrivateScriptDestination('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('publishes a relative destination into the working directory it judged', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - // Nothing is refused here: the working directory is where the process stands, so the spelling the walk - // judged and the directory the kernel resolves are one directory. The entry is still created IN THAT - // DIRECTORY, spelled from it, and not by handing the kernel the relative destination back: the answer - // the walk gave is the one thing this call knows about where the bytes belong, and a relative name asks - // the kernel to answer the question a second time, from whatever the working directory is by then. - const directory = root(); - const home = directoryWith(path.join(directory, 'home'), 0o700); - const mine = directoryWith(path.join(home, 'mine'), 0o700); - const published: string[] = []; - const realRenameSync = fs.renameSync; - vi.spyOn(fs, 'renameSync').mockImplementation(((existing: unknown, newPath: unknown) => { - published.push(String(newPath)); - return (realRenameSync as (...args: unknown[]) => unknown)(existing, newPath); - }) as typeof fs.renameSync); - const previous = process.cwd(); - try { - process.chdir(mine); - publish('journey.ad'); - } finally { - process.chdir(previous); - } - - expect(published).toEqual([path.join(mine, 'journey.ad')]); - expect(fs.readdirSync(mine)).toEqual(['journey.ad']); -}); - skipOnWindows('refuses a relative target that lands in ground others can write', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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); @@ -492,7 +382,6 @@ skipOnWindows('refuses a relative target that lands in ground others can write', }); skipOnWindows('applies a .. inside a target to the directory the walk reached', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `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. @@ -514,7 +403,6 @@ skipOnWindows('applies a .. inside a target to the directory the walk reached', }); skipOnWindows('follows a relative target that stays inside ground only this user can write', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); const home = directoryWith(path.join(directory, 'home'), 0o700); const real = directoryWith(path.join(directory, 'outside'), 0o700); @@ -526,7 +414,6 @@ skipOnWindows('follows a relative target that stays inside ground only this user }); skipOnWindows('refuses the spelled spelling of a link the walk also follows', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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(); @@ -549,7 +436,6 @@ skipOnWindows('refuses the spelled spelling of a link the walk also follows', () }); skipOnWindows('applies .. to the directory the walk is in, not to the spelling', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `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. @@ -571,7 +457,6 @@ skipOnWindows('applies .. to the directory the walk is in, not to the spelling', }); skipOnWindows('refuses a link whose target stands in ground another local user owns', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `~/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. @@ -593,7 +478,6 @@ skipOnWindows('refuses a link whose target stands in ground another local user o }); skipOnWindows('follows a link whatever mode it carries, judging the directory it lands in', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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. @@ -615,7 +499,6 @@ skipOnWindows('follows a link whatever mode it carries, judging the directory it }); skipOnWindows('refuses a link loop instead of trusting where the walk ran out', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); const work = directoryWith(path.join(directory, 'work'), 0o700); const loop = path.join(work, 'loop'); @@ -630,7 +513,6 @@ skipOnWindows('refuses a link loop instead of trusting where the walk ran out', }); skipOnWindows('follows thirty link hops, and refuses the thirty-first', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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 @@ -665,7 +547,6 @@ skipOnWindows('follows thirty link hops, and refuses the thirty-first', () => { }); skipOnWindows('refuses a path component that cannot carry a publish', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); const work = directoryWith(path.join(directory, 'work'), 0o700); const blocker = path.join(work, 'blocker'); @@ -678,62 +559,35 @@ skipOnWindows('refuses a path component that cannot carry a publish', () => { ); }); -skipOnWindows('refuses a directory its owner opened up while the file was staged', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - const work = path.join(root(), 'work'); - fs.mkdirSync(work); - const destination = path.join(work, 'journey.ad'); - const realWriteFileSync = fs.writeFileSync; - vi.spyOn(fs, 'writeFileSync').mockImplementation(((file: unknown, ...rest: unknown[]) => { - const result = (realWriteFileSync as (...args: unknown[]) => unknown)(file, ...rest); - fs.chmodSync(work, 0o777); - return result; - }) as typeof fs.writeFileSync); - - expectUntrusted(() => publish(destination), 'world_writable', work); - expect(fs.readdirSync(work)).toEqual([]); -}); - -// --- the Ubuntu and Debian private-group home keeps working --- - -skipOnWindows('publishes to a group-writable home directory of a private group', () => { - const gid = currentGid; - serveGroupDatabase(hostDatabase(gid, 4321)); - const home = directoryWith(path.join(root(), 'home'), 0o775, gid); +// --- a group-writable directory is refused, whoever owns the group (ADR 0016) --- - publish(path.join(home, 'journey.ad')); - - expect(fs.readFileSync(path.join(home, 'journey.ad'), 'utf8')).toBe('context\n'); -}); - -skipOnWindows("refuses the same mode and group once the group is not the user's own", () => { - serveGroupDatabase(hostDatabase(4321, currentGid)); +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, currentGid); + 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 the same mode and group once the group database cannot be read', () => { - serveGroupDatabase(unreadableDatabases()); - const home = directoryWith(path.join(root(), 'home'), 0o775, currentGid); +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, currentGid); expectUntrusted(() => publish(path.join(home, 'journey.ad')), 'shared_group_writable', home); }); -skipOnWindows('publishes to a setgid group-writable private-group home', () => { - const gid = currentGid; - serveGroupDatabase(hostDatabase(gid, 4321)); - const home = directoryWith(path.join(root(), 'home'), 0o2775, gid); - - publish(path.join(home, 'journey.ad')); - - expect(fs.existsSync(path.join(home, 'journey.ad'))).toBe(true); -}); - // --- 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', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); const real = path.join(directory, 'real'); fs.mkdirSync(real); @@ -745,7 +599,6 @@ skipOnWindows('follows a symbolic link inside a directory only this user can wri }); skipOnWindows('refuses a link planted in a directory others can add entries to', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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(); @@ -763,7 +616,6 @@ skipOnWindows('refuses a link planted in a directory others can add entries to', }); skipOnWindows('refuses a private link whose target chain is a shared directory', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // `~/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. @@ -786,7 +638,6 @@ skipOnWindows('refuses a private link whose target chain is a shared directory', }); skipOnWindows('refuses a symbolic link whose target is a directory others can write', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); const shared = directoryWith(path.join(directory, 'shared'), 0o777); const privateWork = path.join(shared, 'private'); @@ -803,7 +654,6 @@ skipOnWindows('refuses a symbolic link whose target is a directory others can wr skipOnWindows( 'refuses a symbolic link another local user owns in a sticky shared directory', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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. @@ -825,7 +675,6 @@ skipOnWindows( ); skipOnWindows('keeps working through a root-owned alias whose target is sticky', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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 @@ -848,7 +697,6 @@ skipOnWindows('keeps working through a root-owned alias whose target is sticky', }); skipOnWindows('publishes under the host root-owned system temporary directory', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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. @@ -864,7 +712,6 @@ skipOnWindows('publishes under the host root-owned system temporary directory', }); skipOnWindows('publishes to a path spelled through an alias of the directory that holds it', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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(); @@ -879,7 +726,6 @@ skipOnWindows('publishes to a path spelled through an alias of the directory tha }); skipOnWindows('publishes to a scratch path exactly as the host spelled it', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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. @@ -893,13 +739,12 @@ skipOnWindows('publishes to a scratch path exactly as the host spelled it', () = // --- the destination directory swapped out while the file was staged --- -// The identity a caller captures before it stages something is handed back to -// `assertPrivateScriptDestination`, which is what compares them. The script publisher takes it from the -// directory the walk judged, so only a caller who captured it EARLIER — the remote client, across a -// download — passes one from outside. These two are that comparison. +// Only a caller that captured the identity EARLIER passes one: 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 remote route's single comparison. skipOnWindows('refuses a parent replaced by name while the file was staged', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); const staged = path.join(directory, 'work'); fs.mkdirSync(staged); @@ -922,30 +767,7 @@ skipOnWindows('refuses a parent replaced by name while the file was staged', () expect(fs.existsSync(path.join(elsewhere, 'journey.ad'))).toBe(false); }); -skipOnWindows('re-checks the chain after staging the file, before the entry is created', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - const directory = root(); - const staged = path.join(directory, 'work'); - fs.mkdirSync(staged); - const destination = path.join(staged, 'journey.ad'); - const attacker = path.join(directory, 'attacker'); - fs.mkdirSync(attacker); - const writeFileSync = fs.writeFileSync; - vi.spyOn(fs, 'writeFileSync').mockImplementation(((file: unknown, ...rest: unknown[]) => { - const result = (writeFileSync as (...args: unknown[]) => unknown)(file, ...rest); - // The directory the file was staged in is gone and its name is somebody else's now. A filesystem - // hands back a freed inode, so the swap has to be to a directory that is really another one. - fs.rmSync(staged, { recursive: true, force: true }); - fs.symlinkSync(attacker, staged); - return result; - }) as typeof fs.writeFileSync); - - expectUntrustedReplaced(() => publish(destination), attacker); - expect(fs.readdirSync(attacker)).toEqual([]); -}); - skipOnWindows('accepts the identity a caller captured for the directory the walk answers', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); const directory = root(); const staged = path.join(directory, 'work'); fs.mkdirSync(staged); diff --git a/packages/host-kit/src/internal/atomic-file-decisions.test.ts b/packages/host-kit/src/internal/atomic-file-decisions.test.ts index 196db606cc..7e73dd2f2f 100644 --- a/packages/host-kit/src/internal/atomic-file-decisions.test.ts +++ b/packages/host-kit/src/internal/atomic-file-decisions.test.ts @@ -17,7 +17,7 @@ const currentGid = process.getgid?.() ?? -1; // --- what makes one directory unsafe to publish inside --- const OWN = { uid: currentUid, gid: currentGid, mode: 0o755 }; -const TRUST = { uid: currentUid, privateGid: currentGid }; +const TRUST = { uid: currentUid }; function directoryOf(overrides: Partial): DirectoryAuthority { return { ...OWN, ...overrides }; @@ -36,14 +36,19 @@ 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 by a group that is not this user', () => { +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, so `gid` does not enter the answer. expect(untrustedAncestryExposure(directoryOf({ gid: 4321, mode: 0o775 }), TRUST)).toBe( 'shared_group_writable', ); -}); - -test('accepts a directory group-writable by this user', () => { - expect(untrustedAncestryExposure(directoryOf({ mode: 0o775 }), TRUST)).toBeUndefined(); + 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', () => { @@ -70,7 +75,13 @@ test('refuses a sticky directory another user owns, since both bits shield other 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({ mode: 0o775 }), 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', () => { @@ -93,13 +104,12 @@ test('accepts a link this user or root owns in a sticky shared directory', () => 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({ gid: 4321, mode: 0o775 }), TRUST)).toBe(true); + expect(othersCreateEntriesIn(directoryOf({ mode: 0o775 }), TRUST)).toBe(true); }); -test('names no directory whose group is this user', () => { - expect(othersCreateEntriesIn(directoryOf({ mode: 0o775 }), TRUST)).toBe(false); - expect(othersCreateEntriesIn(directoryOf({ mode: 0o1775 }), TRUST)).toBe(false); +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', () => { diff --git a/packages/host-kit/src/internal/atomic-file-host.fixtures.ts b/packages/host-kit/src/internal/atomic-file-host.fixtures.ts index 45b8b26fcb..7f0fd17833 100644 --- a/packages/host-kit/src/internal/atomic-file-host.fixtures.ts +++ b/packages/host-kit/src/internal/atomic-file-host.fixtures.ts @@ -1,74 +1,17 @@ -// The host this suite's destinations are judged against: a group and passwd database the test names, -// directory owners the 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 those two alone is asserting against whatever -// accounts and modes the machine it runs on happens to have. +// 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, vi } from 'vitest'; +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'; -/** The group database a test stands in for `/etc/group` and `/etc/passwd`. */ -export type Database = Readonly<{ - groups: readonly string[] | undefined; - passwd: readonly string[] | undefined; - /** `undefined` means "only files"; an empty array means "the file cannot be read". */ - nsswitch?: readonly string[] | undefined; -}>; - -const realReadFileSync = fs.readFileSync; - -/** - * The account the fixture's databases name for this process. `readCurrentUser()` reads it from - * `passwdFile` below, so the fixture and the rule agree without a second host lookup. - */ -export const currentUser = process.env.USER ?? ''; - /** This process's ids. Windows has neither, and every test that uses them is skipped there. */ export const currentUid = process.getuid?.() ?? -1; export const currentGid = process.getgid?.() ?? -1; -/** - * Serves `database` for the two group files and the real host for everything else, so the - * private-group decision is the fixture's and not the CI image's user list. - */ -export function serveGroupDatabase(database: Database): void { - vi.spyOn(fs, 'readFileSync').mockImplementation(((file: unknown, options?: unknown) => { - if (file === '/etc/group') { - if (!database.groups) throw new Error('simulated unreadable group file'); - return `${database.groups.join('\n')}\n`; - } - if (file === '/etc/passwd') { - if (!database.passwd) throw new Error('simulated unreadable passwd file'); - return `${database.passwd.join('\n')}\n`; - } - if (file === '/etc/nsswitch.conf') return nsswitchContents(database.nsswitch); - return realReadFileSync(file as never, options as never) as never; - }) as typeof fs.readFileSync); -} - -/** The name-service lines of the fixture host: `files` only, unless the test asks for more. */ -function nsswitchContents(sources: readonly string[] | undefined): string { - if (sources === undefined) return 'passwd: files\ngroup: files\n'; - if (sources.length === 0) throw new Error('simulated unreadable nsswitch.conf'); - return `${sources.join('\n')}\n`; -} - -/** This host's user with a group of their own, and a team group that holds someone else. */ -export function hostDatabase(privateGid: number, sharedGid: number): Database { - return { - groups: ['root:x:0:root', `${currentUser}:x:${privateGid}:`, `team:x:${sharedGid}:ada`], - passwd: [`root:x:0:0`, `${currentUser}:x:${currentUid}:${privateGid}:`], - nsswitch: undefined, - }; -} - -/** The database of a host whose group files cannot be read at all. */ -export function unreadableDatabases(): Database { - return { groups: undefined, passwd: undefined }; -} - /** Some other local user, not this one and not root. */ export const FOREIGN_UID = 65534; @@ -93,6 +36,16 @@ 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); } diff --git a/packages/host-kit/src/internal/atomic-file-parent.test.ts b/packages/host-kit/src/internal/atomic-file-parent.test.ts index 33bc3476db..d1b670519e 100644 --- a/packages/host-kit/src/internal/atomic-file-parent.test.ts +++ b/packages/host-kit/src/internal/atomic-file-parent.test.ts @@ -1,50 +1,45 @@ -// Whether a destination's parent can be RESOLVED at all, and what the 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'; +// 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 { expect, test } from 'vitest'; import fs from 'node:fs'; import path from 'node:path'; import { ancestryRoot as root, - currentGid, directoryWith, expectUntrusted, - hostDatabase, + modeOf, publish, - serveGroupDatabase, + withSharedUmask, } from './atomic-file-host.fixtures.ts'; -import { assertPrivateScriptDestination } from './atomic-file.ts'; +import { assertPrivateScriptDestination, 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`; -skipOnWindows('refuses a destination that steps back out of a missing directory', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - // 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. A - // destination that would be resolved by creating it is refused, and nothing is created on the way. - 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( - () => assertPrivateScriptDestination(destination), - 'unresolvable_parent', - privateDir, - ); - expect(fs.readdirSync(privateDir)).toEqual([]); - expect(fs.readdirSync(shared)).toEqual([]); -}); + 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', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); // 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. @@ -59,15 +54,50 @@ skipOnWindows('accepts a destination that steps back over directories that all e 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); + }); + + 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 does not exist, and publishes nowhere', () => { - serveGroupDatabase(hostDatabase(currentGid, 4321)); - // This publisher creates no directories, so a walk that stopped at an absent name has no answer to - // publish into. The nearest ancestor it did reach would be a file the caller never asked for: - // `root/journey.ad` instead of `root/missing/journey.ad`. + // `assertPrivateScriptDestination` creates nothing, so a walk that stopped at an absent name has no + // answer to publish into. The nearest ancestor it did reach would be a file the caller never asked + // for: `root/journey.ad` instead of `root/missing/journey.ad`. const directory = root(); const missing = path.join(directory, 'missing'); const destination = path.join(missing, 'journey.ad'); - expectUntrusted(() => publish(destination), 'unreachable_parent', directory); + expectUntrusted( + () => assertPrivateScriptDestination(destination), + 'unreachable_parent', + directory, + ); expect(fs.readdirSync(directory)).toEqual([]); }); diff --git a/packages/host-kit/src/internal/atomic-file-private-group.test.ts b/packages/host-kit/src/internal/atomic-file-private-group.test.ts deleted file mode 100644 index c74515fc12..0000000000 --- a/packages/host-kit/src/internal/atomic-file-private-group.test.ts +++ /dev/null @@ -1,181 +0,0 @@ -// privateGroupId: the one group shape the destination-ancestry rule admits, and what a name service -// does to that claim. Both are pure decisions over host account records, so they are judged here rather -// than through a filesystem. - -import { expect, test } from 'vitest'; -import { nameServiceListsOnlyFiles, privateGroupId } from './atomic-file.ts'; - -const ADA = { uid: 1000, gid: 1000, name: 'ada' }; - -const FILES = ['passwd: files', 'group: files']; - -function database(groups: readonly string[] | undefined, passwd: readonly string[] | undefined) { - return { groups, passwd, nsswitch: FILES }; -} - -const PRIVATE = ['ada:x:1000:', 'staff:x:20:root']; -const PRIVATE_PASSWD = ['ada:x:1000:1000:', 'root:x:0:0']; - -test('admits the group named after the user, holding only them, as their primary group', () => { - expect(privateGroupId(database(PRIVATE, PRIVATE_PASSWD), ADA)).toBe(1000); -}); - -test('admits root named among the members, the account the whole rule trusts', () => { - expect( - privateGroupId(database(['ada:x:1000:root'], ['ada:x:1000:1000:', 'root:x:0:0']), ADA), - ).toBe(1000); -}); - -test('refuses a second group carrying the same gid when it lists another user', () => { - // `ada:x:1000:` looks private on its own, and the group named after the user is the only one the - // exception used to read. A directory group-writable by gid 1000 is writable by grace too, because - // `team` carries the same number. - expect( - privateGroupId( - database( - ['ada:x:1000:', 'team:x:1000:grace'], - ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0'], - ), - ADA, - ), - ).toBeUndefined(); -}); - -test('admits a second group carrying the same gid when it reaches nobody else', () => { - expect( - privateGroupId( - database(['ada:x:1000:', 'ada-alias:x:1000:'], ['ada:x:1000:1000:', 'root:x:0:0']), - ADA, - ), - ).toBe(1000); -}); - -test('refuses it once a second group sharing the gid has another user as its primary group', () => { - expect( - privateGroupId( - database(['ada:x:1000:', 'team:x:1000:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), - ADA, - ), - ).toBeUndefined(); -}); - -test('refuses it once another user is a member', () => { - expect( - privateGroupId( - database(['ada:x:1000:grace'], ['ada:x:1000:1000:', 'grace:x:1001:1001:', 'root:x:0:0']), - ADA, - ), - ).toBeUndefined(); -}); - -test('refuses it once another user has it as their primary group', () => { - expect( - privateGroupId(database(['ada:x:1000:'], ['ada:x:1000:1000:', 'grace:x:1001:1000:']), ADA), - ).toBeUndefined(); -}); - -test('refuses a group that is not the primary group of the user, however few members it lists', () => { - expect(privateGroupId(database(['ada:x:4321:'], ['ada:x:1000:1000:']), ADA)).toBeUndefined(); -}); - -test('refuses a group that does not carry the name of the user', () => { - expect(privateGroupId(database(['team:x:1000:'], ['ada:x:1000:1000:']), ADA)).toBeUndefined(); -}); - -test('refuses it when the group file cannot be read', () => { - expect(privateGroupId(database(undefined, PRIVATE_PASSWD), ADA)).toBeUndefined(); -}); - -test('refuses it when the passwd file cannot be read', () => { - expect(privateGroupId(database(PRIVATE, undefined), ADA)).toBeUndefined(); -}); - -test('refuses it when the user has no passwd record', () => { - expect(privateGroupId(database(PRIVATE, ['root:x:0:0']), ADA)).toBeUndefined(); -}); - -test('refuses it when the passwd record names another uid or gid', () => { - const other = { uid: 1002, gid: 1000, name: 'ada' }; - expect(privateGroupId(database(PRIVATE, PRIVATE_PASSWD), other)).toBeUndefined(); -}); - -test('refuses it when /etc/nsswitch.conf cannot be read', () => { - expect( - privateGroupId({ groups: PRIVATE, passwd: PRIVATE_PASSWD, nsswitch: undefined }, ADA), - ).toBeUndefined(); -}); - -test('refuses it when nsswitch.conf adds a name service to either database', () => { - const withNameService = (databaseLines: string[]) => - privateGroupId({ groups: PRIVATE, passwd: PRIVATE_PASSWD, nsswitch: databaseLines }, ADA); - - expect(withNameService(['passwd: files ldap', 'group: files'])).toBeUndefined(); - expect(withNameService(['passwd: files', 'group: files sss'])).toBeUndefined(); - // `systemd` is the default on some distributions and is still refused: userdbd answers membership from - // records these two files never show. - expect(withNameService(['passwd: files systemd', 'group: files systemd'])).toBeUndefined(); - expect(withNameService(['passwd: files', 'group:'])).toBeUndefined(); - expect(withNameService(['# no database lines here'])).toBeUndefined(); -}); - -test('refuses it when initgroups names a service, the database supplementary membership comes from', () => { - // glibc reads SUPPLEMENTARY group membership from `initgroups:`. `passwd: files` and `group: files` - // say nothing about it, so a service there can hold a member of this gid that neither file shows. - const withInitgroups = (line: string) => - privateGroupId( - { - groups: PRIVATE, - passwd: PRIVATE_PASSWD, - nsswitch: ['passwd: files', 'group: files', line], - }, - ADA, - ); - - expect(withInitgroups('initgroups: sss')).toBeUndefined(); - expect(withInitgroups('initgroups: ldap files')).toBeUndefined(); - expect(withInitgroups('initgroups: systemd')).toBeUndefined(); - // An absent line inherits the `group` setting, which is what the kernel does and what was verified. - expect(privateGroupId({ groups: PRIVATE, passwd: PRIVATE_PASSWD, nsswitch: FILES }, ADA)).toBe( - 1000, - ); - expect(withInitgroups('initgroups: files')).toBe(1000); -}); - -test('refuses it when a database is named twice, whichever order the lines come in', () => { - // glibc CONCATENATES the sources of every line naming a database and consults them in order, so - // `group: files` above `group: files sss` really does consult `sss`. No single line here therefore says - // what the lookup consults, and the exception is refused rather than settled by the first line, the last - // line, or the shorter list. `initgroups:` inherits the `group` setting only when it is ABSENT; a second - // `initgroups:` line is the same concatenation problem. - const withLines = (lines: string[]) => - privateGroupId({ groups: PRIVATE, passwd: PRIVATE_PASSWD, nsswitch: lines }, ADA); - - expect(withLines(['passwd: files', 'group: files', 'group: files sss'])).toBeUndefined(); - // The order that looks harmless from the other end: the refused source comes FIRST, so keeping the last - // line would also admit it. - expect(withLines(['passwd: files', 'group: files sss', 'group: files'])).toBeUndefined(); - expect(withLines(['passwd: files', 'group: files', 'passwd: files ldap'])).toBeUndefined(); - expect( - withLines(['passwd: files', 'group: files', 'initgroups: files', 'initgroups: files sss']), - ).toBeUndefined(); - // Repeating a database with the SAME sources establishes nothing more either: glibc would consult - // `files` twice, and this rule cannot tell that pair apart from the pair above. - expect(withLines(['passwd: files', 'group: files', 'group: files'])).toBeUndefined(); -}); - -test('admits a name service line that names only files, actions and comments aside', () => { - expect( - nameServiceListsOnlyFiles(['passwd: [NOTFOUND=return] files # local only', 'group: files']), - ).toBe(true); - expect(nameServiceListsOnlyFiles(['passwd: files', 'group: files db'])).toBe(false); - expect(nameServiceListsOnlyFiles(undefined)).toBe(false); - // One database, two lines: see the refusal above. A repeated database is refused whoever owns the line. - expect(nameServiceListsOnlyFiles(['passwd: files', 'passwd: files', 'group: files'])).toBe(false); -}); - -test('gives a caller without a full identity no private group', () => { - const groups = database(PRIVATE, PRIVATE_PASSWD); - expect(privateGroupId(groups, { uid: undefined, gid: 1000, name: 'ada' })).toBeUndefined(); - expect(privateGroupId(groups, { uid: 1000, gid: undefined, name: 'ada' })).toBeUndefined(); - expect(privateGroupId(groups, { uid: 1000, gid: 1000, name: undefined })).toBeUndefined(); -}); diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index ce07693beb..0884029ee8 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -46,31 +46,24 @@ 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): the chain is refused before - * anything is staged and judged again before the link or rename. The file is private, because a recording - * is a transcript of what someone did on this machine. - * - * `parentIdentity` is what {@link publishDirectoryIdentity} returned for a parent the caller created or - * checked before it staged this file. + * 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 { - // The directory the entry is created in is the walk's ANSWER, asked for twice inside this call 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. let temporaryPath: string | undefined; try { - const judged = assertPrivateScriptDestination(options.destination); - const expected = publishDirectoryIdentity(judged); + // 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); temporaryPath = createAtomicPublishTempPath(judged, options.destination); fs.writeFileSync(temporaryPath, options.contents, { encoding: 'utf8', mode: SCRIPT_FILE_MODE }); - const stillJudged = assertPrivateScriptDestination(options.destination, expected); - if (stillJudged !== judged) { - throw scriptAncestryFailure(options.destination, stillJudged, 'parent_replaced'); - } // 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. @@ -116,6 +109,56 @@ function removeTempBestEffort(destination: string, temporaryPath: string | undef /** 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. A recursive `mkdir` applies the mode to every + * level it creates, so a creation on the usual umask-002 host is not left 0775 and then refused. + */ +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 destination the rule refuses is refused BEFORE + * anything is created, what is missing is created at {@link SCRIPT_DIR_MODE} inside the directory the + * walk judged, and the now-complete chain is JUDGED again before the answer. A caller never hands its own + * `mkdir` to a path this rule has not stopped first. + * + * The second walk asks the creation question — whether other local users could add the destination's own + * name inside the directory the walk ended in. The first walk does not, because below it the missing + * directories are this call's own to create, at 0700, which is what keeps + * `mkdir -p /recordings` acceptable. + * + * A `..` queued behind the first component that does not exist is refused by the FIRST walk: creating + * cannot resolve it, because the kernel applies that step only to a directory that already exists, while + * a recursive `mkdir` resolves the same spelling as text and builds what stands on the far side of it. + * + * On Windows access is an ACL rather than a mode, so the rule is a no-op and the parent is the answer. + */ +export function prepareScriptDestination(destination: string): string { + if (process.platform === 'win32') { + const parent = path.dirname(path.resolve(destination)); + fs.mkdirSync(parent, { recursive: true, mode: SCRIPT_DIR_MODE }); + return parent; + } + const spelled = spelledParent(destination); + const trust = scriptTrust(); + const walked = walkSpelledParent(spelled, destination, trust); + if (walked.reject !== undefined) throw walked.reject; + if (walked.unresolvable) { + throw scriptAncestryFailure(destination, walked.deepest, 'unresolvable_parent'); + } + // Where the chain already stands, this walk judged the directory the entry is created in and there is + // nothing to create, so it is also the answer. Only a walk that stopped short walks again. + if (walked.arrived) return publishableDirectory(destination, walked, trust); + fs.mkdirSync(path.join(walked.deepest, ...walked.missing), { + recursive: true, + mode: SCRIPT_DIR_MODE, + }); + return publishableDirectory(destination, walkSpelledParent(spelled, destination, trust), trust); +} + export type DurableFilePublishMode = 'replace' | 'link-exclusive'; /** Publishes complete UTF-8 contents with a durable file and directory fence. */ @@ -263,126 +306,75 @@ function statOrNull(pathname: string): fs.Stats | undefined { * the mode, with the sticky bit excusing only passing THROUGH. {@link othersCreateEntriesIn} is asked * separately of the directory the walk ended in, because that bit cannot refuse a NEW entry by name, and * every followed link is judged by {@link untrustedLinkExposure} against the directory that holds it. - * A group-writable directory stays acceptable when its group is this user's own private group, the shape - * Ubuntu and Debian give home directories; {@link privateGroupId} says what that takes to establish. + * A group-writable directory is refused outright: membership cannot be proven from the host's account + * files, so ADR 0016 carries no private-group exception, and the hint says to `chmod g-w` the directory. * * A component that is neither a directory nor a link is refused as `not_a_directory`: the kernel cannot * travel through it either. On Windows access is an ACL, so this rule is a no-op and answers the parent * it was given. * - * `parentIdentity` is what {@link publishDirectoryIdentity} returned for the parent the caller created - * or checked before it staged this file. The rule above already excludes anyone who could swap it, so the - * comparison is defense in depth against a host whose modes moved meanwhile, not what closes the window. + * `parentIdentity` is what {@link publishDirectoryIdentity} returned for the directory an earlier walk + * judged. Only the remote route passes one, because a download runs between its two walks: the rule above + * already excludes anyone who could swap that directory, so the comparison is defense in depth against a + * host whose modes moved meanwhile, not what closes the window. */ export function assertPrivateScriptDestination( destination: string, parentIdentity?: string, ): string { if (process.platform === 'win32') return path.dirname(path.resolve(destination)); - const trust = readScriptTrust(); - const walk = walkParent(destination, trust); - if (walk.reject !== undefined) throw walk.reject; + const trust = scriptTrust(); + const walk = walkSpelledParent(spelledParent(destination), destination, trust); if (walk.unresolvable) { throw scriptAncestryFailure(destination, walk.deepest, 'unresolvable_parent'); } + return publishableDirectory(destination, walk, trust, parentIdentity); +} + +/** + * Judges a finished walk and reports the directory to create the entry in. + * + * 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 the nearest ancestor it did reach is a file under a name nobody asked for. + * + * The identity is asked of the directory the walk answered, which is NOT `path.dirname` of the spelling: + * where a `..` or a link leads elsewhere, the spelled parent is a different directory and comparing + * against it reports a replacement that never happened. + */ +function publishableDirectory( + destination: string, + walk: WalkOutcome, + trust: ScriptDestinationTrust, + parentIdentity?: string, +): string { + if (walk.reject !== undefined) throw walk.reject; if (!walk.arrived) { - // The walk stopped at a name that does not exist. A publisher that creates no directories has - // nowhere to write, and writing the entry into the nearest ancestor instead would publish it under - // a name the caller never gave it. throw scriptAncestryFailure(destination, walk.deepest, 'unreachable_parent'); } - // The identity is asked of the directory the entry is created in, which is the walk's answer and NOT - // `path.dirname` of the spelling: where a `..` or a link leads elsewhere, the spelled parent is a - // different directory and comparing against it reports a replacement that never happened. if (parentIdentity !== undefined && publishDirectoryIdentity(walk.deepest) !== parentIdentity) { throw scriptAncestryFailure(destination, walk.deepest, 'parent_replaced'); } - // The script entry is created inside the deepest directory the walk reached, or below it through - // directories that do not exist yet. Where other local users can add entries, one of them can add - // this entry first and the recording is theirs, so the creation has to be refused. The authority the - // walk read there is reused rather than read again. - if (walk.authority !== undefined && othersCreateEntriesIn(walk.authority, trust)) { + // Where other local users can add entries here, one of them can add this entry first and the + // recording is theirs. The authority the walk read is reused rather than read again. + if (othersCreateEntriesIn(walk.authority, trust)) { throw scriptAncestryFailure(destination, walk.deepest, 'shared_parent'); } return walk.deepest; } /** - * Refuses a script destination before its caller creates anything on the way to it, answering whether - * the caller's `mkdir` may run. Callers that create a missing parent run this first, then create, then - * run {@link assertPrivateScriptDestination} once the directory the entry lands in exists. - * - * It is the same walk, not a second rule: it stops at the first component that does not exist, so asking - * it before the `mkdir` judges exactly the prefix that is already there. Two questions the full rule asks - * are deliberately NOT asked here: the creation question — others adding a name inside the directory the - * walk ends in — because the directories below are the caller's own to create, at its own mode, which is - * what keeps `mkdir -p /recordings` acceptable; and the arrival question, because the - * missing tail is what the `mkdir` is for. - * - * A `..` queued BEHIND the absent component stops the `mkdir` anyway. The kernel cannot apply that step - * until the name before it exists, while a recursive `mkdir` resolves the spelling as text and builds - * what stands on the far side of it: `private/missing/../../shared/recordings` never gets `shared` - * judged, and the `mkdir` creates `/shared/recordings` where any local user can write. A `..` over - * directories that all exist resolves for the walk as the kernel resolves it, and stays fine. - * - * The refusal is the same typed error the full rule raises, so a caller sees one reason for one shape of - * path whichever of the two asked it. + * The parent of `destination` exactly as the caller spells it, refusing a RELATIVE destination at the + * entry. Both routes resolve the caller's path to absolute before asking, and 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). */ -export function assertPrivateScriptDestinationPrefix(destination: string): void { - if (process.platform === 'win32') return; - const walk = walkParent(destination, readScriptTrust()); - if (walk.reject !== undefined) throw walk.reject; - if (walk.unresolvable) { - throw scriptAncestryFailure(destination, walk.deepest, 'unresolvable_parent'); - } -} - -/** - * The parent of `destination` as a chain of components from the root, never normalized: `path.resolve` - * folds a `..` away, which is the one simplification this may not make, because the kernel does not make - * it either — `.../work/../x` lands its entry beside the target of the link named `work`. - * - * A RELATIVE destination is resolved against the working directory, but not made absolute by joining the - * two: the cwd's OWN components are queued first and the destination's follow them raw. Standing the walk - * in the cwd would judge the cwd and nothing above it, and a caller who cannot write `/shared` can still - * swap the `/shared/mine` the cwd names. That name is first confirmed to be where the process really - * stands ({@link standsIn}), because it is the name the walk queues. - */ -function absoluteParent(destination: string): WalkStart { +function spelledParent(destination: string): string { const parent = path.dirname(destination); - if (path.isAbsolute(parent)) return { pathname: parent }; - // `path.resolve('')` is the working directory; its components and the destination's own parent, in - // order, are what the walk has to walk. `path.resolve(destination)` must NOT be used: it folds. - const cwd = path.resolve(''); - if (!standsIn(cwd)) return { reject: { path: cwd, exposure: 'parent_replaced' } }; - return { pathname: `${cwd}/${parent === '.' ? '' : parent}` }; -} - -/** The spelling to start a walk from, or the refusal that stops it before the first component. */ -type WalkStart = - | Readonly<{ pathname: string; reject?: undefined }> - | Readonly<{ - reject: Readonly<{ path: string; exposure: ScriptAncestryExposure }>; - pathname?: undefined; - }>; - -/** - * Whether the process really stands in the directory `pathname` names as its working directory. - * - * Node answers the working directory from the last `chdir` it made, so its NAME can go stale: move the - * directory it points at and put another at that path, and a walk of the name judges the replacement - * while the kernel resolves every relative name in the moved one. The two are therefore compared as - * device and inode, the one answer that makes both names mean one directory. - */ -function standsIn(pathname: string): boolean { - const remembered = statOrNull(pathname); - const standing = statOrNull('.'); - return ( - remembered !== undefined && - standing !== undefined && - remembered.dev === standing.dev && - remembered.ino === standing.ino - ); + if (!path.isAbsolute(parent)) { + throw scriptAncestryFailure(destination, parent, 'relative_destination'); + } + return parent; } /** @@ -414,6 +406,8 @@ type WalkStep = kind: 'short'; deepest: string; authority: DirectoryAuthority; + /** 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; }> @@ -432,13 +426,33 @@ type WalkStep = * the step up depends on a directory that is not there to be looked up in, and the caller's `mkdir` * resolves the same spelling as text and lands somewhere else. */ -type WalkOutcome = Readonly<{ - reject: AppError | undefined; - deepest: string; - authority: DirectoryAuthority | undefined; - arrived: boolean; - unresolvable: boolean; -}>; +/** + * Where a walk ended. Only a walk that ARRIVED reports ground to publish inside, so only it has an + * authority to judge; every other ending reports how far the walk got, which is what a caller that + * creates needs in order to create below judged ground only. + */ +type WalkOutcome = + | Readonly<{ + arrived: true; + /** The PHYSICAL directory the entry is created in. */ + deepest: string; + authority: DirectoryAuthority; + reject?: undefined; + unresolvable?: undefined; + missing?: undefined; + }> + | Readonly<{ + arrived: false; + /** The nearest directory the walk did judge, or `/` when it refused before judging one. */ + deepest: string; + /** The step that made the chain unsafe, when an existing step refused rather than went missing. */ + reject: AppError | undefined; + /** Whether a `..` is queued behind the absent name, so creating cannot resolve the chain. */ + unresolvable: boolean; + /** The spelled names below `deepest`, the first of them absent. */ + missing: readonly string[]; + authority?: undefined; + }>; /** * Walks the spelled parent exactly as the kernel resolves a path, judging every step, and refuses at the @@ -451,8 +465,8 @@ type WalkOutcome = Readonly<{ * - `.` 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: `arrived` is false, and `unresolvable` is true - * when a `..` is queued behind that name. + * directory the walk did reach, and the outcome says so: `arrived` is false, `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 @@ -461,53 +475,58 @@ type WalkOutcome = Readonly<{ * {@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. * - * A relative destination is walked from the root too, over the working directory's components first: the - * caller stands in that directory, but it is still a name in its parent, and the parent is judged too. + * `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 walkParent(destination: string, trust: ScriptDestinationTrust): WalkOutcome { - const start = absoluteParent(destination); - if (start.reject !== undefined) { - return refused(refusalAt(destination, start.reject)); - } - let step = startWalk(start.pathname, trust); +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 refused(refusalAt(destination, step)); - if (step.kind === 'short') { - return { - reject: undefined, - deepest: step.deepest, - authority: step.authority, - arrived: false, - unresolvable: step.behindUpwardStep, - }; + if (step.kind === 'reject') { + return refused(scriptAncestryFailure(destination, step.path, step.exposure)); } + if (step.kind === 'short') return stoppedShort(step); const { state } = step; const [component, ...rest] = state.queue; - if (component === undefined) { - // The one way a walk ARRIVES: every name the parent spelled has been resolved and judged. - return { - reject: undefined, - deepest: state.deepest, - authority: state.authority, - arrived: true, - unresolvable: false, - }; - } + // The only exit that ARRIVES: an empty queue, every name the parent spelled resolved and judged. + if (component === undefined) return arrived(state); step = stepThrough(state, component, rest, trust); } } +/** A walk that refused has no directory to report, because none of them is established as the entry's. */ +/** The one outcome that owns the answer: the judged directory the entry is created in. */ +function arrived(state: WalkState): WalkOutcome { + return { + arrived: true, + deepest: state.deepest, + authority: state.authority, + }; +} + /** A walk that refused has no directory to report, because none of them is established as the entry's. */ function refused(reject: AppError): WalkOutcome { - return { reject, deepest: '/', authority: undefined, arrived: false, unresolvable: false }; + return { + arrived: false, + deepest: '/', + reject, + unresolvable: false, + missing: [], + }; } -function refusalAt( - destination: string, - step: Readonly<{ path: string; exposure: ScriptAncestryExposure }>, -): AppError { - return scriptAncestryFailure(destination, step.path, step.exposure); +function stoppedShort(step: Extract): WalkOutcome { + return { + arrived: false, + deepest: step.deepest, + reject: undefined, + unresolvable: step.behindUpwardStep, + missing: step.missing, + }; } /** The first state: the root, with every component of the parent still to resolve. */ @@ -549,7 +568,7 @@ function pathComponents(directory: string): string[] { /** * Advances one component of the queue, which the caller knows to be non-empty: an empty queue is where a - * walk arrives, and {@link walkParent} answers that itself. + * walk arrives, and {@link walkSpelledParent} answers that itself. */ function stepThrough( state: WalkState, @@ -574,14 +593,15 @@ function stepIntoEntry( ): WalkStep { const entry = path.join(state.deepest, component); const stats = lstatIfPresent(entry); - // Nothing below here exists yet: a caller that creates missing parents stops here and creates inside - // the directory the walk reached; a publisher that creates nothing refuses. Neither may go on as if the - // name had resolved. + // 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, authority: state.authority, + missing: [component, ...rest], behindUpwardStep: rest.includes('..'), }; } @@ -623,7 +643,6 @@ function stepThroughLink( */ export const MAX_SCRIPT_PATH_LINK_HOPS = 30; -/** /** One directory's identity, for a caller that must publish into the same one it created or checked. */ export function publishDirectoryIdentity(directory: string): string | undefined { if (process.platform === 'win32') return 'windows'; @@ -631,229 +650,22 @@ export function publishDirectoryIdentity(directory: string): string | undefined return stats ? `${stats.dev}:${stats.ino}` : undefined; } -export type ScriptDestinationTrust = Readonly<{ - uid: number; - privateGid: number | undefined; -}>; - -/** The fields of a directory the ancestry rule reads, so the decision is testable without a filesystem. */ -export type DirectoryAuthority = Readonly<{ uid: number; gid: number; mode: number }>; - -/** The fields of a symbolic link the ancestry rule reads. */ -export type LinkAuthority = Readonly<{ uid: number }>; - -/** The file that says which sources the host looks in for accounts and groups. */ -const NSSWITCH_FILE = '/etc/nsswitch.conf'; - -/** The host files the private-group exception reads, in `/etc/group` field order. */ -type HostGroupDatabase = Readonly<{ - /** `undefined` when the file could not be read, which is not the same as a file with no records. */ - groups: readonly string[] | undefined; - passwd: readonly string[] | undefined; - /** `/etc/nsswitch.conf`, which says whether the two files above are the whole story. */ - nsswitch: readonly string[] | undefined; -}>; - -/** One `group:` or `passwd:` line of `/etc/nsswitch.conf`, or `undefined` when none was found. */ -type NsswitchLine = Readonly<{ database: string; sources: readonly string[] }>; - -/** - * Whether `/etc/nsswitch.conf` establishes that the group and passwd files are the whole story. - * - * `files` is the only source admitted. `systemd` is deliberately NOT admitted, though it is the default - * on some distributions: `systemd-userdbd` answers membership from user records these files never see, - * which is exactly the member this rule could not read. Bracketed actions such as `[NOTFOUND=return]` - * steer a lookup and add no source, so they are ignored. A missing line, an unparseable line, or an - * unreadable file establishes nothing, and the exception is refused. - * - * A database named MORE THAN ONCE establishes nothing either. glibc appends the sources of every line - * naming it and consults them in order, so `group: files` above `group: files sss` really does consult - * `sss`, and keeping one of the two lines — the last, or the first — would judge by a line the lookup - * never stopped at. {@link nsswitchLine} says how a repeated database is answered. - */ -export function nameServiceListsOnlyFiles(nsswitch: readonly string[] | undefined): boolean { - if (nsswitch === undefined) return false; - const databases = ['passwd', 'group', 'initgroups'].map((database) => - database === 'initgroups' - ? // glibc reads SUPPLEMENTARY membership from `initgroups:`. A line that is absent inherits the - // `group` setting, which is what the kernel does, so the verified `group` line covers it. - (nsswitchLine(nsswitch, 'initgroups') ?? nsswitchLine(nsswitch, 'group')) - : nsswitchLine(nsswitch, database), - ); - return databases.every((line) => line !== undefined && listsOnlyFiles(line)); -} - -function listsOnlyFiles(line: NsswitchLine): boolean { - return line.sources.length > 0 && line.sources.every((source) => source === 'files'); -} - /** - * The sources `/etc/nsswitch.conf` gives `database`, or `undefined` when it says nothing usable. - * - * A database named twice is answered with NO sources, which refuses the exception: the resolver - * concatenates the sources of repeated lines, so no single line says what the lookup consults, and - * {@link listsOnlyFiles} refuses an empty source list. + * 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). */ -function nsswitchLine(lines: readonly string[], database: string): NsswitchLine | undefined { - let found = 0; - let sources: readonly string[] = []; - for (const raw of lines) { - const source = (raw.split('#')[0] ?? '').trimStart(); - const [name, ...rest] = source.split(/[\s:]+/); - if (name !== database) continue; - found += 1; - // A bracketed action steers a lookup and lists no source. - sources = rest.filter((token) => token.length > 0 && !token.startsWith('[')); - } - if (found === 0) return undefined; - return { database, sources: found > 1 ? [] : sources }; -} - -/** One `/etc/group` record. A line without a numeric gid cannot be used to judge membership. */ -type GroupRecord = Readonly<{ name: string; gid: number; members: readonly string[] }>; - -/** One `/etc/passwd` record. */ -type PasswdRecord = Readonly<{ name: string; uid: number; gid: number }>; +export type ScriptDestinationTrust = Readonly<{ uid: number }>; -function parseGroupRecord(line: string): GroupRecord | undefined { - const [name, , rawGid, rawMembers = ''] = line.split(':'); - const gid = Number(rawGid); - if (name === undefined || name === '' || rawGid === '' || !Number.isInteger(gid)) - return undefined; - return { name, gid, members: rawMembers.split(',').filter((member) => member.length > 0) }; -} - -function parsePasswdRecord(line: string): PasswdRecord | undefined { - const [name, , rawUid, rawGid] = line.split(':'); - if (name === undefined || name === '') return undefined; - return { name, uid: Number(rawUid), gid: Number(rawGid) }; +/** What this process may rely on when it judges ground. */ +function scriptTrust(): ScriptDestinationTrust { + return { uid: process.getuid?.() ?? -1 }; } -/** This process's own account: the uid and primary gid the kernel reports, and the name it maps to. */ -type CurrentAccount = Readonly<{ - uid: number | undefined; - gid: number | undefined; - name: string | undefined; -}>; - -/** - * The single group the private-group exception admits, or `undefined` when nothing was established. - * - * Ubuntu and Debian create one group per user, named after them, and set that user's home directory to - * it, often group-writable and owned by them. Such a home is shared with no other local user, so it stays - * a valid destination. Every other group stays outside the exception, and the rule fails closed wherever - * completeness cannot be established: - * - * - {@link nameServiceListsOnlyFiles} must establish that the host's own files answer the question. - * - Both database files must have been READ. An unreadable file is not an empty one, and an empty - * member list proves nothing. - * - The gid must be this process's PRIMARY group, which `getgid` answers from the kernel, and one record - * carrying it must bear this user's name. - * - EVERY record carrying that gid is read, because a directory group-writable by gid 1000 is writable - * by the members of each group holding the number, however named: `ada:x:1000:` beside - * `team:x:1000:grace` reaches grace. Any of them naming a member who is neither this user nor root ends - * the claim — macOS lists only part of `staff` in `/etc/group` while every local user holds it. - * - No other passwd record may hold this gid as its primary group, and the caller's own must exist there - * with this uid and this gid. - */ -export function privateGroupId( - database: HostGroupDatabase, - current: CurrentAccount, -): number | undefined { - if (!nameServiceListsOnlyFiles(database.nsswitch)) return undefined; - const records = parseHostGroupDatabase(database); - if (records === undefined) return undefined; - return admittedPrivateGid(records, current); -} - -/** The host's two databases, parsed, or `undefined` when either file could not be read. */ -type HostAccounts = Readonly<{ - groups: readonly GroupRecord[]; - passwd: readonly PasswdRecord[]; -}>; - -function parseHostGroupDatabase(database: HostGroupDatabase): HostAccounts | undefined { - if (!database.groups || !database.passwd) return undefined; - return { - groups: database.groups.flatMap((line) => { - const record = parseGroupRecord(line); - return record === undefined ? [] : [record]; - }), - passwd: database.passwd.flatMap((line) => { - const record = parsePasswdRecord(line); - return record === undefined ? [] : [record]; - }), - }; -} - -/** The decision the parsed databases allow: this gid, when it is the caller's own private group. */ -function admittedPrivateGid(accounts: HostAccounts, current: CurrentAccount): number | undefined { - const { uid, gid, name } = current; - if (uid === undefined || gid === undefined || name === undefined) return undefined; - const own = accounts.passwd.find((record) => record.name === name); - if (own === undefined || own.uid !== uid || own.gid !== gid) return undefined; - const carrying = accounts.groups.filter((record) => record.gid === gid); - if (!carrying.some((record) => record.name === name)) return undefined; - // EVERY record carrying this gid decides together: a directory group-writable by gid 1000 is writable - // by the members of each of them, however they are named. - const reachesAnybodyElse = carrying.some((record) => - record.members.some((member) => !memberIsTrusted(member, accounts, name)), - ); - if (reachesAnybodyElse) return undefined; - const sharesPrimary = accounts.passwd.some( - (record) => record.name !== name && record.gid === gid && record.uid !== 0, - ); - return sharesPrimary ? undefined : gid; -} - -/** Whether a member of a candidate private group is the user or root, the two accounts the rule trusts. */ -function memberIsTrusted(member: string, accounts: HostAccounts, name: string): boolean { - if (member === name) return true; - const record = accounts.passwd.find((other) => other.name === member); - return record !== undefined && record.uid === 0; -} - -/** - * The account name this process's uid maps to, read from the host account database: the same file the - * group records come from, so a fixture serving one serves the other. No `os.userInfo()`, which answers - * from a different source than the records being judged. - */ -function readCurrentUser( - passwd: readonly string[] | undefined, - uid: number | undefined, -): string | undefined { - if (passwd === undefined || uid === undefined) return undefined; - for (const line of passwd) { - const record = parsePasswdRecord(line); - if (record?.uid === uid) return record.name; - } - return undefined; -} - -/** This process's identity and the private group its host databases establish, if any. */ -function readScriptTrust(): ScriptDestinationTrust { - const passwd = readSystemFile('/etc/passwd'); - const uid = process.getuid?.(); - return { - uid: uid ?? -1, - privateGid: privateGroupId( - { - groups: readSystemFile('/etc/group'), - passwd, - nsswitch: readSystemFile(NSSWITCH_FILE), - }, - { uid, gid: process.getgid?.(), name: readCurrentUser(passwd, uid) }, - ), - }; -} +/** The fields of a directory the ancestry rule reads, so the decision is testable without a filesystem. */ +export type DirectoryAuthority = Readonly<{ uid: number; gid: number; mode: number }>; -function readSystemFile(file: string): string[] | undefined { - try { - return fs.readFileSync(file, 'utf8').split('\n'); - } catch { - return undefined; - } -} +/** 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 @@ -870,6 +682,7 @@ export type ScriptAncestryExposure = | 'planted_link' | 'link_loop_exceeded' | 'not_a_directory' + | 'relative_destination' | 'unresolvable_parent' | 'unreachable_parent' | 'parent_replaced'; @@ -880,9 +693,11 @@ export type ScriptAncestryExposure = * * 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. The sticky bit is the one 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 inside. + * 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, @@ -891,7 +706,7 @@ export function untrustedAncestryExposure( 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 && directory.gid !== trust.privateGid) return 'shared_group_writable'; + if (directory.mode & 0o020) return 'shared_group_writable'; return undefined; } @@ -909,7 +724,7 @@ export function othersCreateEntriesIn( ): boolean { if (directory.uid !== 0 && directory.uid !== trust.uid) return true; if (directory.mode & 0o002) return true; - return Boolean(directory.mode & 0o020) && directory.gid !== trust.privateGid; + return Boolean(directory.mode & 0o020); } /** @@ -938,12 +753,15 @@ export function untrustedLinkExposure( 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: 'another 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.', + 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: @@ -968,13 +786,25 @@ function scriptAncestryFailure( exposure, path: destination, ancestor, - hint: replaced - ? 'Re-record with open --save-script, or save under a directory nobody else can write.' - : 'Save the script under a directory you own that only you can write, and keep the path out of directories other users own.', + 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.'; +} + /** `stat` of the directory a path names, or `undefined` when it is absent or is not a directory. */ function statDirectoryChain(pathname: string): fs.Stats | undefined { let stats: fs.Stats | undefined; diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts index 6194bc490b..6d1daab97c 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-ancestry.test.ts @@ -39,6 +39,42 @@ test.skipIf(process.platform === 'win32')( }, ); +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 () => { diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 4f913f3b6b..b8e2088635 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -14,7 +14,7 @@ import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { acquireProcessLock, assertPrivateScriptDestination, - assertPrivateScriptDestinationPrefix, + prepareScriptDestination, publishDirectoryIdentity, publishFileSync, withProcessLock, @@ -200,14 +200,10 @@ async function publishScriptVersion( const pending = { named: false }; let staging: string | undefined; try { - // The chain that already exists is refused before anything is created, then the missing parent is - // created, then the full rule is asked again in `allocateStaging`: the rule needs the directory the - // entry is really created in, which does not exist until the `mkdir` has run, and a destination this - // route is going to refuse must leave no directories behind in the shared ground it names (#4565). - // The walk covers that same spelled parent, which is where a `..` step would otherwise build a - // directory nobody judged. - assertPrivateScriptDestinationPrefix(record.destination); - await fs.promises.mkdir(path.dirname(record.destination), { recursive: true }); + // 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 + // is going to refuse therefore leaves no directories behind in the shared ground it names. + prepareScriptDestination(record.destination); const allocated = await withRecordLock(file, async () => allocateStaging(file, record.destination), ); diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 7c85d492e9..75cd7a7221 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -33,7 +33,6 @@ "packages/kernel/src/contracts.ts#RESPONSE_LEVELS": "sha256:cef29c3b56c299e35a7fee8058b90dc4a6f65a46a420e4f11f77c8ca7d0359c8", "packages/kernel/src/contracts.ts#ResponseCost": "sha256:2a44de54e8b5c886b36da1500e22d634ec7e12961d2c93b689d2b1aa8c15f186", "packages/kernel/src/contracts.ts#ResponseLevel": "sha256:c7329d28e745b5e69b86aa1a686befa314b98248afbe5e0e2d7d395f0d777f9b", - "packages/kernel/src/contracts.ts#ScriptDeliveryFailure": "sha256:186881f8b2e6a0227a6d1a2c802d8f7356fee39d4137800a0c9fa65401aa2765", "packages/kernel/src/contracts.ts#SESSION_ISOLATION_MODES": "sha256:3d4b3048e22bb0ceccc98cf8fd93a87a1a1e2dad96fa03cffff6d0ecedb58689", "packages/kernel/src/contracts.ts#SessionIsolationMode": "sha256:beea941fe57b000902da28af15a27aa18d0c957408209e3ec372fcf7f605fa7c", "packages/kernel/src/contracts.ts#SESSION_RUNTIME_PLATFORMS": "sha256:6164fc8ca226b5beb3ba52a8dddd3c11633a8accec58b9f8972c44c8339a1bf7", @@ -215,7 +214,7 @@ "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:357bb449fd03596841cede2fcad1589e41b55a806a0c297f10a2320a9b8fb2a7", + "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:4b932f798f4e0b3871270c5b5f1e0081bc056a96c14ea382d94230d98e9b21f9", "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" @@ -223,8 +222,8 @@ "compatibleChanges": [ { "declaration": "packages/remote/src/session-script-destination.ts#publishScriptVersion", - "digest": "sha256:357bb449fd03596841cede2fcad1589e41b55a806a0c297f10a2320a9b8fb2a7", - "rationale": "#4565 adds one call ahead of the `mkdir` that creates a missing parent: the destination-ancestry rule is asked over the directories that already exist, so a destination it is going to refuse leaves no directories behind. Nothing on the wire changes: no request field is added, removed or renamed, no response field, route, status or artifact framing moves, and the download contract this declaration consumes is untouched. A released daemon receives exactly the same request and answers the same way; a released caller resolves the same paths on its own disk. A skewed peer parses every payload as before." + "digest": "sha256:4b932f798f4e0b3871270c5b5f1e0081bc056a96c14ea382d94230d98e9b21f9", + "rationale": "#4565 adds one call ahead of the `mkdir` that creates a missing parent: the destination-ancestry rule is asked over the directories that already exist, so a destination it is going to refuse leaves no directories behind. Nothing on the wire changes: no request field is added, removed or renamed, no response field, route, status or artifact framing moves, and the download contract this declaration consumes is untouched. A released daemon receives exactly the same request and answers the same way; a released caller resolves the same paths on its own disk. A skewed peer parses every payload as before. #4565 revises that local sequencing only: the `mkdir` moves into host-kit's one destination call, which refuses an unsafe destination before creating anything and creates what is missing at 0700, and the judged directory's identity is compared once before the rename. Nothing on the wire moves: same request fields, same response fields, same routes, status and artifact framing, and the download contract this declaration consumes is untouched. A released daemon receives the same request and answers the same way; a released caller resolves the same paths on its own disk." }, { "declaration": "packages/kernel/src/contracts.ts#DaemonRequestMeta", @@ -239,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", @@ -314,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/replay-e2e.md b/website/docs/docs/replay-e2e.md index fde22c292a..bb0e2b9076 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -70,11 +70,11 @@ 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, and only once the directories above them pass the check below. 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. +- Missing parent directories are created, 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 name such as `journey.ad` is checked the same way, from the root down through your working directory, 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. +- 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 you own is accepted when its group is your own private group, the shape Ubuntu and Debian create for home directories, and only where `/etc/nsswitch.conf` shows that `/etc/group` and `/etc/passwd` are the whole story for accounts, groups and supplementary groups alike: a name service could hold a member those files never show, and a database configured on two lines is not settled by the one that looks safer, because the system consults both. Every group carrying that group number is considered, so a second group with the same number that lists somebody else closes this exception. +- 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. From 925158ddf429f7d1714122144e2cf8ce8b9fe756 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 21:37:06 +0100 Subject: [PATCH 18/28] fix(host-kit): judge every script-path step from its own lstat Four shapes the destination-ancestry rule still answered too generously, plus the daemon's own state directories under a shared umask: - Every step of the walk is judged from the `lstat` of the ENTRY, never re-read with `stat`: `stat` resolves a name a second time, and the name can answer a different entry by then, so a directory swapped for a link mid-walk was entered on the strength of its target. Where a walk returns to a name it judged, it re-reads that name only to recognize it and keeps the first judgment. Directory identities are read as BIGINT, because a 32-bit `ino` collapses two distinct large inodes onto one identity, and the answer is confirmed to hold the judged entry before a caller stages anything there. - A missing tail is created ONE LEVEL AT A TIME. A recursive `mkdir` resolves the whole tail as text, so a link another local user plants at one of the absent names while the walk runs carries the creation to its far side, where as root it creates with privileges. Each level is confirmed before the name below it is created, and a name that appeared between the check and the creation is refused (`entry_appeared`). - A destination that is not absolute is refused on every platform, Windows included, where no walk runs to catch it. - The daemon creates and repairs its state directory, `sessions/` and `remote-scripts/` at 0700 rather than through a mode-less `mkdir`, so a umask-002 host no longer gets 0775 `sessions/` and a refusal of the daemon's own default recordings and remote-delivered versions. `prepareScriptDestination` answers the judged directory WITH its identity, so the remote route stages each version where that answer points instead of walking the destination a second time. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 8 +- .../src/daemon-registration-owner.ts | 44 +- .../session-store-teardown-script.test.ts | 50 ++ .../daemon/src/core/session-script-writer.ts | 6 +- packages/daemon/src/core/session-store.ts | 12 +- .../daemon/src/server/http/daemon-runtime.ts | 7 + packages/host-kit/src/file.ts | 1 + .../src/internal/atomic-file-ancestry.test.ts | 178 ++++++- .../src/internal/atomic-file-parent.test.ts | 54 ++- packages/host-kit/src/internal/atomic-file.ts | 437 ++++++++++++------ .../remote/src/session-script-destination.ts | 51 +- test/wire-compat/ledger.json | 6 +- website/docs/docs/replay-e2e.md | 2 +- 13 files changed, 665 insertions(+), 191 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index fd10042b0e..f2db2eec6d 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -207,10 +207,10 @@ 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. -Both routes resolve an absolute destination before asking host-kit, and host-kit refuses a relative one at its entry: 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 both the local writer and the remote client make that one call before staging. The rule closes the window with PERMISSIONS, not with timing. +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 — recursive `mkdir` applies the mode to every level it creates — and the walk runs again over the now-complete chain. 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. +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. Each level is confirmed to be the entry its parent was judged for before the name below it is created, and a name that was absent when the walk looked and exists by the time `mkdir` reaches it is refused (`entry_appeared`) rather than adopted. 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: @@ -219,10 +219,10 @@ Shapes this closes, each of which an earlier shape of the rule accepted: - `..` 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. Both publishers stage inside that directory 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 path is read from the host once per walk, so an alias or a `..` back over ground already crossed does not ask the host again. +The walk ANSWERS with the physical directory the entry is created in, and confirms at that moment that the name the answer is spelled by still holds the entry it judged: a name that answers something else by then is refused (`parent_replaced`), because the caller's next `mkdir`, staging `mkdtemp` or `rename` would travel through it. Directory identities are read as BIGINT, because a 32-bit `ino` collapses two distinct large inodes onto one identity and a swap between the two would then look like the same directory. Both publishers stage inside that directory 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 walk, 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. Where a walk returns to a name it already judged, through a `..` or an alias, it re-reads that name only to RECOGNIZE it and keeps the judgment it first made. 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. +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. 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 remote route captures the judged directory's `dev:ino` when it allocates staging and compares it once, under its record lock, right before the rename, because the download runs in between. That is the ONLY such comparison: the local publish does not repeat it. The ownership rule is what closes the window — anyone able to swap a judged directory was refused at it — and a second re-check would answer for a race the permissions rule already excludes. 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. diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index 21862e45e1..7ff64a0eda 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -276,6 +276,47 @@ export function createOwnedReplayStateDir(): OwnedReplayStateDir { return owned; } +/** + * Creates one of the daemon's own state directories, and repairs one that already 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 the daemon would refuse its own default recordings and every + * remote-delivered version. Creation carries the mode and the repair forces it, because a state dir an older + * version created at 0775 is the same refusal. + * + * Returns the path so a caller can name what it just made without a second `mkdir` of its own. + */ +export function ensurePrivateDaemonStateDir(directory: string): string { + const firstCreated = fs.mkdirSync(directory, { recursive: true, mode: STATE_DIR_MODE }); + // `mkdir` reports the FIRST directory it made, and everything from there down is this call's to force + // private. Repairing only the leaf would leave the level ABOVE a session directory, `sessions/`, at the + // 0775 a umask-002 creation gives it, which is the directory every recording is walked through. + for (const level of createdStateLevels(firstCreated, directory)) { + repairStateMode(level, STATE_DIR_MODE); + } + return directory; +} + +/** Every level one creation made: `firstCreated` itself, down to `directory`. */ +function createdStateLevels( + firstCreated: string | undefined, + directory: string, +): readonly string[] { + const below = + firstCreated === undefined || firstCreated === directory + ? [] + : path.relative(firstCreated, directory).split(path.sep); + if (firstCreated === undefined || below.length === 0 || below[0] === '..') return [directory]; + return [ + firstCreated, + ...below.map((_, index) => path.join(firstCreated, ...below.slice(0, index + 1))), + ]; +} + +const STATE_DIR_MODE = 0o700; + /** * 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 @@ -314,8 +355,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); + ensurePrivateDaemonStateDir(input.paths.baseDir); const logFd = fs.openSync(input.paths.logPath, 'a', 0o600); try { repairStateMode(input.paths.logPath, 0o600); 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 b7a4a0ece5..a926cb2d2f 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 @@ -86,3 +86,53 @@ test.skipIf(process.platform === 'win32')( 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); + } + }, +); + +/** 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); +} diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index c22f725215..5954ead3b2 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, @@ -166,9 +166,7 @@ export class SessionScriptWriter { * `publishScriptFileSync` decides. */ private remoteScriptPath(): string { - const directory = path.join(this.sessionsDir, 'remote-scripts'); - fs.mkdirSync(directory, { recursive: true, mode: 0o700 }); - fs.chmodSync(directory, 0o700); + const directory = ensurePrivateDaemonStateDir(path.join(this.sessionsDir, 'remote-scripts')); return path.join(directory, `${crypto.randomUUID()}.ad`); } diff --git a/packages/daemon/src/core/session-store.ts b/packages/daemon/src/core/session-store.ts index 203d1277c2..1d8d620ffd 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 { ensurePrivateDaemonStateDir } 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 }); + ensurePrivateDaemonStateDir(this.resolveSessionDir(ref.address)); 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 }); + ensurePrivateDaemonStateDir(this.resolveSessionDir(sessionName)); 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 ensurePrivateDaemonStateDir(this.resolveSessionDir(sessionName)); } /** Path to session-scoped app log file. Agent can grep this for token-efficient debugging. */ diff --git a/packages/daemon/src/server/http/daemon-runtime.ts b/packages/daemon/src/server/http/daemon-runtime.ts index 7054039ae3..2002e2015d 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 { + ensurePrivateDaemonStateDir, 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. + ensurePrivateDaemonStateDir(baseDir); + ensurePrivateDaemonStateDir(sessionsDir); 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/host-kit/src/file.ts b/packages/host-kit/src/file.ts index 37da1f9af8..b4c0942890 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -8,6 +8,7 @@ export { publishFileSync, publishScriptFileSync, type DurableFilePublishMode, + type ScriptDestination, } from './internal/atomic-file.ts'; export { NOT_REGULAR_FILE_HINT, diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index d66c939491..4193a57f67 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -309,33 +309,75 @@ skipOnWindows( }, ); -skipOnWindows('reads each directory it stands in once, however many routes lead back to it', () => { - // `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. Each path is read from the host once per walk, so ground come back to by a `..` - // or by an alias of it is not asked for a second time. +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(assertPrivateScriptDestination(`${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 directory whose name answers a different entry on the second look', () => { + // The walk judges an entry by its own `lstat` and remembers that identity. Here the second route into + // `sub` finds a DIFFERENT entry under that name — the swap the permission rule exists to exclude — so the + // walk refuses instead of standing on ground it never judged. 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.mkdirSync(path.join(sub, 'below')); fs.symlinkSync(sub, path.join(home, 'a')); fs.symlinkSync(sub, path.join(home, 'b')); - const reads: string[] = []; - const realStatSync = fs.statSync; - vi.spyOn(fs, 'statSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { - reads.push(String(pathname)); - return (realStatSync as (...args: unknown[]) => unknown)(pathname, ...rest); - }) as typeof fs.statSync); - - expect(assertPrivateScriptDestination(`${home}/a/../b/below/journey.ad`)).toBe(below); + const realLstatSync = fs.lstatSync; + let crossed = 0; + vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + const stats = (realLstatSync as (...args: unknown[]) => unknown)( + pathname, + ...rest, + ) as fs.BigIntStats; + // The first route in sees the real `sub`; the second sees another entry answering that name. + if (String(pathname) === sub && crossed++ > 0) { + return Object.assign(Object.create(Object.getPrototypeOf(stats)), stats, { + ino: stats.ino + 1n, + }); + } + return stats; + }) as typeof fs.lstatSync); - // The shared prefix, `home`, `sub` and `below`: no path is read a second time, including the one the - // two aliases both name. - expect(new Set(reads).size).toBe(reads.length); - expect(reads.filter((read) => read === sub)).toHaveLength(1); - expect(reads.filter((read) => read === home)).toHaveLength(1); + expectUntrustedReplaced( + () => assertPrivateScriptDestination(`${home}/a/../b/below/journey.ad`), + sub, + ); }); skipOnWindows( @@ -778,3 +820,97 @@ skipOnWindows('accepts the identity a caller captured for the directory the walk ); expect(assertPrivateScriptDestination(destination)).toBe(staged); }); + +// --- a step swapped out while the walk is still running --- + +skipOnWindows('refuses a directory swapped for a link between the lstat and entering it', () => { + // The attacker owns `decoy` and stands in a sticky shared parent, where they may replace their own + // entry. Between the walk's `lstat` of `decoy` and the moment it would enter that name, they swap it + // for a link to their own directory. Entering it is what redirects the publish, so the walk judges the + // entry its OWN lstat saw: a name that answers something else by then is refused, and a link planted + // afterwards is never stepped through on the strength of its target. + const directory = root(); + const sticky = directoryWith(path.join(directory, 'tmp'), 0o1777); + const decoy = path.join(sticky, 'decoy'); + fs.mkdirSync(decoy); + const attacker = path.join(directory, 'attacker'); + fs.mkdirSync(attacker); + fs.chmodSync(attacker, 0o700); + const realLstatSync = fs.lstatSync; + let looks = 0; + vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + // The first look is the walk's judgment: the attacker's OWN directory. The swap lands immediately + // after that judgment, so every later look at this name answers a link. + if (String(pathname) === decoy && ++looks === 2) { + fs.renameSync(decoy, `${decoy}.real`); + fs.symlinkSync(attacker, decoy); + } + return (realLstatSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.lstatSync); + + const destination = path.join(decoy, 'sub', 'journey.ad'); + + expectUntrustedReplaced(() => publish(destination), decoy); + // Nothing was staged in the directory the link leads to, which is what the swap was for. + expect(fs.readdirSync(attacker)).toEqual([]); +}); + +skipOnWindows('refuses an answer whose directory was swapped for a link before staging', () => { + // The walk can be asked for an answer and then hand it to a caller that stages bytes there. If the name + // the answer is spelled by answers a link in between, `mkdir`, `mkdtemp` and `rename` would all travel + // through it, so the answer is confirmed against the entry the walk judged before anyone writes. + const directory = root(); + const home = directoryWith(path.join(directory, 'home'), 0o700); + const work = path.join(home, 'work'); + fs.mkdirSync(work); + const attacker = path.join(directory, 'attacker'); + fs.mkdirSync(attacker); + fs.chmodSync(attacker, 0o700); + const realLstatSync = fs.lstatSync; + let looks = 0; + vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { + // The first look judges `work` as the directory the entry is created in. The swap lands immediately + // after that judgment and before anything is staged there. + if (String(pathname) === work && ++looks === 2) { + fs.rmdirSync(work); + fs.symlinkSync(attacker, work); + } + return (realLstatSync as (...args: unknown[]) => unknown)(pathname, ...rest); + }) as typeof fs.lstatSync); + + expectUntrustedReplaced(() => publish(path.join(work, 'journey.ad')), work); + expect(fs.readdirSync(attacker)).toEqual([]); +}); + +skipOnWindows( + 'identifies an entry by its bigint inode, so two large inodes do not collapse', + () => { + // Directory identities are compared for equality, 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 judges, then the one the name answers after. + 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)); + expectUntrustedReplaced(() => publish(path.join(work, 'journey.ad')), work); + }, +); diff --git a/packages/host-kit/src/internal/atomic-file-parent.test.ts b/packages/host-kit/src/internal/atomic-file-parent.test.ts index d1b670519e..54e5d38929 100644 --- a/packages/host-kit/src/internal/atomic-file-parent.test.ts +++ b/packages/host-kit/src/internal/atomic-file-parent.test.ts @@ -2,7 +2,7 @@ // 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 { expect, test } from 'vitest'; +import { expect, test, vi } from 'vitest'; import fs from 'node:fs'; import path from 'node:path'; import { @@ -78,7 +78,7 @@ skipOnWindows('answers the created directory as the one to publish into', () => let judged = ''; withSharedUmask(() => { - judged = prepareScriptDestination(destination); + judged = prepareScriptDestination(destination).directory; }); expect(judged).toBe(path.join(home, 'nested', 'deeper')); @@ -101,3 +101,53 @@ skipOnWindows('refuses a destination whose parent does not exist, and publishes ); expect(fs.readdirSync(directory)).toEqual([]); }); + +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'), + ); + expectUntrusted( + () => assertPrivateScriptDestination(relative), + '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 0884029ee8..347d9e12ec 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -61,7 +61,7 @@ export function publishScriptFileSync(options: { // 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); + 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 @@ -111,38 +111,37 @@ 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. A recursive `mkdir` applies the mode to every - * level it creates, so a creation on the usual umask-002 host is not left 0775 and then refused. + * 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 destination the rule refuses is refused BEFORE - * anything is created, what is missing is created at {@link SCRIPT_DIR_MODE} inside the directory the - * walk judged, and the now-complete chain is JUDGED again before the answer. A caller never hands its own - * `mkdir` to a path this rule has not stopped first. + * 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 + * JUDGED again before the answer. A caller never hands its own `mkdir` to a path this rule has not stopped. * - * The second walk asks the creation question — whether other local users could add the destination's own + * The second walk asks the CREATION question — whether other local users could add the destination's own * name inside the directory the walk ended in. The first walk does not, because below it the missing - * directories are this call's own to create, at 0700, which is what keeps - * `mkdir -p /recordings` acceptable. + * 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. * - * A `..` queued behind the first component that does not exist is refused by the FIRST walk: creating - * cannot resolve it, because the kernel applies that step only to a directory that already exists, while - * a recursive `mkdir` resolves the same spelling as text and builds what stands on the far side of it. + * The answer carries the judged directory's identity, so a caller that stages something there does not ask + * the host about ground this call already judged, and never runs a `mkdir` of its own. * - * On Windows access is an ACL rather than a mode, so the rule is a no-op and the parent is the answer. + * 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): string { +export function prepareScriptDestination(destination: string): ScriptDestination { + const spelled = spelledParent(destination); if (process.platform === 'win32') { - const parent = path.dirname(path.resolve(destination)); - fs.mkdirSync(parent, { recursive: true, mode: SCRIPT_DIR_MODE }); - return parent; + fs.mkdirSync(spelled, { recursive: true, mode: SCRIPT_DIR_MODE }); + return { directory: spelled, identity: publishDirectoryIdentity(spelled) }; } - const spelled = spelledParent(destination); const trust = scriptTrust(); const walked = walkSpelledParent(spelled, destination, trust); if (walked.reject !== undefined) throw walked.reject; @@ -150,15 +149,38 @@ export function prepareScriptDestination(destination: string): string { throw scriptAncestryFailure(destination, walked.deepest, 'unresolvable_parent'); } // Where the chain already stands, this walk judged the directory the entry is created in and there is - // nothing to create, so it is also the answer. Only a walk that stopped short walks again. - if (walked.arrived) return publishableDirectory(destination, walked, trust); - fs.mkdirSync(path.join(walked.deepest, ...walked.missing), { - recursive: true, - mode: SCRIPT_DIR_MODE, - }); - return publishableDirectory(destination, walkSpelledParent(spelled, destination, trust), trust); + // nothing to create, so it is also the answer. Only a walk that stopped short creates and walks again. + if (walked.arrived) return publishableDestination(destination, walked, trust); + // A walk that stopped short always judged the directory it stopped in, so it has an identity to create + // under. Anything else that did not arrive refused ground, and creates nothing. + if (walked.identity === undefined) { + throw scriptAncestryFailure(destination, walked.deepest, 'unreachable_parent'); + } + const created = createMissingLevels( + destination, + walked.deepest, + walked.identity, + walked.missing, + trust, + ); + // The walk that follows creation judges the tail from what the creation saw and every other name from + // what the first walk judged, so a level swapped out in between is refused rather than entered on. + const known = new Map(walked.ground?.judged); + for (const [level, judged] of created) known.set(level, judged); + return publishableDestination( + destination, + walkSpelledParent(spelled, destination, trust, known), + trust, + ); } +/** Where a script entry is created: the PHYSICAL directory the rule judged, and that directory's identity. */ +export type ScriptDestination = Readonly<{ + directory: string; + /** `dev:ino` as the walk's own `lstat` answered it, for a caller that stages bytes there. */ + identity: string | undefined; +}>; + export type DurableFilePublishMode = 'replace' | 'link-exclusive'; /** Publishes complete UTF-8 contents with a durable file and directory fence. */ @@ -238,11 +260,9 @@ function syncDirectoryBestEffort(directory: string): void { } /** - * `lstat` that treats absence as `undefined`; every other errno propagates. - * - * Owned here, not in a module of its own, because the publish rule sits on the daemon's startup path: a - * new module on that edge is eager code every entry that publishes a file pays for today (ADR 0019). The - * verified-file guards ask the same question, and this module is on their path already. + * `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 { @@ -257,10 +277,9 @@ export function lstatIfPresent(pathname: string): fs.Stats | undefined { * 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 — which - * rejects the real temp sibling and accepts a look-alike planted beside the directory the text names. + * 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; @@ -291,67 +310,54 @@ function statOrNull(pathname: string): fs.Stats | undefined { /** * Refuses a script destination unless every directory the kernel looks a name up in is one no other * non-root local user can change (#4565), and reports the PHYSICAL directory the entry is created in. + * {@link prepareScriptDestination} is the same rule for a caller that also needs the missing tail created; + * everything written there about how the walk judges ground, and about the window being closed by + * PERMISSIONS rather than by timing, applies here too. * - * Node exposes no `openat` or `renameat`, so a publisher cannot resolve a destination relative to a - * directory handle. The window is closed by PERMISSIONS instead of by timing: once no other non-root - * user can add or remove an entry in any directory on the walk, nobody can swap a component out or plant - * one, so the path this rule judged is the path the publish reaches. Nothing here depends on when a - * directory was judged, and no re-check is what makes the write safe. - * - * The return value is part of the rule, not a convenience: the caller stages the temp file IN THAT - * DIRECTORY, because a `..` or a link means the entry lands somewhere `path.dirname` does not name, and - * staging outside the judged directory hands another local user the temp file that gets published. - * - * What it asks of every directory it enters is {@link untrustedAncestryExposure}: ownership first, then - * the mode, with the sticky bit excusing only passing THROUGH. {@link othersCreateEntriesIn} is asked - * separately of the directory the walk ended in, because that bit cannot refuse a NEW entry by name, and - * every followed link is judged by {@link untrustedLinkExposure} against the directory that holds it. - * A group-writable directory is refused outright: membership cannot be proven from the host's account - * files, so ADR 0016 carries no private-group exception, and the hint says to `chmod g-w` the directory. - * - * A component that is neither a directory nor a link is refused as `not_a_directory`: the kernel cannot - * travel through it either. On Windows access is an ACL, so this rule is a no-op and answers the parent - * it was given. - * - * `parentIdentity` is what {@link publishDirectoryIdentity} returned for the directory an earlier walk - * judged. Only the remote route passes one, because a download runs between its two walks: the rule above - * already excludes anyone who could swap that directory, so the comparison is defense in depth against a - * host whose modes moved meanwhile, not what closes the window. + * This variant creates NOTHING, so a walk that stopped short at an absent name has no answer to give and + * refuses as `unreachable_parent`. `parentIdentity` is the identity {@link prepareScriptDestination} + * answered for the directory an earlier walk judged; only the remote route passes one, and this walk's own + * identity is compared with it before anything is renamed. */ export function assertPrivateScriptDestination( destination: string, parentIdentity?: string, ): string { - if (process.platform === 'win32') return path.dirname(path.resolve(destination)); + const spelled = spelledParent(destination); + if (process.platform === 'win32') return spelled; const trust = scriptTrust(); - const walk = walkSpelledParent(spelledParent(destination), destination, trust); + const walk = walkSpelledParent(spelled, destination, trust); if (walk.unresolvable) { throw scriptAncestryFailure(destination, walk.deepest, 'unresolvable_parent'); } - return publishableDirectory(destination, walk, trust, parentIdentity); + return publishableDestination(destination, walk, trust, parentIdentity).directory; } /** - * Judges a finished walk and reports the directory to create the entry in. + * 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 never asks the host about ground the walk already judged. * * 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 the nearest ancestor it did reach is a file under a name nobody asked for. - * - * The identity is asked of the directory the walk answered, which is NOT `path.dirname` of the spelling: - * where a `..` or a link leads elsewhere, the spelled parent is a different directory and comparing - * against it reports a replacement that never happened. */ -function publishableDirectory( +function publishableDestination( destination: string, walk: WalkOutcome, trust: ScriptDestinationTrust, parentIdentity?: string, -): string { +): ScriptDestination { if (walk.reject !== undefined) throw walk.reject; if (!walk.arrived) { throw scriptAncestryFailure(destination, walk.deepest, 'unreachable_parent'); } - if (parentIdentity !== undefined && publishDirectoryIdentity(walk.deepest) !== parentIdentity) { + // Confirmed before a caller starts staging: the name the answer is spelled by must still hold the entry + // this walk judged, or the caller's next `mkdir`, `mkdtemp` or `rename` travels through a swap. + if (!stillTheJudgedEntry(walk.deepest, walk.identity)) { + throw scriptAncestryFailure(destination, walk.deepest, 'parent_replaced'); + } + // This walk's identity IS a confirmed `lstat` of the directory it answered, so an earlier answer for the + // same directory is compared without reading the host twice. + if (parentIdentity !== undefined && walk.identity !== parentIdentity) { throw scriptAncestryFailure(destination, walk.deepest, 'parent_replaced'); } // Where other local users can add entries here, one of them can add this entry first and the @@ -359,15 +365,15 @@ function publishableDirectory( if (othersCreateEntriesIn(walk.authority, trust)) { throw scriptAncestryFailure(destination, walk.deepest, 'shared_parent'); } - return walk.deepest; + return { directory: walk.deepest, identity: walk.identity }; } /** - * The parent of `destination` exactly as the caller spells it, refusing a RELATIVE destination at the - * entry. Both routes resolve the caller's path to absolute before asking, and 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). + * 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); @@ -378,26 +384,39 @@ function spelledParent(destination: string): string { } /** - * Where the walk stands: a directory it judged and physically reached, plus the names still to resolve. + * 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; - /** What this walk already learned about the ground it stands on. */ ground: WalkGround; }>; /** - * One walk's memory of the ground it stood on: the `stat` of every path it read, keyed by that path. A - * path that comes back around, through a `..` or an alias, is asked once, so one walk sees the host the - * same way throughout. + * One directory the walk judged, as its `lstat` answered it: the identity to recognize it by, plus the + * fields the rule reads. `lstat` is the ONLY lookup the rule makes — `stat` resolves a name a second time, + * and the name can answer a different entry by then. + */ +type JudgedDirectory = Readonly<{ + identity: string; + uid: number; + gid: number; + mode: number; +}>; + +/** + * One walk's memory of the ground it stood on: every path it judged, keyed by that path, so a name come + * back around through a `..` or an alias keeps the judgment it was given and one walk sees one host. Names + * this call CREATED are seeded here too, to be compared against rather than trusted. */ type WalkGround = Readonly<{ - stats: Map; + judged: Map; }>; type WalkStep = @@ -406,6 +425,9 @@ type WalkStep = kind: 'short'; deepest: string; authority: DirectoryAuthority; + identity: string; + /** Everything judged on the way, so creation and the next walk compare against it. */ + ground: WalkGround; /** 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. */ @@ -414,22 +436,14 @@ type WalkStep = | Readonly<{ kind: 'stand'; state: WalkState }>; /** - * A walk that ended: the typed refusal, or the directory the entry is created in together with the - * authority it was judged with. The authority travels with the answer, so the caller never asks the host - * about ground the walk has already read. - * - * `arrived` says the resolution reached the directory the entry is created in. Otherwise the walk stopped - * at a name that does not exist and reports the nearest ancestor it did reach, which is NOT where the - * entry belongs: publishing there writes a file the caller never named. + * 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. Every other ending reports how far the walk + * got, which is what a caller that creates needs in order to create below judged ground only. * - * `unresolvable` says a `..` is queued behind that absent name, so creating cannot finish the resolution: - * the step up depends on a directory that is not there to be looked up in, and the caller's `mkdir` - * resolves the same spelling as text and lands somewhere else. - */ -/** - * Where a walk ended. Only a walk that ARRIVED reports ground to publish inside, so only it has an - * authority to judge; every other ending reports how far the walk got, which is what a caller that - * creates needs in order to create below judged ground only. + * A walk that did not arrive stopped at a name that does not exist, and the nearest ancestor it did reach is + * NOT where the entry belongs: publishing there writes a file the caller never named. `unresolvable` says a + * `..` is queued behind that absent name, so creating cannot finish the resolution. */ type WalkOutcome = | Readonly<{ @@ -437,6 +451,8 @@ type WalkOutcome = /** 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; reject?: undefined; unresolvable?: undefined; missing?: undefined; @@ -445,6 +461,10 @@ type WalkOutcome = arrived: false; /** The nearest directory the walk did judge, or `/` when it refused before judging one. */ deepest: string; + /** That directory's identity as the walk judged it, when it judged one. */ + identity: string | undefined; + /** Everything that walk judged, to seed the walk that follows a creation. */ + ground: WalkGround | undefined; /** The step that made the chain unsafe, when an existing step refused rather than went missing. */ reject: AppError | undefined; /** Whether a `..` is queued behind the absent name, so creating cannot resolve the chain. */ @@ -482,8 +502,9 @@ function walkSpelledParent( parent: string, destination: string, trust: ScriptDestinationTrust, + created?: ReadonlyMap, ): WalkOutcome { - let step = startWalk(parent, trust); + let step = startWalk(parent, trust, created); // Every step consumes a component, and every link hop counts against a fixed limit, so this ends. for (;;) { if (step.kind === 'reject') { @@ -498,13 +519,13 @@ function walkSpelledParent( } } -/** A walk that refused has no directory to report, because none of them is established as the entry's. */ /** The one outcome that owns the answer: the judged directory the entry is created in. */ function arrived(state: WalkState): WalkOutcome { return { arrived: true, deepest: state.deepest, authority: state.authority, + identity: state.identity, }; } @@ -513,6 +534,8 @@ function refused(reject: AppError): WalkOutcome { return { arrived: false, deepest: '/', + identity: undefined, + ground: undefined, reject, unresolvable: false, missing: [], @@ -523,6 +546,8 @@ function stoppedShort(step: Extract): WalkOutcome { return { arrived: false, deepest: step.deepest, + identity: step.identity, + ground: step.ground, reject: undefined, unresolvable: step.behindUpwardStep, missing: step.missing, @@ -530,35 +555,96 @@ function stoppedShort(step: Extract): WalkOutcome { } /** The first state: the root, with every component of the parent still to resolve. */ -function startWalk(parent: string, trust: ScriptDestinationTrust): WalkStep { +function startWalk( + parent: string, + trust: ScriptDestinationTrust, + created?: ReadonlyMap, +): WalkStep { const queue = pathComponents(parent); - const ground: WalkGround = { stats: new Map() }; - return standIn('/', queue, trust, 0, ground); + const ground: WalkGround = { judged: new Map(created ?? []) }; + return standOn('/', queue, trust, 0, ground); } -/** Judges `directory` and stands the walk there, or refuses it. */ -function standIn( +/** + * Stands the walk on `directory`, judged from the walk's own `lstat` of it, or refuses it. + * + * A name the walk already judged is reused rather than read again, which is what keeps one walk seeing one + * host. A name this call CREATED is reused the same way, but only while the spelling still answers what the + * creation left there: `..` of a created level, or the second walk over it, would otherwise step through a + * link somebody planted on that name in between. + */ +function standOn( directory: string, queue: readonly string[], trust: ScriptDestinationTrust, hops: number, ground: WalkGround, ): WalkStep { - const stats = readGround(ground, directory); - if (stats === undefined) return { kind: 'reject', path: directory, exposure: 'not_a_directory' }; - const authority: DirectoryAuthority = { uid: stats.uid, gid: stats.gid, mode: stats.mode }; + const judged = judgeGround(ground, directory); + if (judged === 'replaced') + return { kind: 'reject', path: directory, exposure: 'parent_replaced' }; + if (judged === undefined) return { kind: 'reject', path: directory, exposure: 'not_a_directory' }; + const authority: DirectoryAuthority = { + uid: judged.uid, + gid: judged.gid, + mode: judged.mode, + }; const exposure = untrustedAncestryExposure(authority, trust); if (exposure) return { kind: 'reject', path: directory, exposure }; - return { kind: 'stand', state: { deepest: directory, authority, queue, hops, ground } }; + return { + kind: 'stand', + state: { deepest: directory, authority, identity: judged.identity, queue, hops, ground }, + }; } -/** The `stat` of a directory this walk stands in, read from the host at most once per path. */ -function readGround(ground: WalkGround, directory: string): fs.Stats | undefined { - const known = ground.stats.get(directory); - if (known !== undefined) return known; - const stats = statDirectoryChain(directory); - if (stats !== undefined) ground.stats.set(directory, stats); - return stats; +/** + * What this walk knows about a directory: the entry it judged there, `'replaced'` when the name answers + * something else now, or nothing when it is absent or is not a directory. + */ +function judgeGround( + ground: WalkGround, + directory: string, +): JudgedDirectory | 'replaced' | undefined { + const known = ground.judged.get(directory); + const stats = lstatEntry(directory); + if (known !== undefined) { + // The entry is read again to RECOGNIZE it, never to judge it: the authority stays what this walk + // judged first, and a name that answers a different entry now is the swap this rule exists to refuse. + if (stats === undefined || !stats.isDirectory() || identityOf(stats) !== known.identity) { + return 'replaced'; + } + return known; + } + if (stats === undefined || !stats.isDirectory()) return undefined; + const judged = judgedFromStats(stats); + ground.judged.set(directory, judged); + return judged; +} + +/** + * Identity and judged fields of one `lstat` answer, as this rule read them. + * + * Identities come from BIGINT stats: a 32-bit `ino` collapses two distinct large inodes onto one identity, + * which is the collision a comparison exists to catch (`fileIdentity` on the remote route reads bigint for + * the same reason). + */ +function judgedFromStats(stats: fs.BigIntStats): JudgedDirectory { + return { + identity: identityOf(stats), + uid: Number(stats.uid), + gid: Number(stats.gid), + mode: Number(stats.mode), + }; +} + +/** The device and inode an `lstat` answer names. */ +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. */ @@ -579,7 +665,7 @@ function stepThrough( // `..` 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 standIn(path.dirname(state.deepest), rest, trust, state.hops, state.ground); + return standOn(path.dirname(state.deepest), rest, trust, state.hops, state.ground); } return stepIntoEntry(state, component, rest, trust); } @@ -592,7 +678,7 @@ function stepIntoEntry( trust: ScriptDestinationTrust, ): WalkStep { const entry = path.join(state.deepest, component); - const stats = lstatIfPresent(entry); + 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. @@ -601,12 +687,40 @@ function stepIntoEntry( kind: 'short', deepest: state.deepest, authority: state.authority, + identity: state.identity, + ground: state.ground, missing: [component, ...rest], behindUpwardStep: rest.includes('..'), }; } + // Asked before the entry's TYPE is believed, and before it is followed. The name may be one this walk + // judged or one this call created, and a name that answers a different entry than the one recorded is a + // swap: the walk would otherwise judge the target's permissions while entering on the name. + const known = state.ground.judged.get(entry); + if (known !== undefined && known.identity !== identityOf(stats)) { + return { kind: 'reject', path: entry, exposure: 'parent_replaced' }; + } if (stats.isSymbolicLink()) return stepThroughLink(state, entry, stats, rest, trust); - return standIn(entry, rest, trust, state.hops, state.ground); + if (!stats.isDirectory()) return { kind: 'reject', path: entry, exposure: 'not_a_directory' }; + // 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 — the walk would judge the target's permissions while entering on the name. + const judged = known ?? judgedFromStats(stats); + state.ground.judged.set(entry, judged); + const authority: DirectoryAuthority = { uid: judged.uid, gid: judged.gid, mode: judged.mode }; + const exposure = untrustedAncestryExposure(authority, trust); + if (exposure) return { kind: 'reject', path: entry, exposure }; + return { + kind: 'stand', + state: { + deepest: entry, + authority, + identity: judged.identity, + queue: rest, + hops: state.hops, + ground: state.ground, + }, + }; } /** @@ -616,11 +730,11 @@ function stepIntoEntry( function stepThroughLink( state: WalkState, link: string, - stats: fs.Stats, + stats: fs.BigIntStats, rest: readonly string[], trust: ScriptDestinationTrust, ): WalkStep { - const exposure = untrustedLinkExposure({ uid: stats.uid }, state.authority, trust); + 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' }; @@ -631,7 +745,7 @@ function stepThroughLink( // 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 standIn(home, [...pathComponents(target), ...rest], trust, state.hops + 1, state.ground); + return standOn(home, [...pathComponents(target), ...rest], trust, state.hops + 1, state.ground); } /** @@ -646,7 +760,7 @@ export const MAX_SCRIPT_PATH_LINK_HOPS = 30; /** One directory's identity, for a caller that must publish into the same one it created or checked. */ export function publishDirectoryIdentity(directory: string): string | undefined { if (process.platform === 'win32') return 'windows'; - const stats = statDirectoryChain(directory); + const stats = fs.lstatSync(directory, { bigint: true, throwIfNoEntry: false }); return stats ? `${stats.dev}:${stats.ino}` : undefined; } @@ -682,6 +796,7 @@ export type ScriptAncestryExposure = | 'planted_link' | 'link_loop_exceeded' | 'not_a_directory' + | 'entry_appeared' | 'relative_destination' | 'unresolvable_parent' | 'unreachable_parent' @@ -760,6 +875,8 @@ const untrustedGroundWording: Record = { 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: @@ -805,17 +922,71 @@ function ancestryHint(exposure: ScriptAncestryExposure, ancestor: string): strin return 'Save the script under a directory you own that only you can write, and keep the path out of directories other users own.'; } -/** `stat` of the directory a path names, or `undefined` when it is absent or is not a directory. */ -function statDirectoryChain(pathname: string): fs.Stats | undefined { - let stats: fs.Stats | undefined; - try { - stats = fs.statSync(pathname); - } catch (error) { - if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; - throw error; +/** + * Whether `directory` still holds the entry the walk judged there: the same type, and the same device and + * inode. `lstat` again because a `stat` would follow the name and answer whatever it resolves to now. + */ +function stillTheJudgedEntry(directory: string, identity: string): boolean { + const stats = lstatEntry(directory); + return stats !== undefined && stats.isDirectory() && identityOf(stats) === identity; +} + +/** + * Creates the tail the walk found missing, ONE LEVEL AT A TIME, and reports what each level turned out to + * be so the walk that follows judges those names from the creation's own `lstat`. + * + * 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. + * + * `EEXIST` is a refusal, never a retry: the name was absent when the walk looked, so anything standing + * there now was put there by someone else. + */ +function createMissingLevels( + destination: string, + established: string, + establishedId: string, + missing: readonly string[], + trust: ScriptDestinationTrust, +): ReadonlyMap { + const created = new Map(); + let parent = established; + let parentId = establishedId; + for (const name of missing) { + // Confirmed before EACH creation, including inside a level this call made moments ago: a `mkdir` is + // what a moved name would redirect, so the name it is handed must still be the entry judged under it. + if (!stillTheJudgedEntry(parent, parentId)) { + throw scriptAncestryFailure(destination, parent, 'parent_replaced'); + } + const level = path.join(parent, name); + try { + fs.mkdirSync(level, { mode: SCRIPT_DIR_MODE }); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'EEXIST') { + throw scriptAncestryFailure(destination, level, 'entry_appeared'); + } + throw error; + } + fs.chmodSync(level, SCRIPT_DIR_MODE); + const seen = lstatEntry(level); + const judged = seen !== undefined && seen.isDirectory() ? judgedFromStats(seen) : undefined; + if (judged === undefined) { + // The name this call just created is not a directory this call can use: whatever it became, it is + // not the level the destination needs. + throw scriptAncestryFailure(destination, level, 'not_a_directory'); + } + const exposure = untrustedAncestryExposure( + { uid: judged.uid, gid: judged.gid, mode: judged.mode }, + trust, + ); + if (exposure) throw scriptAncestryFailure(destination, level, exposure); + created.set(level, judged); + parent = level; + parentId = judged.identity; } - return stats.isDirectory() ? stats : undefined; + return created; } + function assertSafeDestination(destination: string): void { const stats = lstatIfPresent(destination); if (stats?.isSymbolicLink()) { diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index b8e2088635..66a1a5daf4 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -18,6 +18,7 @@ import { publishDirectoryIdentity, 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'; @@ -202,11 +203,11 @@ async function publishScriptVersion( try { // 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 - // is going to refuse therefore leaves no directories behind in the shared ground it names. - prepareScriptDestination(record.destination); - const allocated = await withRecordLock(file, async () => - allocateStaging(file, record.destination), - ); + // is going to refuse therefore leaves no directories behind in the shared ground it names. The ANSWER + // is what staging is allocated in, so this route walks a destination once per version rather than + // walking it again for the sake of being told the same directory. + const prepared = prepareScriptDestination(record.destination); + const allocated = await withRecordLock(file, async () => allocateStaging(file, prepared)); staging = allocated?.staging; if (!staging || !allocated) return { published: undefined }; const staged = path.join(staging, 'script.ad'); @@ -242,24 +243,29 @@ async function publishScriptVersion( /** * Creates a staging directory beside the destination and lists it in the record before any script - * bytes reach it, and reports the destination directory's identity so the publish can confirm it is - * still the same one. Refuses an ancestor another local user can write (#4565), so nothing is - * downloaded into a directory they control. + * bytes reach it, and reports the destination directory's identity so the publish can confirm it is still + * the same one. * - * Staging sits in the directory the ancestry walk JUDGED, which is the destination's parent as the - * kernel resolves it — not `path.dirname` of the spelled destination. Where a `..` or a link in the - * destination leads elsewhere, the spelled parent is a directory nobody judged, and a staging directory - * in it is a directory another local user can populate before the rename does. + * Staging sits in the directory the ancestry walk JUDGED — the `prepareScriptDestination` answer, not + * `path.dirname` of the spelled destination. Where a `..` or a link in the destination leads elsewhere, the + * spelled parent is a directory nobody judged, and a staging directory in it is one another local user can + * populate before the rename does. The identity is the one that answer carried, so the walk is not asked + * twice for one version. */ function allocateStaging( file: string, - destination: string, + prepared: ScriptDestination, ): { staging: string; parentIdentity: string | undefined } | undefined { const record = readRecord(file); if (!record) return undefined; - const directory = assertPrivateScriptDestination(destination); + const directory = prepared.directory; + // One identity check, not a second walk: the answer is only used where the name still holds the entry the + // walk judged it for. Nothing is staged in a directory that moved in between. + if (publishDirectoryIdentity(directory) !== prepared.identity) { + throw destinationMoved(record.destination, directory); + } const staging = fs.mkdtempSync(path.join(directory, '.agent-device-script-')); - const parentIdentity = publishDirectoryIdentity(directory); + const parentIdentity = prepared.identity; try { writeRecord(file, { ...record, staging: [...(record.staging ?? []), staging] }); } catch (error) { @@ -405,6 +411,21 @@ function fileIdentity(file: string): string | undefined { return stat ? `${stat.dev}:${stat.ino}` : undefined; } +/** The judged answer no longer names the entry it was judged for, so this version publishes nowhere. */ +function destinationMoved(destination: string, directory: string): AppError { + return new AppError( + 'COMMAND_FAILED', + `The directory for ${destination} changed while the script was staged, so the script was not saved.`, + { + reason: 'script_ancestry_replaced', + exposure: 'parent_replaced', + path: destination, + ancestor: directory, + hint: 'Re-record with open --save-script, or save under a directory nobody else can write.', + }, + ); +} + function scriptDeliveryFailure( destination: string, publicationId: string, diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 75cd7a7221..09f39f828b 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -214,7 +214,7 @@ "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:4b932f798f4e0b3871270c5b5f1e0081bc056a96c14ea382d94230d98e9b21f9", + "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:7933a02d17d7d8a48e9ba542480a9703ad8688f5ac30c186e503700fe982254e", "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" @@ -222,8 +222,8 @@ "compatibleChanges": [ { "declaration": "packages/remote/src/session-script-destination.ts#publishScriptVersion", - "digest": "sha256:4b932f798f4e0b3871270c5b5f1e0081bc056a96c14ea382d94230d98e9b21f9", - "rationale": "#4565 adds one call ahead of the `mkdir` that creates a missing parent: the destination-ancestry rule is asked over the directories that already exist, so a destination it is going to refuse leaves no directories behind. Nothing on the wire changes: no request field is added, removed or renamed, no response field, route, status or artifact framing moves, and the download contract this declaration consumes is untouched. A released daemon receives exactly the same request and answers the same way; a released caller resolves the same paths on its own disk. A skewed peer parses every payload as before. #4565 revises that local sequencing only: the `mkdir` moves into host-kit's one destination call, which refuses an unsafe destination before creating anything and creates what is missing at 0700, and the judged directory's identity is compared once before the rename. Nothing on the wire moves: same request fields, same response fields, same routes, status and artifact framing, and the download contract this declaration consumes is untouched. A released daemon receives the same request and answers the same way; a released caller resolves the same paths on its own disk." + "digest": "sha256:7933a02d17d7d8a48e9ba542480a9703ad8688f5ac30c186e503700fe982254e", + "rationale": "#4565 adds one call ahead of the `mkdir` that creates a missing parent: the destination-ancestry rule is asked over the directories that already exist, so a destination it is going to refuse leaves no directories behind. Nothing on the wire changes: no request field is added, removed or renamed, no response field, route, status or artifact framing moves, and the download contract this declaration consumes is untouched. A released daemon receives exactly the same request and answers the same way; a released caller resolves the same paths on its own disk. A skewed peer parses every payload as before. #4565 revises that local sequencing only: the `mkdir` moves into host-kit's one destination call, which refuses an unsafe destination before creating anything and creates each missing level at 0700 inside the directory it judged. That call now ANSWERS the judged directory and its identity, so this route stages each version beside the destination without walking the destination a second time, and confirms the identity before the rename. Nothing on the wire moves: same request fields, same response fields, same routes, status and artifact framing, and the download contract this declaration consumes is untouched. A released daemon receives the same request and answers the same way; a released caller resolves the same paths on its own disk." }, { "declaration": "packages/kernel/src/contracts.ts#DaemonRequestMeta", diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index bb0e2b9076..379c756e25 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -70,7 +70,7 @@ 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, 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. +- 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. From eaa9747ef064d6be23d5f46a83e2b7b490f9f59b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 22:24:26 +0100 Subject: [PATCH 19/28] fix(daemon-contracts): judge a state repair before forcing its mode `repairStateMode` forced a mode by pathname, with no type and no ownership check. A root daemon starting against a legacy state directory another user could write can be handed a `sessions` that is a LINK, and the chmod travels through it to a directory that user owns. `ensurePrivateDaemonStateDir` now repairs each level it was asked for from its own `lstat` of the ENTRY: a link or a non-directory is refused (`state_dir_not_a_directory`), a level this process does not own is refused (`state_dir_foreign_owned`), and in both cases nothing is changed. What remains to repair is forced through a descriptor opened `O_DIRECTORY | O_NOFOLLOW`, whose `fstat` dev:ino is confirmed to be the entry the `lstat` judged, so the mode cannot be applied to a second entry behind the name. Ownership is asked only when a mode has to change, so the common startup is still one `lstat`, and no second rule is introduced. Coverage: the repair owner's refusals, and the same two shapes seen through the daemon's own state paths, with foreign ownership simulated as root state (serveHostOwnership); plus pre-existing owned 0775 `sessions` and `remote-scripts` repaired to 0700, which the previous test could not see because it started from 0700. ADR 0016 said remote delivery compares the judged identity ONCE. It asks the rule twice per version, because a download runs in between: prepare and allocate staging, then walk again and compare before the rename. What this branch removed is the THIRD walk the allocation used to run to be told a directory the call before it had already answered. The ADR, and the PR body, say that. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 4 +- ...aemon-registration-owner-state-dir.test.ts | 105 ++++++++++++++++ .../src/daemon-registration-owner.ts | 117 +++++++++++++++++- .../session-store-teardown-script.test.ts | 108 +++++++++++++++- 4 files changed, 330 insertions(+), 4 deletions(-) create mode 100644 packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index f2db2eec6d..aacdfdbf32 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -222,9 +222,9 @@ Shapes this closes, each of which an earlier shape of the rule accepted: The walk ANSWERS with the physical directory the entry is created in, and confirms at that moment that the name the answer is spelled by still holds the entry it judged: a name that answers something else by then is refused (`parent_replaced`), because the caller's next `mkdir`, staging `mkdtemp` or `rename` would travel through it. Directory identities are read as BIGINT, because a 32-bit `ino` collapses two distinct large inodes onto one identity and a swap between the two would then look like the same directory. Both publishers stage inside that directory 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 walk, 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. Where a walk returns to a name it already judged, through a `..` or an alias, it re-reads that name only to RECOGNIZE it and keeps the judgment it first made. 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. +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 applies the same judgment as the walk, and to one directory less: each level is read by `lstat`, so a `sessions` another user left as a LINK is refused rather than followed, and a level this process does not own is refused rather than chmod'ed — a repair that forced the mode by pathname would reach through the link and, run by a root daemon, strip access from an owner who never ran the daemon. The mode is forced through a descriptor opened `O_DIRECTORY | O_NOFOLLOW`, whose `fstat` is confirmed to be the entry the `lstat` judged. 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 remote route captures the judged directory's `dev:ino` when it allocates staging and compares it once, under its record lock, right before the rename, because the download runs in between. That is the ONLY such comparison: the local publish does not repeat it. The ownership rule is what closes the window — anyone able to swap a judged directory was refused at it — and a second re-check would answer for a race the permissions rule already excludes. +Remote delivery asks the rule TWICE per version, because the download runs between the two: once before staging is allocated, and once again under the record lock right before the rename. The first call creates what is missing and ANSWERS the judged directory with its `dev:ino`; allocating staging confirms that name still holds that entry, by identity alone, and stages inside that directory. The second call walks the chain again after the download and compares the identity the answer carried, so a version is never renamed into ground nobody judged. What was removed is a THIRD walk, which an earlier shape ran at allocation to be told the directory a call one line earlier had already answered; the identity comparison it did stands, and an allocation that is not a walk cannot answer for the ground the download moved. The local publish walks once and does not repeat the comparison, 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 these comparisons are 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 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..ed4ce8b7a1 --- /dev/null +++ b/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts @@ -0,0 +1,105 @@ +// 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 name +// this process may not touch is refused with nothing changed, rather than repaired through the name. +// (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 { AppError } from '@agent-device/kernel/errors'; +import { ensurePrivateDaemonStateDir } from './daemon-registration-owner.ts'; + +const skipOnWindows = process.platform === 'win32' ? test.skip : test; + +afterEach(() => { + vi.restoreAllMocks(); +}); + +skipOnWindows('repairs the state directories it owns, whatever mode they 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. + 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/`, the remote writer ensures + // `remote-scripts/`, and each call repairs the levels it was asked for. + ensurePrivateDaemonStateDir(sessions); + expect(ensurePrivateDaemonStateDir(remote)).toBe(remote); + + for (const directory of [sessions, remote]) { + expect(fs.lstatSync(directory).mode & 0o777).toBe(0o700); + } +}); + +skipOnWindows('refuses a state name that is a link, and leaves where it leads alone', () => { + // Repair reaches a legacy state directory another local user could write, and they use that write to + // leave a link at `sessions`. A `chmod` given the NAME travels through it, so a root daemon forcing its + // own state private would be changing the mode of a directory somebody else chose. The link itself is the + // refusal: it is not the directory this call was told to make private. + const base = mkdtempForTestSync('agent-device-state-link-'); + fs.chmodSync(base, 0o777); + const planted = path.join(base, 'other-users-home'); + fs.mkdirSync(planted); + fs.chmodSync(planted, 0o777); + const sessions = path.join(base, 'sessions'); + fs.symlinkSync(planted, sessions); + + expectRefusal(() => ensurePrivateDaemonStateDir(sessions), 'state_dir_not_a_directory', sessions); + + // Nothing was changed: the mode the owner set is still the mode the directory has, and no state + // directory appeared under the name. + expect(fs.lstatSync(planted).mode & 0o777).toBe(0o777); + expect(fs.lstatSync(sessions).isSymbolicLink()).toBe(true); +}); + +skipOnWindows('refuses a state directory another user owns, and leaves its mode', () => { + // Ownership is judged from the same `lstat` the destination rule judges ground by, so a root daemon + // repairs root-owned state and does NOT strip access from a directory somebody else owns — which a + // `chmod 0700` by pathname would have done to their files. + 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 }); + + expectRefusal(() => ensurePrivateDaemonStateDir(sessions), 'state_dir_foreign_owned', sessions); + + expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o775); +}); + +skipOnWindows('warns and changes nothing when a state directory cannot be opened at all', () => { + // A state directory left at 0000 is this process's own, so ownership does not refuse it, and no + // descriptor can be opened to force its mode. Repair reports that and moves on: startup must not die on a + // host it cannot fix, which is the rule `repairStateMode` already applied to a read-only mount. + const base = mkdtempForTestSync('agent-device-state-unreadable-'); + fs.chmodSync(base, 0o755); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions); + fs.chmodSync(sessions, 0o000); + + try { + expect(() => ensurePrivateDaemonStateDir(sessions)).not.toThrow(); + expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o000); + } finally { + fs.chmodSync(sessions, 0o700); + } +}); + +/** The typed refusal the repair answers with, naming the state path it would not touch. */ +function expectRefusal(run: () => void, reason: string, target: string): void { + let seen: AppError | undefined; + try { + run(); + } catch (error) { + seen = error instanceof AppError ? error : undefined; + } + expect(seen?.details).toMatchObject({ reason, path: target }); +} diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index 7ff64a0eda..4f691fbce7 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -286,6 +286,10 @@ export function createOwnedReplayStateDir(): OwnedReplayStateDir { * remote-delivered version. Creation carries the mode and the repair forces it, because a state dir an older * version created at 0775 is the same refusal. * + * A level that is not a directory this process owns is REFUSED rather than repaired (#4565): a repair that + * chmods by pathname reaches through a planted link, so a root daemon starting against a legacy writable + * state directory would change the mode of a directory another user owns. + * * Returns the path so a caller can name what it just made without a second `mkdir` of its own. */ export function ensurePrivateDaemonStateDir(directory: string): string { @@ -294,7 +298,7 @@ export function ensurePrivateDaemonStateDir(directory: string): string { // private. Repairing only the leaf would leave the level ABOVE a session directory, `sessions/`, at the // 0775 a umask-002 creation gives it, which is the directory every recording is walked through. for (const level of createdStateLevels(firstCreated, directory)) { - repairStateMode(level, STATE_DIR_MODE); + repairPrivateStateDir(level); } return directory; } @@ -317,6 +321,117 @@ function createdStateLevels( const STATE_DIR_MODE = 0o700; +/** + * Forces one state level to the private mode, or refuses it and changes NOTHING. + * + * `chmod` by pathname acts on whatever the NAME resolves to, so repairing a legacy state directory that was + * writable by others is not safe on its own: another user who could write it can leave a link at `sessions`, + * and a root daemon asked to repair that name would change the mode of a directory they own. So the level is + * judged by this call's own `lstat` — the ENTRY under the name — before anything is forced, and only a level + * that is a directory, and is not already private, reaches {@link forcePrivateStateDir}. + */ +function repairPrivateStateDir(directory: string): void { + // Windows answers access from an ACL, and `chmod` there only toggles the read-only bit. + if (process.platform === 'win32') return; + const judged = fs.lstatSync(directory, { bigint: true, throwIfNoEntry: false }); + // The name is gone by now: whatever removed it also removed the mode this call came to force. + if (judged === undefined) return; + // A LINK is refused even where its target is already private: the name is what this call was handed, and + // a link under it was put there by whoever could write this directory. + if (!judged.isDirectory()) throw privateStateRefusal(directory, 'state_dir_not_a_directory'); + // Already private, so nothing is changed and nobody's ownership has to be asked. + if ((Number(judged.mode) & 0o777) === STATE_DIR_MODE) return; + forcePrivateStateDir(directory, judged); +} + +/** + * Applies {@link STATE_DIR_MODE} to the entry the name holds, through a descriptor opened on that name. + * + * Ownership is judged from the `lstat`, as the destination-ancestry rule judges ground: a root daemon + * therefore repairs root-owned state and leaves a directory another user owns alone, rather than making it + * unreachable to them. The descriptor's `fstat` must answer the entry the `lstat` judged, so the mode cannot + * land on something put behind the name in between. + */ +function forcePrivateStateDir(directory: string, judged: fs.BigIntStats): void { + if (!thisUsersEntry(judged)) throw privateStateRefusal(directory, 'state_dir_foreign_owned'); + let descriptor: number | undefined; + try { + descriptor = openStateEntry(directory); + const opened = fs.fstatSync(descriptor, { bigint: true }); + if (!sameStateEntry(opened, judged)) { + throw privateStateRefusal(directory, 'state_dir_entry_replaced'); + } + if (!thisUsersEntry(opened)) { + throw privateStateRefusal(directory, 'state_dir_foreign_owned'); + } + fs.fchmodSync(descriptor, STATE_DIR_MODE); + } catch (error) { + if (error instanceof AppError) throw error; + // `EACCES` says the directory does not even let THIS user open it (a state directory left at 0000): no + // descriptor exists to force the mode with, and startup must not fail on a host it cannot fix. + if (!STATE_DIR_REPAIR_SKIPPED_CODES.has((error as NodeJS.ErrnoException).code ?? '')) + throw error; + emitDiagnostic({ + level: 'warn', + phase: 'daemon_state_mode_repair_skipped', + data: { path: directory, error: normalizeError(error) }, + }); + } finally { + if (descriptor !== undefined) fs.closeSync(descriptor); + } +} + +/** Whether an entry belongs to the user this process runs as. */ +function thisUsersEntry(stats: fs.BigIntStats): boolean { + return Number(stats.uid) === (process.getuid?.() ?? -1); +} + +/** Whether a descriptor answers the same entry an `lstat` judged. */ +function sameStateEntry(opened: fs.BigIntStats, judged: fs.BigIntStats): boolean { + return `${opened.dev}:${opened.ino}` === `${judged.dev}:${judged.ino}`; +} + +/** A repair that cannot be done now, on top of what a mode repair may never fail the daemon on. */ +const STATE_DIR_REPAIR_SKIPPED_CODES = new Set([ + 'EPERM', + 'EROFS', + 'ENOTSUP', + 'EOPNOTSUPP', + 'EACCES', +]); + +/** + * Opens the entry the name holds, refusing one that is not a directory the caller may enter: `O_NOFOLLOW` + * answers `ELOOP` for a link, and `O_DIRECTORY` for anything that is not a directory. + */ +function openStateEntry(directory: string): number { + try { + return fs.openSync( + directory, + fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW, + ); + } catch (error) { + const code = (error as NodeJS.ErrnoException).code ?? ''; + if (code === 'ELOOP' || code === 'ENOTDIR') { + throw privateStateRefusal(directory, 'state_dir_not_a_directory'); + } + throw error; + } +} + +/** A state name this call will not touch, with the shape that made it unsafe. */ +function privateStateRefusal(directory: string, reason: string): AppError { + return new AppError( + 'COMMAND_FAILED', + `Refusing to repair the daemon state directory ${directory}.`, + { + reason, + path: directory, + hint: 'Restore the state directory owned by the user who runs the daemon, or point AGENT_DEVICE_STATE_DIR at one.', + }, + ); +} + /** * 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 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 a926cb2d2f..89d1bae665 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,14 @@ 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 { AppError } from '@agent-device/kernel/errors'; import { SessionStore } from '../session-store.ts'; import { authoringPublication, @@ -132,7 +139,106 @@ test.skipIf(process.platform === 'win32')( }, ); +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); + 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')( + 'refuses to repair a `sessions` directory another user owns, and changes nothing there', + () => { + // 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. + 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(refusalOf(() => ensurePrivateDaemonStateDir(sessions))).toMatchObject({ + reason: 'state_dir_foreign_owned', + path: sessions, + }); + + // 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')( + 'refuses a planted `sessions` link under state another user can write, and leaves where it leads alone', + () => { + // 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 ENTRY under the name is what gets judged instead, so the link itself is the refusal. + 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(refusalOf(() => ensurePrivateDaemonStateDir(sessions))).toMatchObject({ + reason: 'state_dir_not_a_directory', + path: sessions, + }); + + 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); } + +/** The typed details of the refusal a state repair answered with. */ +function refusalOf(run: () => void): Record | undefined { + try { + run(); + } catch (error) { + return (error as AppError).details as Record; + } + throw new Error('a state directory this process may not repair was repaired'); +} From ed5c7b9618bdbcc158f823de671ee731e09453ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 23:54:03 +0100 Subject: [PATCH 20/28] fix(host-kit): confirm a script destination with one call, and cut the rest Host-kit now exports one confirmation: `confirmScriptDestination(destination, prepared)` walks the destination again, compares it with the identity `prepareScriptDestination` answered, and returns the directory to create the entry in. The remote route calls it after its download, under the record lock, so every `parent_replaced` refusal is built by `scriptAncestryFailure` and no route holds a copy of the reason, exposure, ancestor or hint. `destinationMoved` and the local identity compare are deleted, along with the hand-kept reason literals: the route reads the reason back through `scriptAncestryReason`. The recognition layer that grew around the walk is cut, because the ownership rule is what excludes anyone who could move a judged directory. The walk keeps no memory of ground it stood on, does not re-recognise a name it reached through a `..` or an alias, and runs no second identity check before a creation. What is kept per step is one `lstat` of that step, never a `stat`. `createMissingLevel` judges a name that appeared instead of refusing it: the same single `lstat`, the same rule. It adopts a private directory this user owns, refuses a foreign or writable one, and asks whether other local users could add the destination's own name inside it. Startup is pinned as the thing that repairs a state chain a legacy release or a shared checkout left at 0775, and a state repair that forces a mode through a descriptor is asserted as such. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 6 +- .../http/daemon-runtime-state-dir.test.ts | 111 ++++++ packages/host-kit/src/file.ts | 4 +- .../src/internal/atomic-file-ancestry.test.ts | 239 ++++-------- .../src/internal/atomic-file-parent.test.ts | 143 ++++++- packages/host-kit/src/internal/atomic-file.ts | 357 ++++++++---------- .../remote/src/session-script-destination.ts | 71 +--- src/__tests__/daemon-launch-cwd.test.ts | 33 +- test/wire-compat/ledger.json | 6 +- 9 files changed, 515 insertions(+), 455 deletions(-) create mode 100644 packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index aacdfdbf32..2055ada251 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -210,7 +210,7 @@ It adds no state name, command, or flag: 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. Each level is confirmed to be the entry its parent was judged for before the name below it is created, and a name that was absent when the walk looked and exists by the time `mkdir` reaches it is refused (`entry_appeared`) rather than adopted. 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. +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: @@ -219,12 +219,12 @@ Shapes this closes, each of which an earlier shape of the rule accepted: - `..` 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 confirms at that moment that the name the answer is spelled by still holds the entry it judged: a name that answers something else by then is refused (`parent_replaced`), because the caller's next `mkdir`, staging `mkdtemp` or `rename` would travel through it. Directory identities are read as BIGINT, because a 32-bit `ino` collapses two distinct large inodes onto one identity and a swap between the two would then look like the same directory. Both publishers stage inside that directory 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 walk, 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. Where a walk returns to a name it already judged, through a `..` or an alias, it re-reads that name only to RECOGNIZE it and keeps the judgment it first made. +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 applies the same judgment as the walk, and to one directory less: each level is read by `lstat`, so a `sessions` another user left as a LINK is refused rather than followed, and a level this process does not own is refused rather than chmod'ed — a repair that forced the mode by pathname would reach through the link and, run by a root daemon, strip access from an owner who never ran the daemon. The mode is forced through a descriptor opened `O_DIRECTORY | O_NOFOLLOW`, whose `fstat` is confirmed to be the entry the `lstat` judged. 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 asks the rule TWICE per version, because the download runs between the two: once before staging is allocated, and once again under the record lock right before the rename. The first call creates what is missing and ANSWERS the judged directory with its `dev:ino`; allocating staging confirms that name still holds that entry, by identity alone, and stages inside that directory. The second call walks the chain again after the download and compares the identity the answer carried, so a version is never renamed into ground nobody judged. What was removed is a THIRD walk, which an earlier shape ran at allocation to be told the directory a call one line earlier had already answered; the identity comparison it did stands, and an allocation that is not a walk cannot answer for the ground the download moved. The local publish walks once and does not repeat the comparison, 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 these comparisons are defense in depth against a host whose modes moved, not what excludes the attacker. +Remote delivery walks a destination TWICE per version, and compares identity ONCE. The first walk happens before staging: it creates what is missing and 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 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..e41c103e9c --- /dev/null +++ b/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts @@ -0,0 +1,111 @@ +// 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. +// (https://github.com/callstack/agent-device/pull/4584) + +import fs from 'node:fs'; +import { expect, test } from 'vitest'; +import { + createTestHostEnvironment, + FOREIGN_UID, + mkdtempForTestSync, + serveHostOwnership, +} from '@agent-device/test-kit'; +import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; +import { AppError } from '@agent-device/kernel/errors'; +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 refuses state it may not force private, instead of changing another user files', + async () => { + // A `sessions` left owned by a different uid — the shape a machine sees when one user ran the daemon as + // root — is refused with its mode intact. Forcing it would take a directory away from its owner. + const stateDir = mkdtempForTestSync('agent-device-startup-state-foreign-'); + const { sessionsDir } = resolveDaemonPaths(stateDir); + fs.mkdirSync(sessionsDir, { mode: 0o755 }); + fs.chmodSync(sessionsDir, 0o775); + serveHostOwnership({ [sessionsDir]: FOREIGN_UID }); + + const started = startDaemonRuntime({ + host: hostFor(stateDir), + ...silent, + composeDeps: daemonRuntimeDepsFixture({}), + }); + + expect(detailsOf(await started.catch((error: unknown) => error))).toMatchObject({ + reason: 'state_dir_foreign_owned', + path: sessionsDir, + }); + expect(modeOf(sessionsDir)).toBe(0o775); + }, +); + +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); +} + +/** The typed details of the startup failure, so a refusal is read by its reason and never by its text. */ +function detailsOf(error: unknown): Record | undefined { + return error instanceof AppError ? (error.details as Record) : undefined; +} diff --git a/packages/host-kit/src/file.ts b/packages/host-kit/src/file.ts index b4c0942890..1baf896441 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -1,9 +1,9 @@ export { - assertPrivateScriptDestination, + confirmScriptDestination, + scriptAncestryReason, isAtomicPublishTemporaryPath, lstatIfPresent, prepareScriptDestination, - publishDirectoryIdentity, publishDurableFileSync, publishFileSync, publishScriptFileSync, diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index 4193a57f67..8d6b0da2fc 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -13,12 +13,23 @@ import { publish, } from './atomic-file-host.fixtures.ts'; import { - assertPrivateScriptDestination, - publishDirectoryIdentity, + confirmScriptDestination, + prepareScriptDestination, 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(() => { @@ -79,11 +90,7 @@ skipOnWindows('refuses a destination under a world-writable directory', () => { skipOnWindows('refuses a destination created inside a directory others can add entries to', () => { const shared = directoryWith(path.join(root(), 'shared'), 0o777 | 0o1000); - expectUntrusted( - () => assertPrivateScriptDestination(path.join(shared, 'journey.ad')), - 'shared_parent', - shared, - ); + expectUntrusted(() => judgedDirectory(path.join(shared, 'journey.ad')), 'shared_parent', shared); expect(fs.existsSync(path.join(shared, 'journey.ad'))).toBe(false); }); @@ -102,11 +109,7 @@ skipOnWindows('refuses a directory another user owns, whatever the mode', () => const work = directoryWith(path.join(root(), 'foreign'), 0o755); serveOwnership({ [work]: FOREIGN_UID }); - expectUntrusted( - () => assertPrivateScriptDestination(path.join(work, 'journey.ad')), - 'foreign_owned', - work, - ); + expectUntrusted(() => judgedDirectory(path.join(work, 'journey.ad')), 'foreign_owned', work); }); skipOnWindows( @@ -119,11 +122,7 @@ skipOnWindows( const work = path.join(team, 'work'); fs.mkdirSync(work); - expectUntrusted( - () => assertPrivateScriptDestination(path.join(work, 'journey.ad')), - 'foreign_owned', - team, - ); + expectUntrusted(() => judgedDirectory(path.join(work, 'journey.ad')), 'foreign_owned', team); }, ); @@ -140,7 +139,7 @@ skipOnWindows( serveOwnership({ [systemTmp]: 0, [recordings]: FOREIGN_UID }); expectUntrusted( - () => assertPrivateScriptDestination(path.join(recordings, 'journey.ad')), + () => judgedDirectory(path.join(recordings, 'journey.ad')), 'foreign_owned', recordings, ); @@ -159,7 +158,7 @@ skipOnWindows('refuses a link standing in a private-mode directory another user fs.symlinkSync(mine, path.join(teammate, 'link')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(teammate, 'link', 'journey.ad')), + () => judgedDirectory(path.join(teammate, 'link', 'journey.ad')), 'foreign_owned', teammate, ); @@ -179,7 +178,7 @@ skipOnWindows('refuses a private link standing on shared ground two levels up', fs.symlinkSync(privateWork, path.join(mine, 'rec')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(mine, 'rec', 'journey.ad')), + () => judgedDirectory(path.join(mine, 'rec', 'journey.ad')), 'world_writable', shared, ); @@ -202,7 +201,7 @@ skipOnWindows('refuses a chain that leaves a shared directory through an interme fs.symlinkSync(path.join(team, 'relay'), path.join(home, 'rec')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), 'world_writable', team, ); @@ -222,7 +221,7 @@ skipOnWindows('judges the directory a .. steps back into', () => { fs.symlinkSync(dir, path.join(privateHome, 'link')); expectUntrusted( - () => assertPrivateScriptDestination(`${privateHome}/link/../x/journey.ad`), + () => judgedDirectory(`${privateHome}/link/../x/journey.ad`), 'world_writable', elsewhere, ); @@ -244,7 +243,7 @@ skipOnWindows('refuses the ground under a link that leads into a shared director fs.symlinkSync(path.join(shared, 'mine', 'relay', 'subdir'), path.join(home, 'rec')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), 'world_writable', shared, ); @@ -269,7 +268,7 @@ skipOnWindows( fs.symlinkSync(path.join('..', 'shared', 'mine', 'relay', 'sub'), path.join(home, 'rec')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), 'world_writable', shared, ); @@ -336,7 +335,7 @@ skipOnWindows( return (realStatSync as (...args: unknown[]) => unknown)(pathname, ...rest); }) as typeof fs.statSync); - expect(assertPrivateScriptDestination(`${home}/a/../b/below/journey.ad`)).toBe(below); + 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. @@ -348,38 +347,6 @@ skipOnWindows( }, ); -skipOnWindows('refuses a directory whose name answers a different entry on the second look', () => { - // The walk judges an entry by its own `lstat` and remembers that identity. Here the second route into - // `sub` finds a DIFFERENT entry under that name — the swap the permission rule exists to exclude — so the - // walk refuses instead of standing on ground it never judged. - const directory = root(); - const home = directoryWith(path.join(directory, 'home'), 0o700); - const sub = directoryWith(path.join(home, 'sub'), 0o700); - fs.mkdirSync(path.join(sub, 'below')); - fs.symlinkSync(sub, path.join(home, 'a')); - fs.symlinkSync(sub, path.join(home, 'b')); - const realLstatSync = fs.lstatSync; - let crossed = 0; - vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { - const stats = (realLstatSync as (...args: unknown[]) => unknown)( - pathname, - ...rest, - ) as fs.BigIntStats; - // The first route in sees the real `sub`; the second sees another entry answering that name. - if (String(pathname) === sub && crossed++ > 0) { - return Object.assign(Object.create(Object.getPrototypeOf(stats)), stats, { - ino: stats.ino + 1n, - }); - } - return stats; - }) as typeof fs.lstatSync); - - expectUntrustedReplaced( - () => assertPrivateScriptDestination(`${home}/a/../b/below/journey.ad`), - sub, - ); -}); - skipOnWindows( 'refuses a destination that is not absolute, before judging or creating anything', () => { @@ -395,11 +362,7 @@ skipOnWindows( process.chdir(home); expectUntrusted(() => publish('journey.ad'), 'relative_destination', '.'); - expectUntrusted( - () => assertPrivateScriptDestination('work/journey.ad'), - 'relative_destination', - 'work', - ); + 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 { @@ -416,7 +379,7 @@ skipOnWindows('refuses a relative target that lands in ground others can write', fs.symlinkSync('open', path.join(home, 'rel')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(home, 'rel', 'journey.ad')), + () => judgedDirectory(path.join(home, 'rel', 'journey.ad')), 'world_writable', open, ); @@ -437,7 +400,7 @@ skipOnWindows('applies a .. inside a target to the directory the walk reached', fs.symlinkSync('priv/../x', path.join(home, 'rel')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(home, 'rel', 'journey.ad')), + () => judgedDirectory(path.join(home, 'rel', 'journey.ad')), 'world_writable', shared, ); @@ -466,15 +429,11 @@ skipOnWindows('refuses the spelled spelling of a link the walk also follows', () fs.symlinkSync(shared, path.join(home, 'rec')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), - 'world_writable', - shared, - ); - expectUntrusted( - () => assertPrivateScriptDestination(path.join(shared, 'journey.ad')), + () => 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', () => { @@ -490,11 +449,7 @@ skipOnWindows('applies .. to the directory the walk is in, not to the spelling', fs.mkdirSync(path.join(home, 'y')); fs.symlinkSync(privX, path.join(home, 'work')); - expectUntrusted( - () => assertPrivateScriptDestination(`${home}/work/../y/journey.ad`), - 'world_writable', - privY, - ); + expectUntrusted(() => judgedDirectory(`${home}/work/../y/journey.ad`), 'world_writable', privY); expect(fs.readdirSync(privY)).toEqual([]); }); @@ -512,7 +467,7 @@ skipOnWindows('refuses a link whose target stands in ground another local user o fs.symlinkSync(relay, path.join(home, 'rec')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), 'planted_link', relay, ); @@ -546,11 +501,7 @@ skipOnWindows('refuses a link loop instead of trusting where the walk ran out', const loop = path.join(work, 'loop'); fs.symlinkSync(loop, loop); - expectUntrusted( - () => assertPrivateScriptDestination(path.join(loop, 'journey.ad')), - 'link_loop_exceeded', - loop, - ); + expectUntrusted(() => judgedDirectory(path.join(loop, 'journey.ad')), 'link_loop_exceeded', loop); expect(fs.readdirSync(work)).toEqual(['loop']); }); @@ -580,7 +531,7 @@ skipOnWindows('follows thirty link hops, and refuses the thirty-first', () => { fs.rmSync(path.join(real, 'journey.ad'), { force: true }); expectUntrusted( - () => assertPrivateScriptDestination(path.join(chain(31), 'journey.ad')), + () => judgedDirectory(path.join(chain(31), 'journey.ad')), 'link_loop_exceeded', path.join(work, 'link30'), ); @@ -595,7 +546,7 @@ skipOnWindows('refuses a path component that cannot carry a publish', () => { fs.writeFileSync(blocker, 'not a directory\n'); expectUntrusted( - () => assertPrivateScriptDestination(path.join(blocker, 'journey.ad')), + () => judgedDirectory(path.join(blocker, 'journey.ad')), 'not_a_directory', blocker, ); @@ -650,7 +601,7 @@ skipOnWindows('refuses a link planted in a directory others can add entries to', fs.symlinkSync(attacker, path.join(shared, 'work')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(shared, 'work', 'journey.ad')), + () => judgedDirectory(path.join(shared, 'work', 'journey.ad')), 'world_writable', shared, ); @@ -673,7 +624,7 @@ skipOnWindows('refuses a private link whose target chain is a shared directory', fs.symlinkSync(rec, path.join(home, 'rec')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(home, 'rec', 'journey.ad')), + () => judgedDirectory(path.join(home, 'rec', 'journey.ad')), 'world_writable', team, ); @@ -687,7 +638,7 @@ skipOnWindows('refuses a symbolic link whose target is a directory others can wr fs.symlinkSync(privateWork, path.join(directory, 'link')); expectUntrusted( - () => assertPrivateScriptDestination(path.join(directory, 'link', 'journey.ad')), + () => judgedDirectory(path.join(directory, 'link', 'journey.ad')), 'world_writable', shared, ); @@ -708,7 +659,7 @@ skipOnWindows( serveOwnership({ [shared]: 0, [link]: FOREIGN_UID }); expectUntrusted( - () => assertPrivateScriptDestination(path.join(shared, 'work', 'journey.ad')), + () => judgedDirectory(path.join(shared, 'work', 'journey.ad')), 'planted_link', link, ); @@ -781,20 +732,20 @@ skipOnWindows('publishes to a scratch path exactly as the host spelled it', () = // --- the destination directory swapped out while the file was staged --- -// Only a caller that captured the identity EARLIER passes one: 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 remote route's single comparison. +// 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 parentIdentity = publishDirectoryIdentity(staged); const destination = path.join(staged, 'journey.ad'); - // 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 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 }); @@ -802,92 +753,31 @@ skipOnWindows('refuses a parent replaced by name while the file was 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( - () => assertPrivateScriptDestination(destination, parentIdentity), - elsewhere, - ); + expectUntrustedReplaced(() => confirmScriptDestination(destination, prepared), elsewhere); expect(fs.existsSync(path.join(elsewhere, 'journey.ad'))).toBe(false); }); -skipOnWindows('accepts the identity a caller captured for the directory the walk answers', () => { - const directory = root(); - const staged = path.join(directory, 'work'); - fs.mkdirSync(staged); - const destination = path.join(staged, 'journey.ad'); +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(assertPrivateScriptDestination(destination, publishDirectoryIdentity(staged))).toBe( - staged, - ); - expect(assertPrivateScriptDestination(destination)).toBe(staged); -}); + expect(confirmScriptDestination(destination, prepared)).toBe(staged); + }, +); // --- a step swapped out while the walk is still running --- -skipOnWindows('refuses a directory swapped for a link between the lstat and entering it', () => { - // The attacker owns `decoy` and stands in a sticky shared parent, where they may replace their own - // entry. Between the walk's `lstat` of `decoy` and the moment it would enter that name, they swap it - // for a link to their own directory. Entering it is what redirects the publish, so the walk judges the - // entry its OWN lstat saw: a name that answers something else by then is refused, and a link planted - // afterwards is never stepped through on the strength of its target. - const directory = root(); - const sticky = directoryWith(path.join(directory, 'tmp'), 0o1777); - const decoy = path.join(sticky, 'decoy'); - fs.mkdirSync(decoy); - const attacker = path.join(directory, 'attacker'); - fs.mkdirSync(attacker); - fs.chmodSync(attacker, 0o700); - const realLstatSync = fs.lstatSync; - let looks = 0; - vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { - // The first look is the walk's judgment: the attacker's OWN directory. The swap lands immediately - // after that judgment, so every later look at this name answers a link. - if (String(pathname) === decoy && ++looks === 2) { - fs.renameSync(decoy, `${decoy}.real`); - fs.symlinkSync(attacker, decoy); - } - return (realLstatSync as (...args: unknown[]) => unknown)(pathname, ...rest); - }) as typeof fs.lstatSync); - - const destination = path.join(decoy, 'sub', 'journey.ad'); - - expectUntrustedReplaced(() => publish(destination), decoy); - // Nothing was staged in the directory the link leads to, which is what the swap was for. - expect(fs.readdirSync(attacker)).toEqual([]); -}); - -skipOnWindows('refuses an answer whose directory was swapped for a link before staging', () => { - // The walk can be asked for an answer and then hand it to a caller that stages bytes there. If the name - // the answer is spelled by answers a link in between, `mkdir`, `mkdtemp` and `rename` would all travel - // through it, so the answer is confirmed against the entry the walk judged before anyone writes. - const directory = root(); - const home = directoryWith(path.join(directory, 'home'), 0o700); - const work = path.join(home, 'work'); - fs.mkdirSync(work); - const attacker = path.join(directory, 'attacker'); - fs.mkdirSync(attacker); - fs.chmodSync(attacker, 0o700); - const realLstatSync = fs.lstatSync; - let looks = 0; - vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: unknown, ...rest: unknown[]) => { - // The first look judges `work` as the directory the entry is created in. The swap lands immediately - // after that judgment and before anything is staged there. - if (String(pathname) === work && ++looks === 2) { - fs.rmdirSync(work); - fs.symlinkSync(attacker, work); - } - return (realLstatSync as (...args: unknown[]) => unknown)(pathname, ...rest); - }) as typeof fs.lstatSync); - - expectUntrustedReplaced(() => publish(path.join(work, 'journey.ad')), work); - expect(fs.readdirSync(attacker)).toEqual([]); -}); - skipOnWindows( 'identifies an entry by its bigint inode, so two large inodes do not collapse', () => { - // Directory identities are compared for equality, 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. + // 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'); @@ -901,7 +791,8 @@ skipOnWindows( options, ) as fs.Stats; if (String(pathname) !== work) return stats; - // Two distinct entries, one per look: the inode the walk judges, then the one the name answers after. + // 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, { @@ -911,6 +802,8 @@ skipOnWindows( // A numeric read would answer Number(2^53 + 1n) === Number(2^53n), and the swap would pass. expect(Number(LOW + 1n)).toBe(Number(LOW)); - expectUntrustedReplaced(() => publish(path.join(work, 'journey.ad')), work); + const destination = path.join(work, 'journey.ad'); + const prepared = prepareScriptDestination(destination); + expectUntrustedReplaced(() => confirmScriptDestination(destination, prepared), work); }, ); diff --git a/packages/host-kit/src/internal/atomic-file-parent.test.ts b/packages/host-kit/src/internal/atomic-file-parent.test.ts index 54e5d38929..58708b7713 100644 --- a/packages/host-kit/src/internal/atomic-file-parent.test.ts +++ b/packages/host-kit/src/internal/atomic-file-parent.test.ts @@ -2,21 +2,26 @@ // 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 { expect, test, vi } from 'vitest'; +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 { assertPrivateScriptDestination, prepareScriptDestination } from './atomic-file.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', () => { @@ -86,22 +91,142 @@ skipOnWindows('answers the created directory as the one to publish into', () => expect(modeOf(judged)).toBe(0o700); }); -skipOnWindows('refuses a destination whose parent does not exist, and publishes nowhere', () => { - // `assertPrivateScriptDestination` creates nothing, so a walk that stopped at an absent name has no - // answer to publish into. The nearest ancestor it did reach would be a file the caller never asked - // for: `root/journey.ad` instead of `root/missing/journey.ad`. +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( - () => assertPrivateScriptDestination(destination), + () => 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` @@ -143,8 +268,10 @@ test('refuses a destination that is not absolute on every platform, and creates '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( - () => assertPrivateScriptDestination(relative), + () => confirmScriptDestination(relative, { directory: relative, identity: undefined }), 'relative_destination', path.join('recordings'), ); diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index 347d9e12ec..ea4cbfa7e7 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -122,7 +122,7 @@ const SCRIPT_DIR_MODE = 0o700; * 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 - * JUDGED again before the answer. A caller never hands its own `mkdir` to a path this rule has not stopped. + * WALKED AGAIN before the answer. A caller never hands its own `mkdir` to a path this rule has not stopped. * * The second walk asks the CREATION question — whether other local users could add the destination's own * name inside the directory the walk ended in. The first walk does not, because below it the missing @@ -130,8 +130,9 @@ const SCRIPT_DIR_MODE = 0o700; * `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. * - * The answer carries the judged directory's identity, so a caller that stages something there does not ask - * the host about ground this call already judged, and never runs a `mkdir` of its own. + * The answer carries the judged directory's identity, so a caller that stages bytes there can confirm the + * ground one time before it renames, without asking the host about ground this call already judged, and + * never runs a `mkdir` of its own. * * 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. @@ -156,28 +157,19 @@ export function prepareScriptDestination(destination: string): ScriptDestination if (walked.identity === undefined) { throw scriptAncestryFailure(destination, walked.deepest, 'unreachable_parent'); } - const created = createMissingLevels( - destination, - walked.deepest, - walked.identity, - walked.missing, - trust, - ); - // The walk that follows creation judges the tail from what the creation saw and every other name from - // what the first walk judged, so a level swapped out in between is refused rather than entered on. - const known = new Map(walked.ground?.judged); - for (const [level, judged] of created) known.set(level, judged); - return publishableDestination( - destination, - walkSpelledParent(spelled, destination, trust, known), - trust, - ); + createMissingLevels(destination, walked.deepest, walked.missing, trust); + return publishableDestination(destination, walkSpelledParent(spelled, destination, trust), trust); } -/** Where a script entry is created: the PHYSICAL directory the rule judged, and that directory's identity. */ +/** + * Where a script entry is created: the PHYSICAL directory the rule judged, and that directory's identity. + * + * `identity` is `dev:ino` as the walk's own `lstat` answered it. It is what + * {@link confirmScriptDestination} compares for a caller that stages bytes for a later rename, so the one + * check a caller owes is one this host-kit makes rather than one it writes itself. + */ export type ScriptDestination = Readonly<{ directory: string; - /** `dev:ino` as the walk's own `lstat` answered it, for a caller that stages bytes there. */ identity: string | undefined; }>; @@ -308,34 +300,54 @@ function statOrNull(pathname: string): fs.Stats | undefined { } /** - * Refuses a script destination unless every directory the kernel looks a name up in is one no other - * non-root local user can change (#4565), and reports the PHYSICAL directory the entry is created in. - * {@link prepareScriptDestination} is the same rule for a caller that also needs the missing tail created; - * everything written there about how the walk judges ground, and about the window being closed by - * PERMISSIONS rather than by timing, applies here too. + * 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, a long upload or any other wait + * 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. Every `parent_replaced` refusal is built by + * {@link scriptAncestryFailure}, which is why no caller writes one: the shape a caller would copy is the + * host-kit answer's reason, exposure, ancestor and hint, and a route that hand-rolls them drifts from the + * rule that produced them. * - * This variant creates NOTHING, so a walk that stopped short at an absent name has no answer to give and - * refuses as `unreachable_parent`. `parentIdentity` is the identity {@link prepareScriptDestination} - * answered for the directory an earlier walk judged; only the remote route passes one, and this walk's own - * identity is compared with it before anything is renamed. + * A walk that now answers a DIFFERENT directory than the answer named — an ancestor pointed at a link + * meanwhile — is the swap this catches, and the version is refused rather than renamed into ground nobody + * judged. Nothing here 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 assertPrivateScriptDestination( - destination: string, - parentIdentity?: string, -): string { +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 a destination 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; everything written there about how the walk judges ground, 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 spelled; + if (process.platform === 'win32') { + return { directory: spelled, identity: publishDirectoryIdentity(spelled) }; + } const trust = scriptTrust(); const walk = walkSpelledParent(spelled, destination, trust); + if (walk.reject !== undefined) throw walk.reject; if (walk.unresolvable) { throw scriptAncestryFailure(destination, walk.deepest, 'unresolvable_parent'); } - return publishableDestination(destination, walk, trust, parentIdentity).directory; + 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 never asks the host about ground the walk already judged. + * caller that stages bytes beside it can confirm the ground one time before its rename. * * 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 the nearest ancestor it did reach is a file under a name nobody asked for. @@ -344,24 +356,13 @@ function publishableDestination( destination: string, walk: WalkOutcome, trust: ScriptDestinationTrust, - parentIdentity?: string, ): ScriptDestination { if (walk.reject !== undefined) throw walk.reject; if (!walk.arrived) { throw scriptAncestryFailure(destination, walk.deepest, 'unreachable_parent'); } - // Confirmed before a caller starts staging: the name the answer is spelled by must still hold the entry - // this walk judged, or the caller's next `mkdir`, `mkdtemp` or `rename` travels through a swap. - if (!stillTheJudgedEntry(walk.deepest, walk.identity)) { - throw scriptAncestryFailure(destination, walk.deepest, 'parent_replaced'); - } - // This walk's identity IS a confirmed `lstat` of the directory it answered, so an earlier answer for the - // same directory is compared without reading the host twice. - if (parentIdentity !== undefined && walk.identity !== parentIdentity) { - throw scriptAncestryFailure(destination, walk.deepest, 'parent_replaced'); - } // Where other local users can add entries here, one of them can add this entry first and the - // recording is theirs. The authority the walk read is reused rather than read again. + // recording is theirs. if (othersCreateEntriesIn(walk.authority, trust)) { throw scriptAncestryFailure(destination, walk.deepest, 'shared_parent'); } @@ -395,28 +396,6 @@ type WalkState = Readonly<{ queue: readonly string[]; /** Link targets expanded so far. */ hops: number; - ground: WalkGround; -}>; - -/** - * One directory the walk judged, as its `lstat` answered it: the identity to recognize it by, plus the - * fields the rule reads. `lstat` is the ONLY lookup the rule makes — `stat` resolves a name a second time, - * and the name can answer a different entry by then. - */ -type JudgedDirectory = Readonly<{ - identity: string; - uid: number; - gid: number; - mode: number; -}>; - -/** - * One walk's memory of the ground it stood on: every path it judged, keyed by that path, so a name come - * back around through a `..` or an alias keeps the judgment it was given and one walk sees one host. Names - * this call CREATED are seeded here too, to be compared against rather than trusted. - */ -type WalkGround = Readonly<{ - judged: Map; }>; type WalkStep = @@ -426,8 +405,6 @@ type WalkStep = deepest: string; authority: DirectoryAuthority; identity: string; - /** Everything judged on the way, so creation and the next walk compare against it. */ - ground: WalkGround; /** 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. */ @@ -463,8 +440,6 @@ type WalkOutcome = deepest: string; /** That directory's identity as the walk judged it, when it judged one. */ identity: string | undefined; - /** Everything that walk judged, to seed the walk that follows a creation. */ - ground: WalkGround | undefined; /** The step that made the chain unsafe, when an existing step refused rather than went missing. */ reject: AppError | undefined; /** Whether a `..` is queued behind the absent name, so creating cannot resolve the chain. */ @@ -502,9 +477,8 @@ function walkSpelledParent( parent: string, destination: string, trust: ScriptDestinationTrust, - created?: ReadonlyMap, ): WalkOutcome { - let step = startWalk(parent, trust, created); + 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') { @@ -535,7 +509,6 @@ function refused(reject: AppError): WalkOutcome { arrived: false, deepest: '/', identity: undefined, - ground: undefined, reject, unresolvable: false, missing: [], @@ -547,7 +520,6 @@ function stoppedShort(step: Extract): WalkOutcome { arrived: false, deepest: step.deepest, identity: step.identity, - ground: step.ground, reject: undefined, unresolvable: step.behindUpwardStep, missing: step.missing, @@ -555,89 +527,48 @@ function stoppedShort(step: Extract): WalkOutcome { } /** The first state: the root, with every component of the parent still to resolve. */ -function startWalk( - parent: string, - trust: ScriptDestinationTrust, - created?: ReadonlyMap, -): WalkStep { - const queue = pathComponents(parent); - const ground: WalkGround = { judged: new Map(created ?? []) }; - return standOn('/', queue, trust, 0, ground); +function startWalk(parent: string, trust: ScriptDestinationTrust): WalkStep { + return standOn('/', pathComponents(parent), trust, 0); } /** - * Stands the walk on `directory`, judged from the walk's own `lstat` of it, or refuses it. + * Stands the walk on `directory`, judged from this call's own `lstat` of it, or refuses it. * - * A name the walk already judged is reused rather than read again, which is what keeps one walk seeing one - * host. A name this call CREATED is reused the same way, but only while the spelling still answers what the - * creation left there: `..` of a created level, or the second walk over it, would otherwise step through a - * link somebody planted on that name in between. + * 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, - ground: WalkGround, ): WalkStep { - const judged = judgeGround(ground, directory); - if (judged === 'replaced') - return { kind: 'reject', path: directory, exposure: 'parent_replaced' }; - if (judged === undefined) return { kind: 'reject', path: directory, exposure: 'not_a_directory' }; - const authority: DirectoryAuthority = { - uid: judged.uid, - gid: judged.gid, - mode: judged.mode, - }; + 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: judged.identity, queue, hops, ground }, + state: { deepest: directory, authority, identity: identityOf(stats), queue, hops }, }; } -/** - * What this walk knows about a directory: the entry it judged there, `'replaced'` when the name answers - * something else now, or nothing when it is absent or is not a directory. - */ -function judgeGround( - ground: WalkGround, - directory: string, -): JudgedDirectory | 'replaced' | undefined { - const known = ground.judged.get(directory); - const stats = lstatEntry(directory); - if (known !== undefined) { - // The entry is read again to RECOGNIZE it, never to judge it: the authority stays what this walk - // judged first, and a name that answers a different entry now is the swap this rule exists to refuse. - if (stats === undefined || !stats.isDirectory() || identityOf(stats) !== known.identity) { - return 'replaced'; - } - return known; - } - if (stats === undefined || !stats.isDirectory()) return undefined; - const judged = judgedFromStats(stats); - ground.judged.set(directory, judged); - return judged; +/** The fields this rule reads off one `lstat` answer: owner, group and mode of the ENTRY. */ +function directoryAuthority(stats: fs.BigIntStats): DirectoryAuthority { + return { uid: Number(stats.uid), gid: Number(stats.gid), mode: Number(stats.mode) }; } /** - * Identity and judged fields of one `lstat` answer, as this rule read them. + * The device and inode an `lstat` answer names. * - * Identities come from BIGINT stats: a 32-bit `ino` collapses two distinct large inodes onto one identity, - * which is the collision a comparison exists to catch (`fileIdentity` on the remote route reads bigint for - * the same reason). + * 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 judgedFromStats(stats: fs.BigIntStats): JudgedDirectory { - return { - identity: identityOf(stats), - uid: Number(stats.uid), - gid: Number(stats.gid), - mode: Number(stats.mode), - }; -} - -/** The device and inode an `lstat` answer names. */ function identityOf(stats: fs.BigIntStats): string { return `${stats.dev}:${stats.ino}`; } @@ -665,7 +596,7 @@ function stepThrough( // `..` 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, state.ground); + return standOn(path.dirname(state.deepest), rest, trust, state.hops); } return stepIntoEntry(state, component, rest, trust); } @@ -688,26 +619,16 @@ function stepIntoEntry( deepest: state.deepest, authority: state.authority, identity: state.identity, - ground: state.ground, missing: [component, ...rest], behindUpwardStep: rest.includes('..'), }; } - // Asked before the entry's TYPE is believed, and before it is followed. The name may be one this walk - // judged or one this call created, and a name that answers a different entry than the one recorded is a - // swap: the walk would otherwise judge the target's permissions while entering on the name. - const known = state.ground.judged.get(entry); - if (known !== undefined && known.identity !== identityOf(stats)) { - return { kind: 'reject', path: entry, exposure: 'parent_replaced' }; - } + // 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' }; - // 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 — the walk would judge the target's permissions while entering on the name. - const judged = known ?? judgedFromStats(stats); - state.ground.judged.set(entry, judged); - const authority: DirectoryAuthority = { uid: judged.uid, gid: judged.gid, mode: judged.mode }; + const authority = directoryAuthority(stats); const exposure = untrustedAncestryExposure(authority, trust); if (exposure) return { kind: 'reject', path: entry, exposure }; return { @@ -715,10 +636,9 @@ function stepIntoEntry( state: { deepest: entry, authority, - identity: judged.identity, + identity: identityOf(stats), queue: rest, hops: state.hops, - ground: state.ground, }, }; } @@ -745,7 +665,7 @@ function stepThroughLink( // 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, state.ground); + return standOn(home, [...pathComponents(target), ...rest], trust, state.hops + 1); } /** @@ -757,11 +677,11 @@ function stepThroughLink( */ export const MAX_SCRIPT_PATH_LINK_HOPS = 30; -/** One directory's identity, for a caller that must publish into the same one it created or checked. */ -export function publishDirectoryIdentity(directory: string): string | undefined { +/** 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 = fs.lstatSync(directory, { bigint: true, throwIfNoEntry: false }); - return stats ? `${stats.dev}:${stats.ino}` : undefined; + const stats = lstatEntry(directory); + return stats ? identityOf(stats) : undefined; } /** @@ -886,6 +806,24 @@ const untrustedGroundWording: Record = { 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, @@ -899,7 +837,7 @@ function scriptAncestryFailure( ? `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_replaced' : 'script_ancestor_untrusted', + reason: replaced ? SCRIPT_ANCESTRY_REASONS[1] : SCRIPT_ANCESTRY_REASONS[0], exposure, path: destination, ancestor, @@ -923,68 +861,69 @@ function ancestryHint(exposure: ScriptAncestryExposure, ancestor: string): strin } /** - * Whether `directory` still holds the entry the walk judged there: the same type, and the same device and - * inode. `lstat` again because a `stat` would follow the name and answer whatever it resolves to now. - */ -function stillTheJudgedEntry(directory: string, identity: string): boolean { - const stats = lstatEntry(directory); - return stats !== undefined && stats.isDirectory() && identityOf(stats) === identity; -} - -/** - * Creates the tail the walk found missing, ONE LEVEL AT A TIME, and reports what each level turned out to - * be so the walk that follows judges those names from the creation's own `lstat`. + * 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. * - * `EEXIST` is a refusal, never a retry: the name was absent when the walk looked, so anything standing - * there now was put there by someone 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, - establishedId: string, missing: readonly string[], trust: ScriptDestinationTrust, -): ReadonlyMap { - const created = new Map(); +): void { let parent = established; - let parentId = establishedId; for (const name of missing) { - // Confirmed before EACH creation, including inside a level this call made moments ago: a `mkdir` is - // what a moved name would redirect, so the name it is handed must still be the entry judged under it. - if (!stillTheJudgedEntry(parent, parentId)) { - throw scriptAncestryFailure(destination, parent, 'parent_replaced'); - } - const level = path.join(parent, name); - try { - fs.mkdirSync(level, { mode: SCRIPT_DIR_MODE }); - } catch (error) { - if ((error as NodeJS.ErrnoException).code === 'EEXIST') { - throw scriptAncestryFailure(destination, level, 'entry_appeared'); - } - throw error; - } + 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) { + // The creation carries the mode, and this forces it: `mkdir` ANDs it with the umask, so under the + // shared-checkout 002 the level would stand 0775 and the walk that follows would refuse it. fs.chmodSync(level, SCRIPT_DIR_MODE); - const seen = lstatEntry(level); - const judged = seen !== undefined && seen.isDirectory() ? judgedFromStats(seen) : undefined; - if (judged === undefined) { - // The name this call just created is not a directory this call can use: whatever it became, it is - // not the level the destination needs. - throw scriptAncestryFailure(destination, level, 'not_a_directory'); - } - const exposure = untrustedAncestryExposure( - { uid: judged.uid, gid: judged.gid, mode: judged.mode }, - trust, - ); - if (exposure) throw scriptAncestryFailure(destination, level, exposure); - created.set(level, judged); - parent = level; - parentId = judged.identity; + 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 created; + return level; } function assertSafeDestination(destination: string): void { diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 66a1a5daf4..106b94ba56 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -13,9 +13,9 @@ import { assertScriptArtifactsCapability } from '@agent-device/daemon-contracts/ import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import { acquireProcessLock, - assertPrivateScriptDestination, + confirmScriptDestination, + scriptAncestryReason, prepareScriptDestination, - publishDirectoryIdentity, publishFileSync, withProcessLock, type ScriptDestination, @@ -222,7 +222,9 @@ async function publishScriptVersion( revision: revision as number, staging, staged, - parentIdentity: allocated.parentIdentity, + // The directory host-kit answered when staging was allocated, so the publish can confirm the ground + // one time before the rename, through the same call that refuses it. + prepared: allocated.prepared, pending, }; return { published: await withRecordLock(file, async () => publishStaged(file, version)) }; @@ -243,36 +245,28 @@ async function publishScriptVersion( /** * Creates a staging directory beside the destination and lists it in the record before any script - * bytes reach it, and reports the destination directory's identity so the publish can confirm it is still - * the same one. + * bytes reach it, and reports the confirmed destination so the publish can confirm it once more. * * Staging sits in the directory the ancestry walk JUDGED — the `prepareScriptDestination` answer, not * `path.dirname` of the spelled destination. Where a `..` or a link in the destination leads elsewhere, the * spelled parent is a directory nobody judged, and a staging directory in it is one another local user can - * populate before the rename does. The identity is the one that answer carried, so the walk is not asked - * twice for one version. + * populate before the rename does. The answer is used as it stands: nobody the rule accepted can move it + * before this call, and the check the route owes comes after the download, at {@link confirmScriptDestination}. */ function allocateStaging( file: string, prepared: ScriptDestination, -): { staging: string; parentIdentity: string | undefined } | undefined { +): { staging: string; prepared: ScriptDestination } | undefined { const record = readRecord(file); if (!record) return undefined; - const directory = prepared.directory; - // One identity check, not a second walk: the answer is only used where the name still holds the entry the - // walk judged it for. Nothing is staged in a directory that moved in between. - if (publishDirectoryIdentity(directory) !== prepared.identity) { - throw destinationMoved(record.destination, directory); - } - const staging = fs.mkdtempSync(path.join(directory, '.agent-device-script-')); - const parentIdentity = prepared.identity; + const staging = fs.mkdtempSync(path.join(prepared.directory, '.agent-device-script-')); try { writeRecord(file, { ...record, staging: [...(record.staging ?? []), staging] }); } catch (error) { fs.rmSync(staging, { recursive: true, force: true }); throw error; } - return { staging, parentIdentity }; + return { staging, prepared }; } /** @@ -353,11 +347,11 @@ function publishStaged( revision: number; staging: string; staged: string; - parentIdentity: string | undefined; + prepared: ScriptDestination; pending: { named: boolean }; }>, ): string | undefined { - const { revision, staging, staged, parentIdentity, pending } = version; + const { revision, staging, staged, prepared, pending } = version; const record = readRecord(file); if (!record) return undefined; let current = settlePublishing(record); @@ -368,12 +362,10 @@ function publishStaged( current = withoutStaging(current, record.publishing.staging); } if (revision <= current.revision) return current.destination; - // Re-asked here, under the record lock and right before the entry is created: whoever could write an - // ancestor while the version was downloaded cannot move it now (#4565). The identity handed in was taken - // from the directory the walk judged when staging was created, so a walk that now answers a DIFFERENT - // directory — an ancestor swapped for a link meanwhile — fails the comparison instead of renaming bytes - // into ground nobody judged. - const judged = assertPrivateScriptDestination(current.destination, parentIdentity); + // 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`); @@ -411,21 +403,6 @@ function fileIdentity(file: string): string | undefined { return stat ? `${stat.dev}:${stat.ino}` : undefined; } -/** The judged answer no longer names the entry it was judged for, so this version publishes nowhere. */ -function destinationMoved(destination: string, directory: string): AppError { - return new AppError( - 'COMMAND_FAILED', - `The directory for ${destination} changed while the script was staged, so the script was not saved.`, - { - reason: 'script_ancestry_replaced', - exposure: 'parent_replaced', - path: destination, - ancestor: directory, - hint: 'Re-record with open --save-script, or save under a directory nobody else can write.', - }, - ); -} - function scriptDeliveryFailure( destination: string, publicationId: string, @@ -434,7 +411,7 @@ 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 = scriptAncestryRefusal(error); + const refusal = scriptAncestryReason(error); if (refusal) { return { reason: 'script_delivery_failed', @@ -467,18 +444,6 @@ function scriptDeliveryFailure( }; } -/** - * The typed reason a destination-ancestry refusal reported (#4565), so a caller can tell an unsafe - * destination from a download that failed. Anything else is `undefined`. - */ -function scriptAncestryRefusal(error: unknown): string | undefined { - if (!(error instanceof AppError)) return undefined; - const reason = error.details?.reason; - return reason === 'script_ancestor_untrusted' || reason === 'script_ancestry_replaced' - ? reason - : undefined; -} - function recordPath( stateDir: string, baseUrl: string, 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/ledger.json b/test/wire-compat/ledger.json index 09f39f828b..70117dd98e 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -214,7 +214,7 @@ "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:7933a02d17d7d8a48e9ba542480a9703ad8688f5ac30c186e503700fe982254e", + "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:28fe42532406633c86578f468b2ccc5c7fa43764fd62cfec35975678ff080e66", "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" @@ -222,8 +222,8 @@ "compatibleChanges": [ { "declaration": "packages/remote/src/session-script-destination.ts#publishScriptVersion", - "digest": "sha256:7933a02d17d7d8a48e9ba542480a9703ad8688f5ac30c186e503700fe982254e", - "rationale": "#4565 adds one call ahead of the `mkdir` that creates a missing parent: the destination-ancestry rule is asked over the directories that already exist, so a destination it is going to refuse leaves no directories behind. Nothing on the wire changes: no request field is added, removed or renamed, no response field, route, status or artifact framing moves, and the download contract this declaration consumes is untouched. A released daemon receives exactly the same request and answers the same way; a released caller resolves the same paths on its own disk. A skewed peer parses every payload as before. #4565 revises that local sequencing only: the `mkdir` moves into host-kit's one destination call, which refuses an unsafe destination before creating anything and creates each missing level at 0700 inside the directory it judged. That call now ANSWERS the judged directory and its identity, so this route stages each version beside the destination without walking the destination a second time, and confirms the identity before the rename. Nothing on the wire moves: same request fields, same response fields, same routes, status and artifact framing, and the download contract this declaration consumes is untouched. A released daemon receives the same request and answers the same way; a released caller resolves the same paths on its own disk." + "digest": "sha256:28fe42532406633c86578f468b2ccc5c7fa43764fd62cfec35975678ff080e66", + "rationale": "#4565 changes only how the caller resolves 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. 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", From b9f17ce472fdcc9b74e48bc26996585bddd6c1bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 01:00:02 +0100 Subject: [PATCH 21/28] fix(daemon-contracts): never let a state-mode repair decide daemon startup The repair forces 0700 through an O_DIRECTORY | O_NOFOLLOW descriptor only when the fstat of that descriptor says this uid owns the entry. Every other shape - a link, a name that is not a directory, a level another uid owns, EACCES/EPERM/EROFS from a mount it cannot force - changes nothing and emits daemon_state_mode_repair_skipped, so a symlinked state dir and a container whose sessions/ belongs to the mounted uid start as they did on main. The destination walk stays the only thing that refuses a recording. sameStateEntry, state_dir_entry_replaced, the duplicate ownership check and privateStateRefusal go with the refusal path they served. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 6 +- .../src/daemon-registration-owner.ts | 129 ++++++------------ 2 files changed, 45 insertions(+), 90 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 2055ada251..ab9269cc54 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -222,9 +222,11 @@ Shapes this closes, each of which an earlier shape of the rule accepted: 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 applies the same judgment as the walk, and to one directory less: each level is read by `lstat`, so a `sessions` another user left as a LINK is refused rather than followed, and a level this process does not own is refused rather than chmod'ed — a repair that forced the mode by pathname would reach through the link and, run by a root daemon, strip access from an owner who never ran the daemon. The mode is forced through a descriptor opened `O_DIRECTORY | O_NOFOLLOW`, whose `fstat` is confirmed to be the entry the `lstat` judged. +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 applies the same judgment as the walk, and to one directory less: each level is read by `lstat` first, so the mode is forced through a descriptor opened `O_DIRECTORY | O_NOFOLLOW` on the entry that read judged, never through the NAME: 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. + +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, `EACCES`/`EPERM`/`EROFS` from a mount it cannot force — changes nothing and emits `daemon_state_mode_repair_skipped`. A state directory on a bind-mounted CI volume, a `~/.agent-device` symlinked to another disk, and a root container whose `sessions/` belongs to the mounted uid therefore start exactly as they did before this rule existed, and every command still works. The destination walk stays the ONLY thing that refuses a recording: it judges that same chain per publish and refuses a script under such a tree with `script_ancestor_untrusted` and its hint, so the repair skipping costs safety nothing — an unsafe destination is refused where the entry is actually created. 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. 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, and compares identity ONCE. The first walk happens before staging: it creates what is missing and 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. +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 diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index 4f691fbce7..241d03fb50 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -277,7 +277,7 @@ export function createOwnedReplayStateDir(): OwnedReplayStateDir { } /** - * Creates one of the daemon's own state directories, and repairs one that already exists, to 0700. + * 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 @@ -286,9 +286,10 @@ export function createOwnedReplayStateDir(): OwnedReplayStateDir { * remote-delivered version. Creation carries the mode and the repair forces it, because a state dir an older * version created at 0775 is the same refusal. * - * A level that is not a directory this process owns is REFUSED rather than repaired (#4565): a repair that - * chmods by pathname reaches through a planted link, so a root daemon starting against a legacy writable - * state directory would change the mode of a directory another user owns. + * The repair is BEST-EFFORT and never refuses (#4565): it forces the mode on a level this uid owns and + * changes nothing about any other, so a state directory on a mounted volume, or one another uid left at + * 0755, still gets a daemon that starts. A recording under ground the daemon does not own is refused by the + * destination walk, which is where the entry is actually created. * * Returns the path so a caller can name what it just made without a second `mkdir` of its own. */ @@ -322,13 +323,17 @@ function createdStateLevels( const STATE_DIR_MODE = 0o700; /** - * Forces one state level to the private mode, or refuses it and changes NOTHING. + * Forces one existing state level to {@link STATE_DIR_MODE}, or changes nothing and says why. * - * `chmod` by pathname acts on whatever the NAME resolves to, so repairing a legacy state directory that was - * writable by others is not safe on its own: another user who could write it can leave a link at `sessions`, - * and a root daemon asked to repair that name would change the mode of a directory they own. So the level is - * judged by this call's own `lstat` — the ENTRY under the name — before anything is forced, and only a level - * that is a directory, and is not already private, reaches {@link forcePrivateStateDir}. + * `chmod` given the NAME acts on whatever the name resolves to, so the mode is applied through a descriptor + * opened `O_DIRECTORY | O_NOFOLLOW` and only after that descriptor's `fstat` says this uid owns the entry: a + * root daemon repairing a legacy state directory another local user could write would otherwise reach through + * a `sessions` they left as a link, and strip access from an owner who never ran the daemon. + * + * Every case that cannot be forced is a SKIP with a diagnostic, not a refusal — a link, a name that is not a + * directory, a level another uid owns, and a mount that denies the open or the chmod. This function never + * throws for them: it decides a mode, never whether the daemon starts (ADR 0016), and the destination walk is + * the only thing that refuses a recording. */ function repairPrivateStateDir(directory: string): void { // Windows answers access from an ACL, and `chmod` there only toggles the read-only bit. @@ -336,102 +341,52 @@ function repairPrivateStateDir(directory: string): void { const judged = fs.lstatSync(directory, { bigint: true, throwIfNoEntry: false }); // The name is gone by now: whatever removed it also removed the mode this call came to force. if (judged === undefined) return; - // A LINK is refused even where its target is already private: the name is what this call was handed, and - // a link under it was put there by whoever could write this directory. - if (!judged.isDirectory()) throw privateStateRefusal(directory, 'state_dir_not_a_directory'); - // Already private, so nothing is changed and nobody's ownership has to be asked. + // 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; - forcePrivateStateDir(directory, judged); -} - -/** - * Applies {@link STATE_DIR_MODE} to the entry the name holds, through a descriptor opened on that name. - * - * Ownership is judged from the `lstat`, as the destination-ancestry rule judges ground: a root daemon - * therefore repairs root-owned state and leaves a directory another user owns alone, rather than making it - * unreachable to them. The descriptor's `fstat` must answer the entry the `lstat` judged, so the mode cannot - * land on something put behind the name in between. - */ -function forcePrivateStateDir(directory: string, judged: fs.BigIntStats): void { - if (!thisUsersEntry(judged)) throw privateStateRefusal(directory, 'state_dir_foreign_owned'); let descriptor: number | undefined; try { - descriptor = openStateEntry(directory); - const opened = fs.fstatSync(descriptor, { bigint: true }); - if (!sameStateEntry(opened, judged)) { - throw privateStateRefusal(directory, 'state_dir_entry_replaced'); - } - if (!thisUsersEntry(opened)) { - throw privateStateRefusal(directory, 'state_dir_foreign_owned'); + descriptor = fs.openSync( + directory, + fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW, + ); + if (Number(fs.fstatSync(descriptor, { bigint: true }).uid) !== (process.getuid?.() ?? -1)) { + skipStateDirMode(directory, 'not owned by this user'); + return; } fs.fchmodSync(descriptor, STATE_DIR_MODE); } catch (error) { - if (error instanceof AppError) throw error; - // `EACCES` says the directory does not even let THIS user open it (a state directory left at 0000): no - // descriptor exists to force the mode with, and startup must not fail on a host it cannot fix. - if (!STATE_DIR_REPAIR_SKIPPED_CODES.has((error as NodeJS.ErrnoException).code ?? '')) - throw error; - emitDiagnostic({ - level: 'warn', - phase: 'daemon_state_mode_repair_skipped', - data: { path: directory, error: normalizeError(error) }, - }); + if (!MODE_REPAIR_SKIPPED_CODES.has((error as NodeJS.ErrnoException).code ?? '')) throw error; + skipStateDirMode(directory, (error as NodeJS.ErrnoException).code ?? 'unknown'); } finally { if (descriptor !== undefined) fs.closeSync(descriptor); } } -/** Whether an entry belongs to the user this process runs as. */ -function thisUsersEntry(stats: fs.BigIntStats): boolean { - return Number(stats.uid) === (process.getuid?.() ?? -1); -} - -/** Whether a descriptor answers the same entry an `lstat` judged. */ -function sameStateEntry(opened: fs.BigIntStats, judged: fs.BigIntStats): boolean { - return `${opened.dev}:${opened.ino}` === `${judged.dev}:${judged.ino}`; +/** Reports the one state level whose mode this repair will not change. */ +function skipStateDirMode(directory: string, because: string): void { + emitDiagnostic({ + level: 'warn', + phase: 'daemon_state_mode_repair_skipped', + data: { path: directory, error: { message: `state level kept as it is: ${because}` } }, + }); } -/** A repair that cannot be done now, on top of what a mode repair may never fail the daemon on. */ -const STATE_DIR_REPAIR_SKIPPED_CODES = new Set([ +/** + * What a mode repair may never fail the daemon on: a host that denies the chmod (`EPERM`, `EROFS`, the two + * spellings of an unsupported one), a name that cannot be opened as a directory (`ELOOP` for a link, + * `ENOTDIR`), and a directory that will not even open for this user (`EACCES`). + */ +const MODE_REPAIR_SKIPPED_CODES = new Set([ 'EPERM', 'EROFS', 'ENOTSUP', 'EOPNOTSUPP', 'EACCES', + 'ELOOP', + 'ENOTDIR', ]); -/** - * Opens the entry the name holds, refusing one that is not a directory the caller may enter: `O_NOFOLLOW` - * answers `ELOOP` for a link, and `O_DIRECTORY` for anything that is not a directory. - */ -function openStateEntry(directory: string): number { - try { - return fs.openSync( - directory, - fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW, - ); - } catch (error) { - const code = (error as NodeJS.ErrnoException).code ?? ''; - if (code === 'ELOOP' || code === 'ENOTDIR') { - throw privateStateRefusal(directory, 'state_dir_not_a_directory'); - } - throw error; - } -} - -/** A state name this call will not touch, with the shape that made it unsafe. */ -function privateStateRefusal(directory: string, reason: string): AppError { - return new AppError( - 'COMMAND_FAILED', - `Refusing to repair the daemon state directory ${directory}.`, - { - reason, - path: directory, - hint: 'Restore the state directory owned by the user who runs the daemon, or point AGENT_DEVICE_STATE_DIR at one.', - }, - ); -} - /** * 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 @@ -450,8 +405,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<{ From 632cc84121795b69f59c59b999b9eb9085f55476 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 01:15:11 +0100 Subject: [PATCH 22/28] test(daemon-contracts): pin a state repair that skips levels it may not force The suites that pinned a state refusal are flipped to the rule: a level this uid does not own, a link, and a name the host will not open are all skipped with daemon_state_mode_repair_skipped, the daemon starts, and the destination walk is what refuses the recording under that tree with script_ancestor_untrusted. The unopenable case injects EACCES at the open seam rather than staging a 0000 mode, because a root process opens a 0000 directory it owns. serveHostOwnership now serves the ids through fstat as well, which is where a repair that forces a mode asks who owns the entry. Co-Authored-By: Claude Opus 5.5 --- ...aemon-registration-owner-state-dir.test.ts | 110 ++++++---- .../src/daemon-registration-owner.ts | 36 ++-- .../session-store-teardown-script.test.ts | 45 ++-- .../http/daemon-runtime-state-dir.test.ts | 102 +++++++-- packages/host-kit/src/internal/atomic-file.ts | 202 +++++++----------- .../remote/src/session-script-destination.ts | 20 +- .../test-kit/src/host-ownership.fixtures.ts | 45 ++-- 7 files changed, 315 insertions(+), 245 deletions(-) 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 index ed4ce8b7a1..7ad59da029 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts @@ -1,16 +1,21 @@ // 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 name -// this process may not touch is refused with nothing changed, rather than repaired through the name. +// 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 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 thing that refuses. // (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 { AppError } from '@agent-device/kernel/errors'; +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']; afterEach(() => { vi.restoreAllMocks(); @@ -38,11 +43,26 @@ skipOnWindows('repairs the state directories it owns, whatever mode they were cr } }); -skipOnWindows('refuses a state name that is a link, and leaves where it leads alone', () => { +skipOnWindows('asks nothing of a level that already stands private', () => { + // The fast path, and the reason a normal start costs no extra work: a 0700 level is already what the + // repair would force, so it is not even opened. Deleting the mode check makes this red. + const base = mkdtempForTestSync('agent-device-state-private-'); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions); + fs.chmodSync(sessions, 0o700); + const open = vi.spyOn(fs, 'openSync'); + + ensurePrivateDaemonStateDir(sessions); + + expect(open).not.toHaveBeenCalled(); +}); + +skipOnWindows('skips a state name that is a link, and leaves where it leads alone', async () => { // Repair reaches a legacy state directory another local user could write, and they use that write to // leave a link at `sessions`. A `chmod` given the NAME travels through it, so a root daemon forcing its - // own state private would be changing the mode of a directory somebody else chose. The link itself is the - // refusal: it is not the directory this call was told to make private. + // own state private would change the mode of a directory somebody else chose. So the mode is applied + // through an `O_NOFOLLOW` descriptor instead, and a link cannot be opened as one: this call skips the + // level, and the daemon starts as it did before the repair judged links at all. const base = mkdtempForTestSync('agent-device-state-link-'); fs.chmodSync(base, 0o777); const planted = path.join(base, 'other-users-home'); @@ -51,18 +71,20 @@ skipOnWindows('refuses a state name that is a link, and leaves where it leads al const sessions = path.join(base, 'sessions'); fs.symlinkSync(planted, sessions); - expectRefusal(() => ensurePrivateDaemonStateDir(sessions), 'state_dir_not_a_directory', sessions); + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions))).toBe(1); - // Nothing was changed: the mode the owner set is still the mode the directory has, and no state - // directory appeared under the name. + // Nothing was changed: the mode the owner set is still the mode the directory has, the link is still a + // link rather than a directory this call made, and nothing was created on its far side. expect(fs.lstatSync(planted).mode & 0o777).toBe(0o777); + expect(fs.readdirSync(planted)).toEqual([]); expect(fs.lstatSync(sessions).isSymbolicLink()).toBe(true); }); -skipOnWindows('refuses a state directory another user owns, and leaves its mode', () => { - // Ownership is judged from the same `lstat` the destination rule judges ground by, so a root daemon - // repairs root-owned state and does NOT strip access from a directory somebody else owns — which a - // `chmod 0700` by pathname would have done to their files. +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'); @@ -70,36 +92,46 @@ skipOnWindows('refuses a state directory another user owns, and leaves its mode' fs.chmodSync(sessions, 0o775); serveHostOwnership({ [sessions]: FOREIGN_UID }); - expectRefusal(() => ensurePrivateDaemonStateDir(sessions), 'state_dir_foreign_owned', sessions); + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions))).toBe(1); expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o775); }); -skipOnWindows('warns and changes nothing when a state directory cannot be opened at all', () => { - // A state directory left at 0000 is this process's own, so ownership does not refuse it, and no - // descriptor can be opened to force its mode. Repair reports that and moves on: startup must not die on a - // host it cannot fix, which is the rule `repairStateMode` already applied to a read-only mount. - const base = mkdtempForTestSync('agent-device-state-unreadable-'); - fs.chmodSync(base, 0o755); - const sessions = path.join(base, 'sessions'); - fs.mkdirSync(sessions); - fs.chmodSync(sessions, 0o000); +skipOnWindows( + 'skips a state directory the host will not let it open, and starts anyway', + async () => { + // `EACCES` from the open is what a read-only mount, or a directory this user cannot even read, answers + // with. A root process CAN open a 0000 directory it owns, so the denial is injected at the seam the mode + // is forced through rather than staged as a mode: that keeps this the same case on any uid. Startup must + // not die on a host it cannot fix, which is the rule `repairStateMode` already applied to the log file. + const base = mkdtempForTestSync('agent-device-state-unopenable-'); + const sessions = path.join(base, 'sessions'); + fs.mkdirSync(sessions); + fs.chmodSync(sessions, 0o755); + const denied = Object.assign(new Error('test open denied'), { code: 'EACCES' }); + const realOpen = fs.openSync; + vi.spyOn(fs, 'openSync').mockImplementation((( + target: fs.PathLike | number, + flags: fs.OpenMode, + mode?: fs.Mode, + ) => { + if (target === sessions) throw denied; + return realOpen(target as fs.PathLike, flags, mode); + }) as typeof fs.openSync); - try { - expect(() => ensurePrivateDaemonStateDir(sessions)).not.toThrow(); - expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o000); - } finally { - fs.chmodSync(sessions, 0o700); - } -}); + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions))).toBe(1); -/** The typed refusal the repair answers with, naming the state path it would not touch. */ -function expectRefusal(run: () => void, reason: string, target: string): void { - let seen: AppError | undefined; - try { - run(); - } catch (error) { - seen = error instanceof AppError ? error : undefined; - } - expect(seen?.details).toMatchObject({ reason, path: target }); + expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o755); + }, +); + +/** + * 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 241d03fb50..0fdf7396d5 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -282,22 +282,19 @@ export function createOwnedReplayStateDir(): OwnedReplayStateDir { * 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 the daemon would refuse its own default recordings and every - * remote-delivered version. Creation carries the mode and the repair forces it, because a state dir an older - * version created at 0775 is the same refusal. + * 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): it forces the mode on a level this uid owns and * changes nothing about any other, so a state directory on a mounted volume, or one another uid left at - * 0755, still gets a daemon that starts. A recording under ground the daemon does not own is refused by the - * destination walk, which is where the entry is actually created. - * - * Returns the path so a caller can name what it just made without a second `mkdir` of its own. + * 0755, still gets a daemon that starts. The destination walk is what refuses a recording under ground this + * daemon does not own. Returns the path, so a caller can name what it made without a second `mkdir`. */ export function ensurePrivateDaemonStateDir(directory: string): string { const firstCreated = fs.mkdirSync(directory, { recursive: true, mode: STATE_DIR_MODE }); // `mkdir` reports the FIRST directory it made, and everything from there down is this call's to force - // private. Repairing only the leaf would leave the level ABOVE a session directory, `sessions/`, at the - // 0775 a umask-002 creation gives it, which is the directory every recording is walked through. + // private. Repairing only the leaf would leave `sessions/` at the 0775 a umask-002 creation gives it, and + // every recording is walked through that directory. for (const level of createdStateLevels(firstCreated, directory)) { repairPrivateStateDir(level); } @@ -325,15 +322,14 @@ const STATE_DIR_MODE = 0o700; /** * Forces one existing state level to {@link STATE_DIR_MODE}, or changes nothing and says why. * - * `chmod` given the NAME acts on whatever the name resolves to, so the mode is applied through a descriptor - * opened `O_DIRECTORY | O_NOFOLLOW` and only after that descriptor's `fstat` says this uid owns the entry: a - * root daemon repairing a legacy state directory another local user could write would otherwise reach through - * a `sessions` they left as a link, and strip access from an owner who never ran the daemon. + * `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: a root + * daemon repairing a legacy state directory another local user could write would otherwise reach through a + * `sessions` they left as a link, and strip access from an owner who never ran the daemon. * - * Every case that cannot be forced is a SKIP with a diagnostic, not a refusal — a link, a name that is not a - * directory, a level another uid owns, and a mount that denies the open or the chmod. This function never - * throws for them: it decides a mode, never whether the daemon starts (ADR 0016), and the destination walk is - * the only thing that refuses a recording. + * A link, a name that is not a directory, a level another uid owns and a mount that denies the open or the + * chmod are all a SKIP with a diagnostic, never a refusal: this decides a mode, not whether the daemon + * starts (ADR 0016). */ function repairPrivateStateDir(directory: string): void { // Windows answers access from an ACL, and `chmod` there only toggles the read-only bit. @@ -373,9 +369,9 @@ function skipStateDirMode(directory: string, because: string): void { } /** - * What a mode repair may never fail the daemon on: a host that denies the chmod (`EPERM`, `EROFS`, the two - * spellings of an unsupported one), a name that cannot be opened as a directory (`ELOOP` for a link, - * `ENOTDIR`), and a directory that will not even open for this user (`EACCES`). + * 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', 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 89d1bae665..f968b88220 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 @@ -8,7 +8,10 @@ import { serveHostOwnership, } from '@agent-device/test-kit'; import { ensurePrivateDaemonStateDir } from '@agent-device/daemon-contracts/daemon-registration-owner'; -import { AppError } from '@agent-device/kernel/errors'; +import { + countDiagnosticEventsByPhase, + withDiagnosticsScope, +} from '@agent-device/host-kit/diagnostics'; import { SessionStore } from '../session-store.ts'; import { authoringPublication, @@ -180,11 +183,14 @@ test.skipIf(process.platform === 'win32')( ); test.skipIf(process.platform === 'win32')( - 'refuses to repair a `sessions` directory another user owns, and changes nothing there', - () => { + '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'); @@ -192,10 +198,7 @@ test.skipIf(process.platform === 'win32')( fs.chmodSync(sessions, 0o775); serveHostOwnership({ [sessions]: FOREIGN_UID }); - expect(refusalOf(() => ensurePrivateDaemonStateDir(sessions))).toMatchObject({ - reason: 'state_dir_foreign_owned', - path: sessions, - }); + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions))).toBe(1); // Nothing was touched: the owner's directory keeps the mode they set for it. expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o775); @@ -203,12 +206,12 @@ test.skipIf(process.platform === 'win32')( ); test.skipIf(process.platform === 'win32')( - 'refuses a planted `sessions` link under state another user can write, and leaves where it leads alone', - () => { + '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 ENTRY under the name is what gets judged instead, so the link itself is the refusal. + // 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'); @@ -217,10 +220,7 @@ test.skipIf(process.platform === 'win32')( const sessions = path.join(root, 'sessions'); fs.symlinkSync(planted, sessions); - expect(refusalOf(() => ensurePrivateDaemonStateDir(sessions))).toMatchObject({ - reason: 'state_dir_not_a_directory', - path: sessions, - }); + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions))).toBe(1); expect(fs.lstatSync(planted).mode & 0o777).toBe(0o777); expect(fs.readdirSync(planted)).toEqual([]); @@ -233,12 +233,13 @@ function refusal(result: object): string { return JSON.stringify(result); } -/** The typed details of the refusal a state repair answered with. */ -function refusalOf(run: () => void): Record | undefined { - try { - run(); - } catch (error) { - return (error as AppError).details as Record; - } - throw new Error('a state directory this process may not repair was repaired'); +/** + * 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/server/http/daemon-runtime-state-dir.test.ts b/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts index e41c103e9c..b00f72c0e5 100644 --- a/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts +++ b/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts @@ -1,10 +1,12 @@ // 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. +// 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, @@ -12,8 +14,11 @@ import { 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 { AppError } from '@agent-device/kernel/errors'; import { SessionStore } from '../../core/session-store.ts'; import { authoringPublication, @@ -66,27 +71,82 @@ test.skipIf(process.platform === 'win32')( ); test.skipIf(process.platform === 'win32')( - 'startup refuses state it may not force private, instead of changing another user files', + 'startup starts on state another user owns, warns, and refuses only the recording under it', async () => { - // A `sessions` left owned by a different uid — the shape a machine sees when one user ran the daemon as - // root — is refused with its mode intact. Forcing it would take a directory away from its owner. - const stateDir = mkdtempForTestSync('agent-device-startup-state-foreign-'); + // 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, 0o775); + fs.chmodSync(sessionsDir, 0o755); serveHostOwnership({ [sessionsDir]: FOREIGN_UID }); - const started = startDaemonRuntime({ - host: hostFor(stateDir), - ...silent, - composeDeps: daemonRuntimeDepsFixture({}), - }); + // 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); - expect(detailsOf(await started.catch((error: unknown) => error))).toMatchObject({ - reason: 'state_dir_foreign_owned', - path: sessionsDir, - }); - expect(modeOf(sessionsDir)).toBe(0o775); + // The refusal the host DOES get is the one that names the destination, per recording. + 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: 'script_ancestor_untrusted', + exposure: 'foreign_owned', + ancestor: sessionsDir, + }); + } 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(); + } }, ); @@ -105,7 +165,9 @@ function modeOf(target: string): number { return Number(fs.lstatSync(target).mode & 0o777); } -/** The typed details of the startup failure, so a refusal is read by its reason and never by its text. */ -function detailsOf(error: unknown): Record | undefined { - return error instanceof AppError ? (error.details as Record) : undefined; +/** 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/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index ea4cbfa7e7..68ac011ffd 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -120,20 +120,14 @@ 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 + * 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. A caller never hands its own `mkdir` to a path this rule has not stopped. - * - * The second walk asks the CREATION question — whether other local users could add the destination's own - * name inside the directory the walk ended in. The first walk does not, because below it the missing - * directories are this call's own to create at 0700, which is what keeps + * 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. * - * The answer carries the judged directory's identity, so a caller that stages bytes there can confirm the - * ground one time before it renames, without asking the host about ground this call already judged, and - * never runs a `mkdir` of its own. - * * 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. */ @@ -145,28 +139,24 @@ export function prepareScriptDestination(destination: string): ScriptDestination } const trust = scriptTrust(); const walked = walkSpelledParent(spelled, destination, trust); - if (walked.reject !== undefined) throw walked.reject; - if (walked.unresolvable) { - throw scriptAncestryFailure(destination, walked.deepest, 'unresolvable_parent'); - } - // Where the chain already stands, this walk judged the directory the entry is created in and there is - // nothing to create, so it is also the answer. Only a walk that stopped short creates and walks again. - if (walked.arrived) return publishableDestination(destination, walked, trust); - // A walk that stopped short always judged the directory it stopped in, so it has an identity to create - // under. Anything else that did not arrive refused ground, and creates nothing. - if (walked.identity === undefined) { - throw scriptAncestryFailure(destination, walked.deepest, 'unreachable_parent'); + 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, + ); } - 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. - * - * `identity` is `dev:ino` as the walk's own `lstat` answered it. It is what - * {@link confirmScriptDestination} compares for a caller that stages bytes for a later rename, so the one - * check a caller owes is one this host-kit makes rather than one it writes itself. + * 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; @@ -302,17 +292,12 @@ function statOrNull(pathname: string): fs.Stats | 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, a long upload or any other wait - * 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. Every `parent_replaced` refusal is built by - * {@link scriptAncestryFailure}, which is why no caller writes one: the shape a caller would copy is the - * host-kit answer's reason, exposure, ancestor and hint, and a route that hand-rolls them drifts from the - * rule that produced them. - * - * A walk that now answers a DIFFERENT directory than the answer named — an ancestor pointed at a link - * meanwhile — is the swap this catches, and the version is refused rather than renamed into ground nobody - * judged. Nothing here 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). + * 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); @@ -323,13 +308,12 @@ export function confirmScriptDestination(destination: string, prepared: ScriptDe } /** - * Walks a destination that has to stand as it is, creating nothing, and judges the answer. - * - * Refuses a destination 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; everything written there about how the walk judges ground, 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`. + * 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); @@ -338,10 +322,7 @@ function scriptDestination(destination: string): ScriptDestination { } const trust = scriptTrust(); const walk = walkSpelledParent(spelled, destination, trust); - if (walk.reject !== undefined) throw walk.reject; - if (walk.unresolvable) { - throw scriptAncestryFailure(destination, walk.deepest, 'unresolvable_parent'); - } + if (walk.ended === 'refused') throw walk.reject; return publishableDestination(destination, walk, trust); } @@ -349,17 +330,23 @@ function scriptDestination(destination: string): ScriptDestination { * 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. * - * 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 the nearest ancestor it did reach is a file under a name nobody asked for. + * 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.reject !== undefined) throw walk.reject; - if (!walk.arrived) { - throw scriptAncestryFailure(destination, walk.deepest, 'unreachable_parent'); + 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. @@ -403,8 +390,6 @@ type WalkStep = | Readonly<{ kind: 'short'; deepest: string; - authority: DirectoryAuthority; - identity: 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. */ @@ -413,41 +398,35 @@ type WalkStep = | 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. Every other ending reports how far the walk - * got, which is what a caller that creates needs in order to create below judged ground only. + * 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 did not arrive stopped at a name that does not exist, and the nearest ancestor it did reach is - * NOT where the entry belongs: publishing there writes a file the caller never named. `unresolvable` says a - * `..` is queued behind that absent name, so creating cannot finish the resolution. + * 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<{ - arrived: true; + 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; - reject?: undefined; - unresolvable?: undefined; - missing?: undefined; }> | Readonly<{ - arrived: false; - /** The nearest directory the walk did judge, or `/` when it refused before judging one. */ + ended: 'short'; + /** The nearest directory the walk did judge; the destination's name is absent below it. */ deepest: string; - /** That directory's identity as the walk judged it, when it judged one. */ - identity: string | undefined; - /** The step that made the chain unsafe, when an existing step refused rather than went missing. */ - reject: AppError | undefined; - /** Whether a `..` is queued behind the absent name, so creating cannot resolve the chain. */ - unresolvable: boolean; /** The spelled names below `deepest`, the first of them absent. */ missing: readonly string[]; - authority?: undefined; - }>; + /** Whether a `..` is queued behind that name, so creating cannot resolve the chain. */ + unresolvable: boolean; + }> + | Readonly<{ ended: 'refused'; reject: AppError }>; /** * Walks the spelled parent exactly as the kernel resolves a path, judging every step, and refuses at the @@ -460,7 +439,7 @@ type WalkOutcome = * - `.` 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: `arrived` is false, `missing` is the tail + * 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. @@ -482,50 +461,34 @@ function walkSpelledParent( // Every step consumes a component, and every link hop counts against a fixed limit, so this ends. for (;;) { if (step.kind === 'reject') { - return refused(scriptAncestryFailure(destination, step.path, step.exposure)); + return { + ended: 'refused', + reject: scriptAncestryFailure(destination, step.path, step.exposure), + }; + } + if (step.kind === 'short') { + return { + ended: 'short', + deepest: step.deepest, + missing: step.missing, + unresolvable: step.behindUpwardStep, + }; } - if (step.kind === 'short') return stoppedShort(step); const { state } = step; const [component, ...rest] = state.queue; - // The only exit that ARRIVES: an empty queue, every name the parent spelled resolved and judged. - if (component === undefined) return arrived(state); + // 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 one outcome that owns the answer: the judged directory the entry is created in. */ -function arrived(state: WalkState): WalkOutcome { - return { - arrived: true, - deepest: state.deepest, - authority: state.authority, - identity: state.identity, - }; -} - -/** A walk that refused has no directory to report, because none of them is established as the entry's. */ -function refused(reject: AppError): WalkOutcome { - return { - arrived: false, - deepest: '/', - identity: undefined, - reject, - unresolvable: false, - missing: [], - }; -} - -function stoppedShort(step: Extract): WalkOutcome { - return { - arrived: false, - deepest: step.deepest, - identity: step.identity, - reject: undefined, - unresolvable: step.behindUpwardStep, - missing: step.missing, - }; -} - /** 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); @@ -617,8 +580,6 @@ function stepIntoEntry( return { kind: 'short', deepest: state.deepest, - authority: state.authority, - identity: state.identity, missing: [component, ...rest], behindUpwardStep: rest.includes('..'), }; @@ -913,8 +874,9 @@ function createMissingLevel( const exposure = untrustedAncestryExposure(authority, trust); if (exposure) throw scriptAncestryFailure(destination, level, exposure); if (created) { - // The creation carries the mode, and this forces it: `mkdir` ANDs it with the umask, so under the - // shared-checkout 002 the level would stand 0775 and the walk that follows would refuse it. + // `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; } diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 106b94ba56..cd7c628fe1 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -203,9 +203,8 @@ async function publishScriptVersion( try { // 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 - // is going to refuse therefore leaves no directories behind in the shared ground it names. The ANSWER - // is what staging is allocated in, so this route walks a destination once per version rather than - // walking it again for the sake of being told the same directory. + // 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?.staging; @@ -222,8 +221,7 @@ async function publishScriptVersion( revision: revision as number, staging, staged, - // The directory host-kit answered when staging was allocated, so the publish can confirm the ground - // one time before the rename, through the same call that refuses it. + // What host-kit answered when staging was allocated, for the one confirmation before the rename. prepared: allocated.prepared, pending, }; @@ -244,14 +242,12 @@ async function publishScriptVersion( } /** - * Creates a staging directory beside the destination and lists it in the record before any script - * bytes reach it, and reports the confirmed destination so the publish can confirm it once more. + * Creates a staging directory beside the destination and lists it in the record before any script bytes + * reach it, and reports the prepared destination the publish confirms before its rename. * - * Staging sits in the directory the ancestry walk JUDGED — the `prepareScriptDestination` answer, not - * `path.dirname` of the spelled destination. Where a `..` or a link in the destination leads elsewhere, the - * spelled parent is a directory nobody judged, and a staging directory in it is one another local user can - * populate before the rename does. The answer is used as it stands: nobody the rule accepted can move it - * before this call, and the check the route owes comes after the download, at {@link confirmScriptDestination}. + * 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, diff --git a/packages/test-kit/src/host-ownership.fixtures.ts b/packages/test-kit/src/host-ownership.fixtures.ts index ae945c1966..b2d95e07e0 100644 --- a/packages/test-kit/src/host-ownership.fixtures.ts +++ b/packages/test-kit/src/host-ownership.fixtures.ts @@ -8,20 +8,41 @@ 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` to another uid — and moving - * the CALLER's uid instead decides the test by which directories the scratch tree happens to sit under. + * 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>): void { - const realLstat = fs.lstatSync.bind(fs); - const realStat = fs.statSync.bind(fs); - const reuid = (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; + // 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), }; - vi.spyOn(fs, 'lstatSync').mockImplementation(((pathname: never, ...rest: never[]) => - reuid(realLstat(pathname, ...rest), String(pathname))) as typeof fs.lstatSync); - vi.spyOn(fs, 'statSync').mockImplementation(((pathname: never, ...rest: never[]) => - reuid(realStat(pathname, ...rest), String(pathname))) as typeof fs.statSync); + const openedOn = new Map(); + // 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; + }; + 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)); + 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); } From 4b630c1f5b9856171a73da86dd548898b8a5ef96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 01:22:18 +0100 Subject: [PATCH 23/28] docs(adr): say what the state repair judges, in the tense the code has The paragraph that introduced the repair said the descriptor's fstat must match the lstat that judged the name. The lstat is now only the fast path, and ownership is answered by the fstat of the descriptor the chmod goes through, so the ADR says that instead. Co-Authored-By: Claude Opus 5.5 --- docs/adr/0016-active-session-script-publication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index ab9269cc54..51df6b010e 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -222,7 +222,7 @@ Shapes this closes, each of which an earlier shape of the rule accepted: 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 applies the same judgment as the walk, and to one directory less: each level is read by `lstat` first, so the mode is forced through a descriptor opened `O_DIRECTORY | O_NOFOLLOW` on the entry that read judged, never through the NAME: 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. +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. 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, `EACCES`/`EPERM`/`EROFS` from a mount it cannot force — changes nothing and emits `daemon_state_mode_repair_skipped`. A state directory on a bind-mounted CI volume, a `~/.agent-device` symlinked to another disk, and a root container whose `sessions/` belongs to the mounted uid therefore start exactly as they did before this rule existed, and every command still works. The destination walk stays the ONLY thing that refuses a recording: it judges that same chain per publish and refuses a script under such a tree with `script_ancestor_untrusted` and its hint, so the repair skipping costs safety nothing — an unsafe destination is refused where the entry is actually created. 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. The script file is created 0600, locally and remotely alike, so a recording is not world-readable in a directory that is merely shared. From e38764b1e7ad735b2bb4e644b6b2a301673972c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 01:54:49 +0100 Subject: [PATCH 24/28] fix(daemon): judge the state repair down from the state base Two blockers in the best-effort state repair. A repair step that failed could still stop startup: the `lstat` stood outside the catch, unlisted errnos were rethrown, and the `close` that ends the repair could throw. Every step is now inside one catch, so `EACCES` on a level this user cannot read, `ENOENT` on one that disappears meanwhile, and `EIO` on the close are all reported as a skipped level and stop there. Creation keeps its own failures. `O_NOFOLLOW` guards only the LAST name of an open, so judging the requested level alone let an intermediate link redirect the repair: `sessions -> /etc` makes the leaf `sessions/ssh` resolve to `/etc/ssh`, and a root daemon forced that mode to 0700. The repair now 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 link, a non-directory or a foreign-owned level stops the descent, and every level beneath it is left as it is. Callers pass the base they judge from. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 4 +- ...aemon-registration-owner-state-dir.test.ts | 210 +++++++++++++----- .../src/daemon-registration-owner.ts | 139 ++++++++---- .../session-store-teardown-script.test.ts | 6 +- .../daemon/src/core/session-script-writer.ts | 5 +- packages/daemon/src/core/session-store.ts | 15 +- .../daemon/src/server/http/daemon-runtime.ts | 4 +- 7 files changed, 270 insertions(+), 113 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 51df6b010e..ca5e3285bd 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -222,9 +222,9 @@ Shapes this closes, each of which an earlier shape of the rule accepted: 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. +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. -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, `EACCES`/`EPERM`/`EROFS` from a mount it cannot force — changes nothing and emits `daemon_state_mode_repair_skipped`. A state directory on a bind-mounted CI volume, a `~/.agent-device` symlinked to another disk, and a root container whose `sessions/` belongs to the mounted uid therefore start exactly as they did before this rule existed, and every command still works. The destination walk stays the ONLY thing that refuses a recording: it judges that same chain per publish and refuses a script under such a tree with `script_ancestor_untrusted` and its hint, so the repair skipping costs safety nothing — an unsafe destination is refused where the entry is actually created. 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. +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 level 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. A state directory on a bind-mounted CI volume, a `~/.agent-device` symlinked to another disk, and a root container whose `sessions/` belongs to the mounted uid therefore start exactly as they did before this rule existed, and every command still works. The destination walk stays the ONLY thing that refuses a recording: it judges that same chain per publish and refuses a script under such a tree with `script_ancestor_untrusted` and its hint, so the repair skipping costs safety nothing — an unsafe destination is refused where the entry is actually created. 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. 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. 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 index 7ad59da029..3528e8a264 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts @@ -1,7 +1,7 @@ // 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 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 thing that refuses. +// 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'; @@ -16,14 +16,28 @@ 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 directories it owns, whatever mode they were created with', () => { +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. + // 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'); @@ -33,51 +47,82 @@ skipOnWindows('repairs the state directories it owns, whatever mode they were cr fs.chmodSync(directory, 0o775); } - // How the daemon actually calls it: startup ensures `sessions/`, the remote writer ensures - // `remote-scripts/`, and each call repairs the levels it was asked for. - ensurePrivateDaemonStateDir(sessions); - expect(ensurePrivateDaemonStateDir(remote)).toBe(remote); + // 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); + expect(ensurePrivateDaemonStateDir(remote, base)).toBe(remote); - for (const directory of [sessions, remote]) { - expect(fs.lstatSync(directory).mode & 0o777).toBe(0o700); + for (const directory of [base, sessions, remote]) { + expect(modeOf(directory)).toBe(0o700); } }); -skipOnWindows('asks nothing of a level that already stands private', () => { - // The fast path, and the reason a normal start costs no extra work: a 0700 level is already what the - // repair would force, so it is not even opened. Deleting the mode check makes this red. +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); - fs.chmodSync(sessions, 0o700); + for (const directory of [base, sessions]) fs.chmodSync(directory, 0o700); const open = vi.spyOn(fs, 'openSync'); - ensurePrivateDaemonStateDir(sessions); + ensurePrivateDaemonStateDir(sessions, base); expect(open).not.toHaveBeenCalled(); }); -skipOnWindows('skips a state name that is a link, and leaves where it leads alone', async () => { - // Repair reaches a legacy state directory another local user could write, and they use that write to - // leave a link at `sessions`. A `chmod` given the NAME travels through it, so a root daemon forcing its - // own state private would change the mode of a directory somebody else chose. So the mode is applied - // through an `O_NOFOLLOW` descriptor instead, and a link cannot be opened as one: this call skips the - // level, and the daemon starts as it did before the repair judged links at all. - const base = mkdtempForTestSync('agent-device-state-link-'); +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); - const planted = path.join(base, 'other-users-home'); - fs.mkdirSync(planted); - fs.chmodSync(planted, 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('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.symlinkSync(planted, 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(sessions))).toBe(1); + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(remote, base))).toBe(1); - // Nothing was changed: the mode the owner set is still the mode the directory has, the link is still a - // link rather than a directory this call made, and nothing was created on its far side. - expect(fs.lstatSync(planted).mode & 0o777).toBe(0o777); - expect(fs.readdirSync(planted)).toEqual([]); - expect(fs.lstatSync(sessions).isSymbolicLink()).toBe(true); + expect(modeOf(sessions)).toBe(0o700); + expect(modeOf(outside)).toBe(0o777); + expect(fs.readdirSync(outside)).toEqual([]); }); skipOnWindows('skips a state directory another user owns, and leaves its mode', async () => { @@ -92,39 +137,92 @@ skipOnWindows('skips a state directory another user owns, and leaves its mode', fs.chmodSync(sessions, 0o775); serveHostOwnership({ [sessions]: FOREIGN_UID }); - expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions))).toBe(1); + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, base))).toBe(1); - expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o775); + expect(modeOf(sessions)).toBe(0o775); }); skipOnWindows( - 'skips a state directory the host will not let it open, and starts anyway', + 'skips a chain whose state base is a link, and creates its state anyway', async () => { - // `EACCES` from the open is what a read-only mount, or a directory this user cannot even read, answers - // with. A root process CAN open a 0000 directory it owns, so the denial is injected at the seam the mode - // is forced through rather than staged as a mode: that keeps this the same case on any uid. Startup must - // not die on a host it cannot fix, which is the rule `repairStateMode` already applied to the log file. - const base = mkdtempForTestSync('agent-device-state-unopenable-'); + // `~/.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'); - fs.mkdirSync(sessions); - fs.chmodSync(sessions, 0o755); - const denied = Object.assign(new Error('test open denied'), { code: 'EACCES' }); - const realOpen = fs.openSync; - vi.spyOn(fs, 'openSync').mockImplementation((( - target: fs.PathLike | number, - flags: fs.OpenMode, - mode?: fs.Mode, - ) => { - if (target === sessions) throw denied; - return realOpen(target as fs.PathLike, flags, mode); - }) as typeof fs.openSync); - - expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions))).toBe(1); - - expect(fs.lstatSync(sessions).mode & 0o777).toBe(0o755); + + 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. diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index 0fdf7396d5..cb8faea358 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -289,82 +289,129 @@ export function createOwnedReplayStateDir(): OwnedReplayStateDir { * changes nothing about any other, so a state directory on a mounted volume, or one another uid left at * 0755, still gets a daemon that starts. The destination walk is what refuses a recording under ground this * daemon does not own. Returns the path, so a caller can name what it made without a second `mkdir`. + * + * `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): string { - const firstCreated = fs.mkdirSync(directory, { recursive: true, mode: STATE_DIR_MODE }); - // `mkdir` reports the FIRST directory it made, and everything from there down is this call's to force - // private. Repairing only the leaf would leave `sessions/` at the 0775 a umask-002 creation gives it, and - // every recording is walked through that directory. - for (const level of createdStateLevels(firstCreated, directory)) { - repairPrivateStateDir(level); - } +export function ensurePrivateDaemonStateDir(directory: string, stateBase: string): string { + // Creation is one recursive `mkdir`: it creates the whole tail, while the repair below judges every level + // it reached. Creating one level at a time would have to decide what to do when the BASE is a link, which + // is the shape of a `~/.agent-device` on another disk, and refusing to create there would break a host the + // operator pointed at that disk. What creation can leave on ground the chain rejects is an empty + // directory, and the destination walk refuses any recording under it. + fs.mkdirSync(directory, { recursive: true, mode: STATE_DIR_MODE }); + repairStateChain(stateBase, directory); return directory; } -/** Every level one creation made: `firstCreated` itself, down to `directory`. */ -function createdStateLevels( - firstCreated: string | undefined, - directory: string, -): readonly string[] { - const below = - firstCreated === undefined || firstCreated === directory - ? [] - : path.relative(firstCreated, directory).split(path.sep); - if (firstCreated === undefined || below.length === 0 || below[0] === '..') return [directory]; - return [ - firstCreated, - ...below.map((_, index) => path.join(firstCreated, ...below.slice(0, index + 1))), - ]; -} - const STATE_DIR_MODE = 0o700; /** - * Forces one existing state level to {@link STATE_DIR_MODE}, or changes nothing and says why. + * Forces every state level from `stateBase` down to `directory` to {@link STATE_DIR_MODE}, and never throws. * - * `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: a root - * daemon repairing a legacy state directory another local user could write would otherwise 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 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. * - * A link, a name that is not a directory, a level another uid owns and a mount that denies the open or the - * chmod are all a SKIP with a diagnostic, never a refusal: this decides a mode, not whether the daemon - * starts (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` above. */ -function repairPrivateStateDir(directory: string): void { +function repairStateChain(stateBase: string, directory: string): void { // Windows answers access from an ACL, and `chmod` there only toggles the read-only bit. if (process.platform === 'win32') return; - const judged = fs.lstatSync(directory, { bigint: true, throwIfNoEntry: false }); - // The name is gone by now: whatever removed it also removed the mode this call came to force. - if (judged === undefined) return; + 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; + } + for (const level of levels) { + try { + if (!repairStateLevel(level)) return; + } catch (error) { + skipStateDirMode(level, (error as NodeJS.ErrnoException).code ?? 'unknown'); + return; + } + } +} + +/** + * Forces one level, and reports whether the descent may go on beneath it. + * + * `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 a name that does not exist. + if (judged === undefined) return false; + 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; + if ((Number(judged.mode) & 0o777) === STATE_DIR_MODE) return true; + forcePrivateStateDir(level); + return true; +} + +/** Forces one level whose ownership passed, through a descriptor that cannot follow a link. */ +function forcePrivateStateDir(level: string): void { let descriptor: number | undefined; try { descriptor = fs.openSync( - directory, + 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(directory, 'not owned by this user'); + skipStateDirMode(level, 'foreign_owned'); return; } fs.fchmodSync(descriptor, STATE_DIR_MODE); - } catch (error) { - if (!MODE_REPAIR_SKIPPED_CODES.has((error as NodeJS.ErrnoException).code ?? '')) throw error; - skipStateDirMode(directory, (error as NodeJS.ErrnoException).code ?? 'unknown'); } finally { if (descriptor !== undefined) fs.closeSync(descriptor); } } -/** Reports the one state level whose mode this repair will not change. */ -function skipStateDirMode(directory: string, because: string): void { +/** 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: directory, error: { message: `state level kept as it is: ${because}` } }, + data: { path: level, reason: `state mode repair stopped at this level: ${reason}` }, }); } @@ -419,7 +466,7 @@ export function launchDaemonProcess( throw new AppError('COMMAND_FAILED', 'Replay daemon startup admission is closed.', { reason: 'daemon_startup_admission_closed', }); - ensurePrivateDaemonStateDir(input.paths.baseDir); + ensurePrivateDaemonStateDir(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/core/__tests__/session-store-teardown-script.test.ts b/packages/daemon/src/core/__tests__/session-store-teardown-script.test.ts index f968b88220..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 @@ -169,7 +169,7 @@ test.skipIf(process.platform === 'win32')( // 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); + 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); @@ -198,7 +198,7 @@ test.skipIf(process.platform === 'win32')( fs.chmodSync(sessions, 0o775); serveHostOwnership({ [sessions]: FOREIGN_UID }); - expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions))).toBe(1); + 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); @@ -220,7 +220,7 @@ test.skipIf(process.platform === 'win32')( const sessions = path.join(root, 'sessions'); fs.symlinkSync(planted, sessions); - expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions))).toBe(1); + expect(await skipCountFor(() => ensurePrivateDaemonStateDir(sessions, root))).toBe(1); expect(fs.lstatSync(planted).mode & 0o777).toBe(0o777); expect(fs.readdirSync(planted)).toEqual([]); diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index 5954ead3b2..472edd1262 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -166,7 +166,10 @@ export class SessionScriptWriter { * `publishScriptFileSync` decides. */ private remoteScriptPath(): string { - const directory = ensurePrivateDaemonStateDir(path.join(this.sessionsDir, 'remote-scripts')); + const directory = ensurePrivateDaemonStateDir( + path.join(this.sessionsDir, 'remote-scripts'), + path.dirname(this.sessionsDir), + ); return path.join(directory, `${crypto.randomUUID()}.ad`); } diff --git a/packages/daemon/src/core/session-store.ts b/packages/daemon/src/core/session-store.ts index 1d8d620ffd..65f3950b80 100644 --- a/packages/daemon/src/core/session-store.ts +++ b/packages/daemon/src/core/session-store.ts @@ -370,7 +370,10 @@ export class SessionStore { const session = this.resolveCurrent(ref); if (!session) return; try { - ensurePrivateDaemonStateDir(this.resolveSessionDir(ref.address)); + ensurePrivateDaemonStateDir( + this.resolveSessionDir(ref.address), + this.resolveDaemonStateDir(), + ); const tombstone: RepairSessionTombstone = { owner: ref.address, reapedAt: Date.now(), @@ -439,7 +442,10 @@ export class SessionStore { */ writeIdleExpiryTombstone(sessionName: string, tombstone: IdleSessionTombstone): void { try { - ensurePrivateDaemonStateDir(this.resolveSessionDir(sessionName)); + ensurePrivateDaemonStateDir( + this.resolveSessionDir(sessionName), + this.resolveDaemonStateDir(), + ); fs.writeFileSync( resolveIdleSessionTombstonePath(this.resolveSessionDir(sessionName)), `${JSON.stringify(tombstone)}\n`, @@ -523,7 +529,10 @@ export class SessionStore { // 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 { - return ensurePrivateDaemonStateDir(this.resolveSessionDir(sessionName)); + return ensurePrivateDaemonStateDir( + 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/http/daemon-runtime.ts b/packages/daemon/src/server/http/daemon-runtime.ts index 2002e2015d..4e482bce33 100644 --- a/packages/daemon/src/server/http/daemon-runtime.ts +++ b/packages/daemon/src/server/http/daemon-runtime.ts @@ -212,8 +212,8 @@ async function startDaemonRuntimeOnHost( // 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. - ensurePrivateDaemonStateDir(baseDir); - ensurePrivateDaemonStateDir(sessionsDir); + ensurePrivateDaemonStateDir(baseDir, baseDir); + ensurePrivateDaemonStateDir(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 From 8cd5b8ac35ffddd8e1d3bcc97518146c0bbee8d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 02:00:01 +0100 Subject: [PATCH 25/28] fix(daemon): judge what a state level is before its mode A link that carries its own mode answers the mode question with the private mode, so a repair that read the mode first passed an `lchmod 0700` link without judging it. The level-by-level repair already asks `isDirectory` before the fast path; this pins the order, and a skip is what such a link now reports. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 2 +- ...aemon-registration-owner-state-dir.test.ts | 26 +++++++++++++++++++ .../src/daemon-registration-owner.ts | 2 ++ 3 files changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index ca5e3285bd..52a1e56d42 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -222,7 +222,7 @@ Shapes this closes, each of which an earlier shape of the rule accepted: 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. +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. 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 level 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. A state directory on a bind-mounted CI volume, a `~/.agent-device` symlinked to another disk, and a root container whose `sessions/` belongs to the mounted uid therefore start exactly as they did before this rule existed, and every command still works. The destination walk stays the ONLY thing that refuses a recording: it judges that same chain per publish and refuses a script under such a tree with `script_ancestor_untrusted` and its hint, so the repair skipping costs safety nothing — an unsafe destination is refused where the entry is actually created. 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. The script file is created 0600, locally and remotely alike, so a recording is not world-readable in a directory that is merely shared. 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 index 3528e8a264..666e9c3dff 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts @@ -103,6 +103,32 @@ skipOnWindows('stops at an intermediate link and leaves where it leads alone', a 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 diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index cb8faea358..f811a93a6f 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -356,6 +356,8 @@ function repairStateLevel(level: string): boolean { // The name is gone: whatever removed it also removed the mode this call came to force, and there is // nothing below a name that does not exist. if (judged === undefined) 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; From fa64dfe53b4e2c45606a66a61547532a64123459 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 02:52:49 +0100 Subject: [PATCH 26/28] fix(daemon): refuse a script the state repair could not claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two blockers in the state repair. A remote version followed a state link the repair had skipped. The repair stops at a link, but the writer used the path the ensure call returned anyway, and the destination rule accepts a link standing in a parent others cannot write, so `sessions -> outside` and `remote-scripts -> outside` both published outside the state tree. Ensuring a state level now answers whether the whole chain from the state base is private ground, and a destination the daemon picked for itself — a remote version, or a default recording — is written only on such a chain. The write returns a typed refusal (`state_chain_untrusted`), the capability carries it as the `scriptDeliveryFailure` cause and keeps the action's success, and startup ignores the answer and still starts. A descriptor ownership rejection did not stop the descent: `forcePrivateStateDir` returned on a foreign uid while its caller returned `true` regardless, so the repair continued beneath a level it had just refused. The decision now travels out of the force step. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 7 +- ...aemon-registration-owner-state-dir.test.ts | 70 +++++++++++- .../src/daemon-registration-owner.ts | 63 +++++++--- .../session-script-writer-ancestry.test.ts | 108 +++++++++++++++++- .../session-script-publication-capability.ts | 7 +- .../daemon/src/core/session-script-writer.ts | 91 ++++++++++++--- packages/daemon/src/core/session-store.ts | 17 +-- .../http/daemon-runtime-state-dir.test.ts | 13 ++- .../daemon/src/server/http/daemon-runtime.ts | 6 +- .../test-kit/src/host-ownership.fixtures.ts | 42 ++++++- packages/test-kit/src/index.ts | 6 +- 11 files changed, 365 insertions(+), 65 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 52a1e56d42..9ac3141a73 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. @@ -224,7 +224,8 @@ A link hop count is kept and refused at `link_loop_exceeded` below the limit the 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. -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 level 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. A state directory on a bind-mounted CI volume, a `~/.agent-device` symlinked to another disk, and a root container whose `sessions/` belongs to the mounted uid therefore start exactly as they did before this rule existed, and every command still works. The destination walk stays the ONLY thing that refuses a recording: it judges that same chain per publish and refuses a script under such a tree with `script_ancestor_untrusted` and its hint, so the repair skipping costs safety nothing — an unsafe destination is refused where the entry is actually created. 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. +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. A state directory on a bind-mounted CI volume, a `~/.agent-device` symlinked to another disk, and a root container whose `sessions/` belongs to the mounted uid therefore start exactly as they did before this rule existed, and every command still works. 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. A SCRIPT DOES NOT. 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 (`state_chain_untrusted`). The destination walk cannot stand in for that: it 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 the version lands outside the state tree. Skipping the repair is what opens that gap, so the same answer that stopped the repair also stops the write. A caller's `--save-script=` is unaffected: that destination is the caller's own, and the walk alone decides it. So the repair skips modes best-effort and never refuses STARTUP, while 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. @@ -238,7 +239,7 @@ The rule judges ownership bits, mode bits and link shape. Three things sit outsi - **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. +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 index 666e9c3dff..154c7d650f 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts @@ -50,13 +50,43 @@ skipOnWindows('repairs the state chain it owns, whatever mode its levels were cr // 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); - expect(ensurePrivateDaemonStateDir(remote, base)).toBe(remote); + 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. @@ -151,6 +181,44 @@ skipOnWindows('repairs above a planted link and stops below it', async () => { 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('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 diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index f811a93a6f..d796b346f9 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -287,22 +287,40 @@ export function createOwnedReplayStateDir(): OwnedReplayStateDir { * * The repair is BEST-EFFORT and never refuses (#4565): it forces the mode on a level this uid owns and * changes nothing about any other, so a state directory on a mounted volume, or one another uid left at - * 0755, still gets a daemon that starts. The destination walk is what refuses a recording under ground this - * daemon does not own. Returns the path, so a caller can name what it made without a second `mkdir`. + * 0755, still gets a daemon that starts. It answers {@link DaemonStateDir} — the path, and whether the + * chain is private ground — because a caller that WRITES under the directory needs that second answer: a + * chain the repair stopped on leads outside the state tree, and the destination rule accepts a link whose + * parent others cannot write. Startup ignores the answer; the script writer refuses on it (ADR 0016). * * `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): string { +export function ensurePrivateDaemonStateDir(directory: string, stateBase: string): DaemonStateDir { // Creation is one recursive `mkdir`: it creates the whole tail, while the repair below judges every level // it reached. Creating one level at a time would have to decide what to do when the BASE is a link, which // is the shape of a `~/.agent-device` on another disk, and refusing to create there would break a host the // operator pointed at that disk. What creation can leave on ground the chain rejects is an empty // directory, and the destination walk refuses any recording under it. fs.mkdirSync(directory, { recursive: true, mode: STATE_DIR_MODE }); - repairStateChain(stateBase, directory); - return directory; + 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 only names the directory it made — startup, or a + * tombstone written beside a session — and writes no script under it. Such a caller has nothing to refuse + * on, 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; @@ -322,28 +340,34 @@ const STATE_DIR_MODE = 0o700; * 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` above. + * + * The answer is whether the WHOLE chain reached `directory` and stands private. A caller that only forces + * modes ignores it; a caller that writes under the directory (ADR 0016) refuses, because a chain that + * stopped at a link leads to ground outside the state tree that the destination rule has no reason to reject. */ -function repairStateChain(stateBase: string, directory: string): void { +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; + 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; + return false; } for (const level of levels) { try { - if (!repairStateLevel(level)) return; + if (!repairStateLevel(level)) return false; } catch (error) { skipStateDirMode(level, (error as NodeJS.ErrnoException).code ?? 'unknown'); - return; + return false; } } + return true; } /** - * Forces one level, and reports whether the descent may go on beneath it. + * 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 @@ -369,12 +393,16 @@ function repairStateLevel(level: string): boolean { // 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; - forcePrivateStateDir(level); - return true; + return forcePrivateStateDir(level); } -/** Forces one level whose ownership passed, through a descriptor that cannot follow a link. */ -function forcePrivateStateDir(level: string): void { +/** + * 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( @@ -385,9 +413,10 @@ function forcePrivateStateDir(level: string): void { // 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; + return false; } fs.fchmodSync(descriptor, STATE_DIR_MODE); + return true; } finally { if (descriptor !== undefined) fs.closeSync(descriptor); } @@ -468,7 +497,7 @@ export function launchDaemonProcess( throw new AppError('COMMAND_FAILED', 'Replay daemon startup admission is closed.', { reason: 'daemon_startup_admission_closed', }); - ensurePrivateDaemonStateDir(input.paths.baseDir, input.paths.baseDir); + 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/core/__tests__/session-script-writer-ancestry.test.ts b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts index 347eaeeb44..453601d9d5 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -8,7 +8,12 @@ import { serveHostOwnership, } from '@agent-device/test-kit'; import { SessionScriptWriter } from '../session-script-writer.ts'; -import { makeAuthoringSession } from '../../__tests__/support/session-factories.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; @@ -41,6 +46,14 @@ function recordingTo(destination: string) { }); } +/** 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-')); } @@ -478,3 +491,96 @@ skipOnWindows('a recording creates a missing parent at 0700 on a shared umask', 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 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/session-script-publication-capability.ts b/packages/daemon/src/core/session-script-publication-capability.ts index b6418f80dc..8239c66e1e 100644 --- a/packages/daemon/src/core/session-script-publication-capability.ts +++ b/packages/daemon/src/core/session-script-publication-capability.ts @@ -310,11 +310,16 @@ 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 goes along as the failure's cause, so a client can tell a refused state chain from a full + // disk without reading prose (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 } + : {}), }, }); }; diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index 472edd1262..09d8496b7b 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -5,7 +5,10 @@ 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 { + ensurePrivateDaemonStateDir, + type DaemonStateDir, +} from '@agent-device/daemon-contracts/daemon-registration-owner'; import { inferFillText, appendScriptSeriesFlags, @@ -131,8 +134,14 @@ export class SessionScriptWriter { activePublication, }); const remote = - session.scriptPublication?.kind === 'authoring' && session.scriptPublication.remoteDelivery; - scriptPath = remote ? this.remoteScriptPath() : this.resolveScriptPath(session); + session.scriptPublication?.kind === 'authoring' && + session.scriptPublication.remoteDelivery !== undefined; + const destination = this.resolveScriptDestination(session, remote); + // A path the daemon picked for itself is written only where its own state chain is private ground. + 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 @@ -159,28 +168,63 @@ export class SessionScriptWriter { } } + /** + * 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 — a default recording under `sessions/`, + * or a remote version under `sessions/remote-scripts/` — and the daemon is the only party that knows that + * chain is its own. Ensuring a state level answers whether the chain from the state base is private + * ground; a chain that stopped at a link, a foreign level or a level it could not judge LEADS OUTSIDE the + * state tree, and the destination rule accepts a link standing in a parent others cannot write, so a + * skipped chain is refused here rather than published through. Startup keeps going either way (#4565). + */ + private resolveScriptDestination( + session: SessionState, + remote: boolean, + ): { path: string; pickedByDaemon: boolean; privateChain: boolean } { + if (remote) { + const directory = this.remoteScriptDir(); + return { + ...directory, + pickedByDaemon: true, + path: path.join(directory.path, `${crypto.randomUUID()}.ad`), + }; + } + const targetPath = scriptTargetPath(session.scriptPublication ?? NO_SCRIPT_PUBLICATION); + if (targetPath) { + return { + path: expandSessionPath(targetPath, this.hostCwd), + pickedByDaemon: false, + privateChain: true, + }; + } + const safeName = safeSessionName(session.name); + const timestamp = new Date(session.createdAt).toISOString().replaceAll(/[:.]/g, '-'); + const own = this.stateSessionsDir(); + return { + ...own, + pickedByDaemon: true, + path: path.join(own.path, `${safeName}-${timestamp}.ad`), + }; + } + /** * A remote recording's caller downloads each version once, so every version, the close-time * script included, gets a fresh file of its own in a private (0700) directory that only the daemon * user can enter. The file itself is private (0600) like every other published script, which * `publishScriptFileSync` decides. */ - private remoteScriptPath(): string { - const directory = ensurePrivateDaemonStateDir( + private remoteScriptDir(): DaemonStateDir { + return ensurePrivateDaemonStateDir( path.join(this.sessionsDir, 'remote-scripts'), path.dirname(this.sessionsDir), ); - return path.join(directory, `${crypto.randomUUID()}.ad`); } - private resolveScriptPath(session: SessionState): string { - const targetPath = scriptTargetPath(session.scriptPublication ?? NO_SCRIPT_PUBLICATION); - if (targetPath) { - return expandSessionPath(targetPath, this.hostCwd); - } - const safeName = safeSessionName(session.name); - const timestamp = new Date(session.createdAt).toISOString().replaceAll(/[:.]/g, '-'); - return path.join(this.sessionsDir, `${safeName}-${timestamp}.ad`); + /** The daemon's own `sessions/` directory, ensured the same way a remote version's directory is. */ + private stateSessionsDir(): DaemonStateDir { + return ensurePrivateDaemonStateDir(this.sessionsDir, path.dirname(this.sessionsDir)); } } @@ -254,6 +298,25 @@ function toScriptWriteFailure( ); } +/** + * Refusal for a script the daemon was about to write into its OWN state, on a chain the repair stopped on + * (ADR 0016): the chain is not private ground, so where the file would land is outside the state tree the + * daemon owns. This is not a repair failure and not a destination-rule failure — nothing was judged unsafe + * by the walk, because the walk ACCEPTS a link whose parent others cannot write. It is the daemon declining + * a path it picked for itself on ground it could not establish as its own. + */ +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 is a symbolic link, is owned by another user, or could not be judged. Point AGENT_DEVICE_STATE_DIR at a directory this user owns, or repair that level, then re-record.', + }, + ); +} + function toOrdinaryWriteFailure(error: unknown, scriptPath: string | undefined): AppError { if (error instanceof AppError) return error; return toScriptWriteFailure(error, scriptPath, { diff --git a/packages/daemon/src/core/session-store.ts b/packages/daemon/src/core/session-store.ts index 65f3950b80..3d3967fa1a 100644 --- a/packages/daemon/src/core/session-store.ts +++ b/packages/daemon/src/core/session-store.ts @@ -4,7 +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 { ensurePrivateDaemonStateDir } from '@agent-device/daemon-contracts/daemon-registration-owner'; +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'; @@ -370,10 +370,7 @@ export class SessionStore { const session = this.resolveCurrent(ref); if (!session) return; try { - ensurePrivateDaemonStateDir( - this.resolveSessionDir(ref.address), - this.resolveDaemonStateDir(), - ); + ensureDaemonStateDir(this.resolveSessionDir(ref.address), this.resolveDaemonStateDir()); const tombstone: RepairSessionTombstone = { owner: ref.address, reapedAt: Date.now(), @@ -442,10 +439,7 @@ export class SessionStore { */ writeIdleExpiryTombstone(sessionName: string, tombstone: IdleSessionTombstone): void { try { - ensurePrivateDaemonStateDir( - this.resolveSessionDir(sessionName), - this.resolveDaemonStateDir(), - ); + ensureDaemonStateDir(this.resolveSessionDir(sessionName), this.resolveDaemonStateDir()); fs.writeFileSync( resolveIdleSessionTombstonePath(this.resolveSessionDir(sessionName)), `${JSON.stringify(tombstone)}\n`, @@ -529,10 +523,7 @@ export class SessionStore { // 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 { - return ensurePrivateDaemonStateDir( - this.resolveSessionDir(sessionName), - this.resolveDaemonStateDir(), - ); + 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/http/daemon-runtime-state-dir.test.ts b/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts index b00f72c0e5..63950a13f8 100644 --- a/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts +++ b/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts @@ -97,7 +97,9 @@ test.skipIf(process.platform === 'win32')( // Nothing was taken from the owner: the directory stands as they left it. expect(modeOf(sessionsDir)).toBe(0o755); - // The refusal the host DOES get is the one that names the destination, per recording. + // 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( @@ -108,11 +110,10 @@ test.skipIf(process.platform === 'win32')( }), ), ); - expect(refusalOf(refused)).toMatchObject({ - reason: 'script_ancestor_untrusted', - exposure: 'foreign_owned', - ancestor: sessionsDir, - }); + expect(refusalOf(refused)).toMatchObject({ reason: 'state_chain_untrusted' }); + expect(String(refusalOf(refused).path).startsWith(sessionsDir + path.sep)).toBe(true); + // Nothing was written under the foreign directory. + expect(fs.readdirSync(sessionsDir)).toEqual([]); } finally { await runtime.close(); } diff --git a/packages/daemon/src/server/http/daemon-runtime.ts b/packages/daemon/src/server/http/daemon-runtime.ts index 4e482bce33..130cd98184 100644 --- a/packages/daemon/src/server/http/daemon-runtime.ts +++ b/packages/daemon/src/server/http/daemon-runtime.ts @@ -84,7 +84,7 @@ import { resolveDaemonCodeSignature, } from './server-lifecycle.ts'; import { - ensurePrivateDaemonStateDir, + ensureDaemonStateDir, tryAcquireDaemonRegistration, DAEMON_STARTUP_EXIT_CODES, type DaemonRegistrationOwner, @@ -212,8 +212,8 @@ async function startDaemonRuntimeOnHost( // 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. - ensurePrivateDaemonStateDir(baseDir, baseDir); - ensurePrivateDaemonStateDir(sessionsDir, baseDir); + 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/test-kit/src/host-ownership.fixtures.ts b/packages/test-kit/src/host-ownership.fixtures.ts index b2d95e07e0..51fe1a3ec9 100644 --- a/packages/test-kit/src/host-ownership.fixtures.ts +++ b/packages/test-kit/src/host-ownership.fixtures.ts @@ -14,15 +14,21 @@ export const FOREIGN_UID = 65534; * 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>): void { +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]; @@ -31,13 +37,19 @@ export function serveHostOwnership(owners: Readonly>): vo uid: typeof stats.uid === 'bigint' ? BigInt(uid) : uid, }) as S; }; - 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); + // `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[]) => @@ -45,4 +57,24 @@ export function serveHostOwnership(owners: Readonly>): vo 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 fbd6c01e3e..609a3c9f50 100644 --- a/packages/test-kit/src/index.ts +++ b/packages/test-kit/src/index.ts @@ -122,7 +122,11 @@ export { unavailableDeploymentSnapshotAndShutdownOperationFacts, } from './runtime-operation-facts.ts'; export { createTestRuntimeStateHandle, type TestRuntimeStateHandle } from './runtime-state.ts'; -export { FOREIGN_UID, serveHostOwnership } from './host-ownership.fixtures.ts'; +export { + FOREIGN_UID, + serveHostOwnership, + type HostOwnershipProbe, +} from './host-ownership.fixtures.ts'; export { buildNodes } from './snapshot-builders.ts'; export { bottomTabsRealCaptureFixture, From 687822affe0927dc2a6eeea276e121d52dbd3df2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 03:28:16 +0100 Subject: [PATCH 27/28] fix(daemon): carry the close refusal's reason and say who owns the state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A remote close dropped the typed reason. `remoteCloseScript` received only a boolean, so the close response's `scriptDeliveryFailure` said a version failed without saying which way it failed. The close write's AppError now travels into it, and its `details.reason` becomes the failure's `cause`, the same field the per-action route already fills. A level that disappeared before the repair reached it stopped the chain with no diagnostic: `lstat` answering `undefined` returned false silently, while every other stop reports itself. It reports now. The refusal hint names the host shape the cross-check found undocumented — a container or mounted volume that leaves the state tree to another uid — and its two fixes. The ADR and the two user docs say the same thing plainly: that host starts and answers every command, and loses only the recordings the daemon picks a path for; the refusal comes from the chain verdict, not the destination walk. State-level creation stays best-effort and happens before validation, so it can leave an empty directory beyond a rejected link, and that is stated too. Trimmed: the unchanged `prepared` value returned through `allocateStaging`, the one-use state-directory wrappers, the unused `gid` on `DirectoryAuthority`, and comments that repeated the same rule at every call site. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 4 +- ...aemon-registration-owner-state-dir.test.ts | 39 +++++++++++++ .../src/daemon-registration-owner.ts | 36 +++++------- .../session-script-publication-capability.ts | 28 +++++++-- .../daemon/src/core/session-script-writer.ts | 57 +++++++------------ .../http/daemon-runtime-state-dir.test.ts | 4 ++ .../__tests__/session-close-script.test.ts | 32 +++++++++++ .../internal/session-close-script.ts | 2 +- .../src/internal/atomic-file-ancestry.test.ts | 7 +-- .../internal/atomic-file-decisions.test.ts | 8 +-- .../src/internal/atomic-file-host.fixtures.ts | 12 ++-- packages/host-kit/src/internal/atomic-file.ts | 6 +- .../remote/src/session-script-destination.ts | 21 +++---- test/wire-compat/ledger.json | 6 +- website/docs/docs/remote-proxy.md | 7 ++- website/docs/docs/replay-e2e.md | 1 + 16 files changed, 168 insertions(+), 102 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 9ac3141a73..b8c2a487ae 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -224,8 +224,8 @@ A link hop count is kept and refused at `link_loop_exceeded` below the limit the 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. -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. A state directory on a bind-mounted CI volume, a `~/.agent-device` symlinked to another disk, and a root container whose `sessions/` belongs to the mounted uid therefore start exactly as they did before this rule existed, and every command still works. 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. A SCRIPT DOES NOT. 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 (`state_chain_untrusted`). The destination walk cannot stand in for that: it 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 the version lands outside the state tree. Skipping the repair is what opens that gap, so the same answer that stopped the repair also stops the write. A caller's `--save-script=` is unaffected: that destination is the caller's own, and the walk alone decides it. So the repair skips modes best-effort and never refuses STARTUP, while the only refusals of a RECORDING are the destination walk (a caller's path) and this chain answer (the daemon's own). +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. 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 index 154c7d650f..cc2a4d8a9a 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts @@ -219,6 +219,45 @@ skipOnWindows( }, ); +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('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 diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index d796b346f9..5506ef0afd 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -285,23 +285,18 @@ export function createOwnedReplayStateDir(): OwnedReplayStateDir { * 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): it forces the mode on a level this uid owns and - * changes nothing about any other, so a state directory on a mounted volume, or one another uid left at - * 0755, still gets a daemon that starts. It answers {@link DaemonStateDir} — the path, and whether the - * chain is private ground — because a caller that WRITES under the directory needs that second answer: a - * chain the repair stopped on leads outside the state tree, and the destination rule accepts a link whose - * parent others cannot write. Startup ignores the answer; the script writer refuses on it (ADR 0016). + * 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 { - // Creation is one recursive `mkdir`: it creates the whole tail, while the repair below judges every level - // it reached. Creating one level at a time would have to decide what to do when the BASE is a link, which - // is the shape of a `~/.agent-device` on another disk, and refusing to create there would break a host the - // operator pointed at that disk. What creation can leave on ground the chain rejects is an empty - // directory, and the destination walk refuses any recording under it. + // 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) }; } @@ -315,9 +310,8 @@ export function ensurePrivateDaemonStateDir(directory: string, stateBase: string export type DaemonStateDir = Readonly<{ path: string; privateChain: boolean }>; /** - * {@link ensurePrivateDaemonStateDir} for a caller that only names the directory it made — startup, or a - * tombstone written beside a session — and writes no script under it. Such a caller has nothing to refuse - * on, so it takes the path and leaves the verdict unread. + * {@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; @@ -339,11 +333,8 @@ const STATE_DIR_MODE = 0o700; * `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` above. - * - * The answer is whether the WHOLE chain reached `directory` and stands private. A caller that only forces - * modes ignores it; a caller that writes under the directory (ADR 0016) refuses, because a chain that - * stopped at a link leads to ground outside the state tree that the destination rule has no reason to reject. + * 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. @@ -378,8 +369,11 @@ function repairStateChain(stateBase: string, directory: string): boolean { 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 a name that does not exist. - if (judged === undefined) return false; + // 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()) { diff --git a/packages/daemon/src/core/session-script-publication-capability.ts b/packages/daemon/src/core/session-script-publication-capability.ts index 8239c66e1e..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<{ @@ -311,8 +314,7 @@ export function remoteScriptVersionDelivery( } if (!result.error) return response; // The daemon diagnostic keeps the cause; its daemon-host path stays out of the response. The typed - // reason goes along as the failure's cause, so a client can tell a refused state chain from a full - // disk without reading prose (ADR 0016). + // 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.', @@ -329,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 09d8496b7b..a37d5c0576 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -5,10 +5,7 @@ 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, - type DaemonStateDir, -} from '@agent-device/daemon-contracts/daemon-registration-owner'; +import { ensurePrivateDaemonStateDir } from '@agent-device/daemon-contracts/daemon-registration-owner'; import { inferFillText, appendScriptSeriesFlags, @@ -137,7 +134,6 @@ export class SessionScriptWriter { session.scriptPublication?.kind === 'authoring' && session.scriptPublication.remoteDelivery !== undefined; const destination = this.resolveScriptDestination(session, remote); - // A path the daemon picked for itself is written only where its own state chain is private ground. scriptPath = destination.path; if (destination.pickedByDaemon && !destination.privateChain) { throw daemonStateUntrustedFailure(destination.path); @@ -172,19 +168,21 @@ export class SessionScriptWriter { * 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 — a default recording under `sessions/`, - * or a remote version under `sessions/remote-scripts/` — and the daemon is the only party that knows that - * chain is its own. Ensuring a state level answers whether the chain from the state base is private - * ground; a chain that stopped at a link, a foreign level or a level it could not judge LEADS OUTSIDE the - * state tree, and the destination rule accepts a link standing in a parent others cannot write, so a - * skipped chain is refused here rather than published through. Startup keeps going either way (#4565). + * 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 resolveScriptDestination( session: SessionState, remote: boolean, ): { path: string; pickedByDaemon: boolean; privateChain: boolean } { + const stateBase = path.dirname(this.sessionsDir); if (remote) { - const directory = this.remoteScriptDir(); + const directory = ensurePrivateDaemonStateDir( + path.join(this.sessionsDir, 'remote-scripts'), + stateBase, + ); return { ...directory, pickedByDaemon: true, @@ -201,31 +199,13 @@ export class SessionScriptWriter { } const safeName = safeSessionName(session.name); const timestamp = new Date(session.createdAt).toISOString().replaceAll(/[:.]/g, '-'); - const own = this.stateSessionsDir(); + const own = ensurePrivateDaemonStateDir(this.sessionsDir, stateBase); return { ...own, pickedByDaemon: true, path: path.join(own.path, `${safeName}-${timestamp}.ad`), }; } - - /** - * A remote recording's caller downloads each version once, so every version, the close-time - * script included, gets a fresh file of its own in a private (0700) directory that only the daemon - * user can enter. The file itself is private (0600) like every other published script, which - * `publishScriptFileSync` decides. - */ - private remoteScriptDir(): DaemonStateDir { - return ensurePrivateDaemonStateDir( - path.join(this.sessionsDir, 'remote-scripts'), - path.dirname(this.sessionsDir), - ); - } - - /** The daemon's own `sessions/` directory, ensured the same way a remote version's directory is. */ - private stateSessionsDir(): DaemonStateDir { - return ensurePrivateDaemonStateDir(this.sessionsDir, path.dirname(this.sessionsDir)); - } } function prepareSessionScript( @@ -299,11 +279,9 @@ function toScriptWriteFailure( } /** - * Refusal for a script the daemon was about to write into its OWN state, on a chain the repair stopped on - * (ADR 0016): the chain is not private ground, so where the file would land is outside the state tree the - * daemon owns. This is not a repair failure and not a destination-rule failure — nothing was judged unsafe - * by the walk, because the walk ACCEPTS a link whose parent others cannot write. It is the daemon declining - * a path it picked for itself on ground it could not establish as its own. + * 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( @@ -312,7 +290,12 @@ function daemonStateUntrustedFailure(scriptPath: string): AppError { { reason: 'state_chain_untrusted', path: scriptPath, - hint: 'A level of the daemon state chain is a symbolic link, is owned by another user, or could not be judged. Point AGENT_DEVICE_STATE_DIR at a directory this user owns, or repair that level, then re-record.', + hint: + 'A level of the daemon state chain is a symbolic link, is owned by another user, or could not be ' + + 'judged, so the daemon cannot call it private ground. This is the shape of a bind-mounted CI volume ' + + 'or a container image that leaves the state directory to another uid. 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.', }, ); } 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 index 63950a13f8..2668437912 100644 --- a/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts +++ b/packages/daemon/src/server/http/daemon-runtime-state-dir.test.ts @@ -112,6 +112,10 @@ test.skipIf(process.platform === 'win32')( ); 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 { 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 dfae250f43..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,6 +14,7 @@ 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'; @@ -92,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', { 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/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index 8d6b0da2fc..a012bf5025 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -5,7 +5,6 @@ import { AppError } from '@agent-device/kernel/errors'; import { FOREIGN_UID, ancestryRoot as root, - currentGid, directoryWith, expectUntrusted, expectUntrustedReplaced, @@ -95,7 +94,7 @@ skipOnWindows('refuses a destination created inside a directory others can add e }); skipOnWindows('refuses a destination under a group-writable shared directory', () => { - const team = directoryWith(path.join(root(), 'team'), 0o775, currentGid); + const team = directoryWith(path.join(root(), 'team'), 0o775); const sub = path.join(team, 'sub'); fs.mkdirSync(sub); @@ -558,7 +557,7 @@ skipOnWindows('refuses a group-writable 0775 directory with the hint to close th // 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, currentGid); + const home = directoryWith(path.join(root(), 'home'), 0o775); let hint = ''; try { publish(path.join(home, 'journey.ad')); @@ -573,7 +572,7 @@ skipOnWindows('refuses a group-writable 0775 directory with the hint to close th 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, currentGid); + const home = directoryWith(path.join(root(), 'home'), 0o2775); expectUntrusted(() => publish(path.join(home, 'journey.ad')), 'shared_group_writable', home); }); diff --git a/packages/host-kit/src/internal/atomic-file-decisions.test.ts b/packages/host-kit/src/internal/atomic-file-decisions.test.ts index 7e73dd2f2f..374674b352 100644 --- a/packages/host-kit/src/internal/atomic-file-decisions.test.ts +++ b/packages/host-kit/src/internal/atomic-file-decisions.test.ts @@ -12,11 +12,10 @@ import { } from './atomic-file.ts'; const currentUid = process.getuid?.() ?? -1; -const currentGid = process.getgid?.() ?? -1; // --- what makes one directory unsafe to publish inside --- -const OWN = { uid: currentUid, gid: currentGid, mode: 0o755 }; +const OWN = { uid: currentUid, mode: 0o755 }; const TRUST = { uid: currentUid }; function directoryOf(overrides: Partial): DirectoryAuthority { @@ -39,10 +38,7 @@ test('refuses a directory that is 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, so `gid` does not enter the answer. - expect(untrustedAncestryExposure(directoryOf({ gid: 4321, mode: 0o775 }), TRUST)).toBe( - 'shared_group_writable', - ); + // 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', ); diff --git a/packages/host-kit/src/internal/atomic-file-host.fixtures.ts b/packages/host-kit/src/internal/atomic-file-host.fixtures.ts index 7f0fd17833..a3e98a3a5b 100644 --- a/packages/host-kit/src/internal/atomic-file-host.fixtures.ts +++ b/packages/host-kit/src/internal/atomic-file-host.fixtures.ts @@ -8,9 +8,9 @@ import { AppError } from '@agent-device/kernel/errors'; import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; import { publishScriptFileSync } from './atomic-file.ts'; -/** This process's ids. Windows has neither, and every test that uses them is skipped there. */ +/** This process's uid. Windows has none, and every test that uses it is skipped there. */ export const currentUid = process.getuid?.() ?? -1; -export const currentGid = process.getgid?.() ?? -1; +const currentGid = process.getgid?.() ?? -1; /** Some other local user, not this one and not root. */ export const FOREIGN_UID = 65534; @@ -21,12 +21,12 @@ export function ancestryRoot(): string { } /** - * A directory carrying `mode` and `gid`, so the rule reads the group the test chose. The group is set - * explicitly because a scratch directory inherits one from its parent, not necessarily this user's. + * 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, gid = currentGid): string { +export function directoryWith(directory: string, mode: number): string { fs.mkdirSync(directory); - fs.chownSync(directory, currentUid, gid); + fs.chownSync(directory, currentUid, currentGid); fs.chmodSync(directory, mode); return directory; } diff --git a/packages/host-kit/src/internal/atomic-file.ts b/packages/host-kit/src/internal/atomic-file.ts index 68ac011ffd..c14aaa421a 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -521,9 +521,9 @@ function standOn( }; } -/** The fields this rule reads off one `lstat` answer: owner, group and mode of the ENTRY. */ +/** 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), gid: Number(stats.gid), mode: Number(stats.mode) }; + return { uid: Number(stats.uid), mode: Number(stats.mode) }; } /** @@ -657,7 +657,7 @@ function scriptTrust(): ScriptDestinationTrust { } /** The fields of a directory the ancestry rule reads, so the decision is testable without a filesystem. */ -export type DirectoryAuthority = Readonly<{ uid: number; gid: number; mode: number }>; +export type DirectoryAuthority = Readonly<{ uid: number; mode: number }>; /** The fields of a symbolic link the ancestry rule reads. */ export type LinkAuthority = Readonly<{ uid: number }>; diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index cd7c628fe1..fce74da2ab 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -207,9 +207,9 @@ async function publishScriptVersion( // 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?.staging; - if (!staging || !allocated) return { published: undefined }; - const staged = path.join(staging, 'script.ad'); + staging = allocated; + if (!allocated) return { published: undefined }; + const staged = path.join(allocated, 'script.ad'); await context.download({ ...endpoint, artifactId: artifactId as string, @@ -219,10 +219,10 @@ async function publishScriptVersion( }); const version = { revision: revision as number, - staging, + staging: allocated, staged, - // What host-kit answered when staging was allocated, for the one confirmation before the rename. - prepared: allocated.prepared, + // What host-kit answered above, carried for the one confirmation before the rename. + prepared, pending, }; return { published: await withRecordLock(file, async () => publishStaged(file, version)) }; @@ -243,16 +243,13 @@ async function publishScriptVersion( /** * Creates a staging directory beside the destination and lists it in the record before any script bytes - * reach it, and reports the prepared destination the publish confirms before its rename. + * 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, -): { staging: string; prepared: ScriptDestination } | undefined { +function allocateStaging(file: string, prepared: ScriptDestination): string | undefined { const record = readRecord(file); if (!record) return undefined; const staging = fs.mkdtempSync(path.join(prepared.directory, '.agent-device-script-')); @@ -262,7 +259,7 @@ function allocateStaging( fs.rmSync(staging, { recursive: true, force: true }); throw error; } - return { staging, prepared }; + return staging; } /** diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 70117dd98e..c0ab8688d6 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -214,7 +214,7 @@ "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:28fe42532406633c86578f468b2ccc5c7fa43764fd62cfec35975678ff080e66", + "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" @@ -222,8 +222,8 @@ "compatibleChanges": [ { "declaration": "packages/remote/src/session-script-destination.ts#publishScriptVersion", - "digest": "sha256:28fe42532406633c86578f468b2ccc5c7fa43764fd62cfec35975678ff080e66", - "rationale": "#4565 changes only how the caller resolves 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. 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." + "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", diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 7eabfc7c00..8867004466 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -124,7 +124,12 @@ 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, for example one whose +state tree a container or a mounted volume left to another uid, refuses every version it picks a +path for with `state_chain_untrusted`. That daemon still starts and answers every other command, and +the fix is on the daemon host: make its user own the state directory, or point +`AGENT_DEVICE_STATE_DIR` at a directory it owns. 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 379c756e25..0ec09bba4c 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -78,6 +78,7 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow - 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 does not own the daemon's state directory, because a container or a mounted volume left it to another uid, 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, or point `AGENT_DEVICE_STATE_DIR` at a directory it owns. - 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. From 208b3802463cee4455ac7baa3afc1ca83064e269 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 04:33:01 +0100 Subject: [PATCH 28/28] fix(daemon): judge the ancestry above the state base before repairing it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The state repair walked DOWN from the state base and never questioned the ground the base stands on. A local user who can write an ancestor above it can rename the base and leave a link at its name between two of the repair's calls; every level below then resolves on ground nothing judged, and a root daemon forces a mode there and reports the chain private. The reviewer reproduced an outside directory going 0755 to 0700 while the call answered `privateChain: true`. `untrustedDirectoryAncestry` in host-kit asks the destination walk what a name inside a directory would resolve by, and creates nothing. The repair calls it on the base's PARENT before touching any level: the ancestry above the base is what is judged, so a `sessions/` left at 0775 by umask 002 is still repaired rather than refused. Where that rule refuses — a shared non-sticky ancestor, a foreign one, a chain it cannot resolve — nothing below is touched, one `daemon_state_mode_repair_skipped` names the ancestor and its exposure, the chain answers not private, and startup goes ahead. The refusal hint and the two user docs name that host shape, and say state creation is best-effort and runs before validation, so it can leave an empty directory beyond a rejected link. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 1 + ...aemon-registration-owner-state-dir.test.ts | 123 ++++++++++++++++++ .../src/daemon-registration-owner.ts | 23 ++++ .../session-script-writer-ancestry.test.ts | 24 ++++ .../daemon/src/core/session-script-writer.ts | 11 +- packages/host-kit/src/file.ts | 1 + .../src/internal/atomic-file-ancestry.test.ts | 69 ++++++++++ packages/host-kit/src/internal/atomic-file.ts | 54 +++++++- website/docs/docs/remote-proxy.md | 14 +- website/docs/docs/replay-e2e.md | 3 +- 10 files changed, 311 insertions(+), 12 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index b8c2a487ae..cfad7ef9df 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -223,6 +223,7 @@ The walk ANSWERS with the physical directory the entry is created in, and that a 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). 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 index cc2a4d8a9a..ffedb313a2 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner-state-dir.test.ts @@ -258,6 +258,129 @@ skipOnWindows('reports the level that disappeared before the repair reached it', 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 diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index 5506ef0afd..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'; @@ -329,6 +330,13 @@ const STATE_DIR_MODE = 0o700; * 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, @@ -345,6 +353,7 @@ function repairStateChain(stateBase: string, directory: string): boolean { skipStateDirMode(directory, 'not_below_state_base'); return false; } + if (!stateAncestryIsTrusted(stateBase)) return false; for (const level of levels) { try { if (!repairStateLevel(level)) return false; @@ -356,6 +365,20 @@ function repairStateChain(stateBase: string, directory: string): boolean { 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. 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 index 453601d9d5..e5bb1dd42a 100644 --- a/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts +++ b/packages/daemon/src/core/__tests__/session-script-writer-ancestry.test.ts @@ -522,6 +522,30 @@ skipOnWindows.each(['sessions', 'remote-scripts'] as const)( }, ); +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. diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index a37d5c0576..de56f2707b 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -291,11 +291,12 @@ function daemonStateUntrustedFailure(scriptPath: string): AppError { reason: 'state_chain_untrusted', path: scriptPath, hint: - 'A level of the daemon state chain is a symbolic link, is owned by another user, or could not be ' + - 'judged, so the daemon cannot call it private ground. This is the shape of a bind-mounted CI volume ' + - 'or a container image that leaves the state directory to another uid. 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.', + '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.', }, ); } diff --git a/packages/host-kit/src/file.ts b/packages/host-kit/src/file.ts index 1baf896441..7bdba1f70f 100644 --- a/packages/host-kit/src/file.ts +++ b/packages/host-kit/src/file.ts @@ -7,6 +7,7 @@ export { publishDurableFileSync, publishFileSync, publishScriptFileSync, + untrustedDirectoryAncestry, type DurableFilePublishMode, type ScriptDestination, } from './internal/atomic-file.ts'; diff --git a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts index a012bf5025..2e8bc249fd 100644 --- a/packages/host-kit/src/internal/atomic-file-ancestry.test.ts +++ b/packages/host-kit/src/internal/atomic-file-ancestry.test.ts @@ -14,6 +14,7 @@ import { import { confirmScriptDestination, prepareScriptDestination, + untrustedDirectoryAncestry, MAX_SCRIPT_PATH_LINK_HOPS, } from './atomic-file.ts'; import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; @@ -806,3 +807,71 @@ skipOnWindows( 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.ts b/packages/host-kit/src/internal/atomic-file.ts index c14aaa421a..509994c272 100644 --- a/packages/host-kit/src/internal/atomic-file.ts +++ b/packages/host-kit/src/internal/atomic-file.ts @@ -426,7 +426,57 @@ type WalkOutcome = /** Whether a `..` is queued behind that name, so creating cannot resolve the chain. */ unresolvable: boolean; }> - | Readonly<{ ended: 'refused'; reject: AppError }>; + | 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 @@ -463,6 +513,8 @@ function walkSpelledParent( if (step.kind === 'reject') { return { ended: 'refused', + ancestor: step.path, + exposure: step.exposure, reject: scriptAncestryFailure(destination, step.path, step.exposure), }; } diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 8867004466..218f8b5521 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -125,11 +125,15 @@ action or `close` delivers the full recording again. If `close` cannot deliver t 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. Its `cause` -names why: a daemon that cannot call its own state directory private ground, for example one whose -state tree a container or a mounted volume left to another uid, refuses every version it picks a -path for with `state_chain_untrusted`. That daemon still starts and answers every other command, and -the fix is on the daemon host: make its user own the state directory, or point -`AGENT_DEVICE_STATE_DIR` at a directory it owns. +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 0ec09bba4c..3c79067745 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -78,7 +78,8 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow - 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 does not own the daemon's state directory, because a container or a mounted volume left it to another uid, 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, or point `AGENT_DEVICE_STATE_DIR` at a directory it owns. +- 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.