@clipboard-health/clearance 1.0.0

package/README.md

@@ -0,0 +1,219 @@
+# @clipboard-health/clearance
+
+HTTP/HTTPS clearance for deny-by-default sandboxes.
+
+The proxy ships with **zero compiled-in opinions** about which hosts to allow.
+Bring your own list — either inline via env or by pointing at one or more
+plain-text files. Teams typically check those files into their repo so
+everyone shares the same baseline.
+
+## Install
+
+```bash
+npm install -g @clipboard-health/clearance
+```
+
+This installs two binaries: `clearance` (the proxy) and `clearance-ensure`
+(idempotent daemon launcher).
+
+## Raw proxy usage
+
+```bash
+CLEARANCE_ALLOW_HOSTS=api.example.com clearance
+```
+
+Then point tools at `http://127.0.0.1:19999` with `HTTP_PROXY` and
+`HTTPS_PROXY`.
+
+By default the proxy listens on `127.0.0.1:19999`, allows destination port
+`443`, and blocks private, loopback, link-local, multicast, documentation,
+and other non-public IP ranges after DNS resolution.
+
+If neither `CLEARANCE_ALLOW_HOSTS` nor `CLEARANCE_ALLOW_HOSTS_FILES` is
+set, the proxy refuses to start.
+
+### Allow-host files
+
+A file is a plain-text list of hosts, one per line. Blank lines are ignored,
+`#` introduces a comment to end-of-line, and trailing dots / wildcard
+prefixes (`*.example.com`) are normalized.
+
+```text
+# AI agents
+api.openai.com
+api.anthropic.com
+
+# Source code
+github.com
+api.github.com
+*.githubusercontent.com
+```
+
+Point at one or more files via `CLEARANCE_ALLOW_HOSTS_FILES` using your
+platform's PATH delimiter — `:` on macOS/Linux, `;` on Windows. The values
+from `CLEARANCE_ALLOW_HOSTS`, all referenced files, and any duplicates
+are concatenated and deduped.
+
+```bash
+CLEARANCE_ALLOW_HOSTS_FILES="$REPO/clearance-allow-hosts:$HOME/.config/clearance/personal-hosts" \
+  clearance
+```
+
+This is how teams share a baseline: check a `team-allow-hosts` file into
+your repo, and let individuals layer a personal file on top via the same
+env var.
+
+### Configuration reference
+
+<!-- markdownlint-disable MD060 -->
+
+| Variable                      | Default     | Notes                                                                                                     |
+| ----------------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
+| `CLEARANCE_ALLOW_HOSTS`       | _(unset)_   | Comma- or whitespace-separated exact hosts and wildcard suffixes.                                         |
+| `CLEARANCE_ALLOW_HOSTS_FILES` | _(unset)_   | PATH-delimited paths (`:` macOS/Linux, `;` Windows) to plain-text host files (`#` comments, blank lines). |
+| `CLEARANCE_ALLOW_PORTS`       | `443`       | Comma- or whitespace-separated TCP ports.                                                                 |
+| `CLEARANCE_LISTEN_HOST`       | `127.0.0.1` | Bind host.                                                                                                |
+| `CLEARANCE_PORT`              | `19999`     | Bind port.                                                                                                |
+| `CLEARANCE_DNS_TTL_MS`        | `60000`     | In-process DNS cache TTL.                                                                                 |
+| `CLEARANCE_IDLE_TIMEOUT_MS`   | `120000`    | Socket idle timeout.                                                                                      |
+| `CLEARANCE_MAX_SOCKETS`       | `1024`      | Inbound connection cap and outbound HTTP agent cap.                                                       |
+| `CLEARANCE_ALLOW_PRIVATE_IPS` | _(unset)_   | Set to `1` to disable private/non-public IP blocking for local testing.                                   |
+
+<!-- markdownlint-enable MD060 -->
+
+## Managed proxy: `clearance-ensure`
+
+`clearance-ensure` checks `127.0.0.1:19999`; if no proxy is listening it
+spawns one detached using the same env vars and waits for it to bind. Logs
+live at `${XDG_CACHE_HOME:-$HOME/.cache}/clearance/clearance.log`,
+pid at `…/clearance.pid`.
+
+```bash
+CLEARANCE_ALLOW_HOSTS_FILES="$REPO/clearance-allow-hosts" clearance-ensure
+```
+
+To stop or restart the managed proxy after editing your allow-host files:
+
+```bash
+kill "$(cat "${XDG_CACHE_HOME:-$HOME/.cache}/clearance/clearance.pid")"
+```
+
+## Safehouse integration (macOS)
+
+Safehouse uses macOS sandbox profiles, so this section is for macOS hosts
+only. Safehouse allows network access by default for agent compatibility.
+To force a wrapped agent through this proxy, run the proxy outside
+Safehouse, then append a Safehouse profile that denies direct remote
+egress while leaving `localhost` open for `http://127.0.0.1:19999`.
+
+The package ships a `safehouse-clearance` wrapper plus the matching
+`clearance.env` and `clearance-only.sb` profile. After a global install,
+the wrapper lives at `$(npm root -g)/@clipboard-health/clearance/safehouse/safehouse-clearance`.
+It ensures the proxy is running, then `exec`s safehouse with the env file and
+sandbox profile alongside it. It does **not** parse or rewrite your
+arguments — anything you pass is forwarded verbatim, so put any safehouse
+flags before the agent command:
+
+```bash
+SAFEHOUSE_CLEARANCE="$(npm root -g)/@clipboard-health/clearance/safehouse/safehouse-clearance"
+
+"$SAFEHOUSE_CLEARANCE" \
+  --enable=cloud-credentials --env-pass=AWS_PROFILE,AWS_REGION \
+  -- codex --dangerously-bypass-approvals-and-sandbox
+```
+
+For day-to-day agent use, set `CLEARANCE_ALLOW_HOSTS_FILES` to point at
+your team's checked-in file (and optionally a personal file), then add
+shell aliases:
+
+```bash
+SAFEHOUSE_CLEARANCE="$(npm root -g)/@clipboard-health/clearance/safehouse/safehouse-clearance"
+export CLEARANCE_ALLOW_HOSTS_FILES="$HOME/code/<your-repo>/clearance-allow-hosts:$HOME/.config/clearance/personal-allow-hosts"
+
+alias codex-proxy="$SAFEHOUSE_CLEARANCE codex --dangerously-bypass-approvals-and-sandbox"
+alias claude-proxy="$SAFEHOUSE_CLEARANCE claude --enable-auto-mode"
+```
+
+For AWS SSO work, log in on the host first, then layer the safehouse cloud
+credentials flag through the wrapper:
+
+```bash
+aws sso login --profile <profile>
+AWS_PROFILE=<profile> "$SAFEHOUSE_CLEARANCE" \
+  --enable=cloud-credentials --env-pass=AWS_PROFILE,AWS_REGION,AWS_SDK_LOAD_CONFIG,AWS_CONFIG_FILE,AWS_SHARED_CREDENTIALS_FILE,AWS_CA_BUNDLE \
+  -- codex --dangerously-bypass-approvals-and-sandbox
+```
+
+Make sure your allow-host file includes the AWS endpoints you need
+(typically `*.amazonaws.com`, `*.api.aws`, `*.awsapps.com`, `*.ecr.aws`).
+
+### Manual setup
+
+If you'd rather not depend on the bundled assets, you can build the same
+setup by hand.
+
+```bash
+mkdir -p ~/.config/agent-safehouse
+```
+
+```bash
+cat > ~/.config/agent-safehouse/clearance-only.sb <<'SB'
+;; Force remote network egress through the local clearance while keeping
+;; localhost available for local-only agent workflows.
+(deny network-outbound
+  (remote ip "*:*")
+  (remote tcp "*:*")
+  (remote udp "*:*"))
+
+(allow network-outbound
+  (remote ip "localhost:*")
+  (remote tcp "localhost:*")
+  (remote udp "localhost:*"))
+SB
+```
+
+```bash
+cat > ~/.config/agent-safehouse/clearance.env <<'ENV'
+HTTP_PROXY="http://127.0.0.1:19999"
+HTTPS_PROXY="http://127.0.0.1:19999"
+ALL_PROXY="http://127.0.0.1:19999"
+NO_PROXY="localhost,127.0.0.1,::1"
+
+http_proxy="${HTTP_PROXY}"
+https_proxy="${HTTPS_PROXY}"
+all_proxy="${ALL_PROXY}"
+no_proxy="${NO_PROXY}"
+ENV
+```
+
+Then run the wrapped command with Safehouse:
+
+```bash
+safehouse \
+  --env="$HOME/.config/agent-safehouse/clearance.env" \
+  --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \
+  -- <agent-command>
+```
+
+Do not pass API-key environment variables just for proxying. The env file
+only supplies proxy settings; agents should continue to use their normal
+auth/config stores.
+
+Quick checks:
+
+```bash
+# Should use the proxy and usually return 401 without auth.
+safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \
+  --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \
+  -- curl -I https://api.openai.com/v1/models
+
+# Should fail because this bypasses the proxy and tries direct egress.
+safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \
+  --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \
+  -- curl --noproxy '*' -I https://api.openai.com/v1/models
+
+# Should be denied by the proxy unless example.com is in your allow-host list.
+safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \
+  --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \
+  -- curl -I https://example.com
+```

package/bin/ensure.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../src/ensureCli.js";

package/bin/run.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../src/cli.js";

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@clipboard-health/clearance",
+  "version": "1.0.0",
+  "description": "Localhost HTTP/HTTPS egress proxy with hostname allow-listing, plus a macOS Safehouse integration for sandboxed agent processes.",
+  "keywords": [
+    "agent",
+    "allowlist",
+    "egress",
+    "proxy",
+    "safehouse",
+    "sandbox"
+  ],
+  "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClipboardHealth/core-utils.git",
+    "directory": "packages/clearance"
+  },
+  "bin": {
+    "clearance": "./bin/run.js",
+    "clearance-ensure": "./bin/ensure.js"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "typings": "./src/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "tslib": "2.8.1"
+  },
+  "types": "./src/index.d.ts",
+  "module": "./src/index.js"
+}

package/safehouse/clearance-only.sb

@@ -0,0 +1,11 @@
+;; Force remote network egress through the local clearance while keeping
+;; localhost available for local-only agent workflows.
+(deny network-outbound
+  (remote ip "*:*")
+  (remote tcp "*:*")
+  (remote udp "*:*"))
+
+(allow network-outbound
+  (remote ip "localhost:*")
+  (remote tcp "localhost:*")
+  (remote udp "localhost:*"))

package/safehouse/clearance.env

@@ -0,0 +1,9 @@
+HTTP_PROXY="http://127.0.0.1:19999"
+HTTPS_PROXY="http://127.0.0.1:19999"
+ALL_PROXY="http://127.0.0.1:19999"
+NO_PROXY="localhost,127.0.0.1,::1"
+
+http_proxy="${HTTP_PROXY}"
+https_proxy="${HTTPS_PROXY}"
+all_proxy="${ALL_PROXY}"
+no_proxy="${NO_PROXY}"

package/safehouse/safehouse-clearance

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+source_path="${BASH_SOURCE[0]}"
+while [ -h "$source_path" ]; do
+  source_dir="$(cd -P "$(dirname "$source_path")" >/dev/null 2>&1 && pwd)"
+  link_target="$(readlink "$source_path")"
+  case "$link_target" in
+    /*) source_path="$link_target" ;;
+    *) source_path="$source_dir/$link_target" ;;
+  esac
+done
+
+script_dir="$(cd -P "$(dirname "$source_path")" >/dev/null 2>&1 && pwd)"
+package_dir="$(cd -P "$script_dir/.." >/dev/null 2>&1 && pwd)"
+
+node "$package_dir/bin/ensure.js" >&2
+
+exec safehouse \
+  --env="$script_dir/clearance.env" \
+  --append-profile="$script_dir/clearance-only.sb" \
+  "$@"

package/src/allowlist.d.ts

@@ -0,0 +1,5 @@
+export interface ResolveAllowlistInput {
+    env: NodeJS.ProcessEnv;
+    readFile?: (path: string) => string;
+}
+export declare function resolveAllowlist(input: ResolveAllowlistInput): readonly string[];

package/src/allowlist.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { delimiter as PATH_DELIMITER } from "node:path";
+import { normalizeRule, parseList } from "./hostRule.js";
+const COMMENT_PREFIX = "#";
+export function resolveAllowlist(input) {
+    const readFile = input.readFile ?? defaultReadFile;
+    const fromEnv = parseList(input.env["CLEARANCE_ALLOW_HOSTS"]);
+    const fromFiles = parseFilesEnv(input.env["CLEARANCE_ALLOW_HOSTS_FILES"]).flatMap((path) => readHostsFile({ path, readFile }));
+    const normalized = [...fromEnv, ...fromFiles]
+        .map(normalizeRule)
+        .filter((rule) => rule !== undefined);
+    if (normalized.length === 0) {
+        throw new Error("Set CLEARANCE_ALLOW_HOSTS or CLEARANCE_ALLOW_HOSTS_FILES, e.g. CLEARANCE_ALLOW_HOSTS=api.example.com");
+    }
+    return [...new Set(normalized)];
+}
+function parseFilesEnv(value) {
+    if (value === undefined) {
+        return [];
+    }
+    return value
+        .split(PATH_DELIMITER)
+        .map((path) => path.trim())
+        .filter((path) => path.length > 0);
+}
+function readHostsFile(input) {
+    let content;
+    try {
+        content = input.readFile(input.path);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read CLEARANCE_ALLOW_HOSTS_FILES path ${JSON.stringify(input.path)}: ${message}`, { cause: error });
+    }
+    const hosts = [];
+    for (const rawLine of content.split("\n")) {
+        const [beforeComment = ""] = rawLine.split(COMMENT_PREFIX, 1);
+        const trimmed = beforeComment.trim();
+        if (trimmed.length > 0) {
+            hosts.push(trimmed);
+        }
+    }
+    return hosts;
+}
+function defaultReadFile(path) {
+    return readFileSync(path, "utf8");
+}
+//# sourceMappingURL=allowlist.js.map

package/src/allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../../../../packages/clearance/src/allowlist.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,SAAS,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEzD,MAAM,cAAc,GAAG,GAAG,CAAC;AAO3B,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,eAAe,CAAC;IACnD,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CACzF,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAClC,CAAC;IACF,MAAM,UAAU,GAAG,CAAC,GAAG,OAAO,EAAE,GAAG,SAAS,CAAC;SAC1C,GAAG,CAAC,aAAa,CAAC;SAClB,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAExD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,sGAAsG,CACvG,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,aAAa,CAAC,KAAyB;IAC9C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,KAAK;SACT,KAAK,CAAC,cAAc,CAAC;SACrB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAOD,SAAS,aAAa,CAAC,KAAyB;IAC9C,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,IAAI,KAAK,CACb,mDAAmD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,EAC3F,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,CAAC,aAAa,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;QAC9D,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,IAAY;IACnC,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC"}

package/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { startClearanceFromEnv } from "./index.js";
+startClearanceFromEnv({ env: process.env }).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 2;
+});
+//# sourceMappingURL=cli.js.map

package/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../../packages/clearance/src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,qBAAqB,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACnE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/src/ensureCli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/ensureCli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { ensureClearance } from "./launcher.js";
+ensureClearance({
+    logger: (message) => {
+        process.stderr.write(`${message}\n`);
+    },
+}).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exit(2);
+});
+//# sourceMappingURL=ensureCli.js.map

package/src/ensureCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureCli.js","sourceRoot":"","sources":["../../../../packages/clearance/src/ensureCli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,eAAe,CAAC;IACd,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE;QAClB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACvC,CAAC;CACF,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC1B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/src/hostRule.d.ts

@@ -0,0 +1,4 @@
+export declare function normalizeRule(rule: string): string | undefined;
+export declare function normalizeRules(rules: readonly string[]): string[];
+export declare function parseList(input: string | undefined): string[];
+export declare function normalizeHost(host: string): string | undefined;

package/src/hostRule.js

@@ -0,0 +1,62 @@
+import * as net from "node:net";
+import { domainToASCII } from "node:url";
+export function normalizeRule(rule) {
+    const trimmed = rule.trim().toLowerCase().replace(/\.$/, "");
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    if (trimmed.startsWith("*.")) {
+        const suffix = normalizeHost(trimmed.slice(2));
+        if (suffix === undefined || net.isIP(suffix) !== 0) {
+            return undefined;
+        }
+        return `*.${suffix}`;
+    }
+    return normalizeHost(trimmed);
+}
+export function normalizeRules(rules) {
+    const normalizedRules = [];
+    for (const rule of rules) {
+        const normalizedRule = normalizeRule(rule);
+        if (normalizedRule !== undefined) {
+            normalizedRules.push(normalizedRule);
+        }
+    }
+    return [...new Set(normalizedRules)];
+}
+export function parseList(input) {
+    if (input === undefined) {
+        return [];
+    }
+    return input
+        .split(/[\s,]+/)
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+export function normalizeHost(host) {
+    const trimmed = host.trim().toLowerCase().replace(/\.$/, "");
+    const isBracketed = trimmed.startsWith("[") && trimmed.endsWith("]");
+    const unbracketed = isBracketed ? trimmed.slice(1, -1) : trimmed;
+    if (unbracketed.length === 0 ||
+        unbracketed.includes("%") ||
+        unbracketed.includes("/") ||
+        /\s/.test(unbracketed)) {
+        return undefined;
+    }
+    if (net.isIP(unbracketed) !== 0) {
+        return unbracketed;
+    }
+    // Brackets are reserved for IP literals; bracketed non-IPs are malformed.
+    if (isBracketed) {
+        return undefined;
+    }
+    if (unbracketed.includes(":") || unbracketed.includes("@")) {
+        return undefined;
+    }
+    const ascii = domainToASCII(unbracketed);
+    if (ascii.length === 0 || ascii.includes("*")) {
+        return undefined;
+    }
+    return ascii;
+}
+//# sourceMappingURL=hostRule.js.map

package/src/hostRule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostRule.js","sourceRoot":"","sources":["../../../../packages/clearance/src/hostRule.ts"],"names":[],"mappings":"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"}

package/src/index.d.ts

@@ -0,0 +1,36 @@
+import type { LookupAddress } from "node:dns";
+import * as http from "node:http";
+export { resolveAllowlist, type ResolveAllowlistInput } from "./allowlist.js";
+export { type ClearanceCheckInput, type ClearanceListenerCheck, type ClearanceSpawner, ensureClearance, type EnsureClearanceInput, type EnsureClearanceResult, isClearanceListening, spawnClearance, type SpawnClearanceInput, } from "./launcher.js";
+export declare const CLEARANCE_PACKAGE_NAME = "@clipboard-health/clearance";
+export interface ClearanceConfig {
+    allowedHosts: readonly string[];
+    allowedPorts: readonly number[];
+    dnsTtlMs: number;
+    idleTimeoutMs: number;
+    listenHost: string;
+    maxSockets: number;
+    port: number;
+    shouldBlockPrivateIps: boolean;
+}
+export interface ClearanceLogger {
+    info(message: string): void;
+}
+export type DnsLookup = (hostname: string) => Promise<readonly LookupAddress[]>;
+export interface CreateClearanceServerOptions {
+    allowedHosts: readonly string[];
+    allowedPorts?: readonly number[];
+    dnsLookup?: DnsLookup;
+    dnsTtlMs?: number;
+    idleTimeoutMs?: number;
+    logger?: ClearanceLogger;
+    maxSockets?: number;
+    shouldBlockPrivateIps?: boolean;
+}
+export interface StartClearanceFromEnvInput {
+    env: NodeJS.ProcessEnv;
+    logger?: ClearanceLogger;
+}
+export declare function resolveClearanceConfig(env: NodeJS.ProcessEnv): ClearanceConfig;
+export declare function createClearanceServer(options: CreateClearanceServerOptions): http.Server;
+export declare function startClearanceFromEnv(input: StartClearanceFromEnvInput): Promise<http.Server>;

package/src/index.js

@@ -0,0 +1,509 @@
+import { Buffer } from "node:buffer";
+import * as dns from "node:dns/promises";
+import * as http from "node:http";
+import * as net from "node:net";
+import { resolveAllowlist } from "./allowlist.js";
+import { normalizeHost, normalizeRules, parseList } from "./hostRule.js";
+export { resolveAllowlist } from "./allowlist.js";
+export { ensureClearance, isClearanceListening, spawnClearance, } from "./launcher.js";
+export const CLEARANCE_PACKAGE_NAME = "@clipboard-health/clearance";
+const DEFAULT_LISTEN_HOST = "127.0.0.1";
+const DEFAULT_PORT = 19_999;
+const DEFAULT_ALLOWED_PORTS = [443];
+const DEFAULT_DNS_TTL_MS = 60_000;
+const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_SOCKETS = 1024;
+const SERVER_HEADERS_TIMEOUT_MS = 15_000;
+const SERVER_KEEP_ALIVE_TIMEOUT_MS = 5000;
+const NOOP_LOGGER = {
+    info: noop,
+};
+const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+const PRIVATE_IPV4_RANGES = [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+];
+const PRIVATE_IPV6_RANGES = [
+    ["::", 128],
+    ["::1", 128],
+    ["::", 96],
+    ["::ffff:0:0", 96],
+    ["64:ff9b::", 96],
+    ["64:ff9b:1::", 48],
+    ["100::", 64],
+    ["2001::", 23],
+    ["2001:db8::", 32],
+    ["2002::", 16],
+    ["fc00::", 7],
+    ["fe80::", 10],
+    ["ff00::", 8],
+];
+const PRIVATE_IPV4_BLOCK_LIST = createIpBlockList(PRIVATE_IPV4_RANGES, "ipv4");
+const PRIVATE_IPV6_BLOCK_LIST = createIpBlockList(PRIVATE_IPV6_RANGES, "ipv6");
+export function resolveClearanceConfig(env) {
+    const allowedHosts = resolveAllowlist({ env });
+    return {
+        allowedHosts,
+        allowedPorts: normalizeAllowedPorts(parseList(env["CLEARANCE_ALLOW_PORTS"] ?? DEFAULT_ALLOWED_PORTS.join(","))),
+        dnsTtlMs: parseIntegerEnv(env, "CLEARANCE_DNS_TTL_MS", DEFAULT_DNS_TTL_MS, 0, Number.MAX_SAFE_INTEGER),
+        idleTimeoutMs: parseIntegerEnv(env, "CLEARANCE_IDLE_TIMEOUT_MS", DEFAULT_IDLE_TIMEOUT_MS, 1, Number.MAX_SAFE_INTEGER),
+        listenHost: env["CLEARANCE_LISTEN_HOST"] ?? DEFAULT_LISTEN_HOST,
+        maxSockets: parseIntegerEnv(env, "CLEARANCE_MAX_SOCKETS", DEFAULT_MAX_SOCKETS, 1, Number.MAX_SAFE_INTEGER),
+        port: parseIntegerEnv(env, "CLEARANCE_PORT", DEFAULT_PORT, 1, 65_535),
+        shouldBlockPrivateIps: env["CLEARANCE_ALLOW_PRIVATE_IPS"] !== "1",
+    };
+}
+export function createClearanceServer(options) {
+    const state = createProxyState(options);
+    const server = http.createServer((req, res) => {
+        void handleHttpRequest({ req, res, state });
+    });
+    server.on("connect", (req, clientSocket, head) => {
+        /* v8 ignore next @preserve */
+        if (!isNetSocket(clientSocket)) {
+            socketReply(clientSocket, 400, "Bad Request", "Bad CONNECT socket\n");
+            return;
+        }
+        void handleConnect({ clientSocket, head, req, state });
+    });
+    server.on("clientError", (_error, socket) => {
+        socketReply(socket, 400, "Bad Request", "Bad Request\n");
+    });
+    server.headersTimeout = SERVER_HEADERS_TIMEOUT_MS;
+    server.keepAliveTimeout = SERVER_KEEP_ALIVE_TIMEOUT_MS;
+    server.maxConnections = state.maxSockets;
+    server.once("close", () => {
+        state.httpAgent.destroy();
+    });
+    return server;
+}
+export async function startClearanceFromEnv(input) {
+    const { env } = input;
+    const logger = input.logger ?? console;
+    const config = resolveClearanceConfig(env);
+    const server = createClearanceServer({
+        allowedHosts: config.allowedHosts,
+        allowedPorts: config.allowedPorts,
+        dnsTtlMs: config.dnsTtlMs,
+        idleTimeoutMs: config.idleTimeoutMs,
+        logger,
+        maxSockets: config.maxSockets,
+        shouldBlockPrivateIps: config.shouldBlockPrivateIps,
+    });
+    await listen(server, config);
+    logger.info(`clearance listening on http://${config.listenHost}:${config.port}`);
+    logger.info(`allowed hosts: ${config.allowedHosts.join(", ")}`);
+    logger.info(`allowed ports: ${config.allowedPorts.join(",")}`);
+    return server;
+}
+function createProxyState(options) {
+    const allowedHosts = normalizeRules(options.allowedHosts);
+    if (allowedHosts.length === 0) {
+        throw new Error("allowedHosts must include at least one valid host rule");
+    }
+    const maxSockets = options.maxSockets ?? DEFAULT_MAX_SOCKETS;
+    return {
+        allowedHosts,
+        allowedPorts: new Set(normalizeAllowedPorts(options.allowedPorts ?? DEFAULT_ALLOWED_PORTS)),
+        dnsCache: new Map(),
+        dnsLookup: options.dnsLookup ?? defaultDnsLookup,
+        dnsTtlMs: options.dnsTtlMs ?? DEFAULT_DNS_TTL_MS,
+        httpAgent: new http.Agent({ keepAlive: true, maxSockets }),
+        idleTimeoutMs: options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS,
+        logger: options.logger ?? NOOP_LOGGER,
+        maxSockets,
+        shouldBlockPrivateIps: options.shouldBlockPrivateIps ?? true,
+    };
+}
+async function listen(server, config) {
+    await new Promise((resolve, reject) => {
+        function onError(error) {
+            server.off("listening", onListening);
+            reject(error);
+        }
+        function onListening() {
+            server.off("error", onError);
+            resolve();
+        }
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(config.port, config.listenHost);
+    });
+}
+async function handleConnect(input) {
+    const { clientSocket, head, req, state } = input;
+    /* v8 ignore next @preserve */
+    clientSocket.on("error", noop);
+    /* v8 ignore next @preserve */
+    clientSocket.setTimeout(state.idleTimeoutMs, () => {
+        clientSocket.destroy(new Error("idle timeout"));
+    });
+    const parsed = parseConnectTarget(String(req.url));
+    if (parsed === undefined) {
+        socketReply(clientSocket, 400, "Bad Request", "Bad CONNECT target\n");
+        return;
+    }
+    let target;
+    try {
+        target = await authorize({ host: parsed.host, port: parsed.port, state });
+    }
+    catch (error) {
+        const reason = errorMessage(error);
+        logDecision(state.logger, {
+            decision: "DENY",
+            hostname: parsed.host,
+            method: "CONNECT",
+            port: parsed.port,
+            reason,
+        });
+        socketReply(clientSocket, 403, "Forbidden", `${reason}\n`);
+        return;
+    }
+    let isEstablished = false;
+    const upstream = net.createConnection({
+        family: target.family,
+        host: target.address,
+        port: target.port,
+    });
+    upstream.setNoDelay(true);
+    /* v8 ignore next @preserve */
+    upstream.setTimeout(state.idleTimeoutMs, () => {
+        upstream.destroy(new Error("idle timeout"));
+    });
+    upstream.once("connect", () => {
+        isEstablished = true;
+        logDecision(state.logger, {
+            address: target.address,
+            decision: "ALLOW",
+            hostname: target.hostname,
+            method: "CONNECT",
+            port: target.port,
+        });
+        clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+        if (head.length > 0) {
+            upstream.write(head);
+        }
+        upstream.pipe(clientSocket);
+        clientSocket.pipe(upstream);
+    });
+    upstream.once("error", (error) => {
+        /* v8 ignore else @preserve */
+        if (!isEstablished) {
+            socketReply(clientSocket, 502, "Bad Gateway", `${error.message}\n`);
+            return;
+        }
+        /* v8 ignore next @preserve */
+        clientSocket.destroy(error);
+    });
+    clientSocket.once("close", () => {
+        upstream.destroy();
+    });
+}
+async function handleHttpRequest(input) {
+    const { req, res, state } = input;
+    const rawUrl = String(req.url);
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        httpReply(res, 400, "HTTP proxy requests must use absolute URLs\n");
+        return;
+    }
+    if (url.protocol !== "http:") {
+        httpReply(res, 400, "Use CONNECT for HTTPS\n");
+        return;
+    }
+    const port = url.port.length > 0 ? Number(url.port) : 80;
+    const method = String(req.method);
+    let target;
+    try {
+        target = await authorize({ host: url.hostname, port, state });
+    }
+    catch (error) {
+        const reason = errorMessage(error);
+        logDecision(state.logger, {
+            decision: "DENY",
+            hostname: url.hostname,
+            method,
+            port,
+            reason,
+        });
+        httpReply(res, 403, `${reason}\n`);
+        return;
+    }
+    const headers = stripHopByHopHeaders(req.headers);
+    headers.host = url.host;
+    const upstreamReq = http.request({
+        agent: state.httpAgent,
+        family: target.family,
+        headers,
+        hostname: target.address,
+        method: req.method,
+        path: `${url.pathname}${url.search}`,
+        port: target.port,
+    }, (upstreamRes) => {
+        logDecision(state.logger, {
+            address: target.address,
+            decision: "ALLOW",
+            hostname: target.hostname,
+            method,
+            port: target.port,
+        });
+        /* v8 ignore next @preserve */
+        const statusCode = upstreamRes.statusCode ?? 502;
+        res.writeHead(statusCode, stripHopByHopHeaders(upstreamRes.headers));
+        upstreamRes.pipe(res);
+    });
+    upstreamReq.setTimeout(state.idleTimeoutMs, () => {
+        upstreamReq.destroy(new Error("upstream timeout"));
+    });
+    /* v8 ignore next @preserve */
+    req.socket.setTimeout(state.idleTimeoutMs, () => {
+        upstreamReq.destroy(new Error("client idle timeout"));
+    });
+    req.once("end", () => {
+        req.socket.setTimeout(0);
+    });
+    upstreamReq.on("error", (error) => {
+        /* v8 ignore next @preserve */
+        if (res.headersSent) {
+            res.destroy(error);
+            return;
+        }
+        httpReply(res, 502, `${error.message}\n`);
+    });
+    upstreamReq.once("close", () => {
+        req.socket.setTimeout(0);
+    });
+    /* v8 ignore next @preserve */
+    req.once("aborted", () => {
+        upstreamReq.destroy(new Error("client aborted"));
+    });
+    res.once("close", () => {
+        if (!res.writableEnded) {
+            upstreamReq.destroy(new Error("client disconnected"));
+        }
+    });
+    req.pipe(upstreamReq);
+}
+async function authorize(input) {
+    const { host, port, state } = input;
+    const hostname = normalizeHost(host);
+    if (hostname === undefined) {
+        throw new Error("empty or invalid host");
+    }
+    if (!state.allowedPorts.has(port)) {
+        throw new Error(`port not allowed: ${port}`);
+    }
+    if (!hostAllowed(hostname, state.allowedHosts)) {
+        throw new Error(`host not allowed: ${hostname}`);
+    }
+    const resolved = await resolveHost({ hostname, state });
+    return { address: resolved.address, family: resolved.family, hostname, port };
+}
+async function resolveHost(input) {
+    const { hostname, state } = input;
+    const directIpFamily = net.isIP(hostname);
+    if (isIpFamily(directIpFamily)) {
+        if (state.shouldBlockPrivateIps && isPrivateIpAddress(hostname, directIpFamily)) {
+            throw new Error(`private IP blocked: ${hostname}`);
+        }
+        return { address: hostname, family: directIpFamily };
+    }
+    const now = Date.now();
+    const cached = state.dnsCache.get(hostname);
+    const cachedRecord = cached?.records[0];
+    if (cached !== undefined && cached.until > now && cachedRecord !== undefined) {
+        return cachedRecord;
+    }
+    if (cached !== undefined && cached.until <= now) {
+        state.dnsCache.delete(hostname);
+    }
+    const lookupRecords = await state.dnsLookup(hostname);
+    const records = lookupRecords
+        .filter(hasIpFamily)
+        .filter((record) => !(state.shouldBlockPrivateIps && isPrivateIpAddress(record.address, record.family)))
+        .toSorted((a, b) => a.family - b.family);
+    const [firstRecord] = records;
+    if (firstRecord === undefined) {
+        throw new Error(`no public address for ${hostname}`);
+    }
+    if (state.dnsTtlMs > 0) {
+        state.dnsCache.set(hostname, { records, until: now + state.dnsTtlMs });
+    }
+    return firstRecord;
+}
+async function defaultDnsLookup(hostname) {
+    return await dns.lookup(hostname, { all: true, verbatim: false });
+}
+function hostAllowed(hostname, allowedHosts) {
+    return allowedHosts.some((rule) => {
+        if (rule.startsWith("*.")) {
+            const suffix = rule.slice(1);
+            return hostname.endsWith(suffix) && hostname.length > suffix.length;
+        }
+        return hostname === rule;
+    });
+}
+function parseConnectTarget(input) {
+    const ipv6 = /^\[([^\]]+)]:(\d+)$/.exec(input);
+    if (ipv6 !== null) {
+        const [, host, rawPort] = ipv6;
+        const port = parsePort(rawPort);
+        /* v8 ignore next @preserve */
+        if (host === undefined || port === undefined) {
+            return undefined;
+        }
+        return { host, port };
+    }
+    const separatorIndex = input.lastIndexOf(":");
+    if (separatorIndex <= 0) {
+        return undefined;
+    }
+    const port = parsePort(input.slice(separatorIndex + 1));
+    if (port === undefined) {
+        return undefined;
+    }
+    return { host: input.slice(0, separatorIndex), port };
+}
+function stripHopByHopHeaders(headers) {
+    const blockedHeaders = new Set(HOP_BY_HOP_HEADERS);
+    for (const token of parseConnectionHeaderTokens(headers.connection)) {
+        blockedHeaders.add(token);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (!blockedHeaders.has(key.toLowerCase()) && value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function parseConnectionHeaderTokens(value) {
+    /* v8 ignore next @preserve */
+    if (value === undefined) {
+        return [];
+    }
+    /* v8 ignore next @preserve */
+    const values = Array.isArray(value) ? value : [String(value)];
+    return values
+        .flatMap((header) => header.split(","))
+        .map((token) => token.trim().toLowerCase())
+        .filter((token) => token.length > 0);
+}
+function normalizeAllowedPorts(rawPorts) {
+    const ports = rawPorts
+        .map((rawPort) => (typeof rawPort === "number" ? rawPort : Number(rawPort)))
+        .filter((port) => isValidPort(port));
+    if (ports.length === 0) {
+        throw new Error("CLEARANCE_ALLOW_PORTS must include at least one valid TCP port");
+    }
+    return [...new Set(ports)];
+}
+function parseIntegerEnv(env, name, fallback, minimum, maximum) {
+    const value = env[name];
+    if (value === undefined || value.trim().length === 0) {
+        return fallback;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed)) {
+        throw new TypeError(`${name} must be an integer`);
+    }
+    if (parsed < minimum || parsed > maximum) {
+        throw new Error(`${name} must be between ${minimum} and ${maximum}`);
+    }
+    return parsed;
+}
+function parsePort(rawPort) {
+    if (rawPort === undefined || rawPort.trim().length === 0) {
+        return undefined;
+    }
+    const port = Number(rawPort);
+    return isValidPort(port) ? port : undefined;
+}
+function isValidPort(port) {
+    return Number.isInteger(port) && port > 0 && port <= 65_535;
+}
+function isIpFamily(family) {
+    return family === 4 || family === 6;
+}
+function hasIpFamily(record) {
+    return isIpFamily(record.family);
+}
+function isPrivateIpAddress(ip, family) {
+    if (family === 4) {
+        return PRIVATE_IPV4_BLOCK_LIST.check(ip, "ipv4");
+    }
+    return PRIVATE_IPV6_BLOCK_LIST.check(ip, "ipv6");
+}
+function createIpBlockList(ranges, family) {
+    const blockList = new net.BlockList();
+    for (const [address, prefix] of ranges) {
+        blockList.addSubnet(address, prefix, family);
+    }
+    return blockList;
+}
+function httpReply(res, status, body) {
+    res.writeHead(status, {
+        connection: "close",
+        "content-length": Buffer.byteLength(body),
+        "content-type": "text/plain; charset=utf-8",
+    });
+    res.end(body);
+}
+function socketReply(socket, status, reason, body) {
+    /* v8 ignore next @preserve */
+    if (socket.destroyed) {
+        return;
+    }
+    socket.end(`HTTP/1.1 ${status} ${reason}\r\ncontent-type: text/plain; charset=utf-8\r\ncontent-length: ${Buffer.byteLength(body)}\r\nconnection: close\r\n\r\n${body}`);
+}
+function logDecision(logger, input) {
+    const parts = [
+        input.decision,
+        `method=${input.method}`,
+        `host=${input.hostname}`,
+        `port=${input.port}`,
+    ];
+    if (input.address !== undefined) {
+        parts.push(`address=${input.address}`);
+    }
+    if (input.reason !== undefined) {
+        parts.push(`reason=${input.reason}`);
+    }
+    logger.info(parts.join(" "));
+}
+function errorMessage(error) {
+    /* v8 ignore next @preserve */
+    return error instanceof Error ? error.message : String(error);
+}
+function isNetSocket(socket) {
+    return socket instanceof net.Socket;
+}
+function noop() {
+    // Intentionally ignore optional proxy log and socket error events.
+}
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/clearance/src/index.ts"],"names":[],"mappings":"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"}

package/src/launcher.d.ts

@@ -0,0 +1,32 @@
+export interface ClearanceCheckInput {
+    host: string;
+    port: number;
+}
+export type ClearanceListenerCheck = (input: ClearanceCheckInput) => Promise<boolean>;
+export interface SpawnClearanceInput {
+    args: readonly string[];
+    command: string;
+    env: NodeJS.ProcessEnv;
+    logPath: string;
+}
+export type ClearanceSpawner = (input: SpawnClearanceInput) => number;
+export interface EnsureClearanceInput {
+    cacheDir?: string;
+    env?: NodeJS.ProcessEnv;
+    isListening?: ClearanceListenerCheck;
+    logger?: (message: string) => void;
+    pollIntervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    spawnDetached?: ClearanceSpawner;
+    timeoutMs?: number;
+}
+export interface EnsureClearanceResult {
+    logPath?: string;
+    pid?: number;
+    pidPath?: string;
+    port: number;
+    status: "already-running" | "started";
+}
+export declare function isClearanceListening(input: ClearanceCheckInput): Promise<boolean>;
+export declare function spawnClearance(input: SpawnClearanceInput): number;
+export declare function ensureClearance(input?: EnsureClearanceInput): Promise<EnsureClearanceResult>;

package/src/launcher.js

@@ -0,0 +1,148 @@
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, writeFileSync } from "node:fs";
+import * as net from "node:net";
+import { homedir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
+import { resolveAllowlist } from "./allowlist.js";
+const CLEARANCE_HOST = "127.0.0.1";
+const CLEARANCE_PORT = 19_999;
+const CLEARANCE_START_TIMEOUT_MS = 3000;
+const CLEARANCE_POLL_INTERVAL_MS = 100;
+const FORWARDED_ENV_VARS = [
+    "CLEARANCE_ALLOW_HOSTS",
+    "CLEARANCE_ALLOW_HOSTS_FILES",
+    "CLEARANCE_ALLOW_PORTS",
+    "CLEARANCE_ALLOW_PRIVATE_IPS",
+    "CLEARANCE_DNS_TTL_MS",
+    "CLEARANCE_IDLE_TIMEOUT_MS",
+    "CLEARANCE_MAX_SOCKETS",
+    "HOME",
+    "PATH",
+    "XDG_CACHE_HOME",
+];
+// import.meta.dirname is `<package>/{src,dist}`; the proxy server bin lives at `<package>/bin/run.js`.
+const PACKAGE_ROOT = resolvePath(import.meta.dirname, "..");
+const CLEARANCE_BIN_PATH = resolvePath(PACKAGE_ROOT, "bin", "run.js");
+export async function isClearanceListening(input) {
+    return await new Promise((resolve) => {
+        const socket = net.createConnection({ host: input.host, port: input.port });
+        socket.setTimeout(500);
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("error", () => {
+            socket.destroy();
+            resolve(false);
+        });
+        /* v8 ignore next 4 @preserve -- timeout is a defensive slow-network path; connection refused is the normal closed-port path */
+        socket.once("timeout", () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+export function spawnClearance(input) {
+    const logFile = openSync(input.logPath, "a");
+    try {
+        const child = spawn(input.command, input.args, {
+            detached: true,
+            env: input.env,
+            stdio: ["ignore", logFile, logFile],
+        });
+        child.unref();
+        /* v8 ignore next 3 @preserve -- Node assigns pid for spawned processes; this is a defensive guard */
+        if (child.pid === undefined) {
+            throw new Error("clearance process started without a pid");
+        }
+        return child.pid;
+    }
+    finally {
+        closeSync(logFile);
+    }
+}
+export async function ensureClearance(input = {}) {
+    const env = input.env ?? defaultProxyEnv();
+    /* v8 ignore next @preserve -- default listener is covered directly by isClearanceListening tests */
+    const isListening = input.isListening ?? isClearanceListening;
+    const logger = input.logger ?? noop;
+    if (await isListening({ host: CLEARANCE_HOST, port: CLEARANCE_PORT })) {
+        logger(`Clearance already listening on http://${CLEARANCE_HOST}:${CLEARANCE_PORT}`);
+        return { port: CLEARANCE_PORT, status: "already-running" };
+    }
+    // Fail fast with a readable message instead of a "did not start listening" timeout.
+    resolveAllowlist({ env });
+    const cacheDir = input.cacheDir ?? cacheDirFor(env);
+    const logPath = join(cacheDir, "clearance.log");
+    const pidPath = join(cacheDir, "clearance.pid");
+    mkdirSync(cacheDir, { recursive: true });
+    /* v8 ignore next @preserve -- default spawner is covered directly by spawnClearance tests */
+    const spawnDetached = input.spawnDetached ?? spawnClearance;
+    const pid = spawnDetached({
+        args: [CLEARANCE_BIN_PATH],
+        command: process.execPath,
+        env: childEnv(env),
+        logPath,
+    });
+    writeFileSync(pidPath, `${pid}\n`);
+    const isReady = await waitForListening({
+        host: CLEARANCE_HOST,
+        isListening,
+        pollIntervalMs: input.pollIntervalMs ?? CLEARANCE_POLL_INTERVAL_MS,
+        port: CLEARANCE_PORT,
+        sleep: input.sleep ?? defaultSleep,
+        timeoutMs: input.timeoutMs ?? CLEARANCE_START_TIMEOUT_MS,
+    });
+    if (!isReady) {
+        throw new Error(`Clearance did not start listening on ${CLEARANCE_HOST}:${CLEARANCE_PORT}; check ${logPath}`);
+    }
+    logger(`Started clearance on http://${CLEARANCE_HOST}:${CLEARANCE_PORT} (pid ${pid}); logs: ${logPath}`);
+    return { logPath, pid, pidPath, port: CLEARANCE_PORT, status: "started" };
+}
+function noop() {
+    // No-op default for the optional logger hook.
+}
+function cacheDirFor(env) {
+    const xdgCacheHome = env["XDG_CACHE_HOME"];
+    if (xdgCacheHome !== undefined && xdgCacheHome.length > 0) {
+        return join(xdgCacheHome, "clearance");
+    }
+    const home = env["HOME"];
+    /* v8 ignore else @preserve -- tests use HOME/XDG_CACHE_HOME to avoid writing to the real home dir */
+    if (home !== undefined && home.length > 0) {
+        return join(home, ".cache", "clearance");
+    }
+    /* v8 ignore next @preserve -- tests pass HOME/XDG_CACHE_HOME to avoid writing to the real home dir */
+    return join(homedir(), ".cache", "clearance");
+}
+function childEnv(env) {
+    return {
+        ...env,
+        CLEARANCE_LISTEN_HOST: CLEARANCE_HOST,
+        CLEARANCE_PORT: String(CLEARANCE_PORT),
+    };
+}
+function defaultProxyEnv() {
+    return Object.fromEntries(FORWARDED_ENV_VARS
+        // oxlint-disable-next-line node/no-process-env -- centralized env accessor for the launcher CLI
+        .map((name) => [name, process.env[name]])
+        .filter(([, value]) => value !== undefined));
+}
+async function waitForListening(input) {
+    const attempts = Math.max(1, Math.ceil(input.timeoutMs / input.pollIntervalMs));
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        // eslint-disable-next-line no-await-in-loop -- readiness polling is intentionally sequential
+        if (await input.isListening({ host: input.host, port: input.port })) {
+            return true;
+        }
+        // eslint-disable-next-line no-await-in-loop -- readiness polling is intentionally sequential
+        await input.sleep(input.pollIntervalMs);
+    }
+    return false;
+}
+async function defaultSleep(ms) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+//# sourceMappingURL=launcher.js.map

package/src/launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../../../packages/clearance/src/launcher.ts"],"names":[],"mappings":"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"}