@clipboard-health/clearance 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,9 @@
 # @clipboard-health/clearance
 
-HTTP/HTTPS clearance for deny-by-default sandboxes.
+A local HTTP/HTTPS forward proxy that gates network egress against a
+hostname allowlist. Built for deny-by-default sandboxes — coding agents,
+CI workers, isolated build steps — where you want one choke point the
+sandbox can permit, with every other route to the network closed.
 
 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
@@ -100,8 +103,9 @@ 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.
+[Safehouse](https://agent-safehouse.dev/) 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`.
@@ -217,3 +221,14 @@ safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \
   --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \
   -- curl -I https://example.com
 ```
+
+## Hacking on clearance
+
+For developers working on the package itself, the source lives in [`ClipboardHealth/core-utils`](https://github.com/ClipboardHealth/core-utils). After `npm install` in the repo, the bin scripts dispatch through a `runCli` helper that detects no compiled JS and re-execs node with `--conditions @clipboard-health/source`, so the proxy runs straight from TypeScript source — no build step:
+
+```bash
+cd ~/dev/c/core-utils
+CLEARANCE_ALLOW_HOSTS=api.example.com node ./packages/clearance/bin/run.js
+```
+
+Requires Node ≥ 24.3 (native `.ts` type stripping enabled by default).

package/bin/ensure.js

@@ -1,3 +1,7 @@
 #!/usr/bin/env node
 
-import "../src/ensureCli.js";
+import { dirname } from "node:path";
+
+import { runCli } from "./runCli.js";
+
+await runCli(dirname(import.meta.dirname), "ensureCli");

package/bin/run.js

@@ -1,3 +1,7 @@
 #!/usr/bin/env node
 
-import "../src/cli.js";
+import { dirname } from "node:path";
+
+import { runCli } from "./runCli.js";
+
+await runCli(dirname(import.meta.dirname), "cli");

package/bin/runCli.js

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants as osConstants } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Load a side-effecting entrypoint by basename. In published/built mode, dynamically
+ * imports the compiled `${name}.js` in-process. In source/dev mode (no compiled output
+ * present), spawns a child node that loads the `.ts` source with
+ * `--conditions @clipboard-health/source` so cross-package bare imports of
+ * `@clipboard-health/*` workspace deps also resolve to source.
+ *
+ * @param {string} packageRoot
+ * @param {string} name
+ */
+export async function runCli(packageRoot, name) {
+  const compiledPath = join(packageRoot, "src", `${name}.js`);
+  if (existsSync(compiledPath)) {
+    await import(pathToFileURL(compiledPath).href);
+    return;
+  }
+
+  const sourcePath = join(packageRoot, "src", `${name}.ts`);
+  const result = spawnSync(
+    process.execPath,
+    ["--conditions", "@clipboard-health/source", sourcePath, ...process.argv.slice(2)],
+    { stdio: "inherit" },
+  );
+
+  if (result.error !== undefined) {
+    throw result.error;
+  }
+
+  if (result.signal !== null) {
+    const signalNumber = osConstants.signals[result.signal];
+    process.exitCode = signalNumber === undefined ? 1 : 128 + signalNumber;
+    return;
+  }
+
+  process.exitCode = result.status ?? 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/clearance",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Localhost HTTP/HTTPS egress proxy with hostname allow-listing, plus a macOS Safehouse integration for sandboxed agent processes.",
   "keywords": [
     "agent",
@@ -24,6 +24,15 @@
   "type": "module",
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@clipboard-health/source": "./src/index.ts",
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/index.d.ts

@@ -1,7 +1,7 @@
 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 { resolveAllowlist, type ResolveAllowlistInput } from "./allowlist.ts";
+export { type ClearanceCheckInput, type ClearanceListenerCheck, type ClearanceSpawner, ensureClearance, type EnsureClearanceInput, type EnsureClearanceResult, isClearanceListening, spawnClearance, type SpawnClearanceInput, } from "./launcher.ts";
 export declare const CLEARANCE_PACKAGE_NAME = "@clipboard-health/clearance";
 export interface ClearanceConfig {
     allowedHosts: readonly string[];