typeclaw 0.46.0 → 0.46.2
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/README.md +1 -1
- package/package.json +2 -2
- package/src/agent/multimodal/looker.ts +11 -1
- package/src/agent/network/safe-http.ts +17 -8
- package/src/agent/plugin-tools.ts +1 -3
- package/src/agent/tool-file-safety.ts +414 -145
- package/src/agent/tools/webfetch/fetch.ts +22 -2
- package/src/agent/tools/webfetch/strategies/jq.ts +1 -2
- package/src/agent/tools/webfetch/strategies/readability.ts +39 -16
- package/src/agent/tools/webfetch/strategies/selector.ts +4 -2
- package/src/agent/tools/webfetch/strategies/snapshot.ts +3 -2
- package/src/agent/tools/webfetch/tool.ts +3 -3
- package/src/agent/tools-without-local-file-operands.ts +9 -6
- package/src/bundled-plugins/backup/README.md +23 -10
- package/src/bundled-plugins/backup/git-auth.ts +6 -4
- package/src/bundled-plugins/backup/index.ts +104 -47
- package/src/bundled-plugins/backup/runner.ts +102 -5
- package/src/bundled-plugins/github-cli-auth/git-askpass.ts +74 -26
- package/src/bundled-plugins/github-cli-auth/git-command.ts +224 -36
- package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +9 -9
- package/src/bundled-plugins/github-cli-auth/index.ts +110 -31
- package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
- package/src/bundled-plugins/memory/README.md +9 -0
- package/src/bundled-plugins/memory/vector/embed-threads.ts +36 -0
- package/src/bundled-plugins/memory/vector/embedder.ts +19 -1
- package/src/bundled-plugins/memory/vector/hybrid.ts +10 -2
- package/src/bundled-plugins/memory/vector/store.ts +21 -9
- package/src/bundled-plugins/researcher/write-report.ts +3 -3
- package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +8 -3
- package/src/bundled-plugins/security/policies/private-surface-read.ts +616 -50
- package/src/bundled-plugins/security/policies/ssrf.ts +119 -34
- package/src/channels/adapters/github/inbound.ts +11 -0
- package/src/channels/adapters/github/index.ts +48 -54
- package/src/channels/adapters/github/reconcile-cooldown-store.ts +178 -0
- package/src/channels/adapters/github/reconcile-open-prs.ts +31 -0
- package/src/channels/adapters/slack-bot-edit.ts +85 -20
- package/src/channels/adapters/slack-bot.ts +7 -2
- package/src/channels/adapters/slack-format.ts +245 -0
- package/src/channels/github-token-bridge.ts +2 -3
- package/src/cli/inspect.ts +16 -0
- package/src/container/docker-app.ts +42 -13
- package/src/container/shared.ts +19 -6
- package/src/container/start.ts +13 -0
- package/src/cron/bridge.ts +9 -2
- package/src/doctor/checks.ts +5 -2
- package/src/git/bound-gc-config.ts +82 -0
- package/src/hostd/spawn.ts +133 -47
- package/src/init/checkpoint.ts +4 -4
- package/src/init/dockerfile.ts +100 -88
- package/src/init/gitignore.ts +5 -6
- package/src/init/run-bun-install.ts +16 -2
- package/src/init/validate-api-key.ts +1 -0
- package/src/inspect/item-list.ts +12 -6
- package/src/inspect/replay.ts +21 -9
- package/src/inspect/session-list.ts +71 -33
- package/src/mcp/tools.ts +1 -0
- package/src/network/internal-destinations.ts +267 -0
- package/src/permissions/permissions.ts +93 -2
- package/src/plugin/types.ts +3 -2
- package/src/role-claim/code.ts +9 -5
- package/src/run/index.ts +45 -36
- package/src/sandbox/canonical-secrets.ts +6 -0
- package/src/sandbox/env-exposure.ts +18 -15
- package/src/sandbox/index.ts +1 -0
- package/src/sandbox/policy.ts +5 -3
- package/src/sandbox/privileged-runtime.ts +1 -0
- package/src/sandbox/symlinks.ts +1 -1
- package/src/secrets/export-claude-credentials-file.ts +13 -22
- package/src/secrets/export-codex-auth-file.ts +12 -28
- package/src/skills/typeclaw-config/SKILL.md +22 -6
- package/src/skills/typeclaw-permissions/SKILL.md +22 -9
- package/src/skills/typeclaw-plugins/SKILL.md +37 -0
- package/src/usage/scan.ts +11 -2
- package/typeclaw.schema.json +5 -0
- package/src/git/secret-history.ts +0 -371
|
@@ -1,4 +1,16 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import {
|
|
2
|
+
closeSync,
|
|
3
|
+
constants,
|
|
4
|
+
fstatSync,
|
|
5
|
+
lstatSync,
|
|
6
|
+
openSync,
|
|
7
|
+
opendirSync,
|
|
8
|
+
realpathSync,
|
|
9
|
+
statSync,
|
|
10
|
+
type Dir,
|
|
11
|
+
type Dirent,
|
|
12
|
+
type Stats,
|
|
13
|
+
} from 'node:fs'
|
|
2
14
|
import { homedir } from 'node:os'
|
|
3
15
|
import path from 'node:path'
|
|
4
16
|
import { fileURLToPath } from 'node:url'
|
|
@@ -10,6 +22,7 @@ import {
|
|
|
10
22
|
CANONICAL_AGENT_SECRET_FILES,
|
|
11
23
|
CANONICAL_HOME_SECRET_DIRS,
|
|
12
24
|
CANONICAL_HOME_SECRET_FILES,
|
|
25
|
+
CONTAINER_RUNTIME_HOME,
|
|
13
26
|
type HiddenPaths,
|
|
14
27
|
} from '@/sandbox'
|
|
15
28
|
|
|
@@ -31,6 +44,7 @@ export const GUARD_PRIVATE_SURFACE_READ = 'privateSurfaceRead'
|
|
|
31
44
|
// keeps both enforcement points agreeing on which tools read no local path.
|
|
32
45
|
const UNSCANNED_TOOLS = new Set(['bash', ...TOOLS_WITHOUT_LOCAL_FILE_OPERANDS])
|
|
33
46
|
const VIRTUAL_FILESYSTEM_ROOTS = ['/proc', '/sys', '/dev', '/run'] as const
|
|
47
|
+
const HARDLINK_SCAN_EXCLUDED_AGENT_DIRS = new Set(['.git', '.gitstore', 'node_modules'])
|
|
34
48
|
|
|
35
49
|
// The bash sandbox hides the role's private surface — the working DIRECTORIES
|
|
36
50
|
// (workspace/, memory/, sessions/), unconditional credential directories, and
|
|
@@ -55,37 +69,25 @@ const VIRTUAL_FILESYSTEM_ROOTS = ['/proc', '/sys', '/dev', '/run'] as const
|
|
|
55
69
|
// shapes like look_at's images[].path and channel_send's attachments[].path —
|
|
56
70
|
// and blocks any string that resolves to (a secret file) or under (a hidden
|
|
57
71
|
// directory) the deny-list.
|
|
58
|
-
export function checkPrivateSurfaceReadGuard(
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
72
|
+
export function checkPrivateSurfaceReadGuard(
|
|
73
|
+
options: {
|
|
74
|
+
tool: string
|
|
75
|
+
args: Record<string, unknown>
|
|
76
|
+
agentDir: string
|
|
77
|
+
hidden: HiddenPaths
|
|
78
|
+
fileOperands?: ToolFileOperands
|
|
79
|
+
},
|
|
80
|
+
hooks: PrivateSurfaceIdentityScanHooks = {},
|
|
81
|
+
): SecurityBlock | undefined {
|
|
65
82
|
const { tool, args, agentDir, hidden, fileOperands } = options
|
|
66
83
|
if (UNSCANNED_TOOLS.has(tool)) return undefined
|
|
67
|
-
const deniedDirs =
|
|
68
|
-
...new Set([
|
|
69
|
-
...hidden.dirs,
|
|
70
|
-
...CANONICAL_AGENT_SECRET_DIRS.map((dir) => path.join(agentDir, dir)),
|
|
71
|
-
...CANONICAL_HOME_SECRET_DIRS.map((dir) => path.join(homedir(), dir)),
|
|
72
|
-
]),
|
|
73
|
-
]
|
|
74
|
-
// Keep these runtime-owned credential stores independent of role-derived
|
|
75
|
-
// visibility so a privileged role or partially-wired caller cannot turn raw
|
|
76
|
-
// credentials into model context.
|
|
77
|
-
const deniedFiles = [
|
|
78
|
-
...new Set([
|
|
79
|
-
...hidden.files,
|
|
80
|
-
...CANONICAL_AGENT_SECRET_FILES.map((file) => path.join(agentDir, file)),
|
|
81
|
-
...CANONICAL_HOME_SECRET_FILES.map((file) => path.join(homedir(), file)),
|
|
82
|
-
]),
|
|
83
|
-
]
|
|
84
|
+
const { deniedDirs, deniedFiles } = deniedSurface(agentDir, hidden)
|
|
84
85
|
if (deniedDirs.length === 0 && deniedFiles.length === 0) return undefined
|
|
86
|
+
const identityScanner = createHardlinkIdentityScanner(agentDir, deniedDirs, deniedFiles, hooks)
|
|
85
87
|
|
|
86
88
|
const nonFile = fileOperands?.nonFile === undefined ? undefined : new Set(fileOperands.nonFile)
|
|
87
89
|
for (const candidate of collectPathCandidates(args, tool, nonFile)) {
|
|
88
|
-
const hit = matchHidden(candidate, agentDir, deniedDirs, deniedFiles)
|
|
90
|
+
const hit = matchHidden(candidate, agentDir, deniedDirs, deniedFiles, identityScanner)
|
|
89
91
|
if (hit !== undefined) {
|
|
90
92
|
return {
|
|
91
93
|
block: true,
|
|
@@ -99,6 +101,102 @@ export function checkPrivateSurfaceReadGuard(options: {
|
|
|
99
101
|
return undefined
|
|
100
102
|
}
|
|
101
103
|
|
|
104
|
+
type PrivateSurfaceIdentityOptions = {
|
|
105
|
+
tool: string
|
|
106
|
+
agentDir: string
|
|
107
|
+
hidden: HiddenPaths
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
export type PrivateSurfaceIdentityScanHooks = {
|
|
111
|
+
maxEntries?: number
|
|
112
|
+
openDirectory?(directory: string): Pick<Dir, 'readSync' | 'closeSync'>
|
|
113
|
+
lstat?(candidate: string): Stats
|
|
114
|
+
afterEntryLstat?(candidate: string, stats: Stats): void
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export type PrivateSurfaceIdentityVerifier = {
|
|
118
|
+
check(identity: Pick<Stats, 'dev' | 'ino' | 'nlink'>): SecurityBlock | undefined
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export function createPrivateSurfaceReadIdentityVerifier(
|
|
122
|
+
options: PrivateSurfaceIdentityOptions,
|
|
123
|
+
hooks: PrivateSurfaceIdentityScanHooks = {},
|
|
124
|
+
): PrivateSurfaceIdentityVerifier {
|
|
125
|
+
const { deniedDirs, deniedFiles } = deniedSurface(options.agentDir, options.hidden)
|
|
126
|
+
const scanner = createHardlinkIdentityScanner(options.agentDir, deniedDirs, deniedFiles, hooks)
|
|
127
|
+
return {
|
|
128
|
+
check(identity) {
|
|
129
|
+
if (identity.nlink <= 1) return undefined
|
|
130
|
+
const hit = scanner.check(identity)
|
|
131
|
+
return hit === undefined ? undefined : privateSurfaceBlock(options.tool, hit)
|
|
132
|
+
},
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
export function checkPrivateSurfaceReadIdentityGuard(
|
|
137
|
+
options: PrivateSurfaceIdentityOptions & { identity: Pick<Stats, 'dev' | 'ino' | 'nlink'> },
|
|
138
|
+
hooks: PrivateSurfaceIdentityScanHooks = {},
|
|
139
|
+
): SecurityBlock | undefined {
|
|
140
|
+
return createPrivateSurfaceReadIdentityVerifier(options, hooks).check(options.identity)
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
function createHardlinkIdentityScanner(
|
|
144
|
+
agentDir: string,
|
|
145
|
+
deniedDirs: readonly string[],
|
|
146
|
+
deniedFiles: readonly string[],
|
|
147
|
+
hooks: PrivateSurfaceIdentityScanHooks,
|
|
148
|
+
): HardlinkIdentityScanner {
|
|
149
|
+
const lstat = hooks.lstat ?? lstatSync
|
|
150
|
+
return new HardlinkIdentityScanner({
|
|
151
|
+
agentDir,
|
|
152
|
+
deniedDirs,
|
|
153
|
+
deniedFiles,
|
|
154
|
+
maxEntries: hooks.maxEntries ?? MAX_HARDLINK_IDENTITY_ENTRIES,
|
|
155
|
+
openDirectory:
|
|
156
|
+
hooks.openDirectory === undefined
|
|
157
|
+
? openDescriptorAnchoredDirectory
|
|
158
|
+
: createPathDirectoryOpener(hooks.openDirectory, lstat),
|
|
159
|
+
lstat,
|
|
160
|
+
afterEntryLstat: hooks.afterEntryLstat,
|
|
161
|
+
})
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
function deniedSurface(agentDir: string, hidden: HiddenPaths): { deniedDirs: string[]; deniedFiles: string[] } {
|
|
165
|
+
return {
|
|
166
|
+
deniedDirs: [
|
|
167
|
+
...new Set([
|
|
168
|
+
...hidden.dirs,
|
|
169
|
+
...CANONICAL_AGENT_SECRET_DIRS.map((dir) => path.join(agentDir, dir)),
|
|
170
|
+
// homedir() follows the live container HOME; the fixed runtime path
|
|
171
|
+
// keeps the same denial deterministic in host-stage tests and any
|
|
172
|
+
// partially-initialized caller whose environment has not switched yet.
|
|
173
|
+
...CANONICAL_HOME_SECRET_DIRS.map((dir) => path.join(homedir(), dir)),
|
|
174
|
+
...CANONICAL_HOME_SECRET_DIRS.map((dir) => path.join(CONTAINER_RUNTIME_HOME, dir)),
|
|
175
|
+
]),
|
|
176
|
+
],
|
|
177
|
+
// Keep runtime-owned credential stores independent of role-derived
|
|
178
|
+
// visibility so a partially-wired caller cannot expose raw credentials.
|
|
179
|
+
deniedFiles: [
|
|
180
|
+
...new Set([
|
|
181
|
+
...hidden.files,
|
|
182
|
+
...CANONICAL_AGENT_SECRET_FILES.map((file) => path.join(agentDir, file)),
|
|
183
|
+
...CANONICAL_HOME_SECRET_FILES.map((file) => path.join(homedir(), file)),
|
|
184
|
+
...CANONICAL_HOME_SECRET_FILES.map((file) => path.join(CONTAINER_RUNTIME_HOME, file)),
|
|
185
|
+
]),
|
|
186
|
+
],
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
function privateSurfaceBlock(tool: string, hit: string): SecurityBlock {
|
|
191
|
+
return {
|
|
192
|
+
block: true,
|
|
193
|
+
reason: [
|
|
194
|
+
`Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: input inode aliases ${hit}, which is not available to LLM tools.`,
|
|
195
|
+
'The bash sandbox masks the same path. Privileged roles cannot bypass canonical agent credential files; use host-side redacted diagnostics instead.',
|
|
196
|
+
].join(' '),
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
|
|
102
200
|
// Field names whose values are ALWAYS free text (prose/queries/ids), NEVER a
|
|
103
201
|
// filesystem path, for EVERY tool. Scanning them caused false positives: a
|
|
104
202
|
// guest's `channel_reply({ text: "the memory leak" })` or `web_search({ query:
|
|
@@ -242,6 +340,7 @@ function matchHidden(
|
|
|
242
340
|
agentDir: string,
|
|
243
341
|
deniedDirs: string[],
|
|
244
342
|
deniedFiles: string[],
|
|
343
|
+
identityScanner: HardlinkIdentityScanner,
|
|
245
344
|
): string | undefined {
|
|
246
345
|
const lexicalHit = matchLexicallyDenied(candidate, agentDir, deniedDirs, deniedFiles)
|
|
247
346
|
if (lexicalHit !== undefined) return lexicalHit
|
|
@@ -259,9 +358,10 @@ function matchHidden(
|
|
|
259
358
|
// "\"-joined paths a win32 test runner produces.
|
|
260
359
|
if (resolved === realDir || resolved.startsWith(`${realDir}${path.sep}`)) return dir
|
|
261
360
|
}
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
361
|
+
const identity = fileIdentity(resolved)
|
|
362
|
+
if (identity !== undefined && identity.nlink > 1) {
|
|
363
|
+
const hit = identityScanner.check(identity)
|
|
364
|
+
if (hit !== undefined) return hit
|
|
265
365
|
}
|
|
266
366
|
return undefined
|
|
267
367
|
}
|
|
@@ -311,39 +411,505 @@ function virtualFilesystemRoot(candidate: string): string | undefined {
|
|
|
311
411
|
return undefined
|
|
312
412
|
}
|
|
313
413
|
|
|
314
|
-
function
|
|
414
|
+
function fileIdentity(candidate: string): Pick<Stats, 'dev' | 'ino' | 'nlink'> | undefined {
|
|
315
415
|
try {
|
|
316
|
-
const stats =
|
|
317
|
-
return stats.isFile()
|
|
416
|
+
const stats = lstatSync(candidate)
|
|
417
|
+
return stats.isFile() ? stats : undefined
|
|
318
418
|
} catch {
|
|
319
|
-
return
|
|
419
|
+
return undefined
|
|
420
|
+
}
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
type HardlinkDirectory = {
|
|
424
|
+
readSync(): Dirent | null
|
|
425
|
+
statSync(): Stats
|
|
426
|
+
lstatEntrySync(name: string): Stats
|
|
427
|
+
openChildSync(name: string): HardlinkDirectory
|
|
428
|
+
finishSync(): void
|
|
429
|
+
closeSync(): void
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
type OpenedHardlinkDirectory = { reader: HardlinkDirectory; census: Stats }
|
|
433
|
+
|
|
434
|
+
function createPathDirectoryOpener(
|
|
435
|
+
openDirectory: (directory: string) => Pick<Dir, 'readSync' | 'closeSync'>,
|
|
436
|
+
lstat: (candidate: string) => Stats,
|
|
437
|
+
): (directory: string) => HardlinkDirectory {
|
|
438
|
+
const openPath = (directory: string): HardlinkDirectory => {
|
|
439
|
+
const reader = openDirectory(directory)
|
|
440
|
+
let finished = false
|
|
441
|
+
return {
|
|
442
|
+
readSync: () => reader.readSync(),
|
|
443
|
+
statSync: () => lstat(directory),
|
|
444
|
+
lstatEntrySync: (name) => lstat(path.join(directory, name)),
|
|
445
|
+
openChildSync: (name) => openPath(path.join(directory, name)),
|
|
446
|
+
finishSync() {
|
|
447
|
+
if (finished) return
|
|
448
|
+
finished = true
|
|
449
|
+
reader.closeSync()
|
|
450
|
+
},
|
|
451
|
+
closeSync() {
|
|
452
|
+
if (!finished) reader.closeSync()
|
|
453
|
+
finished = true
|
|
454
|
+
},
|
|
455
|
+
}
|
|
320
456
|
}
|
|
457
|
+
return openPath
|
|
321
458
|
}
|
|
322
459
|
|
|
323
|
-
function
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
460
|
+
function openDescriptorAnchoredDirectory(directory: string): HardlinkDirectory {
|
|
461
|
+
if (process.platform !== 'linux') {
|
|
462
|
+
throw new Error('hardlink identity traversal requires Linux descriptor anchoring')
|
|
463
|
+
}
|
|
464
|
+
const descriptor = openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
|
|
465
|
+
const anchor = `/proc/self/fd/${descriptor}`
|
|
466
|
+
let reader: Dir
|
|
467
|
+
try {
|
|
468
|
+
reader = opendirSync(anchor)
|
|
469
|
+
} catch (error) {
|
|
470
|
+
closeSync(descriptor)
|
|
471
|
+
throw error
|
|
472
|
+
}
|
|
473
|
+
let closed = false
|
|
474
|
+
let finished = false
|
|
475
|
+
return {
|
|
476
|
+
readSync: () => reader.readSync(),
|
|
477
|
+
statSync: () => fstatSync(descriptor),
|
|
478
|
+
lstatEntrySync: (name) => lstatSync(path.join(anchor, name)),
|
|
479
|
+
openChildSync: (name) => openDescriptorAnchoredDirectory(path.join(anchor, name)),
|
|
480
|
+
finishSync() {
|
|
481
|
+
if (finished) return
|
|
482
|
+
finished = true
|
|
483
|
+
reader.closeSync()
|
|
484
|
+
},
|
|
485
|
+
closeSync() {
|
|
486
|
+
if (closed) return
|
|
487
|
+
closed = true
|
|
488
|
+
let closeError: unknown
|
|
489
|
+
if (!finished) {
|
|
490
|
+
try {
|
|
491
|
+
reader.closeSync()
|
|
492
|
+
} catch (error) {
|
|
493
|
+
closeError = error
|
|
494
|
+
}
|
|
495
|
+
}
|
|
496
|
+
try {
|
|
497
|
+
closeSync(descriptor)
|
|
498
|
+
} catch (error) {
|
|
499
|
+
closeError ??= error
|
|
500
|
+
}
|
|
501
|
+
if (closeError !== undefined) throw closeError
|
|
502
|
+
},
|
|
503
|
+
}
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
type HardlinkIdentityScannerOptions = {
|
|
507
|
+
agentDir: string
|
|
508
|
+
deniedDirs: readonly string[]
|
|
509
|
+
deniedFiles: readonly string[]
|
|
510
|
+
maxEntries: number
|
|
511
|
+
openDirectory(directory: string): HardlinkDirectory
|
|
512
|
+
lstat(candidate: string): Stats
|
|
513
|
+
afterEntryLstat?(candidate: string, stats: Stats): void
|
|
514
|
+
}
|
|
515
|
+
|
|
516
|
+
class HardlinkIdentityScanner {
|
|
517
|
+
private remaining: number
|
|
518
|
+
private readonly visibleCounts = new Map<string, number>()
|
|
519
|
+
private readonly deniedIdentities = new Map<string, string>()
|
|
520
|
+
private readonly observedEntries = new Set<string>()
|
|
521
|
+
private readonly openedDirectories = new Set<string>()
|
|
522
|
+
private visibleScanned = false
|
|
523
|
+
private deniedScanned = false
|
|
524
|
+
private visibleFailure: string | undefined
|
|
525
|
+
private deniedFailure: string | undefined
|
|
526
|
+
private deniedFilesScanned = false
|
|
527
|
+
|
|
528
|
+
constructor(private readonly options: HardlinkIdentityScannerOptions) {
|
|
529
|
+
this.remaining = options.maxEntries
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
check(identity: Pick<Stats, 'dev' | 'ino' | 'nlink'>): string | undefined {
|
|
533
|
+
const key = identityKey(identity)
|
|
534
|
+
this.scanDeniedFiles()
|
|
535
|
+
if (this.deniedFailure !== undefined) return this.deniedFailure
|
|
536
|
+
const deniedFile = this.deniedIdentities.get(key)
|
|
537
|
+
if (deniedFile !== undefined) return deniedFile
|
|
538
|
+
|
|
539
|
+
this.scanDeniedTrees()
|
|
540
|
+
const deniedAlias = this.deniedIdentities.get(key)
|
|
541
|
+
if (deniedAlias !== undefined) return deniedAlias
|
|
542
|
+
if (this.deniedFailure !== undefined) return this.deniedFailure
|
|
543
|
+
|
|
544
|
+
this.scanVisibleTree()
|
|
545
|
+
if (this.visibleFailure !== undefined) return this.visibleFailure
|
|
546
|
+
if ((this.visibleCounts.get(key) ?? 0) >= identity.nlink) return undefined
|
|
547
|
+
return 'hardlink identities could not be fully accounted within the agent tree'
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
private scanDeniedFiles(): void {
|
|
551
|
+
if (this.deniedFilesScanned) return
|
|
552
|
+
this.deniedFilesScanned = true
|
|
553
|
+
for (const file of this.options.deniedFiles) {
|
|
331
554
|
try {
|
|
332
|
-
|
|
555
|
+
const stats = this.options.lstat(file)
|
|
556
|
+
if (stats.isFile()) this.deniedIdentities.set(identityKey(stats), file)
|
|
557
|
+
} catch (error) {
|
|
558
|
+
if (isNotFoundError(error)) continue
|
|
559
|
+
this.deniedFailure = `denied-file hardlink identity could not be read: ${file}`
|
|
560
|
+
return
|
|
561
|
+
}
|
|
562
|
+
}
|
|
563
|
+
}
|
|
564
|
+
|
|
565
|
+
private scanVisibleTree(): void {
|
|
566
|
+
if (this.visibleScanned) return
|
|
567
|
+
this.visibleScanned = true
|
|
568
|
+
const root = realpathRealIntendedPath(this.options.agentDir)
|
|
569
|
+
const deniedRoots = this.options.deniedDirs.map(realpathRealIntendedPath)
|
|
570
|
+
const deniedFiles = new Set(this.options.deniedFiles.map(realpathRealIntendedPath))
|
|
571
|
+
const rootStats = this.readRootStats(root, 'visible')
|
|
572
|
+
if (rootStats === undefined) return
|
|
573
|
+
const rootDirectory = this.openVerifiedDirectory(root, rootStats, 'visible')
|
|
574
|
+
if (rootDirectory === undefined) return
|
|
575
|
+
const pending: Array<{
|
|
576
|
+
directory: string
|
|
577
|
+
reader: HardlinkDirectory
|
|
578
|
+
identity: Pick<Stats, 'dev' | 'ino'>
|
|
579
|
+
census: Stats
|
|
580
|
+
agentRoot: boolean
|
|
581
|
+
}> = [{ directory: root, ...rootDirectory, identity: rootStats, agentRoot: true }]
|
|
582
|
+
const opened: Array<{ directory: string; reader: HardlinkDirectory; census: Stats }> = [
|
|
583
|
+
{ directory: root, ...rootDirectory },
|
|
584
|
+
]
|
|
585
|
+
let scanCompleted = false
|
|
586
|
+
try {
|
|
587
|
+
while (pending.length > 0) {
|
|
588
|
+
const current = pending.pop()
|
|
589
|
+
if (current === undefined) break
|
|
590
|
+
const completed = this.forEachEntry(current, 'visible', (entry, stats) => {
|
|
591
|
+
const entryPath = path.join(current.directory, entry.name)
|
|
592
|
+
if (current.agentRoot && HARDLINK_SCAN_EXCLUDED_AGENT_DIRS.has(entry.name)) return true
|
|
593
|
+
if (deniedFiles.has(entryPath) || deniedRoots.some((deniedRoot) => isPathAtOrBelow(entryPath, deniedRoot))) {
|
|
594
|
+
return true
|
|
595
|
+
}
|
|
596
|
+
if (stats.isDirectory()) {
|
|
597
|
+
const child = this.openVerifiedChild(current, entry.name, stats, 'visible')
|
|
598
|
+
if (child === undefined) return false
|
|
599
|
+
const openedChild = { directory: entryPath, ...child }
|
|
600
|
+
pending.push({ ...openedChild, identity: stats, agentRoot: false })
|
|
601
|
+
opened.push(openedChild)
|
|
602
|
+
} else if (stats.isFile()) {
|
|
603
|
+
this.recordVisibleFile(stats)
|
|
604
|
+
}
|
|
605
|
+
return true
|
|
606
|
+
})
|
|
607
|
+
if (!completed) return
|
|
608
|
+
}
|
|
609
|
+
scanCompleted = true
|
|
610
|
+
} finally {
|
|
611
|
+
this.verifyAndCloseDirectories(opened, 'visible', scanCompleted)
|
|
612
|
+
}
|
|
613
|
+
}
|
|
614
|
+
|
|
615
|
+
private scanDeniedTrees(): void {
|
|
616
|
+
if (this.deniedScanned) return
|
|
617
|
+
this.deniedScanned = true
|
|
618
|
+
for (const deniedDir of this.options.deniedDirs) {
|
|
619
|
+
let rootStats: Stats
|
|
620
|
+
let root: string
|
|
621
|
+
try {
|
|
622
|
+
root = realpathRealIntendedPath(deniedDir)
|
|
623
|
+
rootStats = this.options.lstat(root)
|
|
624
|
+
} catch (error) {
|
|
625
|
+
if (isNotFoundError(error)) continue
|
|
626
|
+
this.deniedFailure = `denied-directory hardlink identity could not be read: ${deniedDir}`
|
|
627
|
+
return
|
|
628
|
+
}
|
|
629
|
+
if (!rootStats.isDirectory()) {
|
|
630
|
+
this.deniedFailure = `denied-directory hardlink identity root is not a directory: ${deniedDir}`
|
|
631
|
+
return
|
|
632
|
+
}
|
|
633
|
+
const rootDirectory = this.openVerifiedDirectory(root, rootStats, 'denied')
|
|
634
|
+
if (rootDirectory === undefined) return
|
|
635
|
+
const pending: Array<{
|
|
636
|
+
directory: string
|
|
637
|
+
reader: HardlinkDirectory
|
|
638
|
+
identity: Pick<Stats, 'dev' | 'ino'>
|
|
639
|
+
census: Stats
|
|
640
|
+
}> = [{ directory: root, ...rootDirectory, identity: rootStats }]
|
|
641
|
+
const opened: Array<{ directory: string; reader: HardlinkDirectory; census: Stats }> = [
|
|
642
|
+
{ directory: root, ...rootDirectory },
|
|
643
|
+
]
|
|
644
|
+
let scanCompleted = false
|
|
645
|
+
try {
|
|
646
|
+
while (pending.length > 0) {
|
|
647
|
+
const current = pending.pop()
|
|
648
|
+
if (current === undefined) break
|
|
649
|
+
const completed = this.forEachEntry(current, 'denied', (entry, stats) => {
|
|
650
|
+
const entryPath = path.join(current.directory, entry.name)
|
|
651
|
+
if (stats.isDirectory()) {
|
|
652
|
+
const child = this.openVerifiedChild(current, entry.name, stats, 'denied')
|
|
653
|
+
if (child === undefined) return false
|
|
654
|
+
const openedChild = { directory: entryPath, ...child }
|
|
655
|
+
pending.push({ ...openedChild, identity: stats })
|
|
656
|
+
opened.push(openedChild)
|
|
657
|
+
} else if (stats.isFile()) {
|
|
658
|
+
this.recordDeniedFile(stats, deniedDir)
|
|
659
|
+
}
|
|
660
|
+
return true
|
|
661
|
+
})
|
|
662
|
+
if (!completed) return
|
|
663
|
+
}
|
|
664
|
+
scanCompleted = true
|
|
665
|
+
} finally {
|
|
666
|
+
this.verifyAndCloseDirectories(opened, 'denied', scanCompleted)
|
|
667
|
+
}
|
|
668
|
+
}
|
|
669
|
+
}
|
|
670
|
+
|
|
671
|
+
private forEachEntry(
|
|
672
|
+
current: {
|
|
673
|
+
directory: string
|
|
674
|
+
reader: HardlinkDirectory
|
|
675
|
+
identity: Pick<Stats, 'dev' | 'ino'>
|
|
676
|
+
},
|
|
677
|
+
surface: 'visible' | 'denied',
|
|
678
|
+
visit: (entry: Dirent, stats: Stats) => boolean,
|
|
679
|
+
): boolean {
|
|
680
|
+
let completed = true
|
|
681
|
+
try {
|
|
682
|
+
while (true) {
|
|
683
|
+
const entry = current.reader.readSync()
|
|
684
|
+
if (entry === null) break
|
|
685
|
+
if (!this.consumeEntry(surface)) {
|
|
686
|
+
completed = false
|
|
687
|
+
break
|
|
688
|
+
}
|
|
689
|
+
if (!this.claimEntryObservation(current.identity, entry.name, surface)) {
|
|
690
|
+
completed = false
|
|
691
|
+
break
|
|
692
|
+
}
|
|
693
|
+
let stats: Stats
|
|
694
|
+
try {
|
|
695
|
+
stats = current.reader.lstatEntrySync(entry.name)
|
|
696
|
+
this.options.afterEntryLstat?.(path.join(current.directory, entry.name), stats)
|
|
697
|
+
} catch {
|
|
698
|
+
this.recordEntryFailure(path.join(current.directory, entry.name), surface)
|
|
699
|
+
completed = false
|
|
700
|
+
break
|
|
701
|
+
}
|
|
702
|
+
if (!visit(entry, stats)) {
|
|
703
|
+
completed = false
|
|
704
|
+
break
|
|
705
|
+
}
|
|
706
|
+
try {
|
|
707
|
+
const confirmed = current.reader.lstatEntrySync(entry.name)
|
|
708
|
+
if (!sameDirectoryEntry(stats, confirmed)) {
|
|
709
|
+
this.recordEntryFailure(path.join(current.directory, entry.name), surface)
|
|
710
|
+
completed = false
|
|
711
|
+
break
|
|
712
|
+
}
|
|
713
|
+
} catch {
|
|
714
|
+
this.recordEntryFailure(path.join(current.directory, entry.name), surface)
|
|
715
|
+
completed = false
|
|
716
|
+
break
|
|
717
|
+
}
|
|
718
|
+
}
|
|
719
|
+
} catch {
|
|
720
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
721
|
+
completed = false
|
|
722
|
+
} finally {
|
|
723
|
+
try {
|
|
724
|
+
current.reader.finishSync()
|
|
333
725
|
} catch {
|
|
334
|
-
|
|
726
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
727
|
+
completed = false
|
|
728
|
+
}
|
|
729
|
+
}
|
|
730
|
+
return completed
|
|
731
|
+
}
|
|
732
|
+
|
|
733
|
+
private readRootStats(directory: string, surface: 'visible' | 'denied'): Stats | undefined {
|
|
734
|
+
try {
|
|
735
|
+
const stats = this.options.lstat(directory)
|
|
736
|
+
if (!stats.isDirectory()) {
|
|
737
|
+
this.recordDirectoryFailure(directory, surface)
|
|
738
|
+
return undefined
|
|
739
|
+
}
|
|
740
|
+
return stats
|
|
741
|
+
} catch {
|
|
742
|
+
this.recordDirectoryFailure(directory, surface)
|
|
743
|
+
return undefined
|
|
744
|
+
}
|
|
745
|
+
}
|
|
746
|
+
|
|
747
|
+
private openVerifiedDirectory(
|
|
748
|
+
directory: string,
|
|
749
|
+
expected: Pick<Stats, 'dev' | 'ino'>,
|
|
750
|
+
surface: 'visible' | 'denied',
|
|
751
|
+
): OpenedHardlinkDirectory | undefined {
|
|
752
|
+
let reader: HardlinkDirectory | undefined
|
|
753
|
+
try {
|
|
754
|
+
reader = this.options.openDirectory(directory)
|
|
755
|
+
const opened = reader.statSync()
|
|
756
|
+
if (!opened.isDirectory() || opened.dev !== expected.dev || opened.ino !== expected.ino) {
|
|
757
|
+
this.recordDirectoryFailure(directory, surface)
|
|
758
|
+
reader.closeSync()
|
|
759
|
+
return undefined
|
|
760
|
+
}
|
|
761
|
+
if (!this.claimDirectoryIdentity(opened, directory, surface)) {
|
|
762
|
+
reader.closeSync()
|
|
763
|
+
return undefined
|
|
335
764
|
}
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
765
|
+
return { reader, census: opened }
|
|
766
|
+
} catch {
|
|
767
|
+
try {
|
|
768
|
+
reader?.closeSync()
|
|
769
|
+
} catch {}
|
|
770
|
+
this.recordDirectoryFailure(directory, surface)
|
|
771
|
+
return undefined
|
|
772
|
+
}
|
|
773
|
+
}
|
|
774
|
+
|
|
775
|
+
private openVerifiedChild(
|
|
776
|
+
parent: { directory: string; reader: HardlinkDirectory },
|
|
777
|
+
name: string,
|
|
778
|
+
expected: Pick<Stats, 'dev' | 'ino'>,
|
|
779
|
+
surface: 'visible' | 'denied',
|
|
780
|
+
): OpenedHardlinkDirectory | undefined {
|
|
781
|
+
const directory = path.join(parent.directory, name)
|
|
782
|
+
let reader: HardlinkDirectory | undefined
|
|
783
|
+
try {
|
|
784
|
+
reader = parent.reader.openChildSync(name)
|
|
785
|
+
const opened = reader.statSync()
|
|
786
|
+
if (!opened.isDirectory() || opened.dev !== expected.dev || opened.ino !== expected.ino) {
|
|
787
|
+
this.recordDirectoryFailure(directory, surface)
|
|
788
|
+
reader.closeSync()
|
|
789
|
+
return undefined
|
|
790
|
+
}
|
|
791
|
+
if (!this.claimDirectoryIdentity(opened, directory, surface)) {
|
|
792
|
+
reader.closeSync()
|
|
793
|
+
return undefined
|
|
794
|
+
}
|
|
795
|
+
return { reader, census: opened }
|
|
796
|
+
} catch {
|
|
797
|
+
try {
|
|
798
|
+
reader?.closeSync()
|
|
799
|
+
} catch {}
|
|
800
|
+
this.recordDirectoryFailure(directory, surface)
|
|
801
|
+
return undefined
|
|
802
|
+
}
|
|
803
|
+
}
|
|
804
|
+
|
|
805
|
+
private verifyAndCloseDirectories(
|
|
806
|
+
opened: Array<{ directory: string; reader: HardlinkDirectory; census: Stats }>,
|
|
807
|
+
surface: 'visible' | 'denied',
|
|
808
|
+
verify: boolean,
|
|
809
|
+
): void {
|
|
810
|
+
for (const current of opened.reverse()) {
|
|
811
|
+
if (verify) {
|
|
812
|
+
try {
|
|
813
|
+
if (!sameDirectoryCensus(current.census, current.reader.statSync())) {
|
|
814
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
815
|
+
}
|
|
816
|
+
} catch {
|
|
817
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
342
818
|
}
|
|
343
819
|
}
|
|
820
|
+
try {
|
|
821
|
+
current.reader.closeSync()
|
|
822
|
+
} catch {
|
|
823
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
824
|
+
}
|
|
344
825
|
}
|
|
345
826
|
}
|
|
346
|
-
|
|
827
|
+
|
|
828
|
+
private recordDirectoryFailure(directory: string, surface: 'visible' | 'denied'): void {
|
|
829
|
+
const reason = `${surface} hardlink identity directory could not be read: ${directory}`
|
|
830
|
+
if (surface === 'visible') this.visibleFailure = reason
|
|
831
|
+
else this.deniedFailure = reason
|
|
832
|
+
}
|
|
833
|
+
|
|
834
|
+
private consumeEntry(surface: 'visible' | 'denied'): boolean {
|
|
835
|
+
if (this.remaining > 0) {
|
|
836
|
+
this.remaining -= 1
|
|
837
|
+
return true
|
|
838
|
+
}
|
|
839
|
+
const reason = `hardlink identity entry limit exceeded (${this.options.maxEntries})`
|
|
840
|
+
if (surface === 'visible') this.visibleFailure = reason
|
|
841
|
+
else this.deniedFailure = reason
|
|
842
|
+
return false
|
|
843
|
+
}
|
|
844
|
+
|
|
845
|
+
private recordEntryFailure(candidate: string, surface: 'visible' | 'denied'): void {
|
|
846
|
+
const reason = `${surface} hardlink identity could not be read: ${candidate}`
|
|
847
|
+
if (surface === 'visible') this.visibleFailure = reason
|
|
848
|
+
else this.deniedFailure = reason
|
|
849
|
+
}
|
|
850
|
+
|
|
851
|
+
private claimDirectoryIdentity(
|
|
852
|
+
identity: Pick<Stats, 'dev' | 'ino'>,
|
|
853
|
+
directory: string,
|
|
854
|
+
surface: 'visible' | 'denied',
|
|
855
|
+
): boolean {
|
|
856
|
+
const key = identityKey(identity)
|
|
857
|
+
if (this.openedDirectories.has(key)) {
|
|
858
|
+
this.recordDirectoryFailure(directory, surface)
|
|
859
|
+
return false
|
|
860
|
+
}
|
|
861
|
+
this.openedDirectories.add(key)
|
|
862
|
+
return true
|
|
863
|
+
}
|
|
864
|
+
|
|
865
|
+
private claimEntryObservation(
|
|
866
|
+
directoryIdentity: Pick<Stats, 'dev' | 'ino'>,
|
|
867
|
+
name: string,
|
|
868
|
+
surface: 'visible' | 'denied',
|
|
869
|
+
): boolean {
|
|
870
|
+
const key = `${identityKey(directoryIdentity)}:${JSON.stringify(name)}`
|
|
871
|
+
if (this.observedEntries.has(key)) {
|
|
872
|
+
this.recordEntryFailure(name, surface)
|
|
873
|
+
return false
|
|
874
|
+
}
|
|
875
|
+
this.observedEntries.add(key)
|
|
876
|
+
return true
|
|
877
|
+
}
|
|
878
|
+
|
|
879
|
+
private recordVisibleFile(stats: Stats): void {
|
|
880
|
+
const key = identityKey(stats)
|
|
881
|
+
this.visibleCounts.set(key, (this.visibleCounts.get(key) ?? 0) + 1)
|
|
882
|
+
}
|
|
883
|
+
|
|
884
|
+
private recordDeniedFile(stats: Stats, deniedRoot: string): void {
|
|
885
|
+
this.deniedIdentities.set(identityKey(stats), deniedRoot)
|
|
886
|
+
}
|
|
887
|
+
}
|
|
888
|
+
|
|
889
|
+
function identityKey(identity: Pick<Stats, 'dev' | 'ino'>): string {
|
|
890
|
+
return `${identity.dev}:${identity.ino}`
|
|
891
|
+
}
|
|
892
|
+
|
|
893
|
+
function sameDirectoryEntry(before: Stats, after: Stats): boolean {
|
|
894
|
+
return (
|
|
895
|
+
before.dev === after.dev && before.ino === after.ino && before.mode === after.mode && before.nlink === after.nlink
|
|
896
|
+
)
|
|
897
|
+
}
|
|
898
|
+
|
|
899
|
+
function sameDirectoryCensus(before: Stats, after: Stats): boolean {
|
|
900
|
+
return (
|
|
901
|
+
before.dev === after.dev &&
|
|
902
|
+
before.ino === after.ino &&
|
|
903
|
+
before.mode === after.mode &&
|
|
904
|
+
before.nlink === after.nlink &&
|
|
905
|
+
before.size === after.size &&
|
|
906
|
+
before.mtimeMs === after.mtimeMs &&
|
|
907
|
+
before.ctimeMs === after.ctimeMs
|
|
908
|
+
)
|
|
909
|
+
}
|
|
910
|
+
|
|
911
|
+
function isPathAtOrBelow(candidate: string, root: string): boolean {
|
|
912
|
+
return candidate === root || candidate.startsWith(`${root}${path.sep}`)
|
|
347
913
|
}
|
|
348
914
|
|
|
349
915
|
function isPathKey(key: string | undefined): boolean {
|