@mycadet/gateway 0.12.9 → 0.12.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycadet/gateway",
-  "version": "0.12.9",
+  "version": "0.12.10",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/credential-reader.test.ts

@@ -53,7 +53,7 @@ function getMachineEntropy(): string {
   } catch {
     parts.push("unknown-user");
   }
-  // Must match assistant/src/util/platform.ts#getPlatformName.
+  // Must match assistant/src/util/os.ts#getPlatformName.
   parts.push(process.platform);
   parts.push(process.arch);
   try {

package/src/__tests__/credential-watcher.test.ts

@@ -56,7 +56,7 @@ function getMachineEntropy(): string {
   } catch {
     parts.push("unknown-user");
   }
-  // Must mirror assistant/src/util/platform.ts#getPlatformName (raw platform).
+  // Must mirror assistant/src/util/os.ts#getPlatformName (raw platform).
   parts.push(process.platform);
   parts.push(process.arch);
   try {

package/src/__tests__/remote-web-pairing-challenge.test.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { beforeEach, describe, expect, test } from "bun:test";
 
 const { handleCreateRemoteWebPairingChallenge } =
@@ -15,6 +17,7 @@ const {
 } = await import("../remote-web/pairing-challenge-store.js");
 const { resetRemoteWebPairingChallengeRateLimiterForTests } =
   await import("../remote-web/pairing-challenge-rate-limit-store.js");
+const { testSecurityDir } = await import("./test-preload.js");
 
 import {
   LOOPBACK_IP,
@@ -501,3 +504,37 @@ describe("remote web pairing request list/approve/deny", () => {
     });
   });
 });
+
+describe("file-backed persistence", () => {
+  test("persists challenges to the security dir for other processes", () => {
+    setRemoteWebPairingChallengeNowForTests(() => 1_000);
+    createRemoteWebPairingChallenge(PUBLIC_BASE_URL, TEST_REQUESTER);
+
+    const storePath = join(
+      testSecurityDir,
+      "remote-web-pairing-challenges.json",
+    );
+    expect(existsSync(storePath)).toBe(true);
+    const persisted: unknown[] = JSON.parse(readFileSync(storePath, "utf-8"));
+    expect(persisted).toHaveLength(1);
+
+    // The reset helper removes the file so other tests start empty.
+    resetRemoteWebPairingChallengesForTests();
+    expect(existsSync(storePath)).toBe(false);
+  });
+
+  test("starts empty and warns when the store file is corrupt", () => {
+    const storePath = join(
+      testSecurityDir,
+      "remote-web-pairing-challenges.json",
+    );
+    writeFileSync(storePath, "{not json", "utf-8");
+
+    const challenge = createRemoteWebPairingChallenge(
+      PUBLIC_BASE_URL,
+      TEST_REQUESTER,
+    );
+    const stored = getRemoteWebPairingChallengeForTests(challenge.userCode);
+    expect(stored).toBeDefined();
+  });
+});

package/src/cli/__tests__/pairing.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Tests for the `gateway pairing mint <url>` CLI command. The mint executes
+ * the pairing logic DIRECTLY against the file-backed challenge store — no
+ * IPC (the assistant daemon shares the gateway's socket, so an IPC-exposed
+ * mint would let the assistant approve pairings for itself). These tests run
+ * the real command and pin both the printed challenge and its landing in
+ * the on-disk store the running gateway reads.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { z } from "zod";
+
+const { parsePairingArgs, runPairingCommand } = await import("../pairing.js");
+const {
+  getRemoteWebPairingChallengeForTests,
+  resetRemoteWebPairingChallengesForTests,
+} = await import("../../remote-web/pairing-challenge-store.js");
+const { resetRemoteWebPairingChallengeRateLimiterForTests } =
+  await import("../../remote-web/pairing-challenge-rate-limit-store.js");
+const { testSecurityDir } = await import("../../__tests__/test-preload.js");
+
+// ---------------------------------------------------------------------------
+// Test infrastructure
+// ---------------------------------------------------------------------------
+
+const PrintedChallengeSchema = z.object({
+  deviceCode: z.string().min(1),
+  userCode: z.string().regex(/^[A-Z2-9]{4}-[A-Z2-9]{4}$/),
+  verificationUri: z.string(),
+  expiresAt: z.string(),
+  expiresInSeconds: z.number(),
+  intervalSeconds: z.number(),
+});
+
+let logs: string[];
+let errors: string[];
+let logSpy: ReturnType<typeof spyOn>;
+let errorSpy: ReturnType<typeof spyOn>;
+
+beforeEach(() => {
+  resetRemoteWebPairingChallengesForTests();
+  resetRemoteWebPairingChallengeRateLimiterForTests();
+
+  logs = [];
+  errors = [];
+  logSpy = spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+    logs.push(args.map(String).join(" "));
+  });
+  errorSpy = spyOn(console, "error").mockImplementation(
+    (...args: unknown[]) => {
+      errors.push(args.map(String).join(" "));
+    },
+  );
+});
+
+afterEach(() => {
+  logSpy.mockRestore();
+  errorSpy.mockRestore();
+});
+
+function lastLoggedChallenge() {
+  const line = logs[logs.length - 1];
+  expect(line).toBeTruthy();
+  return PrintedChallengeSchema.parse(JSON.parse(line!));
+}
+
+describe("gateway pairing mint", () => {
+  test("mints an approved challenge directly against the file-backed store", async () => {
+    const code = await runPairingCommand([
+      "mint",
+      "https://my-assistant.ts.net",
+    ]);
+
+    expect(code).toBe(0);
+    const challenge = lastLoggedChallenge();
+    expect(challenge.verificationUri).toBe(
+      "https://my-assistant.ts.net/assistant/pair",
+    );
+    expect(challenge.intervalSeconds).toBe(5);
+
+    // Approved on the spot: the CLI invocation IS the approval.
+    const stored = getRemoteWebPairingChallengeForTests(challenge.userCode);
+    expect(stored?.status).toBe("approved");
+  });
+
+  test("persists the challenge to the store the running gateway reads", async () => {
+    const code = await runPairingCommand([
+      "mint",
+      "https://my-assistant.ts.net",
+    ]);
+    expect(code).toBe(0);
+
+    const storePath = join(
+      testSecurityDir,
+      "remote-web-pairing-challenges.json",
+    );
+    expect(existsSync(storePath)).toBe(true);
+    const raw = readFileSync(storePath, "utf-8");
+    expect(raw).toContain('"status":"approved"');
+    expect(raw).toContain('"requesterIp":"cli"');
+  });
+
+  test("rejects an unparseable public base URL", async () => {
+    const code = await runPairingCommand(["mint", "not-a-url"]);
+
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("publicBaseUrl is required");
+  });
+
+  test("requires the public base URL argument", async () => {
+    const code = await runPairingCommand(["mint"]);
+
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("mint requires the public base URL");
+  });
+});
+
+describe("parsePairingArgs", () => {
+  test("splits the subcommand and positional", () => {
+    expect(parsePairingArgs(["mint", "https://x.example"])).toEqual({
+      subcommand: "mint",
+      positional: "https://x.example",
+    });
+    expect(parsePairingArgs([])).toEqual({
+      subcommand: null,
+      positional: null,
+    });
+  });
+});

package/src/cli/index.ts

@@ -8,6 +8,7 @@
  */
 
 import { runContactsCommand } from "./contacts.js";
+import { runPairingCommand } from "./pairing.js";
 
 function printUsage(): void {
   console.log("Usage: gateway <command>");
@@ -15,7 +16,12 @@ function printUsage(): void {
   console.log("Operator commands for gateway-owned state.");
   console.log("");
   console.log("Commands:");
-  console.log("  contacts    Manage the contact ACL with list, get, set-risk-threshold");
+  console.log(
+    "  contacts    Manage the contact ACL with list, get, set-risk-threshold",
+  );
+  console.log(
+    "  pairing     Mint/approve a remote-web pairing challenge (mint <url>)",
+  );
 }
 
 const args = process.argv.slice(2);
@@ -31,6 +37,11 @@ if (command === "contacts") {
   process.exit(code);
 }
 
+if (command === "pairing") {
+  const code = await runPairingCommand(args.slice(1));
+  process.exit(code);
+}
+
 console.error(`Unknown command: ${command}`);
 printUsage();
 process.exit(1);

package/src/cli/pairing.ts

@@ -0,0 +1,71 @@
+/**
+ * `gateway pairing` — operator subcommands for the remote-web pairing flow.
+ *
+ *   gateway pairing mint <url>
+ *
+ * Mints (and approves) a remote-web pairing challenge by executing the
+ * pairing mint logic DIRECTLY in this process — deliberately NOT over the
+ * gateway's IPC socket, which the assistant daemon shares (an IPC-exposed
+ * mint would let the assistant mint + approve pairings for itself). The
+ * challenge persists to the file-backed pairing store under
+ * GATEWAY_SECURITY_DIR, so the running gateway's verification and
+ * token-exchange routes see it. This is the surface `cadet pair` invokes
+ * (directly on the host, or via `docker exec` inside the gateway container):
+ * process execution is the local-presence proof, so no loopback-peer check
+ * is needed and the topology (native or containerized) stops mattering.
+ * Prints the challenge response as single-line JSON on stdout; the caller
+ * parses it and renders the pairing link/QR.
+ */
+
+import { mintAndApproveRemoteWebPairingChallenge } from "../remote-web/pairing-mint.js";
+
+function printUsage(): void {
+  console.log("Usage: gateway pairing mint <url>");
+  console.log("");
+  console.log(
+    "Mint and approve a remote-web pairing challenge on this machine and",
+  );
+  console.log("print the challenge as JSON.");
+  console.log("");
+  console.log("Arguments:");
+  console.log("  <url>   Public base URL to advertise in the pairing link,");
+  console.log("          e.g. https://your-assistant.ts.net");
+}
+
+/** Parse `pairing` argv (after the command word) into a subcommand + arg. */
+export function parsePairingArgs(args: string[]): {
+  subcommand: string | null;
+  positional: string | null;
+} {
+  const [subcommand = null, positional = null] = args;
+  return { subcommand, positional };
+}
+
+export async function runPairingCommand(args: string[]): Promise<number> {
+  const { subcommand, positional } = parsePairingArgs(args);
+
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    printUsage();
+    return subcommand ? 0 : 1;
+  }
+  if (subcommand !== "mint") {
+    console.error(`Error: unknown pairing subcommand '${subcommand}'.`);
+    printUsage();
+    return 1;
+  }
+  if (!positional) {
+    console.error("Error: mint requires the public base URL to advertise.");
+    printUsage();
+    return 1;
+  }
+
+  try {
+    const challenge = mintAndApproveRemoteWebPairingChallenge(positional);
+    console.log(JSON.stringify(challenge));
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: pairing mint failed: ${message}`);
+    return 1;
+  }
+}

package/src/credential-reader.ts

@@ -46,7 +46,7 @@ type StoreFile = StoreFileV1 | StoreFileV2;
 const STORE_KEY_FILENAME = "store.key";
 
 function getPlatformName(): string {
-  // Must match assistant/src/util/platform.ts#getPlatformName exactly.
+  // Must match assistant/src/util/os.ts#getPlatformName exactly.
   // Using user-friendly labels like "macOS" here changes PBKDF2 entropy and
   // makes gateway unable to decrypt credentials written by the daemon.
   return process.platform;

package/src/http/routes/guardian-pin.ts

@@ -40,6 +40,7 @@ import { findCadetGuardian } from "../../auth/guardian-bootstrap.js";
 import type { GatewayConfig } from "../../config.js";
 import { requestHasTunnelBridgeAuth } from "../../tunnel/bridge-auth.js";
 import { readStoredCloudUserId } from "../../cloud-user-id.js";
+import { isWebsocketUpgradeRequest } from "../utils.js";
 
 const TUNNEL_USER_ID_HEADER = "x-tunnel-user-id";
 const TUNNEL_ORG_ID_HEADER = "x-tunnel-org-id";
@@ -175,7 +176,7 @@ export async function authorizeGuardianStream(
   // Checked here as well as in the shared gate, because the cloud path
   // below skips that gate entirely: without this, a cloud caller sending a
   // plain request would fall through to `server.upgrade` and get a 500.
-  if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+  if (!isWebsocketUpgradeRequest(req)) {
     return new Response("Upgrade Required", { status: 426 });
   }
 

package/src/http/routes/ingress-domains.test.ts

@@ -97,14 +97,17 @@ describe("POST /v1/ingress/domains", () => {
     expect(afterSecond).toBe(afterFirst);
   });
 
-  test("rejects non-loopback callers", async () => {
+  test("does not gate on the peer IP — auth lives in the edge-guardian strategy", async () => {
+    // The docker hatch's gateway sees the host CLI as a non-loopback peer
+    // (the docker bridge IP); peer-IP gating here 403'd valid
+    // guardian-token requests, so it moved to the auth strategy.
     const res = await handleSaveIngressDomain(
       request({ publicBaseUrl: "https://foo.ngrok.app" }),
       "10.0.0.1",
       new ConfigFileCache(),
     );
 
-    expect(res.status).toBe(403);
+    expect(res.status).toBe(200);
   });
 
   test("rejects a body without a usable public URL", async () => {

package/src/http/routes/ingress-domains.ts

@@ -1,5 +1,5 @@
 /**
- * Loopback-guarded recording of a tunnel's public URL.
+ * Guardian-authed recording of a tunnel's public URL.
  *
  *   POST /v1/ingress/domains — the CLI (its ngrok agent, today) tells the
  *   gateway the public URL its tunnel published; the gateway writes
@@ -19,11 +19,7 @@ import { normalizeHttpPublicBaseUrlWithoutTrailingSlash } from "@mycadet/service
 
 import type { ConfigFileCache } from "../../config-file-cache.js";
 import { writeManagedPublicBaseUrl } from "../../tunnel/client.js";
-import {
-  enforceLoopbackOnly,
-  errorResponse,
-  rejectBrowserOrigin,
-} from "../loopback-guard.js";
+import { errorResponse, rejectBrowserOrigin } from "../loopback-guard.js";
 
 const SaveIngressDomainRequestSchema = z.object({
   publicBaseUrl: z.string(),
@@ -41,8 +37,6 @@ export async function handleSaveIngressDomain(
     });
   }
 
-  const guardError = enforceLoopbackOnly(req, clientIp, "ingress-domains");
-  if (guardError) return guardError;
   const originError = rejectBrowserOrigin(req, clientIp, "ingress-domains");
   if (originError) return originError;
 

package/src/http/routes/live-voice-websocket.ts

@@ -16,6 +16,7 @@ import {
   requireBoundGuardian,
   requireManagedGuardian,
 } from "./guardian-pin.js";
+import { isWebsocketUpgradeRequest } from "../utils.js";
 
 const log = getLogger("live-voice-ws");
 
@@ -53,7 +54,7 @@ export function createLiveVoiceWebsocketHandler(config: GatewayConfig) {
     req: Request,
     server: import("bun").Server<unknown>,
   ): Promise<Response | undefined> {
-    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+    if (!isWebsocketUpgradeRequest(req)) {
       return new Response("Upgrade Required", { status: 426 });
     }
 

package/src/http/routes/plugin-webhook-websocket.test.ts

@@ -13,6 +13,7 @@ import {
   isPluginWebhookSocketData,
   type PluginWebhookSocketData,
 } from "./plugin-webhook-websocket.js";
+import { IngressRoute } from "../../channels/plugin-ingress.js";
 
 initSigningKey(Buffer.from("test-signing-key-at-least-32-bytes-long"));
 
@@ -24,7 +25,7 @@ const CONFIG = {
 
 const PLUGIN_SECRET = "plugin-webhook-secret";
 const CADET_SECRET = "platform-webhook-secret";
-const WS_PATH = "/webhooks/plugins/meeting-bot/realtime";
+const WS_PATH = "/webhooks/plugins/example/realtime";
 
 const ROUTE = {
   path: "realtime",
@@ -43,7 +44,7 @@ function credentialsFor(entries: Record<string, string>) {
 }
 
 const CREDENTIALS = credentialsFor({
-  "credential/meeting-bot/webhook_secret": PLUGIN_SECRET,
+  "credential/example/webhook_secret": PLUGIN_SECRET,
   "credential/cadet/webhook_secret": CADET_SECRET,
 });
 
@@ -53,17 +54,9 @@ function resolution(
   return { approved: [], pending: [], problems: [], ...overrides };
 }
 
-function approvedWith(
-  routes: {
-    path: string;
-    kind: "http" | "websocket";
-    signer: "plugin" | "cadet";
-    handshake: "signed-headers" | "signed-query";
-    description: string;
-  }[],
-): PluginIngressResolution {
+function approvedWith(routes: IngressRoute[]): PluginIngressResolution {
   return resolution({
-    approved: [{ plugin: "meeting-bot", routes, digest: "d".repeat(32) }],
+    approved: [{ plugin: "example", routes, digest: "d".repeat(32) }],
   });
 }
 
@@ -128,13 +121,13 @@ describe("upgrade gate", () => {
     const res = await handle(
       upgradeRequest(),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
     expect(res).toBeUndefined();
     expect(upgrades).toHaveLength(1);
-    expect(upgrades[0]!.plugin).toBe("meeting-bot");
+    expect(upgrades[0]!.plugin).toBe("example");
     expect(isPluginWebhookSocketData(upgrades[0])).toBe(true);
   });
 
@@ -145,7 +138,7 @@ describe("upgrade gate", () => {
     const res = await handle(
       upgradeRequest({ upgrade: false }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -158,7 +151,7 @@ describe("upgrade gate", () => {
       resolve: () =>
         resolution({
           pending: [
-            { plugin: "meeting-bot", routes: [ROUTE], digest: "d".repeat(32) },
+            { plugin: "example", routes: [ROUTE], digest: "d".repeat(32) },
           ],
         }),
     });
@@ -167,7 +160,7 @@ describe("upgrade gate", () => {
     const res = await handle(
       upgradeRequest(),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -183,7 +176,7 @@ describe("upgrade gate", () => {
         resolution({
           pending: [
             {
-              plugin: "meeting-bot",
+              plugin: "example",
               routes: [{ ...ROUTE, signer: "cadet" as const }],
               digest: "d".repeat(32),
             },
@@ -195,7 +188,7 @@ describe("upgrade gate", () => {
     const res = await handle(
       upgradeRequest({ secret: CADET_SECRET }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -210,7 +203,7 @@ describe("upgrade gate", () => {
         resolution({
           pending: [
             {
-              plugin: "meeting-bot",
+              plugin: "example",
               routes: [{ ...ROUTE, signer: "cadet" as const }],
               digest: "d".repeat(32),
             },
@@ -222,7 +215,7 @@ describe("upgrade gate", () => {
     const res = await handle(
       upgradeRequest({ secret: PLUGIN_SECRET }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -240,7 +233,7 @@ describe("upgrade gate", () => {
     const res = await handle(
       upgradeRequest(),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -255,7 +248,7 @@ describe("upgrade gate", () => {
     const res = await handle(
       upgradeRequest({ path: "/webhooks/plugins/meeting-bot/admin" }),
       server,
-      "meeting-bot",
+      "example",
       "admin",
     );
 
@@ -274,7 +267,7 @@ describe("upgrade gate", () => {
     const res = await handle(
       upgradeRequest(),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -291,7 +284,7 @@ describe("handshake signature", () => {
     const res = await handle(
       upgradeRequest({ secret: "" }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -306,7 +299,7 @@ describe("handshake signature", () => {
     const res = await handle(
       upgradeRequest({ secret: "nope" }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -324,7 +317,7 @@ describe("handshake signature", () => {
         timestamp: String(Math.floor(Date.now() / 1000) - 3600),
       }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -339,7 +332,7 @@ describe("handshake signature", () => {
     const res = await handle(
       upgradeRequest({ timestamp: "" }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -355,7 +348,7 @@ describe("handshake signature", () => {
     const res = await handle(
       upgradeRequest({ signPath: "/webhooks/plugins/meeting-bot/other" }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -370,7 +363,7 @@ describe("handshake signature", () => {
     const res = await handle(
       upgradeRequest(),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -388,7 +381,7 @@ describe("handshake signature", () => {
       await handle(
         upgradeRequest({ secret: CADET_SECRET }),
         server,
-        "meeting-bot",
+        "example",
         "realtime",
       ),
     ).toBeUndefined();
@@ -397,7 +390,7 @@ describe("handshake signature", () => {
     const rejected = await handle(
       upgradeRequest({ secret: PLUGIN_SECRET }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
     expect(rejected?.status).toBe(403);
@@ -433,7 +426,7 @@ describe("signed-query handshake", () => {
     const res = await handle(
       signedQueryRequest(),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -454,7 +447,7 @@ describe("signed-query handshake", () => {
     const res = await handle(
       new Request(url.toString(), { headers: { upgrade: "websocket" } }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -469,7 +462,7 @@ describe("signed-query handshake", () => {
     const res = await handle(
       signedQueryRequest({ secret: "not-the-plugin-secret" }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -487,7 +480,7 @@ describe("signed-query handshake", () => {
     const res = await handle(
       signedQueryRequest(),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -503,7 +496,7 @@ describe("signed-query handshake", () => {
     const res = await handle(
       upgradeRequest({ secret: PLUGIN_SECRET }),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -523,7 +516,7 @@ describe("signed-query handshake", () => {
     const res = await handle(
       new Request(url.toString()),
       server,
-      "meeting-bot",
+      "example",
       "realtime",
     );
 
@@ -551,7 +544,7 @@ function socketData(
   return {
     wsType: "plugin-webhook",
     config: CONFIG,
-    plugin: "meeting-bot",
+    plugin: "example",
     path: "realtime",
     queue: [],
     queuedBytes: 0,
@@ -591,7 +584,7 @@ describe("frame delivery", () => {
     expect(calls).toHaveLength(1);
     expect(calls[0]!.method).toBe("user_route_post");
     expect(calls[0]!.params).toMatchObject({
-      pathParams: { path: "plugins/meeting-bot/realtime" },
+      pathParams: { path: "plugins/example/realtime" },
     });
     // The frame travels as the raw body, byte-for-byte.
     expect(new TextDecoder().decode(calls[0]!.binary)).toBe(evt("joined"));

package/src/http/routes/plugin-webhook-websocket.ts

@@ -41,6 +41,7 @@ import {
   timestampWithinTolerance,
   verifyCadetSignature,
 } from "../cadet-signature.js";
+import { isWebsocketUpgradeRequest } from "../utils.js";
 
 const log = getLogger("plugin-webhook-ws");
 
@@ -131,7 +132,7 @@ export function createPluginWebhookWebsocketHandler(deps: PluginWebhookWsDeps) {
     plugin: string,
     path: string,
   ): Promise<Response | undefined> {
-    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+    if (!isWebsocketUpgradeRequest(req)) {
       return new Response("Upgrade Required", { status: 426 });
     }
 

package/src/http/routes/remote-web-pairing-challenge.ts

@@ -21,7 +21,14 @@ import { methodNotAllowed, readJsonStringField } from "../route-helpers.js";
 
 const MAX_CHALLENGE_BODY_BYTES = 512;
 
-function parsePublicBaseUrl(value: string): string | null {
+/**
+ * Normalize an advertised base URL to `origin + trailing-slash-stripped path`,
+ * or null when the value is empty, unparseable, non-http(s), or hostless.
+ * Shared with the direct pairing mint (remote-web/pairing-mint.ts), which
+ * validates the CLI-passed URL with the exact same rules the HTTP route
+ * applies.
+ */
+export function parsePublicBaseUrl(value: string): string | null {
   if (!value.trim()) {
     return null;
   }

package/src/http/routes/runtime-audio-stream.ts

@@ -35,6 +35,7 @@ import {
 import { admitActorToken } from "../../auth/actor-token-revocation.js";
 import { parseSub } from "../../auth/subject.js";
 import type { GatewayConfig } from "../../config.js";
+import { isWebsocketUpgradeRequest } from "../utils.js";
 
 /**
  * Cap on frames held while the upstream socket is still connecting, so a
@@ -83,7 +84,7 @@ export function authorizeRuntimeAudioStream(
   config: GatewayConfig,
   log: Logger,
 ): RuntimeAudioStreamAuth {
-  if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+  if (!isWebsocketUpgradeRequest(req)) {
     return {
       ok: false,
       response: new Response("Upgrade Required", { status: 426 }),

package/src/http/routes/speech-relay-websocket.ts

@@ -33,6 +33,7 @@ import { getLogger } from "../../logger.js";
 import { getCloudBaseUrl } from "../../cloud-url.js";
 import { TUNNEL_FORWARDED_HEADER } from "../../tunnel/bridge-utils.js";
 import { requestHasTunnelBridgeAuth } from "../../tunnel/bridge-auth.js";
+import { isWebsocketUpgradeRequest } from "../utils.js";
 
 const log = getLogger("speech-relay-ws");
 
@@ -325,7 +326,7 @@ export function createSpeechRelayUpgradeHandler(
 
     // Non-upgrade request: this is the daemon's dial-failure probe.
     // Replay the gate and hand back tunnel's own rejection.
-    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+    if (!isWebsocketUpgradeRequest(req)) {
       const apiKey = await readAssistantApiKey(deps);
       if (!apiKey) {
         return jsonError(

package/src/http/utils.ts

@@ -0,0 +1,3 @@
+export function isWebsocketUpgradeRequest(req: Request) {
+  return req.headers.get("upgrade")?.toLowerCase() === "websocket";
+}

package/src/index.ts

@@ -278,6 +278,7 @@ import {
   enablePublicIngress,
 } from "./tunnel/client.js";
 import { VERSION_HEADER_NAME, VERSION_HEADER_VALUE } from "./version.js";
+import { isWebsocketUpgradeRequest } from "./http/utils.js";
 
 const log = getLogger("main");
 
@@ -889,11 +890,11 @@ async function main() {
       handler: () => psHandler.handlePs(),
     },
 
-    // ── Ingress domain recording (localhost CLI only, bearer-authed) ──
+    // ── Ingress domain recording (guardian bearer, loopback fallback) ──
     {
       path: "/v1/ingress/domains",
       method: "POST",
-      auth: "edge",
+      auth: "edge-guardian",
       handler: (req, _params, getClientIp) =>
         handleSaveIngressDomain(req, getClientIp(), configFileCache),
     },
@@ -2309,7 +2310,7 @@ async function main() {
     // Plugin ingress declared as `websocket`. Claimed only for a genuine
     // upgrade — a plain request to the same path stays with the route table,
     // where the HTTP half 404s it for not being an approved HTTP route.
-    if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+    if (isWebsocketUpgradeRequest(req)) {
       const match = url.pathname.match(PLUGIN_WEBHOOK_PATH_PATTERN);
       if (match) {
         const upgradeResult = await handlePluginWebhookWs(

package/src/remote-web/pairing-challenge-rate-limit-store.ts

@@ -1,5 +1,28 @@
+/**
+ * Creation-rate limit for remote-web pairing challenges — 20 per minute,
+ * FILE-BACKED under GATEWAY_SECURITY_DIR so every minting process counts
+ * against the same window: the `gateway pairing mint` CLI runs in its own
+ * process (never over the gateway's IPC socket — the assistant daemon shares
+ * that socket), and the gateway's HTTP mint route runs in the server
+ * process. A per-process window would be meaningless for the CLI (a fresh
+ * process per mint), so the timestamps persist to disk and every call
+ * re-reads them.
+ */
+
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getGatewaySecurityDir } from "../paths.js";
+
 const RATE_LIMIT_MAX_CHALLENGES = 20;
 const RATE_LIMIT_WINDOW_MS = 60_000;
+const STORE_FILENAME = "remote-web-pairing-creation-rate.json";
 
 export interface RemoteWebPairingChallengeRateLimit {
   retryAfterSeconds: number;
@@ -7,7 +30,69 @@ export interface RemoteWebPairingChallengeRateLimit {
 
 const challengeCreationTimestamps: number[] = [];
 
+let lastResolvedStorePath: string | null = null;
+
+function rateLimitStoreFilePath(): string {
+  const resolved = join(getGatewaySecurityDir(), STORE_FILENAME);
+  lastResolvedStorePath = resolved;
+  return resolved;
+}
+
+function isNotExistError(err: unknown): boolean {
+  return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+
+/** Re-sync the timestamps from disk; a missing file is an empty window. */
+function loadFromDisk(): void {
+  challengeCreationTimestamps.length = 0;
+
+  let raw: string;
+  try {
+    raw = readFileSync(rateLimitStoreFilePath(), "utf-8");
+  } catch (err) {
+    if (isNotExistError(err)) return;
+    throw err;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    console.warn(
+      `[pairing-challenge-rate-limit] could not read ${rateLimitStoreFilePath()} — starting empty.`,
+    );
+    return;
+  }
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    !("timestamps" in parsed) ||
+    !Array.isArray(parsed.timestamps)
+  ) {
+    return;
+  }
+  for (const timestamp of parsed.timestamps) {
+    if (typeof timestamp === "number") {
+      challengeCreationTimestamps.push(timestamp);
+    }
+  }
+}
+
+/** Persist the current window atomically so other processes see it. */
+function saveToDisk(): void {
+  const filePath = rateLimitStoreFilePath();
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.tmp`;
+  writeFileSync(
+    tmpPath,
+    JSON.stringify({ timestamps: [...challengeCreationTimestamps] }),
+    { mode: 0o600 },
+  );
+  renameSync(tmpPath, filePath);
+}
+
 export function recordRemoteWebPairingChallengeCreation(): RemoteWebPairingChallengeRateLimit | null {
+  loadFromDisk();
   const now = Date.now();
   const windowStart = now - RATE_LIMIT_WINDOW_MS;
 
@@ -26,9 +111,18 @@ export function recordRemoteWebPairingChallengeCreation(): RemoteWebPairingChall
   }
 
   challengeCreationTimestamps.push(now);
+  saveToDisk();
   return null;
 }
 
 export function resetRemoteWebPairingChallengeRateLimiterForTests(): void {
   challengeCreationTimestamps.length = 0;
+  // Best effort on the LAST-RESOLVED path — see the challenge store's note.
+  if (lastResolvedStorePath) {
+    try {
+      rmSync(lastResolvedStorePath, { force: true });
+    } catch {
+      /* the timestamps are cleared either way */
+    }
+  }
 }

package/src/remote-web/pairing-challenge-store.ts

@@ -1,4 +1,14 @@
 import { createHash, randomBytes, randomInt } from "node:crypto";
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getGatewaySecurityDir } from "../paths.js";
 
 import {
   REMOTE_WEB_PAIRING_CODE_TTL_MS,
@@ -70,6 +80,94 @@ function nowMs(): number {
   return nowForTests?.() ?? Date.now();
 }
 
+/**
+ * The challenge store is FILE-BACKED under GATEWAY_SECURITY_DIR so a mint can
+ * run in ANY process: `gateway pairing mint` executes the mint logic directly
+ * (deliberately never over the gateway's IPC socket — the assistant daemon
+ * shares that socket, and an IPC-exposed mint would let the assistant
+ * approve pairings for itself) and persists the challenge here. The running
+ * gateway's verification and token-exchange routes re-read the file on every
+ * store call, so cross-process writes land. Writes are atomic (tmp + rename)
+ * and the single-user local flow makes last-writer-wins races a non-issue.
+ */
+const STORE_FILENAME = "remote-web-pairing-challenges.json";
+
+let lastResolvedStorePath: string | null = null;
+
+function challengeStoreFilePath(): string {
+  const resolved = join(getGatewaySecurityDir(), STORE_FILENAME);
+  lastResolvedStorePath = resolved;
+  return resolved;
+}
+
+function isNotExistError(err: unknown): boolean {
+  return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+
+function isChallengeLike(
+  value: unknown,
+): value is PendingRemoteWebPairingChallenge {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "userCodeHash" in value &&
+    typeof value.userCodeHash === "string" &&
+    "deviceCodeHash" in value &&
+    typeof value.deviceCodeHash === "string"
+  );
+}
+
+/**
+ * Re-sync the in-memory maps from disk at the top of every exported call.
+ * A missing file is an empty store; a corrupt one warns and starts empty.
+ * Expired challenges are NOT dropped here — the same cleanup/expiry checks
+ * that ran before file-backing still classify them ("expired", not
+ * "invalid") and delete them on their own paths.
+ */
+function loadFromDisk(): void {
+  challengesByUserCodeHash.clear();
+  challengesByDeviceCodeHash.clear();
+
+  let raw: string;
+  try {
+    raw = readFileSync(challengeStoreFilePath(), "utf-8");
+  } catch (err) {
+    if (isNotExistError(err)) return;
+    throw err;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    parsed = null;
+  }
+  if (!Array.isArray(parsed)) {
+    console.warn(
+      `[pairing-challenge-store] could not read ${challengeStoreFilePath()} — starting empty.`,
+    );
+    return;
+  }
+  for (const entry of parsed) {
+    if (!isChallengeLike(entry)) continue;
+    challengesByUserCodeHash.set(entry.userCodeHash, entry);
+    challengesByDeviceCodeHash.set(entry.deviceCodeHash, entry);
+  }
+}
+
+/** Persist the current challenges so other processes can see them. */
+function saveToDisk(): void {
+  const filePath = challengeStoreFilePath();
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.tmp`;
+  writeFileSync(
+    tmpPath,
+    JSON.stringify([...challengesByUserCodeHash.values()]),
+    { mode: 0o600 },
+  );
+  renameSync(tmpPath, filePath);
+}
+
 function hashSecret(value: string): string {
   return createHash("sha256").update(value).digest("hex");
 }
@@ -100,6 +198,7 @@ function cleanupExpiredChallenges(now = nowMs()): void {
 }
 
 export function checkRemoteWebPairingChallengeCapacity(): RemoteWebPairingChallengeCapacityLimit | null {
+  loadFromDisk();
   const now = nowMs();
   cleanupExpiredChallenges(now);
 
@@ -122,6 +221,7 @@ export function createRemoteWebPairingChallenge(
   publicBaseUrl: string,
   requester: { ip: string; userAgent: string | null; viaEdgeProxy: boolean },
 ): RemoteWebPairingChallengeResponse {
+  loadFromDisk();
   cleanupExpiredChallenges();
 
   const deviceCode = randomBytes(DEVICE_CODE_BYTES).toString("base64url");
@@ -152,6 +252,7 @@ export function createRemoteWebPairingChallenge(
   };
   challengesByUserCodeHash.set(userCodeHash, challenge);
   challengesByDeviceCodeHash.set(deviceCodeHash, challenge);
+  saveToDisk();
 
   return {
     deviceCode,
@@ -188,12 +289,15 @@ function approveChallenge(
 export function approveRemoteWebPairingChallenge(
   userCode: string,
 ): ApproveRemoteWebPairingChallengeResult {
+  loadFromDisk();
   const userCodeHash = hashSecret(normalizeUserCode(userCode));
   const challenge = challengesByUserCodeHash.get(userCodeHash);
   if (!challenge) {
     return { status: "invalid" };
   }
-  return approveChallenge(challenge);
+  const result = approveChallenge(challenge);
+  saveToDisk();
+  return result;
 }
 
 function findChallengeById(
@@ -208,6 +312,7 @@ function findChallengeById(
 }
 
 export function listPendingRemoteWebPairingChallenges(): RemoteWebPairingRequestSummary[] {
+  loadFromDisk();
   cleanupExpiredChallenges();
 
   const pending = [...challengesByUserCodeHash.values()]
@@ -229,11 +334,14 @@ export function listPendingRemoteWebPairingChallenges(): RemoteWebPairingRequest
 export function approveRemoteWebPairingChallengeById(
   id: string,
 ): ApproveRemoteWebPairingChallengeResult {
+  loadFromDisk();
   const challenge = findChallengeById(id);
   if (!challenge) {
     return { status: "invalid" };
   }
-  return approveChallenge(challenge);
+  const result = approveChallenge(challenge);
+  saveToDisk();
+  return result;
 }
 
 export type DenyRemoteWebPairingChallengeResult =
@@ -244,6 +352,7 @@ export type DenyRemoteWebPairingChallengeResult =
 export function denyRemoteWebPairingChallengeById(
   id: string,
 ): DenyRemoteWebPairingChallengeResult {
+  loadFromDisk();
   const challenge = findChallengeById(id);
   if (!challenge) {
     return { status: "invalid" };
@@ -256,12 +365,14 @@ export function denyRemoteWebPairingChallengeById(
   }
 
   deleteChallenge(challenge);
+  saveToDisk();
   return { status: "denied" };
 }
 
 export function claimRemoteWebPairingChallengeExchange(
   deviceCode: string,
 ): ClaimRemoteWebPairingChallengeExchangeResult {
+  loadFromDisk();
   const deviceCodeHash = hashSecret(deviceCode);
   const challenge = challengesByDeviceCodeHash.get(deviceCodeHash);
   if (!challenge) return { status: "invalid" };
@@ -269,6 +380,7 @@ export function claimRemoteWebPairingChallengeExchange(
   const now = nowMs();
   if (challenge.expiresAtMs <= now) {
     deleteChallenge(challenge);
+    saveToDisk();
     return { status: "expired" };
   }
 
@@ -290,6 +402,7 @@ export function claimRemoteWebPairingChallengeExchange(
 
   challenge.status = "exchanging";
   challenge.exchangeStartedAtMs = now;
+  saveToDisk();
   return {
     status: "approved",
     publicBaseUrl: challenge.publicBaseUrl,
@@ -301,27 +414,41 @@ export function claimRemoteWebPairingChallengeExchange(
 export function completeRemoteWebPairingChallengeExchange(
   deviceCode: string,
 ): void {
+  loadFromDisk();
   const challenge = challengesByDeviceCodeHash.get(hashSecret(deviceCode));
   if (!challenge || challenge.status !== "exchanging") return;
 
   challenge.status = "consumed";
   challenge.consumedAtMs = nowMs();
+  saveToDisk();
 }
 
 export function releaseRemoteWebPairingChallengeExchange(
   deviceCode: string,
 ): void {
+  loadFromDisk();
   const challenge = challengesByDeviceCodeHash.get(hashSecret(deviceCode));
   if (!challenge || challenge.status !== "exchanging") return;
 
   challenge.status = "approved";
   challenge.exchangeStartedAtMs = undefined;
+  saveToDisk();
 }
 
 export function resetRemoteWebPairingChallengesForTests(): void {
   challengesByUserCodeHash.clear();
   challengesByDeviceCodeHash.clear();
   nowForTests = null;
+  // Best effort on the LAST-RESOLVED path: test files may delete
+  // GATEWAY_SECURITY_DIR before this runs, and re-resolving then would
+  // either throw the ephemeral-path guard or point at the wrong dir.
+  if (lastResolvedStorePath) {
+    try {
+      rmSync(lastResolvedStorePath, { force: true });
+    } catch {
+      /* the maps are cleared either way */
+    }
+  }
 }
 
 export function setRemoteWebPairingChallengeNowForTests(
@@ -333,5 +460,6 @@ export function setRemoteWebPairingChallengeNowForTests(
 export function getRemoteWebPairingChallengeForTests(
   userCode: string,
 ): PendingRemoteWebPairingChallenge | undefined {
+  loadFromDisk();
   return challengesByUserCodeHash.get(hashSecret(normalizeUserCode(userCode)));
 }

package/src/remote-web/pairing-mint.ts

@@ -0,0 +1,94 @@
+/**
+ * Mint-and-approve for the remote-web pairing flow — executed DIRECTLY in
+ * the calling process (the `gateway pairing mint` CLI), deliberately NOT
+ * exposed over the gateway's IPC socket: the assistant daemon shares that
+ * socket, and an IPC-exposed mint would let the assistant mint + approve
+ * pairings for itself, defeating the local-presence proof. Challenges
+ * persist to the file-backed pairing store under GATEWAY_SECURITY_DIR, so
+ * the RUNNING gateway's verification and token-exchange routes see what
+ * this mints.
+ *
+ * This is the exact sequence the loopback HTTP mint used to run (parse →
+ * rate-limit → capacity → create → approve), with the requester metadata
+ * honestly naming the CLI invocation instead of an HTTP peer.
+ */
+
+import type { RemoteWebPairingChallengeResponse } from "@mycadet/service-contracts/remote-web-pairing";
+
+import { parsePublicBaseUrl } from "../http/routes/remote-web-pairing-challenge.js";
+import { recordRemoteWebPairingChallengeCreation } from "./pairing-challenge-rate-limit-store.js";
+import {
+  approveRemoteWebPairingChallenge,
+  checkRemoteWebPairingChallengeCapacity,
+  createRemoteWebPairingChallenge,
+  type RemoteWebPairingChallengeCapacityLimit,
+} from "./pairing-challenge-store.js";
+
+/**
+ * Client-facing failure with a stable code (BAD_REQUEST, RATE_LIMITED,
+ * PAIRING_CHALLENGE_CAPACITY_EXCEEDED, MINT_APPROVAL_FAILED).
+ */
+export class PairingMintError extends Error {
+  readonly code: string;
+
+  constructor(message: string, code: string) {
+    super(message);
+    this.name = "PairingMintError";
+    this.code = code;
+  }
+}
+
+function rateLimitError(retryAfterSeconds: number): PairingMintError {
+  return new PairingMintError(
+    `too many remote web pairing challenges; retry in ${retryAfterSeconds}s`,
+    "RATE_LIMITED",
+  );
+}
+
+function capacityLimitError(
+  limit: RemoteWebPairingChallengeCapacityLimit,
+): PairingMintError {
+  return new PairingMintError(
+    `too many pending remote web pairing challenges; retry in ${limit.retryAfterSeconds}s`,
+    "PAIRING_CHALLENGE_CAPACITY_EXCEEDED",
+  );
+}
+
+export function mintAndApproveRemoteWebPairingChallenge(
+  publicBaseUrlRaw: string,
+): RemoteWebPairingChallengeResponse {
+  const publicBaseUrl = parsePublicBaseUrl(publicBaseUrlRaw);
+  if (!publicBaseUrl) {
+    throw new PairingMintError(
+      "publicBaseUrl is required (an http(s) URL with a host)",
+      "BAD_REQUEST",
+    );
+  }
+
+  const rateLimited = recordRemoteWebPairingChallengeCreation();
+  if (rateLimited) throw rateLimitError(rateLimited.retryAfterSeconds);
+
+  const capacityLimited = checkRemoteWebPairingChallengeCapacity();
+  if (capacityLimited) throw capacityLimitError(capacityLimited);
+
+  // The requester fields back the host approval UI; a direct mint has no
+  // HTTP peer to report, so the honest provenance is the CLI invocation
+  // itself.
+  const challenge = createRemoteWebPairingChallenge(publicBaseUrl, {
+    ip: "cli",
+    userAgent: null,
+    viaEdgeProxy: false,
+  });
+
+  const approved = approveRemoteWebPairingChallenge(challenge.userCode);
+  if (approved.status !== "approved") {
+    // Unreachable for a challenge minted this tick, but fail loudly rather
+    // than hand out an unapproved link.
+    throw new PairingMintError(
+      `minted challenge could not be approved (${approved.status})`,
+      "MINT_APPROVAL_FAILED",
+    );
+  }
+
+  return challenge;
+}