@draht/coding-agent 2026.7.30 → 2026.9.5-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/CHANGELOG.md +154 -0
- package/README.md +46 -2
- package/agents/debugger.md +12 -1
- package/agents/git-committer.md +1 -0
- package/agents/implementer.md +20 -0
- package/agents/investigator.md +75 -0
- package/agents/reviewer.md +7 -0
- package/agents/spec-reviewer.md +66 -0
- package/agents/verifier.md +4 -3
- package/bin/draht-tools.cjs +472 -41
- package/dist/agents/debugger.md +12 -1
- package/dist/agents/git-committer.md +1 -0
- package/dist/agents/implementer.md +20 -0
- package/dist/agents/investigator.md +75 -0
- package/dist/agents/reviewer.md +7 -0
- package/dist/agents/spec-reviewer.md +66 -0
- package/dist/agents/verifier.md +4 -3
- package/dist/cli/args.d.ts +10 -0
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +69 -2
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/attach-mode.d.ts +61 -0
- package/dist/cli/attach-mode.d.ts.map +1 -1
- package/dist/cli/attach-mode.js +243 -5
- package/dist/cli/attach-mode.js.map +1 -1
- package/dist/cli/credential-print.d.ts +1 -1
- package/dist/cli/credential-print.d.ts.map +1 -1
- package/dist/cli/credential-print.js +5 -4
- package/dist/cli/credential-print.js.map +1 -1
- package/dist/config.d.ts +9 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +31 -4
- package/dist/config.js.map +1 -1
- package/dist/core/agent-session-runtime.d.ts +17 -1
- package/dist/core/agent-session-runtime.d.ts.map +1 -1
- package/dist/core/agent-session-runtime.js +87 -30
- package/dist/core/agent-session-runtime.js.map +1 -1
- package/dist/core/agent-session-services.d.ts +1 -1
- package/dist/core/agent-session-services.d.ts.map +1 -1
- package/dist/core/agent-session-services.js +1 -0
- package/dist/core/agent-session-services.js.map +1 -1
- package/dist/core/agent-session.d.ts +35 -16
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +149 -64
- package/dist/core/agent-session.js.map +1 -1
- package/dist/core/auth-storage.d.ts +5 -1
- package/dist/core/auth-storage.d.ts.map +1 -1
- package/dist/core/auth-storage.js +72 -15
- package/dist/core/auth-storage.js.map +1 -1
- package/dist/core/builtins/checkpoints.d.ts +20 -0
- package/dist/core/builtins/checkpoints.d.ts.map +1 -0
- package/dist/core/builtins/checkpoints.js +161 -0
- package/dist/core/builtins/checkpoints.js.map +1 -0
- package/dist/core/builtins/duet.d.ts +26 -0
- package/dist/core/builtins/duet.d.ts.map +1 -0
- package/dist/core/builtins/duet.js +660 -0
- package/dist/core/builtins/duet.js.map +1 -0
- package/dist/core/builtins/index.d.ts.map +1 -1
- package/dist/core/builtins/index.js +7 -1
- package/dist/core/builtins/index.js.map +1 -1
- package/dist/core/builtins/subagent.d.ts +24 -4
- package/dist/core/builtins/subagent.d.ts.map +1 -1
- package/dist/core/builtins/subagent.js +278 -35
- package/dist/core/builtins/subagent.js.map +1 -1
- package/dist/core/checkpoints/checkpoint-cli.d.ts +17 -0
- package/dist/core/checkpoints/checkpoint-cli.d.ts.map +1 -0
- package/dist/core/checkpoints/checkpoint-cli.js +78 -0
- package/dist/core/checkpoints/checkpoint-cli.js.map +1 -0
- package/dist/core/checkpoints/checkpoint-manager.d.ts +294 -0
- package/dist/core/checkpoints/checkpoint-manager.d.ts.map +1 -0
- package/dist/core/checkpoints/checkpoint-manager.js +865 -0
- package/dist/core/checkpoints/checkpoint-manager.js.map +1 -0
- package/dist/core/checkpoints/rewind.d.ts +141 -0
- package/dist/core/checkpoints/rewind.d.ts.map +1 -0
- package/dist/core/checkpoints/rewind.js +246 -0
- package/dist/core/checkpoints/rewind.js.map +1 -0
- package/dist/core/compaction/branch-summarization.d.ts +1 -1
- package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
- package/dist/core/compaction/branch-summarization.js +9 -4
- package/dist/core/compaction/branch-summarization.js.map +1 -1
- package/dist/core/compaction/compaction.d.ts +5 -0
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +25 -4
- package/dist/core/compaction/compaction.js.map +1 -1
- package/dist/core/extensions/index.d.ts +1 -1
- package/dist/core/extensions/index.d.ts.map +1 -1
- package/dist/core/extensions/index.js.map +1 -1
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +83 -20
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts +13 -2
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +37 -2
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +189 -6
- package/dist/core/extensions/types.d.ts.map +1 -1
- package/dist/core/extensions/types.js.map +1 -1
- package/dist/core/http-dispatcher.d.ts.map +1 -1
- package/dist/core/http-dispatcher.js +7 -0
- package/dist/core/http-dispatcher.js.map +1 -1
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js.map +1 -1
- package/dist/core/keybindings.d.ts +5 -0
- package/dist/core/keybindings.d.ts.map +1 -1
- package/dist/core/keybindings.js +1 -0
- package/dist/core/keybindings.js.map +1 -1
- package/dist/core/model-registry.d.ts +3 -2
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +8 -8
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/model-resolver.d.ts.map +1 -1
- package/dist/core/model-resolver.js +34 -7
- package/dist/core/model-resolver.js.map +1 -1
- package/dist/core/model-runtime.d.ts +7 -1
- package/dist/core/model-runtime.d.ts.map +1 -1
- package/dist/core/model-runtime.js +30 -10
- package/dist/core/model-runtime.js.map +1 -1
- package/dist/core/multi-agent/permission-gate.d.ts.map +1 -1
- package/dist/core/multi-agent/permission-gate.js +4 -3
- package/dist/core/multi-agent/permission-gate.js.map +1 -1
- package/dist/core/multi-agent/worktree.d.ts +2 -0
- package/dist/core/multi-agent/worktree.d.ts.map +1 -1
- package/dist/core/multi-agent/worktree.js +2 -2
- package/dist/core/multi-agent/worktree.js.map +1 -1
- package/dist/core/package-manager.d.ts +7 -1
- package/dist/core/package-manager.d.ts.map +1 -1
- package/dist/core/package-manager.js +21 -44
- package/dist/core/package-manager.js.map +1 -1
- package/dist/core/permission-relay/index.d.ts +19 -0
- package/dist/core/permission-relay/index.d.ts.map +1 -0
- package/dist/core/permission-relay/index.js +49 -0
- package/dist/core/permission-relay/index.js.map +1 -0
- package/dist/core/permission-relay/relay-ui-context.d.ts +39 -0
- package/dist/core/permission-relay/relay-ui-context.d.ts.map +1 -0
- package/dist/core/permission-relay/relay-ui-context.js +788 -0
- package/dist/core/permission-relay/relay-ui-context.js.map +1 -0
- package/dist/core/permission-relay/types.d.ts +222 -0
- package/dist/core/permission-relay/types.d.ts.map +1 -0
- package/dist/core/permission-relay/types.js +15 -0
- package/dist/core/permission-relay/types.js.map +1 -0
- package/dist/core/pi-manifest.d.ts +14 -0
- package/dist/core/pi-manifest.d.ts.map +1 -0
- package/dist/core/pi-manifest.js +35 -0
- package/dist/core/pi-manifest.js.map +1 -0
- package/dist/core/project-trust.js +2 -2
- package/dist/core/project-trust.js.map +1 -1
- package/dist/core/resource-loader.d.ts +21 -0
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +101 -24
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/sandbox/bash-operations.d.ts +149 -0
- package/dist/core/sandbox/bash-operations.d.ts.map +1 -0
- package/dist/core/sandbox/bash-operations.js +163 -0
- package/dist/core/sandbox/bash-operations.js.map +1 -0
- package/dist/core/sandbox/env.d.ts +83 -0
- package/dist/core/sandbox/env.d.ts.map +1 -0
- package/dist/core/sandbox/env.js +123 -0
- package/dist/core/sandbox/env.js.map +1 -0
- package/dist/core/sandbox/executor.d.ts +104 -0
- package/dist/core/sandbox/executor.d.ts.map +1 -0
- package/dist/core/sandbox/executor.js +92 -0
- package/dist/core/sandbox/executor.js.map +1 -0
- package/dist/core/sandbox/index.d.ts +36 -0
- package/dist/core/sandbox/index.d.ts.map +1 -0
- package/dist/core/sandbox/index.js +36 -0
- package/dist/core/sandbox/index.js.map +1 -0
- package/dist/core/sandbox/linux.d.ts +121 -0
- package/dist/core/sandbox/linux.d.ts.map +1 -0
- package/dist/core/sandbox/linux.js +260 -0
- package/dist/core/sandbox/linux.js.map +1 -0
- package/dist/core/sandbox/policy.d.ts +142 -0
- package/dist/core/sandbox/policy.d.ts.map +1 -0
- package/dist/core/sandbox/policy.js +297 -0
- package/dist/core/sandbox/policy.js.map +1 -0
- package/dist/core/sandbox/real-path.d.ts +112 -0
- package/dist/core/sandbox/real-path.d.ts.map +1 -0
- package/dist/core/sandbox/real-path.js +158 -0
- package/dist/core/sandbox/real-path.js.map +1 -0
- package/dist/core/sandbox/seatbelt-profile.d.ts +95 -0
- package/dist/core/sandbox/seatbelt-profile.d.ts.map +1 -0
- package/dist/core/sandbox/seatbelt-profile.js +239 -0
- package/dist/core/sandbox/seatbelt-profile.js.map +1 -0
- package/dist/core/sandbox/seatbelt.d.ts +95 -0
- package/dist/core/sandbox/seatbelt.d.ts.map +1 -0
- package/dist/core/sandbox/seatbelt.js +154 -0
- package/dist/core/sandbox/seatbelt.js.map +1 -0
- package/dist/core/sandbox/self-test.d.ts +109 -0
- package/dist/core/sandbox/self-test.d.ts.map +1 -0
- package/dist/core/sandbox/self-test.js +369 -0
- package/dist/core/sandbox/self-test.js.map +1 -0
- package/dist/core/sandbox/spawn.d.ts +33 -0
- package/dist/core/sandbox/spawn.d.ts.map +1 -0
- package/dist/core/sandbox/spawn.js +87 -0
- package/dist/core/sandbox/spawn.js.map +1 -0
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +3 -1
- package/dist/core/sdk.js.map +1 -1
- package/dist/core/session-manager.d.ts +60 -1
- package/dist/core/session-manager.d.ts.map +1 -1
- package/dist/core/session-manager.js +53 -6
- package/dist/core/session-manager.js.map +1 -1
- package/dist/core/settings-manager.d.ts +21 -0
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js +36 -16
- package/dist/core/settings-manager.js.map +1 -1
- package/dist/core/skills.d.ts +3 -1
- package/dist/core/skills.d.ts.map +1 -1
- package/dist/core/skills.js +19 -6
- package/dist/core/skills.js.map +1 -1
- package/dist/core/slash-commands.d.ts.map +1 -1
- package/dist/core/slash-commands.js +1 -0
- package/dist/core/slash-commands.js.map +1 -1
- package/dist/core/soak/soak-log.d.ts +298 -0
- package/dist/core/soak/soak-log.d.ts.map +1 -0
- package/dist/core/soak/soak-log.js +660 -0
- package/dist/core/soak/soak-log.js.map +1 -0
- package/dist/core/soak/soak-reader.d.ts +60 -0
- package/dist/core/soak/soak-reader.d.ts.map +1 -0
- package/dist/core/soak/soak-reader.js +106 -0
- package/dist/core/soak/soak-reader.js.map +1 -0
- package/dist/core/socket-server/discovery.d.ts +78 -1
- package/dist/core/socket-server/discovery.d.ts.map +1 -1
- package/dist/core/socket-server/discovery.js +356 -37
- package/dist/core/socket-server/discovery.js.map +1 -1
- package/dist/core/socket-server/index.d.ts +10 -4
- package/dist/core/socket-server/index.d.ts.map +1 -1
- package/dist/core/socket-server/index.js +6 -3
- package/dist/core/socket-server/index.js.map +1 -1
- package/dist/core/socket-server/permission-delivery.d.ts +125 -0
- package/dist/core/socket-server/permission-delivery.d.ts.map +1 -0
- package/dist/core/socket-server/permission-delivery.js +152 -0
- package/dist/core/socket-server/permission-delivery.js.map +1 -0
- package/dist/core/socket-server/permission-registry.d.ts +301 -0
- package/dist/core/socket-server/permission-registry.d.ts.map +1 -0
- package/dist/core/socket-server/permission-registry.js +410 -0
- package/dist/core/socket-server/permission-registry.js.map +1 -0
- package/dist/core/socket-server/permission-relay.d.ts +81 -0
- package/dist/core/socket-server/permission-relay.d.ts.map +1 -0
- package/dist/core/socket-server/permission-relay.js +528 -0
- package/dist/core/socket-server/permission-relay.js.map +1 -0
- package/dist/core/socket-server/safe-text.d.ts +83 -0
- package/dist/core/socket-server/safe-text.d.ts.map +1 -0
- package/dist/core/socket-server/safe-text.js +277 -0
- package/dist/core/socket-server/safe-text.js.map +1 -0
- package/dist/core/socket-server/session-integration.d.ts +65 -2
- package/dist/core/socket-server/session-integration.d.ts.map +1 -1
- package/dist/core/socket-server/session-integration.js +434 -32
- package/dist/core/socket-server/session-integration.js.map +1 -1
- package/dist/core/socket-server/socket-client.d.ts +21 -2
- package/dist/core/socket-server/socket-client.d.ts.map +1 -1
- package/dist/core/socket-server/socket-client.js +52 -1
- package/dist/core/socket-server/socket-client.js.map +1 -1
- package/dist/core/socket-server/socket-server.d.ts +152 -1
- package/dist/core/socket-server/socket-server.d.ts.map +1 -1
- package/dist/core/socket-server/socket-server.js +775 -26
- package/dist/core/socket-server/socket-server.js.map +1 -1
- package/dist/core/socket-server/types.d.ts +106 -2
- package/dist/core/socket-server/types.d.ts.map +1 -1
- package/dist/core/socket-server/types.js +13 -1
- package/dist/core/socket-server/types.js.map +1 -1
- package/dist/core/system-prompt.d.ts.map +1 -1
- package/dist/core/system-prompt.js +8 -9
- package/dist/core/system-prompt.js.map +1 -1
- package/dist/core/tools/bash.d.ts +1 -1
- package/dist/core/tools/bash.d.ts.map +1 -1
- package/dist/core/tools/bash.js +5 -2
- package/dist/core/tools/bash.js.map +1 -1
- package/dist/core/tools/edit.d.ts.map +1 -1
- package/dist/core/tools/edit.js +17 -2
- package/dist/core/tools/edit.js.map +1 -1
- package/dist/core/tools/find.d.ts +3 -0
- package/dist/core/tools/find.d.ts.map +1 -1
- package/dist/core/tools/find.js +11 -18
- package/dist/core/tools/find.js.map +1 -1
- package/dist/core/trust-manager.d.ts +6 -4
- package/dist/core/trust-manager.d.ts.map +1 -1
- package/dist/core/trust-manager.js +55 -21
- package/dist/core/trust-manager.js.map +1 -1
- package/dist/extensions/index.d.ts.map +1 -1
- package/dist/extensions/index.js +5 -1
- package/dist/extensions/index.js.map +1 -1
- package/dist/extensions/llama/provider.d.ts.map +1 -1
- package/dist/extensions/llama/provider.js +5 -1
- package/dist/extensions/llama/provider.js.map +1 -1
- package/dist/extensions/stub-provider/index.d.ts +9 -0
- package/dist/extensions/stub-provider/index.d.ts.map +1 -0
- package/dist/extensions/stub-provider/index.js +13 -0
- package/dist/extensions/stub-provider/index.js.map +1 -0
- package/dist/extensions/stub-provider/provider.d.ts +77 -0
- package/dist/extensions/stub-provider/provider.d.ts.map +1 -0
- package/dist/extensions/stub-provider/provider.js +193 -0
- package/dist/extensions/stub-provider/provider.js.map +1 -0
- package/dist/hooks/gsd/draht-quality-gate.js +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +242 -45
- package/dist/main.js.map +1 -1
- package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/config-selector.js +3 -2
- package/dist/modes/interactive/components/config-selector.js.map +1 -1
- package/dist/modes/interactive/components/extension-selector.d.ts +49 -0
- package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/extension-selector.js +202 -5
- package/dist/modes/interactive/components/extension-selector.js.map +1 -1
- package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/session-selector.js +10 -2
- package/dist/modes/interactive/components/session-selector.js.map +1 -1
- package/dist/modes/interactive/components/settings-selector.d.ts +2 -0
- package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/settings-selector.js +10 -0
- package/dist/modes/interactive/components/settings-selector.js.map +1 -1
- package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
- package/dist/modes/interactive/components/tool-execution.js +10 -1
- package/dist/modes/interactive/components/tool-execution.js.map +1 -1
- package/dist/modes/interactive/components/tree-selector.d.ts +20 -2
- package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/tree-selector.js +21 -5
- package/dist/modes/interactive/components/tree-selector.js.map +1 -1
- package/dist/modes/interactive/interactive-mode.d.ts +97 -3
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +394 -24
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-mode.js +165 -7
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-types.d.ts +68 -1
- package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-types.js.map +1 -1
- package/dist/prompts/commands/atomic-commit.md +1 -12
- package/dist/prompts/commands/brainstorm.md +12 -15
- package/dist/prompts/commands/create-verification-skill.md +108 -0
- package/dist/prompts/commands/discuss-phase.md +3 -14
- package/dist/prompts/commands/execute-phase.md +3 -11
- package/dist/prompts/commands/fix.md +41 -18
- package/dist/prompts/commands/grill.md +66 -0
- package/dist/prompts/commands/init-project.md +5 -15
- package/dist/prompts/commands/map-codebase.md +1 -13
- package/dist/prompts/commands/new-project.md +5 -15
- package/dist/prompts/commands/next-milestone.md +1 -13
- package/dist/prompts/commands/orchestrate.md +1 -1
- package/dist/prompts/commands/pause-work.md +1 -13
- package/dist/prompts/commands/plan-phase.md +2 -11
- package/dist/prompts/commands/progress.md +0 -13
- package/dist/prompts/commands/quick.md +3 -11
- package/dist/prompts/commands/resolve-conflicts.md +71 -0
- package/dist/prompts/commands/resume-work.md +0 -13
- package/dist/prompts/commands/review.md +4 -13
- package/dist/prompts/commands/triage.md +159 -0
- package/dist/prompts/commands/verify-work.md +4 -14
- package/dist/prompts/commands/why.md +135 -0
- package/dist/skills/atomic-reasoning/SKILL.md +115 -0
- package/dist/skills/blast-radius/SKILL.md +55 -0
- package/dist/skills/epistemics/SKILL.md +99 -0
- package/dist/skills/hexagon-animation/SKILL.md +49 -0
- package/dist/skills/hexagon-animation/generate.mjs +81 -0
- package/dist/skills/hexagon-animation/template.html +361 -0
- package/dist/skills/typescript-discipline/SKILL.md +50 -0
- package/dist/skills/typescript-discipline/references/patterns.md +294 -0
- package/dist/skills/unslop/SKILL.md +101 -0
- package/dist/utils/canonical-path.d.ts +28 -0
- package/dist/utils/canonical-path.d.ts.map +1 -0
- package/dist/utils/canonical-path.js +90 -0
- package/dist/utils/canonical-path.js.map +1 -0
- package/dist/utils/child-process.d.ts +12 -1
- package/dist/utils/child-process.d.ts.map +1 -1
- package/dist/utils/child-process.js +25 -8
- package/dist/utils/child-process.js.map +1 -1
- package/dist/utils/clipboard.d.ts +1 -1
- package/dist/utils/clipboard.d.ts.map +1 -1
- package/dist/utils/clipboard.js +22 -2
- package/dist/utils/clipboard.js.map +1 -1
- package/dist/utils/exif-orientation.d.ts.map +1 -1
- package/dist/utils/exif-orientation.js +2 -3
- package/dist/utils/exif-orientation.js.map +1 -1
- package/dist/utils/paths.d.ts +2 -7
- package/dist/utils/paths.d.ts.map +1 -1
- package/dist/utils/paths.js +13 -15
- package/dist/utils/paths.js.map +1 -1
- package/dist/utils/shell.d.ts.map +1 -1
- package/dist/utils/shell.js +6 -4
- package/dist/utils/shell.js.map +1 -1
- package/dist/utils/tools-manager.d.ts.map +1 -1
- package/dist/utils/tools-manager.js +3 -5
- package/dist/utils/tools-manager.js.map +1 -1
- package/docs/attachable-sessions.md +79 -0
- package/docs/compaction.md +21 -21
- package/docs/containerization.md +23 -23
- package/docs/custom-provider.md +16 -16
- package/docs/development.md +9 -9
- package/docs/docs.json +6 -2
- package/docs/duet.md +42 -0
- package/docs/extensions.md +58 -58
- package/docs/index.md +10 -10
- package/docs/json.md +7 -7
- package/docs/keybindings.md +6 -5
- package/docs/llama-cpp.md +6 -6
- package/docs/models.md +6 -6
- package/docs/packages.md +43 -43
- package/docs/prompt-templates.md +4 -4
- package/docs/providers.md +12 -12
- package/docs/quickstart.md +32 -32
- package/docs/rpc.md +83 -12
- package/docs/sdk.md +15 -15
- package/docs/security.md +18 -18
- package/docs/session-format.md +35 -13
- package/docs/sessions.md +17 -14
- package/docs/settings.md +25 -18
- package/docs/shell-aliases.md +2 -2
- package/docs/skills.md +12 -11
- package/docs/terminal-setup.md +12 -12
- package/docs/termux.md +6 -6
- package/docs/themes.md +11 -11
- package/docs/tmux.md +4 -4
- package/docs/tui.md +5 -5
- package/docs/usage.md +50 -50
- package/docs/windows.md +2 -2
- package/examples/extensions/overlay-qa-tests.ts +3 -3
- package/hooks/gsd/draht-quality-gate.js +3 -3
- package/package.json +11 -10
- package/prompts/commands/atomic-commit.md +1 -12
- package/prompts/commands/brainstorm.md +12 -15
- package/prompts/commands/create-verification-skill.md +108 -0
- package/prompts/commands/discuss-phase.md +3 -14
- package/prompts/commands/execute-phase.md +3 -11
- package/prompts/commands/fix.md +41 -18
- package/prompts/commands/grill.md +66 -0
- package/prompts/commands/init-project.md +5 -15
- package/prompts/commands/map-codebase.md +1 -13
- package/prompts/commands/new-project.md +5 -15
- package/prompts/commands/next-milestone.md +1 -13
- package/prompts/commands/orchestrate.md +1 -1
- package/prompts/commands/pause-work.md +1 -13
- package/prompts/commands/plan-phase.md +2 -11
- package/prompts/commands/progress.md +0 -13
- package/prompts/commands/quick.md +3 -11
- package/prompts/commands/resolve-conflicts.md +71 -0
- package/prompts/commands/resume-work.md +0 -13
- package/prompts/commands/review.md +4 -13
- package/prompts/commands/triage.md +159 -0
- package/prompts/commands/verify-work.md +4 -14
- package/prompts/commands/why.md +135 -0
- package/skills/atomic-reasoning/SKILL.md +115 -0
- package/skills/blast-radius/SKILL.md +55 -0
- package/skills/epistemics/SKILL.md +99 -0
- package/skills/hexagon-animation/SKILL.md +49 -0
- package/skills/hexagon-animation/generate.mjs +81 -0
- package/skills/hexagon-animation/template.html +361 -0
- package/skills/typescript-discipline/SKILL.md +50 -0
- package/skills/typescript-discipline/references/patterns.md +294 -0
- package/skills/unslop/SKILL.md +101 -0
- package/dist/prompts/agents/build.md +0 -86
- package/dist/prompts/agents/plan.md +0 -79
- package/dist/prompts/agents/verify.md +0 -69
- package/prompts/agents/build.md +0 -86
- package/prompts/agents/plan.md +0 -79
- package/prompts/agents/verify.md +0 -69
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `SandboxPolicy` v1 (R44-SBX.2) and its resolution (R44-SBX.3).
|
|
3
|
+
*
|
|
4
|
+
* The policy is a **plain declarative value**: a resolved write allowlist, a
|
|
5
|
+
* read mode, a network toggle, and a privilege-escalation invariant. Backends
|
|
6
|
+
* translate it into an SBPL profile / a Landlock ruleset; they do not extend it.
|
|
7
|
+
* Keeping it plain is what makes it reviewable, serialisable, diffable and
|
|
8
|
+
* testable independently of any platform.
|
|
9
|
+
*
|
|
10
|
+
* v1 shape, deliberately small (see
|
|
11
|
+
* `.planning/specs/2026-07-12-bash-sandbox-confinement.md`):
|
|
12
|
+
*
|
|
13
|
+
* - **Write allowlist** -- project cwd, session scratch dir, OS temp,
|
|
14
|
+
* `extraWritePaths` from settings, plus a curated set of cache roots that dev
|
|
15
|
+
* toolchains write to outside the project. Everything else is read-only.
|
|
16
|
+
* - **Read** -- allow-all. Dev workflows read toolchains, caches and dotfiles
|
|
17
|
+
* constantly; a read-deny list is a v2 concern and must not block v1.
|
|
18
|
+
* - **Network** -- one on/off toggle, default **on** (`npm install`, `git fetch`).
|
|
19
|
+
* - **Privilege escalation** -- not representable. `allowPrivilegeEscalation` is
|
|
20
|
+
* the literal `false`, not a boolean, so no caller can widen it and every
|
|
21
|
+
* backend must render a profile in which `sudo` cannot work by construction.
|
|
22
|
+
*
|
|
23
|
+
* ## Resolution rules
|
|
24
|
+
*
|
|
25
|
+
* Every path is real-path resolved *before* it lands in the policy (see
|
|
26
|
+
* `real-path.ts` for why). The two classes of input are treated differently on
|
|
27
|
+
* failure, and the difference is deliberate:
|
|
28
|
+
*
|
|
29
|
+
* - **Agent-supplied paths** (`cwd`, `sessionScratchDir`, `tmpDir`) that cannot
|
|
30
|
+
* be resolved throw `SandboxPolicyError`. A session whose own working
|
|
31
|
+
* directory does not resolve is broken; backends catch this and report
|
|
32
|
+
* `unavailable`, which is the fail-closed outcome.
|
|
33
|
+
* - **User-configured paths** (`extraWritePaths`) that cannot be resolved are
|
|
34
|
+
* dropped and reported in `rejected`. Dropping narrows the writable set, so it
|
|
35
|
+
* is safe; it is never silent, so it is debuggable.
|
|
36
|
+
*
|
|
37
|
+
* ## Excluded roots: the exclusions apply to *every* entry, cwd included
|
|
38
|
+
*
|
|
39
|
+
* The curated cache roots below deliberately exclude `~` itself. That exclusion
|
|
40
|
+
* used to be trivially defeated: `cwd` was pushed into the allowlist with no
|
|
41
|
+
* check at all, so running the agent from `$HOME` (or `/Users`, or macOS's
|
|
42
|
+
* `/System/Volumes/Data`) produced a policy whose allowlist *was* the home
|
|
43
|
+
* directory -- silently, with no `rejected` entry, and reported `available`. A
|
|
44
|
+
* sandbox whose allowlist is `$HOME` confines nothing, and the user had no way
|
|
45
|
+
* to know.
|
|
46
|
+
*
|
|
47
|
+
* So `excludedWriteRootReason` is applied uniformly, and the two input classes
|
|
48
|
+
* keep their documented failure modes: an excluded **agent-supplied** path
|
|
49
|
+
* throws, an excluded **configured** path lands in `rejected` and is surfaced.
|
|
50
|
+
* The check is not purely lexical -- `/System/Volumes/Data/Users/alice` is
|
|
51
|
+
* `realpath`-stable on macOS yet is the same directory as `/Users/alice`, so
|
|
52
|
+
* candidates are also compared to the home directory and its ancestors by
|
|
53
|
+
* device+inode identity.
|
|
54
|
+
*/
|
|
55
|
+
export declare const SANDBOX_POLICY_VERSION = 1;
|
|
56
|
+
export type SandboxNetworkMode = "on" | "off";
|
|
57
|
+
/** Resolved, declarative sandbox policy. Frozen: backends read it, never edit it. */
|
|
58
|
+
export interface SandboxPolicy {
|
|
59
|
+
readonly version: typeof SANDBOX_POLICY_VERSION;
|
|
60
|
+
/**
|
|
61
|
+
* Absolute, real-path resolved, deduplicated, minimal (no entry nested under
|
|
62
|
+
* another) and sorted. The sort makes generated profiles byte-stable, which
|
|
63
|
+
* matters for profile caching and for diffing what a session was allowed to do.
|
|
64
|
+
*/
|
|
65
|
+
readonly writePaths: readonly string[];
|
|
66
|
+
/** v1 is read allow-all. A union so v2 can add modes without changing the field. */
|
|
67
|
+
readonly read: "allow-all";
|
|
68
|
+
readonly network: SandboxNetworkMode;
|
|
69
|
+
/**
|
|
70
|
+
* Always `false`, and typed as the literal so it cannot be set otherwise.
|
|
71
|
+
* Backends must render a profile where privilege escalation is impossible,
|
|
72
|
+
* and the R44-SBX.4 self-test probes it before any backend reports
|
|
73
|
+
* `available` (see `self-test.ts`).
|
|
74
|
+
*/
|
|
75
|
+
readonly allowPrivilegeEscalation: false;
|
|
76
|
+
}
|
|
77
|
+
export interface SandboxPolicyInput {
|
|
78
|
+
/** Project working directory. Must exist, resolve, and not be an excluded root. */
|
|
79
|
+
cwd: string;
|
|
80
|
+
/** The session's scratch directory, when it has one. */
|
|
81
|
+
sessionScratchDir?: string;
|
|
82
|
+
/** OS temp dir. Defaults to `os.tmpdir()`; overridable for tests. */
|
|
83
|
+
tmpDir?: string;
|
|
84
|
+
/** Additional writable roots from settings / `permissions.yml`. */
|
|
85
|
+
extraWritePaths?: readonly string[];
|
|
86
|
+
/** Include the curated cache roots below. Defaults to `true`. */
|
|
87
|
+
includeDefaultCacheRoots?: boolean;
|
|
88
|
+
/** Home directory used to expand cache roots and to compute exclusions. Defaults to `os.homedir()`. */
|
|
89
|
+
homeDir?: string;
|
|
90
|
+
/** Defaults to `"on"`. */
|
|
91
|
+
network?: SandboxNetworkMode;
|
|
92
|
+
/** Platform the exclusion list is curated for. Defaults to `process.platform`. */
|
|
93
|
+
platform?: NodeJS.Platform;
|
|
94
|
+
}
|
|
95
|
+
export interface RejectedWritePath {
|
|
96
|
+
/** The entry exactly as configured, so the user can find it in their settings. */
|
|
97
|
+
readonly input: string;
|
|
98
|
+
readonly reason: string;
|
|
99
|
+
}
|
|
100
|
+
export interface SandboxPolicyResolution {
|
|
101
|
+
readonly policy: SandboxPolicy;
|
|
102
|
+
/**
|
|
103
|
+
* Configured write paths that were dropped. Never empty-but-ignored: surfacing
|
|
104
|
+
* these is what keeps "we narrowed your policy" from being a silent behaviour.
|
|
105
|
+
*/
|
|
106
|
+
readonly rejected: readonly RejectedWritePath[];
|
|
107
|
+
}
|
|
108
|
+
/** Thrown when an agent-supplied policy path cannot be resolved or is an excluded root (see module doc). */
|
|
109
|
+
export declare class SandboxPolicyError extends Error {
|
|
110
|
+
constructor(message: string);
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Why `path` must not enter the write allowlist, or `null` when it may.
|
|
114
|
+
*
|
|
115
|
+
* `path` must already be real-path resolved. The reason is a sentence fragment
|
|
116
|
+
* that reads after "refusing ...: <reason>".
|
|
117
|
+
*/
|
|
118
|
+
export declare function excludedWriteRootReason(path: string, home: string | undefined, platform: NodeJS.Platform): string | null;
|
|
119
|
+
/**
|
|
120
|
+
* Builds a v1 policy from `input`, real-path resolving every path first.
|
|
121
|
+
*
|
|
122
|
+
* Throws `SandboxPolicyError` when an agent-supplied path cannot be resolved or
|
|
123
|
+
* is an excluded root; drops unresolvable or excluded `extraWritePaths` into
|
|
124
|
+
* `rejected`.
|
|
125
|
+
*/
|
|
126
|
+
export declare function resolveSandboxPolicy(input: SandboxPolicyInput): SandboxPolicyResolution;
|
|
127
|
+
/**
|
|
128
|
+
* Whether `policy` permits writing to `candidate`.
|
|
129
|
+
*
|
|
130
|
+
* Resolves `candidate` to a real path first -- a lexical `startsWith` against
|
|
131
|
+
* `writePaths` is exactly the bug this exists to prevent, since a symlink or a
|
|
132
|
+
* `..` hop makes an in-project-looking string name a file outside the project.
|
|
133
|
+
* Use this anywhere an in-process pre-check is needed; the kernel backend
|
|
134
|
+
* remains the enforcement boundary, this mirrors it.
|
|
135
|
+
*
|
|
136
|
+
* `candidate` must be absolute unless a `base` is given. Anything unresolvable
|
|
137
|
+
* answers `false` -- an undecidable path is not a writable one.
|
|
138
|
+
*/
|
|
139
|
+
export declare function isPathWritable(policy: SandboxPolicy, candidate: string, options?: {
|
|
140
|
+
base?: string;
|
|
141
|
+
}): boolean;
|
|
142
|
+
//# sourceMappingURL=policy.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAOH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,KAAK,CAAC;AAE9C,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,sBAAsB,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,wBAAwB,EAAE,KAAK,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IAClC,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iEAAiE;IACjE,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IACjC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAChD;AAED,4GAA4G;AAC5G,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACD;AAkGD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,EAAE,MAAM,CAAC,QAAQ,GACvB,MAAM,GAAG,IAAI,CAoBf;AAsBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,uBAAuB,CAkEvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAK7G"}
|
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `SandboxPolicy` v1 (R44-SBX.2) and its resolution (R44-SBX.3).
|
|
3
|
+
*
|
|
4
|
+
* The policy is a **plain declarative value**: a resolved write allowlist, a
|
|
5
|
+
* read mode, a network toggle, and a privilege-escalation invariant. Backends
|
|
6
|
+
* translate it into an SBPL profile / a Landlock ruleset; they do not extend it.
|
|
7
|
+
* Keeping it plain is what makes it reviewable, serialisable, diffable and
|
|
8
|
+
* testable independently of any platform.
|
|
9
|
+
*
|
|
10
|
+
* v1 shape, deliberately small (see
|
|
11
|
+
* `.planning/specs/2026-07-12-bash-sandbox-confinement.md`):
|
|
12
|
+
*
|
|
13
|
+
* - **Write allowlist** -- project cwd, session scratch dir, OS temp,
|
|
14
|
+
* `extraWritePaths` from settings, plus a curated set of cache roots that dev
|
|
15
|
+
* toolchains write to outside the project. Everything else is read-only.
|
|
16
|
+
* - **Read** -- allow-all. Dev workflows read toolchains, caches and dotfiles
|
|
17
|
+
* constantly; a read-deny list is a v2 concern and must not block v1.
|
|
18
|
+
* - **Network** -- one on/off toggle, default **on** (`npm install`, `git fetch`).
|
|
19
|
+
* - **Privilege escalation** -- not representable. `allowPrivilegeEscalation` is
|
|
20
|
+
* the literal `false`, not a boolean, so no caller can widen it and every
|
|
21
|
+
* backend must render a profile in which `sudo` cannot work by construction.
|
|
22
|
+
*
|
|
23
|
+
* ## Resolution rules
|
|
24
|
+
*
|
|
25
|
+
* Every path is real-path resolved *before* it lands in the policy (see
|
|
26
|
+
* `real-path.ts` for why). The two classes of input are treated differently on
|
|
27
|
+
* failure, and the difference is deliberate:
|
|
28
|
+
*
|
|
29
|
+
* - **Agent-supplied paths** (`cwd`, `sessionScratchDir`, `tmpDir`) that cannot
|
|
30
|
+
* be resolved throw `SandboxPolicyError`. A session whose own working
|
|
31
|
+
* directory does not resolve is broken; backends catch this and report
|
|
32
|
+
* `unavailable`, which is the fail-closed outcome.
|
|
33
|
+
* - **User-configured paths** (`extraWritePaths`) that cannot be resolved are
|
|
34
|
+
* dropped and reported in `rejected`. Dropping narrows the writable set, so it
|
|
35
|
+
* is safe; it is never silent, so it is debuggable.
|
|
36
|
+
*
|
|
37
|
+
* ## Excluded roots: the exclusions apply to *every* entry, cwd included
|
|
38
|
+
*
|
|
39
|
+
* The curated cache roots below deliberately exclude `~` itself. That exclusion
|
|
40
|
+
* used to be trivially defeated: `cwd` was pushed into the allowlist with no
|
|
41
|
+
* check at all, so running the agent from `$HOME` (or `/Users`, or macOS's
|
|
42
|
+
* `/System/Volumes/Data`) produced a policy whose allowlist *was* the home
|
|
43
|
+
* directory -- silently, with no `rejected` entry, and reported `available`. A
|
|
44
|
+
* sandbox whose allowlist is `$HOME` confines nothing, and the user had no way
|
|
45
|
+
* to know.
|
|
46
|
+
*
|
|
47
|
+
* So `excludedWriteRootReason` is applied uniformly, and the two input classes
|
|
48
|
+
* keep their documented failure modes: an excluded **agent-supplied** path
|
|
49
|
+
* throws, an excluded **configured** path lands in `rejected` and is surfaced.
|
|
50
|
+
* The check is not purely lexical -- `/System/Volumes/Data/Users/alice` is
|
|
51
|
+
* `realpath`-stable on macOS yet is the same directory as `/Users/alice`, so
|
|
52
|
+
* candidates are also compared to the home directory and its ancestors by
|
|
53
|
+
* device+inode identity.
|
|
54
|
+
*/
|
|
55
|
+
import { statSync } from "node:fs";
|
|
56
|
+
import { homedir, tmpdir } from "node:os";
|
|
57
|
+
import { dirname, isAbsolute, join } from "node:path";
|
|
58
|
+
import { isContainedIn, resolveRealPath } from "./real-path.js";
|
|
59
|
+
export const SANDBOX_POLICY_VERSION = 1;
|
|
60
|
+
/** Thrown when an agent-supplied policy path cannot be resolved or is an excluded root (see module doc). */
|
|
61
|
+
export class SandboxPolicyError extends Error {
|
|
62
|
+
constructor(message) {
|
|
63
|
+
super(message);
|
|
64
|
+
this.name = "SandboxPolicyError";
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Cache roots dev toolchains write to outside the project.
|
|
69
|
+
*
|
|
70
|
+
* The bar an entry has to clear is **not** "regenerable". Every package cache is
|
|
71
|
+
* regenerable, and every package cache also holds code that a later,
|
|
72
|
+
* *unsandboxed* `npm install` / `cargo build` / `npx` links into a tree and
|
|
73
|
+
* runs. Granting one of those is a persistence route straight out of the
|
|
74
|
+
* sandbox, so the bar is:
|
|
75
|
+
*
|
|
76
|
+
* > tampering with an entry must be **detected**, or the entry must be
|
|
77
|
+
* > unreachable by a later lookup, by a mechanism that is on **by default**.
|
|
78
|
+
*
|
|
79
|
+
* What that leaves, and why:
|
|
80
|
+
*
|
|
81
|
+
* | root | why it stays |
|
|
82
|
+
* |--------------------------|------------------------------------------------------------------------------------|
|
|
83
|
+
* | `~/.npm/_cacache` | content-addressed; npm verifies the SRI hash from the lockfile on read, and a mismatch is a cache miss, so a planted blob is unreachable |
|
|
84
|
+
* | `~/.npm/_logs` | plain-text run logs, no code, and npm writes them on every command |
|
|
85
|
+
* | `~/.pnpm-store` | content-addressable store keyed by file hash; `verify-store-integrity` is on by default |
|
|
86
|
+
* | `~/.yarn/berry/cache` | zips checksummed against `yarn.lock`; `checksumBehavior` defaults to `throw` |
|
|
87
|
+
* | `~/.cargo/registry` | `.cargo-checksum.json` is verified on use; a modified crate source is a hard error |
|
|
88
|
+
*
|
|
89
|
+
* Removed in the Phase 44 review, and why each one is a persistence route rather
|
|
90
|
+
* than a cache:
|
|
91
|
+
*
|
|
92
|
+
* - `~/.cache` and `$XDG_CACHE_HOME` -- an unowned catch-all. Playwright browser
|
|
93
|
+
* binaries, pre-commit hook virtualenvs and toolchains installed by `uv` /
|
|
94
|
+
* bazelisk live under it and are executed directly by the next unsandboxed run.
|
|
95
|
+
* - `~/Library/Caches` (macOS) -- same, and worse: Sparkle-style auto-updaters
|
|
96
|
+
* stage the installer they will later launch under `~/Library/Caches/<bundle-id>/`,
|
|
97
|
+
* and Homebrew caches downloaded bottles and `.pkg` installers there.
|
|
98
|
+
* - `~/.npm` as a whole -- narrowed to the two subtrees above because
|
|
99
|
+
* `~/.npm/_npx` holds fully installed package trees that `npx` executes
|
|
100
|
+
* verbatim, with no integrity check at run time.
|
|
101
|
+
* - `~/.bun/install/cache` -- keyed by name@version and hard-linked into
|
|
102
|
+
* `node_modules`; there is no default re-verification step to point at.
|
|
103
|
+
* - `~/.yarn/cache` -- yarn classic's cache does not live here anyway (it is
|
|
104
|
+
* under the XDG / `~/Library/Caches` roots that are now excluded).
|
|
105
|
+
* - `~/.cargo/git` -- git checkouts of dependencies carry no checksum file, and a
|
|
106
|
+
* planted `build.rs` runs at the next unsandboxed `cargo build`.
|
|
107
|
+
* - `~/go/pkg/mod` -- `go.sum` is verified when the module zip is *downloaded*,
|
|
108
|
+
* not when the already-extracted tree is compiled.
|
|
109
|
+
* - `~/.gradle/caches` and `~/.m2/repository` -- jars and compiled build scripts
|
|
110
|
+
* executed by the next unsandboxed `gradle` / `mvn`; dependency verification is
|
|
111
|
+
* opt-in in Gradle and warn-only by default in Maven.
|
|
112
|
+
*
|
|
113
|
+
* Nothing here is a parent of user documents, credentials or shell config, and
|
|
114
|
+
* `~` itself, `~/.config`, `~/.local` and `~/.ssh` remain absent -- see
|
|
115
|
+
* `excludedWriteRootReason`, which now enforces that rather than trusting this
|
|
116
|
+
* list to be the only way in. The long tail is handled by `extraWritePaths` and
|
|
117
|
+
* (Phase 45) the rerun-unsandboxed escalation prompt, not by growing this list.
|
|
118
|
+
*/
|
|
119
|
+
function defaultCacheRoots(home) {
|
|
120
|
+
return [
|
|
121
|
+
join(home, ".npm", "_cacache"),
|
|
122
|
+
join(home, ".npm", "_logs"),
|
|
123
|
+
join(home, ".pnpm-store"),
|
|
124
|
+
join(home, ".yarn", "berry", "cache"),
|
|
125
|
+
join(home, ".cargo", "registry"),
|
|
126
|
+
];
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Directories that alias the whole filesystem under another spelling, so that
|
|
130
|
+
* granting one is granting `/`. macOS mounts the data volume at
|
|
131
|
+
* `/System/Volumes/Data` and firmlinks it into `/`, and `realpath` keeps both
|
|
132
|
+
* spellings, so a string comparison against `/` does not see it.
|
|
133
|
+
*/
|
|
134
|
+
const SYSTEM_VOLUME_ROOTS = {
|
|
135
|
+
darwin: ["/System/Volumes/Data"],
|
|
136
|
+
};
|
|
137
|
+
/** Device+inode identity, so firmlinks and bind mounts cannot spell their way past a string check. */
|
|
138
|
+
function isSameDirectory(a, b) {
|
|
139
|
+
try {
|
|
140
|
+
const left = statSync(a);
|
|
141
|
+
const right = statSync(b);
|
|
142
|
+
return left.dev === right.dev && left.ino === right.ino;
|
|
143
|
+
}
|
|
144
|
+
catch {
|
|
145
|
+
// A path that cannot be stat'ed is not the home directory under another name.
|
|
146
|
+
return false;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
/** `path` and every directory above it, ending at the filesystem root. */
|
|
150
|
+
function selfAndAncestors(path) {
|
|
151
|
+
const out = [];
|
|
152
|
+
let cursor = path;
|
|
153
|
+
for (;;) {
|
|
154
|
+
out.push(cursor);
|
|
155
|
+
const parent = dirname(cursor);
|
|
156
|
+
if (parent === cursor)
|
|
157
|
+
return out;
|
|
158
|
+
cursor = parent;
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Why `path` must not enter the write allowlist, or `null` when it may.
|
|
163
|
+
*
|
|
164
|
+
* `path` must already be real-path resolved. The reason is a sentence fragment
|
|
165
|
+
* that reads after "refusing ...: <reason>".
|
|
166
|
+
*/
|
|
167
|
+
export function excludedWriteRootReason(path, home, platform) {
|
|
168
|
+
if (path === "/")
|
|
169
|
+
return "it is the filesystem root, so the allowlist would not be an allowlist";
|
|
170
|
+
for (const root of SYSTEM_VOLUME_ROOTS[platform] ?? []) {
|
|
171
|
+
if (isContainedIn(root, path)) {
|
|
172
|
+
return `it is ${JSON.stringify(root)} or an ancestor of it, which aliases the entire filesystem`;
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
if (home === undefined || home === "")
|
|
176
|
+
return null;
|
|
177
|
+
if (path === home)
|
|
178
|
+
return "it is the home directory, which would make every dotfile, key and credential writable";
|
|
179
|
+
if (isContainedIn(home, path)) {
|
|
180
|
+
return `it contains the home directory ${JSON.stringify(home)}, which would make every dotfile, key and credential writable`;
|
|
181
|
+
}
|
|
182
|
+
for (const ancestor of selfAndAncestors(home)) {
|
|
183
|
+
if (isSameDirectory(path, ancestor)) {
|
|
184
|
+
return ancestor === home
|
|
185
|
+
? `it is the home directory ${JSON.stringify(home)} reached by another spelling`
|
|
186
|
+
: `it is ${JSON.stringify(ancestor)} reached by another spelling, and that contains the home directory`;
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
return null;
|
|
190
|
+
}
|
|
191
|
+
function rejectionFor(result) {
|
|
192
|
+
return { input: result.input, reason: result.reason };
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* Deduplicates, drops entries already covered by another entry, and sorts.
|
|
196
|
+
*
|
|
197
|
+
* Sorting ascending puts every ancestor before its descendants (an ancestor is a
|
|
198
|
+
* proper string prefix), so a single forward pass is enough to collapse nesting.
|
|
199
|
+
*/
|
|
200
|
+
function normalizeWriteSet(paths) {
|
|
201
|
+
const unique = [...new Set(paths)].sort();
|
|
202
|
+
const minimal = [];
|
|
203
|
+
for (const path of unique) {
|
|
204
|
+
if (minimal.some((existing) => isContainedIn(path, existing)))
|
|
205
|
+
continue;
|
|
206
|
+
minimal.push(path);
|
|
207
|
+
}
|
|
208
|
+
return minimal;
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* Builds a v1 policy from `input`, real-path resolving every path first.
|
|
212
|
+
*
|
|
213
|
+
* Throws `SandboxPolicyError` when an agent-supplied path cannot be resolved or
|
|
214
|
+
* is an excluded root; drops unresolvable or excluded `extraWritePaths` into
|
|
215
|
+
* `rejected`.
|
|
216
|
+
*/
|
|
217
|
+
export function resolveSandboxPolicy(input) {
|
|
218
|
+
const platform = input.platform ?? process.platform;
|
|
219
|
+
// Resolved so the comparison happens between real paths; an unresolvable home
|
|
220
|
+
// still participates as a plain string rather than disabling the exclusion.
|
|
221
|
+
const configuredHome = input.homeDir ?? homedir();
|
|
222
|
+
const resolvedHome = configuredHome ? resolveRealPath(configuredHome, { base: "/" }) : undefined;
|
|
223
|
+
const home = resolvedHome?.ok ? resolvedHome.path : configuredHome || undefined;
|
|
224
|
+
/** Agent-supplied path: unresolvable or excluded is fatal, never silent. */
|
|
225
|
+
const requireAllowedRoot = (label, entry, base) => {
|
|
226
|
+
const result = resolveRealPath(entry, { base });
|
|
227
|
+
if (!result.ok) {
|
|
228
|
+
throw new SandboxPolicyError(`cannot build a sandbox policy: ${label} ${result.reason}`);
|
|
229
|
+
}
|
|
230
|
+
const excluded = excludedWriteRootReason(result.path, home, platform);
|
|
231
|
+
if (excluded) {
|
|
232
|
+
throw new SandboxPolicyError(`cannot build a sandbox policy: refusing to put ${label} ${JSON.stringify(result.path)} in the write allowlist because ${excluded}. Run from a project directory, or grant the specific subtrees you need with extraWritePaths.`);
|
|
233
|
+
}
|
|
234
|
+
return result.path;
|
|
235
|
+
};
|
|
236
|
+
const cwd = requireAllowedRoot("the project cwd", input.cwd, process.cwd());
|
|
237
|
+
const rejected = [];
|
|
238
|
+
const writePaths = [cwd];
|
|
239
|
+
writePaths.push(requireAllowedRoot("the OS temp dir", input.tmpDir ?? tmpdir(), cwd));
|
|
240
|
+
if (input.sessionScratchDir !== undefined) {
|
|
241
|
+
writePaths.push(requireAllowedRoot("the session scratch dir", input.sessionScratchDir, cwd));
|
|
242
|
+
}
|
|
243
|
+
const configured = [...(input.extraWritePaths ?? [])];
|
|
244
|
+
if (input.includeDefaultCacheRoots ?? true) {
|
|
245
|
+
// No home dir means no cache roots -- there is nothing to expand them against,
|
|
246
|
+
// and the fail-closed answer is a narrower policy, not a guessed one.
|
|
247
|
+
if (home)
|
|
248
|
+
configured.push(...defaultCacheRoots(home));
|
|
249
|
+
}
|
|
250
|
+
for (const entry of configured) {
|
|
251
|
+
const result = resolveRealPath(entry, { base: cwd });
|
|
252
|
+
if (!result.ok) {
|
|
253
|
+
rejected.push(rejectionFor(result));
|
|
254
|
+
continue;
|
|
255
|
+
}
|
|
256
|
+
const excluded = excludedWriteRootReason(result.path, home, platform);
|
|
257
|
+
if (excluded) {
|
|
258
|
+
// Configured input: narrow the policy and say so. Silently accepting this
|
|
259
|
+
// is what made the exclusions above decorative.
|
|
260
|
+
rejected.push({
|
|
261
|
+
input: entry,
|
|
262
|
+
reason: `refusing to add ${JSON.stringify(result.path)} to the write allowlist because ${excluded}`,
|
|
263
|
+
});
|
|
264
|
+
continue;
|
|
265
|
+
}
|
|
266
|
+
writePaths.push(result.path);
|
|
267
|
+
}
|
|
268
|
+
const policy = Object.freeze({
|
|
269
|
+
version: SANDBOX_POLICY_VERSION,
|
|
270
|
+
writePaths: Object.freeze(normalizeWriteSet(writePaths)),
|
|
271
|
+
read: "allow-all",
|
|
272
|
+
network: input.network ?? "on",
|
|
273
|
+
allowPrivilegeEscalation: false,
|
|
274
|
+
});
|
|
275
|
+
return { policy, rejected };
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Whether `policy` permits writing to `candidate`.
|
|
279
|
+
*
|
|
280
|
+
* Resolves `candidate` to a real path first -- a lexical `startsWith` against
|
|
281
|
+
* `writePaths` is exactly the bug this exists to prevent, since a symlink or a
|
|
282
|
+
* `..` hop makes an in-project-looking string name a file outside the project.
|
|
283
|
+
* Use this anywhere an in-process pre-check is needed; the kernel backend
|
|
284
|
+
* remains the enforcement boundary, this mirrors it.
|
|
285
|
+
*
|
|
286
|
+
* `candidate` must be absolute unless a `base` is given. Anything unresolvable
|
|
287
|
+
* answers `false` -- an undecidable path is not a writable one.
|
|
288
|
+
*/
|
|
289
|
+
export function isPathWritable(policy, candidate, options) {
|
|
290
|
+
if (options?.base === undefined && !isAbsolute(candidate))
|
|
291
|
+
return false;
|
|
292
|
+
const result = resolveRealPath(candidate, { base: options?.base ?? candidate });
|
|
293
|
+
if (!result.ok)
|
|
294
|
+
return false;
|
|
295
|
+
return policy.writePaths.some((root) => isContainedIn(result.path, root));
|
|
296
|
+
}
|
|
297
|
+
//# sourceMappingURL=policy.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `SandboxPolicy` v1 (R44-SBX.2) and its resolution (R44-SBX.3).\n *\n * The policy is a **plain declarative value**: a resolved write allowlist, a\n * read mode, a network toggle, and a privilege-escalation invariant. Backends\n * translate it into an SBPL profile / a Landlock ruleset; they do not extend it.\n * Keeping it plain is what makes it reviewable, serialisable, diffable and\n * testable independently of any platform.\n *\n * v1 shape, deliberately small (see\n * `.planning/specs/2026-07-12-bash-sandbox-confinement.md`):\n *\n * - **Write allowlist** -- project cwd, session scratch dir, OS temp,\n * `extraWritePaths` from settings, plus a curated set of cache roots that dev\n * toolchains write to outside the project. Everything else is read-only.\n * - **Read** -- allow-all. Dev workflows read toolchains, caches and dotfiles\n * constantly; a read-deny list is a v2 concern and must not block v1.\n * - **Network** -- one on/off toggle, default **on** (`npm install`, `git fetch`).\n * - **Privilege escalation** -- not representable. `allowPrivilegeEscalation` is\n * the literal `false`, not a boolean, so no caller can widen it and every\n * backend must render a profile in which `sudo` cannot work by construction.\n *\n * ## Resolution rules\n *\n * Every path is real-path resolved *before* it lands in the policy (see\n * `real-path.ts` for why). The two classes of input are treated differently on\n * failure, and the difference is deliberate:\n *\n * - **Agent-supplied paths** (`cwd`, `sessionScratchDir`, `tmpDir`) that cannot\n * be resolved throw `SandboxPolicyError`. A session whose own working\n * directory does not resolve is broken; backends catch this and report\n * `unavailable`, which is the fail-closed outcome.\n * - **User-configured paths** (`extraWritePaths`) that cannot be resolved are\n * dropped and reported in `rejected`. Dropping narrows the writable set, so it\n * is safe; it is never silent, so it is debuggable.\n *\n * ## Excluded roots: the exclusions apply to *every* entry, cwd included\n *\n * The curated cache roots below deliberately exclude `~` itself. That exclusion\n * used to be trivially defeated: `cwd` was pushed into the allowlist with no\n * check at all, so running the agent from `$HOME` (or `/Users`, or macOS's\n * `/System/Volumes/Data`) produced a policy whose allowlist *was* the home\n * directory -- silently, with no `rejected` entry, and reported `available`. A\n * sandbox whose allowlist is `$HOME` confines nothing, and the user had no way\n * to know.\n *\n * So `excludedWriteRootReason` is applied uniformly, and the two input classes\n * keep their documented failure modes: an excluded **agent-supplied** path\n * throws, an excluded **configured** path lands in `rejected` and is surfaced.\n * The check is not purely lexical -- `/System/Volumes/Data/Users/alice` is\n * `realpath`-stable on macOS yet is the same directory as `/Users/alice`, so\n * candidates are also compared to the home directory and its ancestors by\n * device+inode identity.\n */\n\nimport { statSync } from \"node:fs\";\nimport { homedir, tmpdir } from \"node:os\";\nimport { dirname, isAbsolute, join } from \"node:path\";\nimport { isContainedIn, type RealPathResolution, resolveRealPath } from \"./real-path.ts\";\n\nexport const SANDBOX_POLICY_VERSION = 1;\n\nexport type SandboxNetworkMode = \"on\" | \"off\";\n\n/** Resolved, declarative sandbox policy. Frozen: backends read it, never edit it. */\nexport interface SandboxPolicy {\n\treadonly version: typeof SANDBOX_POLICY_VERSION;\n\t/**\n\t * Absolute, real-path resolved, deduplicated, minimal (no entry nested under\n\t * another) and sorted. The sort makes generated profiles byte-stable, which\n\t * matters for profile caching and for diffing what a session was allowed to do.\n\t */\n\treadonly writePaths: readonly string[];\n\t/** v1 is read allow-all. A union so v2 can add modes without changing the field. */\n\treadonly read: \"allow-all\";\n\treadonly network: SandboxNetworkMode;\n\t/**\n\t * Always `false`, and typed as the literal so it cannot be set otherwise.\n\t * Backends must render a profile where privilege escalation is impossible,\n\t * and the R44-SBX.4 self-test probes it before any backend reports\n\t * `available` (see `self-test.ts`).\n\t */\n\treadonly allowPrivilegeEscalation: false;\n}\n\nexport interface SandboxPolicyInput {\n\t/** Project working directory. Must exist, resolve, and not be an excluded root. */\n\tcwd: string;\n\t/** The session's scratch directory, when it has one. */\n\tsessionScratchDir?: string;\n\t/** OS temp dir. Defaults to `os.tmpdir()`; overridable for tests. */\n\ttmpDir?: string;\n\t/** Additional writable roots from settings / `permissions.yml`. */\n\textraWritePaths?: readonly string[];\n\t/** Include the curated cache roots below. Defaults to `true`. */\n\tincludeDefaultCacheRoots?: boolean;\n\t/** Home directory used to expand cache roots and to compute exclusions. Defaults to `os.homedir()`. */\n\thomeDir?: string;\n\t/** Defaults to `\"on\"`. */\n\tnetwork?: SandboxNetworkMode;\n\t/** Platform the exclusion list is curated for. Defaults to `process.platform`. */\n\tplatform?: NodeJS.Platform;\n}\n\nexport interface RejectedWritePath {\n\t/** The entry exactly as configured, so the user can find it in their settings. */\n\treadonly input: string;\n\treadonly reason: string;\n}\n\nexport interface SandboxPolicyResolution {\n\treadonly policy: SandboxPolicy;\n\t/**\n\t * Configured write paths that were dropped. Never empty-but-ignored: surfacing\n\t * these is what keeps \"we narrowed your policy\" from being a silent behaviour.\n\t */\n\treadonly rejected: readonly RejectedWritePath[];\n}\n\n/** Thrown when an agent-supplied policy path cannot be resolved or is an excluded root (see module doc). */\nexport class SandboxPolicyError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"SandboxPolicyError\";\n\t}\n}\n\n/**\n * Cache roots dev toolchains write to outside the project.\n *\n * The bar an entry has to clear is **not** \"regenerable\". Every package cache is\n * regenerable, and every package cache also holds code that a later,\n * *unsandboxed* `npm install` / `cargo build` / `npx` links into a tree and\n * runs. Granting one of those is a persistence route straight out of the\n * sandbox, so the bar is:\n *\n * > tampering with an entry must be **detected**, or the entry must be\n * > unreachable by a later lookup, by a mechanism that is on **by default**.\n *\n * What that leaves, and why:\n *\n * | root | why it stays |\n * |--------------------------|------------------------------------------------------------------------------------|\n * | `~/.npm/_cacache` | content-addressed; npm verifies the SRI hash from the lockfile on read, and a mismatch is a cache miss, so a planted blob is unreachable |\n * | `~/.npm/_logs` | plain-text run logs, no code, and npm writes them on every command |\n * | `~/.pnpm-store` | content-addressable store keyed by file hash; `verify-store-integrity` is on by default |\n * | `~/.yarn/berry/cache` | zips checksummed against `yarn.lock`; `checksumBehavior` defaults to `throw` |\n * | `~/.cargo/registry` | `.cargo-checksum.json` is verified on use; a modified crate source is a hard error |\n *\n * Removed in the Phase 44 review, and why each one is a persistence route rather\n * than a cache:\n *\n * - `~/.cache` and `$XDG_CACHE_HOME` -- an unowned catch-all. Playwright browser\n * binaries, pre-commit hook virtualenvs and toolchains installed by `uv` /\n * bazelisk live under it and are executed directly by the next unsandboxed run.\n * - `~/Library/Caches` (macOS) -- same, and worse: Sparkle-style auto-updaters\n * stage the installer they will later launch under `~/Library/Caches/<bundle-id>/`,\n * and Homebrew caches downloaded bottles and `.pkg` installers there.\n * - `~/.npm` as a whole -- narrowed to the two subtrees above because\n * `~/.npm/_npx` holds fully installed package trees that `npx` executes\n * verbatim, with no integrity check at run time.\n * - `~/.bun/install/cache` -- keyed by name@version and hard-linked into\n * `node_modules`; there is no default re-verification step to point at.\n * - `~/.yarn/cache` -- yarn classic's cache does not live here anyway (it is\n * under the XDG / `~/Library/Caches` roots that are now excluded).\n * - `~/.cargo/git` -- git checkouts of dependencies carry no checksum file, and a\n * planted `build.rs` runs at the next unsandboxed `cargo build`.\n * - `~/go/pkg/mod` -- `go.sum` is verified when the module zip is *downloaded*,\n * not when the already-extracted tree is compiled.\n * - `~/.gradle/caches` and `~/.m2/repository` -- jars and compiled build scripts\n * executed by the next unsandboxed `gradle` / `mvn`; dependency verification is\n * opt-in in Gradle and warn-only by default in Maven.\n *\n * Nothing here is a parent of user documents, credentials or shell config, and\n * `~` itself, `~/.config`, `~/.local` and `~/.ssh` remain absent -- see\n * `excludedWriteRootReason`, which now enforces that rather than trusting this\n * list to be the only way in. The long tail is handled by `extraWritePaths` and\n * (Phase 45) the rerun-unsandboxed escalation prompt, not by growing this list.\n */\nfunction defaultCacheRoots(home: string): string[] {\n\treturn [\n\t\tjoin(home, \".npm\", \"_cacache\"),\n\t\tjoin(home, \".npm\", \"_logs\"),\n\t\tjoin(home, \".pnpm-store\"),\n\t\tjoin(home, \".yarn\", \"berry\", \"cache\"),\n\t\tjoin(home, \".cargo\", \"registry\"),\n\t];\n}\n\n/**\n * Directories that alias the whole filesystem under another spelling, so that\n * granting one is granting `/`. macOS mounts the data volume at\n * `/System/Volumes/Data` and firmlinks it into `/`, and `realpath` keeps both\n * spellings, so a string comparison against `/` does not see it.\n */\nconst SYSTEM_VOLUME_ROOTS: Partial<Record<NodeJS.Platform, readonly string[]>> = {\n\tdarwin: [\"/System/Volumes/Data\"],\n};\n\n/** Device+inode identity, so firmlinks and bind mounts cannot spell their way past a string check. */\nfunction isSameDirectory(a: string, b: string): boolean {\n\ttry {\n\t\tconst left = statSync(a);\n\t\tconst right = statSync(b);\n\t\treturn left.dev === right.dev && left.ino === right.ino;\n\t} catch {\n\t\t// A path that cannot be stat'ed is not the home directory under another name.\n\t\treturn false;\n\t}\n}\n\n/** `path` and every directory above it, ending at the filesystem root. */\nfunction selfAndAncestors(path: string): string[] {\n\tconst out: string[] = [];\n\tlet cursor = path;\n\tfor (;;) {\n\t\tout.push(cursor);\n\t\tconst parent = dirname(cursor);\n\t\tif (parent === cursor) return out;\n\t\tcursor = parent;\n\t}\n}\n\n/**\n * Why `path` must not enter the write allowlist, or `null` when it may.\n *\n * `path` must already be real-path resolved. The reason is a sentence fragment\n * that reads after \"refusing ...: <reason>\".\n */\nexport function excludedWriteRootReason(\n\tpath: string,\n\thome: string | undefined,\n\tplatform: NodeJS.Platform,\n): string | null {\n\tif (path === \"/\") return \"it is the filesystem root, so the allowlist would not be an allowlist\";\n\tfor (const root of SYSTEM_VOLUME_ROOTS[platform] ?? []) {\n\t\tif (isContainedIn(root, path)) {\n\t\t\treturn `it is ${JSON.stringify(root)} or an ancestor of it, which aliases the entire filesystem`;\n\t\t}\n\t}\n\tif (home === undefined || home === \"\") return null;\n\tif (path === home) return \"it is the home directory, which would make every dotfile, key and credential writable\";\n\tif (isContainedIn(home, path)) {\n\t\treturn `it contains the home directory ${JSON.stringify(home)}, which would make every dotfile, key and credential writable`;\n\t}\n\tfor (const ancestor of selfAndAncestors(home)) {\n\t\tif (isSameDirectory(path, ancestor)) {\n\t\t\treturn ancestor === home\n\t\t\t\t? `it is the home directory ${JSON.stringify(home)} reached by another spelling`\n\t\t\t\t: `it is ${JSON.stringify(ancestor)} reached by another spelling, and that contains the home directory`;\n\t\t}\n\t}\n\treturn null;\n}\n\nfunction rejectionFor(result: Extract<RealPathResolution, { ok: false }>): RejectedWritePath {\n\treturn { input: result.input, reason: result.reason };\n}\n\n/**\n * Deduplicates, drops entries already covered by another entry, and sorts.\n *\n * Sorting ascending puts every ancestor before its descendants (an ancestor is a\n * proper string prefix), so a single forward pass is enough to collapse nesting.\n */\nfunction normalizeWriteSet(paths: readonly string[]): string[] {\n\tconst unique = [...new Set(paths)].sort();\n\tconst minimal: string[] = [];\n\tfor (const path of unique) {\n\t\tif (minimal.some((existing) => isContainedIn(path, existing))) continue;\n\t\tminimal.push(path);\n\t}\n\treturn minimal;\n}\n\n/**\n * Builds a v1 policy from `input`, real-path resolving every path first.\n *\n * Throws `SandboxPolicyError` when an agent-supplied path cannot be resolved or\n * is an excluded root; drops unresolvable or excluded `extraWritePaths` into\n * `rejected`.\n */\nexport function resolveSandboxPolicy(input: SandboxPolicyInput): SandboxPolicyResolution {\n\tconst platform = input.platform ?? process.platform;\n\t// Resolved so the comparison happens between real paths; an unresolvable home\n\t// still participates as a plain string rather than disabling the exclusion.\n\tconst configuredHome = input.homeDir ?? homedir();\n\tconst resolvedHome = configuredHome ? resolveRealPath(configuredHome, { base: \"/\" }) : undefined;\n\tconst home = resolvedHome?.ok ? resolvedHome.path : configuredHome || undefined;\n\n\t/** Agent-supplied path: unresolvable or excluded is fatal, never silent. */\n\tconst requireAllowedRoot = (label: string, entry: string, base: string): string => {\n\t\tconst result = resolveRealPath(entry, { base });\n\t\tif (!result.ok) {\n\t\t\tthrow new SandboxPolicyError(`cannot build a sandbox policy: ${label} ${result.reason}`);\n\t\t}\n\t\tconst excluded = excludedWriteRootReason(result.path, home, platform);\n\t\tif (excluded) {\n\t\t\tthrow new SandboxPolicyError(\n\t\t\t\t`cannot build a sandbox policy: refusing to put ${label} ${JSON.stringify(result.path)} in the write allowlist because ${excluded}. Run from a project directory, or grant the specific subtrees you need with extraWritePaths.`,\n\t\t\t);\n\t\t}\n\t\treturn result.path;\n\t};\n\n\tconst cwd = requireAllowedRoot(\"the project cwd\", input.cwd, process.cwd());\n\tconst rejected: RejectedWritePath[] = [];\n\tconst writePaths: string[] = [cwd];\n\n\twritePaths.push(requireAllowedRoot(\"the OS temp dir\", input.tmpDir ?? tmpdir(), cwd));\n\tif (input.sessionScratchDir !== undefined) {\n\t\twritePaths.push(requireAllowedRoot(\"the session scratch dir\", input.sessionScratchDir, cwd));\n\t}\n\n\tconst configured = [...(input.extraWritePaths ?? [])];\n\tif (input.includeDefaultCacheRoots ?? true) {\n\t\t// No home dir means no cache roots -- there is nothing to expand them against,\n\t\t// and the fail-closed answer is a narrower policy, not a guessed one.\n\t\tif (home) configured.push(...defaultCacheRoots(home));\n\t}\n\n\tfor (const entry of configured) {\n\t\tconst result = resolveRealPath(entry, { base: cwd });\n\t\tif (!result.ok) {\n\t\t\trejected.push(rejectionFor(result));\n\t\t\tcontinue;\n\t\t}\n\t\tconst excluded = excludedWriteRootReason(result.path, home, platform);\n\t\tif (excluded) {\n\t\t\t// Configured input: narrow the policy and say so. Silently accepting this\n\t\t\t// is what made the exclusions above decorative.\n\t\t\trejected.push({\n\t\t\t\tinput: entry,\n\t\t\t\treason: `refusing to add ${JSON.stringify(result.path)} to the write allowlist because ${excluded}`,\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\twritePaths.push(result.path);\n\t}\n\n\tconst policy: SandboxPolicy = Object.freeze({\n\t\tversion: SANDBOX_POLICY_VERSION,\n\t\twritePaths: Object.freeze(normalizeWriteSet(writePaths)),\n\t\tread: \"allow-all\",\n\t\tnetwork: input.network ?? \"on\",\n\t\tallowPrivilegeEscalation: false,\n\t});\n\treturn { policy, rejected };\n}\n\n/**\n * Whether `policy` permits writing to `candidate`.\n *\n * Resolves `candidate` to a real path first -- a lexical `startsWith` against\n * `writePaths` is exactly the bug this exists to prevent, since a symlink or a\n * `..` hop makes an in-project-looking string name a file outside the project.\n * Use this anywhere an in-process pre-check is needed; the kernel backend\n * remains the enforcement boundary, this mirrors it.\n *\n * `candidate` must be absolute unless a `base` is given. Anything unresolvable\n * answers `false` -- an undecidable path is not a writable one.\n */\nexport function isPathWritable(policy: SandboxPolicy, candidate: string, options?: { base?: string }): boolean {\n\tif (options?.base === undefined && !isAbsolute(candidate)) return false;\n\tconst result = resolveRealPath(candidate, { base: options?.base ?? candidate });\n\tif (!result.ok) return false;\n\treturn policy.writePaths.some((root) => isContainedIn(result.path, root));\n}\n"]}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Real-path resolution for sandbox policy paths (R44-SBX.3).
|
|
3
|
+
*
|
|
4
|
+
* Every path that reaches a sandbox profile must first become the path the
|
|
5
|
+
* *kernel* sees, not the path a string spells. This is a security property, not
|
|
6
|
+
* tidiness: the write allowlist is the whole policy, so anything that lets one
|
|
7
|
+
* string name two different places lets the allowlist be widened silently.
|
|
8
|
+
*
|
|
9
|
+
* Two such mechanisms exist, and both are handled here:
|
|
10
|
+
*
|
|
11
|
+
* 1. **Symlinks.** A link inside the project pointing outside it (`<project>/link
|
|
12
|
+
* -> /somewhere/else`) makes `<project>/link/x` pass any `startsWith(project)`
|
|
13
|
+
* check while actually writing to `/somewhere/else/x`.
|
|
14
|
+
* 2. **`..` traversal.** `..` is *not* a lexical operation once symlinks are in
|
|
15
|
+
* play: `<project>/link/../x` is `/somewhere/x`, not `<project>/x`. Node's
|
|
16
|
+
* `path.join`/`path.resolve` collapse `..` lexically and would therefore
|
|
17
|
+
* produce exactly the wrong answer, so this module deliberately never uses
|
|
18
|
+
* them to build the path it resolves.
|
|
19
|
+
*
|
|
20
|
+
* ## Why `..` is walked here instead of being handed to `realpath(3)`
|
|
21
|
+
*
|
|
22
|
+
* The obvious implementation -- hand the raw spelling to `realpathSync.native`
|
|
23
|
+
* and let the OS walk it -- is **not portable, and the runtime it is wrong on is
|
|
24
|
+
* the one that ships**. Measured, same machine, same fixture
|
|
25
|
+
* (`<project>/link -> <outside>/sub`):
|
|
26
|
+
*
|
|
27
|
+
* | call | node 26 | bun 1.4 |
|
|
28
|
+
* |-----------------------------------------------|---------|------------|
|
|
29
|
+
* | `realpathSync(<project>/link/..)` | `<project>` (lexical, wrong) | `<project>` (lexical, wrong) |
|
|
30
|
+
* | `realpathSync.native(<project>/link/..)` | `<outside>` (POSIX, right) | `<project>` (lexical, **wrong**) |
|
|
31
|
+
*
|
|
32
|
+
* Bun's `realpathSync.native` collapses `..` lexically before resolving, exactly
|
|
33
|
+
* like the JS variant. The released `draht` binaries are built with `bun build
|
|
34
|
+
* --compile` (see `packages/coding-agent` `build:binary`), so delegating `..` to
|
|
35
|
+
* the OS would have meant `isPathWritable()` answering **true** for
|
|
36
|
+
* `<project>/link/../evil.txt` in every shipped binary -- a path the kernel
|
|
37
|
+
* writes to `<outside>/evil.txt`, outside the allowlist. That is R44-SBX.3
|
|
38
|
+
* defeated by the very call that was supposed to enforce it.
|
|
39
|
+
*
|
|
40
|
+
* So the guarantee this module actually makes, and the one the walk below
|
|
41
|
+
* implements, is:
|
|
42
|
+
*
|
|
43
|
+
* > `..` is never passed to the platform's `realpath`. The path is walked one
|
|
44
|
+
* > segment at a time by the shared `resolveRealSegment` primitive
|
|
45
|
+
* > (`src/utils/canonical-path.ts`) against an already fully-resolved prefix (a
|
|
46
|
+
* > single name, no `..`, so both runtimes agree and symlink chasing, `ELOOP` and
|
|
47
|
+
* > permission checks stay in the kernel); each `..` is applied to that resolved
|
|
48
|
+
* > prefix, which is where POSIX says it applies.
|
|
49
|
+
*
|
|
50
|
+
* That primitive also carries bun's second divergence — a backslash in a name is
|
|
51
|
+
* rewritten to `/` before the syscall, so `<dir>/a\b` resolves to a *different* real
|
|
52
|
+
* directory, one the kernel will never traverse for that spelling.
|
|
53
|
+
*
|
|
54
|
+
* `test/sandbox-real-path-runtime.test.ts` executes the same assertions under
|
|
55
|
+
* **both** node and bun and fails if the two disagree, so this claim is checked
|
|
56
|
+
* against the runtime that ships rather than only the one the tests run in.
|
|
57
|
+
*
|
|
58
|
+
* ## Paths that do not exist yet
|
|
59
|
+
*
|
|
60
|
+
* A configured write path may legitimately not exist yet (a build output dir, a
|
|
61
|
+
* cache root on a fresh machine). `realpath(3)` fails on those, and guessing is
|
|
62
|
+
* how allowlists get widened by accident. The rule here:
|
|
63
|
+
*
|
|
64
|
+
* - Resolve every segment that *does* exist (so no symlink anywhere in the
|
|
65
|
+
* existing prefix can widen anything).
|
|
66
|
+
* - Re-attach the remaining segments literally, since they name nothing yet.
|
|
67
|
+
* - If any remaining segment is `..`, **refuse**: `..` below a non-existent
|
|
68
|
+
* directory has no determinable target (it depends on what that directory
|
|
69
|
+
* turns out to be when created), and inventing one is precisely the silent
|
|
70
|
+
* widening this requirement forbids.
|
|
71
|
+
*
|
|
72
|
+
* The resolved leaf is only an *ancestor* guarantee -- someone could later create
|
|
73
|
+
* that leaf as a symlink pointing elsewhere. That is why `isPathWritable`
|
|
74
|
+
* (see `policy.ts`) re-resolves the candidate at check time rather than trusting
|
|
75
|
+
* the stored string, and why the kernel backends, not this module, are the
|
|
76
|
+
* enforcement boundary.
|
|
77
|
+
*/
|
|
78
|
+
export interface ResolveRealPathOptions {
|
|
79
|
+
/** Absolute directory that relative inputs resolve against (normally the project cwd). */
|
|
80
|
+
base: string;
|
|
81
|
+
}
|
|
82
|
+
export type RealPathResolution = {
|
|
83
|
+
readonly ok: true;
|
|
84
|
+
/** The path as given. */
|
|
85
|
+
readonly input: string;
|
|
86
|
+
/** Absolute, fully symlink-resolved path. Contains no `.` or `..` segments. */
|
|
87
|
+
readonly path: string;
|
|
88
|
+
/** True when the whole path already existed; false when only its ancestor did. */
|
|
89
|
+
readonly existed: boolean;
|
|
90
|
+
} | {
|
|
91
|
+
readonly ok: false;
|
|
92
|
+
readonly input: string;
|
|
93
|
+
/** Human-readable explanation, safe to surface in diagnostics. */
|
|
94
|
+
readonly reason: string;
|
|
95
|
+
};
|
|
96
|
+
/**
|
|
97
|
+
* Resolves `input` to a real, absolute path. Never throws -- failures come back
|
|
98
|
+
* as `{ ok: false, reason }` so callers can drop the entry (narrowing the
|
|
99
|
+
* writable set) instead of falling back to an unresolved spelling.
|
|
100
|
+
*/
|
|
101
|
+
export declare function resolveRealPath(input: string, options: ResolveRealPathOptions): RealPathResolution;
|
|
102
|
+
/**
|
|
103
|
+
* True when `candidate` is `root` itself or lies underneath it. Both arguments
|
|
104
|
+
* must already be real paths -- this is a pure string comparison and makes no
|
|
105
|
+
* claim about symlinks; resolve first.
|
|
106
|
+
*
|
|
107
|
+
* Comparison is exact-case. On case-sensitive filesystems that is correct; on a
|
|
108
|
+
* case-insensitive one (default APFS/HFS+) it is stricter than the kernel, which
|
|
109
|
+
* can only produce a false "not contained", never a false "contained".
|
|
110
|
+
*/
|
|
111
|
+
export declare function isContainedIn(candidate: string, root: string): boolean;
|
|
112
|
+
//# sourceMappingURL=real-path.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"real-path.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/real-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAKH,MAAM,WAAW,sBAAsB;IACtC,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CACzB,GACD;IACA,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACvB,CAAC;AAQL;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,kBAAkB,CA0DlG;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAItE"}
|