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.
Files changed (75) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -2
  3. package/src/agent/multimodal/looker.ts +11 -1
  4. package/src/agent/network/safe-http.ts +17 -8
  5. package/src/agent/plugin-tools.ts +1 -3
  6. package/src/agent/tool-file-safety.ts +414 -145
  7. package/src/agent/tools/webfetch/fetch.ts +22 -2
  8. package/src/agent/tools/webfetch/strategies/jq.ts +1 -2
  9. package/src/agent/tools/webfetch/strategies/readability.ts +39 -16
  10. package/src/agent/tools/webfetch/strategies/selector.ts +4 -2
  11. package/src/agent/tools/webfetch/strategies/snapshot.ts +3 -2
  12. package/src/agent/tools/webfetch/tool.ts +3 -3
  13. package/src/agent/tools-without-local-file-operands.ts +9 -6
  14. package/src/bundled-plugins/backup/README.md +23 -10
  15. package/src/bundled-plugins/backup/git-auth.ts +6 -4
  16. package/src/bundled-plugins/backup/index.ts +104 -47
  17. package/src/bundled-plugins/backup/runner.ts +102 -5
  18. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +74 -26
  19. package/src/bundled-plugins/github-cli-auth/git-command.ts +224 -36
  20. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +9 -9
  21. package/src/bundled-plugins/github-cli-auth/index.ts +110 -31
  22. package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
  23. package/src/bundled-plugins/memory/README.md +9 -0
  24. package/src/bundled-plugins/memory/vector/embed-threads.ts +36 -0
  25. package/src/bundled-plugins/memory/vector/embedder.ts +19 -1
  26. package/src/bundled-plugins/memory/vector/hybrid.ts +10 -2
  27. package/src/bundled-plugins/memory/vector/store.ts +21 -9
  28. package/src/bundled-plugins/researcher/write-report.ts +3 -3
  29. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +8 -3
  30. package/src/bundled-plugins/security/policies/private-surface-read.ts +616 -50
  31. package/src/bundled-plugins/security/policies/ssrf.ts +119 -34
  32. package/src/channels/adapters/github/inbound.ts +11 -0
  33. package/src/channels/adapters/github/index.ts +48 -54
  34. package/src/channels/adapters/github/reconcile-cooldown-store.ts +178 -0
  35. package/src/channels/adapters/github/reconcile-open-prs.ts +31 -0
  36. package/src/channels/adapters/slack-bot-edit.ts +85 -20
  37. package/src/channels/adapters/slack-bot.ts +7 -2
  38. package/src/channels/adapters/slack-format.ts +245 -0
  39. package/src/channels/github-token-bridge.ts +2 -3
  40. package/src/cli/inspect.ts +16 -0
  41. package/src/container/docker-app.ts +42 -13
  42. package/src/container/shared.ts +19 -6
  43. package/src/container/start.ts +13 -0
  44. package/src/cron/bridge.ts +9 -2
  45. package/src/doctor/checks.ts +5 -2
  46. package/src/git/bound-gc-config.ts +82 -0
  47. package/src/hostd/spawn.ts +133 -47
  48. package/src/init/checkpoint.ts +4 -4
  49. package/src/init/dockerfile.ts +100 -88
  50. package/src/init/gitignore.ts +5 -6
  51. package/src/init/run-bun-install.ts +16 -2
  52. package/src/init/validate-api-key.ts +1 -0
  53. package/src/inspect/item-list.ts +12 -6
  54. package/src/inspect/replay.ts +21 -9
  55. package/src/inspect/session-list.ts +71 -33
  56. package/src/mcp/tools.ts +1 -0
  57. package/src/network/internal-destinations.ts +267 -0
  58. package/src/permissions/permissions.ts +93 -2
  59. package/src/plugin/types.ts +3 -2
  60. package/src/role-claim/code.ts +9 -5
  61. package/src/run/index.ts +45 -36
  62. package/src/sandbox/canonical-secrets.ts +6 -0
  63. package/src/sandbox/env-exposure.ts +18 -15
  64. package/src/sandbox/index.ts +1 -0
  65. package/src/sandbox/policy.ts +5 -3
  66. package/src/sandbox/privileged-runtime.ts +1 -0
  67. package/src/sandbox/symlinks.ts +1 -1
  68. package/src/secrets/export-claude-credentials-file.ts +13 -22
  69. package/src/secrets/export-codex-auth-file.ts +12 -28
  70. package/src/skills/typeclaw-config/SKILL.md +22 -6
  71. package/src/skills/typeclaw-permissions/SKILL.md +22 -9
  72. package/src/skills/typeclaw-plugins/SKILL.md +37 -0
  73. package/src/usage/scan.ts +11 -2
  74. package/typeclaw.schema.json +5 -0
  75. package/src/git/secret-history.ts +0 -371
@@ -1,4 +1,16 @@
1
- import { readdirSync, realpathSync, statSync } from 'node:fs'
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(options: {
59
- tool: string
60
- args: Record<string, unknown>
61
- agentDir: string
62
- hidden: HiddenPaths
63
- fileOperands?: ToolFileOperands
64
- }): SecurityBlock | undefined {
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
- if (hasMultipleLinks(resolved)) {
263
- const alias = findDeniedHardlinkAlias(resolved, deniedDirs)
264
- if (alias !== undefined) return alias
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 hasMultipleLinks(candidate: string): boolean {
414
+ function fileIdentity(candidate: string): Pick<Stats, 'dev' | 'ino' | 'nlink'> | undefined {
315
415
  try {
316
- const stats = statSync(candidate)
317
- return stats.isFile() && stats.nlink > 1
416
+ const stats = lstatSync(candidate)
417
+ return stats.isFile() ? stats : undefined
318
418
  } catch {
319
- return false
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 findDeniedHardlinkAlias(candidate: string, deniedDirs: readonly string[]): string | undefined {
324
- let remaining = MAX_HARDLINK_IDENTITY_ENTRIES
325
- for (const deniedDir of deniedDirs) {
326
- const pending = [realpathRealIntendedPath(deniedDir)]
327
- while (pending.length > 0) {
328
- const current = pending.pop()
329
- if (current === undefined) break
330
- let entries
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
- entries = readdirSync(current, { withFileTypes: true })
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
- continue
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
- for (const entry of entries) {
337
- const entryPath = path.join(current, entry.name)
338
- if (entry.isDirectory()) pending.push(entryPath)
339
- else if (entry.isFile()) {
340
- if (remaining-- <= 0) return undefined
341
- if (hasSameFileIdentity(candidate, entryPath)) return deniedDir
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
- return undefined
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 {