Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/architecture/tla/CustomToolCache.Direct.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
CONSTANT Writers <- MCWriters
CONSTANT AtomicPublish = FALSE
SPECIFICATION Spec
INVARIANT VisibleIsReady
INVARIANT FailedIsClean
CHECK_DEADLOCK FALSE

CONSTANT CanonicalMatch = TRUE
INVARIANT OwnershipMockReachesRoot

CONSTANT NormalizeCache = TRUE
CONSTANT GuardCleanup = TRUE
CONSTANT CleanupCases <- MCCleanupCases
INVARIANT CleanupSelectsRoot
INVARIANT UnsafeRootIsUntouched
15 changes: 15 additions & 0 deletions docs/architecture/tla/CustomToolCache.MixedPath.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
CONSTANT Writers <- MCWriters
CONSTANT AtomicPublish = TRUE
SPECIFICATION Spec
INVARIANT VisibleIsReady
INVARIANT FailedIsClean
CHECK_DEADLOCK FALSE

CONSTANT CanonicalMatch = TRUE
INVARIANT OwnershipMockReachesRoot

CONSTANT NormalizeCache = FALSE
CONSTANT GuardCleanup = TRUE
CONSTANT CleanupCases <- MCCleanupCases
INVARIANT CleanupSelectsRoot
INVARIANT UnsafeRootIsUntouched
15 changes: 15 additions & 0 deletions docs/architecture/tla/CustomToolCache.NoCleanupGuard.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
CONSTANT Writers <- MCWriters
CONSTANT AtomicPublish = TRUE
SPECIFICATION Spec
INVARIANT VisibleIsReady
INVARIANT FailedIsClean
CHECK_DEADLOCK FALSE

CONSTANT CanonicalMatch = TRUE
INVARIANT OwnershipMockReachesRoot

CONSTANT NormalizeCache = TRUE
CONSTANT GuardCleanup = FALSE
CONSTANT CleanupCases <- MCCleanupCases
INVARIANT CleanupSelectsRoot
INVARIANT UnsafeRootIsUntouched
15 changes: 15 additions & 0 deletions docs/architecture/tla/CustomToolCache.RawPath.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
CONSTANT Writers <- MCWriters
CONSTANT AtomicPublish = TRUE
SPECIFICATION Spec
INVARIANT VisibleIsReady
INVARIANT FailedIsClean
CHECK_DEADLOCK FALSE

CONSTANT CanonicalMatch = FALSE
INVARIANT OwnershipMockReachesRoot

CONSTANT NormalizeCache = TRUE
CONSTANT GuardCleanup = TRUE
CONSTANT CleanupCases <- MCCleanupCases
INVARIANT CleanupSelectsRoot
INVARIANT UnsafeRootIsUntouched
15 changes: 15 additions & 0 deletions docs/architecture/tla/CustomToolCache.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
CONSTANT Writers <- MCWriters
CONSTANT AtomicPublish = TRUE
SPECIFICATION Spec
INVARIANT VisibleIsReady
INVARIANT FailedIsClean
CHECK_DEADLOCK FALSE

CONSTANT CanonicalMatch = TRUE
INVARIANT OwnershipMockReachesRoot

CONSTANT NormalizeCache = TRUE
CONSTANT GuardCleanup = TRUE
CONSTANT CleanupCases <- MCCleanupCases
INVARIANT CleanupSelectsRoot
INVARIANT UnsafeRootIsUntouched
79 changes: 79 additions & 0 deletions docs/architecture/tla/CustomToolCache.tla
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
------------------------- MODULE CustomToolCache -------------------------
(* Sources: CustomToolRegistry.import/runEsbuild and RegistryOptions.cacheDir.
Sinks: import(bundle.mjs), the lstatSync test double, and clearCache. *)
(* VisibleIsReady: Readers see only complete, private, checked bundles.
FailedIsClean: Failed writers leave no pending file. *)
(* OwnershipMockReachesRoot: The ownership double matches the resolved cache root.
CleanupSelectsRoot: Cleanup selects the configured root for each input path. *)
(* UnsafeRootIsUntouched: Cleanup preserves roots that fail validation.
Compiler, path results, and filesystem checks are oracles. MC sets the bounds. *)
(* Expectation: Each faulty variant fails its invariant. Fixed variants pass.
The reviews preceded the new invariants. The blind step was missed. *)
(* Findings: Replays confirm the reported bugs. No new bug or false alarm found.
The model does not prove the code. A stopped process can leave a pending file. *)
(* TLC: Fixed passes all five invariants (49 states, depth 11).
Direct fails VisibleIsReady after Start (2 states). RawPath fails at the start. *)
(* MixedPath fails CleanupSelectsRoot. NoCleanupGuard fails UnsafeRootIsUntouched.
Latest runs took under 1s each. Round 3 runs took 27 to 42s. *)
(* Replay: Old publication fails 3 of 4 cases. Raw ownership matching fails aliases.
Old cleanup fails 4 of 7 cases. Guard sabotage deletes all 3 unsafe sentinels. *)
(* Validation: Fixed code passes 40 integration and 21 unit tests.
Both type checks and focused lint pass. Suppression counts do not increase. *)
(* Review ratchet, PR #2485: Added 4, covered 0, gap 4 across four rounds.
Gaps cover test routing, defaults, module placement, and PR metadata. *)
(* Round 1: Threads PRRT_kwDOSK-bwM64vzgN, PRRT_kwDOSK-bwM64vzgR, PRRT_kwDOSK-bwM64vzgV. Added 1, gap 2.
Publication became an invariant. Test routing and defaults use direct tests. *)
(* Round 2: Thread PRRT_kwDOSK-bwM64vzgN, reply 4622881580. Added 1.
Canonical ownership matching became an invariant. *)
(* Round 3: Thread PRRT_kwDOSK-bwM65T3Dd, comment 4623919335. Gap 1.
Writer bounds moved to MC. A state invariant cannot check module placement. *)
(* Round 4: Review 5968844313. Added 2, gap 1.
Cleanup gained two invariants. PR metadata is outside the model. *)
(* Cost: One agent, no delegates. Rounds 1/2/3/4 took about 6/3/4/6 minutes.
Header cleanup took about 2 minutes. These are work estimates. *)
(* Gate: Run all five configs against CustomToolCacheMC and the property tables.
Use -metadir outside the repo. TLC needs a local socket. Run file tests on the host. *)
EXTENDS Naturals, TLC
CONSTANTS AtomicPublish, CanonicalMatch, Writers, NormalizeCache, GuardCleanup, CleanupCases
VARIABLES phase, published, pending
vars == <<phase, published, pending>>
Init == /\ phase = [w \in Writers |-> "idle"]
/\ published = "absent"
/\ pending = {}
Start(w) == /\ phase[w] = "idle"
/\ phase' = [phase EXCEPT ![w] = "writing"]
/\ pending' = pending \cup {w}
/\ published' = IF AtomicPublish THEN published ELSE "partial"
Finish(w) == /\ phase[w] = "writing"
/\ phase' = [phase EXCEPT ![w] = "complete"]
/\ published' = IF AtomicPublish THEN published ELSE "readable"
/\ UNCHANGED pending
Restrict(w) == /\ phase[w] = "complete"
/\ phase' = [phase EXCEPT ![w] = "private"]
/\ UNCHANGED <<published, pending>>
Check(w) == /\ phase[w] = "private"
/\ phase' = [phase EXCEPT ![w] = "checked"]
/\ UNCHANGED <<published, pending>>
Publish(w) == /\ phase[w] = "checked"
/\ phase' = [phase EXCEPT ![w] = "done"]
/\ published' = "ready"
/\ pending' = pending \ {w}
Fail(w) == /\ phase[w] \in {"writing", "complete", "private", "checked"}
/\ phase' = [phase EXCEPT ![w] = "failed"]
/\ pending' = pending \ {w}
/\ UNCHANGED published
Next == \E w \in Writers : Start(w) \/ Finish(w) \/ Restrict(w) \/ Check(w) \/ Publish(w) \/ Fail(w)
Spec == Init /\ [][Next]_vars
VisibleIsReady == published \in {"absent", "ready"}
FailedIsClean == \A w \in Writers : phase[w] = "failed" => w \notin pending
(* Source: configured cache path. Sink: lstatSync ownership test double. *)
CachePaths == {"cache", "alias/cache"}
Canonical(p) == IF p = "alias/cache" THEN "cache" ELSE p
MockTarget(p) == IF CanonicalMatch THEN Canonical(p) ELSE p
OwnershipMockReachesRoot == \A p \in CachePaths : MockTarget(p) = Canonical(p)
(* Path results are input oracles. The model does not copy Node path parsing. *)
CleanupTarget(c) == IF NormalizeCache THEN c.normalizedTarget ELSE c.mixedTarget
CleanupSelectsRoot == \A c \in CleanupCases : CleanupTarget(c) = c.root
MayClear(safe) == IF GuardCleanup THEN safe ELSE TRUE
UnsafeRootIsUntouched == \A safe \in BOOLEAN : ~safe => ~MayClear(safe)
=============================================================================
13 changes: 13 additions & 0 deletions docs/architecture/tla/CustomToolCacheMC.tla
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
------------------------ MODULE CustomToolCacheMC ------------------------
(* TLC bounds for CustomToolCache: Two writers and four path forms.
The spec header records expectations, cost, findings, and validation. *)
EXTENDS CustomToolCache
MCWriters == {1, 2}
(* These path results come from Node path.resolve, dirname, and basename. *)
MCCleanupCases == {
[form |-> "plain", root |-> "cache", normalizedTarget |-> "cache", mixedTarget |-> "cache"],
[form |-> "dot", root |-> "cache", normalizedTarget |-> "cache", mixedTarget |-> "parent"],
[form |-> "dots", root |-> "cache", normalizedTarget |-> "cache", mixedTarget |-> "parent"],
[form |-> "dotdot", root |-> "cache", normalizedTarget |-> "cache", mixedTarget |-> "grandparent"]
}
=============================================================================
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
// pnpm --filter @roo-code/core test src/custom-tools/__tests__/custom-tool-registry.integration.spec.ts

import fs from "fs"
import os from "os"
import { createHash } from "crypto"
import path from "path"
import { fileURLToPath } from "url"

Expand All @@ -17,6 +20,200 @@ describe.sequential("CustomToolRegistry integration", () => {
registry = new CustomToolRegistry()
})

describe.skipIf(process.platform === "win32")("cache security", () => {
let sandbox: string
let toolDir: string
let cacheDir: string
let entryDir: string

beforeEach(() => {
sandbox = fs.mkdtempSync(path.join(os.tmpdir(), "tool-cache-security-"))
toolDir = path.join(sandbox, "tools")
cacheDir = path.join(sandbox, "cache")
fs.mkdirSync(toolDir)
const source = path.join(toolDir, "safe.ts")
fs.writeFileSync(
source,
'export default { name: "safe", description: "trusted", execute: async () => "ok" }',
)
fs.writeFileSync(path.join(toolDir, ".env"), "SYNTHETIC_TEST_VALUE=example")
const key = `${source}:${fs.statSync(source).mtimeMs}`
entryDir = path.join(cacheDir, createHash("sha256").update(key).digest("hex").slice(0, 16))
registry = new CustomToolRegistry({ cacheDir })
})

afterEach(() => fs.rmSync(sandbox, { recursive: true, force: true }))

it("creates a private cache, reuses bundles across instances, and clears it", async () => {
expect((await registry.loadFromDirectory(toolDir)).loaded).toEqual(["safe"])
for (const location of [
cacheDir,
entryDir,
path.join(entryDir, "bundle.mjs"),
path.join(entryDir, ".env"),
]) {
expect(fs.statSync(location).mode & 0o077).toBe(0)
}
const bundle = path.join(entryDir, "bundle.mjs")
const modified = fs.statSync(bundle).mtimeMs
const second = new CustomToolRegistry({ cacheDir })
expect((await second.loadFromDirectory(toolDir)).loaded).toEqual(["safe"])
expect(fs.statSync(bundle).mtimeMs).toBe(modified)
second.clearCache()
expect(fs.readdirSync(cacheDir)).toEqual([])
})

it.each(["", "/.", "/./.", "/nested/.."])("clears only the configured cache with suffix %s", (suffix) => {
fs.mkdirSync(cacheDir, { mode: 0o700 })
fs.mkdirSync(path.join(cacheDir, "nested"))
const cachedBundle = path.join(cacheDir, "bundle.mjs")
const sibling = path.join(toolDir, "sentinel")
fs.writeFileSync(cachedBundle, "cached")
fs.writeFileSync(sibling, "keep")
new CustomToolRegistry({ cacheDir: `${cacheDir}${suffix}` }).clearCache()
expect(fs.existsSync(cachedBundle)).toBe(false)
expect(fs.readFileSync(sibling, "utf8")).toBe("keep")
})

it.each(["permissions", "symlink", "symlink-dot"])("does not clear an unsafe cache root: %s", (kind) => {
fs.mkdirSync(cacheDir, { mode: 0o700 })
let sentinel: string
if (kind.startsWith("symlink")) {
fs.rmdirSync(cacheDir)
fs.symlinkSync(toolDir, cacheDir)
sentinel = path.join(toolDir, "bundle.mjs")
} else {
fs.chmodSync(cacheDir, 0o777)
sentinel = path.join(cacheDir, "bundle.mjs")
}
fs.writeFileSync(sentinel, "keep")
const error = vi.spyOn(console, "error").mockImplementation(() => {})
try {
new CustomToolRegistry({ cacheDir: kind === "symlink-dot" ? `${cacheDir}/.` : cacheDir }).clearCache()
expect(fs.readFileSync(sentinel, "utf8")).toBe("keep")
expect(error).toHaveBeenCalledWith(expect.stringContaining("clearCache failed to clean disk cache"))
} finally {
error.mockRestore()
}
})

it.each(["root", "entry", "bundle", "symlink-root", "symlink-entry", "symlink-bundle", "hardlink-bundle"])(
"rejects an unsafe %s before importing attacker code",
async (kind) => {
fs.mkdirSync(entryDir, { recursive: true, mode: 0o700 })
const payload = path.join(sandbox, "payload.mjs")
const marker = path.join(sandbox, "executed")
fs.writeFileSync(
payload,
`import fs from "node:fs"; fs.writeFileSync(${JSON.stringify(marker)}, "bad")`,
)
const bundle = path.join(entryDir, "bundle.mjs")
fs.copyFileSync(payload, bundle)
fs.chmodSync(bundle, 0o600)
const target = kind.endsWith("root") ? cacheDir : kind.endsWith("entry") ? entryDir : bundle
if (kind.startsWith("symlink")) {
fs.rmSync(target, { recursive: true, force: true })
fs.symlinkSync(kind === "symlink-bundle" ? payload : toolDir, target)
} else if (kind === "hardlink-bundle") {
fs.linkSync(bundle, path.join(sandbox, "linked.mjs"))
} else {
fs.chmodSync(target, kind === "bundle" ? 0o666 : 0o777)
}
const result = await registry.loadFromDirectory(toolDir)
expect(result.loaded).toEqual([])
expect(result.failed[0]?.error).toContain("Unsafe custom tool cache")
expect(fs.existsSync(marker)).toBe(false)
},
)

it.each(["direct", "symlink-parent"])("rejects a cache owned by another account via %s", async (kind) => {
fs.mkdirSync(cacheDir, { mode: 0o700 })
if (kind === "symlink-parent") {
const alias = path.join(sandbox, "alias")
fs.symlinkSync(sandbox, alias)
cacheDir = path.join(alias, "cache")
registry = new CustomToolRegistry({ cacheDir })
}
const resolvedCacheDir = fs.realpathSync(cacheDir)
const stat = fs.lstatSync(resolvedCacheDir)
stat.uid += 1
const originalLstat = fs.lstatSync
const spy = vi.spyOn(fs, "lstatSync").mockImplementation((location, options) => {
return location === resolvedCacheDir ? stat : originalLstat(location, options)
})
try {
const result = await registry.loadFromDirectory(toolDir)
expect(result.loaded).toEqual([])
expect(result.failed).toEqual([
{ file: "safe.ts", error: `Unsafe custom tool cache path: ${resolvedCacheDir}` },
])
} finally {
spy.mockRestore()
}
})

it.each(["success", "build failure", "validation failure", "publish failure"])(
"publishes only complete private bundles and removes pending files: %s",
async (outcome) => {
const bundle = path.join(entryDir, "bundle.mjs")
const originalChmod = fs.chmodSync
const originalRename = fs.renameSync
const chmod = vi.spyOn(fs, "chmodSync").mockImplementation((location, mode) => {
if (String(location).endsWith(".mjs")) {
expect(fs.existsSync(bundle)).toBe(false)
expect(fs.readFileSync(location, "utf8")).toContain('name: "safe"')
if (outcome === "validation failure") return originalChmod(location, 0o644)
}
return originalChmod(location, mode)
})
const rename = vi.spyOn(fs, "renameSync").mockImplementation((source, destination) => {
expect(destination).toBe(bundle)
expect(fs.statSync(source).mode & 0o777).toBe(0o600)
if (outcome === "publish failure") throw new Error("Synthetic publish failure")
originalRename(source, destination)
})
if (outcome === "build failure") fs.writeFileSync(path.join(toolDir, "safe.ts"), "export default {")
try {
const result = await registry.loadFromDirectory(toolDir)
expect(result.loaded).toEqual(outcome === "success" ? ["safe"] : [])
expect(result.failed).toHaveLength(outcome === "success" ? 0 : 1)
// A source change creates a new hash, so inspect all entries.
const entries = fs.readdirSync(cacheDir)
for (const entry of entries) {
expect(
fs.readdirSync(path.join(cacheDir, entry)).filter((name) => name.endsWith(".tmp.mjs")),
).toEqual([])
}
expect(fs.existsSync(bundle)).toBe(outcome === "success")
expect(rename).toHaveBeenCalledTimes(outcome === "success" || outcome === "publish failure" ? 1 : 0)
} finally {
chmod.mockRestore()
rename.mockRestore()
}
},
)

it("creates nested configured cache directories privately", async () => {
const nested = path.join(cacheDir, "nested", "cache")
const nestedRegistry = new CustomToolRegistry({ cacheDir: nested })
expect((await nestedRegistry.loadFromDirectory(toolDir)).loaded).toEqual(["safe"])
expect(fs.statSync(nested).mode & 0o077).toBe(0)
})

it("rechecks permissions before using the in-memory cache", async () => {
expect((await registry.loadFromDirectory(toolDir)).loaded).toEqual(["safe"])
fs.chmodSync(entryDir, 0o777)
expect((await registry.loadFromDirectory(toolDir)).failed[0]?.error).toContain("Unsafe custom tool cache")
})

it("rejects cache paths beneath a replaceable parent", async () => {
fs.chmodSync(sandbox, 0o777)
expect((await registry.loadFromDirectory(toolDir)).failed[0]?.error).toContain(
"Unsafe custom tool cache parent",
)
})
})

describe("loadFromDirectory", () => {
it("should load tools from TypeScript files", async () => {
const result = await registry.loadFromDirectory(TEST_FIXTURES_DIR)
Expand Down
Loading
Loading