@mycadet/gateway 0.12.8 → 0.12.9-dev.202610131452.9acab64

package/node_modules/@mycadet/ces-client/node_modules/@mycadet/service-contracts/package.json

@@ -40,6 +40,6 @@
   },
   "devDependencies": {
     "@types/bun": "1.2.4",
-    "typescript": "5.7.3"
+    "typescript": "5.9.3"
   }
 }

package/node_modules/@mycadet/ces-client/package.json

@@ -19,6 +19,6 @@
   },
   "devDependencies": {
     "@types/bun": "1.2.4",
-    "typescript": "5.7.3"
+    "typescript": "5.9.3"
   }
 }

package/node_modules/@mycadet/ces-client/src/__tests__/ces-client.test.ts

@@ -141,7 +141,7 @@ describe("CesHttpCredentialClient", () => {
       Promise.resolve(
         Response.json({ account: "test-acct", value: "secret-123" }),
       ),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -156,7 +156,7 @@ describe("CesHttpCredentialClient", () => {
   test("get returns not-found on 404", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(new Response(null, { status: 404 })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -171,7 +171,7 @@ describe("CesHttpCredentialClient", () => {
   test("get returns unreachable on 500", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(new Response("internal error", { status: 500 })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -186,7 +186,7 @@ describe("CesHttpCredentialClient", () => {
   test("get returns unreachable on network error", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("ECONNREFUSED")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -201,7 +201,7 @@ describe("CesHttpCredentialClient", () => {
   test("delete returns deleted on 200", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(Response.json({ ok: true, account: "acct" })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -215,7 +215,7 @@ describe("CesHttpCredentialClient", () => {
   test("delete returns not-found on 404", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(new Response(null, { status: 404 })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -229,7 +229,7 @@ describe("CesHttpCredentialClient", () => {
   test("delete returns error on network failure", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("network down")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -243,7 +243,7 @@ describe("CesHttpCredentialClient", () => {
   test("list returns accounts on 200", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(Response.json({ accounts: ["a", "b", "c"] })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -258,7 +258,7 @@ describe("CesHttpCredentialClient", () => {
   test("list returns unreachable on error", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("timeout")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -273,7 +273,7 @@ describe("CesHttpCredentialClient", () => {
   test("bulkSet returns all-failed when request fails", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("network")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -311,7 +311,7 @@ describe("fetchCesLogExport", () => {
           headers: { "Content-Type": "application/gzip" },
         }),
       ),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const result = await fetchCesLogExport({
       baseUrl: "http://ces-test:8090",
@@ -327,7 +327,7 @@ describe("fetchCesLogExport", () => {
   test("returns error on non-OK status", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(new Response("forbidden", { status: 403 })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const result = await fetchCesLogExport({
       baseUrl: "http://ces-test:8090",
@@ -343,7 +343,7 @@ describe("fetchCesLogExport", () => {
   test("returns error on network failure", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("connection refused")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const result = await fetchCesLogExport({
       baseUrl: "http://ces-test:8090",
@@ -361,7 +361,7 @@ describe("fetchCesLogExport", () => {
     globalThis.fetch = mock((url: string | URL | Request) => {
       capturedUrl = typeof url === "string" ? url : url.toString();
       return Promise.resolve(new Response(new ArrayBuffer(0), { status: 200 }));
-    }) as typeof fetch;
+    }) as unknown as typeof fetch;
 
     await fetchCesLogExport(
       { baseUrl: "http://ces-test:8090", serviceToken: "tok" },

package/node_modules/@mycadet/gateway-client/node_modules/@mycadet/service-contracts/package.json

@@ -40,6 +40,6 @@
   },
   "devDependencies": {
     "@types/bun": "1.2.4",
-    "typescript": "5.7.3"
+    "typescript": "5.9.3"
   }
 }

package/node_modules/@mycadet/service-contracts/package.json

@@ -40,6 +40,6 @@
   },
   "devDependencies": {
     "@types/bun": "1.2.4",
-    "typescript": "5.7.3"
+    "typescript": "5.9.3"
   }
 }

package/openapi.json

@@ -2,10 +2,10 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Cadet Gateway API",
-    "version": "0.12.6",
+    "version": "0.12.8",
     "description": "Auto-generated OpenAPI specification for the Cadet Gateway HTTP endpoints."
   },
-  "servers": [{ "url": "", "description": "Same-origin (gateway)" }],
+  "servers": [{ "url": "", "description": "Same-origin — the gateway" }],
   "paths": {
     "/v1/permissions/thresholds": {
       "get": {
@@ -105,7 +105,7 @@
         "operationId": "conversationThresholdGet",
         "summary": "Get a conversation's threshold override",
         "tags": ["permissions"],
-        "description": "Returns { threshold: null } when no override exists. (Gateways predating that behavior returned 404 for the same condition; clients tolerate both during rollout.)",
+        "description": "Returns { threshold: null } when no override exists. Gateways predating that behavior returned 404 for the same condition; clients tolerate both during rollout.",
         "parameters": [
           {
             "name": "conversation_id",
@@ -209,7 +209,7 @@
         "operationId": "channelAdmissionPolicyList",
         "summary": "List per-channel admission floors",
         "tags": ["channel-admission-policy"],
-        "description": "Returns one entry per enforced channel (exempt and hidden channels are omitted), seeded with defaults for channels without a stored row.",
+        "description": "Returns one entry per enforced channel, excluding exempt and hidden channels, seeded with defaults for channels without a stored row.",
         "responses": {
           "200": {
             "description": "Successful response",
@@ -272,7 +272,7 @@
             "in": "path",
             "required": true,
             "schema": { "type": "string" },
-            "description": "The channel type (e.g. slack)"
+            "description": "The channel type, e.g. slack"
           }
         ],
         "requestBody": {
@@ -452,7 +452,7 @@
             "in": "path",
             "required": true,
             "schema": { "type": "string" },
-            "description": "The declaring ingress source (today, a plugin name)"
+            "description": "The declaring ingress source, today a plugin name"
           }
         ],
         "requestBody": {
@@ -502,7 +502,7 @@
             "in": "path",
             "required": true,
             "schema": { "type": "string" },
-            "description": "The declaring ingress source (today, a plugin name)"
+            "description": "The declaring ingress source, today a plugin name"
           }
         ],
         "responses": {
@@ -530,7 +530,7 @@
         "operationId": "channelPermissionOverridesList",
         "summary": "List channel-permission matrix cells",
         "tags": ["channel-permission-overrides"],
-        "description": "Returns every persisted cell (cascade selector × contact-type → RiskThreshold). Unset cells fall through the cascade; the list contains only explicit overrides.",
+        "description": "Returns every persisted cell in the cascade selector × contact-type → RiskThreshold map. Unset cells fall through the cascade; the list contains only explicit overrides.",
         "responses": {
           "200": {
             "description": "Successful response",
@@ -854,7 +854,7 @@
         "operationId": "channelPermissionResolve",
         "summary": "Resolve the effective channel-permission threshold",
         "tags": ["channel-permission-overrides"],
-        "description": "Read-only cascade resolution for one coordinate: walks channel → channel_type → adapter → workspace for the given selector keys and contact-type, returning the winning cell's threshold and scope, or null when no cell matches (the caller then falls through to the global thresholds). Same resolver the runtime evaluator uses over IPC.",
+        "description": "Read-only cascade resolution for one coordinate: walks channel → channel_type → adapter → workspace for the given selector keys and contact-type, returning the winning cell's threshold and scope, or null when no cell matches, in which case the caller falls through to the global thresholds. Same resolver the runtime evaluator uses over IPC.",
         "requestBody": {
           "required": true,
           "content": {
@@ -931,7 +931,7 @@
         "operationId": "channelPermissionOverrideDelete",
         "summary": "Delete a channel-permission matrix cell",
         "tags": ["channel-permission-overrides"],
-        "description": "Removes one cell by its composite key (selector × contact-type), letting the next cascade tier up win. Returns whether a cell was removed.",
+        "description": "Removes one cell by its composite key, selector × contact-type, letting the next cascade tier up win. Returns whether a cell was removed.",
         "requestBody": {
           "required": true,
           "content": {
@@ -1027,7 +1027,7 @@
         "operationId": "contactsUpsert",
         "summary": "Create or update a contact",
         "tags": ["contacts"],
-        "description": "Gateway-native contact upsert (dual-writes the gateway ACL store and the assistant info mirror). Matches by id, then by any provided (type, address) channel, else creates.",
+        "description": "Gateway-native contact upsert that dual-writes the gateway ACL store and the assistant info mirror. Matches by id, then by the provided type and address channel, else creates.",
         "requestBody": {
           "required": true,
           "content": {
@@ -1085,7 +1085,7 @@
                         "address": { "type": "string" },
                         "isPrimary": { "type": "boolean" },
                         "externalChatId": {
-                          "description": "Delivery chat id. Omit to preserve the stored value. A legacy explicit null is accepted for compatibility and treated as omitted; clearing is not supported (a stored null is indistinguishable from never-learned, so no consumer could tell a clear from a gap).",
+                          "description": "Delivery chat id. Omit to preserve the stored value. A legacy explicit null is accepted for compatibility and treated as omitted; clearing is not supported: a stored null is indistinguishable from never-learned, so no consumer could tell a clear from a gap.",
                           "type": "string"
                         },
                         "status": { "type": "string" },
@@ -1141,7 +1141,7 @@
                             },
                             { "type": "null" }
                           ],
-                          "description": "Per-contact auto-approve ceiling. Null means unset (inherit cascade)."
+                          "description": "Per-contact auto-approve ceiling. Null means unset, inheriting the cascade."
                         },
                         "assistantMetadata": {
                           "anyOf": [
@@ -1184,7 +1184,7 @@
                               },
                               "externalUserId": {
                                 "type": "string",
-                                "description": "Compat alias for address (older macOS clients)"
+                                "description": "Compat alias for address, for older macOS clients"
                               },
                               "status": {
                                 "anyOf": [
@@ -1479,7 +1479,7 @@
         "operationId": "contactChannelVerify",
         "summary": "Manually verify a contact channel",
         "tags": ["contacts"],
-        "description": "Guardian-only manual attestation: marks the channel active/verified in the gateway store (source of truth) with a best-effort assistant mirror. Idempotent.",
+        "description": "Guardian-only manual attestation: marks the channel active/verified in the gateway store, the source of truth, with a best-effort assistant mirror. Idempotent.",
         "parameters": [
           {
             "name": "channel_id",
@@ -1828,7 +1828,7 @@
             "in": "query",
             "required": false,
             "schema": { "type": "string" },
-            "description": "Filter by origin (default | user_defined)"
+            "description": "Filter by origin: default or user_defined"
           },
           {
             "name": "tool",
@@ -1929,7 +1929,7 @@
                   },
                   "description": { "type": "string", "minLength": 1 },
                   "scope": {
-                    "description": "Compatibility field. Trust rules apply workspace-wide: the engine matches on (tool, pattern) only, so a narrower scope cannot be honored and any value other than \"everywhere\" is rejected rather than stored broader than the consent it records.",
+                    "description": "Compatibility field. Trust rules apply workspace-wide: the engine matches on tool and pattern only, so a narrower scope cannot be honored and any value other than \"everywhere\" is rejected rather than stored broader than the consent it records.",
                     "type": "string",
                     "const": "everywhere"
                   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycadet/gateway",
-  "version": "0.12.8",
+  "version": "0.12.9-dev.202610131452.9acab64",
   "license": "MIT",
   "type": "module",
   "exports": {

package/scripts/generate-openapi.ts

@@ -126,7 +126,7 @@ function buildSpec(version: string) {
       description:
         "Auto-generated OpenAPI specification for the Cadet Gateway HTTP endpoints.",
     },
-    servers: [{ url: "", description: "Same-origin (gateway)" }],
+    servers: [{ url: "", description: "Same-origin — the gateway" }],
     paths,
   });
 }

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/auth/guardian-bootstrap.ts

@@ -41,6 +41,7 @@ import {
 import { CURRENT_POLICY_EPOCH } from "./policy.js";
 import { mintToken } from "./token-service.js";
 import type { ScopeProfile } from "./types.js";
+import { getIsCloud } from "../cloud-url.js";
 
 const log = getLogger("guardian-bootstrap");
 
@@ -1046,9 +1047,7 @@ async function fetchPlatformOwnerDisplayName(): Promise<string | null> {
     return null;
   }
 
-  const isCloud =
-    process.env.IS_CLOUD?.trim().toLowerCase() === "true" ||
-    process.env.IS_CLOUD?.trim() === "1";
+  const isCloud = getIsCloud();
   if (!isCloud) return null;
 
   const assistantApiKey = await readCredential(

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/contacts.ts

@@ -204,7 +204,9 @@ export async function executeContactsCommand(
       );
     }
     console.log("");
-    console.log(`${contacts.length} contact(s)`);
+    console.log(
+      `${contacts.length} ${contacts.length === 1 ? "contact" : "contacts"}`,
+    );
     return 0;
   }
 

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 contact ACL (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;
+  }
+}