@kill-switch/agent-guard 0.1.0 → 0.1.1

package/dist/alert.js

@@ -13,6 +13,7 @@
 import { appendFileSync } from "node:fs";
 import { eventsPath, ensureGuardDir } from "./config.js";
 import { fmtUSD } from "./cost.js";
+import { isSafeEndpoint, warnIfUnexpectedHost } from "./net.js";
 const TIMEOUT_MS = 2500;
 async function postJson(url, body, headers = {}) {
     const ctrl = new AbortController();
@@ -61,7 +62,9 @@ export async function dispatchAlert(cfg, evt) {
     if (cfg.slackWebhook) {
         tasks.push(postJson(cfg.slackWebhook, { text: slackText(evt) }));
     }
-    if (cfg.apiKey && cfg.apiUrl) {
+    // Only POST the ks_live key to a safe endpoint; warn on an unexpected host.
+    if (cfg.apiKey && cfg.apiUrl && isSafeEndpoint(cfg.apiUrl)) {
+        warnIfUnexpectedHost(cfg.apiUrl, "api.kill-switch.net", "apiUrl");
         tasks.push(postJson(`${cfg.apiUrl.replace(/\/$/, "")}/agent-guard/events`, evt, { authorization: `Bearer ${cfg.apiKey}` }));
     }
     await Promise.allSettled(tasks);

package/dist/net.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Endpoint safety checks (security: M-1).
+ *
+ * The proxy forwards the caller's LLM API key to `upstream`, and breach alerts
+ * POST the user's ks_live key to `apiUrl`. A poisoned local config / flag could
+ * redirect those credentials to an attacker. We can't host-allowlist (users may
+ * self-host the API), but we can refuse insecure schemes and surface a warning
+ * when the host isn't the expected default — so a redirect is never silent.
+ */
+/** True for http(s) URLs that are safe to send credentials to. */
+export declare function isSafeEndpoint(raw: string): boolean;
+/** Validate a credential-bearing endpoint; throws on an unsafe URL. */
+export declare function assertSafeEndpoint(raw: string, label: string): string;
+/** Warn (non-fatal) to stderr when a credential-bearing host isn't the default. */
+export declare function warnIfUnexpectedHost(raw: string, expectedHost: string, label: string): void;

package/dist/net.js

@@ -0,0 +1,45 @@
+/**
+ * Endpoint safety checks (security: M-1).
+ *
+ * The proxy forwards the caller's LLM API key to `upstream`, and breach alerts
+ * POST the user's ks_live key to `apiUrl`. A poisoned local config / flag could
+ * redirect those credentials to an attacker. We can't host-allowlist (users may
+ * self-host the API), but we can refuse insecure schemes and surface a warning
+ * when the host isn't the expected default — so a redirect is never silent.
+ */
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+/** True for http(s) URLs that are safe to send credentials to. */
+export function isSafeEndpoint(raw) {
+    try {
+        const u = new URL(raw);
+        if (u.protocol === "https:")
+            return true;
+        // plaintext http is only acceptable to loopback (local dev / self-test)
+        return u.protocol === "http:" && LOCAL_HOSTS.has(u.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate a credential-bearing endpoint; throws on an unsafe URL. */
+export function assertSafeEndpoint(raw, label) {
+    if (!isSafeEndpoint(raw)) {
+        throw new Error(`Refusing to use ${label}="${raw}": it must be an https:// URL ` +
+            `(http:// is allowed only for localhost). This protects your API key ` +
+            `from being sent over an insecure or unexpected channel.`);
+    }
+    return raw;
+}
+/** Warn (non-fatal) to stderr when a credential-bearing host isn't the default. */
+export function warnIfUnexpectedHost(raw, expectedHost, label) {
+    try {
+        const host = new URL(raw).hostname;
+        if (host !== expectedHost) {
+            process.stderr.write(`⚠  agent-guard: ${label} points at "${host}", not "${expectedHost}". ` +
+                `Your API key will be sent there — make sure that's intended.\n`);
+        }
+    }
+    catch {
+        /* assertSafeEndpoint handles invalid URLs */
+    }
+}

package/dist/proxy.d.ts

@@ -15,6 +15,7 @@
  * — they'd each meter the same dollars. Hook for Claude Code; proxy for everything
  * else (Cursor, Aider, raw scripts). See README.
  */
+import { type Server } from "node:http";
 import { type TokenUsage } from "./cost.js";
 export interface ProxyOptions {
     port: number;
@@ -33,5 +34,5 @@ export declare function parseStreamUsage(flavor: string, sse: string): {
     model: string;
     usage: TokenUsage;
 } | null;
-export declare function startProxy(opts: ProxyOptions): void;
+export declare function startProxy(opts: ProxyOptions): Server;
 export declare function resolveUpstream(flavor: string, explicit?: string): string;

package/dist/proxy.js

@@ -23,6 +23,7 @@ import { costForUsage, fmtUSD } from "./cost.js";
 import { loadLedger, saveLedger, addSessionCost, rollingDailyCost, prune, } from "./ledger.js";
 import { evaluate } from "./budget.js";
 import { dispatchAlert } from "./alert.js";
+import { assertSafeEndpoint, warnIfUnexpectedHost } from "./net.js";
 const UPSTREAMS = {
     anthropic: "https://api.anthropic.com",
     openai: "https://api.openai.com",
@@ -135,7 +136,7 @@ function meter(cfg, ledger, sessionId, parsed, now) {
 }
 export function startProxy(opts) {
     const cfg = loadConfig();
-    const upstreamOrigin = opts.upstream.replace(/\/$/, "");
+    const upstreamOrigin = assertSafeEndpoint(opts.upstream, "upstream").replace(/\/$/, "");
     const blockedNotified = {};
     const server = createServer(async (req, res) => {
         const now = Date.now();
@@ -242,7 +243,9 @@ export function startProxy(opts) {
             }
         })();
     });
-    server.listen(opts.port, () => {
+    // Bind to loopback only — this proxy forwards the caller's LLM API key
+    // upstream, so it must never be reachable from the local network.
+    server.listen(opts.port, "127.0.0.1", () => {
         process.stdout.write(`🛡  agent-guard proxy on http://localhost:${opts.port} → ${upstreamOrigin} (${opts.flavor})\n` +
             `   Caps: session hard ${fmtUSD(cfg.budget.sessionHardUSD)}, daily hard ${fmtUSD(cfg.budget.dailyHardUSD)}\n` +
             `   Point your agent at it, e.g.:\n` +
@@ -250,7 +253,14 @@ export function startProxy(opts) {
                 ? `     ANTHROPIC_BASE_URL=http://localhost:${opts.port} claude\n`
                 : `     OPENAI_BASE_URL=http://localhost:${opts.port}/v1 aider\n`));
     });
+    return server;
 }
 export function resolveUpstream(flavor, explicit) {
-    return explicit || UPSTREAMS[flavor] || UPSTREAMS.anthropic;
+    const upstream = explicit || UPSTREAMS[flavor] || UPSTREAMS.anthropic;
+    assertSafeEndpoint(upstream, "upstream");
+    if (explicit) {
+        const expected = new URL(UPSTREAMS[flavor] || UPSTREAMS.anthropic).hostname;
+        warnIfUnexpectedHost(upstream, expected, "--upstream");
+    }
+    return upstream;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kill-switch/agent-guard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Kill Switch for coding agents — stop runaway Claude Code / Cursor / Aider sessions from racking up an LLM bill. Native hook + token-metering proxy with per-session and daily-rolling budgets.",
   "type": "module",
   "bin": {