typeclaw 0.45.1 → 0.46.1
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 +3 -2
- package/src/agent/git-nudge.ts +2 -1
- package/src/agent/index.ts +44 -30
- package/src/agent/live-subagents.ts +18 -0
- package/src/agent/multimodal/index.ts +1 -1
- package/src/agent/multimodal/look-at.ts +78 -44
- package/src/agent/multimodal/looker.ts +161 -39
- package/src/agent/network/response-body.ts +26 -0
- package/src/agent/network/safe-http.ts +207 -0
- package/src/agent/plugin-tools.ts +377 -157
- package/src/agent/provider-error.ts +52 -1
- package/src/agent/restart/index.ts +61 -40
- package/src/agent/restart-handoff/index.ts +73 -4
- package/src/agent/reviewer-bash-policy.ts +42 -1
- package/src/agent/session-origin.ts +2 -0
- package/src/agent/subagent-drain.ts +117 -7
- package/src/agent/subagents.ts +49 -16
- package/src/agent/throttle-circuit.ts +25 -5
- package/src/agent/tool-error-remediation.ts +72 -0
- package/src/agent/tool-file-safety.ts +1310 -0
- package/src/agent/tools/channel-fetch-attachment.ts +10 -3
- package/src/agent/tools/ddg.ts +16 -2
- package/src/agent/tools/post-github-review.ts +199 -0
- package/src/agent/tools/spawn-subagent.ts +21 -18
- package/src/agent/tools/webfetch/fetch.ts +163 -183
- package/src/agent/tools/webfetch/tool.ts +2 -3
- package/src/agent/tools/websearch.ts +23 -2
- package/src/agent/tools-without-local-file-operands.ts +30 -0
- package/src/agent/turn-runner.ts +86 -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 +85 -44
- package/src/bundled-plugins/backup/runner.ts +85 -1
- package/src/bundled-plugins/doc-render/render.ts +93 -12
- package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
- package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
- package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
- 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 +207 -132
- package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
- package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
- package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
- package/src/bundled-plugins/memory/README.md +32 -11
- package/src/bundled-plugins/memory/append-tool.ts +15 -8
- package/src/bundled-plugins/memory/citations.ts +22 -9
- package/src/bundled-plugins/memory/dreaming.ts +13 -8
- package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
- package/src/bundled-plugins/memory/index.ts +0 -4
- package/src/bundled-plugins/memory/load-memory.ts +8 -3
- package/src/bundled-plugins/memory/provenance-index.ts +717 -0
- package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
- package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
- package/src/bundled-plugins/memory/search-tool.ts +163 -60
- package/src/bundled-plugins/memory/stream-events.ts +2 -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 +126 -13
- package/src/bundled-plugins/researcher/write-report.ts +8 -5
- package/src/bundled-plugins/reviewer/index.ts +2 -2
- package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
- package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
- package/src/bundled-plugins/scout/scout.ts +8 -0
- package/src/bundled-plugins/security/index.ts +4 -4
- package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
- package/src/bundled-plugins/security/policies/private-surface-read.ts +787 -36
- package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
- package/src/bundled-plugins/security/policies/ssrf.ts +147 -42
- package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
- package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
- package/src/channels/adapters/discord-bot.ts +66 -6
- package/src/channels/adapters/discord-channel-resolver.ts +91 -23
- package/src/channels/adapters/discord-id.ts +4 -0
- package/src/channels/adapters/discord-resolver-cache.ts +41 -0
- package/src/channels/adapters/discord.ts +57 -7
- package/src/channels/adapters/github/auth-app.ts +41 -12
- package/src/channels/adapters/github/inbound.ts +11 -0
- package/src/channels/adapters/github/index.ts +71 -65
- 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/github/review-submitter.ts +302 -0
- package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
- package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
- package/src/channels/adapters/kakaotalk-typing.ts +17 -15
- package/src/channels/adapters/slack-attachment-download.ts +71 -0
- package/src/channels/adapters/slack-bot-edit.ts +85 -20
- package/src/channels/adapters/slack-bot.ts +26 -10
- package/src/channels/adapters/slack-classify.ts +21 -2
- package/src/channels/adapters/slack-format.ts +245 -0
- package/src/channels/adapters/slack.ts +59 -7
- package/src/channels/adapters/telegram-bot.ts +18 -5
- package/src/channels/adapters/webex-bot.ts +8 -3
- package/src/channels/adapters/webex.ts +8 -3
- package/src/channels/fetch-attachment.ts +43 -0
- package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
- package/src/channels/github-token-bridge.ts +12 -6
- package/src/channels/manager.ts +9 -0
- package/src/channels/router.ts +248 -6
- package/src/channels/types.ts +28 -1
- package/src/cli/channel.ts +1 -1
- package/src/cli/init.ts +1 -1
- package/src/cli/model.ts +57 -7
- package/src/compose/stop.ts +17 -5
- package/src/config/config.ts +6 -6
- package/src/config/models-mutation.ts +13 -1
- package/src/config/providers.ts +176 -0
- package/src/container/docker-app.ts +42 -13
- package/src/container/start.ts +62 -10
- package/src/cron/bridge.ts +9 -2
- package/src/doctor/checks.ts +8 -3
- package/src/doctor/commit.ts +2 -1
- package/src/doctor/file-ownership.ts +52 -0
- package/src/dreams/git.ts +2 -1
- package/src/git/bound-gc-config.ts +82 -0
- package/src/git/hookless.ts +5 -0
- package/src/git/reconcile-ignored.ts +18 -5
- package/src/git/system-commit.ts +12 -6
- package/src/hostd/spawn.ts +133 -47
- package/src/init/dockerfile.ts +99 -5
- package/src/init/index.ts +17 -5
- package/src/init/models-dev.ts +4 -0
- package/src/init/validate-api-key.ts +2 -0
- package/src/inspect/replay.ts +21 -9
- package/src/inspect/session-list.ts +71 -33
- package/src/mcp/tools.ts +17 -3
- package/src/network/internal-destinations.ts +267 -0
- package/src/permissions/builtins.ts +3 -1
- package/src/plugin/context.ts +2 -0
- package/src/plugin/index.ts +1 -0
- package/src/plugin/manager.ts +4 -0
- package/src/plugin/types.ts +22 -0
- package/src/run/index.ts +40 -0
- package/src/run/llm-fetch-observer.ts +41 -4
- package/src/sandbox/build.ts +37 -15
- package/src/sandbox/canonical-secrets.ts +18 -0
- package/src/sandbox/env-exposure.ts +83 -0
- package/src/sandbox/errors.ts +13 -6
- package/src/sandbox/hidden-paths.ts +102 -44
- package/src/sandbox/index.ts +22 -4
- package/src/sandbox/package-install.ts +3 -27
- package/src/sandbox/policy.ts +16 -28
- package/src/sandbox/privileged-runtime.ts +256 -0
- package/src/sandbox/session-tmp.ts +8 -2
- package/src/sandbox/writable-zones.ts +204 -140
- package/src/secrets/index.ts +8 -0
- package/src/secrets/refresh-provider-oauth.ts +128 -0
- package/src/server/command-runner.ts +48 -4
- package/src/server/index.ts +4 -0
- package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
- package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
- package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
- package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
- package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
- package/src/skills/typeclaw-config/SKILL.md +27 -11
- package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
- package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
- package/src/skills/typeclaw-memory/SKILL.md +9 -3
- package/src/skills/typeclaw-permissions/SKILL.md +36 -19
- package/src/skills/typeclaw-plugins/SKILL.md +37 -0
- package/src/usage/scan.ts +11 -2
- package/typeclaw.schema.json +25 -0
|
@@ -1,7 +1,29 @@
|
|
|
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'
|
|
14
|
+
import { homedir } from 'node:os'
|
|
2
15
|
import path from 'node:path'
|
|
16
|
+
import { fileURLToPath } from 'node:url'
|
|
3
17
|
|
|
4
|
-
import
|
|
18
|
+
import { TOOLS_WITHOUT_LOCAL_FILE_OPERANDS } from '@/agent/tools-without-local-file-operands'
|
|
19
|
+
import type { ToolFileOperands } from '@/plugin'
|
|
20
|
+
import {
|
|
21
|
+
CANONICAL_AGENT_SECRET_DIRS,
|
|
22
|
+
CANONICAL_AGENT_SECRET_FILES,
|
|
23
|
+
CANONICAL_HOME_SECRET_DIRS,
|
|
24
|
+
CANONICAL_HOME_SECRET_FILES,
|
|
25
|
+
type HiddenPaths,
|
|
26
|
+
} from '@/sandbox'
|
|
5
27
|
|
|
6
28
|
import type { SecurityBlock } from '../policy'
|
|
7
29
|
|
|
@@ -12,10 +34,20 @@ export const GUARD_PRIVATE_SURFACE_READ = 'privateSurfaceRead'
|
|
|
12
34
|
// scanned, so a new file-reading tool — bundled or third-party — is covered
|
|
13
35
|
// the day it ships without a whitelist edit. web_search/web_fetch take URLs, not
|
|
14
36
|
// local paths, and the path-plausibility filter keeps their args from matching.
|
|
15
|
-
|
|
37
|
+
//
|
|
38
|
+
// TOOLS_WITHOUT_LOCAL_FILE_OPERANDS is the SAME set the file-operand scanner
|
|
39
|
+
// skips: first-party tools whose args are only remote ids/control tokens
|
|
40
|
+
// (channel/stream/subagent/role reads). Without this, an id equal to a working
|
|
41
|
+
// dir — channel_read({ workspace: "memory" }) — would resolve to /agent/memory
|
|
42
|
+
// and be wrongly blocked here even after the scanner cleared it. Sharing one set
|
|
43
|
+
// keeps both enforcement points agreeing on which tools read no local path.
|
|
44
|
+
const UNSCANNED_TOOLS = new Set(['bash', ...TOOLS_WITHOUT_LOCAL_FILE_OPERANDS])
|
|
45
|
+
const VIRTUAL_FILESYSTEM_ROOTS = ['/proc', '/sys', '/dev', '/run'] as const
|
|
46
|
+
const HARDLINK_SCAN_EXCLUDED_AGENT_DIRS = new Set(['.git', '.gitstore', 'node_modules'])
|
|
16
47
|
|
|
17
48
|
// The bash sandbox hides the role's private surface — the working DIRECTORIES
|
|
18
|
-
// (workspace/, memory/, sessions/)
|
|
49
|
+
// (workspace/, memory/, sessions/), unconditional credential directories, and
|
|
50
|
+
// secret FILES (.env, secrets.json, auth.json) —
|
|
19
51
|
// via bwrap masks, but every non-bash tool runs in the main process, outside
|
|
20
52
|
// any sandbox. find_entry, look_at, and the channel attachment tools all read
|
|
21
53
|
// files by a caller-supplied path, so without a guard a restricted role could
|
|
@@ -26,36 +58,41 @@ const UNSCANNED_TOOLS = new Set(['bash'])
|
|
|
26
58
|
// It covers the full deny-list rather than delegating secret files to the
|
|
27
59
|
// secretExfilRead guard: that guard only inspects read/grep/find/ls (not
|
|
28
60
|
// edit/write/look_at/channel_send) and is acknowledgement-bypassable, so
|
|
29
|
-
// delegating would leave
|
|
61
|
+
// delegating would leave canonical credential files reachable through uncovered
|
|
30
62
|
// tools — exactly the gap the bash masks close. secretExfilRead remains as
|
|
31
63
|
// independent defense in depth for the four tools it does cover.
|
|
32
64
|
//
|
|
33
|
-
// Posture is FAIL-CLOSED
|
|
65
|
+
// Posture is FAIL-CLOSED: it does not whitelist a known
|
|
34
66
|
// set of tools (that fails open the moment a new reader is added). It scans
|
|
35
67
|
// every arg of every non-bash tool — recursively, since paths hide in nested
|
|
36
68
|
// shapes like look_at's images[].path and channel_send's attachments[].path —
|
|
37
69
|
// and blocks any string that resolves to (a secret file) or under (a hidden
|
|
38
70
|
// directory) the deny-list.
|
|
39
|
-
export function checkPrivateSurfaceReadGuard(
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
71
|
+
export function checkPrivateSurfaceReadGuard(
|
|
72
|
+
options: {
|
|
73
|
+
tool: string
|
|
74
|
+
args: Record<string, unknown>
|
|
75
|
+
agentDir: string
|
|
76
|
+
hidden: HiddenPaths
|
|
77
|
+
fileOperands?: ToolFileOperands
|
|
78
|
+
},
|
|
79
|
+
hooks: PrivateSurfaceIdentityScanHooks = {},
|
|
80
|
+
): SecurityBlock | undefined {
|
|
81
|
+
const { tool, args, agentDir, hidden, fileOperands } = options
|
|
46
82
|
if (UNSCANNED_TOOLS.has(tool)) return undefined
|
|
47
|
-
const deniedDirs = hidden
|
|
48
|
-
const deniedFiles = hidden.files
|
|
83
|
+
const { deniedDirs, deniedFiles } = deniedSurface(agentDir, hidden)
|
|
49
84
|
if (deniedDirs.length === 0 && deniedFiles.length === 0) return undefined
|
|
85
|
+
const identityScanner = createHardlinkIdentityScanner(agentDir, deniedDirs, deniedFiles, hooks)
|
|
50
86
|
|
|
51
|
-
|
|
52
|
-
|
|
87
|
+
const nonFile = fileOperands?.nonFile === undefined ? undefined : new Set(fileOperands.nonFile)
|
|
88
|
+
for (const candidate of collectPathCandidates(args, tool, nonFile)) {
|
|
89
|
+
const hit = matchHidden(candidate, agentDir, deniedDirs, deniedFiles, identityScanner)
|
|
53
90
|
if (hit !== undefined) {
|
|
54
91
|
return {
|
|
55
92
|
block: true,
|
|
56
93
|
reason: [
|
|
57
|
-
`Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: argument \`${candidate}\` resolves to ${hit}, which is
|
|
58
|
-
'The bash sandbox masks the same path;
|
|
94
|
+
`Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: argument \`${candidate}\` resolves to ${hit}, which is not available to LLM tools.`,
|
|
95
|
+
'The bash sandbox masks the same path. Privileged roles cannot bypass canonical agent credential files; use host-side redacted diagnostics such as `typeclaw doctor`, `typeclaw provider list`, or `typeclaw channel list` instead.',
|
|
59
96
|
].join(' '),
|
|
60
97
|
}
|
|
61
98
|
}
|
|
@@ -63,6 +100,97 @@ export function checkPrivateSurfaceReadGuard(options: {
|
|
|
63
100
|
return undefined
|
|
64
101
|
}
|
|
65
102
|
|
|
103
|
+
type PrivateSurfaceIdentityOptions = {
|
|
104
|
+
tool: string
|
|
105
|
+
agentDir: string
|
|
106
|
+
hidden: HiddenPaths
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
export type PrivateSurfaceIdentityScanHooks = {
|
|
110
|
+
maxEntries?: number
|
|
111
|
+
openDirectory?(directory: string): Pick<Dir, 'readSync' | 'closeSync'>
|
|
112
|
+
lstat?(candidate: string): Stats
|
|
113
|
+
afterEntryLstat?(candidate: string, stats: Stats): void
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
export type PrivateSurfaceIdentityVerifier = {
|
|
117
|
+
check(identity: Pick<Stats, 'dev' | 'ino' | 'nlink'>): SecurityBlock | undefined
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
export function createPrivateSurfaceReadIdentityVerifier(
|
|
121
|
+
options: PrivateSurfaceIdentityOptions,
|
|
122
|
+
hooks: PrivateSurfaceIdentityScanHooks = {},
|
|
123
|
+
): PrivateSurfaceIdentityVerifier {
|
|
124
|
+
const { deniedDirs, deniedFiles } = deniedSurface(options.agentDir, options.hidden)
|
|
125
|
+
const scanner = createHardlinkIdentityScanner(options.agentDir, deniedDirs, deniedFiles, hooks)
|
|
126
|
+
return {
|
|
127
|
+
check(identity) {
|
|
128
|
+
if (identity.nlink <= 1) return undefined
|
|
129
|
+
const hit = scanner.check(identity)
|
|
130
|
+
return hit === undefined ? undefined : privateSurfaceBlock(options.tool, hit)
|
|
131
|
+
},
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
export function checkPrivateSurfaceReadIdentityGuard(
|
|
136
|
+
options: PrivateSurfaceIdentityOptions & { identity: Pick<Stats, 'dev' | 'ino' | 'nlink'> },
|
|
137
|
+
hooks: PrivateSurfaceIdentityScanHooks = {},
|
|
138
|
+
): SecurityBlock | undefined {
|
|
139
|
+
return createPrivateSurfaceReadIdentityVerifier(options, hooks).check(options.identity)
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function createHardlinkIdentityScanner(
|
|
143
|
+
agentDir: string,
|
|
144
|
+
deniedDirs: readonly string[],
|
|
145
|
+
deniedFiles: readonly string[],
|
|
146
|
+
hooks: PrivateSurfaceIdentityScanHooks,
|
|
147
|
+
): HardlinkIdentityScanner {
|
|
148
|
+
const lstat = hooks.lstat ?? lstatSync
|
|
149
|
+
return new HardlinkIdentityScanner({
|
|
150
|
+
agentDir,
|
|
151
|
+
deniedDirs,
|
|
152
|
+
deniedFiles,
|
|
153
|
+
maxEntries: hooks.maxEntries ?? MAX_HARDLINK_IDENTITY_ENTRIES,
|
|
154
|
+
openDirectory:
|
|
155
|
+
hooks.openDirectory === undefined
|
|
156
|
+
? openDescriptorAnchoredDirectory
|
|
157
|
+
: createPathDirectoryOpener(hooks.openDirectory, lstat),
|
|
158
|
+
lstat,
|
|
159
|
+
afterEntryLstat: hooks.afterEntryLstat,
|
|
160
|
+
})
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
function deniedSurface(agentDir: string, hidden: HiddenPaths): { deniedDirs: string[]; deniedFiles: string[] } {
|
|
164
|
+
return {
|
|
165
|
+
deniedDirs: [
|
|
166
|
+
...new Set([
|
|
167
|
+
...hidden.dirs,
|
|
168
|
+
...CANONICAL_AGENT_SECRET_DIRS.map((dir) => path.join(agentDir, dir)),
|
|
169
|
+
...CANONICAL_HOME_SECRET_DIRS.map((dir) => path.join(homedir(), dir)),
|
|
170
|
+
]),
|
|
171
|
+
],
|
|
172
|
+
// Keep runtime-owned credential stores independent of role-derived
|
|
173
|
+
// visibility so a partially-wired caller cannot expose raw credentials.
|
|
174
|
+
deniedFiles: [
|
|
175
|
+
...new Set([
|
|
176
|
+
...hidden.files,
|
|
177
|
+
...CANONICAL_AGENT_SECRET_FILES.map((file) => path.join(agentDir, file)),
|
|
178
|
+
...CANONICAL_HOME_SECRET_FILES.map((file) => path.join(homedir(), file)),
|
|
179
|
+
]),
|
|
180
|
+
],
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
function privateSurfaceBlock(tool: string, hit: string): SecurityBlock {
|
|
185
|
+
return {
|
|
186
|
+
block: true,
|
|
187
|
+
reason: [
|
|
188
|
+
`Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: input inode aliases ${hit}, which is not available to LLM tools.`,
|
|
189
|
+
'The bash sandbox masks the same path. Privileged roles cannot bypass canonical agent credential files; use host-side redacted diagnostics instead.',
|
|
190
|
+
].join(' '),
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
|
|
66
194
|
// Field names whose values are ALWAYS free text (prose/queries/ids), NEVER a
|
|
67
195
|
// filesystem path, for EVERY tool. Scanning them caused false positives: a
|
|
68
196
|
// guest's `channel_reply({ text: "the memory leak" })` or `web_search({ query:
|
|
@@ -95,13 +223,12 @@ const NON_PATH_KEYS = new Set([
|
|
|
95
223
|
'newText',
|
|
96
224
|
// memory append tool: fragment topic is free text.
|
|
97
225
|
'topic',
|
|
98
|
-
// channel_send/channel_reply attachments[].filename and
|
|
99
|
-
// channel_fetch_attachment.filename: display-only metadata (defaults to the
|
|
100
|
-
// basename of the real `path`), never the file location the guard cares
|
|
101
|
-
// about — `attachments[].path` carries that and is NOT exempted.
|
|
102
|
-
'filename',
|
|
103
226
|
])
|
|
104
227
|
|
|
228
|
+
const PATH_KEYS = /(?:^|[_-])(path|filepath|file)$/i
|
|
229
|
+
const CAMEL_PATH_KEYS = /(?:Path|Filepath|File)$/
|
|
230
|
+
const MAX_HARDLINK_IDENTITY_ENTRIES = 4_096
|
|
231
|
+
|
|
105
232
|
// Keys that are free text in SPECIFIC tools but path-bearing in others, so a
|
|
106
233
|
// global denylist would either over-block or open a bypass. Scoped per tool:
|
|
107
234
|
// - grep.pattern : a regex/search string (e.g. "sessions"), NOT a path.
|
|
@@ -117,37 +244,73 @@ const NON_PATH_KEYS = new Set([
|
|
|
117
244
|
// (or grep gaining a new key) scans everything.
|
|
118
245
|
const FREE_TEXT_KEYS_BY_TOOL: Record<string, ReadonlySet<string>> = {
|
|
119
246
|
grep: new Set(['pattern']),
|
|
247
|
+
// These channel tools use filename only as attachment display metadata. The
|
|
248
|
+
// corresponding attachments[].path is scanned independently where present.
|
|
249
|
+
channel_send: new Set(['filename']),
|
|
250
|
+
channel_reply: new Set(['filename']),
|
|
251
|
+
channel_fetch_attachment: new Set(['filename']),
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
// Trim before the `file:` test: an exempt prose key otherwise lets a
|
|
255
|
+
// leading-whitespace `file: file://…/memory` URI slip past the scan (the value
|
|
256
|
+
// is not path-shaped and `isFileUrl` misses it), reaching a fetcher that trims
|
|
257
|
+
// before parsing. Returns the trimmed URI so callers scan the real target.
|
|
258
|
+
function trimmedFileUri(value: string): string | undefined {
|
|
259
|
+
const trimmed = value.trim()
|
|
260
|
+
return trimmed.toLocaleLowerCase().startsWith('file:') ? trimmed : undefined
|
|
120
261
|
}
|
|
121
262
|
|
|
122
263
|
// Recursively collects strings that could be paths, skipping values under a
|
|
123
|
-
// universally-free-text key or a tool-scoped free-text key.
|
|
264
|
+
// universally-free-text key or a tool-scoped free-text key. Explicit path-like
|
|
265
|
+
// keys still win, and file:// values are normalized before matching. matchHidden then
|
|
124
266
|
// realpath-resolves each candidate and fires only on one landing inside a
|
|
125
267
|
// hidden directory. Fail-closed by design: a bare path-bearing value equal to a
|
|
126
268
|
// hidden dir name (e.g. `path: "memory"`) is still blocked. `underExempt`
|
|
127
269
|
// propagates so nested values under an exempt key (e.g. a structured pattern)
|
|
128
270
|
// stay exempt; top-level strings and array elements carry no key and are always
|
|
129
271
|
// scanned (so attachments[].path is collected).
|
|
130
|
-
|
|
272
|
+
//
|
|
273
|
+
// `nonFile` holds the tool author's declared control-token operand PATHS
|
|
274
|
+
// (`fileOperands.nonFile`, trusted metadata). A string at exactly one of those
|
|
275
|
+
// operand paths is skipped, mirroring the file-operand scanner so the two
|
|
276
|
+
// enforcement points agree — an id like `{ tenant: "memory" }` on a tool that
|
|
277
|
+
// declared `nonFile: ['tenant']` is not blocked here. Scoped by EXACT operand
|
|
278
|
+
// path (not key name), so an undeclared key still fails closed; `input`/
|
|
279
|
+
// `output`/`destructive` are deliberately NOT honored (a declared real-file path
|
|
280
|
+
// that resolves under a hidden dir must still block).
|
|
281
|
+
function collectPathCandidates(value: unknown, tool: string, nonFile?: ReadonlySet<string>): string[] {
|
|
131
282
|
const out: string[] = []
|
|
132
|
-
walk(value, out, tool, false)
|
|
283
|
+
walk(value, out, tool, false, nonFile, '')
|
|
133
284
|
return out
|
|
134
285
|
}
|
|
135
286
|
|
|
136
|
-
function walk(
|
|
287
|
+
function walk(
|
|
288
|
+
value: unknown,
|
|
289
|
+
out: string[],
|
|
290
|
+
tool: string,
|
|
291
|
+
underExempt: boolean,
|
|
292
|
+
nonFile: ReadonlySet<string> | undefined,
|
|
293
|
+
operandPath: string,
|
|
294
|
+
key?: string,
|
|
295
|
+
): void {
|
|
137
296
|
if (typeof value === 'string') {
|
|
138
|
-
if (
|
|
139
|
-
|
|
297
|
+
if (nonFile?.has(operandPath) === true) return
|
|
298
|
+
const isFileUrl = trimmedFileUri(value) !== undefined
|
|
299
|
+
if (underExempt && !isPathKey(key) && !isFileUrl) return
|
|
300
|
+
const normalized = normalizeCandidate(value)
|
|
301
|
+
if (normalized !== undefined) out.push(normalized)
|
|
140
302
|
return
|
|
141
303
|
}
|
|
142
304
|
if (Array.isArray(value)) {
|
|
143
|
-
for (const item of value) walk(item, out, tool, underExempt)
|
|
305
|
+
for (const item of value) walk(item, out, tool, underExempt, nonFile, operandPath, key)
|
|
144
306
|
return
|
|
145
307
|
}
|
|
146
308
|
if (value !== null && typeof value === 'object') {
|
|
147
309
|
const toolFreeText = FREE_TEXT_KEYS_BY_TOOL[tool]
|
|
148
|
-
for (const [
|
|
149
|
-
const keyIsExempt = NON_PATH_KEYS.has(
|
|
150
|
-
|
|
310
|
+
for (const [childKey, item] of Object.entries(value)) {
|
|
311
|
+
const keyIsExempt = NON_PATH_KEYS.has(childKey) || (toolFreeText?.has(childKey) ?? false)
|
|
312
|
+
const childPath = operandPath === '' ? childKey : `${operandPath}.${childKey}`
|
|
313
|
+
walk(item, out, tool, underExempt || keyIsExempt, nonFile, childPath, childKey)
|
|
151
314
|
}
|
|
152
315
|
}
|
|
153
316
|
}
|
|
@@ -171,10 +334,16 @@ function matchHidden(
|
|
|
171
334
|
agentDir: string,
|
|
172
335
|
deniedDirs: string[],
|
|
173
336
|
deniedFiles: string[],
|
|
337
|
+
identityScanner: HardlinkIdentityScanner,
|
|
174
338
|
): string | undefined {
|
|
175
|
-
const
|
|
339
|
+
const lexicalHit = matchLexicallyDenied(candidate, agentDir, deniedDirs, deniedFiles)
|
|
340
|
+
if (lexicalHit !== undefined) return lexicalHit
|
|
341
|
+
const lexical = path.resolve(agentDir, candidate)
|
|
342
|
+
const resolved = realpathRealIntendedPath(lexical)
|
|
343
|
+
const virtualRoot = virtualFilesystemRoot(lexical) ?? virtualFilesystemRoot(resolved)
|
|
344
|
+
if (virtualRoot !== undefined) return `${virtualRoot}, a virtual or process-backed filesystem`
|
|
176
345
|
for (const file of deniedFiles) {
|
|
177
|
-
if (resolved === realpathRealIntendedPath(file)) return file
|
|
346
|
+
if (resolved === realpathRealIntendedPath(file) || hasSameFileIdentity(resolved, file)) return file
|
|
178
347
|
}
|
|
179
348
|
for (const dir of deniedDirs) {
|
|
180
349
|
const realDir = realpathRealIntendedPath(dir)
|
|
@@ -183,9 +352,591 @@ function matchHidden(
|
|
|
183
352
|
// "\"-joined paths a win32 test runner produces.
|
|
184
353
|
if (resolved === realDir || resolved.startsWith(`${realDir}${path.sep}`)) return dir
|
|
185
354
|
}
|
|
355
|
+
const identity = fileIdentity(resolved)
|
|
356
|
+
if (identity !== undefined && identity.nlink > 1) {
|
|
357
|
+
const hit = identityScanner.check(identity)
|
|
358
|
+
if (hit !== undefined) return hit
|
|
359
|
+
}
|
|
360
|
+
return undefined
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
function matchLexicallyDenied(
|
|
364
|
+
candidate: string,
|
|
365
|
+
agentDir: string,
|
|
366
|
+
deniedDirs: readonly string[],
|
|
367
|
+
deniedFiles: readonly string[],
|
|
368
|
+
): string | undefined {
|
|
369
|
+
const absolute = portableAbsolute(agentDir, candidate)
|
|
370
|
+
const virtualRoot = virtualFilesystemRoot(absolute)
|
|
371
|
+
if (virtualRoot !== undefined) return `${virtualRoot}, a virtual or process-backed filesystem`
|
|
372
|
+
for (const file of deniedFiles) {
|
|
373
|
+
if (portableEqual(absolute, portableAbsolute(agentDir, file))) return file
|
|
374
|
+
}
|
|
375
|
+
for (const dir of deniedDirs) {
|
|
376
|
+
const root = portableAbsolute(agentDir, dir)
|
|
377
|
+
if (portableEqual(absolute, root) || portableInside(root, absolute)) return dir
|
|
378
|
+
}
|
|
379
|
+
return undefined
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
function portableAbsolute(agentDir: string, candidate: string): string {
|
|
383
|
+
const normalized = candidate.replaceAll('\\', '/')
|
|
384
|
+
if (/^[A-Za-z]:\//.test(normalized) || normalized.startsWith('//')) return path.posix.normalize(normalized)
|
|
385
|
+
if (normalized.startsWith('/')) return path.posix.normalize(normalized)
|
|
386
|
+
return path.posix.resolve(agentDir.replaceAll('\\', '/'), normalized)
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
function portableEqual(left: string, right: string): boolean {
|
|
390
|
+
const windows =
|
|
391
|
+
/^[A-Za-z]:\//.test(left) || left.startsWith('//') || /^[A-Za-z]:\//.test(right) || right.startsWith('//')
|
|
392
|
+
return windows ? left.toLocaleLowerCase() === right.toLocaleLowerCase() : left === right
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
function portableInside(parent: string, child: string): boolean {
|
|
396
|
+
const normalizedParent = parent.endsWith('/') ? parent : `${parent}/`
|
|
397
|
+
return portableEqual(child.slice(0, normalizedParent.length), normalizedParent)
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
function virtualFilesystemRoot(candidate: string): string | undefined {
|
|
401
|
+
const normalized = candidate.replaceAll('\\', '/')
|
|
402
|
+
for (const root of VIRTUAL_FILESYSTEM_ROOTS) {
|
|
403
|
+
if (normalized === root || normalized.startsWith(`${root}/`)) return root
|
|
404
|
+
}
|
|
186
405
|
return undefined
|
|
187
406
|
}
|
|
188
407
|
|
|
408
|
+
function fileIdentity(candidate: string): Pick<Stats, 'dev' | 'ino' | 'nlink'> | undefined {
|
|
409
|
+
try {
|
|
410
|
+
const stats = lstatSync(candidate)
|
|
411
|
+
return stats.isFile() ? stats : undefined
|
|
412
|
+
} catch {
|
|
413
|
+
return undefined
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
type HardlinkDirectory = {
|
|
418
|
+
readSync(): Dirent | null
|
|
419
|
+
statSync(): Stats
|
|
420
|
+
lstatEntrySync(name: string): Stats
|
|
421
|
+
openChildSync(name: string): HardlinkDirectory
|
|
422
|
+
finishSync(): void
|
|
423
|
+
closeSync(): void
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
type OpenedHardlinkDirectory = { reader: HardlinkDirectory; census: Stats }
|
|
427
|
+
|
|
428
|
+
function createPathDirectoryOpener(
|
|
429
|
+
openDirectory: (directory: string) => Pick<Dir, 'readSync' | 'closeSync'>,
|
|
430
|
+
lstat: (candidate: string) => Stats,
|
|
431
|
+
): (directory: string) => HardlinkDirectory {
|
|
432
|
+
const openPath = (directory: string): HardlinkDirectory => {
|
|
433
|
+
const reader = openDirectory(directory)
|
|
434
|
+
let finished = false
|
|
435
|
+
return {
|
|
436
|
+
readSync: () => reader.readSync(),
|
|
437
|
+
statSync: () => lstat(directory),
|
|
438
|
+
lstatEntrySync: (name) => lstat(path.join(directory, name)),
|
|
439
|
+
openChildSync: (name) => openPath(path.join(directory, name)),
|
|
440
|
+
finishSync() {
|
|
441
|
+
if (finished) return
|
|
442
|
+
finished = true
|
|
443
|
+
reader.closeSync()
|
|
444
|
+
},
|
|
445
|
+
closeSync() {
|
|
446
|
+
if (!finished) reader.closeSync()
|
|
447
|
+
finished = true
|
|
448
|
+
},
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
return openPath
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
function openDescriptorAnchoredDirectory(directory: string): HardlinkDirectory {
|
|
455
|
+
if (process.platform !== 'linux') {
|
|
456
|
+
throw new Error('hardlink identity traversal requires Linux descriptor anchoring')
|
|
457
|
+
}
|
|
458
|
+
const descriptor = openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
|
|
459
|
+
const anchor = `/proc/self/fd/${descriptor}`
|
|
460
|
+
let reader: Dir
|
|
461
|
+
try {
|
|
462
|
+
reader = opendirSync(anchor)
|
|
463
|
+
} catch (error) {
|
|
464
|
+
closeSync(descriptor)
|
|
465
|
+
throw error
|
|
466
|
+
}
|
|
467
|
+
let closed = false
|
|
468
|
+
let finished = false
|
|
469
|
+
return {
|
|
470
|
+
readSync: () => reader.readSync(),
|
|
471
|
+
statSync: () => fstatSync(descriptor),
|
|
472
|
+
lstatEntrySync: (name) => lstatSync(path.join(anchor, name)),
|
|
473
|
+
openChildSync: (name) => openDescriptorAnchoredDirectory(path.join(anchor, name)),
|
|
474
|
+
finishSync() {
|
|
475
|
+
if (finished) return
|
|
476
|
+
finished = true
|
|
477
|
+
reader.closeSync()
|
|
478
|
+
},
|
|
479
|
+
closeSync() {
|
|
480
|
+
if (closed) return
|
|
481
|
+
closed = true
|
|
482
|
+
let closeError: unknown
|
|
483
|
+
if (!finished) {
|
|
484
|
+
try {
|
|
485
|
+
reader.closeSync()
|
|
486
|
+
} catch (error) {
|
|
487
|
+
closeError = error
|
|
488
|
+
}
|
|
489
|
+
}
|
|
490
|
+
try {
|
|
491
|
+
closeSync(descriptor)
|
|
492
|
+
} catch (error) {
|
|
493
|
+
closeError ??= error
|
|
494
|
+
}
|
|
495
|
+
if (closeError !== undefined) throw closeError
|
|
496
|
+
},
|
|
497
|
+
}
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
type HardlinkIdentityScannerOptions = {
|
|
501
|
+
agentDir: string
|
|
502
|
+
deniedDirs: readonly string[]
|
|
503
|
+
deniedFiles: readonly string[]
|
|
504
|
+
maxEntries: number
|
|
505
|
+
openDirectory(directory: string): HardlinkDirectory
|
|
506
|
+
lstat(candidate: string): Stats
|
|
507
|
+
afterEntryLstat?(candidate: string, stats: Stats): void
|
|
508
|
+
}
|
|
509
|
+
|
|
510
|
+
class HardlinkIdentityScanner {
|
|
511
|
+
private remaining: number
|
|
512
|
+
private readonly visibleCounts = new Map<string, number>()
|
|
513
|
+
private readonly deniedIdentities = new Map<string, string>()
|
|
514
|
+
private readonly observedEntries = new Set<string>()
|
|
515
|
+
private readonly openedDirectories = new Set<string>()
|
|
516
|
+
private visibleScanned = false
|
|
517
|
+
private deniedScanned = false
|
|
518
|
+
private visibleFailure: string | undefined
|
|
519
|
+
private deniedFailure: string | undefined
|
|
520
|
+
private deniedFilesScanned = false
|
|
521
|
+
|
|
522
|
+
constructor(private readonly options: HardlinkIdentityScannerOptions) {
|
|
523
|
+
this.remaining = options.maxEntries
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
check(identity: Pick<Stats, 'dev' | 'ino' | 'nlink'>): string | undefined {
|
|
527
|
+
const key = identityKey(identity)
|
|
528
|
+
this.scanDeniedFiles()
|
|
529
|
+
if (this.deniedFailure !== undefined) return this.deniedFailure
|
|
530
|
+
const deniedFile = this.deniedIdentities.get(key)
|
|
531
|
+
if (deniedFile !== undefined) return deniedFile
|
|
532
|
+
|
|
533
|
+
this.scanDeniedTrees()
|
|
534
|
+
const deniedAlias = this.deniedIdentities.get(key)
|
|
535
|
+
if (deniedAlias !== undefined) return deniedAlias
|
|
536
|
+
if (this.deniedFailure !== undefined) return this.deniedFailure
|
|
537
|
+
|
|
538
|
+
this.scanVisibleTree()
|
|
539
|
+
if (this.visibleFailure !== undefined) return this.visibleFailure
|
|
540
|
+
if ((this.visibleCounts.get(key) ?? 0) >= identity.nlink) return undefined
|
|
541
|
+
return 'hardlink identities could not be fully accounted within the agent tree'
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
private scanDeniedFiles(): void {
|
|
545
|
+
if (this.deniedFilesScanned) return
|
|
546
|
+
this.deniedFilesScanned = true
|
|
547
|
+
for (const file of this.options.deniedFiles) {
|
|
548
|
+
try {
|
|
549
|
+
const stats = this.options.lstat(file)
|
|
550
|
+
if (stats.isFile()) this.deniedIdentities.set(identityKey(stats), file)
|
|
551
|
+
} catch (error) {
|
|
552
|
+
if (isNotFoundError(error)) continue
|
|
553
|
+
this.deniedFailure = `denied-file hardlink identity could not be read: ${file}`
|
|
554
|
+
return
|
|
555
|
+
}
|
|
556
|
+
}
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
private scanVisibleTree(): void {
|
|
560
|
+
if (this.visibleScanned) return
|
|
561
|
+
this.visibleScanned = true
|
|
562
|
+
const root = realpathRealIntendedPath(this.options.agentDir)
|
|
563
|
+
const deniedRoots = this.options.deniedDirs.map(realpathRealIntendedPath)
|
|
564
|
+
const deniedFiles = new Set(this.options.deniedFiles.map(realpathRealIntendedPath))
|
|
565
|
+
const rootStats = this.readRootStats(root, 'visible')
|
|
566
|
+
if (rootStats === undefined) return
|
|
567
|
+
const rootDirectory = this.openVerifiedDirectory(root, rootStats, 'visible')
|
|
568
|
+
if (rootDirectory === undefined) return
|
|
569
|
+
const pending: Array<{
|
|
570
|
+
directory: string
|
|
571
|
+
reader: HardlinkDirectory
|
|
572
|
+
identity: Pick<Stats, 'dev' | 'ino'>
|
|
573
|
+
census: Stats
|
|
574
|
+
agentRoot: boolean
|
|
575
|
+
}> = [{ directory: root, ...rootDirectory, identity: rootStats, agentRoot: true }]
|
|
576
|
+
const opened: Array<{ directory: string; reader: HardlinkDirectory; census: Stats }> = [
|
|
577
|
+
{ directory: root, ...rootDirectory },
|
|
578
|
+
]
|
|
579
|
+
let scanCompleted = false
|
|
580
|
+
try {
|
|
581
|
+
while (pending.length > 0) {
|
|
582
|
+
const current = pending.pop()
|
|
583
|
+
if (current === undefined) break
|
|
584
|
+
const completed = this.forEachEntry(current, 'visible', (entry, stats) => {
|
|
585
|
+
const entryPath = path.join(current.directory, entry.name)
|
|
586
|
+
if (current.agentRoot && HARDLINK_SCAN_EXCLUDED_AGENT_DIRS.has(entry.name)) return true
|
|
587
|
+
if (deniedFiles.has(entryPath) || deniedRoots.some((deniedRoot) => isPathAtOrBelow(entryPath, deniedRoot))) {
|
|
588
|
+
return true
|
|
589
|
+
}
|
|
590
|
+
if (stats.isDirectory()) {
|
|
591
|
+
const child = this.openVerifiedChild(current, entry.name, stats, 'visible')
|
|
592
|
+
if (child === undefined) return false
|
|
593
|
+
const openedChild = { directory: entryPath, ...child }
|
|
594
|
+
pending.push({ ...openedChild, identity: stats, agentRoot: false })
|
|
595
|
+
opened.push(openedChild)
|
|
596
|
+
} else if (stats.isFile()) {
|
|
597
|
+
this.recordVisibleFile(stats)
|
|
598
|
+
}
|
|
599
|
+
return true
|
|
600
|
+
})
|
|
601
|
+
if (!completed) return
|
|
602
|
+
}
|
|
603
|
+
scanCompleted = true
|
|
604
|
+
} finally {
|
|
605
|
+
this.verifyAndCloseDirectories(opened, 'visible', scanCompleted)
|
|
606
|
+
}
|
|
607
|
+
}
|
|
608
|
+
|
|
609
|
+
private scanDeniedTrees(): void {
|
|
610
|
+
if (this.deniedScanned) return
|
|
611
|
+
this.deniedScanned = true
|
|
612
|
+
for (const deniedDir of this.options.deniedDirs) {
|
|
613
|
+
let rootStats: Stats
|
|
614
|
+
let root: string
|
|
615
|
+
try {
|
|
616
|
+
root = realpathRealIntendedPath(deniedDir)
|
|
617
|
+
rootStats = this.options.lstat(root)
|
|
618
|
+
} catch (error) {
|
|
619
|
+
if (isNotFoundError(error)) continue
|
|
620
|
+
this.deniedFailure = `denied-directory hardlink identity could not be read: ${deniedDir}`
|
|
621
|
+
return
|
|
622
|
+
}
|
|
623
|
+
if (!rootStats.isDirectory()) {
|
|
624
|
+
this.deniedFailure = `denied-directory hardlink identity root is not a directory: ${deniedDir}`
|
|
625
|
+
return
|
|
626
|
+
}
|
|
627
|
+
const rootDirectory = this.openVerifiedDirectory(root, rootStats, 'denied')
|
|
628
|
+
if (rootDirectory === undefined) return
|
|
629
|
+
const pending: Array<{
|
|
630
|
+
directory: string
|
|
631
|
+
reader: HardlinkDirectory
|
|
632
|
+
identity: Pick<Stats, 'dev' | 'ino'>
|
|
633
|
+
census: Stats
|
|
634
|
+
}> = [{ directory: root, ...rootDirectory, identity: rootStats }]
|
|
635
|
+
const opened: Array<{ directory: string; reader: HardlinkDirectory; census: Stats }> = [
|
|
636
|
+
{ directory: root, ...rootDirectory },
|
|
637
|
+
]
|
|
638
|
+
let scanCompleted = false
|
|
639
|
+
try {
|
|
640
|
+
while (pending.length > 0) {
|
|
641
|
+
const current = pending.pop()
|
|
642
|
+
if (current === undefined) break
|
|
643
|
+
const completed = this.forEachEntry(current, 'denied', (entry, stats) => {
|
|
644
|
+
const entryPath = path.join(current.directory, entry.name)
|
|
645
|
+
if (stats.isDirectory()) {
|
|
646
|
+
const child = this.openVerifiedChild(current, entry.name, stats, 'denied')
|
|
647
|
+
if (child === undefined) return false
|
|
648
|
+
const openedChild = { directory: entryPath, ...child }
|
|
649
|
+
pending.push({ ...openedChild, identity: stats })
|
|
650
|
+
opened.push(openedChild)
|
|
651
|
+
} else if (stats.isFile()) {
|
|
652
|
+
this.recordDeniedFile(stats, deniedDir)
|
|
653
|
+
}
|
|
654
|
+
return true
|
|
655
|
+
})
|
|
656
|
+
if (!completed) return
|
|
657
|
+
}
|
|
658
|
+
scanCompleted = true
|
|
659
|
+
} finally {
|
|
660
|
+
this.verifyAndCloseDirectories(opened, 'denied', scanCompleted)
|
|
661
|
+
}
|
|
662
|
+
}
|
|
663
|
+
}
|
|
664
|
+
|
|
665
|
+
private forEachEntry(
|
|
666
|
+
current: {
|
|
667
|
+
directory: string
|
|
668
|
+
reader: HardlinkDirectory
|
|
669
|
+
identity: Pick<Stats, 'dev' | 'ino'>
|
|
670
|
+
},
|
|
671
|
+
surface: 'visible' | 'denied',
|
|
672
|
+
visit: (entry: Dirent, stats: Stats) => boolean,
|
|
673
|
+
): boolean {
|
|
674
|
+
let completed = true
|
|
675
|
+
try {
|
|
676
|
+
while (true) {
|
|
677
|
+
const entry = current.reader.readSync()
|
|
678
|
+
if (entry === null) break
|
|
679
|
+
if (!this.consumeEntry(surface)) {
|
|
680
|
+
completed = false
|
|
681
|
+
break
|
|
682
|
+
}
|
|
683
|
+
if (!this.claimEntryObservation(current.identity, entry.name, surface)) {
|
|
684
|
+
completed = false
|
|
685
|
+
break
|
|
686
|
+
}
|
|
687
|
+
let stats: Stats
|
|
688
|
+
try {
|
|
689
|
+
stats = current.reader.lstatEntrySync(entry.name)
|
|
690
|
+
this.options.afterEntryLstat?.(path.join(current.directory, entry.name), stats)
|
|
691
|
+
} catch {
|
|
692
|
+
this.recordEntryFailure(path.join(current.directory, entry.name), surface)
|
|
693
|
+
completed = false
|
|
694
|
+
break
|
|
695
|
+
}
|
|
696
|
+
if (!visit(entry, stats)) {
|
|
697
|
+
completed = false
|
|
698
|
+
break
|
|
699
|
+
}
|
|
700
|
+
try {
|
|
701
|
+
const confirmed = current.reader.lstatEntrySync(entry.name)
|
|
702
|
+
if (!sameDirectoryEntry(stats, confirmed)) {
|
|
703
|
+
this.recordEntryFailure(path.join(current.directory, entry.name), surface)
|
|
704
|
+
completed = false
|
|
705
|
+
break
|
|
706
|
+
}
|
|
707
|
+
} catch {
|
|
708
|
+
this.recordEntryFailure(path.join(current.directory, entry.name), surface)
|
|
709
|
+
completed = false
|
|
710
|
+
break
|
|
711
|
+
}
|
|
712
|
+
}
|
|
713
|
+
} catch {
|
|
714
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
715
|
+
completed = false
|
|
716
|
+
} finally {
|
|
717
|
+
try {
|
|
718
|
+
current.reader.finishSync()
|
|
719
|
+
} catch {
|
|
720
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
721
|
+
completed = false
|
|
722
|
+
}
|
|
723
|
+
}
|
|
724
|
+
return completed
|
|
725
|
+
}
|
|
726
|
+
|
|
727
|
+
private readRootStats(directory: string, surface: 'visible' | 'denied'): Stats | undefined {
|
|
728
|
+
try {
|
|
729
|
+
const stats = this.options.lstat(directory)
|
|
730
|
+
if (!stats.isDirectory()) {
|
|
731
|
+
this.recordDirectoryFailure(directory, surface)
|
|
732
|
+
return undefined
|
|
733
|
+
}
|
|
734
|
+
return stats
|
|
735
|
+
} catch {
|
|
736
|
+
this.recordDirectoryFailure(directory, surface)
|
|
737
|
+
return undefined
|
|
738
|
+
}
|
|
739
|
+
}
|
|
740
|
+
|
|
741
|
+
private openVerifiedDirectory(
|
|
742
|
+
directory: string,
|
|
743
|
+
expected: Pick<Stats, 'dev' | 'ino'>,
|
|
744
|
+
surface: 'visible' | 'denied',
|
|
745
|
+
): OpenedHardlinkDirectory | undefined {
|
|
746
|
+
let reader: HardlinkDirectory | undefined
|
|
747
|
+
try {
|
|
748
|
+
reader = this.options.openDirectory(directory)
|
|
749
|
+
const opened = reader.statSync()
|
|
750
|
+
if (!opened.isDirectory() || opened.dev !== expected.dev || opened.ino !== expected.ino) {
|
|
751
|
+
this.recordDirectoryFailure(directory, surface)
|
|
752
|
+
reader.closeSync()
|
|
753
|
+
return undefined
|
|
754
|
+
}
|
|
755
|
+
if (!this.claimDirectoryIdentity(opened, directory, surface)) {
|
|
756
|
+
reader.closeSync()
|
|
757
|
+
return undefined
|
|
758
|
+
}
|
|
759
|
+
return { reader, census: opened }
|
|
760
|
+
} catch {
|
|
761
|
+
try {
|
|
762
|
+
reader?.closeSync()
|
|
763
|
+
} catch {}
|
|
764
|
+
this.recordDirectoryFailure(directory, surface)
|
|
765
|
+
return undefined
|
|
766
|
+
}
|
|
767
|
+
}
|
|
768
|
+
|
|
769
|
+
private openVerifiedChild(
|
|
770
|
+
parent: { directory: string; reader: HardlinkDirectory },
|
|
771
|
+
name: string,
|
|
772
|
+
expected: Pick<Stats, 'dev' | 'ino'>,
|
|
773
|
+
surface: 'visible' | 'denied',
|
|
774
|
+
): OpenedHardlinkDirectory | undefined {
|
|
775
|
+
const directory = path.join(parent.directory, name)
|
|
776
|
+
let reader: HardlinkDirectory | undefined
|
|
777
|
+
try {
|
|
778
|
+
reader = parent.reader.openChildSync(name)
|
|
779
|
+
const opened = reader.statSync()
|
|
780
|
+
if (!opened.isDirectory() || opened.dev !== expected.dev || opened.ino !== expected.ino) {
|
|
781
|
+
this.recordDirectoryFailure(directory, surface)
|
|
782
|
+
reader.closeSync()
|
|
783
|
+
return undefined
|
|
784
|
+
}
|
|
785
|
+
if (!this.claimDirectoryIdentity(opened, directory, surface)) {
|
|
786
|
+
reader.closeSync()
|
|
787
|
+
return undefined
|
|
788
|
+
}
|
|
789
|
+
return { reader, census: opened }
|
|
790
|
+
} catch {
|
|
791
|
+
try {
|
|
792
|
+
reader?.closeSync()
|
|
793
|
+
} catch {}
|
|
794
|
+
this.recordDirectoryFailure(directory, surface)
|
|
795
|
+
return undefined
|
|
796
|
+
}
|
|
797
|
+
}
|
|
798
|
+
|
|
799
|
+
private verifyAndCloseDirectories(
|
|
800
|
+
opened: Array<{ directory: string; reader: HardlinkDirectory; census: Stats }>,
|
|
801
|
+
surface: 'visible' | 'denied',
|
|
802
|
+
verify: boolean,
|
|
803
|
+
): void {
|
|
804
|
+
for (const current of opened.reverse()) {
|
|
805
|
+
if (verify) {
|
|
806
|
+
try {
|
|
807
|
+
if (!sameDirectoryCensus(current.census, current.reader.statSync())) {
|
|
808
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
809
|
+
}
|
|
810
|
+
} catch {
|
|
811
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
812
|
+
}
|
|
813
|
+
}
|
|
814
|
+
try {
|
|
815
|
+
current.reader.closeSync()
|
|
816
|
+
} catch {
|
|
817
|
+
this.recordDirectoryFailure(current.directory, surface)
|
|
818
|
+
}
|
|
819
|
+
}
|
|
820
|
+
}
|
|
821
|
+
|
|
822
|
+
private recordDirectoryFailure(directory: string, surface: 'visible' | 'denied'): void {
|
|
823
|
+
const reason = `${surface} hardlink identity directory could not be read: ${directory}`
|
|
824
|
+
if (surface === 'visible') this.visibleFailure = reason
|
|
825
|
+
else this.deniedFailure = reason
|
|
826
|
+
}
|
|
827
|
+
|
|
828
|
+
private consumeEntry(surface: 'visible' | 'denied'): boolean {
|
|
829
|
+
if (this.remaining > 0) {
|
|
830
|
+
this.remaining -= 1
|
|
831
|
+
return true
|
|
832
|
+
}
|
|
833
|
+
const reason = `hardlink identity entry limit exceeded (${this.options.maxEntries})`
|
|
834
|
+
if (surface === 'visible') this.visibleFailure = reason
|
|
835
|
+
else this.deniedFailure = reason
|
|
836
|
+
return false
|
|
837
|
+
}
|
|
838
|
+
|
|
839
|
+
private recordEntryFailure(candidate: string, surface: 'visible' | 'denied'): void {
|
|
840
|
+
const reason = `${surface} hardlink identity could not be read: ${candidate}`
|
|
841
|
+
if (surface === 'visible') this.visibleFailure = reason
|
|
842
|
+
else this.deniedFailure = reason
|
|
843
|
+
}
|
|
844
|
+
|
|
845
|
+
private claimDirectoryIdentity(
|
|
846
|
+
identity: Pick<Stats, 'dev' | 'ino'>,
|
|
847
|
+
directory: string,
|
|
848
|
+
surface: 'visible' | 'denied',
|
|
849
|
+
): boolean {
|
|
850
|
+
const key = identityKey(identity)
|
|
851
|
+
if (this.openedDirectories.has(key)) {
|
|
852
|
+
this.recordDirectoryFailure(directory, surface)
|
|
853
|
+
return false
|
|
854
|
+
}
|
|
855
|
+
this.openedDirectories.add(key)
|
|
856
|
+
return true
|
|
857
|
+
}
|
|
858
|
+
|
|
859
|
+
private claimEntryObservation(
|
|
860
|
+
directoryIdentity: Pick<Stats, 'dev' | 'ino'>,
|
|
861
|
+
name: string,
|
|
862
|
+
surface: 'visible' | 'denied',
|
|
863
|
+
): boolean {
|
|
864
|
+
const key = `${identityKey(directoryIdentity)}:${JSON.stringify(name)}`
|
|
865
|
+
if (this.observedEntries.has(key)) {
|
|
866
|
+
this.recordEntryFailure(name, surface)
|
|
867
|
+
return false
|
|
868
|
+
}
|
|
869
|
+
this.observedEntries.add(key)
|
|
870
|
+
return true
|
|
871
|
+
}
|
|
872
|
+
|
|
873
|
+
private recordVisibleFile(stats: Stats): void {
|
|
874
|
+
const key = identityKey(stats)
|
|
875
|
+
this.visibleCounts.set(key, (this.visibleCounts.get(key) ?? 0) + 1)
|
|
876
|
+
}
|
|
877
|
+
|
|
878
|
+
private recordDeniedFile(stats: Stats, deniedRoot: string): void {
|
|
879
|
+
this.deniedIdentities.set(identityKey(stats), deniedRoot)
|
|
880
|
+
}
|
|
881
|
+
}
|
|
882
|
+
|
|
883
|
+
function identityKey(identity: Pick<Stats, 'dev' | 'ino'>): string {
|
|
884
|
+
return `${identity.dev}:${identity.ino}`
|
|
885
|
+
}
|
|
886
|
+
|
|
887
|
+
function sameDirectoryEntry(before: Stats, after: Stats): boolean {
|
|
888
|
+
return (
|
|
889
|
+
before.dev === after.dev && before.ino === after.ino && before.mode === after.mode && before.nlink === after.nlink
|
|
890
|
+
)
|
|
891
|
+
}
|
|
892
|
+
|
|
893
|
+
function sameDirectoryCensus(before: Stats, after: Stats): boolean {
|
|
894
|
+
return (
|
|
895
|
+
before.dev === after.dev &&
|
|
896
|
+
before.ino === after.ino &&
|
|
897
|
+
before.mode === after.mode &&
|
|
898
|
+
before.nlink === after.nlink &&
|
|
899
|
+
before.size === after.size &&
|
|
900
|
+
before.mtimeMs === after.mtimeMs &&
|
|
901
|
+
before.ctimeMs === after.ctimeMs
|
|
902
|
+
)
|
|
903
|
+
}
|
|
904
|
+
|
|
905
|
+
function isPathAtOrBelow(candidate: string, root: string): boolean {
|
|
906
|
+
return candidate === root || candidate.startsWith(`${root}${path.sep}`)
|
|
907
|
+
}
|
|
908
|
+
|
|
909
|
+
function isPathKey(key: string | undefined): boolean {
|
|
910
|
+
return key !== undefined && (PATH_KEYS.test(key) || CAMEL_PATH_KEYS.test(key))
|
|
911
|
+
}
|
|
912
|
+
|
|
913
|
+
function normalizeCandidate(value: string): string | undefined {
|
|
914
|
+
const uri = trimmedFileUri(value)
|
|
915
|
+
if (uri === undefined) return value
|
|
916
|
+
try {
|
|
917
|
+
const url = new URL(uri)
|
|
918
|
+
const pathname = decodeURIComponent(url.pathname)
|
|
919
|
+
if (url.hostname !== '') return `//${url.hostname}${pathname}`
|
|
920
|
+
if (/^\/[A-Za-z]:\//.test(pathname)) return pathname.slice(1)
|
|
921
|
+
// Keep synthetic POSIX container paths platform-independent. fileURLToPath
|
|
922
|
+
// would reinterpret file:///agent/... through the Windows host grammar.
|
|
923
|
+
if (pathname.startsWith('/agent/') || pathname === '/agent') return pathname
|
|
924
|
+
return fileURLToPath(uri)
|
|
925
|
+
} catch {
|
|
926
|
+
return value
|
|
927
|
+
}
|
|
928
|
+
}
|
|
929
|
+
|
|
930
|
+
function hasSameFileIdentity(candidate: string, deniedFile: string): boolean {
|
|
931
|
+
try {
|
|
932
|
+
const candidateStats = statSync(candidate)
|
|
933
|
+
const deniedStats = statSync(deniedFile)
|
|
934
|
+
return candidateStats.dev === deniedStats.dev && candidateStats.ino === deniedStats.ino
|
|
935
|
+
} catch {
|
|
936
|
+
return false
|
|
937
|
+
}
|
|
938
|
+
}
|
|
939
|
+
|
|
189
940
|
// Resolves symlinks on the longest existing prefix of an absolute path, then
|
|
190
941
|
// re-appends the non-existent tail. A bare realpathSync throws on a path that
|
|
191
942
|
// does not exist yet (a write target, or a read of a not-yet-created file), so
|