@capybara-hq/device 0.1.0-rc.3 → 0.1.0-rc.4

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/dist/policy.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { SandboxLimits, SandboxRoots } from "@capybara-hq/plugin-sdk";
1
+ import { type DeviceExecGrants, type SandboxLimits, type SandboxRoots, type SandboxTier } from "@capybara-hq/plugin-sdk";
2
2
  import type { Policy } from "./state.js";
3
3
  /**
4
4
  * Paths no command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
@@ -14,11 +14,76 @@ export declare function deniedSecretPaths(home?: string): string[];
14
14
  * convenience directories). They lie outside the device directory, so they are denied.
15
15
  */
16
16
  export declare function implicitWritePaths(home?: string): string[];
17
+ /** True when the allowlist entry `pattern` admits every host `host` names (`host` may be a wildcard). */
18
+ export declare function covers(pattern: string, host: string): boolean;
17
19
  /**
18
- * The domains one command may reach: what the device's egress allows, cut to the local
19
- * policy. The cloud can only narrow it: an empty policy allows nothing, whatever the egress.
20
+ * The entry {@link effectiveEgress} returns when a command may reach any public host (the device
21
+ * is `open` and so is the org). sandbox-runtime 0.0.81 matches `*` as any host but refuses it in a
22
+ * per-command list, so the OS executor never registers it: its ask callback allows instead.
20
23
  */
21
- export declare function effectiveEgress(policy: Pick<Policy, "allowedDomains">, limits: Pick<SandboxLimits, "egress" | "allowHosts">): string[];
24
+ export declare const ANY_HOST = "*";
25
+ /** The tier fields of an exec's limits: the org's ceiling and its default. */
26
+ export type TierLimits = Pick<SandboxLimits, "tier" | "defaultTier">;
27
+ /**
28
+ * The tier this device runs a command at (spec §4.4): the owner's choice, or the org's default
29
+ * when there is none (`strict` when the kernel sent no default either), cut to the ceiling the
30
+ * kernel sends in `limits.tier`.
31
+ */
32
+ export declare function deviceTier(policy: Pick<Policy, "tier">, limits: TierLimits): SandboxTier;
33
+ /**
34
+ * The tier before any exec was seen (no ceiling known yet): the owner's choice, else `dev`, the
35
+ * default of every org unless changed. Used for the sandbox's first configuration only; the next
36
+ * command applies its own limits.
37
+ */
38
+ export declare function provisionalTier(policy: Pick<Policy, "tier">): SandboxTier;
39
+ /** What a tier really gives on this machine (the device page and `policy show`). */
40
+ export interface TierFacts {
41
+ effectiveTier: SandboxTier;
42
+ /** Whether sandboxed commands may listen on and reach localhost. */
43
+ localhost: "on" | "off-proxy-detected" | "off";
44
+ /** Unix sockets: within the device's directories, every socket with the host's masked, none. */
45
+ unixSockets: "roots" | "all-masked" | "off";
46
+ }
47
+ /**
48
+ * The facts of the device's tier (spec §5.2.3, §7.3). `limits` undefined means no exec was seen
49
+ * yet: the owner's choice, else `dev`, uncapped. `isolation: none` is reported separately (these
50
+ * describe the sandboxed tier).
51
+ *
52
+ * - Docker mode: the container has its own loopback and sockets in every tier.
53
+ * - OS mode, Linux: the sandbox has its own network namespace, so its loopback always works (not
54
+ * reachable from the host); unix sockets stay blocked (srt cannot limit them by path there).
55
+ * - OS mode, macOS: `strict` has neither; `dev` / `open` get unix sockets under the device's
56
+ * directories and localhost unless a local forwarding proxy was detected and the owner did not
57
+ * set `localhost: allow`.
58
+ */
59
+ export declare function tierFacts(policy: Policy, limits: TierLimits | undefined, opts: {
60
+ platform?: NodeJS.Platform;
61
+ proxyDetected: boolean;
62
+ mode: "os" | "docker";
63
+ }): TierFacts;
64
+ type Limits = Pick<SandboxLimits, "egress" | "allowHosts">;
65
+ /**
66
+ * The granted hosts that apply to one command: none unless the local `remoteGrants` is `owner`;
67
+ * only valid exact hosts (no wildcards, addresses or internal names), lowercased and deduped; and
68
+ * only those the org's egress admits (any host when it is `open`, none when it is `none`).
69
+ */
70
+ export declare function grantedHosts(policy: Pick<Policy, "remoteGrants">, limits: Limits, grants: Pick<DeviceExecGrants, "hosts"> | undefined): string[];
71
+ /** The limits {@link effectiveEgress} reads: the ceiling's network and tiers, and the dev hosts. */
72
+ export type EgressLimits = Pick<SandboxLimits, "egress" | "allowHosts" | "tier" | "defaultTier" | "devHosts">;
73
+ /**
74
+ * The hosts the device itself admits at `tier` (before the ceiling): its `allowedDomains`, plus
75
+ * the dev hosts in `dev`. Undefined for `open`: the device admits every host.
76
+ */
77
+ export declare function deviceHosts(policy: Pick<Policy, "allowedDomains">, tier: SandboxTier, devHosts: readonly string[]): string[] | undefined;
78
+ /**
79
+ * The domains one command may reach (spec §4.2), with `t` = {@link deviceTier} and the ceiling's
80
+ * hosts (`limits.allowHosts`, or any host when `limits.egress` is `open`):
81
+ * - `strict`: ceiling ∩ `allowedDomains` (an empty list allows nothing but the grants);
82
+ * - `dev`: ceiling ∩ (`allowedDomains` ∪ `limits.devHosts`);
83
+ * - `open`: the ceiling itself ({@link ANY_HOST} when it is `open`);
84
+ * plus the command's grants ({@link grantedHosts}). The cloud can only narrow the local policy.
85
+ */
86
+ export declare function effectiveEgress(policy: Pick<Policy, "allowedDomains" | "tier" | "remoteGrants">, limits: EgressLimits, grants?: Pick<DeviceExecGrants, "hosts">): string[];
22
87
  /** The sandbox-runtime configuration of one device. */
23
88
  export interface SrtConfig {
24
89
  filesystem: {
@@ -29,14 +94,40 @@ export interface SrtConfig {
29
94
  network: {
30
95
  allowedDomains: string[];
31
96
  deniedDomains: string[];
97
+ /** macOS: bind and accept on local ports, connect to any port on localhost. */
98
+ allowLocalBinding: boolean;
99
+ /** macOS only: the paths under which unix sockets may be bound and connected to. */
100
+ allowUnixSockets?: string[];
32
101
  };
33
102
  }
34
- /**
35
- * The sandbox-runtime configuration: writes only under the workspace and tmp roots (the runtime's
36
- * implicit write paths denied), skills read only, the secret paths (plus `opts.denyRead`, such as this program's own state directory)
37
- * unreadable, and network limited to `egress`.
38
- */
39
- export declare function srtConfig(_policy: Policy, roots: SandboxRoots, egress: string[], opts?: {
103
+ /** What {@link srtConfig} needs besides the policy and the roots. */
104
+ export interface SrtConfigOptions {
105
+ /** The tier the commands run at (default `strict`). */
106
+ tier?: SandboxTier;
107
+ /** The home whose secret paths are denied (default: the user's home). */
40
108
  home?: string;
109
+ /** More paths commands may not read (this program's state directory). */
41
110
  denyRead?: string[];
42
- }): SrtConfig;
111
+ platform?: NodeJS.Platform;
112
+ /** The proxy guard found a local forwarding proxy (macOS `dev` / `open` then skip localhost). */
113
+ proxyDetected?: boolean;
114
+ /** macOS: the short socket directory (`TMPDIR` in `dev` / `open`). */
115
+ socketDir?: string;
116
+ /** The device's package caches (`<dir>/cache`), writable in `dev` / `open`. */
117
+ cacheDir?: string;
118
+ }
119
+ /**
120
+ * The sandbox-runtime configuration (spec §5.1, §5.2.3): writes only under the workspace and tmp
121
+ * roots (the runtime's implicit write paths denied), skills read only, the secret paths (plus
122
+ * `opts.denyRead`, such as this program's own state directory) unreadable, and network limited to
123
+ * `egress`.
124
+ *
125
+ * `strict` stops there: no local binding, no unix sockets. `dev` and `open` also write the
126
+ * package caches and (macOS) the short socket directory; on macOS they may listen on and reach
127
+ * localhost unless the proxy guard found a local forwarding proxy (`localhost: allow` overrides)
128
+ * and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
129
+ * sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
130
+ * sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
131
+ */
132
+ export declare function srtConfig(policy: Policy, roots: SandboxRoots, egress: string[], opts?: SrtConfigOptions): SrtConfig;
133
+ export {};
package/dist/policy.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { homedir } from "node:os";
2
2
  import { join } from "node:path";
3
+ import { minTier, validateAllowHost, } from "@capybara-hq/plugin-sdk";
3
4
  /**
4
5
  * Paths no command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
5
6
  * credentials, container and Kubernetes credentials, netrc, GnuPG, git / npm / PyPI tokens, the
@@ -51,47 +52,181 @@ export function implicitWritePaths(home = homedir()) {
51
52
  ];
52
53
  }
53
54
  /** True when the allowlist entry `pattern` admits every host `host` names (`host` may be a wildcard). */
54
- function covers(pattern, host) {
55
+ export function covers(pattern, host) {
55
56
  if (pattern === host)
56
57
  return true;
57
58
  // `*.x.com` admits `a.x.com` and `*.a.x.com`, never the apex `x.com`.
58
59
  return pattern.startsWith("*.") && host.endsWith(pattern.slice(1));
59
60
  }
60
61
  /**
61
- * The domains one command may reach: what the device's egress allows, cut to the local
62
- * policy. The cloud can only narrow it: an empty policy allows nothing, whatever the egress.
62
+ * The entry {@link effectiveEgress} returns when a command may reach any public host (the device
63
+ * is `open` and so is the org). sandbox-runtime 0.0.81 matches `*` as any host but refuses it in a
64
+ * per-command list, so the OS executor never registers it: its ask callback allows instead.
63
65
  */
64
- export function effectiveEgress(policy, limits) {
65
- const local = policy.allowedDomains.map((d) => d.toLowerCase());
66
+ export const ANY_HOST = "*";
67
+ /**
68
+ * The tier this device runs a command at (spec §4.4): the owner's choice, or the org's default
69
+ * when there is none (`strict` when the kernel sent no default either), cut to the ceiling the
70
+ * kernel sends in `limits.tier`.
71
+ */
72
+ export function deviceTier(policy, limits) {
73
+ return minTier(policy.tier ?? limits.defaultTier ?? "strict", limits.tier);
74
+ }
75
+ /**
76
+ * The tier before any exec was seen (no ceiling known yet): the owner's choice, else `dev`, the
77
+ * default of every org unless changed. Used for the sandbox's first configuration only; the next
78
+ * command applies its own limits.
79
+ */
80
+ export function provisionalTier(policy) {
81
+ return policy.tier ?? "dev";
82
+ }
83
+ /**
84
+ * The facts of the device's tier (spec §5.2.3, §7.3). `limits` undefined means no exec was seen
85
+ * yet: the owner's choice, else `dev`, uncapped. `isolation: none` is reported separately (these
86
+ * describe the sandboxed tier).
87
+ *
88
+ * - Docker mode: the container has its own loopback and sockets in every tier.
89
+ * - OS mode, Linux: the sandbox has its own network namespace, so its loopback always works (not
90
+ * reachable from the host); unix sockets stay blocked (srt cannot limit them by path there).
91
+ * - OS mode, macOS: `strict` has neither; `dev` / `open` get unix sockets under the device's
92
+ * directories and localhost unless a local forwarding proxy was detected and the owner did not
93
+ * set `localhost: allow`.
94
+ */
95
+ export function tierFacts(policy, limits, opts) {
96
+ const effectiveTier = limits === undefined ? provisionalTier(policy) : deviceTier(policy, limits);
97
+ if (opts.mode === "docker")
98
+ return { effectiveTier, localhost: "on", unixSockets: "all-masked" };
99
+ const platform = opts.platform ?? process.platform;
100
+ if (platform !== "darwin")
101
+ return { effectiveTier, localhost: "on", unixSockets: "off" };
102
+ if (effectiveTier === "strict")
103
+ return { effectiveTier, localhost: "off", unixSockets: "off" };
104
+ return {
105
+ effectiveTier,
106
+ localhost: localBinding(policy, opts.proxyDetected) ? "on" : "off-proxy-detected",
107
+ unixSockets: "roots",
108
+ };
109
+ }
110
+ /** macOS `dev` / `open`: local binding, unless a local proxy was found and not overridden. */
111
+ function localBinding(policy, proxyDetected) {
112
+ return policy.localhost === "allow" || !proxyDetected;
113
+ }
114
+ /**
115
+ * The granted hosts that apply to one command: none unless the local `remoteGrants` is `owner`;
116
+ * only valid exact hosts (no wildcards, addresses or internal names), lowercased and deduped; and
117
+ * only those the org's egress admits (any host when it is `open`, none when it is `none`).
118
+ */
119
+ export function grantedHosts(policy, limits, grants) {
120
+ if (grants === undefined || policy.remoteGrants !== "owner")
121
+ return [];
66
122
  if (limits.egress === "none")
67
123
  return [];
68
- if (limits.egress === "open")
69
- return [...new Set(local)];
70
124
  const out = new Set();
71
- for (const raw of limits.allowHosts) {
125
+ for (const raw of grants.hosts) {
126
+ if (typeof raw !== "string")
127
+ continue;
72
128
  const host = raw.toLowerCase();
73
- for (const p of local) {
74
- // The intersection of two entries is the narrower one, if either contains the other.
75
- if (covers(p, host))
76
- out.add(host);
77
- else if (covers(host, p))
78
- out.add(p);
129
+ if (host.startsWith("*.") || validateAllowHost(host).length > 0)
130
+ continue;
131
+ if (limits.egress === "open" || limits.allowHosts.some((p) => covers(p.toLowerCase(), host))) {
132
+ out.add(host);
79
133
  }
80
134
  }
81
135
  return [...out];
82
136
  }
83
137
  /**
84
- * The sandbox-runtime configuration: writes only under the workspace and tmp roots (the runtime's
85
- * implicit write paths denied), skills read only, the secret paths (plus `opts.denyRead`, such as this program's own state directory)
86
- * unreadable, and network limited to `egress`.
138
+ * The hosts the device itself admits at `tier` (before the ceiling): its `allowedDomains`, plus
139
+ * the dev hosts in `dev`. Undefined for `open`: the device admits every host.
87
140
  */
88
- export function srtConfig(_policy, roots, egress, opts = {}) {
141
+ export function deviceHosts(policy, tier, devHosts) {
142
+ if (tier === "open")
143
+ return undefined;
144
+ const local = policy.allowedDomains.map((d) => d.toLowerCase());
145
+ if (tier === "dev")
146
+ for (const d of devHosts)
147
+ local.push(d.toLowerCase());
148
+ return [...new Set(local)];
149
+ }
150
+ /**
151
+ * The domains one command may reach (spec §4.2), with `t` = {@link deviceTier} and the ceiling's
152
+ * hosts (`limits.allowHosts`, or any host when `limits.egress` is `open`):
153
+ * - `strict`: ceiling ∩ `allowedDomains` (an empty list allows nothing but the grants);
154
+ * - `dev`: ceiling ∩ (`allowedDomains` ∪ `limits.devHosts`);
155
+ * - `open`: the ceiling itself ({@link ANY_HOST} when it is `open`);
156
+ * plus the command's grants ({@link grantedHosts}). The cloud can only narrow the local policy.
157
+ */
158
+ export function effectiveEgress(policy, limits, grants) {
159
+ if (limits.egress === "none")
160
+ return [];
161
+ const local = deviceHosts(policy, deviceTier(policy, limits), limits.devHosts ?? []);
162
+ if (local === undefined) {
163
+ if (limits.egress === "open")
164
+ return [ANY_HOST];
165
+ return [...new Set(limits.allowHosts.map((h) => h.toLowerCase()))];
166
+ }
167
+ const out = new Set();
168
+ if (limits.egress === "open") {
169
+ for (const d of local)
170
+ out.add(d);
171
+ }
172
+ else {
173
+ for (const raw of limits.allowHosts) {
174
+ const host = raw.toLowerCase();
175
+ for (const p of local) {
176
+ // The intersection of two entries is the narrower one, if either contains the other.
177
+ if (covers(p, host))
178
+ out.add(host);
179
+ else if (covers(host, p))
180
+ out.add(p);
181
+ }
182
+ }
183
+ }
184
+ for (const h of grantedHosts(policy, limits, grants))
185
+ out.add(h);
186
+ return [...out];
187
+ }
188
+ /**
189
+ * The sandbox-runtime configuration (spec §5.1, §5.2.3): writes only under the workspace and tmp
190
+ * roots (the runtime's implicit write paths denied), skills read only, the secret paths (plus
191
+ * `opts.denyRead`, such as this program's own state directory) unreadable, and network limited to
192
+ * `egress`.
193
+ *
194
+ * `strict` stops there: no local binding, no unix sockets. `dev` and `open` also write the
195
+ * package caches and (macOS) the short socket directory; on macOS they may listen on and reach
196
+ * localhost unless the proxy guard found a local forwarding proxy (`localhost: allow` overrides)
197
+ * and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
198
+ * sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
199
+ * sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
200
+ */
201
+ export function srtConfig(policy, roots, egress, opts = {}) {
202
+ const platform = opts.platform ?? process.platform;
203
+ const tier = opts.tier ?? "strict";
204
+ const darwin = platform === "darwin";
205
+ const dev = tier !== "strict";
206
+ const socketDir = darwin && dev ? opts.socketDir : undefined;
89
207
  return {
90
208
  filesystem: {
91
209
  denyRead: [...deniedSecretPaths(opts.home), ...(opts.denyRead ?? [])],
92
- allowWrite: [roots.workspace, roots.tmp],
210
+ allowWrite: [
211
+ roots.workspace,
212
+ roots.tmp,
213
+ ...(socketDir !== undefined ? [socketDir] : []),
214
+ ...(dev && opts.cacheDir !== undefined ? [opts.cacheDir] : []),
215
+ ],
93
216
  denyWrite: [roots.skills, ...implicitWritePaths()],
94
217
  },
95
- network: { allowedDomains: [...egress], deniedDomains: [] },
218
+ network: {
219
+ allowedDomains: [...egress],
220
+ deniedDomains: [],
221
+ allowLocalBinding: darwin && dev && localBinding(policy, opts.proxyDetected === true),
222
+ ...(darwin &&
223
+ dev && {
224
+ allowUnixSockets: [
225
+ roots.tmp,
226
+ roots.workspace,
227
+ ...(socketDir !== undefined ? [socketDir] : []),
228
+ ],
229
+ }),
230
+ },
96
231
  };
97
232
  }
@@ -0,0 +1,58 @@
1
+ /**
2
+ * The macOS localhost proxy guard (spec §5.2.3). `dev` lets sandboxed commands reach any port on
3
+ * this machine's localhost, which includes a local proxy that forwards past the network allowlist
4
+ * (Clash and the like) or Docker's TCP API. The device looks for one at start, whenever the
5
+ * policy is reloaded and again before a command once the last result is older than
6
+ * {@link PROXY_GUARD_TTL_MS}; when it finds one, `dev` / `open` run without local binding unless the
7
+ * owner set `localhost: allow`. A check that cannot run on macOS counts as a finding (fail safe).
8
+ */
9
+ /** How long a proxy guard result is used before the next command runs the guard again. */
10
+ export declare const PROXY_GUARD_TTL_MS = 30000;
11
+ /** Common local proxy ports (Clash, V2Ray, Surge, Privoxy, Tor) and Docker's TCP API ports. */
12
+ export declare const PROXY_PORTS: readonly number[];
13
+ export interface ProxyGuardResult {
14
+ detected: boolean;
15
+ /** What was found, in English (for `policy show` and the log). */
16
+ reasons: string[];
17
+ }
18
+ export interface ProxyGuardDeps {
19
+ platform?: NodeJS.Platform;
20
+ /** The program's environment (default: `process.env`). */
21
+ env?: Record<string, string | undefined>;
22
+ /** `scutil --proxy`'s output, or undefined when it cannot run (default: runs it on macOS). */
23
+ scutil?: () => Promise<string | undefined>;
24
+ /** Whether something accepts TCP connections on `host`:`port` (default: a short connect). */
25
+ probe?: (port: number, host: string) => Promise<boolean>;
26
+ ports?: readonly number[];
27
+ }
28
+ /** Whether `host` names this machine's loopback. */
29
+ export declare function isLoopbackHost(host: string): boolean;
30
+ /**
31
+ * The loopback proxies `scutil --proxy` reports as enabled: `HTTPEnable`, `HTTPSEnable`,
32
+ * `SOCKSEnable` set to 1 with their `*Proxy` host on loopback. Returns `"HTTP 127.0.0.1:7890"`
33
+ * style entries.
34
+ */
35
+ export declare function parseScutilProxy(text: string): string[];
36
+ /**
37
+ * `value` with the user and password of a proxy URL (`user:pass@`) replaced by `***@`. The
38
+ * userinfo ends at the last `@` before the host, so a password with an unencoded `@`, `/` or `:`
39
+ * is hidden whole.
40
+ */
41
+ export declare function redactProxyUserinfo(value: string): string;
42
+ /**
43
+ * The proxy variables of `env` (any case) whose host is loopback, as `NAME=value` (credentials in
44
+ * the value redacted: the result is printed and logged).
45
+ */
46
+ export declare function loopbackProxyEnv(env: Record<string, string | undefined>): string[];
47
+ /** The loopback addresses probed: a proxy may listen on either. */
48
+ export declare const PROBE_HOSTS: readonly string[];
49
+ /** Whether something accepts a TCP connection on `host`:`port` within a short time. */
50
+ export declare function probeLoopbackPort(port: number, host?: string, timeoutMs?: number): Promise<boolean>;
51
+ /**
52
+ * Looks for a local forwarding proxy: the system proxy (macOS `scutil --proxy`), loopback proxy
53
+ * variables in the program's environment, and a listener on {@link PROXY_PORTS} of 127.0.0.1 or
54
+ * ::1. A proxy configured only through a PAC file (automatic proxy configuration) is not read.
55
+ * Never throws. On macOS a system proxy setting that cannot be read counts as found (fail safe);
56
+ * a port probe that cannot run finds nothing.
57
+ */
58
+ export declare function detectLocalProxy(deps?: ProxyGuardDeps): Promise<ProxyGuardResult>;
@@ -0,0 +1,137 @@
1
+ import { execFile } from "node:child_process";
2
+ import { connect } from "node:net";
3
+ /**
4
+ * The macOS localhost proxy guard (spec §5.2.3). `dev` lets sandboxed commands reach any port on
5
+ * this machine's localhost, which includes a local proxy that forwards past the network allowlist
6
+ * (Clash and the like) or Docker's TCP API. The device looks for one at start, whenever the
7
+ * policy is reloaded and again before a command once the last result is older than
8
+ * {@link PROXY_GUARD_TTL_MS}; when it finds one, `dev` / `open` run without local binding unless the
9
+ * owner set `localhost: allow`. A check that cannot run on macOS counts as a finding (fail safe).
10
+ */
11
+ /** How long a proxy guard result is used before the next command runs the guard again. */
12
+ export const PROXY_GUARD_TTL_MS = 30_000;
13
+ /** Common local proxy ports (Clash, V2Ray, Surge, Privoxy, Tor) and Docker's TCP API ports. */
14
+ export const PROXY_PORTS = Object.freeze([
15
+ 7890, 7891, 7897, 1080, 1087, 8118, 9050, 9150, 2375, 2376,
16
+ ]);
17
+ /** How long one port probe waits for a connection. */
18
+ const PROBE_TIMEOUT_MS = 150;
19
+ /** The proxy variables of a program's environment, checked in any case. */
20
+ const PROXY_ENV = ["http_proxy", "https_proxy", "all_proxy"];
21
+ /** Whether `host` names this machine's loopback. */
22
+ export function isLoopbackHost(host) {
23
+ const h = host
24
+ .trim()
25
+ .toLowerCase()
26
+ .replace(/^\[|\]$/g, "");
27
+ return h === "localhost" || h === "::1" || h.startsWith("127.") || h === "0.0.0.0";
28
+ }
29
+ /**
30
+ * The loopback proxies `scutil --proxy` reports as enabled: `HTTPEnable`, `HTTPSEnable`,
31
+ * `SOCKSEnable` set to 1 with their `*Proxy` host on loopback. Returns `"HTTP 127.0.0.1:7890"`
32
+ * style entries.
33
+ */
34
+ export function parseScutilProxy(text) {
35
+ const fields = new Map();
36
+ for (const line of text.split("\n")) {
37
+ const m = /^\s*([A-Za-z]+)\s*:\s*(.*?)\s*$/.exec(line);
38
+ if (m !== null)
39
+ fields.set(m[1], m[2]);
40
+ }
41
+ const out = [];
42
+ for (const kind of ["HTTP", "HTTPS", "SOCKS"]) {
43
+ if (fields.get(`${kind}Enable`) !== "1")
44
+ continue;
45
+ const host = fields.get(`${kind}Proxy`);
46
+ if (host === undefined || !isLoopbackHost(host))
47
+ continue;
48
+ const port = fields.get(`${kind}Port`);
49
+ out.push(`${kind} ${host}${port !== undefined ? `:${port}` : ""}`);
50
+ }
51
+ return out;
52
+ }
53
+ /**
54
+ * `value` with the user and password of a proxy URL (`user:pass@`) replaced by `***@`. The
55
+ * userinfo ends at the last `@` before the host, so a password with an unencoded `@`, `/` or `:`
56
+ * is hidden whole.
57
+ */
58
+ export function redactProxyUserinfo(value) {
59
+ const scheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.exec(value)?.[0] ?? "";
60
+ const rest = value.slice(scheme.length);
61
+ // the host part never holds an `@`: everything before the last one is userinfo
62
+ const at = rest.lastIndexOf("@");
63
+ return at === -1 ? value : `${scheme}***@${rest.slice(at + 1)}`;
64
+ }
65
+ /**
66
+ * The proxy variables of `env` (any case) whose host is loopback, as `NAME=value` (credentials in
67
+ * the value redacted: the result is printed and logged).
68
+ */
69
+ export function loopbackProxyEnv(env) {
70
+ const out = [];
71
+ for (const [name, value] of Object.entries(env)) {
72
+ if (!PROXY_ENV.includes(name.toLowerCase()) || value === undefined || value === "")
73
+ continue;
74
+ let host;
75
+ try {
76
+ // `127.0.0.1:7890` without a scheme is common too.
77
+ host = new URL(value.includes("://") ? value : `http://${value}`).hostname;
78
+ }
79
+ catch {
80
+ continue;
81
+ }
82
+ if (isLoopbackHost(host))
83
+ out.push(`${name}=${redactProxyUserinfo(value)}`);
84
+ }
85
+ return out;
86
+ }
87
+ function runScutil() {
88
+ return new Promise((resolve) => {
89
+ execFile("/usr/sbin/scutil", ["--proxy"], { timeout: 2_000 }, (e, stdout) => resolve(e === null ? stdout : undefined));
90
+ });
91
+ }
92
+ /** The loopback addresses probed: a proxy may listen on either. */
93
+ export const PROBE_HOSTS = Object.freeze(["127.0.0.1", "::1"]);
94
+ /** Whether something accepts a TCP connection on `host`:`port` within a short time. */
95
+ export function probeLoopbackPort(port, host = "127.0.0.1", timeoutMs = PROBE_TIMEOUT_MS) {
96
+ return new Promise((resolve) => {
97
+ const socket = connect({ host, port });
98
+ const done = (open) => {
99
+ socket.destroy();
100
+ resolve(open);
101
+ };
102
+ socket.setTimeout(timeoutMs, () => done(false));
103
+ socket.once("connect", () => done(true));
104
+ socket.once("error", () => done(false));
105
+ });
106
+ }
107
+ /**
108
+ * Looks for a local forwarding proxy: the system proxy (macOS `scutil --proxy`), loopback proxy
109
+ * variables in the program's environment, and a listener on {@link PROXY_PORTS} of 127.0.0.1 or
110
+ * ::1. A proxy configured only through a PAC file (automatic proxy configuration) is not read.
111
+ * Never throws. On macOS a system proxy setting that cannot be read counts as found (fail safe);
112
+ * a port probe that cannot run finds nothing.
113
+ */
114
+ export async function detectLocalProxy(deps = {}) {
115
+ const platform = deps.platform ?? process.platform;
116
+ const reasons = [];
117
+ if (platform === "darwin") {
118
+ const text = await (deps.scutil ?? runScutil)().catch(() => undefined);
119
+ if (text === undefined)
120
+ reasons.push("the system proxy settings could not be read");
121
+ else
122
+ for (const p of parseScutilProxy(text))
123
+ reasons.push(`system proxy ${p}`);
124
+ }
125
+ for (const v of loopbackProxyEnv(deps.env ?? process.env))
126
+ reasons.push(`environment ${v}`);
127
+ const probe = deps.probe ?? ((port, host) => probeLoopbackPort(port, host));
128
+ const ports = deps.ports ?? PROXY_PORTS;
129
+ const targets = PROBE_HOSTS.flatMap((host) => ports.map((port) => ({ host, port })));
130
+ const open = await Promise.all(targets.map((t) => probe(t.port, t.host).catch(() => false)));
131
+ targets.forEach((t, i) => {
132
+ const where = t.host.includes(":") ? `[${t.host}]` : t.host;
133
+ if (open[i])
134
+ reasons.push(`a listener on ${where}:${t.port}`);
135
+ });
136
+ return { detected: reasons.length > 0, reasons };
137
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Why a `*.` wildcard is too broad to add from the device page: its remainder is a whole public
3
+ * suffix (one label such as `com`, or a known multi-label one such as `co.uk`, `github.io`);
4
+ * null for an exact host or a narrower wildcard.
5
+ */
6
+ export declare function publicSuffixWildcard(pattern: string): string | null;
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Public suffixes of more than one label that a device-page wildcard may not cover (a small
3
+ * built-in list, not the public suffix list; the kernel keeps the same list in
4
+ * packages/kernel/src/devices/public-suffix.ts). Includes the shared hosting suffixes where each
5
+ * subdomain belongs to someone else.
6
+ */
7
+ const MULTI_LABEL_SUFFIXES = new Set([
8
+ "ac.uk",
9
+ "co.uk",
10
+ "gov.uk",
11
+ "ltd.uk",
12
+ "me.uk",
13
+ "net.uk",
14
+ "org.uk",
15
+ "plc.uk",
16
+ "com.cn",
17
+ "edu.cn",
18
+ "gov.cn",
19
+ "net.cn",
20
+ "org.cn",
21
+ "com.hk",
22
+ "org.hk",
23
+ "com.tw",
24
+ "org.tw",
25
+ "co.jp",
26
+ "ne.jp",
27
+ "or.jp",
28
+ "ac.jp",
29
+ "co.kr",
30
+ "or.kr",
31
+ "com.au",
32
+ "net.au",
33
+ "org.au",
34
+ "edu.au",
35
+ "co.nz",
36
+ "org.nz",
37
+ "com.br",
38
+ "com.mx",
39
+ "com.sg",
40
+ "com.my",
41
+ "co.in",
42
+ "co.za",
43
+ "com.tr",
44
+ "com.ar",
45
+ "github.io",
46
+ "gitlab.io",
47
+ "pages.dev",
48
+ "workers.dev",
49
+ "vercel.app",
50
+ "netlify.app",
51
+ "herokuapp.com",
52
+ "appspot.com",
53
+ "web.app",
54
+ "firebaseapp.com",
55
+ "azurewebsites.net",
56
+ "cloudfront.net",
57
+ "amazonaws.com",
58
+ "blogspot.com",
59
+ "ngrok.io",
60
+ "ngrok-free.app",
61
+ "trycloudflare.com",
62
+ "onrender.com",
63
+ "fly.dev",
64
+ "glitch.me",
65
+ ]);
66
+ /**
67
+ * Why a `*.` wildcard is too broad to add from the device page: its remainder is a whole public
68
+ * suffix (one label such as `com`, or a known multi-label one such as `co.uk`, `github.io`);
69
+ * null for an exact host or a narrower wildcard.
70
+ */
71
+ export function publicSuffixWildcard(pattern) {
72
+ if (!pattern.startsWith("*."))
73
+ return null;
74
+ const rest = pattern.slice(2).toLowerCase();
75
+ if (!rest.includes(".") || MULTI_LABEL_SUFFIXES.has(rest)) {
76
+ return `Use a narrower domain; ${pattern.toLowerCase()} covers a whole public suffix.`;
77
+ }
78
+ return null;
79
+ }