code-guardian-ai 0.0.0-stage → 0.3.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/.env.example +24 -0
- package/LICENSE +21 -0
- package/README.md +774 -2
- package/bin/cli.js +2 -0
- package/dist/build-manifest.json +136 -0
- package/dist/cli/commands/check.js +56 -0
- package/dist/cli/commands/doctor.js +55 -0
- package/dist/cli/commands/find.js +31 -0
- package/dist/cli/commands/init-files.js +13 -0
- package/dist/cli/commands/init.js +50 -0
- package/dist/cli/commands/optimize.js +53 -0
- package/dist/cli/commands/scan.js +47 -0
- package/dist/cli/index.js +62 -0
- package/dist/cli/output.js +4 -0
- package/dist/context.js +11 -0
- package/dist/core/ast/analysis.js +455 -0
- package/dist/core/ast/cached-info.js +46 -0
- package/dist/core/ast/discovery.js +485 -0
- package/dist/core/ast/extract-js.js +531 -0
- package/dist/core/ast/extract-py.js +298 -0
- package/dist/core/ast/graph.js +92 -0
- package/dist/core/ast/health.js +338 -0
- package/dist/core/ast/indexer.js +286 -0
- package/dist/core/ast/packages.js +343 -0
- package/dist/core/ast/parser.js +91 -0
- package/dist/core/ast/report.js +154 -0
- package/dist/core/ast/resolver.js +392 -0
- package/dist/core/ast/rules.js +37 -0
- package/dist/core/ast/scope-js.js +191 -0
- package/dist/core/ast/shared-index.js +131 -0
- package/dist/core/ast/tsconfig.js +301 -0
- package/dist/core/ast/types.js +1 -0
- package/dist/core/ast/util.js +156 -0
- package/dist/core/git/git.js +430 -0
- package/dist/core/llm/policy.js +35 -0
- package/dist/core/llm/provider.js +199 -0
- package/dist/core/prompt/compressor.js +118 -0
- package/dist/core/prompt/criteria.js +36 -0
- package/dist/core/prompt/find.js +47 -0
- package/dist/core/prompt/guidelines.js +22 -0
- package/dist/core/prompt/model-output.js +178 -0
- package/dist/core/prompt/refiner.js +194 -0
- package/dist/core/prompt/relevance.js +265 -0
- package/dist/core/prompt/untrusted.js +57 -0
- package/dist/core/security/masker.js +330 -0
- package/dist/core/security/outbound.js +40 -0
- package/dist/core/security/safe-file.js +396 -0
- package/dist/core/security/sandbox.js +181 -0
- package/dist/core/validation/baseline.js +121 -0
- package/dist/core/validation/delta.js +243 -0
- package/dist/core/validation/policy.js +123 -0
- package/dist/db/cache-key.js +221 -0
- package/dist/db/client.js +563 -0
- package/dist/db/schema-check.js +149 -0
- package/dist/db/schema.js +36 -0
- package/dist/db/windows-acl.js +150 -0
- package/dist/index.js +55 -0
- package/dist/mcp/server.js +20 -0
- package/dist/mcp/tools/find-reusable.js +22 -0
- package/dist/mcp/tools/get-context.js +39 -0
- package/dist/mcp/tools/optimize-prompt.js +31 -0
- package/dist/mcp/tools/result.js +31 -0
- package/dist/mcp/tools/validate-rules.js +28 -0
- package/dist/utils/config.js +117 -0
- package/dist/utils/errors.js +9 -0
- package/dist/utils/logger.js +19 -0
- package/dist/utils/pace.js +19 -0
- package/dist/utils/text.js +22 -0
- package/dist/utils/tokens.js +14 -0
- package/package.json +69 -4
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { InputError } from '../../utils/errors.js';
|
|
2
|
+
import { findUnverifiable, maskSecrets } from './masker.js';
|
|
3
|
+
export class OutboundBlocked extends InputError {
|
|
4
|
+
constructor(message) {
|
|
5
|
+
super(message, 'outbound_blocked');
|
|
6
|
+
}
|
|
7
|
+
}
|
|
8
|
+
const describe = (items) => items.map((u) => `${u.count} ${u.kind.replace(/-/g, ' ')}`).join(', ');
|
|
9
|
+
export function strictFromEnv(configured) {
|
|
10
|
+
const raw = process.env.GUARDIAN_STRICT?.trim().toLowerCase();
|
|
11
|
+
if (raw === undefined || raw === '')
|
|
12
|
+
return configured;
|
|
13
|
+
return ['1', 'on', 'true', 'yes'].includes(raw);
|
|
14
|
+
}
|
|
15
|
+
// The only way text reaches an external provider. Both halves are masked as one unit right before sending,
|
|
16
|
+
// then re-scanned: if anything still looks like a secret the payload is refused rather than sent.
|
|
17
|
+
// In strict mode the payload is also refused when it holds content the masker cannot vouch for (key-like
|
|
18
|
+
// high-entropy strings, encoded blobs, binary data, or more text than it scans), so a miss fails closed.
|
|
19
|
+
export function prepareOutbound(system, prompt, options = {}) {
|
|
20
|
+
// Any failure while masking or re-checking blocks the send. Nothing is ever sent on the strength of a masking step that did not finish.
|
|
21
|
+
let maskedSystem;
|
|
22
|
+
let maskedPrompt;
|
|
23
|
+
try {
|
|
24
|
+
maskedSystem = maskSecrets(system);
|
|
25
|
+
maskedPrompt = maskSecrets(prompt);
|
|
26
|
+
if (maskSecrets(maskedSystem.text).count > 0 || maskSecrets(maskedPrompt.text).count > 0) {
|
|
27
|
+
throw new OutboundBlocked('Outbound payload failed secret verification and was not sent');
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
catch (err) {
|
|
31
|
+
if (err instanceof OutboundBlocked)
|
|
32
|
+
throw err;
|
|
33
|
+
throw new OutboundBlocked('Masking the outbound payload failed, so nothing was sent');
|
|
34
|
+
}
|
|
35
|
+
const unverifiable = [...findUnverifiable(maskedSystem.text), ...findUnverifiable(maskedPrompt.text)];
|
|
36
|
+
if (options.strict && unverifiable.length > 0) {
|
|
37
|
+
throw new OutboundBlocked(`Strict mode: the outbound payload contains content that could not be verified as free of secrets (${describe(unverifiable)}), so nothing was sent`);
|
|
38
|
+
}
|
|
39
|
+
return { system: maskedSystem.text, prompt: maskedPrompt.text, redactions: maskedSystem.count + maskedPrompt.count, unverifiable };
|
|
40
|
+
}
|
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { InputError, errorCode } from '../../utils/errors.js';
|
|
4
|
+
// Writes to files directly inside a directory we own (the workspace root or .guardian/) must never be steered
|
|
5
|
+
// elsewhere by a symlink, a dangling symlink, a device or a FIFO that a hostile repository planted there.
|
|
6
|
+
// Node has no openat2/RESOLVE_BENEATH, so each write combines three checks: refuse links up front (works where
|
|
7
|
+
// O_NOFOLLOW does not exist), open with O_NOFOLLOW (+ O_EXCL when creating, which never follows a link, dangling or
|
|
8
|
+
// not), then confirm the descriptor we hold is still the file the path names before a single byte is written.
|
|
9
|
+
//
|
|
10
|
+
// Windows is the exception to the open step. There O_NOFOLLOW is 0 and O_CREAT|O_EXCL *follows* a dangling symlink and
|
|
11
|
+
// creates its target, so createFileExclusive never opens the destination on Windows. It creates the file in a private
|
|
12
|
+
// staging directory next to the destination (same volume) and publishes it with fs.linkSync, which fails with EEXIST
|
|
13
|
+
// for any existing entry, a dangling symlink included, and so can neither overwrite nor follow anything. If hard links
|
|
14
|
+
// are unavailable it fails closed (UnsafeFileError); it never falls back to O_EXCL.
|
|
15
|
+
//
|
|
16
|
+
// What this cannot guarantee (Node exposes no openat/unlinkat/O_DIRECTORY handles, so the directory cannot be pinned):
|
|
17
|
+
// - The checks are before-and-after comparisons, not atomic. A directory or file swapped in the instant after the
|
|
18
|
+
// last check, or swapped and restored between two checks, is not detected. Nothing is written to a path that has
|
|
19
|
+
// already been seen to change, but a swap in the final instruction window cannot be ruled out.
|
|
20
|
+
// - Directory identity is the (dev, ino) pair of the directory plus its realpath. On a file system that reports
|
|
21
|
+
// ino 0 or reuses numbers (some network and FUSE mounts, FAT-family volumes) two directories can look identical.
|
|
22
|
+
// - Hard-link publication (Windows) is still path based: linkSync takes two paths. The directory is verified (realpath,
|
|
23
|
+
// dev/ino) and the staged file is re-checked immediately before the link and the result is verified immediately
|
|
24
|
+
// after, but a swap in the instant between the last check and linkSync is not excluded; it is detected afterwards and
|
|
25
|
+
// the file this call created is removed. If the directory is renamed away between staging and publication, the
|
|
26
|
+
// staging directory goes with it, cannot be reached by path and is left behind inside the moved directory while
|
|
27
|
+
// nothing is created at the destination. If removing the staged name or directory fails (a handle held by an
|
|
28
|
+
// antivirus or indexer, say) an empty `.guardian-stage-*` directory can remain; the link-count check then fails
|
|
29
|
+
// the creation closed. Hard links need NTFS or ReFS: FAT, exFAT and some network shares refuse them and creation
|
|
30
|
+
// fails with an UnsafeFileError there. A file exists at the destination, empty, between publication and the write,
|
|
31
|
+
// exactly as with the exclusive open. Whether an open handle inside a directory stops it being renamed on Windows
|
|
32
|
+
// is a sharing-mode behaviour this code does not rely on.
|
|
33
|
+
// - When a created file has to be discarded the unlink goes by path after an identity check, so a swap in the gap
|
|
34
|
+
// between that check and the unlink could remove the wrong entry. The file is only removed if it is verified to be
|
|
35
|
+
// the one this call created, and a failure to remove it is not reported as success.
|
|
36
|
+
export class UnsafeFileError extends InputError {
|
|
37
|
+
constructor(message) {
|
|
38
|
+
super(message, 'unsafe_file');
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
|
|
42
|
+
const NONBLOCK = fs.constants.O_NONBLOCK ?? 0;
|
|
43
|
+
// A file with more than one directory entry can be changed through any of them: appending to a hard-linked .gitignore
|
|
44
|
+
// or opening a hard-linked cache.db edits the other path too, and no symlink check notices. The link count comes from
|
|
45
|
+
// lstat/fstat on every platform Node supports (NTFS and ReFS included, where libuv reads the real count), so the
|
|
46
|
+
// same check serves Windows and Unix. File systems that cannot hold hard links (FAT, exFAT) always report 1, and
|
|
47
|
+
// a file system that misreports the count cannot be detected from here.
|
|
48
|
+
export function isHardLinked(stat) {
|
|
49
|
+
return BigInt(stat.nlink) > 1n;
|
|
50
|
+
}
|
|
51
|
+
export function hardLinkMessage(name) {
|
|
52
|
+
return `${name} has more than one hard link`;
|
|
53
|
+
}
|
|
54
|
+
function target(dir, name) {
|
|
55
|
+
if (name.length === 0 || name === '.' || name === '..' || path.basename(name) !== name || name.includes('\0') || name.includes('\\')) {
|
|
56
|
+
throw new UnsafeFileError(`Unsafe file name: ${name}`);
|
|
57
|
+
}
|
|
58
|
+
return { file: path.join(dir, name), name, realDir: realDirectory(dir, name), dirId: directoryIdentity(dir, name) };
|
|
59
|
+
}
|
|
60
|
+
function realDirectory(dir, name) {
|
|
61
|
+
try {
|
|
62
|
+
return fs.realpathSync.native(dir);
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
throw new UnsafeFileError(`Cannot resolve the directory that holds ${name}`);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
// dev/ino of the directory itself. realpath alone cannot tell a directory from a different one later created at the
|
|
69
|
+
// same path (rename away, mkdir again): the string is identical, the identity is not.
|
|
70
|
+
function directoryIdentity(dir, name) {
|
|
71
|
+
try {
|
|
72
|
+
const stat = fs.statSync(dir, { bigint: true });
|
|
73
|
+
if (stat.isDirectory())
|
|
74
|
+
return { dev: stat.dev, ino: stat.ino };
|
|
75
|
+
}
|
|
76
|
+
catch {
|
|
77
|
+
// reported below
|
|
78
|
+
}
|
|
79
|
+
throw new UnsafeFileError(`Cannot resolve the directory that holds ${name}`);
|
|
80
|
+
}
|
|
81
|
+
// null when the path does not exist. A symlink (dangling or not), directory, device, FIFO or hard-linked file is refused.
|
|
82
|
+
export function regularFileIdentity(file) {
|
|
83
|
+
const name = path.basename(file);
|
|
84
|
+
let stat;
|
|
85
|
+
try {
|
|
86
|
+
stat = fs.lstatSync(file, { bigint: true });
|
|
87
|
+
}
|
|
88
|
+
catch (err) {
|
|
89
|
+
const code = errorCode(err);
|
|
90
|
+
if (code === 'ENOENT' || code === 'ENOTDIR')
|
|
91
|
+
return null;
|
|
92
|
+
throw new UnsafeFileError(`Cannot inspect ${name} (${code ?? 'unknown error'})`);
|
|
93
|
+
}
|
|
94
|
+
if (stat.isSymbolicLink())
|
|
95
|
+
throw new UnsafeFileError(`${name} is a symbolic link`);
|
|
96
|
+
if (!stat.isFile())
|
|
97
|
+
throw new UnsafeFileError(`${name} is not a regular file`);
|
|
98
|
+
if (isHardLinked(stat))
|
|
99
|
+
throw new UnsafeFileError(hardLinkMessage(name));
|
|
100
|
+
return { dev: stat.dev, ino: stat.ino };
|
|
101
|
+
}
|
|
102
|
+
// The descriptor we hold must still be what the path names, that path must not have become a link (symbolic or
|
|
103
|
+
// hard, the latter re-read from the descriptor itself), and the directory above it must still be the very directory
|
|
104
|
+
// we started in: same realpath and same dev/ino.
|
|
105
|
+
function verifyHeld(t, dir, fd, held, action = 'updated') {
|
|
106
|
+
const changed = () => new UnsafeFileError(`${t.name} changed while it was being ${action}`);
|
|
107
|
+
let named;
|
|
108
|
+
try {
|
|
109
|
+
named = fs.lstatSync(t.file, { bigint: true });
|
|
110
|
+
}
|
|
111
|
+
catch {
|
|
112
|
+
throw changed();
|
|
113
|
+
}
|
|
114
|
+
if (named.isSymbolicLink() || !named.isFile() || named.ino !== held.ino || named.dev !== held.dev)
|
|
115
|
+
throw changed();
|
|
116
|
+
if (isHardLinked(named) || isHardLinked(fs.fstatSync(fd, { bigint: true })))
|
|
117
|
+
throw new UnsafeFileError(hardLinkMessage(t.name));
|
|
118
|
+
verifyDirectory(t, dir, action);
|
|
119
|
+
}
|
|
120
|
+
// The directory above the file must still be the one we started in: same realpath and same dev/ino.
|
|
121
|
+
function verifyDirectory(t, dir, action) {
|
|
122
|
+
const now = directoryIdentity(dir, t.name);
|
|
123
|
+
if (realDirectory(dir, t.name) !== t.realDir || now.ino !== t.dirId.ino || now.dev !== t.dirId.dev) {
|
|
124
|
+
throw new UnsafeFileError(`${t.name} changed while it was being ${action}`);
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
// Creates `dir/name` only if nothing exists there. Returns true when created, false when a regular file was
|
|
128
|
+
// already present (left untouched). Throws UnsafeFileError for a link or any non-regular file, without writing.
|
|
129
|
+
// Like appendToRegularFile, the descriptor from the exclusive open is checked against the path and against the
|
|
130
|
+
// directory it was opened in before a byte is written and again after. If a check fails the file this call created
|
|
131
|
+
// is removed, but only while the path still names that very file; anything else found there is left alone.
|
|
132
|
+
// On Windows the file is published by hard link instead (see createFileByHardLink); the results are the same.
|
|
133
|
+
export function createFileExclusive(dir, name, data, mode = 0o644, hooks = {}) {
|
|
134
|
+
// Read at call time. On Windows O_CREAT|O_EXCL without O_NOFOLLOW would follow a dangling symlink, so that path is
|
|
135
|
+
// never taken there.
|
|
136
|
+
if (process.platform === 'win32')
|
|
137
|
+
return createFileByHardLink(dir, name, data, mode, hooks);
|
|
138
|
+
return createFileByExclusiveOpen(dir, name, data, mode, hooks);
|
|
139
|
+
}
|
|
140
|
+
function createFileByExclusiveOpen(dir, name, data, mode, hooks) {
|
|
141
|
+
const t = target(dir, name);
|
|
142
|
+
for (let attempt = 0; attempt < 3; attempt++) {
|
|
143
|
+
if (regularFileIdentity(t.file) !== null)
|
|
144
|
+
return false;
|
|
145
|
+
hooks.beforeOpen?.();
|
|
146
|
+
let fd;
|
|
147
|
+
try {
|
|
148
|
+
fd = fs.openSync(t.file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW, mode);
|
|
149
|
+
}
|
|
150
|
+
catch (err) {
|
|
151
|
+
if (errorCode(err) !== 'EEXIST')
|
|
152
|
+
throw err;
|
|
153
|
+
// Lost a race: something appeared after the check above. Accept it only if it is a plain file. If it has
|
|
154
|
+
// vanished again, look once more rather than report a file that is not there.
|
|
155
|
+
if (regularFileIdentity(t.file) !== null)
|
|
156
|
+
return false;
|
|
157
|
+
continue;
|
|
158
|
+
}
|
|
159
|
+
return finishCreate(t, dir, fd, data, hooks);
|
|
160
|
+
}
|
|
161
|
+
throw new UnsafeFileError(`${name} kept changing while it was being created`);
|
|
162
|
+
}
|
|
163
|
+
const STAGE_PREFIX = '.guardian-stage-';
|
|
164
|
+
const STAGED_NAME = 'file';
|
|
165
|
+
// Windows strategy, exported so the same code is tested everywhere (createFileExclusive selects it on win32).
|
|
166
|
+
// 1. mkdtemp makes a fresh, randomly named directory inside `dir` (so on the same volume); it never reuses an entry.
|
|
167
|
+
// 2. The staged file is created with O_EXCL inside that private directory, where nothing can be waiting at the name.
|
|
168
|
+
// 3. The directory is verified, then fs.linkSync(staged, destination) publishes it. A link never overwrites: EEXIST
|
|
169
|
+
// for a regular file means "already present" (false), for a symlink, dangling or not, or anything else it means
|
|
170
|
+
// UnsafeFileError, and the existing entry is not touched either way. Any other link failure (no hard links on this
|
|
171
|
+
// volume, say) fails closed with UnsafeFileError; there is no fallback to opening the destination.
|
|
172
|
+
// 4. The staged name is removed and finishCreate then verifies and writes through the descriptor exactly as it does
|
|
173
|
+
// for the exclusive open, including discarding the destination if it is still the file this call created.
|
|
174
|
+
// Only what this call created is ever removed: the staged file while it is still that inode, the staging directory
|
|
175
|
+
// with a non-recursive rmdir while it is still that directory, so anything foreign inside it survives.
|
|
176
|
+
export function createFileByHardLink(dir, name, data, mode = 0o644, hooks = {}) {
|
|
177
|
+
const t = target(dir, name);
|
|
178
|
+
for (let attempt = 0; attempt < 3; attempt++) {
|
|
179
|
+
if (regularFileIdentity(t.file) !== null)
|
|
180
|
+
return false;
|
|
181
|
+
hooks.beforeOpen?.();
|
|
182
|
+
const stage = openStage(t, dir, mode);
|
|
183
|
+
let linked = false;
|
|
184
|
+
try {
|
|
185
|
+
hooks.beforePublish?.();
|
|
186
|
+
verifyStage(t, dir, stage);
|
|
187
|
+
try {
|
|
188
|
+
fs.linkSync(stage.file, t.file);
|
|
189
|
+
linked = true;
|
|
190
|
+
}
|
|
191
|
+
catch (err) {
|
|
192
|
+
if (errorCode(err) !== 'EEXIST')
|
|
193
|
+
throw publishFailure(t.name, err);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
catch (err) {
|
|
197
|
+
releaseStage(stage);
|
|
198
|
+
throw err;
|
|
199
|
+
}
|
|
200
|
+
if (!linked) {
|
|
201
|
+
// Something already has the name. Accept it only if it is a plain file; if it vanished again, look once more.
|
|
202
|
+
releaseStage(stage);
|
|
203
|
+
if (regularFileIdentity(t.file) !== null)
|
|
204
|
+
return false;
|
|
205
|
+
continue;
|
|
206
|
+
}
|
|
207
|
+
try {
|
|
208
|
+
removeStageNames(stage); // the link count must be back to 1 before the file is verified
|
|
209
|
+
return finishCreate(t, dir, stage.fd, data, hooks); // closes the descriptor
|
|
210
|
+
}
|
|
211
|
+
finally {
|
|
212
|
+
removeStageNames(stage); // again, now that the descriptor is closed and cannot hold the directory
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
throw new UnsafeFileError(`${name} kept changing while it was being created`);
|
|
216
|
+
}
|
|
217
|
+
function openStage(t, dir, mode) {
|
|
218
|
+
const stageDir = fs.mkdtempSync(path.join(dir, STAGE_PREFIX));
|
|
219
|
+
const names = { dir: stageDir, dirId: null, file: path.join(stageDir, STAGED_NAME), held: null };
|
|
220
|
+
let fd = null;
|
|
221
|
+
try {
|
|
222
|
+
const made = fs.lstatSync(stageDir, { bigint: true });
|
|
223
|
+
if (!made.isDirectory())
|
|
224
|
+
throw new UnsafeFileError(`${t.name} changed while it was being created`);
|
|
225
|
+
names.dirId = { dev: made.dev, ino: made.ino };
|
|
226
|
+
verifyDirectory(t, dir, 'created');
|
|
227
|
+
fd = fs.openSync(names.file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW, mode);
|
|
228
|
+
const held = fs.fstatSync(fd, { bigint: true });
|
|
229
|
+
names.held = held;
|
|
230
|
+
const named = fs.lstatSync(names.file, { bigint: true });
|
|
231
|
+
if (!held.isFile() || isHardLinked(held) || !named.isFile() || named.ino !== held.ino || named.dev !== held.dev) {
|
|
232
|
+
throw new UnsafeFileError(`${t.name} changed while it was being created`);
|
|
233
|
+
}
|
|
234
|
+
return { ...names, dirId: names.dirId, held, fd };
|
|
235
|
+
}
|
|
236
|
+
catch (err) {
|
|
237
|
+
if (fd !== null)
|
|
238
|
+
closeQuietly(fd);
|
|
239
|
+
removeStageNames(names);
|
|
240
|
+
throw err;
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
// Right before publication: the destination directory is still ours, and the staging directory and staged file are
|
|
244
|
+
// still what this call made.
|
|
245
|
+
function verifyStage(t, dir, stage) {
|
|
246
|
+
const changed = () => new UnsafeFileError(`${t.name} changed while it was being created`);
|
|
247
|
+
verifyDirectory(t, dir, 'created');
|
|
248
|
+
try {
|
|
249
|
+
const d = fs.lstatSync(stage.dir, { bigint: true });
|
|
250
|
+
const f = fs.lstatSync(stage.file, { bigint: true });
|
|
251
|
+
if (!d.isDirectory() || d.ino !== stage.dirId.ino || d.dev !== stage.dirId.dev)
|
|
252
|
+
throw changed();
|
|
253
|
+
if (!f.isFile() || f.ino !== stage.held.ino || f.dev !== stage.held.dev)
|
|
254
|
+
throw changed();
|
|
255
|
+
}
|
|
256
|
+
catch (err) {
|
|
257
|
+
throw err instanceof UnsafeFileError ? err : changed();
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
function publishFailure(name, err) {
|
|
261
|
+
const code = errorCode(err);
|
|
262
|
+
if (code === 'ENOENT')
|
|
263
|
+
return new UnsafeFileError(`${name} changed while it was being created`);
|
|
264
|
+
return new UnsafeFileError(`${name} cannot be created safely: publishing it with a hard link failed${code ? ` (${code})` : ''}. ` +
|
|
265
|
+
'This needs a file system that supports hard links (NTFS and ReFS do; FAT, exFAT and some network shares do not). Nothing was created.');
|
|
266
|
+
}
|
|
267
|
+
function releaseStage(stage) {
|
|
268
|
+
closeQuietly(stage.fd);
|
|
269
|
+
removeStageNames(stage);
|
|
270
|
+
}
|
|
271
|
+
// Never throws and never recurses: rmdir fails on a directory that holds anything else, and that is the point.
|
|
272
|
+
function removeStageNames(s) {
|
|
273
|
+
if (!s.dirId)
|
|
274
|
+
return;
|
|
275
|
+
try {
|
|
276
|
+
if (s.held) {
|
|
277
|
+
const f = fs.lstatSync(s.file, { bigint: true });
|
|
278
|
+
if (f.isFile() && f.ino === s.held.ino && f.dev === s.held.dev)
|
|
279
|
+
fs.unlinkSync(s.file);
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
catch {
|
|
283
|
+
// Already gone, or not removable; the leftovers are covered in the header comment.
|
|
284
|
+
}
|
|
285
|
+
try {
|
|
286
|
+
const d = fs.lstatSync(s.dir, { bigint: true });
|
|
287
|
+
if (d.isDirectory() && d.ino === s.dirId.ino && d.dev === s.dirId.dev)
|
|
288
|
+
fs.rmdirSync(s.dir);
|
|
289
|
+
}
|
|
290
|
+
catch {
|
|
291
|
+
// Same.
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
// writeSync may write fewer bytes than asked (a full disk, a quota) and reports that only through its return value. A short write
|
|
295
|
+
// is an incomplete file, so it is an error here and never a success.
|
|
296
|
+
function writeAll(fd, text) {
|
|
297
|
+
const bytes = Buffer.from(text, 'utf8');
|
|
298
|
+
let offset = 0;
|
|
299
|
+
while (offset < bytes.length) {
|
|
300
|
+
const written = fs.writeSync(fd, bytes, offset, bytes.length - offset);
|
|
301
|
+
if (written <= 0)
|
|
302
|
+
throw new UnsafeFileError('the file could not be written completely');
|
|
303
|
+
offset += written;
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
function closeQuietly(fd) {
|
|
307
|
+
try {
|
|
308
|
+
fs.closeSync(fd);
|
|
309
|
+
}
|
|
310
|
+
catch {
|
|
311
|
+
// Nothing useful to do.
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
function finishCreate(t, dir, fd, data, hooks) {
|
|
315
|
+
let held = null;
|
|
316
|
+
let failed = false;
|
|
317
|
+
try {
|
|
318
|
+
held = fs.fstatSync(fd, { bigint: true });
|
|
319
|
+
hooks.afterOpen?.();
|
|
320
|
+
if (!held.isFile())
|
|
321
|
+
throw new UnsafeFileError(`${t.name} is not a regular file`);
|
|
322
|
+
verifyHeld(t, dir, fd, held, 'created');
|
|
323
|
+
if (data.length > 0) {
|
|
324
|
+
writeAll(fd, data);
|
|
325
|
+
hooks.afterWrite?.();
|
|
326
|
+
verifyHeld(t, dir, fd, held, 'created');
|
|
327
|
+
}
|
|
328
|
+
return true;
|
|
329
|
+
}
|
|
330
|
+
catch (err) {
|
|
331
|
+
failed = true;
|
|
332
|
+
throw err;
|
|
333
|
+
}
|
|
334
|
+
finally {
|
|
335
|
+
fs.closeSync(fd);
|
|
336
|
+
if (failed && held)
|
|
337
|
+
discardCreated(t, held);
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
// Removes the file this call created, but only if the path still names it. Never throws: the original error is
|
|
341
|
+
// the one worth reporting. A hard-linked name is removed too, which only drops this entry; the inode and its
|
|
342
|
+
// other name were created empty by this call, so nothing that existed before is lost.
|
|
343
|
+
function discardCreated(t, created) {
|
|
344
|
+
try {
|
|
345
|
+
const named = fs.lstatSync(t.file, { bigint: true });
|
|
346
|
+
if (named.isFile() && named.ino === created.ino && named.dev === created.dev)
|
|
347
|
+
fs.unlinkSync(t.file);
|
|
348
|
+
}
|
|
349
|
+
catch {
|
|
350
|
+
// Best effort; see the limits in the header comment.
|
|
351
|
+
}
|
|
352
|
+
}
|
|
353
|
+
// Appends to an existing regular file. `decide` sees the current text and returns what to append, or null for
|
|
354
|
+
// nothing. The write goes through the descriptor that was verified, never through a path that could be swapped.
|
|
355
|
+
export function appendToRegularFile(dir, name, maxBytes, decide) {
|
|
356
|
+
const t = target(dir, name);
|
|
357
|
+
if (regularFileIdentity(t.file) === null)
|
|
358
|
+
throw new UnsafeFileError(`${name} does not exist`);
|
|
359
|
+
let fd;
|
|
360
|
+
try {
|
|
361
|
+
fd = fs.openSync(t.file, fs.constants.O_RDWR | fs.constants.O_APPEND | NOFOLLOW | NONBLOCK);
|
|
362
|
+
}
|
|
363
|
+
catch (err) {
|
|
364
|
+
if (errorCode(err) === 'ELOOP')
|
|
365
|
+
throw new UnsafeFileError(`${name} is a symbolic link`);
|
|
366
|
+
throw err;
|
|
367
|
+
}
|
|
368
|
+
try {
|
|
369
|
+
const held = fs.fstatSync(fd, { bigint: true });
|
|
370
|
+
if (!held.isFile())
|
|
371
|
+
throw new UnsafeFileError(`${name} is not a regular file`);
|
|
372
|
+
if (isHardLinked(held))
|
|
373
|
+
throw new UnsafeFileError(hardLinkMessage(name));
|
|
374
|
+
if (held.size > BigInt(maxBytes))
|
|
375
|
+
throw new UnsafeFileError(`${name} is too large to update safely`);
|
|
376
|
+
verifyHeld(t, dir, fd, held);
|
|
377
|
+
const size = Number(held.size);
|
|
378
|
+
const data = Buffer.alloc(size);
|
|
379
|
+
let offset = 0;
|
|
380
|
+
while (offset < size) {
|
|
381
|
+
const read = fs.readSync(fd, data, offset, size - offset, offset);
|
|
382
|
+
if (read === 0)
|
|
383
|
+
break;
|
|
384
|
+
offset += read;
|
|
385
|
+
}
|
|
386
|
+
const addition = decide(data.subarray(0, offset).toString('utf8'));
|
|
387
|
+
if (addition === null)
|
|
388
|
+
return false;
|
|
389
|
+
verifyHeld(t, dir, fd, held);
|
|
390
|
+
writeAll(fd, addition);
|
|
391
|
+
return true;
|
|
392
|
+
}
|
|
393
|
+
finally {
|
|
394
|
+
fs.closeSync(fd);
|
|
395
|
+
}
|
|
396
|
+
}
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import os from 'node:os';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { InputError, errorCode } from '../../utils/errors.js';
|
|
5
|
+
export class SandboxError extends InputError {
|
|
6
|
+
constructor(message) {
|
|
7
|
+
super(message, 'invalid_path');
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
const MAX_PATH_LENGTH = 4096;
|
|
11
|
+
const OPEN_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
|
|
12
|
+
// Windows treats these names as devices, and a UNC or device prefix leaves the drive-relative namespace entirely.
|
|
13
|
+
const WINDOWS_DEVICE = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?$/i;
|
|
14
|
+
function rejectWindowsForms(target) {
|
|
15
|
+
if (process.platform !== 'win32')
|
|
16
|
+
return;
|
|
17
|
+
if (/^[\\/]{2}/.test(target) || /^[A-Za-z]:(?![\\/])/.test(target))
|
|
18
|
+
throw new SandboxError(`Unsafe path form: ${target}`);
|
|
19
|
+
if (target.split(/[\\/]/).some((segment) => WINDOWS_DEVICE.test(segment)))
|
|
20
|
+
throw new SandboxError(`Reserved device name in path: ${target}`);
|
|
21
|
+
}
|
|
22
|
+
const SENSITIVE_NAME = /^(?:\.env.*|\.npmrc|\.pypirc|\.netrc|\.pgpass|\.htpasswd|\.dockercfg|\.git-credentials|credentials?|id_(?:rsa|dsa|ecdsa|ed25519)|.*\.(?:pem|key|p12|pfx|jks|keystore|kdbx|tfvars|tfstate)|.*(?:secret|credential)s?\.[a-z0-9]+)$/i;
|
|
23
|
+
export function isSensitivePath(rel) {
|
|
24
|
+
return SENSITIVE_NAME.test(rel.split('/').pop() ?? '');
|
|
25
|
+
}
|
|
26
|
+
function isInside(root, target) {
|
|
27
|
+
const rel = path.relative(root, target);
|
|
28
|
+
return rel === '' || (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
|
|
29
|
+
}
|
|
30
|
+
const canonical = (p) => fs.realpathSync.native(p);
|
|
31
|
+
function canonicalRoot(root) {
|
|
32
|
+
try {
|
|
33
|
+
return canonical(root);
|
|
34
|
+
}
|
|
35
|
+
catch {
|
|
36
|
+
throw new SandboxError('Workspace directory not found');
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
function homeDirectory() {
|
|
40
|
+
try {
|
|
41
|
+
return canonical(os.homedir());
|
|
42
|
+
}
|
|
43
|
+
catch {
|
|
44
|
+
return undefined;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
// Directories that are never a project: the top of a system tree (exactly, so a project below /var/folders or /opt still
|
|
48
|
+
// works) and the folders that hold a user's keys and cloud credentials (themselves and everything below).
|
|
49
|
+
const SYSTEM_DIRECTORIES = new Set(['/etc', '/usr', '/bin', '/sbin', '/lib', '/lib64', '/boot', '/dev', '/proc', '/sys', '/root', '/var', '/System', '/Library', '/Applications']);
|
|
50
|
+
const CREDENTIAL_DIRECTORIES = ['.ssh', '.gnupg', '.aws', '.azure', '.kube'];
|
|
51
|
+
const CANONICAL_SYSTEM_DIRECTORIES = new Set(process.platform === 'win32'
|
|
52
|
+
? []
|
|
53
|
+
: [...SYSTEM_DIRECTORIES].flatMap((directory) => {
|
|
54
|
+
try {
|
|
55
|
+
return [canonical(directory)];
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
return [];
|
|
59
|
+
}
|
|
60
|
+
}));
|
|
61
|
+
function isSystemOrCredentialDirectory(root, home) {
|
|
62
|
+
if (process.platform !== 'win32' &&
|
|
63
|
+
(SYSTEM_DIRECTORIES.has(root) || CANONICAL_SYSTEM_DIRECTORIES.has(root)))
|
|
64
|
+
return true;
|
|
65
|
+
if (home === undefined)
|
|
66
|
+
return false;
|
|
67
|
+
return CREDENTIAL_DIRECTORIES.some((name) => isInside(path.join(home, name), root));
|
|
68
|
+
}
|
|
69
|
+
export function resolveWorkspaceRoot(input) {
|
|
70
|
+
let root;
|
|
71
|
+
try {
|
|
72
|
+
root = canonical(path.resolve(input));
|
|
73
|
+
}
|
|
74
|
+
catch {
|
|
75
|
+
throw new SandboxError(`Workspace directory not found: ${input}`);
|
|
76
|
+
}
|
|
77
|
+
if (!fs.statSync(root).isDirectory())
|
|
78
|
+
throw new SandboxError(`Not a directory: ${root}`);
|
|
79
|
+
const home = homeDirectory();
|
|
80
|
+
const tooBroad = root === path.parse(root).root || (home !== undefined && (root === home || root === path.dirname(home)));
|
|
81
|
+
if (tooBroad)
|
|
82
|
+
throw new SandboxError('Refusing to use a filesystem root or home directory as the workspace. Pass --root <project>.');
|
|
83
|
+
if (isSystemOrCredentialDirectory(root, home))
|
|
84
|
+
throw new SandboxError('Refusing to use a system or credential directory as the workspace. Pass --root <project>.');
|
|
85
|
+
return root;
|
|
86
|
+
}
|
|
87
|
+
export function resolveInside(root, target) {
|
|
88
|
+
if (typeof target !== 'string' || target.length === 0 || target.length > MAX_PATH_LENGTH || target.includes('\0')) {
|
|
89
|
+
throw new SandboxError('Invalid path');
|
|
90
|
+
}
|
|
91
|
+
const outside = () => new SandboxError(`Path is outside the workspace: ${target}`);
|
|
92
|
+
rejectWindowsForms(target);
|
|
93
|
+
const workspace = canonicalRoot(root);
|
|
94
|
+
const lexical = path.resolve(workspace, target);
|
|
95
|
+
if (!isInside(workspace, lexical))
|
|
96
|
+
throw outside();
|
|
97
|
+
let real;
|
|
98
|
+
try {
|
|
99
|
+
real = canonical(lexical);
|
|
100
|
+
}
|
|
101
|
+
catch {
|
|
102
|
+
throw new SandboxError(`Path not found inside workspace: ${target}`);
|
|
103
|
+
}
|
|
104
|
+
if (!isInside(workspace, real))
|
|
105
|
+
throw outside();
|
|
106
|
+
return real;
|
|
107
|
+
}
|
|
108
|
+
export function toRelative(root, absolute) {
|
|
109
|
+
return path.relative(canonicalRoot(root), absolute).split(path.sep).join('/');
|
|
110
|
+
}
|
|
111
|
+
// Node has no openat2/RESOLVE_BENEATH, so the check and the open cannot be one atomic step. Instead the open is
|
|
112
|
+
// verified afterwards: the descriptor we hold must still be what the path names, and that path must still be inside.
|
|
113
|
+
function verifyOpened(root, abs, fd) {
|
|
114
|
+
const workspace = canonicalRoot(root);
|
|
115
|
+
const held = fs.fstatSync(fd, { bigint: true });
|
|
116
|
+
let again;
|
|
117
|
+
try {
|
|
118
|
+
again = canonical(abs);
|
|
119
|
+
}
|
|
120
|
+
catch {
|
|
121
|
+
throw new SandboxError('File changed while it was being read');
|
|
122
|
+
}
|
|
123
|
+
if (again !== abs || !isInside(workspace, again))
|
|
124
|
+
throw new SandboxError('Path changed while it was being checked');
|
|
125
|
+
const named = fs.statSync(again, { bigint: true });
|
|
126
|
+
if (named.ino !== held.ino || named.dev !== held.dev)
|
|
127
|
+
throw new SandboxError('File changed while it was being read');
|
|
128
|
+
}
|
|
129
|
+
export function readInside(root, rel, maxBytes, hooks = {}) {
|
|
130
|
+
const abs = resolveInside(root, rel);
|
|
131
|
+
if (isSensitivePath(rel) || isSensitivePath(toRelative(root, abs))) {
|
|
132
|
+
throw new SandboxError(`Refusing to read sensitive file: ${rel}`);
|
|
133
|
+
}
|
|
134
|
+
hooks.afterResolve?.();
|
|
135
|
+
let fd;
|
|
136
|
+
try {
|
|
137
|
+
fd = fs.openSync(abs, OPEN_FLAGS);
|
|
138
|
+
}
|
|
139
|
+
catch {
|
|
140
|
+
throw new SandboxError(`Cannot open file: ${rel}`);
|
|
141
|
+
}
|
|
142
|
+
try {
|
|
143
|
+
verifyOpened(root, abs, fd);
|
|
144
|
+
const stat = fs.fstatSync(fd);
|
|
145
|
+
if (!stat.isFile())
|
|
146
|
+
throw new SandboxError(`Not a regular file: ${rel}`);
|
|
147
|
+
if (hooks.rejectHardLinks && stat.nlink > 1)
|
|
148
|
+
throw new SandboxError(`Refusing hard-linked file: ${rel}`);
|
|
149
|
+
if (stat.size > maxBytes)
|
|
150
|
+
throw new SandboxError(`File too large: ${rel}`);
|
|
151
|
+
const data = Buffer.alloc(stat.size);
|
|
152
|
+
let offset = 0;
|
|
153
|
+
while (offset < data.length) {
|
|
154
|
+
const read = fs.readSync(fd, data, offset, data.length - offset, offset);
|
|
155
|
+
if (read === 0)
|
|
156
|
+
break;
|
|
157
|
+
offset += read;
|
|
158
|
+
}
|
|
159
|
+
return data.subarray(0, offset);
|
|
160
|
+
}
|
|
161
|
+
finally {
|
|
162
|
+
fs.closeSync(fd);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
// Reads a workspace file that may legitimately be absent (a config file). Absence is null; a symlink that leaves
|
|
166
|
+
// the workspace, a sensitive name or an oversized file still throws, so a hostile repository cannot steer the read.
|
|
167
|
+
export function readOptionalInside(root, rel, maxBytes, hooks = {}) {
|
|
168
|
+
const workspace = canonicalRoot(root);
|
|
169
|
+
const lexical = path.resolve(workspace, rel);
|
|
170
|
+
if (!isInside(workspace, lexical))
|
|
171
|
+
throw new SandboxError(`Path is outside the workspace: ${rel}`);
|
|
172
|
+
try {
|
|
173
|
+
fs.lstatSync(lexical);
|
|
174
|
+
}
|
|
175
|
+
catch (err) {
|
|
176
|
+
if (errorCode(err) === 'ENOENT' || errorCode(err) === 'ENOTDIR')
|
|
177
|
+
return null;
|
|
178
|
+
throw new SandboxError(`Cannot access ${rel}`);
|
|
179
|
+
}
|
|
180
|
+
return readInside(root, rel, maxBytes, hooks);
|
|
181
|
+
}
|