@buildanagent/harness 0.1.0-alpha.28 → 0.1.0-alpha.29
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 +111 -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/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 +9 -5
- package/dist/errors.js +8 -4
- 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/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 +6 -4
- package/dist/sandbox/index.js +5 -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/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 +34 -0
- package/package.json +5 -5
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `EgressPolicy`: what a sandbox may reach, as plain data that names its credentials but never holds them, so a
|
|
3
|
+
* backend can compile it, store it or send it to a hosted provider without carrying a secret. `compileEgressPolicy()`
|
|
4
|
+
* compiles it for the local proxy, `startEgressProxy()`. It is portable: it imports no Node module.
|
|
5
|
+
*/
|
|
6
|
+
import { HarnessError } from "../errors.js";
|
|
7
|
+
import { isAddressLiteral } from "./addresses.js";
|
|
8
|
+
import { gitHostOverlap, parseAllow, parseRoutes } from "./allowlist.js";
|
|
9
|
+
import { checkGitFilter } from "./git-route.js";
|
|
10
|
+
const CREDENTIAL_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
|
|
11
|
+
// Well-known credential formats, matched at the start of a value or of a token in it. Each prefix must be followed by a
|
|
12
|
+
// body as long as a real token's, so a token pasted where its name belongs is refused while an ordinary name that
|
|
13
|
+
// merely starts with such letters, such as sk-labs/app, sk-api.example.com or a route named sk-proxy, is not. An AWS
|
|
14
|
+
// key id is matched only as a whole token, because its prefix starts ordinary upper-case names too.
|
|
15
|
+
const CREDENTIAL_SHAPED = new RegExp([
|
|
16
|
+
"^gh[pousr]_[A-Za-z0-9]{30,}",
|
|
17
|
+
"^github_pat_[A-Za-z0-9_]{20,}",
|
|
18
|
+
"^xox[abposr]-[A-Za-z0-9-]{10,}",
|
|
19
|
+
"^sk-[A-Za-z0-9_-]{20,}",
|
|
20
|
+
"^sk_(live|test)_[A-Za-z0-9]{20,}",
|
|
21
|
+
"^glpat-[A-Za-z0-9_-]{20,}",
|
|
22
|
+
"^AIza[A-Za-z0-9_-]{30,}",
|
|
23
|
+
"^(AKIA|ASIA)[0-9A-Z]{16}$",
|
|
24
|
+
].join("|"));
|
|
25
|
+
const AUTH_SCHEME = /^(Bearer|Basic) /i;
|
|
26
|
+
// What separates a pasted token from the text around it: white space, and the punctuation of `key=value`, `user:pass`,
|
|
27
|
+
// `user@host`, lists and quotes. A repository's `/` and a host's `.` are not separators.
|
|
28
|
+
const TOKEN_SEPARATOR = /[\s=:@,;"'`]+/;
|
|
29
|
+
/** Whether `text` looks like a credential, or carries one in a token or after an auth scheme. */
|
|
30
|
+
const credentialShaped = (text) => AUTH_SCHEME.test(text) || text.split(TOKEN_SEPARATOR).some((token) => CREDENTIAL_SHAPED.test(token));
|
|
31
|
+
const HEADER_FIELDS = new Set(["kind", "route", "host", "methods", "header", "credential"]);
|
|
32
|
+
const GIT_FIELDS = new Set(["kind", "route", "host", "repositories", "pushRefs", "fetch", "username", "credential"]);
|
|
33
|
+
const DEFAULT_GIT_USERNAME = "x-access-token";
|
|
34
|
+
const invalid = (message) => new HarnessError("invalid_egress_options", message);
|
|
35
|
+
/** Every string anywhere in `value`, for the scan that refuses a credential-shaped one. */
|
|
36
|
+
function strings(value) {
|
|
37
|
+
if (typeof value === "string")
|
|
38
|
+
return [value];
|
|
39
|
+
if (Array.isArray(value))
|
|
40
|
+
return value.flatMap(strings);
|
|
41
|
+
if (typeof value === "object" && value !== null)
|
|
42
|
+
return Object.values(value).flatMap(strings);
|
|
43
|
+
return [];
|
|
44
|
+
}
|
|
45
|
+
/** Throws unless `entry` is an exact host name, with an optional port. The message names only its place. */
|
|
46
|
+
function checkHost(entry, where) {
|
|
47
|
+
const text = typeof entry === "string" ? entry : "";
|
|
48
|
+
const name = text.replace(/:[0-9]+$/, "");
|
|
49
|
+
if (text.includes("*") || name.startsWith("[") || isAddressLiteral(name)) {
|
|
50
|
+
throw invalid(`${where} must be an exact host name, not a wildcard or an address`);
|
|
51
|
+
}
|
|
52
|
+
try {
|
|
53
|
+
parseAllow([text]);
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
// The proxy's own message quotes the entry, which this one must not.
|
|
57
|
+
throw invalid(`${where} must be a host name, such as example.com`);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/** Throws unless `route` has only its kind's fields and names its credential. */
|
|
61
|
+
function checkRoute(route, index) {
|
|
62
|
+
if (typeof route !== "object" || route === null)
|
|
63
|
+
throw invalid(`route ${index} is not an object`);
|
|
64
|
+
const kind = route.kind;
|
|
65
|
+
const fields = kind === "header" ? HEADER_FIELDS : kind === "git" ? GIT_FIELDS : undefined;
|
|
66
|
+
if (fields === undefined)
|
|
67
|
+
throw invalid(`route ${index} must have the kind header or git`);
|
|
68
|
+
if (Object.keys(route).some((key) => !fields.has(key))) {
|
|
69
|
+
throw invalid(`route ${index} has a field an egress route doesn't have, such as a credential's value`);
|
|
70
|
+
}
|
|
71
|
+
const credential = route.credential;
|
|
72
|
+
if (typeof credential !== "string" || !CREDENTIAL_NAME.test(credential)) {
|
|
73
|
+
throw invalid(`route ${index} must name its credential in upper case, such as GITHUB_TOKEN, not hold it`);
|
|
74
|
+
}
|
|
75
|
+
checkHost(route.host, `the host of route ${index}`);
|
|
76
|
+
const { route: name, methods, pushRefs } = route;
|
|
77
|
+
const listed = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
|
|
78
|
+
if (typeof name !== "string" || (kind === "header" && !listed(methods))) {
|
|
79
|
+
throw invalid(`route ${index} needs a name and, for a header route, a list of methods`);
|
|
80
|
+
}
|
|
81
|
+
if (kind === "git" && pushRefs !== undefined && !listed(pushRefs))
|
|
82
|
+
throw invalid(`route ${index}'s pushRefs is not a list`);
|
|
83
|
+
}
|
|
84
|
+
/** The proxy's filter for a git route, with its defaults filled in. */
|
|
85
|
+
function gitFilter(route) {
|
|
86
|
+
return {
|
|
87
|
+
repositories: Array.isArray(route.repositories) ? [...route.repositories] : [],
|
|
88
|
+
pushRefs: [...(route.pushRefs ?? [])],
|
|
89
|
+
fetch: route.fetch ?? false,
|
|
90
|
+
username: route.username ?? DEFAULT_GIT_USERNAME,
|
|
91
|
+
};
|
|
92
|
+
}
|
|
93
|
+
/** The local proxy's route for one checked egress route. */
|
|
94
|
+
function toCredentialRoute(route, options) {
|
|
95
|
+
const secret = () => options.secret(route.credential);
|
|
96
|
+
if (route.kind === "header") {
|
|
97
|
+
return { route: route.route, host: route.host, methods: [...route.methods], header: route.header, secret };
|
|
98
|
+
}
|
|
99
|
+
return {
|
|
100
|
+
route: route.route,
|
|
101
|
+
host: route.host,
|
|
102
|
+
methods: ["GET", "POST"],
|
|
103
|
+
header: "authorization",
|
|
104
|
+
secret,
|
|
105
|
+
git: gitFilter(route),
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
/** Throws unless each git route's filter is usable and no tunnel or other route reaches its host. */
|
|
109
|
+
function checkGitRoutes(routes, allow) {
|
|
110
|
+
const overlap = gitHostOverlap(routes.map((route) => ({ host: route.host, ...(route.kind === "git" ? { git: gitFilter(route) } : {}) })), parseAllow(allow));
|
|
111
|
+
if (overlap?.with === "allow") {
|
|
112
|
+
throw invalid(`the host of git route ${overlap.index} is also in allow, so a tunnel could go around its ref filter`);
|
|
113
|
+
}
|
|
114
|
+
if (overlap?.with === "route") {
|
|
115
|
+
throw invalid(`the host of git route ${overlap.index} is another route's host, so that route could go around its ref filter`);
|
|
116
|
+
}
|
|
117
|
+
for (const [index, route] of routes.entries()) {
|
|
118
|
+
if (route.kind !== "git")
|
|
119
|
+
continue;
|
|
120
|
+
try {
|
|
121
|
+
checkGitFilter(gitFilter(route));
|
|
122
|
+
}
|
|
123
|
+
catch (error) {
|
|
124
|
+
// The filter's messages name a field and its place, never its value.
|
|
125
|
+
throw invalid(`git route ${index} is not usable: ${error.message}`);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Checks `policy` and compiles it for `startEgressProxy()`: pass the result's `allow` and `routes` with a `log`.
|
|
131
|
+
* Everything is refused that isn't plainly allowed, with `HarnessError` code `invalid_egress_options`, and the
|
|
132
|
+
* message names the entry's place, never its value:
|
|
133
|
+
*
|
|
134
|
+
* - a field a route kind doesn't have, such as `secret` or `token`, and a credential that is not an upper-case name;
|
|
135
|
+
* - any string in the policy that looks like a credential, such as one starting `ghp_` or `sk-`;
|
|
136
|
+
* - a wildcard or an address literal in `allow` or a route's host;
|
|
137
|
+
* - a git route whose host is also in `allow`, because a tunnel to it would go around the ref filter, and a git route
|
|
138
|
+
* whose host is another route's host, because that route would carry a credential there without the ref filter;
|
|
139
|
+
* - a git route with no repository, a push ref outside `refs/heads/`, or neither a push nor a fetch.
|
|
140
|
+
*
|
|
141
|
+
* The compiled routes read each credential through `options.secret` at every request, so a rotated one is used at once.
|
|
142
|
+
*/
|
|
143
|
+
export function compileEgressPolicy(policy, options) {
|
|
144
|
+
if (typeof options?.secret !== "function")
|
|
145
|
+
throw invalid("compileEgressPolicy needs a secret function");
|
|
146
|
+
const { allow, routes } = (policy ?? {});
|
|
147
|
+
if (!Array.isArray(allow) || !Array.isArray(routes))
|
|
148
|
+
throw invalid("an egress policy has an allow and a routes list");
|
|
149
|
+
if (Object.keys(policy).some((key) => key !== "allow" && key !== "routes")) {
|
|
150
|
+
throw invalid("an egress policy has only allow and routes");
|
|
151
|
+
}
|
|
152
|
+
if (strings(policy).some(credentialShaped)) {
|
|
153
|
+
throw invalid("the egress policy holds what looks like a credential; name it in a route's credential instead");
|
|
154
|
+
}
|
|
155
|
+
for (const [index, entry] of allow.entries())
|
|
156
|
+
checkHost(entry, `allow entry ${index}`);
|
|
157
|
+
for (const [index, route] of routes.entries())
|
|
158
|
+
checkRoute(route, index);
|
|
159
|
+
checkGitRoutes(routes, allow);
|
|
160
|
+
const compiled = routes.map((route) => toCredentialRoute(route, options));
|
|
161
|
+
try {
|
|
162
|
+
parseRoutes(compiled, parseAllow(allow));
|
|
163
|
+
}
|
|
164
|
+
catch {
|
|
165
|
+
// The proxy's own message quotes the route's name or header, which this one must not.
|
|
166
|
+
throw invalid("a route's name, methods or header is not usable, or two routes share a name");
|
|
167
|
+
}
|
|
168
|
+
return { allow: [...allow], routes: compiled };
|
|
169
|
+
}
|
|
170
|
+
//# sourceMappingURL=egress-policy.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"egress-policy.js","sourceRoot":"","sources":["../../src/credentials/egress-policy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `EgressPolicy`: what a sandbox may reach, as plain data that names its credentials but never holds them, so a\n * backend can compile it, store it or send it to a hosted provider without carrying a secret. `compileEgressPolicy()`\n * compiles it for the local proxy, `startEgressProxy()`. It is portable: it imports no Node module.\n */\nimport { HarnessError } from \"../errors.js\";\nimport { isAddressLiteral } from \"./addresses.js\";\nimport { type CredentialRoute, gitHostOverlap, parseAllow, parseRoutes } from \"./allowlist.js\";\nimport { checkGitFilter, type GitRouteFilter } from \"./git-route.js\";\n\n/** A route that swaps the sentinel in one request header for a credential, as `startEgressProxy()`'s routes do. */\nexport interface HeaderEgressRoute {\n readonly kind: \"header\";\n /** The first part of the path the sandbox requests, such as `github`. Lower case letters, digits, `-` and `_`. */\n readonly route: string;\n /** The HTTPS host the request is forwarded to, such as `api.github.com`, with `:port` when it isn't 443. */\n readonly host: string;\n /** The methods the route accepts, such as `[\"GET\"]`. */\n readonly methods: readonly string[];\n /** The request header that carries the credential, such as `authorization`. */\n readonly header: string;\n /** The name of the credential the host injects, in upper case, such as `GITHUB_TOKEN`. Never the credential. */\n readonly credential: string;\n}\n\n/**\n * A route for git over HTTPS: git's smart HTTP requests for the listed repositories only, and a push only to the listed\n * branches. A deletion and a tag are always refused, and so is anything the route can't parse.\n */\nexport interface GitEgressRoute {\n readonly kind: \"git\";\n /** The first part of the path the sandbox's git remote uses, such as `git`. */\n readonly route: string;\n /** The git host, such as `github.com`. */\n readonly host: string;\n /** The repositories the route reaches, as `owner/name`. */\n readonly repositories: readonly string[];\n /** The branches a push may create or update, such as `refs/heads/agent/*`. Leave it out to refuse every push. */\n readonly pushRefs?: readonly string[];\n /** Whether a fetch or clone may read the repositories. Defaults to `false`. */\n readonly fetch?: boolean;\n /** The user name sent with the credential in HTTP Basic. Defaults to `x-access-token`, which GitHub App tokens use. */\n readonly username?: string;\n /** The name of the credential the host injects, in upper case, such as `GITHUB_TOKEN`. Never the credential. */\n readonly credential: string;\n}\n\n/** One credential route of an `EgressPolicy`. */\nexport type EgressRoute = HeaderEgressRoute | GitEgressRoute;\n\n/** What a sandbox may reach: the hosts it may tunnel to, and the routes that add a credential on its behalf. */\nexport interface EgressPolicy {\n /** Exact host names, with `:port` when it isn't 443. A wildcard and an address literal are refused. */\n readonly allow: readonly string[];\n readonly routes: readonly EgressRoute[];\n}\n\n/** The options of `compileEgressPolicy()`. */\nexport interface CompileEgressOptions {\n /** Reads the credential a route names, at each request, on the host. It never runs in the sandbox. */\n readonly secret: (name: string) => Promise<string>;\n}\n\n/** A compiled policy: the `allow` and `routes` options of `startEgressProxy()`. */\nexport interface CompiledEgressPolicy {\n readonly allow: readonly string[];\n readonly routes: readonly CredentialRoute[];\n}\n\nconst CREDENTIAL_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;\n// Well-known credential formats, matched at the start of a value or of a token in it. Each prefix must be followed by a\n// body as long as a real token's, so a token pasted where its name belongs is refused while an ordinary name that\n// merely starts with such letters, such as sk-labs/app, sk-api.example.com or a route named sk-proxy, is not. An AWS\n// key id is matched only as a whole token, because its prefix starts ordinary upper-case names too.\nconst CREDENTIAL_SHAPED = new RegExp(\n [\n \"^gh[pousr]_[A-Za-z0-9]{30,}\",\n \"^github_pat_[A-Za-z0-9_]{20,}\",\n \"^xox[abposr]-[A-Za-z0-9-]{10,}\",\n \"^sk-[A-Za-z0-9_-]{20,}\",\n \"^sk_(live|test)_[A-Za-z0-9]{20,}\",\n \"^glpat-[A-Za-z0-9_-]{20,}\",\n \"^AIza[A-Za-z0-9_-]{30,}\",\n \"^(AKIA|ASIA)[0-9A-Z]{16}$\",\n ].join(\"|\"),\n);\nconst AUTH_SCHEME = /^(Bearer|Basic) /i;\n// What separates a pasted token from the text around it: white space, and the punctuation of `key=value`, `user:pass`,\n// `user@host`, lists and quotes. A repository's `/` and a host's `.` are not separators.\nconst TOKEN_SEPARATOR = /[\\s=:@,;\"'`]+/;\n\n/** Whether `text` looks like a credential, or carries one in a token or after an auth scheme. */\nconst credentialShaped = (text: string): boolean =>\n AUTH_SCHEME.test(text) || text.split(TOKEN_SEPARATOR).some((token) => CREDENTIAL_SHAPED.test(token));\nconst HEADER_FIELDS = new Set([\"kind\", \"route\", \"host\", \"methods\", \"header\", \"credential\"]);\nconst GIT_FIELDS = new Set([\"kind\", \"route\", \"host\", \"repositories\", \"pushRefs\", \"fetch\", \"username\", \"credential\"]);\nconst DEFAULT_GIT_USERNAME = \"x-access-token\";\n\nconst invalid = (message: string) => new HarnessError(\"invalid_egress_options\", message);\n\n/** Every string anywhere in `value`, for the scan that refuses a credential-shaped one. */\nfunction strings(value: unknown): string[] {\n if (typeof value === \"string\") return [value];\n if (Array.isArray(value)) return value.flatMap(strings);\n if (typeof value === \"object\" && value !== null) return Object.values(value).flatMap(strings);\n return [];\n}\n\n/** Throws unless `entry` is an exact host name, with an optional port. The message names only its place. */\nfunction checkHost(entry: unknown, where: string): void {\n const text = typeof entry === \"string\" ? entry : \"\";\n const name = text.replace(/:[0-9]+$/, \"\");\n if (text.includes(\"*\") || name.startsWith(\"[\") || isAddressLiteral(name)) {\n throw invalid(`${where} must be an exact host name, not a wildcard or an address`);\n }\n try {\n parseAllow([text]);\n } catch {\n // The proxy's own message quotes the entry, which this one must not.\n throw invalid(`${where} must be a host name, such as example.com`);\n }\n}\n\n/** Throws unless `route` has only its kind's fields and names its credential. */\nfunction checkRoute(route: unknown, index: number): asserts route is EgressRoute {\n if (typeof route !== \"object\" || route === null) throw invalid(`route ${index} is not an object`);\n const kind = (route as { kind?: unknown }).kind;\n const fields = kind === \"header\" ? HEADER_FIELDS : kind === \"git\" ? GIT_FIELDS : undefined;\n if (fields === undefined) throw invalid(`route ${index} must have the kind header or git`);\n if (Object.keys(route).some((key) => !fields.has(key))) {\n throw invalid(`route ${index} has a field an egress route doesn't have, such as a credential's value`);\n }\n const credential = (route as { credential?: unknown }).credential;\n if (typeof credential !== \"string\" || !CREDENTIAL_NAME.test(credential)) {\n throw invalid(`route ${index} must name its credential in upper case, such as GITHUB_TOKEN, not hold it`);\n }\n checkHost((route as { host?: unknown }).host, `the host of route ${index}`);\n const { route: name, methods, pushRefs } = route as { route?: unknown; methods?: unknown; pushRefs?: unknown };\n const listed = (value: unknown) => Array.isArray(value) && value.every((item) => typeof item === \"string\");\n if (typeof name !== \"string\" || (kind === \"header\" && !listed(methods))) {\n throw invalid(`route ${index} needs a name and, for a header route, a list of methods`);\n }\n if (kind === \"git\" && pushRefs !== undefined && !listed(pushRefs))\n throw invalid(`route ${index}'s pushRefs is not a list`);\n}\n\n/** The proxy's filter for a git route, with its defaults filled in. */\nfunction gitFilter(route: GitEgressRoute): GitRouteFilter {\n return {\n repositories: Array.isArray(route.repositories) ? [...route.repositories] : [],\n pushRefs: [...(route.pushRefs ?? [])],\n fetch: route.fetch ?? false,\n username: route.username ?? DEFAULT_GIT_USERNAME,\n };\n}\n\n/** The local proxy's route for one checked egress route. */\nfunction toCredentialRoute(route: EgressRoute, options: CompileEgressOptions): CredentialRoute {\n const secret = () => options.secret(route.credential);\n if (route.kind === \"header\") {\n return { route: route.route, host: route.host, methods: [...route.methods], header: route.header, secret };\n }\n return {\n route: route.route,\n host: route.host,\n methods: [\"GET\", \"POST\"],\n header: \"authorization\",\n secret,\n git: gitFilter(route),\n };\n}\n\n/** Throws unless each git route's filter is usable and no tunnel or other route reaches its host. */\nfunction checkGitRoutes(routes: readonly EgressRoute[], allow: readonly string[]): void {\n const overlap = gitHostOverlap(\n routes.map((route) => ({ host: route.host, ...(route.kind === \"git\" ? { git: gitFilter(route) } : {}) })),\n parseAllow(allow),\n );\n if (overlap?.with === \"allow\") {\n throw invalid(\n `the host of git route ${overlap.index} is also in allow, so a tunnel could go around its ref filter`,\n );\n }\n if (overlap?.with === \"route\") {\n throw invalid(\n `the host of git route ${overlap.index} is another route's host, so that route could go around its ref filter`,\n );\n }\n for (const [index, route] of routes.entries()) {\n if (route.kind !== \"git\") continue;\n try {\n checkGitFilter(gitFilter(route));\n } catch (error) {\n // The filter's messages name a field and its place, never its value.\n throw invalid(`git route ${index} is not usable: ${(error as Error).message}`);\n }\n }\n}\n\n/**\n * Checks `policy` and compiles it for `startEgressProxy()`: pass the result's `allow` and `routes` with a `log`.\n * Everything is refused that isn't plainly allowed, with `HarnessError` code `invalid_egress_options`, and the\n * message names the entry's place, never its value:\n *\n * - a field a route kind doesn't have, such as `secret` or `token`, and a credential that is not an upper-case name;\n * - any string in the policy that looks like a credential, such as one starting `ghp_` or `sk-`;\n * - a wildcard or an address literal in `allow` or a route's host;\n * - a git route whose host is also in `allow`, because a tunnel to it would go around the ref filter, and a git route\n * whose host is another route's host, because that route would carry a credential there without the ref filter;\n * - a git route with no repository, a push ref outside `refs/heads/`, or neither a push nor a fetch.\n *\n * The compiled routes read each credential through `options.secret` at every request, so a rotated one is used at once.\n */\nexport function compileEgressPolicy(policy: EgressPolicy, options: CompileEgressOptions): CompiledEgressPolicy {\n if (typeof options?.secret !== \"function\") throw invalid(\"compileEgressPolicy needs a secret function\");\n const { allow, routes } = (policy ?? {}) as Partial<EgressPolicy>;\n if (!Array.isArray(allow) || !Array.isArray(routes)) throw invalid(\"an egress policy has an allow and a routes list\");\n if (Object.keys(policy).some((key) => key !== \"allow\" && key !== \"routes\")) {\n throw invalid(\"an egress policy has only allow and routes\");\n }\n if (strings(policy).some(credentialShaped)) {\n throw invalid(\"the egress policy holds what looks like a credential; name it in a route's credential instead\");\n }\n for (const [index, entry] of allow.entries()) checkHost(entry, `allow entry ${index}`);\n for (const [index, route] of routes.entries()) checkRoute(route, index);\n checkGitRoutes(routes, allow);\n const compiled = routes.map((route) => toCredentialRoute(route, options));\n try {\n parseRoutes(compiled, parseAllow(allow));\n } catch {\n // The proxy's own message quotes the route's name or header, which this one must not.\n throw invalid(\"a route's name, methods or header is not usable, or two routes share a name\");\n }\n return { allow: [...allow], routes: compiled };\n}\n"]}
|
|
@@ -38,8 +38,20 @@ export interface EgressProxyOptions {
|
|
|
38
38
|
* for a real run: the check is what keeps a name that points at the host's own network from being reached.
|
|
39
39
|
*/
|
|
40
40
|
readonly unsafeAllowAddresses?: readonly string[];
|
|
41
|
-
/**
|
|
41
|
+
/**
|
|
42
|
+
* Ends a tunnel, a forwarded request or a push check that is idle this long. A whole number of milliseconds from 0 to
|
|
43
|
+
* 2,147,483,647, where 0 turns the idle timeout off, as it does for a socket; anything else throws
|
|
44
|
+
* `invalid_egress_options` when the proxy starts. Defaults to 120000.
|
|
45
|
+
*/
|
|
42
46
|
readonly idleTimeoutMs?: number;
|
|
47
|
+
/**
|
|
48
|
+
* The longest a push's command list may take to arrive, from the start of its body, however often bytes come. The
|
|
49
|
+
* clock starts once and is never reset, so a client that sends a byte just inside the idle timeout is still cut off;
|
|
50
|
+
* a push that takes longer is refused with `git_timeout`. Only the command list is timed, not the pack after it. A
|
|
51
|
+
* whole number of milliseconds from 1 to 2,147,483,647; anything else throws `invalid_egress_options` when the proxy
|
|
52
|
+
* starts. Defaults to 60000.
|
|
53
|
+
*/
|
|
54
|
+
readonly pushCheckTimeoutMs?: number;
|
|
43
55
|
}
|
|
44
56
|
/** A running egress proxy. */
|
|
45
57
|
export interface EgressProxy {
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
import { HarnessError } from "../errors.js";
|
|
10
10
|
import { isAddressLiteral, isPublicAddress } from "./addresses.js";
|
|
11
11
|
import { isAllowed, parseAllow, parseRoutes, } from "./allowlist.js";
|
|
12
|
+
import { basicCarries, basicHeader, gitEndpoint, PushReader, pushVerdict } from "./git-route.js";
|
|
12
13
|
function nodeModules() {
|
|
13
14
|
if (typeof process === "undefined" || typeof process.getBuiltinModule !== "function") {
|
|
14
15
|
throw new HarnessError("invalid_egress_options", "the egress proxy needs Node's network modules, which this runtime lacks");
|
|
@@ -36,6 +37,12 @@ const HOP_BY_HOP = new Set([
|
|
|
36
37
|
"host",
|
|
37
38
|
]);
|
|
38
39
|
const DEFAULT_IDLE_MS = 120_000;
|
|
40
|
+
const DEFAULT_PUSH_CHECK_MS = 60_000;
|
|
41
|
+
// How much of a refused request's unread body is discarded, and for how long, before its connection is closed.
|
|
42
|
+
const LINGER_BYTES = 1024 * 1024;
|
|
43
|
+
const LINGER_MS = 1000;
|
|
44
|
+
// The longest delay a timer takes; past it, `setTimeout` fires at once.
|
|
45
|
+
const MAX_TIMER_MS = 2_147_483_647;
|
|
39
46
|
// What Node refuses in a header value: anything but tab, printable ASCII and the Latin-1 range. A secret with a line break
|
|
40
47
|
// or another control character would split or break the request, so it is refused before it is sent.
|
|
41
48
|
const INVALID_HEADER_VALUE = /[^\t\x20-\x7e\x80-\xff]/;
|
|
@@ -47,6 +54,27 @@ const refusal = (status, reason) => ({
|
|
|
47
54
|
body: undefined,
|
|
48
55
|
reason,
|
|
49
56
|
});
|
|
57
|
+
/**
|
|
58
|
+
* The answer to a git request whose credential is missing or wrong, or `undefined` when its HTTP Basic password is the
|
|
59
|
+
* route's sentinel. A missing one gets 401 with a Basic challenge, so git asks its credential helper.
|
|
60
|
+
*/
|
|
61
|
+
function gitCredentialRefusal(presented, sentinel) {
|
|
62
|
+
if (presented === undefined) {
|
|
63
|
+
return { ...refusal(401, "git_credential_missing"), headers: { "www-authenticate": 'Basic realm="egress"' } };
|
|
64
|
+
}
|
|
65
|
+
return typeof presented === "string" && basicCarries(presented, sentinel) ? undefined : refusal(403, "bad_sentinel");
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Checks a timeout option and returns the value to use: `fallback` when it is unset, or a whole number of milliseconds
|
|
69
|
+
* from `min` to the longest delay a timer takes. The message names the option and never quotes the value.
|
|
70
|
+
*/
|
|
71
|
+
function timeoutOption(name, ms, min, fallback) {
|
|
72
|
+
if (ms === undefined)
|
|
73
|
+
return fallback;
|
|
74
|
+
if (typeof ms === "number" && Number.isInteger(ms) && ms >= min && ms <= MAX_TIMER_MS)
|
|
75
|
+
return ms;
|
|
76
|
+
throw new HarnessError("invalid_egress_options", `${name} must be a whole number of milliseconds from ${min} to ${MAX_TIMER_MS}`);
|
|
77
|
+
}
|
|
50
78
|
class EgressGate {
|
|
51
79
|
modules;
|
|
52
80
|
allow;
|
|
@@ -56,12 +84,17 @@ class EgressGate {
|
|
|
56
84
|
unsafe;
|
|
57
85
|
sockets = new Set();
|
|
58
86
|
requests = new Set();
|
|
87
|
+
pushCheckMs;
|
|
88
|
+
// 0 means no idle timeout, as it does for `socket.setTimeout`.
|
|
89
|
+
idleMs;
|
|
59
90
|
origin = "";
|
|
60
91
|
constructor(modules, options) {
|
|
61
92
|
this.modules = modules;
|
|
62
93
|
this.options = options;
|
|
94
|
+
this.idleMs = timeoutOption("idleTimeoutMs", options.idleTimeoutMs, 0, DEFAULT_IDLE_MS);
|
|
95
|
+
this.pushCheckMs = timeoutOption("pushCheckTimeoutMs", options.pushCheckTimeoutMs, 1, DEFAULT_PUSH_CHECK_MS);
|
|
63
96
|
this.allow = parseAllow(options.allow);
|
|
64
|
-
this.routes = new Map(parseRoutes(options.routes ?? []).map((route) => [route.route, route]));
|
|
97
|
+
this.routes = new Map(parseRoutes(options.routes ?? [], this.allow).map((route) => [route.route, route]));
|
|
65
98
|
this.unsafe = new Set(options.unsafeAllowAddresses ?? []);
|
|
66
99
|
for (const route of this.routes.keys()) {
|
|
67
100
|
this.sentinels[route] = `sentinel_${modules.crypto.randomBytes(18).toString("base64url")}`;
|
|
@@ -143,7 +176,7 @@ class EgressGate {
|
|
|
143
176
|
this.track(upstream);
|
|
144
177
|
// A client that leaves before the tunnel is up takes the connection attempt with it.
|
|
145
178
|
client.once("close", () => upstream.destroy());
|
|
146
|
-
upstream.setTimeout(this.
|
|
179
|
+
upstream.setTimeout(this.idleMs, () => upstream.destroy(Object.assign(new Error("idle"), { code: "ETIMEDOUT" })));
|
|
147
180
|
upstream.once("error", (error) => {
|
|
148
181
|
if (established)
|
|
149
182
|
client.destroy();
|
|
@@ -208,10 +241,9 @@ class EgressGate {
|
|
|
208
241
|
method: request.method ?? "GET",
|
|
209
242
|
route: undefined,
|
|
210
243
|
};
|
|
211
|
-
this.routeRequest(request.method ?? "GET", url, request.headers, request, gone.signal).then((reply) => this.finish(response, reply.reply, reply.base), () => this.finish(response, refusal(502, "request_failed"), base));
|
|
244
|
+
this.routeRequest(request.method ?? "GET", url, request.headers, request, gone.signal).then((reply) => this.finish(response, reply.reply, reply.base, request), () => this.finish(response, refusal(502, "request_failed"), base, request));
|
|
212
245
|
}
|
|
213
|
-
finish(response, reply, base) {
|
|
214
|
-
response.writeHead(reply.status, reply.headers);
|
|
246
|
+
finish(response, reply, base, request) {
|
|
215
247
|
let bytes = 0;
|
|
216
248
|
const report = () => this.record({
|
|
217
249
|
...base,
|
|
@@ -219,6 +251,12 @@ class EgressGate {
|
|
|
219
251
|
bytes,
|
|
220
252
|
...(reply.reason === undefined ? {} : { reason: reply.reason }),
|
|
221
253
|
});
|
|
254
|
+
if (reply.body === undefined && reply.status >= 400 && request !== undefined && !request.complete) {
|
|
255
|
+
this.refuseAndClose(request, response, reply);
|
|
256
|
+
report();
|
|
257
|
+
return;
|
|
258
|
+
}
|
|
259
|
+
response.writeHead(reply.status, reply.headers);
|
|
222
260
|
if (reply.body === undefined) {
|
|
223
261
|
response.end(reply.status === 403 || reply.status >= 400 ? `${reply.reason ?? "refused"}\n` : undefined);
|
|
224
262
|
report();
|
|
@@ -232,6 +270,37 @@ class EgressGate {
|
|
|
232
270
|
response.once("close", () => reply.body?.destroy());
|
|
233
271
|
reply.body.pipe(response);
|
|
234
272
|
}
|
|
273
|
+
/**
|
|
274
|
+
* Refuses a request whose body has not been read to its end, and closes its connection. Node would otherwise read and
|
|
275
|
+
* discard the rest of the body, a whole pack perhaps, to keep the connection alive. The answer is written whole, with
|
|
276
|
+
* its length and `Connection: close`, and the response is ended, which closes the socket, only after the bytes already
|
|
277
|
+
* on their way are discarded, up to `LINGER_BYTES` or for `LINGER_MS`. Closing a socket with unread bytes resets the
|
|
278
|
+
* connection, and a client that has not yet read the answer would lose it.
|
|
279
|
+
*/
|
|
280
|
+
refuseAndClose(request, response, reply) {
|
|
281
|
+
const text = `${reply.reason ?? "refused"}\n`;
|
|
282
|
+
response.writeHead(reply.status, { ...reply.headers, connection: "close", "content-length": String(text.length) });
|
|
283
|
+
response.write(text);
|
|
284
|
+
let discarded = 0;
|
|
285
|
+
const done = () => {
|
|
286
|
+
clearTimeout(timer);
|
|
287
|
+
request.off("data", onData);
|
|
288
|
+
request.off("end", done);
|
|
289
|
+
request.off("close", done);
|
|
290
|
+
request.pause();
|
|
291
|
+
response.end();
|
|
292
|
+
};
|
|
293
|
+
const onData = (chunk) => {
|
|
294
|
+
discarded += chunk.length;
|
|
295
|
+
if (discarded >= LINGER_BYTES)
|
|
296
|
+
done();
|
|
297
|
+
};
|
|
298
|
+
const timer = setTimeout(done, LINGER_MS);
|
|
299
|
+
request.on("data", onData);
|
|
300
|
+
request.once("end", done);
|
|
301
|
+
request.once("close", done);
|
|
302
|
+
request.resume();
|
|
303
|
+
}
|
|
235
304
|
/**
|
|
236
305
|
* Resolves a request for `/<route>/…`. It checks the route, the method and the sentinel, swaps in the secret, and
|
|
237
306
|
* forwards the request to the route's host. A request that fails any check is answered here, and nothing is sent.
|
|
@@ -250,17 +319,116 @@ class EgressGate {
|
|
|
250
319
|
return { reply: refusal(403, "unknown_route"), base };
|
|
251
320
|
if (!route.methods.has(method.toUpperCase()))
|
|
252
321
|
return { reply: refusal(405, "method_not_allowed"), base };
|
|
322
|
+
const target = { path: match[2] ?? "/", query: match[3] ?? "" };
|
|
323
|
+
const reply = route.git === undefined
|
|
324
|
+
? await this.headerRequest(route, method, target, headers, body, signal)
|
|
325
|
+
: await this.gitRequest(route, route.git, method, target, headers, body, signal);
|
|
326
|
+
return { reply, base };
|
|
327
|
+
}
|
|
328
|
+
/** Resolves a request on a header route: it swaps the sentinel in the route's header for the secret. */
|
|
329
|
+
async headerRequest(route, method, target, headers, body, signal) {
|
|
253
330
|
const presented = headers[route.header];
|
|
254
331
|
const sentinel = this.sentinels[route.route] ?? "";
|
|
255
332
|
if (typeof presented !== "string" || sentinel === "" || !presented.includes(sentinel)) {
|
|
256
|
-
return
|
|
333
|
+
return refusal(403, "bad_sentinel");
|
|
257
334
|
}
|
|
258
335
|
const secret = await route.secret().catch(() => "");
|
|
259
336
|
if (secret === "" || INVALID_HEADER_VALUE.test(secret))
|
|
260
|
-
return
|
|
337
|
+
return refusal(502, "secret_unavailable");
|
|
261
338
|
const outgoing = this.outgoingHeaders(headers, route, presented.replaceAll(sentinel, () => secret));
|
|
262
|
-
|
|
263
|
-
|
|
339
|
+
return this.forward(route, method, `${target.path}${target.query}`, outgoing, body, signal);
|
|
340
|
+
}
|
|
341
|
+
/**
|
|
342
|
+
* Resolves a request on a git route. The endpoint and repository are checked first, then the sentinel in HTTP Basic,
|
|
343
|
+
* then a push's command list, and only then is the secret read and the request forwarded with it. A missing
|
|
344
|
+
* credential gets 401 with a Basic challenge, so git asks its credential helper for the sentinel.
|
|
345
|
+
*/
|
|
346
|
+
async gitRequest(route, filter, method, target, headers, body, signal) {
|
|
347
|
+
const endpoint = gitEndpoint(filter, method, target.path, target.query);
|
|
348
|
+
if ("refused" in endpoint)
|
|
349
|
+
return refusal(403, endpoint.refused);
|
|
350
|
+
const unauthorized = gitCredentialRefusal(headers.authorization, this.sentinels[route.route] ?? "");
|
|
351
|
+
if (unauthorized !== undefined)
|
|
352
|
+
return unauthorized;
|
|
353
|
+
let forwarded = body;
|
|
354
|
+
if (endpoint.service === "git-receive-pack" && endpoint.phase === "rpc") {
|
|
355
|
+
const encoding = headers["content-encoding"];
|
|
356
|
+
if (encoding !== undefined && encoding !== "identity")
|
|
357
|
+
return refusal(403, "git_encoded_push");
|
|
358
|
+
const checked = await this.checkPush(body, filter);
|
|
359
|
+
if ("refused" in checked)
|
|
360
|
+
return refusal(403, checked.refused);
|
|
361
|
+
forwarded = checked.body;
|
|
362
|
+
}
|
|
363
|
+
const secret = await route.secret().catch(() => "");
|
|
364
|
+
if (secret === "" || INVALID_HEADER_VALUE.test(secret))
|
|
365
|
+
return refusal(502, "secret_unavailable");
|
|
366
|
+
const outgoing = this.outgoingHeaders(headers, route, basicHeader(filter.username, secret));
|
|
367
|
+
return this.forward(route, method, `${target.path}${target.query}`, outgoing, forwarded, signal);
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* Reads a push's command list and checks it, then hands back a body that starts with what was read. `PushReader`
|
|
371
|
+
* reads each chunk once, so the check is linear in the bytes however small the chunks. The check gives up once the
|
|
372
|
+
* body is idle for the idle timeout, which each chunk resets, or once `pushCheckTimeoutMs` has passed since it
|
|
373
|
+
* started, which nothing resets.
|
|
374
|
+
*/
|
|
375
|
+
checkPush(body, filter) {
|
|
376
|
+
if (body === undefined)
|
|
377
|
+
return Promise.resolve({ refused: "git_bad_pkt_line" });
|
|
378
|
+
if (body instanceof Uint8Array) {
|
|
379
|
+
const verdict = pushVerdict(body, filter, true);
|
|
380
|
+
return Promise.resolve(verdict === "allowed" ? { body } : { refused: verdict.refused });
|
|
381
|
+
}
|
|
382
|
+
return new Promise((resolve) => {
|
|
383
|
+
const reader = new PushReader(filter);
|
|
384
|
+
const chunks = [];
|
|
385
|
+
const timedOut = () => settle({ refused: "git_timeout" });
|
|
386
|
+
// An idle timeout of 0 is off, so only the deadline ends a quiet body.
|
|
387
|
+
const startIdle = () => (this.idleMs === 0 ? undefined : setTimeout(timedOut, this.idleMs));
|
|
388
|
+
let idle = startIdle();
|
|
389
|
+
const deadline = setTimeout(timedOut, this.pushCheckMs);
|
|
390
|
+
const settle = (outcome) => {
|
|
391
|
+
clearTimeout(idle);
|
|
392
|
+
clearTimeout(deadline);
|
|
393
|
+
body.off("data", onData);
|
|
394
|
+
body.off("end", onEnd);
|
|
395
|
+
body.off("error", onError);
|
|
396
|
+
body.off("close", onError);
|
|
397
|
+
// A refused body is not read further; the answer closes its connection.
|
|
398
|
+
if ("refused" in outcome)
|
|
399
|
+
body.pause();
|
|
400
|
+
resolve(outcome);
|
|
401
|
+
};
|
|
402
|
+
const judge = (verdict, ended) => {
|
|
403
|
+
if (verdict === "incomplete")
|
|
404
|
+
return;
|
|
405
|
+
if (verdict !== "allowed") {
|
|
406
|
+
settle(verdict);
|
|
407
|
+
return;
|
|
408
|
+
}
|
|
409
|
+
const rest = new this.modules.stream.PassThrough();
|
|
410
|
+
for (const chunk of chunks)
|
|
411
|
+
rest.write(chunk);
|
|
412
|
+
settle({ body: rest });
|
|
413
|
+
if (ended)
|
|
414
|
+
rest.end();
|
|
415
|
+
else
|
|
416
|
+
body.pipe(rest);
|
|
417
|
+
};
|
|
418
|
+
const onData = (chunk) => {
|
|
419
|
+
clearTimeout(idle);
|
|
420
|
+
idle = startIdle();
|
|
421
|
+
chunks.push(chunk);
|
|
422
|
+
judge(reader.add(chunk), false);
|
|
423
|
+
};
|
|
424
|
+
const onEnd = () => judge(reader.end(), true);
|
|
425
|
+
const onError = () => settle({ refused: "request_failed" });
|
|
426
|
+
body.on("data", onData);
|
|
427
|
+
body.once("end", onEnd);
|
|
428
|
+
body.once("error", onError);
|
|
429
|
+
// A client that goes away before its command list ends would otherwise hold the check until a timeout.
|
|
430
|
+
body.once("close", onError);
|
|
431
|
+
});
|
|
264
432
|
}
|
|
265
433
|
outgoingHeaders(headers, route, credential) {
|
|
266
434
|
const out = {};
|
|
@@ -289,7 +457,7 @@ class EgressGate {
|
|
|
289
457
|
signal?.addEventListener("abort", stop, { once: true });
|
|
290
458
|
upstream.once("close", () => signal?.removeEventListener("abort", stop));
|
|
291
459
|
this.requests.add(upstream);
|
|
292
|
-
upstream.setTimeout(this.
|
|
460
|
+
upstream.setTimeout(this.idleMs, () => upstream.destroy(new Error("idle")));
|
|
293
461
|
upstream.once("close", () => this.requests.delete(upstream));
|
|
294
462
|
upstream.once("response", (reply) => {
|
|
295
463
|
const passed = {};
|
|
@@ -394,7 +562,7 @@ class EgressGate {
|
|
|
394
562
|
this.requests.delete(upstream);
|
|
395
563
|
request.signal.removeEventListener("abort", abort);
|
|
396
564
|
});
|
|
397
|
-
upstream.setTimeout(this.
|
|
565
|
+
upstream.setTimeout(this.idleMs, () => upstream.destroy(new Error("idle")));
|
|
398
566
|
upstream.once("response", (reply) => {
|
|
399
567
|
let bytes = 0;
|
|
400
568
|
reply.on("data", (chunk) => {
|