@capybara-hq/device 0.1.0-rc.2 → 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/README.md +201 -11
- package/dist/args.d.ts +4 -2
- package/dist/args.js +21 -5
- package/dist/cli.d.ts +12 -2
- package/dist/cli.js +60 -8
- package/dist/client.d.ts +9 -1
- package/dist/client.js +38 -14
- package/dist/command-log.d.ts +10 -0
- package/dist/commands/login.js +1 -0
- package/dist/commands/policy.d.ts +66 -3
- package/dist/commands/policy.js +347 -31
- package/dist/commands/start.d.ts +9 -3
- package/dist/commands/start.js +18 -3
- package/dist/exec/docker.d.ts +41 -5
- package/dist/exec/docker.js +73 -19
- package/dist/exec/groups.d.ts +42 -0
- package/dist/exec/groups.js +100 -0
- package/dist/exec/host.d.ts +53 -0
- package/dist/exec/host.js +183 -0
- package/dist/exec/os.d.ts +73 -5
- package/dist/exec/os.js +186 -14
- package/dist/exec/shared.d.ts +28 -0
- package/dist/exec/shared.js +154 -1
- package/dist/exec/switch.d.ts +108 -0
- package/dist/exec/switch.js +214 -0
- package/dist/exec/types.d.ts +37 -3
- package/dist/network.d.ts +45 -0
- package/dist/network.js +161 -0
- package/dist/policy-store.d.ts +38 -0
- package/dist/policy-store.js +92 -0
- package/dist/policy.d.ts +102 -11
- package/dist/policy.js +155 -20
- package/dist/proxy-guard.d.ts +58 -0
- package/dist/proxy-guard.js +137 -0
- package/dist/public-suffix.d.ts +6 -0
- package/dist/public-suffix.js +79 -0
- package/dist/server-ops.d.ts +65 -7
- package/dist/server-ops.js +289 -29
- package/dist/state.d.ts +44 -1
- package/dist/state.js +177 -9
- package/package.json +2 -2
package/dist/policy.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
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
|
|
19
|
-
*
|
|
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
|
|
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
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
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
|
|
62
|
-
*
|
|
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
|
|
65
|
-
|
|
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
|
|
125
|
+
for (const raw of grants.hosts) {
|
|
126
|
+
if (typeof raw !== "string")
|
|
127
|
+
continue;
|
|
72
128
|
const host = raw.toLowerCase();
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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
|
|
85
|
-
*
|
|
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
|
|
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: [
|
|
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: {
|
|
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
|
+
}
|