docks-kit 0.20.10 → 0.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +8 -2
- package/README.md +15 -8
- package/cli/docs/command-guards.md +20 -5
- package/cli/docs/flags.md +11 -0
- package/cli/src/argv.ts +4 -0
- package/cli/src/commands/omp.ts +2 -1
- package/cli/src/commands/scratch.ts +75 -0
- package/cli/src/commands/tidy.ts +91 -0
- package/cli/src/engine-native/ompKitPlugin.ts +94 -0
- package/cli/src/engine-native/ompPlugins.ts +41 -8
- package/cli/src/engine-native/ompSync.ts +7 -4
- package/cli/src/engine-native/scratch.ts +188 -0
- package/cli/src/engine-native/tidy.ts +1296 -0
- package/cli/src/engine-native/tidyLock.ts +138 -0
- package/cli/src/engine-native/tidyReport.ts +509 -0
- package/cli/src/generated/sotPayload.ts +13 -5
- package/cli/src/main.ts +6 -0
- package/cli/tsconfig.json +1 -1
- package/package.json +2 -2
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Agent temporary directories. `createScratchDir` makes a private directory
|
|
3
|
+
* under the kit scratch root. `removeTemporaryPath` removes a path only when it
|
|
4
|
+
* is strictly inside an allowed root and no other user can change a directory
|
|
5
|
+
* on its path, so a deny-listed `rm -r` is never needed for cleanup and the
|
|
6
|
+
* home directory and `/` can never be the target.
|
|
7
|
+
*/
|
|
8
|
+
import {
|
|
9
|
+
chmodSync,
|
|
10
|
+
lstatSync,
|
|
11
|
+
mkdirSync,
|
|
12
|
+
mkdtempSync,
|
|
13
|
+
realpathSync,
|
|
14
|
+
rmSync,
|
|
15
|
+
statSync,
|
|
16
|
+
} from "node:fs";
|
|
17
|
+
import { dirname, isAbsolute, join, relative } from "node:path";
|
|
18
|
+
|
|
19
|
+
import { p } from "./exec";
|
|
20
|
+
|
|
21
|
+
const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
22
|
+
|
|
23
|
+
export function kitCacheDir(home: string): string {
|
|
24
|
+
return p(home, ".cache", "docks-kit");
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function scratchRoot(home: string): string {
|
|
28
|
+
return p(kitCacheDir(home), "scratch");
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function createScratchDir(root: string, label: string): string {
|
|
32
|
+
if (!LABEL_PATTERN.test(label)) {
|
|
33
|
+
throw new Error("label must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$");
|
|
34
|
+
}
|
|
35
|
+
mkdirSync(root, { recursive: true, mode: 0o700 });
|
|
36
|
+
chmodSync(root, 0o700);
|
|
37
|
+
const directory = mkdtempSync(join(root, `${label}-`));
|
|
38
|
+
chmodSync(directory, 0o700);
|
|
39
|
+
return realpathSync(directory);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** True when `child` is `parent` itself or lies below it. */
|
|
43
|
+
export function isSameOrInside(parent: string, child: string): boolean {
|
|
44
|
+
const path = relative(parent, child);
|
|
45
|
+
return path === "" || (!path.startsWith("..") && !isAbsolute(path));
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** True when `child` lies strictly below `parent`. */
|
|
49
|
+
export function isStrictlyInside(parent: string, child: string): boolean {
|
|
50
|
+
const path = relative(parent, child);
|
|
51
|
+
return path !== "" && !path.startsWith("..") && !isAbsolute(path);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function realpathOrUndefined(path: string): string | undefined {
|
|
55
|
+
try {
|
|
56
|
+
return realpathSync(path);
|
|
57
|
+
} catch {
|
|
58
|
+
return undefined;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const STICKY = 0o1000;
|
|
63
|
+
const GROUP_OR_OTHER_WRITE = 0o022;
|
|
64
|
+
|
|
65
|
+
/** The user and root may own a directory on a trusted path. */
|
|
66
|
+
function isTrustedOwner(uid: number, user: number): boolean {
|
|
67
|
+
return uid === user || uid === 0;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* The first directory from the filesystem root down to the parent of `path`
|
|
72
|
+
* that another user can change, or `undefined`. The user or root must own each
|
|
73
|
+
* directory, and group and others must not write it, except a sticky directory
|
|
74
|
+
* whose next entry on the path the user or root owns: POSIX lets only that
|
|
75
|
+
* entry's owner, the directory owner, or root rename such an entry.
|
|
76
|
+
*/
|
|
77
|
+
function untrustedParent(path: string, user: number): string | undefined {
|
|
78
|
+
const chain = [path];
|
|
79
|
+
for (let parent = dirname(path); parent !== chain[0]; parent = dirname(parent)) {
|
|
80
|
+
chain.unshift(parent);
|
|
81
|
+
}
|
|
82
|
+
for (let index = 0; index < chain.length - 1; index++) {
|
|
83
|
+
const directory = lstatSync(chain[index]);
|
|
84
|
+
if (!directory.isDirectory() || !isTrustedOwner(directory.uid, user)) return chain[index];
|
|
85
|
+
if ((directory.mode & GROUP_OR_OTHER_WRITE) === 0) continue;
|
|
86
|
+
const sticky = (directory.mode & STICKY) !== 0;
|
|
87
|
+
if (!sticky || !isTrustedOwner(lstatSync(chain[index + 1]).uid, user)) return chain[index];
|
|
88
|
+
}
|
|
89
|
+
return undefined;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* True when no other user can replace or change `root`: its path is trusted,
|
|
94
|
+
* the user or root owns it, and others cannot write it unless it is sticky.
|
|
95
|
+
* Windows has no POSIX owner bits, so every root passes there.
|
|
96
|
+
*/
|
|
97
|
+
function isTrustedRoot(root: string): boolean {
|
|
98
|
+
if (process.getuid === undefined) return true;
|
|
99
|
+
const user = process.getuid();
|
|
100
|
+
const stats = lstatSync(root);
|
|
101
|
+
if (!isTrustedOwner(stats.uid, user)) return false;
|
|
102
|
+
if ((stats.mode & GROUP_OR_OTHER_WRITE) !== 0 && (stats.mode & STICKY) === 0) return false;
|
|
103
|
+
return untrustedParent(root, user) === undefined;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
export function allowedRemovalRoots(input: {
|
|
107
|
+
readonly home: string;
|
|
108
|
+
readonly scratch: string;
|
|
109
|
+
readonly tmp: string;
|
|
110
|
+
readonly platform: NodeJS.Platform;
|
|
111
|
+
}): ReadonlyArray<string> {
|
|
112
|
+
const candidates = [input.scratch, input.tmp];
|
|
113
|
+
if (input.platform !== "win32") candidates.push("/tmp", "/var/tmp");
|
|
114
|
+
const home = realpathOrUndefined(input.home) ?? input.home;
|
|
115
|
+
const roots: Array<string> = [];
|
|
116
|
+
for (const candidate of candidates) {
|
|
117
|
+
const root = realpathOrUndefined(candidate);
|
|
118
|
+
if (root === undefined || roots.includes(root)) continue;
|
|
119
|
+
if (dirname(root) === root || isSameOrInside(root, home)) continue;
|
|
120
|
+
if (!isTrustedRoot(root)) continue;
|
|
121
|
+
roots.push(root);
|
|
122
|
+
}
|
|
123
|
+
return roots;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export type RemovalOutcome =
|
|
127
|
+
| { readonly kind: "removed"; readonly path: string }
|
|
128
|
+
| { readonly kind: "refused"; readonly path: string; readonly reason: string };
|
|
129
|
+
|
|
130
|
+
function errorCode(cause: unknown): string | undefined {
|
|
131
|
+
return cause instanceof Error && "code" in cause && typeof cause.code === "string"
|
|
132
|
+
? cause.code
|
|
133
|
+
: undefined;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
function errorMessage(cause: unknown): string {
|
|
137
|
+
return cause instanceof Error ? cause.message : String(cause);
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* Remove `operand` when every check passes, in this order: it exists, it is
|
|
142
|
+
* not a symbolic link (also with trailing separators), its real path is
|
|
143
|
+
* strictly inside one root and is no root itself, it does not contain the home
|
|
144
|
+
* directory, the current user owns it, no other user can change a directory on
|
|
145
|
+
* its path, and it is on the same filesystem as its root. The first failed
|
|
146
|
+
* check refuses and deletes nothing.
|
|
147
|
+
*/
|
|
148
|
+
export function removeTemporaryPath(
|
|
149
|
+
operand: string,
|
|
150
|
+
roots: ReadonlyArray<string>,
|
|
151
|
+
home: string,
|
|
152
|
+
): RemovalOutcome {
|
|
153
|
+
const refuse = (reason: string): RemovalOutcome => ({ kind: "refused", path: operand, reason });
|
|
154
|
+
// `lstat` of `link/` follows the link, so check the entry without trailing separators.
|
|
155
|
+
const trailing = process.platform === "win32" ? /[\\/]+$/ : /\/+$/;
|
|
156
|
+
const entry = operand.replace(trailing, "") || operand;
|
|
157
|
+
try {
|
|
158
|
+
if (lstatSync(entry).isSymbolicLink()) return refuse("is a symbolic link");
|
|
159
|
+
} catch (cause) {
|
|
160
|
+
return errorCode(cause) === "ENOENT" ? refuse("does not exist") : refuse(errorMessage(cause));
|
|
161
|
+
}
|
|
162
|
+
try {
|
|
163
|
+
const target = realpathSync(entry);
|
|
164
|
+
const root = roots.includes(target)
|
|
165
|
+
? undefined
|
|
166
|
+
: roots.find((candidate) => isStrictlyInside(candidate, target));
|
|
167
|
+
if (root === undefined) {
|
|
168
|
+
return refuse("is outside the scratch root, the system temporary directory, and /var/tmp");
|
|
169
|
+
}
|
|
170
|
+
if (isSameOrInside(target, realpathOrUndefined(home) ?? home)) {
|
|
171
|
+
return refuse("contains the home directory");
|
|
172
|
+
}
|
|
173
|
+
const stats = statSync(target);
|
|
174
|
+
if (process.getuid !== undefined) {
|
|
175
|
+
const user = process.getuid();
|
|
176
|
+
if (stats.uid !== user) return refuse("is owned by another user");
|
|
177
|
+
const parent = untrustedParent(target, user);
|
|
178
|
+
if (parent !== undefined) {
|
|
179
|
+
return refuse(`has a parent directory that another user can change: ${parent}`);
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
if (stats.dev !== statSync(root).dev) return refuse("is on another filesystem");
|
|
183
|
+
rmSync(target, { recursive: true, force: false });
|
|
184
|
+
return { kind: "removed", path: target };
|
|
185
|
+
} catch (cause) {
|
|
186
|
+
return refuse(errorMessage(cause));
|
|
187
|
+
}
|
|
188
|
+
}
|