@buildanagent/harness 0.1.0-alpha.28 → 0.1.0-alpha.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +152 -5
- package/dist/context/file-spill.d.ts +11 -1
- package/dist/context/file-spill.js +23 -8
- package/dist/context/file-spill.js.map +1 -1
- package/dist/context/spill.d.ts +5 -1
- package/dist/context/spill.js +6 -2
- package/dist/context/spill.js.map +1 -1
- package/dist/credentials/addresses.d.ts +11 -0
- package/dist/credentials/addresses.js +41 -2
- package/dist/credentials/addresses.js.map +1 -1
- package/dist/credentials/allowlist.d.ts +22 -2
- package/dist/credentials/allowlist.js +74 -17
- package/dist/credentials/allowlist.js.map +1 -1
- package/dist/credentials/egress-policy.d.ts +69 -0
- package/dist/credentials/egress-policy.js +170 -0
- package/dist/credentials/egress-policy.js.map +1 -0
- package/dist/credentials/egress-proxy.d.ts +13 -1
- package/dist/credentials/egress-proxy.js +179 -11
- package/dist/credentials/egress-proxy.js.map +1 -1
- package/dist/credentials/git-route.d.ts +68 -0
- package/dist/credentials/git-route.js +288 -0
- package/dist/credentials/git-route.js.map +1 -0
- package/dist/credentials/index.d.ts +5 -1
- package/dist/credentials/index.js +5 -1
- package/dist/credentials/index.js.map +1 -1
- package/dist/credentials/scrub.d.ts +7 -0
- package/dist/credentials/scrub.js +22 -0
- package/dist/credentials/scrub.js.map +1 -1
- package/dist/errors.d.ts +14 -7
- package/dist/errors.js +13 -6
- package/dist/errors.js.map +1 -1
- package/dist/sandbox/base.d.ts +11 -1
- package/dist/sandbox/base.js +14 -0
- package/dist/sandbox/base.js.map +1 -1
- package/dist/sandbox/docker/index.d.ts +8 -2
- package/dist/sandbox/docker/index.js +63 -14
- package/dist/sandbox/docker/index.js.map +1 -1
- package/dist/sandbox/errors.d.ts +30 -2
- package/dist/sandbox/errors.js +36 -1
- package/dist/sandbox/errors.js.map +1 -1
- package/dist/sandbox/escalation-table.d.ts +38 -0
- package/dist/sandbox/escalation-table.js +95 -0
- package/dist/sandbox/escalation-table.js.map +1 -0
- package/dist/sandbox/escalation.d.ts +191 -0
- package/dist/sandbox/escalation.js +370 -0
- package/dist/sandbox/escalation.js.map +1 -0
- package/dist/sandbox/host-files.d.ts +2 -0
- package/dist/sandbox/host-files.js +10 -0
- package/dist/sandbox/host-files.js.map +1 -1
- package/dist/sandbox/index.d.ts +9 -4
- package/dist/sandbox/index.js +8 -3
- package/dist/sandbox/index.js.map +1 -1
- package/dist/sandbox/policy.d.ts +49 -0
- package/dist/sandbox/policy.js +149 -0
- package/dist/sandbox/policy.js.map +1 -0
- package/dist/sandbox/process.js +1 -1
- package/dist/sandbox/process.js.map +1 -1
- package/dist/sandbox/srt/index.d.ts +5 -2
- package/dist/sandbox/srt/index.js +27 -8
- package/dist/sandbox/srt/index.js.map +1 -1
- package/dist/sandbox/srt/settings.d.ts +17 -5
- package/dist/sandbox/srt/settings.js +53 -0
- package/dist/sandbox/srt/settings.js.map +1 -1
- package/dist/sandbox/types.d.ts +41 -4
- package/dist/sandbox/types.js.map +1 -1
- package/dist/sandbox/widen.d.ts +10 -0
- package/dist/sandbox/widen.js +150 -0
- package/dist/sandbox/widen.js.map +1 -0
- package/dist/session/approvals.d.ts +30 -1
- package/dist/session/approvals.js +12 -4
- package/dist/session/approvals.js.map +1 -1
- package/dist/session/code-call.d.ts +15 -1
- package/dist/session/code-call.js +2 -1
- package/dist/session/code-call.js.map +1 -1
- package/dist/session/escalation-log.d.ts +65 -0
- package/dist/session/escalation-log.js +84 -0
- package/dist/session/escalation-log.js.map +1 -0
- package/dist/session/rebuild.js +12 -3
- package/dist/session/rebuild.js.map +1 -1
- package/dist/testing/fake-sandbox.d.ts +21 -3
- package/dist/testing/fake-sandbox.js +157 -8
- package/dist/testing/fake-sandbox.js.map +1 -1
- package/dist/testing/sandbox-conformance.js +108 -1
- package/dist/testing/sandbox-conformance.js.map +1 -1
- package/dist/tools/builtins/bash.d.ts +9 -0
- package/dist/tools/builtins/bash.js +75 -0
- package/dist/tools/builtins/bash.js.map +1 -0
- package/dist/tools/builtins/builtins.d.ts +38 -0
- package/dist/tools/builtins/builtins.js +48 -0
- package/dist/tools/builtins/builtins.js.map +1 -0
- package/dist/tools/builtins/descriptions.d.ts +69 -0
- package/dist/tools/builtins/descriptions.js +94 -0
- package/dist/tools/builtins/descriptions.js.map +1 -0
- package/dist/tools/builtins/fetch.d.ts +12 -0
- package/dist/tools/builtins/fetch.js +157 -0
- package/dist/tools/builtins/fetch.js.map +1 -0
- package/dist/tools/builtins/files.d.ts +27 -0
- package/dist/tools/builtins/files.js +274 -0
- package/dist/tools/builtins/files.js.map +1 -0
- package/dist/tools/builtins/paths.d.ts +30 -0
- package/dist/tools/builtins/paths.js +62 -0
- package/dist/tools/builtins/paths.js.map +1 -0
- package/dist/tools/builtins/results.d.ts +15 -0
- package/dist/tools/builtins/results.js +31 -0
- package/dist/tools/builtins/results.js.map +1 -0
- package/dist/tools/builtins/search.d.ts +18 -0
- package/dist/tools/builtins/search.js +217 -0
- package/dist/tools/builtins/search.js.map +1 -0
- package/dist/tools/index.d.ts +6 -2
- package/dist/tools/index.js +5 -2
- package/dist/tools/index.js.map +1 -1
- package/llms.txt +52 -0
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -60,12 +60,53 @@ const result = await sandbox.exec(["pnpm", "test"], { env: spawnEnv([]), signal:
|
|
|
60
60
|
console.log("denied" in result ? result.denied.reason : result.exitCode);
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
`exec` takes an executable and its arguments, with no shell, and resolves with the exit code and output. A failing command is a result, not an error, and a command the policy refuses resolves with `{ denied }`. A command that runs past `timeoutMs` stops with exit code 124, and one the system can't find gives 127. A command that a signal killed gives 128 plus the signal's number, with `signal` naming it. Output past `maxOutputBytes` (8 MiB for each stream by default) is dropped, and the result says `truncated: true`.
|
|
63
|
+
`exec` takes an executable and its arguments, with no shell, and resolves with the exit code and output. A failing command is a result, not an error, and a command the policy refuses resolves with `{ denied }`. A command that runs past `timeoutMs` stops with exit code 124 and `timedOut: true`, so a command that exits with 124 itself is told apart, and one the system can't find gives 127. A command that a signal killed gives 128 plus the signal's number, with `signal` naming it. Output past `maxOutputBytes` (8 MiB for each stream by default) is dropped, and the result says `truncated: true`.
|
|
64
64
|
|
|
65
65
|
The `none` backend starts each command in its own process group. A timeout, an abort or `dispose()` therefore kills the command and everything it started, and `exec` settles even when a background process still holds the output pipes.
|
|
66
66
|
|
|
67
67
|
Bad input is an error, not a result. A working directory that isn't an existing folder, a bad `timeoutMs` or a bad `maxOutputBytes` throws a `HarnessError`. An already aborted signal rejects before the command runs, and reading a missing file rejects with the code `sandbox_not_found`.
|
|
68
68
|
|
|
69
|
+
## A denied command becomes a signed request, and an approved one reruns once
|
|
70
|
+
|
|
71
|
+
`escalation({ approvalPolicy, approvals })` from `./sandbox` decides what happens when the sandbox denies a command. The host owns that decision, and no tool or model can widen the sandbox. A wider policy is built on the host from two things only, the denial the backend reported and a verified answer, and it lasts for one rerun.
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { escalation, spawnEnv } from "@buildanagent/harness/sandbox";
|
|
75
|
+
|
|
76
|
+
const machine = escalation({ approvalPolicy: "on-request", approvals: createApprovals(harness) });
|
|
77
|
+
const where = { client, manifest: { root: "/work/repo" }, env: spawnEnv([]), signal: controller.signal };
|
|
78
|
+
const outcome = await machine.run(session, { ...where, tool: "fetch", input: { url: "https://example.com" }, command: ["curl", "https://example.com"], policy });
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`machine.run(session, run)` runs the command once under `run.policy` and ends one of three ways. Each result carries `result`, a tool result a tool can return to the model. The model reads it only when nothing was written, as under `never`; once a request exists, the rebuilt context leaves it out and the host reads it.
|
|
82
|
+
|
|
83
|
+
- **`ran`.** The backend did not deny the command, and nothing is written.
|
|
84
|
+
- **`denied`.** The backend denied it, and nobody is asked, so nothing is written. That is every denial under `never`, every denial that no `granular` rule lets the host ask about, and every denial that can't be widened: a path that is `/`, relative or holds `..`, a host with a wildcard, a scheme or a path, and a host that an entry of the policy's own `network.deny` closes. An entry closes a host as `srt` matches a denied domain: `*` closes every host, `*.name` every name under `name` but not `name` itself, and any other entry that host alone, with case ignored. An entry's port is ignored, so a host closed on one port is never widened on any, and an IPv6 address is never widened while `deny` names any IPv6 address. An address must be in its canonical form: an IPv4 address as four decimal octets with no leading zero, and an IPv6 address that does not wrap an IPv4 one. A host whose last label is a number counts as an IPv4 address, so `127.1`, `2130706433` and `0x7f.1` can't be widened, and a deny entry closes an IPv4 address it names in any spelling, such as `10.1` for `10.0.0.1`. A host that reaches the machine itself or its link is never widened, whatever `deny` says: `localhost` and the names under it, and the unspecified, loopback and link-local addresses, which hold the cloud metadata address 169.254.169.254. A name that DNS resolves to a closed address can't be seen here, so the backend's own deny list still covers it.
|
|
85
|
+
- **`awaiting_approval`.** Under `on-request`, or `granular` where a rule allows it, `run()` writes an `approval_requested` entry before it returns. The harness's signer signs the request as `createPendingRequest()` does, and the request's tool is `ESCALATION_TOOL` (`sandbox.escalation`), a name no registered tool can have. Its input is the record the approver sees: the tool and its input, the command, the workspace root, the policy and the denial. `widened` is the policy the rerun would get.
|
|
86
|
+
|
|
87
|
+
`run()` writes only when it asks. A tool's `execute` may call it under `never`, and under the other two policies host code calls it between turns, as it calls `invokeTool()`, because a write inside a turn's tool step can race the turn's own writes.
|
|
88
|
+
|
|
89
|
+
`machine.resolve(session, resolution, options)` answers one request. The log holds no backend, workspace, environment or signal, so `options` passes them again:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
import { spawnEnv } from "@buildanagent/harness/sandbox";
|
|
93
|
+
|
|
94
|
+
const rerun = await machine.resolve(session, { requestId, decision: "allow", by: "grace" }, { client, manifest: { root: "/work/repo" }, env: spawnEnv([]), signal: controller.signal });
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
- **The check comes first.** Before anything is written, the answer is checked against the request: the signature under a key in the ring, the bound host context, the call, and the record, which must hash to the signed hash. A forged, re-signed or edited request throws `approval_refused`, writes nothing and runs nothing.
|
|
98
|
+
- **Only a named person or hook approves a rerun.** An allow with no `by`, or whose `by` starts with `classifier:` in any case, throws `approval_refused`, writes nothing and leaves the request waiting. A person's or a hook's allow approves it. `by` is not covered by the request's signature, so set it only after you have authenticated the approver.
|
|
99
|
+
- **The quorum policy decides.** The answer is written, and the approvals' quorum policy decides the answer. A quorum that still waits returns `awaiting_approval`, and a deny, a rejection or an expiry ends `denied` with no rerun.
|
|
100
|
+
- **An abort before the answer is written writes no answer.** `options.signal` is checked when `resolve()` is called and again just before the answer is written, so an abort by then runs nothing and the request still waits. Once the answer is written the approval is spent, and an abort only reaches the rerun, as `Sandbox.exec()` takes a signal.
|
|
101
|
+
- **A deny rule added since the pause wins.** An allow goes through the permission pipeline again, as the tool call the command ran for.
|
|
102
|
+
- **The rerun runs once, no wider than the denial.** It runs in a fresh sandbox under the recorded policy plus exactly the path or host that was denied, and that sandbox is disposed after it. A second denial is the rerun's result: it ends `denied`, and nobody is asked again.
|
|
103
|
+
|
|
104
|
+
Every move follows `ESCALATION_TRANSITIONS`, a table of the states `sandboxed`, `denied`, `requested`, `approved`, `rerun` and `done` and the events between them. A result's `status` and the state `denied` are different things: `status` is how the call ended, and `states` is the path it took. `nextEscalationState()` throws `invalid_escalation` for an edge the table does not list. Only a verified allow leads from `requested` to `approved`, and `rerun` leads only to `done`. Each result's `states` lists the states its call passed through.
|
|
105
|
+
|
|
106
|
+
A rerun runs at most once, even across a crash. It *starts* once the log holds the pipeline's fresh decision after a final allow, the last entry before the rerun runs. To *settle* an escalation is to write the result it lacks. The next `resolve()`, or `run()` that asks, settles each escalation a crash left open: a rerun that started may have run, so it is settled as such and never run again, and an answer whose rerun never started is settled as never run. The result is a `tool_result` with the tool `sandbox.escalation`. The rerun's output, and any sentence that quotes a backend's denial, an error's message or an approver's reason, is marked `untrusted`; only the harness's own fixed sentences, such as a crash's settlement, are marked `trusted`. The model never reads the result, because the rebuilt context leaves out each result whose call id is an escalation's; a result the model's own call got stays, even for a call to a tool it named `sandbox.escalation`. The host gets the command's output from `resolve()`. The log keeps at most 4,096 characters of each of the rerun's output streams, and `resolve()` returns all of it.
|
|
107
|
+
|
|
108
|
+
`approvals.pending()` and `approvals.resolve()` don't see an escalation: `machine.pending(session)` lists the ones that wait. It asks the quorum policy about each with the answers written so far and leaves out one the policy says has expired. Listing writes nothing, so an expired escalation stays in the log until it is answered, and `resolve()` then writes the policy's denial and runs nothing. A `granular` policy takes `granular`, a list of rules of the form `{ kind?, tool?, escalate }`. The first rule that matches the denial's kind and the tool decides, and a denial no rule matches goes back with no request. `escalation()` throws `invalid_escalation` for rules given with another policy, for a `granular` policy with none, and for approvals that `createApprovals()` did not make. A policy that can ask also needs a harness with a signer and a permission pipeline: without the signer it throws `approval_unavailable`, and without the pipeline `invalid_escalation`.
|
|
109
|
+
|
|
69
110
|
## The srt backend confines each command with Anthropic's OS sandbox
|
|
70
111
|
|
|
71
112
|
`srtSandbox()` from `./sandbox/srt` runs each command under `srt`, Anthropic's sandbox runtime. It pins `@anthropic-ai/sandbox-runtime` 0.0.83 under the Apache-2.0 license. The package calls itself a "Beta Research Preview", and says its APIs and configuration formats may evolve (as of November 2026). `provision()` writes the settings file, so `./sandbox/srt` is the one place that knows that format.
|
|
@@ -101,7 +142,7 @@ The policy decides what is mounted, at the same path inside as outside. A write
|
|
|
101
142
|
|
|
102
143
|
The workspace must lie inside a root. The backend never mounts the Docker socket: a root that resolves to `/`, or that holds the daemon's socket (`/var/run/docker.sock`, `/run/docker.sock` or the one `dockerHost` names), is refused.
|
|
103
144
|
|
|
104
|
-
The container has no network, so a command reaches a host only through `proxySocket`: a Unix socket on the host, mounted at `DOCKER_PROXY_SOCKET_PATH` (`/run/harness/proxy.sock`), that the credential proxy listens on. The program in the image has to speak to that socket itself. Without `proxySocket`, no host is reachable, including the ones the policy allows.
|
|
145
|
+
The container has no network, so a command reaches a host only through `proxySocket`: a Unix socket on the host, mounted at `DOCKER_PROXY_SOCKET_PATH` (`/run/harness/proxy.sock`), that the credential proxy listens on. The program in the image has to speak to that socket itself. Without `proxySocket`, no host is reachable, including the ones the policy allows, so `provision()` refuses a policy whose `network.allow` names one.
|
|
105
146
|
|
|
106
147
|
`provision()` starts the `docker` client with a clean environment: a `PATH`, a private empty `HOME`, and `DOCKER_HOST` when the option or the host sets one. It never copies the host's environment. A missing client, a daemon that doesn't answer or an image that isn't on the host throws `SandboxUnavailableError` and runs nothing.
|
|
107
148
|
|
|
@@ -119,6 +160,30 @@ Five limits are worth knowing:
|
|
|
119
160
|
|
|
120
161
|
The same opt-in tests run the conformance suite and the lock-down cases against a real daemon, with a pinned Node image, and fail on a skipped case. Without Docker, the other tests check the flags and the unavailable paths with a fake client.
|
|
121
162
|
|
|
163
|
+
## A backend that claims a stop reads its policy back, and one that can't resume says so
|
|
164
|
+
|
|
165
|
+
A backend that claims a stop reads back the policy it applied, and `provision()` compares it with the request before it returns. `srtSandbox()` rereads its settings file from disk, and `dockerSandbox()` reports the mounts and flags it creates each container with. If any field differs, `provision()` disposes the sandbox and throws `SandboxPolicyMismatchError`, so nothing runs under a policy you didn't ask for. The check treats `readRoots`, `writeRoots`, `network.allow` and `network.deny` as sets, and a narrower policy throws too.
|
|
166
|
+
|
|
167
|
+
One gap remains: a `denyWrite` that names a write root exactly. Docker mounts such a root read-only, but the read-back counts the caller's `denyWrite` as part of the request, so it still reads back as a write root and `provision()` accepts it. Nothing in that root is writable inside the container.
|
|
168
|
+
|
|
169
|
+
The error's code is `sandbox_policy_mismatch`, and its `field` names the first field that differs, such as `network.allow`. The message never holds a path or a host. The code below catches the error and prints that field:
|
|
170
|
+
|
|
171
|
+
```ts
|
|
172
|
+
import { SandboxPolicyMismatchError } from "@buildanagent/harness/sandbox";
|
|
173
|
+
import { srtSandbox } from "@buildanagent/harness/sandbox/srt";
|
|
174
|
+
|
|
175
|
+
const attempt = srtSandbox().provision({ root: "/work/repo" }, policy);
|
|
176
|
+
await attempt.catch((error) => console.log(error instanceof SandboxPolicyMismatchError ? error.field : error));
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
A client that claims a stop but gives its sandbox no read-back, or one whose read-back fails, makes `provision()` throw the same error, with the field `readBack`. `noneSandbox()` claims no stop, so it needs none.
|
|
180
|
+
|
|
181
|
+
`stopsFor(tier, policy)` computes the stops that an applied policy delivers. Only a `microvm` stops a `hostile_process`. A policy that allows `*`, `0.0.0.0/0` or `::/0` loses `exfiltration`, and a root of `/` loses `mistakes`. A client that claims a stop its applied policy doesn't deliver is refused with the field `stops`, and the message names the cause, such as that the policy allows all hosts, so the sandbox cannot stop exfiltration. `srtSandbox()` and `dockerSandbox()` both claim `mistakes` and `exfiltration`, so `provision()` refuses a policy that allows every host on either.
|
|
182
|
+
|
|
183
|
+
A hosted backend can also list `capabilities`: `resume`, `snapshot` and `pause`. Call them through `resumeSandbox(client, id, policy)`, `snapshotSandbox(client, sandbox)` and `pauseSandbox(client, sandbox)`. A resume reads the policy back as `provision()` does and sets the handle's `stops` from it. Unlike `provision()`, a resume that finds a mismatch throws and leaves the sandbox alone, because disposing it would destroy a paused sandbox and its work: the caller decides whether to dispose. A capability the client doesn't list rejects with `SandboxUnsupportedError`, code `sandbox_unsupported`. The `none`, `srt` and Docker backends list none, so a resume, a snapshot or a pause on them is always refused.
|
|
184
|
+
|
|
185
|
+
None of this authenticates a caller. The read-back shows that the sandbox applies the policy you asked for, and the host still decides who may ask.
|
|
186
|
+
|
|
122
187
|
## The egress proxy keeps every credential outside the sandbox
|
|
123
188
|
|
|
124
189
|
`startEgressProxy({ allow, routes, log })` from `./credentials` starts a proxy on `127.0.0.1`, or on a Unix socket you give it (`socketPath`, which is what `dockerSandbox`'s `proxySocket` mounts). Nothing leaves the sandbox except through it. It refuses everything that isn't on its allowlist with a 403, and it writes one log record for each request: the host, the method, the status and the bytes, never a header or a body. Give the sandbox `proxy.url` as `HTTPS_PROXY`. On a Unix socket, `proxy.url` is `unix:<path>`, which is not a proxy URL, and the program inside the container connects to the socket itself.
|
|
@@ -144,6 +209,48 @@ Four limits are worth knowing:
|
|
|
144
209
|
|
|
145
210
|
The package's tests run the proxy against a real HTTPS server on loopback, with a self-signed certificate that only the test trusts and a table in place of DNS.
|
|
146
211
|
|
|
212
|
+
## An egress policy names a credential and never holds one
|
|
213
|
+
|
|
214
|
+
`EgressPolicy` is plain data: an `allow` list of exact host names, and `routes` that each name the credential they inject. `compileEgressPolicy(policy, { secret })` checks it and returns the `allow` and `routes` that `startEgressProxy()` takes. The compiled routes call `secret(name)` for each request, on the host, so a rotated credential is used at once. The code below compiles one git route and starts a proxy with it:
|
|
215
|
+
|
|
216
|
+
```ts
|
|
217
|
+
import { compileEgressPolicy, startEgressProxy } from "@buildanagent/harness/credentials";
|
|
218
|
+
|
|
219
|
+
const route = { kind: "git", route: "git", host: "github.com", repositories: ["acme/app"], pushRefs: ["refs/heads/agent/*"], credential: "GITHUB_TOKEN" } as const;
|
|
220
|
+
const compiled = compileEgressPolicy({ allow: [], routes: [route] }, { secret: async (name) => process.env[name] ?? "" });
|
|
221
|
+
const proxy = await startEgressProxy({ ...compiled, log: audit });
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
The compiler refuses anything that isn't plainly allowed, with the code `invalid_egress_options`, and its message names the place of the entry and never its value:
|
|
225
|
+
|
|
226
|
+
- a field that a route kind doesn't have, such as `secret` or `token`;
|
|
227
|
+
- a string that looks like a credential: a value, or a whitespace-separated token, that starts with `ghp_` or `sk-` and has a long enough body, or a whole 20-character AWS key id. A name that merely contains a prefix, like the repository `sk-labs/app`, is allowed;
|
|
228
|
+
- a credential name that isn't upper case;
|
|
229
|
+
- a wildcard or an address literal in `allow` or in a route's `host`;
|
|
230
|
+
- a git route whose `host` is also in `allow`, or is the host of any other route, because a tunnel or a header route to that host would go around the ref filter. `startEgressProxy()` enforces the same rule on routes it is given directly.
|
|
231
|
+
|
|
232
|
+
The scan for credential-shaped strings is defence in depth. The field allowlist and the upper-case credential name are the real guards, and a token that starts mid-word, like `acme/ghp_…`, or is base64-encoded passes the scan.
|
|
233
|
+
|
|
234
|
+
The policy holds names, the proxy reads each value on the host, and the sandbox sees only a random placeholder, so no credential value enters a sandbox. The policy does not authenticate a caller: any process that knows the placeholder can use the route. `EgressPolicy` is not yet part of `SandboxPolicy`, and `srtSandbox()` keeps its own proxy.
|
|
235
|
+
|
|
236
|
+
## A git route lets a push reach listed branches and nothing else
|
|
237
|
+
|
|
238
|
+
A route of kind `git` carries git over HTTPS for the repositories it lists, and nothing else. The sandbox's remote is `http://x-access-token:<placeholder>@127.0.0.1:<port>/git/acme/app.git`, where `git` is the route's name and the placeholder is `proxy.sentinels.git`. The proxy swaps the placeholder for the credential and sends it to the host in HTTP Basic, with the route's `username`, which is `x-access-token` unless you set one. A request with no credential gets a 401 challenge, so git asks for one.
|
|
239
|
+
|
|
240
|
+
A push is checked before anything is forwarded. The proxy reads the command list at the start of the body and refuses the whole push when one command breaks a rule:
|
|
241
|
+
|
|
242
|
+
- a deletion, a tag, or a ref that no `pushRefs` pattern matches;
|
|
243
|
+
- a push certificate, a body with a `content-encoding` other than `identity`, or a pkt-line that is malformed or not UTF-8;
|
|
244
|
+
- a command list over 64 KiB (`GIT_MAX_COMMAND_BYTES`) or over 64 commands (`GIT_MAX_COMMANDS`).
|
|
245
|
+
|
|
246
|
+
When a push is bigger than git's `http.postBuffer` (1 MiB by default), git first sends a probe whose body is a single flush packet. The proxy treats that body as an empty command list and forwards it, and it refuses any byte after the flush.
|
|
247
|
+
|
|
248
|
+
The command list has two timeouts. `idleTimeoutMs` restarts on each chunk, so a stalled client is cut off and a slow one is not. It takes a whole number from 0 to 2,147,483,647, and 0 turns the idle timeout off, as for a socket's timeout; any other value makes `startEgressProxy()` throw `invalid_egress_options`. `pushCheckTimeoutMs` never restarts, and it covers the command list only, not the pack, so a client that sends one byte at a time is cut off too. Its default is 60,000 ms, and it takes a whole number from 1 to 2,147,483,647. The 64 KiB limit applies however the list is split across chunks. A refused push gets a 403 with `Connection: close`, and the proxy stops reading the rest of the body: it discards what is already in flight, up to 1 MiB or for 1 second, then ends the response, so a large pack cannot keep the connection open.
|
|
249
|
+
|
|
250
|
+
A pattern is a branch such as `refs/heads/main`, or a prefix such as `refs/heads/agent/*`, which matches the branches under `agent/` and not `agent` itself. A route with no `pushRefs` refuses every push, and one with `fetch` left out refuses every fetch.
|
|
251
|
+
|
|
252
|
+
A route has two limits. With `fetch` on, the sandbox can read every ref of a listed repository, because a fetch is allowed or refused for the whole route. And a route filters git's HTTP requests only, so it says nothing about what a pushed commit contains. The package's tests run a real `git push` over loopback to a fake GitHub on HTTPS: a push to an agent branch arrives with the token, and a push to `main`, a tag and a deletion never reach it.
|
|
253
|
+
|
|
147
254
|
## Every spawned process gets a cleared environment
|
|
148
255
|
|
|
149
256
|
`spawnEnv(allow, extra)` builds the whole environment for a spawned process. It returns `PATH`, a fresh temp `HOME`, `TMPDIR` and `LANG`, the parent variables that `allow` names and the parent has, and `extra`. Nothing else is copied, so a key set in the parent never reaches a child. The caller removes the temp `HOME` when the process is done; an `extra.HOME` replaces it and no folder is made. `PATH` is the parent's with every entry that isn't absolute removed, so a `.` can't run a program from the working directory, and `TMPDIR` is the shared system temp directory, not a private one.
|
|
@@ -158,9 +265,9 @@ The check goes by name and can't catch a credential under an unremarkable one, s
|
|
|
158
265
|
|
|
159
266
|
## Test a sandbox with the fake and the conformance suite
|
|
160
267
|
|
|
161
|
-
`./testing` has `fakeSandbox()`, a sandbox in memory that enforces the policy it is given and records every `exec`, but runs no program: it understands `echo`, `env`, `cat`, `write`, `true`, `false`, `sleep` and `net-probe
|
|
268
|
+
`./testing` has `fakeSandbox()`, a sandbox in memory that enforces the policy it is given and records every `exec`, but runs no program: it understands `echo`, `env`, `cat`, `write`, `true`, `false`, `sleep` and `net-probe`, plus `find`, `grep` and `bash -c` or `sh -c` with one of those commands as the script, which is what the built-in tools run. It claims tier `os`, because it enforces file roots and the network allowlist, but it confines no real process.
|
|
162
269
|
|
|
163
|
-
`runSandboxConformance(factory)` pins the interface for every backend. Its cases check that a file reads back as written, that `exec` reports exit codes and output, that the environment holds only the variables given, that an aborted signal rejects and a timeout stops with 124
|
|
270
|
+
`runSandboxConformance(factory)` pins the interface for every backend. Its cases check that a file reads back as written, that `exec` reports exit codes and output, that the environment holds only the variables given, that an aborted signal rejects and a timeout stops with 124 and `timedOut: true`, and that `dispose` ends the sandbox and any command still running. When the caller passes `processTree`, a case also checks that an abort or timeout ends the command's whole process tree. A backend that adds variables of its own, such as proxy settings, lists them in `addedEnvironment`, and the environment case accepts those and no others.
|
|
164
271
|
|
|
165
272
|
A case that needs enforcement runs only when the backend's `stops` claim it:
|
|
166
273
|
|
|
@@ -169,6 +276,8 @@ A case that needs enforcement runs only when the backend's `stops` claim it:
|
|
|
169
276
|
- a working directory outside the workspace;
|
|
170
277
|
- the network, where the caller passes two hosts it controls, such as two loopback listeners: the allowed one must be reached and the blocked one must not.
|
|
171
278
|
|
|
279
|
+
Three more cases check the read-back and the capabilities: a backend that claims a stop reads its policy back equal to the request, a read-back that differs throws `sandbox_policy_mismatch` and disposes the sandbox, and a capability the backend doesn't list is refused with `sandbox_unsupported`. `fakeSandbox({ applied })` applies a policy in place of the request, as a provider that widens it would.
|
|
280
|
+
|
|
172
281
|
`none` passes the rest and skips those with a reason, and a backend that can't start skips every case with its reason and fails none. The suite tells errors apart by `isHarnessError()` and the error's `code`, so a backend bundled separately from the suite still passes. `sandboxConformanceCases(factory)` returns the same cases one by one, for a runner that wants a test for each.
|
|
173
282
|
|
|
174
283
|
## One registry names, defers and wraps every tool
|
|
@@ -185,6 +294,44 @@ A case that needs enforcement runs only when the backend's `stops` claim it:
|
|
|
185
294
|
- **Output trust.** A tool's `outputTrust` is `untrusted` for an MCP tool and for a tool registered with `remoteAgent: true`, `trusted` otherwise, and the value a registration declares wins. `approvalReuse` defaults to `both`, and `pattern` records whether the tool runs `in_process` or by a `client_request`.
|
|
186
295
|
- **Preamble size.** `preambleTokens({ system })` estimates the tokens a request carries before any message: the system prompt and every `direct` tool. A `deferred` tool adds nothing, which is why the default for MCP is `deferred`. A `RegisteredTool` that `register()` returns is a snapshot, so call `get()` after `setExposure()` to read the current exposure.
|
|
187
296
|
|
|
297
|
+
## The built-in tools reach files, commands and the web only through the sandbox and the egress proxy
|
|
298
|
+
|
|
299
|
+
`builtinTools(sandbox, proxy, { root, policy })` returns up to seven tools for one provisioned sandbox: `read`, `write`, `edit`, `bash`, `grep`, `glob` and `fetch`, which needs a proxy, so six without one. No tool touches the host. Files go through the sandbox's `readFile()` and `writeFile()`, commands through its `exec()`, and the web through the proxy's `fetch()`, so the backend and the allowlist decide what each call can reach. This coding agent binds them to a workspace and lets `read` open the write cap's spill files:
|
|
300
|
+
|
|
301
|
+
```ts
|
|
302
|
+
const sandbox = await client.provision({ root: workspace }, policy);
|
|
303
|
+
const spill = fileSpillStore({ dir: spillDir });
|
|
304
|
+
const registry = createToolRegistry();
|
|
305
|
+
const spills = (path: string) => spill.read(key, path);
|
|
306
|
+
for (const tool of builtinTools(sandbox, proxy, { root: workspace, policy, spills })) registry.register(tool);
|
|
307
|
+
const harness = createHarness({ registry, model, system: SYSTEM, context: createContextPolicy({ spill }) });
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Pass the `root` and `policy` the sandbox was provisioned with, because the sandbox interface reports neither. Leave `proxy` out, as `undefined`, and the set has no `fetch`. `env` is the whole environment of every command the tools run; it defaults to a `PATH` and a `LANG` alone, and on Node you pass `spawnEnv()`.
|
|
311
|
+
|
|
312
|
+
Each tool's contract:
|
|
313
|
+
|
|
314
|
+
- **`read`** takes `path` or `file_path`, relative to `root` or absolute, `offset` (the first line, from 1), `limit` (a line count) and `column` (where to start in the first line, from 1, to read on in a line too long for a page). With none of the three, it returns the whole file up to 2,000 lines and 32 KiB, and a longer file or a page ends with a line that names the next `offset`. The write cap counts bytes after JSON escaping, so `read` counts 32 KiB the same way (a quote, a backslash or a newline costs two bytes). A page therefore always passes the default 64 KiB cap whole. A line longer than a page is shown in parts, and each part's last line names the `offset` and `column` where the next starts, so a cut result that is one long line can still be read in full. Only an absolute path is offered to the `spills` reader, and a path it knows is served from the spill; a relative path always reads the workspace. A binary file is an error result.
|
|
315
|
+
- **`write`** takes a path and `content`, makes the folders and replaces the whole file.
|
|
316
|
+
- **`edit`** takes a path, `old_string` and `new_string`. `old_string` must occur exactly once: no match, or two matches without `replace_all: true`, returns an error result and leaves the file unchanged. `new_string` is inserted as written, so `$&` stays `$&`. A byte order mark is kept, and a binary file or one that is not UTF-8 is an error result, left unchanged, because writing it back as text would corrupt it.
|
|
317
|
+
- **`bash`** runs `command` as `bash -c` inside the sandbox, from `root`, with a timeout of `timeout_ms` (default 120,000, at most 600,000). The model reads the output, standard error and exit code. A timeout or a denial is an error result, and each stream keeps at most 1 MiB. Only the sandbox's `timedOut` flag marks a timeout, so a command that exits with 124 itself reads as that exit code.
|
|
318
|
+
- **`grep`** searches files for `pattern`, an extended regular expression, below `path` (default `root`), and prints `path:line:text`. `glob` narrows the files: a glob with no `/`, such as `*.ts`, matches the file name, and any other matches the path below `path`. `ignore_case` ignores case. Binary files are skipped (`grep -I`).
|
|
319
|
+
|
|
320
|
+
The matching lines stop at 1 MiB, across every `grep` command the call runs, and a result cut there says so, so the model can narrow the search. If the first matching line alone passes 1 MiB, the result still says that lines match, names the file and line, and suggests a narrower search or `read`; it never reports "no match". A file `grep` can't read, or a folder `find` can't list, keeps the matches found elsewhere and adds a line quoting the error; the call fails only when nothing matched.
|
|
321
|
+
- **`glob`** lists the files below `path` whose path matches `pattern`, sorted. `*` matches inside one name, `**` across folders and `?` one character.
|
|
322
|
+
- **`fetch`** sends a GET for an `https` `url` through `proxy.fetch()`. It returns the status line, the final URL, any `location`, the content type and, for a text body, up to 1 MiB of it. A body of another type is left out and reported by its size. Every secret the proxy knows is replaced by `[REDACTED]`, and a body cut at 1 MiB also loses any start of a secret left at its end.
|
|
323
|
+
- A text body is read in the charset its content type names, when `TextDecoder` knows that label, and as UTF-8 otherwise.
|
|
324
|
+
- A body with no content type, or with a charset label `TextDecoder` does not know, is shown only when it reads as UTF-8 text with no NUL byte.
|
|
325
|
+
- A request that takes over 30 seconds returns an error, as do a host off the allowlist and a URL that is not `https`. Plain HTTP is refused, which keeps the model off the proxy's credential routes.
|
|
326
|
+
|
|
327
|
+
**Paths are checked before the sandbox sees them.** `read`, `grep` and `glob` accept a path inside a read or write root, and `write` and `edit` only inside a write root. A path with a backslash is refused, because the workspace is POSIX, where `\` is part of a name, while the permission rules read it as a separator. The check joins a relative path to `root` and removes `.` and `..`, so `../etc/passwd` and `/etc/passwd` are refused without a sandbox call, and the sandbox gets the checked path. A symlink is invisible to a check on text, so the sandbox's own check of the real path is the second line: its denial reaches the model as an error result. `grep` and `glob` list files with `find`, which never follows a symlink, and skip folders named `.git` and `node_modules` below the folder searched, so a search of `node_modules` itself still works.
|
|
328
|
+
|
|
329
|
+
**Big results pass the write cap like any other.** The tools cap nothing themselves: the context policy's write cap cuts a long result and spills its full text, and `read` with `spills` opens that spill. Bind `spills` to one session, as `fileSpillStore().read(key, path)` already does, so one session cannot read another's spills.
|
|
330
|
+
|
|
331
|
+
**Scheduling follows what each tool changes.** `read`, `grep`, `glob` and `fetch` are first-party and read-only, so their calls in one step run together. `write` and `edit` declare a write, so they wait for the file calls before them, and `bash` runs its step one call at a time. A crash during a write makes the next turn report its outcome as unknown. Only `fetch`'s output is `untrusted`, because a web page can carry instructions; the rest is `trusted`, though a workspace file or a command's output can carry instructions too.
|
|
332
|
+
|
|
333
|
+
**The descriptions are versioned.** Every description, limit and default the tools use is in `BUILTIN_TOOL_DEFAULTS`, and `BUILTIN_TOOLS_HASH` changes whenever any of them does, so two runs with different hashes ran with different tools.
|
|
334
|
+
|
|
188
335
|
## One pipeline decides every tool call, and a call no rule settles is denied when nobody can answer
|
|
189
336
|
|
|
190
337
|
`@buildanagent/harness/permissions` decides each tool call in one order: hooks, deny rules, ask rules, the mode, allow rules, the host callback, then the no-match default. A deny at any step ends the decision, so a deny rule beats every mode, `bypass` included, and a hook's deny beats everything. `createPermissionPipeline(config, registry)` returns a pipeline, and `pipeline.gate(context)` is the SDK's `beforeToolCall` gate, where `context` gives each call its session, host context and entries.
|
|
@@ -406,7 +553,7 @@ const context = createContextPolicy({ spill: fileSpillStore({ dir: ".sessions/sp
|
|
|
406
553
|
|
|
407
554
|
**Layer 1, the write cap.** A tool result whose text is over the cap is cut before the model reads it, and the full text goes to the `spill` store. The model reads the first part and a line that names the file, and the `tool_result` entry stores the same cut text with `spill: { path, bytes }`. If the store cannot write, the text is still cut, and the notice says the rest was not kept.
|
|
408
555
|
|
|
409
|
-
The cap counts the bytes the entry takes in the log: JSON escaping, the result's details and other blocks, and 1 KiB for the entry's own fields. A capped entry therefore always fits the stores' 64 KiB entry bound. The default `writeCapBytes` of 65,536 leaves the model a little under 64 KiB of plain text, and less of a text full of newlines or quotes. `fileSpillStore({ dir })` from `@buildanagent/harness/context/file` writes one file per capped result, and `memorySpillStore()` serves tests. A file is named by the run id, a count within the run and the call id, because a provider may reuse a call id. A policy with the layer on and no `spill` throws `invalid_context_options`.
|
|
556
|
+
The cap counts the bytes the entry takes in the log: JSON escaping, the result's details and other blocks, and 1 KiB for the entry's own fields. A capped entry therefore always fits the stores' 64 KiB entry bound. The default `writeCapBytes` of 65,536 leaves the model a little under 64 KiB of plain text, and less of a text full of newlines or quotes. `fileSpillStore({ dir })` from `@buildanagent/harness/context/file` writes one file per capped result, and `memorySpillStore()` serves tests, with absolute paths under `/spill/`. `fileSpillStore().read()` reads only an absolute path inside the session's folder. A file is named by the run id, a count within the run and the call id, because a provider may reuse a call id. A policy with the layer on and no `spill` throws `invalid_context_options`.
|
|
410
557
|
|
|
411
558
|
**Layer 2, stepped masking.** Before each model call, every tool result before a cutoff shrinks to its first 500 characters and a pointer line. The line names the spill file, or the log entry when the result was never spilled. A cut never leaves half of a surrogate pair. The cutoff is `floor((messages − 8) / 8) × 8`, so it moves once every eight messages. Between moves the view's prefix stays byte-identical, which keeps a provider's prompt cache hitting.
|
|
412
559
|
|
|
@@ -1,5 +1,15 @@
|
|
|
1
|
+
import { type SessionKey } from "../session/store.js";
|
|
1
2
|
import type { SpillStore } from "./types.js";
|
|
3
|
+
/** A spill store in files, which can also read back the spills of one session. */
|
|
4
|
+
export interface FileSpillStore extends SpillStore {
|
|
5
|
+
/**
|
|
6
|
+
* The text spilled to `path` for the session `key`, or `undefined` when `path` is not a spill file of that session.
|
|
7
|
+
* `path` must be absolute, as `write()` returns it. A relative path, a path outside the session's folder, and one
|
|
8
|
+
* that leads out through a symlink are never read.
|
|
9
|
+
*/
|
|
10
|
+
read(key: SessionKey, path: string): Promise<string | undefined>;
|
|
11
|
+
}
|
|
2
12
|
/** A spill store that writes `<dir>/<user>/<session>/<callId>.txt` and returns that path. */
|
|
3
13
|
export declare function fileSpillStore(options: {
|
|
4
14
|
readonly dir: string;
|
|
5
|
-
}):
|
|
15
|
+
}): FileSpillStore;
|
|
@@ -1,25 +1,40 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The spill store that keeps each capped tool result in a file, one per call, in a folder per session. It uses Node's
|
|
3
|
-
* file system, loaded with `process.getBuiltinModule()` when a result is written, so importing it costs a
|
|
4
|
-
* bundle nothing. It has its own entry, `@buildanagent/harness/context/file`.
|
|
3
|
+
* file system, loaded with `process.getBuiltinModule()` when a result is written or read, so importing it costs a
|
|
4
|
+
* portable bundle nothing. It has its own entry, `@buildanagent/harness/context/file`.
|
|
5
5
|
*/
|
|
6
6
|
import { HarnessError } from "../errors.js";
|
|
7
7
|
import { encodeName } from "../session/store.js";
|
|
8
|
+
function nodeModules() {
|
|
9
|
+
if (typeof process === "undefined" || typeof process.getBuiltinModule !== "function") {
|
|
10
|
+
throw new HarnessError("spill_unavailable", "fileSpillStore needs Node's file system, which this runtime lacks");
|
|
11
|
+
}
|
|
12
|
+
return { fs: process.getBuiltinModule("node:fs/promises"), path: process.getBuiltinModule("node:path") };
|
|
13
|
+
}
|
|
8
14
|
/** A spill store that writes `<dir>/<user>/<session>/<callId>.txt` and returns that path. */
|
|
9
15
|
export function fileSpillStore(options) {
|
|
16
|
+
const folderOf = (key) => nodeModules().path.resolve(options.dir, encodeName(key.userId), encodeName(key.sessionId));
|
|
10
17
|
return {
|
|
11
18
|
async write(key, callId, text) {
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
}
|
|
15
|
-
const fs = process.getBuiltinModule("node:fs/promises");
|
|
16
|
-
const path = process.getBuiltinModule("node:path");
|
|
17
|
-
const folder = path.resolve(options.dir, encodeName(key.userId), encodeName(key.sessionId));
|
|
19
|
+
const { fs, path } = nodeModules();
|
|
20
|
+
const folder = folderOf(key);
|
|
18
21
|
await fs.mkdir(folder, { recursive: true });
|
|
19
22
|
const file = path.join(folder, `${encodeName(callId)}.txt`);
|
|
20
23
|
await fs.writeFile(file, text, "utf8");
|
|
21
24
|
return file;
|
|
22
25
|
},
|
|
26
|
+
async read(key, file) {
|
|
27
|
+
const { fs, path } = nodeModules();
|
|
28
|
+
// A relative path would resolve against the spill folder, so a workspace file's name could open a spill.
|
|
29
|
+
if (!path.isAbsolute(file))
|
|
30
|
+
return undefined;
|
|
31
|
+
// Both sides are real paths, so a link inside the folder that points out of it is caught.
|
|
32
|
+
const folder = await fs.realpath(folderOf(key)).catch(() => undefined);
|
|
33
|
+
const real = await fs.realpath(path.resolve(folderOf(key), file)).catch(() => undefined);
|
|
34
|
+
if (folder === undefined || real === undefined || path.dirname(real) !== folder)
|
|
35
|
+
return undefined;
|
|
36
|
+
return fs.readFile(real, "utf8").catch(() => undefined);
|
|
37
|
+
},
|
|
23
38
|
};
|
|
24
39
|
}
|
|
25
40
|
//# sourceMappingURL=file-spill.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"file-spill.js","sourceRoot":"","sources":["../../src/context/file-spill.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAmB,MAAM,qBAAqB,CAAC;
|
|
1
|
+
{"version":3,"file":"file-spill.js","sourceRoot":"","sources":["../../src/context/file-spill.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAmB,MAAM,qBAAqB,CAAC;AAalE,SAAS,WAAW;IAClB,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,OAAO,CAAC,gBAAgB,KAAK,UAAU,EAAE,CAAC;QACrF,MAAM,IAAI,YAAY,CAAC,mBAAmB,EAAE,mEAAmE,CAAC,CAAC;IACnH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,CAAC;AAC3G,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,cAAc,CAAC,OAAiC;IAC9D,MAAM,QAAQ,GAAG,CAAC,GAAe,EAAE,EAAE,CACnC,WAAW,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IAC7F,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,GAAe,EAAE,MAAc,EAAE,IAAY;YACvD,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,WAAW,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5D,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YACvC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAe,EAAE,IAAY;YACtC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,WAAW,EAAE,CAAC;YACnC,yGAAyG;YACzG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC7C,0FAA0F;YAC1F,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACvE,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACzF,IAAI,MAAM,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,MAAM;gBAAE,OAAO,SAAS,CAAC;YAClG,OAAO,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1D,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The spill store that keeps each capped tool result in a file, one per call, in a folder per session. It uses Node's\n * file system, loaded with `process.getBuiltinModule()` when a result is written or read, so importing it costs a\n * portable bundle nothing. It has its own entry, `@buildanagent/harness/context/file`.\n */\nimport { HarnessError } from \"../errors.js\";\nimport { encodeName, type SessionKey } from \"../session/store.js\";\nimport type { SpillStore } from \"./types.js\";\n\n/** A spill store in files, which can also read back the spills of one session. */\nexport interface FileSpillStore extends SpillStore {\n /**\n * The text spilled to `path` for the session `key`, or `undefined` when `path` is not a spill file of that session.\n * `path` must be absolute, as `write()` returns it. A relative path, a path outside the session's folder, and one\n * that leads out through a symlink are never read.\n */\n read(key: SessionKey, path: string): Promise<string | undefined>;\n}\n\nfunction nodeModules() {\n if (typeof process === \"undefined\" || typeof process.getBuiltinModule !== \"function\") {\n throw new HarnessError(\"spill_unavailable\", \"fileSpillStore needs Node's file system, which this runtime lacks\");\n }\n return { fs: process.getBuiltinModule(\"node:fs/promises\"), path: process.getBuiltinModule(\"node:path\") };\n}\n\n/** A spill store that writes `<dir>/<user>/<session>/<callId>.txt` and returns that path. */\nexport function fileSpillStore(options: { readonly dir: string }): FileSpillStore {\n const folderOf = (key: SessionKey) =>\n nodeModules().path.resolve(options.dir, encodeName(key.userId), encodeName(key.sessionId));\n return {\n async write(key: SessionKey, callId: string, text: string): Promise<string> {\n const { fs, path } = nodeModules();\n const folder = folderOf(key);\n await fs.mkdir(folder, { recursive: true });\n const file = path.join(folder, `${encodeName(callId)}.txt`);\n await fs.writeFile(file, text, \"utf8\");\n return file;\n },\n async read(key: SessionKey, file: string): Promise<string | undefined> {\n const { fs, path } = nodeModules();\n // A relative path would resolve against the spill folder, so a workspace file's name could open a spill.\n if (!path.isAbsolute(file)) return undefined;\n // Both sides are real paths, so a link inside the folder that points out of it is caught.\n const folder = await fs.realpath(folderOf(key)).catch(() => undefined);\n const real = await fs.realpath(path.resolve(folderOf(key), file)).catch(() => undefined);\n if (folder === undefined || real === undefined || path.dirname(real) !== folder) return undefined;\n return fs.readFile(real, \"utf8\").catch(() => undefined);\n },\n };\n}\n"]}
|
package/dist/context/spill.d.ts
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
import type { SpillStore } from "./types.js";
|
|
2
|
-
/**
|
|
2
|
+
/**
|
|
3
|
+
* A spill store in memory, for tests and for a process that keeps its sessions in `memoryStore()`. Its paths are
|
|
4
|
+
* absolute, `/spill/<user>/<session>/<call>.txt`, so the built-in `read` tool, which asks its spill reader only about an
|
|
5
|
+
* absolute path, can open them.
|
|
6
|
+
*/
|
|
3
7
|
export declare function memorySpillStore(): SpillStore & {
|
|
4
8
|
/** The full text spilled to `path`, or `undefined` when nothing was. */
|
|
5
9
|
read(path: string): string | undefined;
|
package/dist/context/spill.js
CHANGED
|
@@ -1,10 +1,14 @@
|
|
|
1
1
|
import { encodeName } from "../session/store.js";
|
|
2
|
-
/**
|
|
2
|
+
/**
|
|
3
|
+
* A spill store in memory, for tests and for a process that keeps its sessions in `memoryStore()`. Its paths are
|
|
4
|
+
* absolute, `/spill/<user>/<session>/<call>.txt`, so the built-in `read` tool, which asks its spill reader only about an
|
|
5
|
+
* absolute path, can open them.
|
|
6
|
+
*/
|
|
3
7
|
export function memorySpillStore() {
|
|
4
8
|
const files = new Map();
|
|
5
9
|
return {
|
|
6
10
|
async write(key, callId, text) {
|
|
7
|
-
const path =
|
|
11
|
+
const path = `/spill/${encodeName(key.userId)}/${encodeName(key.sessionId)}/${encodeName(callId)}.txt`;
|
|
8
12
|
files.set(path, text);
|
|
9
13
|
return path;
|
|
10
14
|
},
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"spill.js","sourceRoot":"","sources":["../../src/context/spill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAmB,MAAM,qBAAqB,CAAC;AAGlE
|
|
1
|
+
{"version":3,"file":"spill.js","sourceRoot":"","sources":["../../src/context/spill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAmB,MAAM,qBAAqB,CAAC;AAGlE;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAI9B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,GAAe,EAAE,MAAc,EAAE,IAAY;YACvD,MAAM,IAAI,GAAG,UAAU,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC;YACvG,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;KAChC,CAAC;AACJ,CAAC","sourcesContent":["import { encodeName, type SessionKey } from \"../session/store.js\";\nimport type { SpillStore } from \"./types.js\";\n\n/**\n * A spill store in memory, for tests and for a process that keeps its sessions in `memoryStore()`. Its paths are\n * absolute, `/spill/<user>/<session>/<call>.txt`, so the built-in `read` tool, which asks its spill reader only about an\n * absolute path, can open them.\n */\nexport function memorySpillStore(): SpillStore & {\n /** The full text spilled to `path`, or `undefined` when nothing was. */\n read(path: string): string | undefined;\n} {\n const files = new Map<string, string>();\n return {\n async write(key: SessionKey, callId: string, text: string): Promise<string> {\n const path = `/spill/${encodeName(key.userId)}/${encodeName(key.sessionId)}/${encodeName(callId)}.txt`;\n files.set(path, text);\n return path;\n },\n read: (path) => files.get(path),\n };\n}\n"]}
|
|
@@ -12,3 +12,14 @@
|
|
|
12
12
|
export declare function isPublicAddress(address: string): boolean;
|
|
13
13
|
/** Whether `text` is an IPv4 or IPv6 address, as a host name that must not be looked up. */
|
|
14
14
|
export declare function isAddressLiteral(text: string): boolean;
|
|
15
|
+
/**
|
|
16
|
+
* The IPv4 address `address` names, as a number: a dotted quad in its canonical form, or an IPv6 address that wraps
|
|
17
|
+
* one (the mapped, compatible, translated, NAT64 and 6to4 forms). `undefined` for anything else.
|
|
18
|
+
*/
|
|
19
|
+
export declare function ipv4Of(address: string): number | undefined;
|
|
20
|
+
/**
|
|
21
|
+
* Whether `address` reaches the host itself or its link: unspecified, loopback or link-local (which holds the cloud
|
|
22
|
+
* metadata address 169.254.169.254), for IPv4 and IPv6, and an IPv6 address that wraps one of those IPv4 ones. Text
|
|
23
|
+
* that isn't an address literal is not one.
|
|
24
|
+
*/
|
|
25
|
+
export declare function isLocalAddress(address: string): boolean;
|
|
@@ -73,12 +73,14 @@ function parseIpv6(text) {
|
|
|
73
73
|
const missing = 8 - head.length - tail.length;
|
|
74
74
|
return missing >= 1 ? [...head, ...new Array(missing).fill(0), ...tail] : undefined;
|
|
75
75
|
}
|
|
76
|
-
|
|
77
|
-
|
|
76
|
+
/** Whether `value` falls in one of `ranges`, each an `[address, prefix length]` pair. */
|
|
77
|
+
function inIpv4Ranges(value, ranges) {
|
|
78
|
+
return ranges.some(([base, bits]) => {
|
|
78
79
|
const size = 2 ** (32 - bits);
|
|
79
80
|
return Math.floor(value / size) === Math.floor(base / size);
|
|
80
81
|
});
|
|
81
82
|
}
|
|
83
|
+
const ipv4Refused = (value) => inIpv4Ranges(value, IPV4_REFUSED);
|
|
82
84
|
/** The IPv6 prefixes a proxy refuses, as the leading groups and the prefix length in bits. */
|
|
83
85
|
const IPV6_REFUSED = [
|
|
84
86
|
[[0, 0, 0, 0, 0, 0, 0, 0], 128], // ::, unspecified
|
|
@@ -141,4 +143,41 @@ export function isAddressLiteral(text) {
|
|
|
141
143
|
const bare = text.startsWith("[") && text.endsWith("]") ? text.slice(1, -1) : text;
|
|
142
144
|
return parseIpv4(bare) !== undefined || parseIpv6(bare) !== undefined;
|
|
143
145
|
}
|
|
146
|
+
const bareOf = (text) => (text.startsWith("[") && text.endsWith("]") ? text.slice(1, -1) : text);
|
|
147
|
+
/**
|
|
148
|
+
* The IPv4 address `address` names, as a number: a dotted quad in its canonical form, or an IPv6 address that wraps
|
|
149
|
+
* one (the mapped, compatible, translated, NAT64 and 6to4 forms). `undefined` for anything else.
|
|
150
|
+
*/
|
|
151
|
+
export function ipv4Of(address) {
|
|
152
|
+
const bare = bareOf(address);
|
|
153
|
+
const v4 = parseIpv4(bare);
|
|
154
|
+
if (v4 !== undefined)
|
|
155
|
+
return v4;
|
|
156
|
+
const v6 = parseIpv6(bare);
|
|
157
|
+
return v6 === undefined ? undefined : wrappedIpv4(v6);
|
|
158
|
+
}
|
|
159
|
+
/** The IPv4 ranges that reach the host itself or its link: this network, loopback and link-local. */
|
|
160
|
+
const IPV4_LOCAL = [
|
|
161
|
+
[0x00000000, 8],
|
|
162
|
+
[0x7f000000, 8],
|
|
163
|
+
[0xa9fe0000, 16],
|
|
164
|
+
];
|
|
165
|
+
/** The IPv6 prefixes that reach the host itself or its link: unspecified, loopback and link-local. */
|
|
166
|
+
const IPV6_LOCAL = [
|
|
167
|
+
[[0, 0, 0, 0, 0, 0, 0, 0], 128],
|
|
168
|
+
[[0, 0, 0, 0, 0, 0, 0, 1], 128],
|
|
169
|
+
[[0xfe80], 10],
|
|
170
|
+
];
|
|
171
|
+
/**
|
|
172
|
+
* Whether `address` reaches the host itself or its link: unspecified, loopback or link-local (which holds the cloud
|
|
173
|
+
* metadata address 169.254.169.254), for IPv4 and IPv6, and an IPv6 address that wraps one of those IPv4 ones. Text
|
|
174
|
+
* that isn't an address literal is not one.
|
|
175
|
+
*/
|
|
176
|
+
export function isLocalAddress(address) {
|
|
177
|
+
const v4 = ipv4Of(address);
|
|
178
|
+
if (v4 !== undefined && inIpv4Ranges(v4, IPV4_LOCAL))
|
|
179
|
+
return true;
|
|
180
|
+
const v6 = parseIpv6(bareOf(address));
|
|
181
|
+
return v6 !== undefined && IPV6_LOCAL.some(([prefix, bits]) => inPrefix(v6, prefix, bits));
|
|
182
|
+
}
|
|
144
183
|
//# sourceMappingURL=addresses.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"addresses.js","sourceRoot":"","sources":["../../src/credentials/addresses.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which network addresses an egress proxy may connect to. It refuses every address that isn't a public one: loopback,\n * link-local (which holds the cloud metadata address 169.254.169.254), private, carrier-grade NAT, unspecified,\n * multicast and reserved ranges, for both IPv4 and IPv6, and an IPv6 address that wraps one of the refused IPv4 ones.\n * Names resolve to addresses in the proxy, and each address is checked here, so a name that points at the host's own\n * network is refused even when its name is allowed. It parses addresses itself and imports no Node module.\n */\n\n/** The IPv4 ranges a proxy refuses, as `[address, prefix length]`. */\nconst IPV4_REFUSED: readonly (readonly [number, number])[] = [\n [0x00000000, 8], // this network\n [0x0a000000, 8], // private\n [0x64400000, 10], // carrier-grade NAT, 100.64.0.0/10\n [0x7f000000, 8], // loopback\n [0xa9fe0000, 16], // link-local, which holds the metadata address\n [0xac100000, 12], // private\n [0xc0000000, 24], // IETF protocol assignments\n [0xc0000200, 24], // documentation\n [0xc0a80000, 16], // private\n [0xc6120000, 15], // benchmarking, 198.18.0.0/15\n [0xc6336400, 24], // documentation\n [0xcb007100, 24], // documentation\n [0xe0000000, 4], // multicast\n [0xf0000000, 4], // reserved, and the broadcast address\n];\n\n/** The four parts of an IPv4 address as one number, or `undefined` when `text` is not a dotted quad. */\nfunction parseIpv4(text: string): number | undefined {\n const parts = text.split(\".\");\n if (parts.length !== 4) return undefined;\n let value = 0;\n for (const part of parts) {\n if (!/^(0|[1-9][0-9]{0,2})$/.test(part)) return undefined;\n const octet = Number(part);\n if (octet > 255) return undefined;\n value = value * 256 + octet;\n }\n return value;\n}\n\n/** The 16-bit groups in one side of an IPv6 address, where the last piece may be a dotted IPv4 address. */\nfunction readGroups(side: string): number[] | undefined {\n if (side === \"\") return [];\n const groups: number[] = [];\n const pieces = side.split(\":\");\n for (const [index, piece] of pieces.entries()) {\n const v4 = index === pieces.length - 1 && piece.includes(\".\") ? parseIpv4(piece) : undefined;\n if (v4 !== undefined) {\n groups.push(Math.floor(v4 / 65536), v4 % 65536);\n } else if (/^[0-9a-fA-F]{1,4}$/.test(piece)) {\n groups.push(Number.parseInt(piece, 16));\n } else {\n return undefined;\n }\n }\n return groups;\n}\n\n/** The eight 16-bit groups of an IPv6 address, or `undefined` when `text` is not one. */\nfunction parseIpv6(text: string): number[] | undefined {\n const whole = text.split(\"%\")[0] ?? text;\n const doubles = whole.split(\"::\");\n if (doubles.length > 2) return undefined;\n const head = readGroups(doubles[0] ?? \"\");\n const tail = doubles.length === 2 ? readGroups(doubles[1] ?? \"\") : [];\n if (head === undefined || tail === undefined) return undefined;\n if (doubles.length === 1) return head.length === 8 ? head : undefined;\n const missing = 8 - head.length - tail.length;\n return missing >= 1 ? [...head, ...new Array<number>(missing).fill(0), ...tail] : undefined;\n}\n\nfunction ipv4Refused(value: number): boolean {\n return IPV4_REFUSED.some(([base, bits]) => {\n const size = 2 ** (32 - bits);\n return Math.floor(value / size) === Math.floor(base / size);\n });\n}\n\n/** The IPv6 prefixes a proxy refuses, as the leading groups and the prefix length in bits. */\nconst IPV6_REFUSED: readonly (readonly [readonly number[], number])[] = [\n [[0, 0, 0, 0, 0, 0, 0, 0], 128], // ::, unspecified\n [[0, 0, 0, 0, 0, 0, 0, 1], 128], // ::1, loopback\n [[0x64, 0xff9b, 1], 48], // 64:ff9b:1::/48, local-use NAT64\n [[0x100], 64], // 100::/64, discard-only\n [[0x2001, 0], 23], // 2001::/23: Teredo, benchmarking, ORCHID and protocol assignments\n [[0x2001, 0x0db8], 32], // documentation\n [[0x3fff], 20], // 3fff::/20, documentation\n [[0x5f00], 16], // segment routing SIDs\n [[0xfc00], 7], // unique local\n [[0xfe80], 10], // link-local\n [[0xfec0], 10], // site-local, deprecated\n [[0xff00], 8], // multicast\n];\n\n/** Whether the first `bits` bits of `groups` equal those of `prefix`. */\nfunction inPrefix(groups: readonly number[], prefix: readonly number[], bits: number): boolean {\n for (let index = 0; index * 16 < bits; index += 1) {\n const take = Math.min(16, bits - index * 16);\n const mask = (0xffff << (16 - take)) & 0xffff;\n if (((groups[index] ?? 0) & mask) !== ((prefix[index] ?? 0) & mask)) return false;\n }\n return true;\n}\n\n/** The IPv4 address an IPv6 one carries, as a number: mapped, compatible, translated, NAT64 and 6to4 forms. */\nfunction wrappedIpv4(groups: readonly number[]): number | undefined {\n const [a = 0, b = 0, c = 0, d = 0, e = 0, f = 0, g = 0, h = 0] = groups;\n const zeroHigh = a === 0 && b === 0 && c === 0 && d === 0;\n const low = g * 65536 + h;\n if (zeroHigh && e === 0 && (f === 0xffff || f === 0)) return low; // ::ffff:a.b.c.d and ::a.b.c.d\n if (zeroHigh && e === 0xffff && f === 0) return low; // ::ffff:0:a.b.c.d, IPv4-translated\n if (a === 0x64 && b === 0xff9b && c === 0 && d === 0 && e === 0 && f === 0) return low; // 64:ff9b::/96\n return a === 0x2002 ? b * 65536 + c : undefined; // 6to4 wraps the address in its next two groups\n}\n\n/** Whether an IPv6 address, as eight groups, is one a proxy refuses. */\nfunction ipv6Refused(groups: readonly number[]): boolean {\n const wrapped = wrappedIpv4(groups);\n if (wrapped !== undefined && ipv4Refused(wrapped)) return true;\n return IPV6_REFUSED.some(([prefix, bits]) => inPrefix(groups, prefix, bits));\n}\n\n/**\n * Whether `address` is a public one a proxy may connect to. Text that isn't an IPv4 or IPv6 address is not public, so a\n * resolver's odd answer is refused instead of passed on.\n */\nexport function isPublicAddress(address: string): boolean {\n const bare = address.startsWith(\"[\") && address.endsWith(\"]\") ? address.slice(1, -1) : address;\n const v4 = parseIpv4(bare);\n if (v4 !== undefined) return !ipv4Refused(v4);\n const v6 = parseIpv6(bare);\n return v6 !== undefined && !ipv6Refused(v6);\n}\n\n/** Whether `text` is an IPv4 or IPv6 address, as a host name that must not be looked up. */\nexport function isAddressLiteral(text: string): boolean {\n const bare = text.startsWith(\"[\") && text.endsWith(\"]\") ? text.slice(1, -1) : text;\n return parseIpv4(bare) !== undefined || parseIpv6(bare) !== undefined;\n}\n"]}
|
|
1
|
+
{"version":3,"file":"addresses.js","sourceRoot":"","sources":["../../src/credentials/addresses.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which network addresses an egress proxy may connect to. It refuses every address that isn't a public one: loopback,\n * link-local (which holds the cloud metadata address 169.254.169.254), private, carrier-grade NAT, unspecified,\n * multicast and reserved ranges, for both IPv4 and IPv6, and an IPv6 address that wraps one of the refused IPv4 ones.\n * Names resolve to addresses in the proxy, and each address is checked here, so a name that points at the host's own\n * network is refused even when its name is allowed. It parses addresses itself and imports no Node module.\n */\n\n/** The IPv4 ranges a proxy refuses, as `[address, prefix length]`. */\nconst IPV4_REFUSED: readonly (readonly [number, number])[] = [\n [0x00000000, 8], // this network\n [0x0a000000, 8], // private\n [0x64400000, 10], // carrier-grade NAT, 100.64.0.0/10\n [0x7f000000, 8], // loopback\n [0xa9fe0000, 16], // link-local, which holds the metadata address\n [0xac100000, 12], // private\n [0xc0000000, 24], // IETF protocol assignments\n [0xc0000200, 24], // documentation\n [0xc0a80000, 16], // private\n [0xc6120000, 15], // benchmarking, 198.18.0.0/15\n [0xc6336400, 24], // documentation\n [0xcb007100, 24], // documentation\n [0xe0000000, 4], // multicast\n [0xf0000000, 4], // reserved, and the broadcast address\n];\n\n/** The four parts of an IPv4 address as one number, or `undefined` when `text` is not a dotted quad. */\nfunction parseIpv4(text: string): number | undefined {\n const parts = text.split(\".\");\n if (parts.length !== 4) return undefined;\n let value = 0;\n for (const part of parts) {\n if (!/^(0|[1-9][0-9]{0,2})$/.test(part)) return undefined;\n const octet = Number(part);\n if (octet > 255) return undefined;\n value = value * 256 + octet;\n }\n return value;\n}\n\n/** The 16-bit groups in one side of an IPv6 address, where the last piece may be a dotted IPv4 address. */\nfunction readGroups(side: string): number[] | undefined {\n if (side === \"\") return [];\n const groups: number[] = [];\n const pieces = side.split(\":\");\n for (const [index, piece] of pieces.entries()) {\n const v4 = index === pieces.length - 1 && piece.includes(\".\") ? parseIpv4(piece) : undefined;\n if (v4 !== undefined) {\n groups.push(Math.floor(v4 / 65536), v4 % 65536);\n } else if (/^[0-9a-fA-F]{1,4}$/.test(piece)) {\n groups.push(Number.parseInt(piece, 16));\n } else {\n return undefined;\n }\n }\n return groups;\n}\n\n/** The eight 16-bit groups of an IPv6 address, or `undefined` when `text` is not one. */\nfunction parseIpv6(text: string): number[] | undefined {\n const whole = text.split(\"%\")[0] ?? text;\n const doubles = whole.split(\"::\");\n if (doubles.length > 2) return undefined;\n const head = readGroups(doubles[0] ?? \"\");\n const tail = doubles.length === 2 ? readGroups(doubles[1] ?? \"\") : [];\n if (head === undefined || tail === undefined) return undefined;\n if (doubles.length === 1) return head.length === 8 ? head : undefined;\n const missing = 8 - head.length - tail.length;\n return missing >= 1 ? [...head, ...new Array<number>(missing).fill(0), ...tail] : undefined;\n}\n\n/** Whether `value` falls in one of `ranges`, each an `[address, prefix length]` pair. */\nfunction inIpv4Ranges(value: number, ranges: readonly (readonly [number, number])[]): boolean {\n return ranges.some(([base, bits]) => {\n const size = 2 ** (32 - bits);\n return Math.floor(value / size) === Math.floor(base / size);\n });\n}\n\nconst ipv4Refused = (value: number): boolean => inIpv4Ranges(value, IPV4_REFUSED);\n\n/** The IPv6 prefixes a proxy refuses, as the leading groups and the prefix length in bits. */\nconst IPV6_REFUSED: readonly (readonly [readonly number[], number])[] = [\n [[0, 0, 0, 0, 0, 0, 0, 0], 128], // ::, unspecified\n [[0, 0, 0, 0, 0, 0, 0, 1], 128], // ::1, loopback\n [[0x64, 0xff9b, 1], 48], // 64:ff9b:1::/48, local-use NAT64\n [[0x100], 64], // 100::/64, discard-only\n [[0x2001, 0], 23], // 2001::/23: Teredo, benchmarking, ORCHID and protocol assignments\n [[0x2001, 0x0db8], 32], // documentation\n [[0x3fff], 20], // 3fff::/20, documentation\n [[0x5f00], 16], // segment routing SIDs\n [[0xfc00], 7], // unique local\n [[0xfe80], 10], // link-local\n [[0xfec0], 10], // site-local, deprecated\n [[0xff00], 8], // multicast\n];\n\n/** Whether the first `bits` bits of `groups` equal those of `prefix`. */\nfunction inPrefix(groups: readonly number[], prefix: readonly number[], bits: number): boolean {\n for (let index = 0; index * 16 < bits; index += 1) {\n const take = Math.min(16, bits - index * 16);\n const mask = (0xffff << (16 - take)) & 0xffff;\n if (((groups[index] ?? 0) & mask) !== ((prefix[index] ?? 0) & mask)) return false;\n }\n return true;\n}\n\n/** The IPv4 address an IPv6 one carries, as a number: mapped, compatible, translated, NAT64 and 6to4 forms. */\nfunction wrappedIpv4(groups: readonly number[]): number | undefined {\n const [a = 0, b = 0, c = 0, d = 0, e = 0, f = 0, g = 0, h = 0] = groups;\n const zeroHigh = a === 0 && b === 0 && c === 0 && d === 0;\n const low = g * 65536 + h;\n if (zeroHigh && e === 0 && (f === 0xffff || f === 0)) return low; // ::ffff:a.b.c.d and ::a.b.c.d\n if (zeroHigh && e === 0xffff && f === 0) return low; // ::ffff:0:a.b.c.d, IPv4-translated\n if (a === 0x64 && b === 0xff9b && c === 0 && d === 0 && e === 0 && f === 0) return low; // 64:ff9b::/96\n return a === 0x2002 ? b * 65536 + c : undefined; // 6to4 wraps the address in its next two groups\n}\n\n/** Whether an IPv6 address, as eight groups, is one a proxy refuses. */\nfunction ipv6Refused(groups: readonly number[]): boolean {\n const wrapped = wrappedIpv4(groups);\n if (wrapped !== undefined && ipv4Refused(wrapped)) return true;\n return IPV6_REFUSED.some(([prefix, bits]) => inPrefix(groups, prefix, bits));\n}\n\n/**\n * Whether `address` is a public one a proxy may connect to. Text that isn't an IPv4 or IPv6 address is not public, so a\n * resolver's odd answer is refused instead of passed on.\n */\nexport function isPublicAddress(address: string): boolean {\n const bare = address.startsWith(\"[\") && address.endsWith(\"]\") ? address.slice(1, -1) : address;\n const v4 = parseIpv4(bare);\n if (v4 !== undefined) return !ipv4Refused(v4);\n const v6 = parseIpv6(bare);\n return v6 !== undefined && !ipv6Refused(v6);\n}\n\n/** Whether `text` is an IPv4 or IPv6 address, as a host name that must not be looked up. */\nexport function isAddressLiteral(text: string): boolean {\n const bare = text.startsWith(\"[\") && text.endsWith(\"]\") ? text.slice(1, -1) : text;\n return parseIpv4(bare) !== undefined || parseIpv6(bare) !== undefined;\n}\n\nconst bareOf = (text: string): string => (text.startsWith(\"[\") && text.endsWith(\"]\") ? text.slice(1, -1) : text);\n\n/**\n * The IPv4 address `address` names, as a number: a dotted quad in its canonical form, or an IPv6 address that wraps\n * one (the mapped, compatible, translated, NAT64 and 6to4 forms). `undefined` for anything else.\n */\nexport function ipv4Of(address: string): number | undefined {\n const bare = bareOf(address);\n const v4 = parseIpv4(bare);\n if (v4 !== undefined) return v4;\n const v6 = parseIpv6(bare);\n return v6 === undefined ? undefined : wrappedIpv4(v6);\n}\n\n/** The IPv4 ranges that reach the host itself or its link: this network, loopback and link-local. */\nconst IPV4_LOCAL: readonly (readonly [number, number])[] = [\n [0x00000000, 8],\n [0x7f000000, 8],\n [0xa9fe0000, 16],\n];\n\n/** The IPv6 prefixes that reach the host itself or its link: unspecified, loopback and link-local. */\nconst IPV6_LOCAL: readonly (readonly [readonly number[], number])[] = [\n [[0, 0, 0, 0, 0, 0, 0, 0], 128],\n [[0, 0, 0, 0, 0, 0, 0, 1], 128],\n [[0xfe80], 10],\n];\n\n/**\n * Whether `address` reaches the host itself or its link: unspecified, loopback or link-local (which holds the cloud\n * metadata address 169.254.169.254), for IPv4 and IPv6, and an IPv6 address that wraps one of those IPv4 ones. Text\n * that isn't an address literal is not one.\n */\nexport function isLocalAddress(address: string): boolean {\n const v4 = ipv4Of(address);\n if (v4 !== undefined && inIpv4Ranges(v4, IPV4_LOCAL)) return true;\n const v6 = parseIpv6(bareOf(address));\n return v6 !== undefined && IPV6_LOCAL.some(([prefix, bits]) => inPrefix(v6, prefix, bits));\n}\n"]}
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type GitRouteFilter } from "./git-route.js";
|
|
1
2
|
/** A host the proxy may reach on one port. A `*.` name matches every name under it, and never the name itself. */
|
|
2
3
|
export interface AllowEntry {
|
|
3
4
|
readonly name: string;
|
|
@@ -16,6 +17,12 @@ export interface CredentialRoute {
|
|
|
16
17
|
readonly header: string;
|
|
17
18
|
/** The real secret, read at each request so a rotated key is used at once. It never enters the sandbox. */
|
|
18
19
|
readonly secret: () => Promise<string>;
|
|
20
|
+
/**
|
|
21
|
+
* Makes the route a git route: only git's smart HTTP requests for the listed repositories pass, a push only to the
|
|
22
|
+
* listed branches, and the secret goes in HTTP Basic as the password of `username`. Its `header` must be
|
|
23
|
+
* `authorization` and its `methods` `GET` and `POST`. The sandbox's git sends the route's sentinel as its password.
|
|
24
|
+
*/
|
|
25
|
+
readonly git?: GitRouteFilter;
|
|
19
26
|
}
|
|
20
27
|
/** A route with its host and port split, its method and header names normalised, and its sentinel. */
|
|
21
28
|
export interface ParsedRoute {
|
|
@@ -25,10 +32,23 @@ export interface ParsedRoute {
|
|
|
25
32
|
readonly methods: ReadonlySet<string>;
|
|
26
33
|
readonly header: string;
|
|
27
34
|
readonly secret: () => Promise<string>;
|
|
35
|
+
readonly git?: GitRouteFilter;
|
|
28
36
|
}
|
|
29
37
|
/** Parses the allowlist: each entry is `name`, `*.name`, with `:port` when it isn't 443. */
|
|
30
38
|
export declare function parseAllow(entries: readonly string[]): AllowEntry[];
|
|
31
39
|
/** Whether `host` on `port` is on the allowlist. `host` is lower case, without a trailing dot. */
|
|
32
40
|
export declare function isAllowed(allow: readonly AllowEntry[], host: string, port: number): boolean;
|
|
33
|
-
/**
|
|
34
|
-
|
|
41
|
+
/**
|
|
42
|
+
* The first git route that shares its host with a way around its filter, and what that way is: an allowlist entry, on
|
|
43
|
+
* any port, that lets a tunnel reach the host, or another route to the same host, which would carry a credential there
|
|
44
|
+
* without the git route's repository and ref checks. Hosts are compared in lower case without their ports.
|
|
45
|
+
*/
|
|
46
|
+
export declare function gitHostOverlap(routes: readonly Pick<CredentialRoute, "host" | "git">[], allow: readonly AllowEntry[]): {
|
|
47
|
+
readonly index: number;
|
|
48
|
+
readonly with: "allow" | "route";
|
|
49
|
+
} | undefined;
|
|
50
|
+
/**
|
|
51
|
+
* Parses and checks the routes against the parsed allowlist. It refuses two routes with one name, and a git route whose
|
|
52
|
+
* host is also on the allowlist or is another route's host, because either would go around its filter.
|
|
53
|
+
*/
|
|
54
|
+
export declare function parseRoutes(routes: readonly CredentialRoute[], allow: readonly AllowEntry[]): ParsedRoute[];
|