Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
/**
* Where a Bot's traffic leaves from.
*
* Per-Bot egress identity makes traffic attributable to the Bot that caused it. With a distinct
* upstream proxy per Bot, the far side sees a different address for each Bot and can enforce network
* rules alongside application policy.
*
* This does not anonymise anything and it is not a security boundary by itself. It
* gives the far side a stable, per-Bot address to allow-list or attribute, which is what a security
* team actually asks for. A Bot with no proxy configured goes out directly, which is the right default
* for a laptop and the wrong one for a deployment that cares.
*
* This module has no Playwright import, so proxy parsing tests can run outside the browser image.
*/
import { randomBytes, timingSafeEqual } from "node:crypto";
import { lookup } from "node:dns/promises";
import {
createServer,
request as httpRequest,
type IncomingMessage,
type Server,
} from "node:http";
import { BlockList, connect, isIP, type Socket } from "node:net";
import { isPersonBrowserId } from "../../shared/openbot-browser";
/** A proxy as Playwright wants it: credentials separated from the URL. */
export type Egress = {
server: string;
username?: string;
password?: string;
};
/**
* The environment variable naming a Bot's proxy.
*
* Upper-cased with anything unusual replaced, because a bot id is a free-form string and an
* environment variable name is not. `sales-bot` reads `EGRESS_PROXY_SALES_BOT`.
*/
export function egressVariableFor(botId: string): string {
return `EGRESS_PROXY_${botId.replace(/[^a-zA-Z0-9]/g, "_").toUpperCase()}`;
}
/**
* Resolve a Bot's proxy from the environment, or null for direct.
*
* `EGRESS_PROXY_<BOT>` names one Bot's proxy; `EGRESS_PROXY_DEFAULT` covers the rest.
*/
export function egressFor(
botId: string,
env: Record<string, string | undefined>,
): Egress | null {
/*
* While the network-policy filter runs, every Bot's browser goes through it, and it carries the
* Bot in the proxy credentials so one filter can hold a policy per Bot. The filter chains to the
* configured upstream itself, so the per-Bot address the far side sees is unchanged. A browser is
* pointed at the filter's browser listener, which asks for those credentials (see
* `startEgressFilter`), so every connection it makes says whose browser it is.
*/
if (filter) {
return {
server: `http://127.0.0.1:${filter.browserPort}`,
username: botId,
password: filter.secret,
};
}
return upstreamFor(botId, env);
}
/** The configured upstream proxy for a Bot, ignoring the filter. */
export function upstreamFor(
botId: string,
env: Record<string, string | undefined>,
): Egress | null {
const raw = env[egressVariableFor(botId)] ?? env.EGRESS_PROXY_DEFAULT;
if (!raw?.trim()) return null;
return splitProxyCredentials(raw);
}
/**
* Split a proxy string into a server and its credentials.
*
* Credentials commonly arrive inside the URL, which is how proxies are handed out. They are split out
* so that the server string can be shown to a person without leaking a password.
*
* Two shapes reach here, and only one of them is a URL as far as the parser is concerned. A bare
* `host:port` is what an operator writes when they are not thinking about URLs, and Playwright and
* curl both take it; `new URL` reads `proxy.internal:8080` as the scheme `proxy.internal:` and the
* path `8080` with an empty host, rather than throwing. `username` and `password` come back empty for
* that shape, so a proxy written `bot:[email protected]:8080` would keep its password in the
* string it hands back. Re-parsing behind a synthetic scheme makes the split happen for both shapes;
* the synthetic scheme is then removed so the server reads the way it was written.
*/
export function splitProxyCredentials(raw: string): Egress {
const trimmed = raw.trim();
let url: URL | null = null;
let synthetic = "";
try {
const asWritten = new URL(trimmed);
if (asWritten.host !== "") url = asWritten;
} catch (e) {
if (!(e instanceof TypeError)) throw e;
}
if (!url) {
synthetic = "http://";
try {
url = new URL(`${synthetic}${trimmed}`);
} catch (e) {
if (!(e instanceof TypeError)) throw e;
// Not addressable either way. Passed through, so an operator who writes the obvious thing is
// not told they are wrong.
return { server: trimmed };
}
}
const username = url.username ? decodeUserinfo(url.username) : undefined;
const password = url.password ? decodeUserinfo(url.password) : undefined;
url.username = "";
url.password = "";
return {
server: url.toString().replace(/\/$/, "").slice(synthetic.length),
...(username ? { username } : {}),
...(password ? { password } : {}),
};
}
/**
* A proxy username or password, percent-decoded where it was percent-encoded.
*
* A `%` not followed by two hex digits is a character somebody typed, not an escape, and
* `decodeURIComponent` throws `URIError` on it. That escaped every caller here, which only catches
* `TypeError`, and since the shell strips credentials from the proxy variables before every
* command, one such password made every `/exec` fail. As written is what was meant.
*/
function decodeUserinfo(value: string): string {
try {
return decodeURIComponent(value);
} catch (e) {
if (e instanceof URIError) return value;
throw e;
}
}
/**
* The label for a Bot's egress, for people and for the admin list.
*
* Host only. A proxy URL routinely carries a password, and this string is rendered in a browser and
* returned by an API.
*/
export function egressLabel(
botId: string,
env: Record<string, string | undefined>,
): string | null {
const proxy = upstreamFor(botId, env);
if (!proxy) return filter ? "network policy filter" : null;
try {
// `||` handles bare `proxy.internal:8080`, which URL parses as a scheme plus path and an empty
// host rather than throwing.
return new URL(proxy.server).host || proxy.server;
} catch {
return proxy.server;
}
}
/*
* ---------------------------------------------------------------------------------------------------
* Network policy: where a Bot's computer may connect.
*
* The same four modes Grok Bot's Network Controls offer (no policy, allow all, defaults plus team
* allowlist, team allowlist only), plus `deny_all`, which is what a Bot gets when its owner's "Cloud
* network access" capability is off. The rule engine below is pure and is also what the API server
* imports to refuse a navigation before it reaches the computer, so the two ends cannot disagree.
*
* The filter proxy is what enforces it on the computer itself: the browser is pointed at it through
* `egressFor`, and shell commands through HTTP(S)_PROXY. A policy pushed to a running computer is
* consulted on the next connection, so it applies without restarting anything.
*
* WHAT THIS CANNOT STOP: a process that ignores proxy variables and opens a raw socket. That is the
* Kubernetes NetworkPolicy's job, which this narrows rather than replaces.
* ---------------------------------------------------------------------------------------------------
*/
/**
* One thing a policy allows. `ports` narrows either kind to those ports (`443`, `5432,8000-8100`);
* without it a rule allows every port, which is what every rule meant before domains took ports.
*/
export type EgressRule =
| { type: "domain"; value: string; ports?: string }
| { type: "cidr"; value: string; ports?: string };
export type EgressMode =
| "allow_all"
| "defaults_plus_allowlist"
| "allowlist_only"
| "deny_all";
export type EgressPolicy = { mode: EgressMode; rules: EgressRule[] };
export const EGRESS_MODES: readonly EgressMode[] = [
"allow_all",
"defaults_plus_allowlist",
"allowlist_only",
"deny_all",
];
/**
* What "defaults" means in `defaults_plus_allowlist`: the package registries and source hosts a
* development computer needs to install anything at all.
*/
export const DEFAULT_EGRESS_DESTINATIONS: readonly string[] = [
"github.com",
"githubusercontent.com",
"ghcr.io",
"registry.npmjs.org",
"registry.yarnpkg.com",
"pypi.org",
"files.pythonhosted.org",
"crates.io",
"static.crates.io",
"proxy.golang.org",
"sum.golang.org",
"deb.debian.org",
"security.debian.org",
"archive.ubuntu.com",
"security.ubuntu.com",
"registry-1.docker.io",
"auth.docker.io",
"production.cloudflare.docker.com",
];
const DOMAIN =
/^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
const PORTS = /^\d{1,5}(-\d{1,5})?(,\d{1,5}(-\d{1,5})?)*$/;
function normalizeHost(host: string): string {
return host
.trim()
.toLowerCase()
.replace(/\.$/, "")
.replace(/^\[|\]$/g, "");
}
function parseCidr(
value: string,
): { address: string; prefix: number; family: "ipv4" | "ipv6" } | null {
const [address = "", prefixText, ...rest] = value.trim().split("/");
// `Number` reads "" as 0 and takes "0x8", so `10.0.0.5/` would allow every address. A zone id
// passes `isIP` but `BlockList` throws on it when the rule is first used.
if (rest.length > 0 || address.includes("%")) return null;
if (prefixText !== undefined && !/^\d{1,3}$/.test(prefixText)) return null;
const version = isIP(address);
if (version === 0) return null;
const max = version === 4 ? 32 : 128;
const prefix = prefixText === undefined ? max : Number(prefixText);
if (!Number.isInteger(prefix) || prefix < 0 || prefix > max) return null;
return { address, prefix, family: version === 4 ? "ipv4" : "ipv6" };
}
function portsMatch(spec: string | undefined, port: number): boolean {
if (!spec?.trim()) return true;
return spec.split(",").some((part) => {
const [low, high] = part.split("-").map(Number);
if (low === undefined) return false;
return high === undefined ? port === low : port >= low && port <= high;
});
}
/**
* A rule's port list with its spaces taken out, absent for none, or why it is not one. Read exactly
* as an IP range rule's always was, for a domain rule too: anything but text is no port list.
*/
function portsOf(
raw: unknown,
): { ok: true; ports?: string } | { ok: false; error: string } {
if (typeof raw !== "string" || !raw.trim()) return { ok: true };
const ports = raw.replaceAll(" ", "");
if (!PORTS.test(ports))
return {
ok: false,
error: `"${raw}" is not a port list such as 443 or 5432,8000-8100.`,
};
return { ok: true, ports };
}
/** Read a rule list from JSON, refusing anything that is not exactly a rule. */
export function parseEgressRules(
input: unknown,
): { ok: true; rules: EgressRule[] } | { ok: false; error: string } {
if (!Array.isArray(input))
return { ok: false, error: "rules must be a list." };
const rules: EgressRule[] = [];
for (const [index, raw] of input.entries()) {
const entry = raw as Record<string, unknown> | null;
if (!entry || typeof entry !== "object") {
return { ok: false, error: `Rule ${index + 1} is not an object.` };
}
if (entry.type === "domain" && typeof entry.value === "string") {
const value = normalizeHost(entry.value);
if (!DOMAIN.test(value)) {
return { ok: false, error: `"${entry.value}" is not a domain.` };
}
const ports = portsOf(entry.ports);
if (!ports.ok) return ports;
rules.push({
type: "domain",
value,
...(ports.ports ? { ports: ports.ports } : {}),
});
continue;
}
if (entry.type === "cidr" && typeof entry.value === "string") {
if (!parseCidr(entry.value)) {
return {
ok: false,
error: `"${entry.value}" is not an IP address or range such as 10.0.0.0/8.`,
};
}
const ports = portsOf(entry.ports);
if (!ports.ok) return ports;
rules.push({
type: "cidr",
value: entry.value.trim(),
...(ports.ports ? { ports: ports.ports } : {}),
});
continue;
}
return {
ok: false,
error: `Rule ${index + 1} must be { type: "domain", value, ports? } or { type: "cidr", value, ports? }.`,
};
}
return { ok: true, rules };
}
export function parseEgressPolicy(
input: unknown,
): { ok: true; policy: EgressPolicy } | { ok: false; error: string } {
const candidate = input as { mode?: unknown; rules?: unknown } | null;
if (
!candidate ||
typeof candidate !== "object" ||
!EGRESS_MODES.includes(candidate.mode as EgressMode)
) {
return {
ok: false,
error: `mode must be one of ${EGRESS_MODES.join(", ")}.`,
};
}
const rules = parseEgressRules(candidate.rules ?? []);
if (!rules.ok) return rules;
return {
ok: true,
policy: { mode: candidate.mode as EgressMode, rules: rules.rules },
};
}
function domainMatches(pattern: string, host: string): boolean {
if (pattern.startsWith("*.")) return host.endsWith(pattern.slice(1));
return host === pattern || host.endsWith(`.${pattern}`);
}
function addressMatches(rule: EgressRule, address: string, port: number) {
if (rule.type !== "cidr" || !portsMatch(rule.ports, port)) return false;
const cidr = parseCidr(rule.value);
const version = isIP(address);
if (!cidr || version === 0) return false;
const list = new BlockList();
list.addSubnet(cidr.address, cidr.prefix, cidr.family);
return list.check(address, version === 4 ? "ipv4" : "ipv6");
}
export type EgressDecision = { allowed: boolean; reason: string };
/**
* Addresses no Bot may reach, whatever its policy says, allow_all included.
*
* Link-local is where every cloud keeps the endpoint that hands a machine its credentials:
* 169.254.169.254 on AWS, Azure, GCP and Oracle, with AWS and GCP also answering on the IPv6
* addresses below, and Alibaba on 100.100.100.200. The chart's NetworkPolicy cuts out 169.254/16
* too, but it is off by default and says nothing about IPv6, so this is the guard a default install
* actually has. It covers the browser and every command that honours the proxy variables.
*/
const ALWAYS_DENIED: readonly [string, number, "ipv4" | "ipv6"][] = [
["169.254.0.0", 16, "ipv4"],
["100.100.100.200", 32, "ipv4"],
["fe80::", 10, "ipv6"],
["fd00:ec2::254", 128, "ipv6"],
["fd20:ce::254", 128, "ipv6"],
];
const alwaysDenied = new BlockList();
for (const [address, prefix, family] of ALWAYS_DENIED)
alwaysDenied.addSubnet(address, prefix, family);
/** The NAT64 well-known prefix. On a network with a NAT64 gateway it reaches the IPv4 address in its last 32 bits. */
const nat64 = new BlockList();
nat64.addSubnet("64:ff9b::", 96, "ipv6");
/** The IPv4 address a NAT64 address carries, or null when it is not one. */
function nat64Ipv4(address: string): string | null {
if (isIP(address) !== 6 || !nat64.check(address, "ipv6")) return null;
// Let URL spell it in hex groups (`64:ff9b::1.2.3.4` becomes `64:ff9b::102:304`), then expand `::`
// so the last two groups are the IPv4 address however the address was written.
const hex = new URL(`http://[${address}]/`).hostname.slice(1, -1);
const [head = "", tail] = hex.split("::");
const groups = (part: string) => (part ? part.split(":") : []);
const all =
tail === undefined
? groups(head)
: [
...groups(head),
...Array(8 - groups(head).length - groups(tail).length).fill("0"),
...groups(tail),
];
const high = Number.parseInt(all[6] ?? "0", 16);
const low = Number.parseInt(all[7] ?? "0", 16);
return [high >> 8, high & 255, low >> 8, low & 255].join(".");
}
/**
* True for a metadata or link-local address, including one written as IPv4-mapped IPv6 or reached
* through the NAT64 prefix.
*/
export function isAlwaysDenied(addressInput: string): boolean {
const address = normalizeHost(addressInput);
const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address)?.[1];
const candidate = mapped ?? nat64Ipv4(address) ?? address;
const version = isIP(candidate);
if (version === 0) return false;
return alwaysDenied.check(candidate, version === 4 ? "ipv4" : "ipv6");
}
/**
* Who a refusal is said to. A Bot's computer, which is what most connections here are; a person's own
* browser (`person-` ids), whose refusal page the person reads in their browser; or `anyone`, when the
* connection could be either, which is said without naming a Bot or a person.
*/
export type EgressAudience = "bot" | "person" | "anyone";
/** Why a connection was refused, in the words of whoever is refused. */
const REFUSALS = {
alwaysDenied: {
bot: (host: string) =>
`${host} is a cloud metadata or link-local address, which no Bot may reach.`,
person: (host: string) =>
`This browser never opens ${host}: it is a cloud metadata or link-local address, not a website.`,
anyone: (host: string) =>
`${host} is a cloud metadata or link-local address, which OpenBot never opens.`,
},
off: {
bot: "Network access is turned off for this Bot's computer.",
person: "Network access is turned off for this browser.",
anyone: "Network access is turned off here.",
},
notAllowed: {
bot: (where: string) =>
`${where} is not on this deployment's network allowlist.`,
person: (where: string) => `This browser may not open ${where}.`,
anyone: (where: string) =>
`${where} is not on this deployment's network allowlist.`,
},
unresolved: {
bot: (host: string) => `${host} could not be resolved.`,
person: (host: string) => `${host} could not be found.`,
anyone: (host: string) => `${host} could not be resolved.`,
},
noPolicy: {
bot: "No network policy has reached this computer yet, so nothing may leave it.",
person: "This browser cannot reach the network yet. Try again in a moment.",
anyone:
"No network policy has reached this computer yet, so nothing may leave it.",
},
} as const;
/**
* A host and port as a person reads them: an IPv6 address in brackets, as in a URL, since `::1:7555`
* cannot be told apart from an address that ends in `7555`.
*/
function hostPort(host: string, port: number): string {
return `${isIP(host) === 6 ? `[${host}]` : host}:${port}`;
}
/**
* May this connection go out?
*
* `resolved` is what the host name resolved to, when the caller resolved it. A domain rule matches a
* name; an IP-range rule matches an address, whether the Bot dialled the address directly or a name
* that resolved inside the range. Every resolved address must be inside an allowed range, so a name
* that resolves partly outside is refused rather than connected to whichever address came first.
* Either kind of rule allows only its `ports` when it names some.
*
* `audience` is who a refusal is worded for (see `EgressAudience`); it never changes the decision.
*/
export function egressDecision(
policy: EgressPolicy,
hostInput: string,
port: number,
resolved: readonly string[] = [],
audience: EgressAudience = "bot",
): EgressDecision {
const host = normalizeHost(hostInput);
const denied = [host, ...resolved].find(isAlwaysDenied);
if (denied !== undefined) {
return {
allowed: false,
reason: REFUSALS.alwaysDenied[audience](host),
};
}
if (policy.mode === "allow_all") {
return {
allowed: true,
reason: "The network policy allows all destinations.",
};
}
if (policy.mode === "deny_all") {
return { allowed: false, reason: REFUSALS.off[audience] };
}
const domains: { value: string; ports?: string }[] = [
...(policy.mode === "defaults_plus_allowlist"
? DEFAULT_EGRESS_DESTINATIONS.map((value) => ({ value }))
: []),
...policy.rules.flatMap((rule) => (rule.type === "domain" ? [rule] : [])),
];
if (
isIP(host) === 0 &&
domains.some(
(rule) => domainMatches(rule.value, host) && portsMatch(rule.ports, port),
)
) {
return { allowed: true, reason: `${host} is on the allowlist.` };
}
const addresses = isIP(host) !== 0 ? [host] : [...resolved];
if (
addresses.length > 0 &&
addresses.every((address) =>
policy.rules.some((rule) => addressMatches(rule, address, port)),
)
) {
return {
allowed: true,
reason: `${hostPort(host, port)} is inside an allowed range.`,
};
}
return {
allowed: false,
reason: REFUSALS.notAllowed[audience](hostPort(host, port)),
};
}
/** True when deciding needs the host's addresses: a name, and at least one IP-range rule. */
export function needsResolution(policy: EgressPolicy, host: string): boolean {
return (
isIP(normalizeHost(host)) === 0 &&
policy.mode !== "allow_all" &&
policy.mode !== "deny_all" &&
policy.rules.some((rule) => rule.type === "cidr")
);
}
/* --------------------------------- the filter on the computer --------------------------------- */
type RunningFilter = {
/** The shell's listener, which takes a connection without credentials. */
port: number;
/** The browsers' listener, which takes none without them. */
browserPort: number;
secret: string;
servers: Server[];
};
let filter: RunningFilter | null = null;
const policies = new Map<string, EgressPolicy>();
let policyRequired = true;
type Resolver = (host: string) => Promise<string[]>;
const systemResolver: Resolver = async (host) =>
(await lookup(host, { all: true })).map((entry) => entry.address);
let resolver: Resolver = systemResolver;
/** For tests: answer name lookups without DNS. Null puts the system resolver back. */
export function setEgressResolver(next: Resolver | null) {
resolver = next ?? systemResolver;
}
/** Install (or with null, remove) the policy one Bot's connections are judged by. */
export function setEgressPolicy(botId: string, policy: EgressPolicy | null) {
if (policy) policies.set(botId, policy);
else policies.delete(botId);
}
export function egressPolicyFor(botId: string): EgressPolicy | undefined {
return policies.get(botId);
}
/**
* Which policies judge a connection.
*
* A connection carrying a Bot in its proxy credentials is judged by that Bot's policy alone, and
* every browser's does: its listener asks for them. One without (a shell command, whose proxy
* variable has no credentials in it) is judged by the only policy on this computer when there is
* one, and otherwise by every policy at once, so the most restrictive wins. Nothing pushed yet
* refuses: the API server pushes a computer its policy before it acts and whenever the computer
* wakes, so a refusal here is only ever the gap before that push. EGRESS_POLICY_REQUIRED=0 lets a
* computer run with no API server pushing to it at all.
*/
function policiesFor(
botId: string | undefined,
): [owner: string, policy: EgressPolicy][] | "refuse" {
if (botId) {
const own = policies.get(botId);
if (own) return [[botId, own]];
return policyRequired ? "refuse" : [];
}
if (policies.size === 0) return policyRequired ? "refuse" : [];
return [...policies.entries()];
}
/**
* Who a refusal is worded for: the credentials' owner when there are some, else the owners of the
* policies judging the connection when they are all people's browsers or all Bots, else anyone.
*
* A browser's connection has its owner in it (see `startEgressFilter`), so the rest is for one
* without: a shell command's, judged by every policy on the computer, which on one shared by Bots
* and a person could be anybody's, and is said so.
*/
function audienceFor(
botId: string | undefined,
owners: readonly string[],
): EgressAudience {
if (botId) return isPersonBrowserId(botId) ? "person" : "bot";
if (owners.length === 0) return "bot";
if (owners.every(isPersonBrowserId)) return "person";
if (!owners.some(isPersonBrowserId)) return "bot";
return "anyone";
}
async function decide(
botId: string | undefined,
host: string,
port: number,
direct: boolean,
): Promise<EgressDecision & { addresses?: string[] }> {
const judging = policiesFor(botId);
if (judging === "refuse") {
return {
allowed: false,
reason: REFUSALS.noPolicy[audienceFor(botId, [])],
};
}
const audience = audienceFor(
botId,
judging.map(([owner]) => owner),
);
let resolved: string[] = [];
/*
* Resolved whenever this filter makes the connection itself, so the address checked is the
* address connected to and a name cannot reach a metadata endpoint by resolving to one. Through an
* upstream proxy, that proxy resolves on its own network, which may be the only one with DNS, so a
* name is resolved here only when a range rule needs it.
*/
const named = isIP(normalizeHost(host)) === 0;
if (
named &&
(direct || judging.some(([, policy]) => needsResolution(policy, host)))
) {
try {
resolved = await resolver(normalizeHost(host));
} catch {
return { allowed: false, reason: REFUSALS.unresolved[audience](host) };
}
}
// Checked even with no policy to judge by, which EGRESS_POLICY_REQUIRED=0 allows.
for (const policy of judging.length > 0
? judging.map(([, policy]) => policy)
: [{ mode: "allow_all" as const, rules: [] }]) {
const decision = egressDecision(policy, host, port, resolved, audience);
if (!decision.allowed) return decision;
}
// Connect only to the addresses that were checked, so a second lookup cannot answer differently.
return {
allowed: true,
reason: "Allowed.",
...(resolved.length > 0 ? { addresses: resolved } : {}),
};
}
/**
* The checked addresses in the order they are tried: IPv4 first, then IPv6, each in DNS order.
*
* IPv4 first because a container network is the usual place this runs, and many have no IPv6 route:
* an AAAA answer tried first there costs a full attempt timeout on every connection.
*/
export function connectOrder(addresses: readonly string[]): string[] {
return [
...addresses.filter((address) => isIP(address) !== 6),
...addresses.filter((address) => isIP(address) === 6),
];
}
/** How long one address may take to accept before the next checked address is tried. */
export const CONNECT_ATTEMPT_TIMEOUT_MS = 3_000;
/**
* Connect to a name through the addresses already checked, one at a time, and nothing else.
*
* Every address the name resolved to passed the deny check, so any of them may be tried; a literal
* address is the only one tried. The name is never resolved a second time, which is what keeps the
* pin. Each attempt connects to one literal address, so no lookup runs and no runtime fallback logic
* is involved: this loop is the fallback.
*
* NOT `autoSelectFamily` WITH THE CHECKED LIST, WHICH THIS USED TO BE. Bun's `node:net` walks a list
* of addresses with a timer that can fire after the connection it belongs to has been torn down, and
* then throws `TypeError: null is not an object (evaluating 'context')` from
* `internalConnectMultipleTimeout` (oven-sh/bun#25633, still reproducing on 1.3.13 and seen here on
* 1.3.14). The throw is in a timer, so nothing catches it and the computer process exits. A
* Cloudflare-fronted site resolves to several addresses and a challenge page opens and abandons many
* connections at once, so opening one in a Bot's browser restarted the computer and lost the page the
* person was being asked to solve.
*
* Bun fixed the timer in 1.4.0 (oven-sh/bun#32660, which this repository now runs on 1.4.3, where
* Bun's own regression fixture passes and fails on 1.3.14). Kept anyway: walking the checked list
* ourselves is what pins the connection to addresses that passed the deny check, so it is the right
* shape regardless of the runtime bug, and it costs nothing a person would notice.
*/
export function connectInTurn(
target: { host: string; port: number; addresses?: readonly string[] },
onReady: (socket: Socket) => void,
onError: (error: Error) => void,
attemptTimeoutMs = CONNECT_ATTEMPT_TIMEOUT_MS,
): void {
const queue = target.addresses?.length
? connectOrder(target.addresses)
: [target.host];
let lastError: Error | undefined;
const attempt = (index: number) => {
const address = queue[index];
if (address === undefined) {
onError(lastError ?? new Error(`Could not connect to ${target.host}.`));
return;
}
let settled = false;
const socket = connect({ host: address, port: target.port });
const moveOn = (error: Error) => {
if (settled) return;
settled = true;
clearTimeout(timer);
lastError = error;
socket.destroy();
attempt(index + 1);
};
const timer = setTimeout(
() =>
moveOn(new Error(`${address}:${target.port} did not answer in time.`)),
attemptTimeoutMs,
);
socket.once("error", moveOn);
socket.once("connect", () => {
if (settled) return;
settled = true;
clearTimeout(timer);
socket.off("error", moveOn);
// From here an error belongs to the caller, exactly as it did when it registered its own.
socket.once("error", onError);
onReady(socket);
});
};
attempt(0);
}
/**
* Request options that reach a name through one checked address, without a second lookup.
*
* For plain HTTP, where the request library owns the socket. One address rather than the list, for
* the reason given on {@link connectInTurn}: the list is what sends Bun down its crashing path. The
* first IPv4 address is chosen, so a computer with no IPv6 route still connects.
*/
function pinnedTo(addresses: readonly string[] | undefined) {
if (!addresses?.length) return {};
const [address] = connectOrder(addresses);
if (address === undefined) return {};
const family = isIP(address) === 6 ? 6 : 4;
return {
autoSelectFamily: false,
lookup: (
_host: string,
options: { all?: boolean } | number | undefined,
callback: (...args: unknown[]) => void,
) => {
if (typeof options === "object" && options?.all)
callback(null, [{ address, family }]);
else callback(null, address, family);
},
};
}
function botFromProxyAuthorization(
header: string | undefined,
secret: string,
): string | undefined {
if (!header?.startsWith("Basic ")) return undefined;
const decoded = Buffer.from(header.slice(6), "base64").toString("utf8");
const colon = decoded.indexOf(":");
if (colon < 1) return undefined;
const offered = Buffer.from(decoded.slice(colon + 1));
const expected = Buffer.from(secret);
if (
offered.length !== expected.length ||
!timingSafeEqual(offered, expected)
) {
return undefined;
}
return decoded.slice(0, colon);
}
function basic(username?: string, password?: string): string | undefined {
if (username === undefined) return undefined;
return `Basic ${Buffer.from(`${username}:${password ?? ""}`).toString("base64")}`;
}
function upstreamAddress(upstream: Egress): { host: string; port: number } {
const url = new URL(
/^[a-z]+:\/\//i.test(upstream.server)
? upstream.server
: `http://${upstream.server}`,
);
return { host: unbracketed(url.hostname), port: Number(url.port || 80) };
}
function refuse(socket: Socket, reason: string) {
socket.end(
`HTTP/1.1 403 Forbidden\r\ncontent-type: text/plain\r\nx-openbot-egress: refused\r\ncontent-length: ${Buffer.byteLength(reason)}\r\n\r\n${reason}`,
);
}
/**
* The answer a browser's listener gives a connection without its credentials: a 407, the one thing
* that makes Chromium send the proxy credentials it was launched with. It sends them only when asked,
* never first (`HttpAuthController`, which then keeps them for this proxy and sends them up front on
* every later connection from the same profile, WebSockets included). Closed rather than kept, so
* the browser asks again on a fresh connection, which it does.
* https://www.rfc-editor.org/rfc/rfc9110#name-407-proxy-authentication-re
*/
const PROXY_CHALLENGE =
'HTTP/1.1 407 Proxy Authentication Required\r\nproxy-authenticate: Basic realm="OpenBot"\r\ncontent-type: text/plain\r\nconnection: close\r\ncontent-length: 0\r\n\r\n';
/** Open a tunnel to host:port, through the upstream proxy when there is one. */
function tunnel(
target: { host: string; port: number; addresses?: readonly string[] },
upstream: Egress | null,
onReady: (socket: Socket) => void,
onError: (error: Error) => void,
) {
if (!upstream) {
connectInTurn(target, onReady, onError);
return;
}
const via = upstreamAddress(upstream);
const socket = connect(via.port, via.host, () => {
const auth = basic(upstream.username, upstream.password);
// An IPv6 host is bracketed in an authority: `CONNECT ::1:443` cannot be read.
const host = isIP(target.host) === 6 ? `[${target.host}]` : target.host;
socket.write(
`CONNECT ${host}:${target.port} HTTP/1.1\r\nHost: ${host}:${target.port}\r\n${auth ? `Proxy-Authorization: ${auth}\r\n` : ""}\r\n`,
);
});
let head = Buffer.alloc(0);
const onData = (chunk: Buffer) => {
head = Buffer.concat([head, chunk]);
const end = head.indexOf("\r\n\r\n");
if (end === -1) return;
socket.off("data", onData);
if (!/^HTTP\/1\.[01] 200/.test(head.subarray(0, end).toString())) {
socket.destroy();
onError(new Error("The upstream proxy refused the tunnel."));
return;
}
const rest = head.subarray(end + 4);
if (rest.length > 0) socket.unshift(rest);
onReady(socket);
};
socket.on("data", onData);
socket.once("error", onError);
}
export type EgressFilterOptions = {
env?: Record<string, string | undefined>;
/** 0 picks a free port. */
port?: number;
/** Point the shell's commands at the filter (see `egressShellEnvironment`). */
forShell?: boolean;
};
/*
* NOT THIS PROCESS'S ENVIRONMENT. Bun's `http.request` follows HTTP_PROXY and ignores every option
* that should stop it (measured: `agent: false`, a fresh Agent and `createConnection` all still went
* to the proxy). With the filter's own address in this process's HTTP_PROXY, every plain-HTTP request
* the filter forwarded came straight back into the filter, without end, and a page waiting behind
* one never loaded. So the shell gets the address from here, and nothing else in this process does.
*/
let shellProxy: string | null = null;
/** The proxy variables a shell command runs with while the filter is up: the filter, and no other. */
export function egressShellEnvironment(): Record<string, string> {
if (!shellProxy) return {};
return {
HTTP_PROXY: shellProxy,
HTTPS_PROXY: shellProxy,
http_proxy: shellProxy,
https_proxy: shellProxy,
// The computer's own loopback services are not the network.
NO_PROXY: "127.0.0.1,localhost,::1",
no_proxy: "127.0.0.1,localhost,::1",
};
}
/**
* Start the filter on 127.0.0.1.
*
* Idempotent: a second call answers the running filter. Chains to the Bot's configured upstream
* (`EGRESS_PROXY_<BOT>` / `EGRESS_PROXY_DEFAULT`), so the per-Bot egress identity is kept.
*/
export async function startEgressFilter(
options: EgressFilterOptions = {},
): Promise<{
/** The shell's listener. */
port: number;
/** The browsers' listener, which `egressFor` points a browser at. */
browserPort: number;
url: string;
stop: () => Promise<void>;
}> {
const env = options.env ?? process.env;
policyRequired = !(
env.EGRESS_POLICY_REQUIRED === "0" || env.EGRESS_POLICY_REQUIRED === "false"
);
if (filter) {
return {
port: filter.port,
browserPort: filter.browserPort,
url: `http://127.0.0.1:${filter.port}`,
stop: stopEgressFilter,
};
}
const secret = randomBytes(24).toString("base64url");
/*
* TWO LISTENERS, ONE FOR BROWSERS. A browser's connection carries its owner only if the proxy asks
* for it, and this filter used to ask nobody, so every browser's connections arrived anonymous and
* were judged by every policy on the computer, strictest first: on a computer shared by Bots, or by
* a Bot and a person's browser, a Bot allowed to reach an internal service was refused because
* another browser on the computer was not. The browsers' listener therefore asks every connection
* for its credentials, and each browser's connections are judged by its own policy alone. The
* shell's commands keep a listener of their own that asks for nothing, judged as before: their
* proxy variable has no credentials in it, and must not, since any command could read them.
*/
const listener = (asks: boolean) => {
const server = createServer(async (request, response) => {
await handlePlain(request, response, asks);
});
server.on(
"connect",
async (request: IncomingMessage, client: Socket, head: Buffer) => {
await handleConnect(request, client, head, asks);
},
);
return server;
};
const handlePlain = async (
request: IncomingMessage,
response: import("node:http").ServerResponse,
asks: boolean,
) => {
// A plain-HTTP request through a proxy names the absolute URL.
let target: URL;
try {
target = new URL(request.url ?? "");
} catch {
response.writeHead(400).end("A proxy request names an absolute URL.");
return;
}
const botId = botFromProxyAuthorization(
request.headers["proxy-authorization"] as string | undefined,
secret,
);
if (asks && !botId) {
response
.writeHead(407, {
"proxy-authenticate": 'Basic realm="OpenBot"',
"content-type": "text/plain",
connection: "close",
})
.end();
return;
}
const port = Number(
target.port || (target.protocol === "https:" ? 443 : 80),
);
const upstream = upstreamFor(botId ?? "", env);
const decision = await decide(botId, target.hostname, port, !upstream);
if (!decision.allowed) {
response
.writeHead(403, {
"content-type": "text/plain",
"x-openbot-egress": "refused",
})
.end(decision.reason);
return;
}
forwardPlain(request, response, target, upstream, decision.addresses);
};
const handleConnect = async (
request: IncomingMessage,
client: Socket,
head: Buffer,
asks: boolean,
) => {
const [host = "", portText = "443"] = splitHostPort(request.url ?? "");
const port = Number(portText);
const botId = botFromProxyAuthorization(
request.headers["proxy-authorization"] as string | undefined,
secret,
);
client.on("error", () => undefined);
if (asks && !botId) {
client.end(PROXY_CHALLENGE);
return;
}
if (!host || !Number.isInteger(port) || port < 1 || port > 65535) {
refuse(client, "A CONNECT names host:port.");
return;
}
const upstream = upstreamFor(botId ?? "", env);
const decision = await decide(botId, host, port, !upstream);
if (!decision.allowed) {
refuse(client, decision.reason);
return;
}
tunnel(
{
host,
port,
...(upstream ? {} : { addresses: decision.addresses }),
},
upstream,
(remote) => {
client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
if (head.length > 0) remote.write(head);
remote.pipe(client);
client.pipe(remote);
remote.on("error", () => client.destroy());
},
() => {
client.end("HTTP/1.1 502 Bad Gateway\r\n\r\n");
},
);
};
const listen = async (server: Server, port: number): Promise<number> => {
await new Promise<void>((resolve, reject) => {
server.once("error", reject);
server.listen(port, "127.0.0.1", () => resolve());
});
const address = server.address();
return typeof address === "object" && address ? address.port : 0;
};
const shell = listener(false);
const browsers = listener(true);
const port = await listen(shell, options.port ?? 0);
const browserPort = await listen(browsers, 0).catch(async (error) => {
await new Promise<void>((resolve) => shell.close(() => resolve()));
throw error;
});
filter = { port, browserPort, secret, servers: [shell, browsers] };
const url = `http://127.0.0.1:${port}`;
if (options.forShell) shellProxy = url;
return { port, browserPort, url, stop: stopEgressFilter };
}
export async function stopEgressFilter(): Promise<void> {
const running = filter;
filter = null;
shellProxy = null;
policies.clear();
if (running) {
await Promise.all(
running.servers.map(
(server) =>
new Promise<void>((resolve) => server.close(() => resolve())),
),
);
}
}
/** `URL.hostname` keeps an IPv6 address's brackets, and a socket given them looks the name up. */
function unbracketed(hostname: string): string {
return hostname.replace(/^\[|\]$/g, "");
}
function splitHostPort(value: string): [string, string] {
if (value.startsWith("[")) {
const end = value.indexOf("]");
return [value.slice(1, end), value.slice(end + 2) || "443"];
}
const colon = value.lastIndexOf(":");
return colon === -1
? [value, "443"]
: [value.slice(0, colon), value.slice(colon + 1)];
}
function forwardPlain(
request: IncomingMessage,
response: import("node:http").ServerResponse,
target: URL,
upstream: Egress | null,
addresses?: readonly string[],
) {
const headers = { ...request.headers };
delete headers["proxy-authorization"];
delete headers["proxy-connection"];
const via = upstream ? upstreamAddress(upstream) : null;
const auth = upstream
? basic(upstream.username, upstream.password)
: undefined;
const outbound = httpRequest(
{
// Reached through the checked addresses only (see `pinnedTo`): a second lookup could answer
// something else. The Host header still names the site.
host: via ? via.host : unbracketed(target.hostname),
port: via ? via.port : Number(target.port || 80),
...(via ? {} : (pinnedTo(addresses) as object)),
method: request.method,
path: via ? target.toString() : `${target.pathname}${target.search}`,
headers: { ...headers, ...(auth ? { "proxy-authorization": auth } : {}) },
},
(answer) => {
response.writeHead(answer.statusCode ?? 502, answer.headers);
answer.pipe(response);
},
);
outbound.on("error", () => {
if (!response.headersSent) response.writeHead(502);
response.end();
});
request.pipe(outbound);
}
/**
* `PUT /egress-policy` on the computer: the API server pushing a Bot's policy.
*
* Mounted by index.ts after its token check. The body is `{ policy: EgressPolicy | null }`; null
* removes the Bot's policy, which returns it to "nothing pushed".
*/
export async function handleEgressPolicyRequest(
botId: string,
request: Request,
): Promise<Response> {
const body = (await request.json().catch(() => null)) as {
policy?: unknown;
} | null;
if (!body || !("policy" in body)) {
return Response.json({ error: "Expected { policy }." }, { status: 400 });
}
if (body.policy === null) {
setEgressPolicy(botId, null);
return Response.json({ botId, policy: null, filtering: filter !== null });
}
const parsed = parseEgressPolicy(body.policy);
if (!parsed.ok)
return Response.json({ error: parsed.error }, { status: 400 });
setEgressPolicy(botId, parsed.policy);
return Response.json({
botId,
policy: parsed.policy,
filtering: filter !== null,
});
}