@mycadet/gateway 0.12.11 → 0.13.0

package/src/__tests__/ipc-feature-flag-routes.test.ts

@@ -8,10 +8,6 @@ import { connectClient, sendRequest } from "./helpers/ipc-newline-client.js";
 
 const protectedDir = testSecurityDir;
 const featureFlagStorePath = join(protectedDir, "feature-flags.json");
-const remoteFeatureFlagStorePath = join(
-  protectedDir,
-  "feature-flags-remote.json",
-);
 
 // Write the test registry to an isolated temp path
 const defaultsPath = join(protectedDir, "feature-flag-registry.json");
@@ -63,7 +59,6 @@ beforeEach(() => {
   _setRegistryCandidateOverrides([defaultsPath]);
   resetFeatureFlagDefaultsCache();
   clearFeatureFlagStoreCache();
-  clearRemoteFeatureFlagStoreCache();
 });
 
 afterEach(() => {
@@ -76,7 +71,6 @@ afterEach(() => {
   _setRegistryCandidateOverrides(null);
   resetFeatureFlagDefaultsCache();
   clearFeatureFlagStoreCache();
-  clearRemoteFeatureFlagStoreCache();
   resetEnvOverridesCache();
   delete process.env.CADET_FLAG_A2A_CHANNEL;
 });
@@ -84,8 +78,6 @@ afterEach(() => {
 const { resetFeatureFlagDefaultsCache, _setRegistryCandidateOverrides } =
   await import("../feature-flag-defaults.js");
 const { clearFeatureFlagStoreCache } = await import("../feature-flag-store.js");
-const { clearRemoteFeatureFlagStoreCache } =
-  await import("../feature-flag-remote-store.js");
 const { resetEnvOverridesCache } =
   await import("../feature-flag-env-overrides.js");
 const { GatewayIpcServer } = await import("../ipc/server.js");
@@ -161,54 +153,6 @@ describe("IPC feature flag routes", () => {
     expect(flags["a2a-channel"]).toBe(false); // still default
   });
 
-  test("get_feature_flags merges remote values when no local override", async () => {
-    writeFileSync(
-      remoteFeatureFlagStorePath,
-      JSON.stringify({
-        version: 1,
-        values: { "a2a-channel": true },
-      }),
-    );
-    clearRemoteFeatureFlagStoreCache();
-
-    // No local override
-    if (existsSync(featureFlagStorePath)) {
-      rmSync(featureFlagStorePath);
-    }
-    clearFeatureFlagStoreCache();
-
-    await startServerAndConnect();
-    const res = await sendRequest(client, "get_feature_flags");
-
-    expect(res.error).toBeUndefined();
-    const flags = res.result as Record<string, boolean>;
-    expect(flags["a2a-channel"]).toBe(true); // remote overrides default
-  });
-
-  test("get_feature_flags falls back to registry defaults for flags missing from a remote snapshot", async () => {
-    writeFileSync(
-      remoteFeatureFlagStorePath,
-      JSON.stringify({
-        version: 1,
-        values: { "a2a-channel": true },
-      }),
-    );
-    clearRemoteFeatureFlagStoreCache();
-
-    if (existsSync(featureFlagStorePath)) {
-      rmSync(featureFlagStorePath);
-    }
-    clearFeatureFlagStoreCache();
-
-    await startServerAndConnect();
-    const res = await sendRequest(client, "get_feature_flags");
-
-    expect(res.error).toBeUndefined();
-    const flags = res.result as Record<string, boolean>;
-    expect(flags["a2a-channel"]).toBe(true);
-    expect(flags["browser"]).toBe(true);
-  });
-
   test("get_feature_flags includes string flag values", async () => {
     if (existsSync(featureFlagStorePath)) rmSync(featureFlagStorePath);
     clearFeatureFlagStoreCache();

package/src/__tests__/lum-2783-recovery-e2e.test.ts

@@ -35,10 +35,6 @@ import {
   resetGatewayDb,
 } from "../db/connection.js";
 import { actorTokenRecords, contacts, contactChannels } from "../db/schema.js";
-import {
-  resetGuardianIntegrityReporterForTesting,
-  setGuardianIntegrityReporterOverridesForTesting,
-} from "../guardian-integrity-reporter.js";
 import { resolveTrustVerdict } from "../risk/trust-verdict-resolver.js";
 
 initSigningKey(Buffer.from("test-signing-key-at-least-32-bytes-long"));
@@ -79,17 +75,9 @@ beforeEach(async () => {
   db.delete(contacts).run();
   db.delete(actorTokenRecords).run();
   bustGuardianIntegrityCache();
-  resetGuardianIntegrityReporterForTesting();
-  setGuardianIntegrityReporterOverridesForTesting({
-    fetchImpl: async () => new Response("{}"),
-    mintToken: () => "svc-token",
-    baseUrl: "http://127.0.0.1:7821",
-    log: { error: () => {}, warn: () => {} },
-  });
 });
 
 afterEach(() => {
-  resetGuardianIntegrityReporterForTesting();
   resetGatewayDb();
 });
 

package/src/__tests__/post-assistant-ready-deferred.test.ts

@@ -50,10 +50,6 @@ const { contacts, contactChannels, actorTokenRecords } =
 const { MIGRATIONS } = await import("../db/data-migrations/index.js");
 const { bustGuardianIntegrityCache } =
   await import("../auth/guardian-integrity.js");
-const {
-  resetGuardianIntegrityReporterForTesting,
-  setGuardianIntegrityReporterOverridesForTesting,
-} = await import("../guardian-integrity-reporter.js");
 const { seedContact, seedActorToken } =
   await import("./helpers/contact-fixtures.js");
 
@@ -134,12 +130,6 @@ describe("runDeferredTasksWhenAssistantReady", () => {
       // ensureCadetGuardianBinding throws CadetGuardianMintRefusedError.
       seedContact({ id: "invited-contact" });
       bustGuardianIntegrityCache();
-      setGuardianIntegrityReporterOverridesForTesting({
-        fetchImpl: async () => new Response("{}"),
-        mintToken: () => "svc-token",
-        baseUrl: "http://127.0.0.1:7821",
-        log: { error: () => {}, warn: () => {} },
-      });
       resetPostAssistantReadyForTest(); // restore the REAL executor
 
       // The refusal is warn-and-continue inside the executor: the deferred
@@ -152,7 +142,6 @@ describe("runDeferredTasksWhenAssistantReady", () => {
       );
       expect(getGatewayDb().select().from(contacts).all()).toHaveLength(1);
     } finally {
-      resetGuardianIntegrityReporterForTesting();
       resetGatewayDb();
     }
   });
@@ -176,12 +165,6 @@ describe("runDeferredTasksWhenAssistantReady", () => {
       }
       seedActorToken(); // active token, guardianPrincipalId "principal-123"
       bustGuardianIntegrityCache();
-      setGuardianIntegrityReporterOverridesForTesting({
-        fetchImpl: async () => new Response("{}"),
-        mintToken: () => "svc-token",
-        baseUrl: "http://127.0.0.1:7821",
-        log: { error: () => {}, warn: () => {} },
-      });
       resetPostAssistantReadyForTest(); // restore the REAL executor
 
       await runDeferredTasksWhenAssistantReady(5);
@@ -202,7 +185,6 @@ describe("runDeferredTasksWhenAssistantReady", () => {
         principalId: "principal-123",
       });
     } finally {
-      resetGuardianIntegrityReporterForTesting();
       resetGatewayDb();
     }
   });

package/src/__tests__/refresh-device-binding.test.ts

@@ -24,10 +24,6 @@ const { handleGuardianRefresh } =
   await import("../http/routes/guardian-refresh.js");
 const { bustGuardianIntegrityCache } =
   await import("../auth/guardian-integrity.js");
-const {
-  resetGuardianIntegrityReporterForTesting,
-  setGuardianIntegrityReporterOverridesForTesting,
-} = await import("../guardian-integrity-reporter.js");
 
 const PRINCIPAL = "guardian-001";
 const DEVICE_A = "device-A";
@@ -128,18 +124,10 @@ beforeEach(async () => {
   // silence the fail-loud reporter for the missing-guardian cases.
   insertGuardianContact();
   bustGuardianIntegrityCache();
-  resetGuardianIntegrityReporterForTesting();
-  setGuardianIntegrityReporterOverridesForTesting({
-    fetchImpl: async () => new Response("{}"),
-    mintToken: () => "svc-token",
-    baseUrl: "http://127.0.0.1:7821",
-    log: { error: () => {}, warn: () => {} },
-  });
 });
 
 afterEach(() => {
   resetGatewayDb();
-  resetGuardianIntegrityReporterForTesting();
   bustGuardianIntegrityCache();
   if (savedSecurityDir === undefined) {
     delete process.env.GATEWAY_SECURITY_DIR;

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

@@ -58,10 +58,6 @@ const {
 } = await import("../remote-web/pairing-challenge-store.js");
 const { bustGuardianIntegrityCache } =
   await import("../auth/guardian-integrity.js");
-const {
-  resetGuardianIntegrityReporterForTesting,
-  setGuardianIntegrityReporterOverridesForTesting,
-} = await import("../guardian-integrity-reporter.js");
 const realBrowserAuthCookies = await import("../http/browser-auth-cookies.js");
 // Captured before any mock is armed: `mock.module` rewrites the live
 // namespace, so a restore needs its own reference to the real function.
@@ -622,6 +618,8 @@ describe("remote web pairing token exchange", () => {
       .where(eq(contacts.role, "guardian"))
       .all();
     expect(gwGuardian).toHaveLength(1);
+    // The pairing flow mints fresh (brand-neutral principal id, see #294) —
+    // recovery from actor-token evidence is boot-time-only.
     expect(gwGuardian[0].principalId).toMatch(/^principal-/);
   });
 
@@ -641,13 +639,13 @@ describe("remote web pairing token exchange", () => {
     const gwDb = getGatewayDb();
     const realTransaction = gwDb.transaction.bind(gwDb);
     let failedOnce = false;
-     
+
     (gwDb as any).transaction = (...args: unknown[]) => {
       if (!failedOnce) {
         failedOnce = true;
         throw new Error("gateway binding write failed");
       }
-       
+
       return (realTransaction as any)(...args);
     };
 
@@ -658,7 +656,6 @@ describe("remote web pairing token exchange", () => {
         ),
       ).rejects.toThrow("gateway binding write failed");
     } finally {
-       
       (gwDb as any).transaction = realTransaction;
     }
 
@@ -703,12 +700,6 @@ describe("remote web pairing token exchange", () => {
       })
       .run();
     bustGuardianIntegrityCache();
-    setGuardianIntegrityReporterOverridesForTesting({
-      fetchImpl: async () => new Response("{}"),
-      mintToken: () => "svc-token",
-      baseUrl: "http://127.0.0.1:7821",
-      log: { error: () => {}, warn: () => {} },
-    });
 
     try {
       const res = await handleRemoteWebPairingToken(
@@ -748,7 +739,6 @@ describe("remote web pairing token exchange", () => {
       expect(retry.status).toBe(200);
       expect(activeTokens()).toHaveLength(1);
     } finally {
-      resetGuardianIntegrityReporterForTesting();
       bustGuardianIntegrityCache();
     }
   });

package/src/__tests__/runtime-client.test.ts

@@ -332,7 +332,7 @@ describe("resolvePublicHttpBaseUrl", () => {
 
   test("prefers the config publicBaseUrl and strips its trailing slash", async () => {
     const result = await resolvePublicHttpBaseUrl(
-      makeConfig({ tunnelBaseUrl: "https://tunnel-dev.mycadet.ai" }),
+      makeConfig({ tunnelBaseUrl: "https://dev-tunnel.mycadet.ai" }),
       fakeConfigFile("https://assistant.example.com/"),
       getId("assistant-123"),
     );
@@ -342,7 +342,7 @@ describe("resolvePublicHttpBaseUrl", () => {
   test("does not read the cloud assistant id when the config URL resolves", async () => {
     const platformIdGetter = getId("assistant-123");
     await resolvePublicHttpBaseUrl(
-      makeConfig({ tunnelBaseUrl: "https://tunnel-dev.mycadet.ai" }),
+      makeConfig({ tunnelBaseUrl: "https://dev-tunnel.mycadet.ai" }),
       fakeConfigFile("https://assistant.example.com"),
       platformIdGetter,
     );
@@ -352,20 +352,20 @@ describe("resolvePublicHttpBaseUrl", () => {
 
   test("falls back to tunnelBaseUrl + platform assistant id when config is empty", async () => {
     const result = await resolvePublicHttpBaseUrl(
-      makeConfig({ tunnelBaseUrl: "https://tunnel-dev.mycadet.ai" }),
+      makeConfig({ tunnelBaseUrl: "https://dev-tunnel.mycadet.ai" }),
       fakeConfigFile(undefined),
       getId("assistant-123"),
     );
-    expect(result).toBe("https://tunnel-dev.mycadet.ai/assistant-123");
+    expect(result).toBe("https://dev-tunnel.mycadet.ai/assistant-123");
   });
 
   test("strips a trailing slash on tunnelBaseUrl before joining the assistant id", async () => {
     const result = await resolvePublicHttpBaseUrl(
-      makeConfig({ tunnelBaseUrl: "https://tunnel-dev.mycadet.ai/" }),
+      makeConfig({ tunnelBaseUrl: "https://dev-tunnel.mycadet.ai/" }),
       fakeConfigFile(undefined),
       getId("assistant-123"),
     );
-    expect(result).toBe("https://tunnel-dev.mycadet.ai/assistant-123");
+    expect(result).toBe("https://dev-tunnel.mycadet.ai/assistant-123");
   });
 
   test("returns undefined when neither the config URL nor the tunnel fallback resolve", async () => {
@@ -375,7 +375,7 @@ describe("resolvePublicHttpBaseUrl", () => {
     // tunnelBaseUrl present but no platform assistant id → no fallback.
     expect(
       await resolvePublicHttpBaseUrl(
-        makeConfig({ tunnelBaseUrl: "https://tunnel-dev.mycadet.ai" }),
+        makeConfig({ tunnelBaseUrl: "https://dev-tunnel.mycadet.ai" }),
         fakeConfigFile(undefined),
         getId(undefined),
       ),

package/src/__tests__/speech-relay-websocket.test.ts

@@ -91,10 +91,10 @@ describe("tunnel origin derivation", () => {
       "https://tunnel.mycadet.ai",
     );
     expect(tunnelOriginForPlatformHost("staging-cloud.mycadet.ai")).toBe(
-      "https://tunnel-staging.mycadet.ai",
+      "https://staging-tunnel.mycadet.ai",
     );
     expect(tunnelOriginForPlatformHost("dev-cloud.mycadet.ai")).toBe(
-      "https://tunnel-dev.mycadet.ai",
+      "https://dev-tunnel.mycadet.ai",
     );
     expect(tunnelOriginForPlatformHost("mycadet.ai")).toBeNull();
     expect(tunnelOriginForPlatformHost("localhost")).toBeNull();
@@ -124,10 +124,10 @@ describe("tunnel origin derivation", () => {
     expect(await handler(req, server)).toBeUndefined();
     const data = upgradedData<SpeechRelaySocketData>(server);
     expect(new URL(data.upstreamWsUrl).origin).toBe(
-      "wss://tunnel-staging.mycadet.ai",
+      "wss://staging-tunnel.mycadet.ai",
     );
     expect(new URL(data.upstreamHttpUrl).origin).toBe(
-      "https://tunnel-staging.mycadet.ai",
+      "https://staging-tunnel.mycadet.ai",
     );
   });
 

package/src/__tests__/trust-verdict-resolver-guardian-integrity.test.ts

@@ -11,36 +11,46 @@
  *  - A thrown integrity check degrades to the plain unknown verdict — no
  *    crash, no stamp.
  *
- * The fail-loud reporter is silenced/observed through its test-only overrides
- * so no relay or log leaves the test process (bun's mock.module is
- * process-global and would leak into other test files).
+ * The fail-loud reporter's report fns are captured via module
+ * re-registration so no log leaves the test process (the reporter's own
+ * behavior has its own suite).
  */
-import { beforeEach, afterEach, describe, expect, test } from "bun:test";
+import { beforeEach, afterEach, describe, expect, mock, test } from "bun:test";
 import { sql } from "drizzle-orm";
 
 await import("./test-preload.js");
-const { initGatewayDb, resetGatewayDb, getGatewayDb } = await import(
-  "../db/connection.js"
-);
+const { initGatewayDb, resetGatewayDb, getGatewayDb } =
+  await import("../db/connection.js");
 const {
   contacts,
   contactChannels,
   actorTokenRecords,
   actorRefreshTokenRecords,
 } = await import("../db/schema.js");
-const { seedActorToken, seedContact } = await import(
-  "./helpers/contact-fixtures.js"
-);
-const {
-  resetGuardianIntegrityReporterForTesting,
-  setGuardianIntegrityReporterOverridesForTesting,
-} = await import("../guardian-integrity-reporter.js");
-const { bustGuardianIntegrityCache } = await import(
-  "../auth/guardian-integrity.js"
-);
-const { resolveTrustVerdict } = await import(
-  "../risk/trust-verdict-resolver.js"
-);
+const { seedActorToken, seedContact } =
+  await import("./helpers/contact-fixtures.js");
+
+// Captured reporter detail payloads (via module re-registration — the SUTs
+// below must load AFTER this so they bind the recorders, not the real
+// reporter).
+const reportCalls: Record<string, unknown>[] = [];
+
+const actualGuardianIntegrityReporter =
+  await import("../guardian-integrity-reporter.js");
+mock.module("../guardian-integrity-reporter.js", () => ({
+  ...actualGuardianIntegrityReporter,
+  reportMissingGuardian: (detail: Record<string, unknown>) => {
+    reportCalls.push(detail);
+  },
+  reportGuardianMintRefused: (detail: Record<string, unknown>) => {
+    reportCalls.push(detail);
+  },
+}));
+
+const { bustGuardianIntegrityCache } =
+  await import("../auth/guardian-integrity.js");
+const { resolveTrustVerdict } =
+  await import("../risk/trust-verdict-resolver.js");
 
 const CHANNEL = "telegram";
 
@@ -72,9 +82,6 @@ function insertChannel(args: {
     .run();
 }
 
-// Captured reporter detail payloads (via the log-override seam).
-const reportCalls: Record<string, unknown>[] = [];
-
 beforeEach(async () => {
   resetGatewayDb();
   await initGatewayDb();
@@ -84,23 +91,10 @@ beforeEach(async () => {
   getGatewayDb().delete(actorRefreshTokenRecords).run();
   bustGuardianIntegrityCache();
   reportCalls.length = 0;
-  resetGuardianIntegrityReporterForTesting();
-  setGuardianIntegrityReporterOverridesForTesting({
-    fetchImpl: async () => new Response("{}"),
-    mintToken: () => "svc-token",
-    baseUrl: "http://127.0.0.1:7821",
-    log: {
-      error: (detail) => {
-        reportCalls.push(detail);
-      },
-      warn: () => {},
-    },
-  });
 });
 
 afterEach(() => {
   resetGatewayDb();
-  resetGuardianIntegrityReporterForTesting();
 });
 
 describe("missing-guardian state (evidence, zero guardian rows)", () => {

package/src/__tests__/twilio-webhooks.test.ts

@@ -831,7 +831,7 @@ describe("Twilio webhook signature with canonical ingress base URL", () => {
     );
 
     const handler = createTwilioVoiceWebhookHandler(
-      makeConfig({ tunnelBaseUrl: "https://tunnel-staging.mycadet.ai" }),
+      makeConfig({ tunnelBaseUrl: "https://staging-tunnel.mycadet.ai" }),
       makeCaches(),
     );
 
@@ -856,7 +856,7 @@ describe("Twilio webhook signature with canonical ingress base URL", () => {
     expect(res.status).toBe(200);
     const body = await res.text();
     expect(body).toContain(
-      `url="wss://tunnel-staging.mycadet.ai/${assistantId}/webhooks/twilio/media-stream/sess-1/`,
+      `url="wss://staging-tunnel.mycadet.ai/${assistantId}/webhooks/twilio/media-stream/sess-1/`,
     );
     expect(body).not.toContain("__CADET_PUBLIC_BASE_URL__");
     expect(body).not.toContain("staging-cloud.mycadet.ai");

package/src/auth/actor-token-revocation.ts

@@ -96,10 +96,30 @@ export function actorTokenRecordHash(rawToken: string): string {
   return hashToken(canonicalizeTokenForHash(rawToken));
 }
 
+/**
+ * The projection of the presented token's row that admission loads — routes
+ * serving the row (e.g. `GET /v1/devices/mine`) read this instead of
+ * re-querying the same token hash.
+ */
+export type AdmittedActorTokenRecord = Pick<
+  typeof actorTokenRecords.$inferSelect,
+  | "status"
+  | "guardianPrincipalId"
+  | "hashedDeviceId"
+  | "platform"
+  | "pairingUserAgent"
+  | "clientReportedName"
+  | "issuedAt"
+  | "expiresAt"
+>;
+
 /**
  * Decide whether a validated token may proceed, and record the activity of the
- * device that presented it. Returns false only for an actor token whose record
- * is explicitly `status = 'revoked'`; every other case is fail-open.
+ * device that presented it. `admitted` is false only for an actor token whose
+ * record is explicitly `status = 'revoked'`; every other case is fail-open. The
+ * row loaded for the verdict rides back as `record` (null for non-actor
+ * principals, unrecorded tokens, and DB-error fail-open) so callers — routes
+ * especially — can reuse it instead of re-querying by the same token hash.
  *
  * One canonicalize + hash + indexed SELECT serves both jobs, and the two are
  * inseparable by construction: a caller cannot enforce revocation while
@@ -122,10 +142,10 @@ export function actorTokenRecordHash(rawToken: string): string {
 export function admitActorToken(
   rawToken: string,
   claims: TokenClaims,
-): boolean {
+): { admitted: boolean; record: AdmittedActorTokenRecord | null } {
   const parsed = parseSub(claims.sub);
   if (!parsed.ok || parsed.principalType !== "actor") {
-    return true;
+    return { admitted: true, record: null };
   }
 
   const tokenHash = actorTokenRecordHash(rawToken);
@@ -137,6 +157,11 @@ export function admitActorToken(
         status: actorTokenRecords.status,
         guardianPrincipalId: actorTokenRecords.guardianPrincipalId,
         hashedDeviceId: actorTokenRecords.hashedDeviceId,
+        platform: actorTokenRecords.platform,
+        pairingUserAgent: actorTokenRecords.pairingUserAgent,
+        clientReportedName: actorTokenRecords.clientReportedName,
+        issuedAt: actorTokenRecords.issuedAt,
+        expiresAt: actorTokenRecords.expiresAt,
       })
       .from(actorTokenRecords)
       .where(eq(actorTokenRecords.tokenHash, tokenHash))
@@ -144,17 +169,17 @@ export function admitActorToken(
 
     // Verdict first: a rejected token must never stamp.
     if (record?.status === "revoked") {
-      return false;
+      return { admitted: false, record };
     }
 
     if (stampDebounce.has(tokenHash)) {
-      return true;
+      return { admitted: true, record: record ?? null };
     }
 
     if (!record) {
       // A stable answer, not a failure: arm the window like a completed stamp.
       stampDebounce.mark(tokenHash);
-      return true;
+      return { admitted: true, record: null };
     }
 
     db.update(actorTokenRecords)
@@ -169,13 +194,13 @@ export function admitActorToken(
       .run();
 
     stampDebounce.mark(tokenHash);
-    return true;
+    return { admitted: true, record };
   } catch (err) {
     log.warn(
       { err: err instanceof Error ? err.message : String(err) },
       "Actor-token admission failed, allowing request (fail-open)",
     );
-    return true;
+    return { admitted: true, record: null };
   }
 }
 

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

@@ -16,6 +16,7 @@ const { parsePairingArgs, runPairingCommand } = await import("../pairing.js");
 const {
   getRemoteWebPairingChallengeForTests,
   resetRemoteWebPairingChallengesForTests,
+  setRemoteWebPairingChallengeNowForTests,
 } = await import("../../remote-web/pairing-challenge-store.js");
 const { resetRemoteWebPairingChallengeRateLimiterForTests } =
   await import("../../remote-web/pairing-challenge-rate-limit-store.js");
@@ -129,3 +130,97 @@ describe("parsePairingArgs", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// `gateway pairing list`
+// ---------------------------------------------------------------------------
+
+const ListChallengeSchema = z.object({
+  id: z.string(),
+  userCode: z.string(),
+  publicBaseUrl: z.string(),
+  verificationUri: z.string(),
+  status: z.enum(["pending", "approved", "exchanging", "consumed"]),
+  createdAtMs: z.number(),
+  expiresAtMs: z.number(),
+  requesterIp: z.string(),
+  requesterUserAgent: z.string().nullable(),
+  viaEdgeProxy: z.boolean(),
+  expired: z.boolean(),
+});
+
+function lastLoggedChallenges() {
+  const line = logs[logs.length - 1];
+  expect(line).toBeTruthy();
+  const parsed = z
+    .object({ ok: z.literal(true), challenges: z.array(ListChallengeSchema) })
+    .parse(JSON.parse(line!));
+  return parsed.challenges;
+}
+
+describe("gateway pairing list", () => {
+  test("empty store prints a no-results line and exits 0", async () => {
+    const code = await runPairingCommand(["list"]);
+
+    expect(code).toBe(0);
+    expect(logs.join("\n")).toContain("No pairing challenges found.");
+  });
+
+  test("--json lists every persisted challenge newest-first", async () => {
+    // Both mints land inside the last minute so their 10-minute TTL keeps
+    // them active against the real wall clock the CLI checks with, while
+    // the frozen seam still pins deterministic createdAtMs values.
+    const older = Date.now() - 60_000;
+    const newer = Date.now() - 30_000;
+    setRemoteWebPairingChallengeNowForTests(() => older);
+    await runPairingCommand(["mint", "https://older.example.com"]);
+    setRemoteWebPairingChallengeNowForTests(() => newer);
+    await runPairingCommand(["mint", "https://newer.example.com"]);
+    setRemoteWebPairingChallengeNowForTests(() => Date.now());
+
+    const code = await runPairingCommand(["list", "--json"]);
+    expect(code).toBe(0);
+
+    const challenges = lastLoggedChallenges();
+    expect(challenges).toHaveLength(2);
+    expect(challenges[0]!.publicBaseUrl).toBe("https://newer.example.com");
+    expect(challenges[1]!.publicBaseUrl).toBe("https://older.example.com");
+    expect(challenges[1]!.createdAtMs).toBe(older);
+    expect(challenges[1]!.status).toBe("approved");
+    expect(challenges[1]!.expired).toBe(false);
+    expect(challenges[1]!.requesterIp).toBe("cli");
+    expect(challenges[1]!.userCode).toMatch(/^[A-Z2-9]{4}-[A-Z2-9]{4}$/);
+  });
+
+  test("expired challenges still list, flagged expired", async () => {
+    // Mint at a frozen time an hour ago: the challenge's persisted expiry
+    // (mint + 10-minute TTL) is then in the past of the real wall clock the
+    // CLI checks against, without the store's own expiry paths deleting it.
+    setRemoteWebPairingChallengeNowForTests(() => Date.now() - 3_600_000);
+    await runPairingCommand(["mint", "https://stale.example.com"]);
+    setRemoteWebPairingChallengeNowForTests(() => Date.now());
+
+    const code = await runPairingCommand(["list", "--json"]);
+    expect(code).toBe(0);
+
+    const challenges = lastLoggedChallenges();
+    expect(challenges).toHaveLength(1);
+    expect(challenges[0]!.expired).toBe(true);
+    expect(challenges[0]!.status).toBe("approved");
+    expect(challenges[0]!.publicBaseUrl).toBe("https://stale.example.com");
+  });
+
+  test("human output shows user code, status, liveness, and timestamps", async () => {
+    await runPairingCommand(["mint", "https://shown.example.com"]);
+
+    const code = await runPairingCommand(["list"]);
+    expect(code).toBe(0);
+
+    const output = logs.join("\n");
+    expect(output).toContain("approved");
+    expect(output).toContain("active");
+    expect(output).toContain("minted ");
+    expect(output).toContain("expires ");
+    expect(output).toContain("https://shown.example.com/assistant/pair");
+  });
+});

package/src/cli/index.ts

@@ -20,7 +20,7 @@ function printUsage(): void {
     "  contacts    Manage the contact ACL with list, get, set-risk-threshold",
   );
   console.log(
-    "  pairing     Mint/approve a remote-web pairing challenge (mint <url>)",
+    "  pairing     Remote-web pairing challenges (mint <url> | list [--json])",
   );
 }