codex-relay 1.0.4 → 1.0.5

package/README.md

@@ -16,7 +16,7 @@ Run the server from the workspace you want Codex to use:
 npx codex-relay@latest
 ```
 
-The CLI prints a QR code, a mobile URL, and a `codex-relay://pair...` pairing payload. Scan the QR code from the mobile app. If scanning is not available, paste the full pairing payload into the app.
+The CLI prints a QR code, a mobile URL, and a `codex-relay://pair...` pairing payload. Scan the QR code from the mobile app. If the relay detects multiple possible network addresses, the QR includes them and the app automatically uses the first address it can reach. If scanning is not available, paste the full pairing payload into the app.
 
 When the app shows an approval code, approve it on the computer:
 
@@ -117,10 +117,11 @@ CODEX_RELAY_WORKSPACE_PATH=/path/to/project npx codex-relay@latest
 
 ## Network Notes
 
-The phone must be able to reach the URL printed as `Mobile:` by the relay.
+The phone must be able to reach one of the URLs printed by the relay.
 
 - On the same Wi-Fi network, the relay usually prints a local network address.
 - On Tailscale, the relay prefers your Tailscale address when it can detect one.
+- If several Wi-Fi, VPN, or virtual network addresses are available, the QR includes all detected candidates and the app tries them automatically.
 - If the printed URL is not reachable from the phone, set `CODEX_RELAY_PUBLIC_URL` to a reachable HTTP URL.
 
 ## Troubleshooting

package/dist/api-schema2.js

@@ -640,6 +640,7 @@ const apiPaths = {
 	pair: "/v1/pair",
 	pairApproval: (approvalCode) => `/v1/pair/${encodeURIComponent(approvalCode)}`,
 	pairApprove: "/v1/pair/approve",
+	sessionsClear: "/v1/sessions/clear",
 	sessionRefresh: "/v1/session/refresh",
 	status: "/v1/status",
 	preferences: "/v1/preferences",

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { Dt as apiPaths } from "./api-schema2.js";
-import { n as codexRelayHome, r as legacyCodexRelayDataPath, t as codexRelayDataPath } from "./paths.js";
+import { n as codexRelayHome, o as getConnectUrlGuidance, r as legacyCodexRelayDataPath, s as createTursoPairingSessionStore, t as codexRelayDataPath } from "./paths.js";
 import { Command } from "@commander-js/extra-typings";
 import qrcode from "qrcode-terminal";
 import { spawn } from "node:child_process";
 import { closeSync, openSync } from "node:fs";
-import { mkdir, readFile, unlink } from "node:fs/promises";
+import { access, mkdir, readFile, rm, unlink } from "node:fs/promises";
 import { dirname } from "node:path";
 import { setTimeout } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
@@ -17,6 +17,7 @@ Examples:
   ${npxCommand}              Start the relay and print a pairing QR
   ${npxCommand} --bg         Start the relay in the background
   ${npxCommand} qr           Print the current pairing QR
+  ${npxCommand} clear        Sign out every paired mobile app
   ${npxCommand} approve CODE Approve a pending mobile pairing request`).action(async (options) => {
 	if (options.debug) process.env.CODEX_RELAY_DEBUG = "1";
 	if (options.dangerouslyAutoApprove) process.env.CODEX_RELAY_DANGEROUSLY_AUTO_APPROVE = "1";
@@ -32,6 +33,9 @@ program.command("qr").description("Print the current pairing QR for an already r
 program.command("approve").description("Approve a pending mobile pairing request.").argument("<approval-code>", "approval code shown in the mobile app").action(async (approvalCode) => {
 	await approvePairing(approvalCode);
 });
+program.command("clear").description("Sign out every paired mobile app.").option("--debug", "also delete debug.log").action(async (options, command) => {
+	await clearPairings({ clearDebugLog: Boolean(options.debug || command.optsWithGlobals().debug) });
+});
 await program.parseAsync();
 async function startBackgroundServer() {
 	const logPath = codexRelayDataPath("server.log");
@@ -135,6 +139,74 @@ async function approvePairing(rawCode) {
 	}
 	console.log("Approved Codex Relay pairing request.");
 }
+async function clearPairings(options) {
+	const result = await clearPairingsViaServer().catch(async (error) => {
+		if (await hasRunningBackgroundServer()) throw error;
+		return clearPairingsFromLocalStore();
+	});
+	const removedDebugLogs = options.clearDebugLog ? await clearDebugLogs() : [];
+	console.log(`Signed out ${result.sessionsCleared} paired mobile app${result.sessionsCleared === 1 ? "" : "s"}.`);
+	if (result.pendingPairingsCleared > 0) console.log(`Removed ${result.pendingPairingsCleared} pending pairing request${result.pendingPairingsCleared === 1 ? "" : "s"}.`);
+	if (options.clearDebugLog) console.log(removedDebugLogs.length > 0 ? `Deleted debug logs: ${removedDebugLogs.join(", ")}` : "No debug logs found.");
+}
+async function clearPairingsViaServer() {
+	const endpoint = await getApprovalEndpoint();
+	const secret = await readApprovalSecret();
+	const response = await fetch(`${endpoint}${apiPaths.sessionsClear}`, {
+		method: "POST",
+		headers: {
+			accept: "application/json",
+			"x-codex-relay-approve-secret": secret
+		}
+	});
+	const payload = await response.json().catch(() => void 0);
+	if (!response.ok) {
+		const message = payload && typeof payload === "object" && "error" in payload && payload.error && typeof payload.error === "object" && "message" in payload.error ? String(payload.error.message) : `Codex Relay server returned ${response.status}`;
+		throw new Error(message);
+	}
+	return parseClearPairingResult(payload);
+}
+async function clearPairingsFromLocalStore() {
+	const dbPath = await resolveAuthDbPath();
+	if (!dbPath) return {
+		pendingPairingsCleared: 0,
+		sessionsCleared: 0
+	};
+	return (await createTursoPairingSessionStore(dbPath)).clearAll();
+}
+async function resolveAuthDbPath() {
+	if (process.env.CODEX_RELAY_AUTH_DB_PATH) return process.env.CODEX_RELAY_AUTH_DB_PATH;
+	const primary = codexRelayDataPath("auth.db");
+	if (await pathExists(primary)) return primary;
+	const legacy = legacyCodexRelayDataPath("auth.db");
+	if (await pathExists(legacy)) return legacy;
+}
+async function clearDebugLogs() {
+	const paths = [...new Set([codexRelayDataPath("debug.log"), legacyCodexRelayDataPath("debug.log")])];
+	const removed = [];
+	for (const path of paths) {
+		if (!await pathExists(path)) continue;
+		await rm(path, { force: true });
+		removed.push(path);
+	}
+	return removed;
+}
+async function hasRunningBackgroundServer() {
+	return Boolean(await readRunningPid(codexRelayDataPath("server.pid")));
+}
+async function pathExists(path) {
+	return access(path).then(() => true, () => false);
+}
+function parseClearPairingResult(payload) {
+	if (!payload || typeof payload !== "object") return {
+		pendingPairingsCleared: 0,
+		sessionsCleared: 0
+	};
+	return {
+		pendingPairingsCleared: "pendingPairingsCleared" in payload ? Number(payload.pendingPairingsCleared) || 0 : 0,
+		sessionsCleared: "sessionsCleared" in payload ? Number(payload.sessionsCleared) || 0 : 0
+	};
+}
 async function printPairingQr() {
 	const storedState = await readServerState();
 	const state = storedState?.pairingPayload ? storedState : await readServerLogState();
@@ -148,7 +220,15 @@ async function printPairingQr() {
 	console.log("");
 	qrcode.generate(state.pairingPayload, { small: true });
 	console.log("");
-	if (state.connectUrl) console.log(`Mobile: ${state.connectUrl}`);
+	if (state.connectUrl) {
+		console.log(`Mobile: ${state.connectUrl}`);
+		const guidance = getConnectUrlGuidance(state.connectUrl);
+		if (guidance) console.log(`Network: ${guidance}`);
+	}
+	if (state.connectUrlCandidates && state.connectUrlCandidates.length > 1) {
+		console.log(`Candidate addresses: ${state.connectUrlCandidates.length}`);
+		for (const candidate of state.connectUrlCandidates.slice(1)) console.log(`  ${candidate.label}: ${candidate.url}`);
+	}
 	if (state.listenUrl) console.log(`Server: ${state.listenUrl}`);
 	console.log("");
 	console.log(`Pairing: ${state.pairingPayload}`);
@@ -206,6 +286,7 @@ async function readServerState() {
 	if (!state) return;
 	return {
 		connectUrl: typeof state.connectUrl === "string" ? state.connectUrl : void 0,
+		connectUrlCandidates: parseConnectUrlCandidates(state.connectUrlCandidates),
 		host: typeof state.host === "string" ? state.host : void 0,
 		listenUrl: typeof state.listenUrl === "string" ? state.listenUrl : void 0,
 		pairingPayload: typeof state.pairingPayload === "string" ? state.pairingPayload : void 0,
@@ -235,6 +316,18 @@ function lastLogValue(log, label) {
 	for (const match of log.matchAll(pattern)) value = match[1];
 	return value;
 }
+function parseConnectUrlCandidates(value) {
+	if (!Array.isArray(value)) return;
+	return value.map((candidate) => {
+		if (!candidate || typeof candidate !== "object") return;
+		const label = "label" in candidate ? candidate.label : void 0;
+		const url = "url" in candidate ? candidate.url : void 0;
+		return typeof label === "string" && typeof url === "string" ? {
+			label,
+			url
+		} : void 0;
+	}).filter((candidate) => Boolean(candidate));
+}
 function isDatabaseLockError(error) {
 	const message = error instanceof Error ? error.message : String(error);
 	return message.includes("failed to open database") && message.includes("Locking error");

package/dist/paths.js

@@ -1,5 +1,427 @@
-import { join, resolve } from "node:path";
-import { homedir, platform } from "node:os";
+import { execFileSync } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { connect } from "@tursodatabase/database";
+import { fromByteArray, toByteArray } from "base64-js";
+import { homedir, networkInterfaces, platform } from "node:os";
+//#region src/pairing-store.ts
+async function createTursoPairingSessionStore(path) {
+	if (path !== ":memory:") await mkdir(dirname(path), { recursive: true });
+	const db = await connect(path);
+	await db.exec(`
+    CREATE TABLE IF NOT EXISTS pairing_sessions (
+      token_hash TEXT PRIMARY KEY,
+      client_session_id TEXT,
+      client_name TEXT,
+      expires_at INTEGER NOT NULL,
+      key_epoch INTEGER,
+      mobile_to_server_key TEXT,
+      server_to_mobile_key TEXT,
+      last_mobile_counter INTEGER,
+      next_server_counter INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS pending_pairings (
+      approval_code TEXT PRIMARY KEY,
+      client_session_id TEXT,
+      client_name TEXT,
+      client_ephemeral_public_key TEXT NOT NULL,
+      client_nonce TEXT NOT NULL,
+      server_url TEXT NOT NULL,
+      approved INTEGER NOT NULL DEFAULT 0,
+      expires_at INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+  `);
+	await ensurePairingSessionColumns();
+	async function countActive(now) {
+		const row = await db.prepare("SELECT COUNT(DISTINCT COALESCE(client_session_id, token_hash)) AS count FROM pairing_sessions WHERE expires_at > ?").get(now);
+		return Number(row?.count ?? 0);
+	}
+	async function deleteSession(tokenHash) {
+		await db.prepare("DELETE FROM pairing_sessions WHERE token_hash = ?").run(tokenHash);
+	}
+	async function deletePendingPairing(approvalCode) {
+		await db.prepare("DELETE FROM pending_pairings WHERE approval_code = ?").run(approvalCode);
+	}
+	async function getPendingPairing(approvalCode, now) {
+		const row = await db.prepare(`SELECT approval_code AS approvalCode,
+                client_session_id AS clientSessionId,
+                client_name AS clientName,
+                client_ephemeral_public_key AS clientEphemeralPublicKey,
+                client_nonce AS clientNonce,
+                server_url AS serverUrl,
+                approved,
+                expires_at AS expiresAt
+         FROM pending_pairings
+         WHERE approval_code = ?`).get(approvalCode);
+		if (!row) return;
+		const expiresAt = Number(row.expiresAt);
+		if (now > expiresAt) {
+			await deletePendingPairing(approvalCode);
+			return;
+		}
+		return {
+			approvalCode: String(row.approvalCode),
+			approved: Number(row.approved) === 1,
+			clientEphemeralPublicKey: String(row.clientEphemeralPublicKey),
+			clientSessionId: typeof row.clientSessionId === "string" ? row.clientSessionId : void 0,
+			clientName: typeof row.clientName === "string" ? row.clientName : void 0,
+			clientNonce: String(row.clientNonce),
+			expiresAt,
+			serverUrl: String(row.serverUrl)
+		};
+	}
+	return {
+		async approvePendingPairing(approvalCode, now) {
+			const pending = await getPendingPairing(approvalCode, now);
+			if (!pending) return;
+			await db.prepare("UPDATE pending_pairings SET approved = 1, updated_at = ? WHERE approval_code = ?").run(now, approvalCode);
+			return {
+				...pending,
+				approved: true
+			};
+		},
+		async clearAll() {
+			return await db.transaction(async () => {
+				const sessionRow = await db.prepare("SELECT COUNT(*) AS count FROM pairing_sessions").get();
+				const pendingRow = await db.prepare("SELECT COUNT(*) AS count FROM pending_pairings").get();
+				await db.prepare("DELETE FROM pairing_sessions").run();
+				await db.prepare("DELETE FROM pending_pairings").run();
+				return {
+					pendingPairingsCleared: Number(pendingRow?.count ?? 0),
+					sessionsCleared: Number(sessionRow?.count ?? 0)
+				};
+			})();
+		},
+		countActive,
+		async createPendingPairing(pairing) {
+			const now = Date.now();
+			await db.prepare(`INSERT INTO pending_pairings (
+             approval_code,
+             client_session_id,
+             client_name,
+             client_ephemeral_public_key,
+             client_nonce,
+             server_url,
+             approved,
+             expires_at,
+             created_at,
+             updated_at
+           )
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(pairing.approvalCode, pairing.clientSessionId ?? null, pairing.clientName ?? null, pairing.clientEphemeralPublicKey, pairing.clientNonce, pairing.serverUrl, pairing.approved ? 1 : 0, pairing.expiresAt, now, now);
+		},
+		async createSession(tokenHash, session) {
+			const now = Date.now();
+			const secure = encodeSecureSession(session.secureSession);
+			if (session.clientSessionId) {
+				await db.prepare("DELETE FROM pairing_sessions WHERE client_session_id = ?").run(session.clientSessionId);
+				if (session.clientName) await db.prepare("DELETE FROM pairing_sessions WHERE client_session_id IS NULL AND client_name = ?").run(session.clientName);
+			}
+			await db.prepare(`INSERT INTO pairing_sessions (
+             token_hash,
+             client_session_id,
+             client_name,
+             expires_at,
+             key_epoch,
+             mobile_to_server_key,
+             server_to_mobile_key,
+             last_mobile_counter,
+             next_server_counter,
+             created_at,
+             updated_at
+           )
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(tokenHash, session.clientSessionId ?? null, session.clientName ?? null, session.expiresAt, secure?.keyEpoch ?? null, secure?.mobileToServerKey ?? null, secure?.serverToMobileKey ?? null, secure?.lastMobileCounter ?? null, secure?.nextServerCounter ?? null, now, now);
+			return countActive(now);
+		},
+		deleteSession,
+		deletePendingPairing,
+		getPendingPairing,
+		async getValidSession(tokenHash, now) {
+			const row = await db.prepare(`SELECT client_name AS clientName,
+                  client_session_id AS clientSessionId,
+                  expires_at AS expiresAt,
+                  key_epoch AS keyEpoch,
+                  mobile_to_server_key AS mobileToServerKey,
+                  server_to_mobile_key AS serverToMobileKey,
+                  last_mobile_counter AS lastMobileCounter,
+                  next_server_counter AS nextServerCounter
+           FROM pairing_sessions
+           WHERE token_hash = ?`).get(tokenHash);
+			if (!row) return;
+			const expiresAt = Number(row.expiresAt);
+			if (now > expiresAt) {
+				await deleteSession(tokenHash);
+				return;
+			}
+			return {
+				clientSessionId: typeof row.clientSessionId === "string" ? row.clientSessionId : void 0,
+				clientName: typeof row.clientName === "string" ? row.clientName : void 0,
+				expiresAt,
+				secureSession: decodeSecureSession(row)
+			};
+		},
+		async pruneExpired(now) {
+			await db.prepare("DELETE FROM pairing_sessions WHERE expires_at <= ?").run(now);
+			await db.prepare("DELETE FROM pending_pairings WHERE expires_at <= ?").run(now);
+		},
+		async rotateSession(oldTokenHash, newTokenHash, session) {
+			const now = Date.now();
+			const secure = encodeSecureSession(session.secureSession);
+			await db.transaction(async () => {
+				await db.prepare("DELETE FROM pairing_sessions WHERE token_hash = ?").run(oldTokenHash);
+				if (session.clientSessionId) {
+					await db.prepare("DELETE FROM pairing_sessions WHERE client_session_id = ?").run(session.clientSessionId);
+					if (session.clientName) await db.prepare("DELETE FROM pairing_sessions WHERE client_session_id IS NULL AND client_name = ?").run(session.clientName);
+				}
+				await db.prepare(`INSERT INTO pairing_sessions (
+               token_hash,
+               client_session_id,
+               client_name,
+               expires_at,
+               key_epoch,
+               mobile_to_server_key,
+               server_to_mobile_key,
+               last_mobile_counter,
+               next_server_counter,
+               created_at,
+               updated_at
+             )
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(newTokenHash, session.clientSessionId ?? null, session.clientName ?? null, session.expiresAt, secure?.keyEpoch ?? null, secure?.mobileToServerKey ?? null, secure?.serverToMobileKey ?? null, secure?.lastMobileCounter ?? null, secure?.nextServerCounter ?? null, now, now);
+			})();
+			return countActive(now);
+		},
+		async updateSecureSession(tokenHash, secureSession) {
+			const secure = encodeSecureSession(secureSession);
+			const now = Date.now();
+			await db.prepare(`UPDATE pairing_sessions
+           SET key_epoch = ?,
+               mobile_to_server_key = ?,
+               server_to_mobile_key = ?,
+               last_mobile_counter = ?,
+               next_server_counter = ?,
+               updated_at = ?
+           WHERE token_hash = ?`).run(secure.keyEpoch, secure.mobileToServerKey, secure.serverToMobileKey, secure.lastMobileCounter, secure.nextServerCounter, now, tokenHash);
+		}
+	};
+	async function ensurePairingSessionColumns() {
+		const rows = await db.prepare("PRAGMA table_info(pairing_sessions)").all();
+		const columns = new Set(resultRows(rows).map((row) => String(row.name)));
+		for (const [column, sql] of [
+			["client_session_id", "ALTER TABLE pairing_sessions ADD COLUMN client_session_id TEXT"],
+			["key_epoch", "ALTER TABLE pairing_sessions ADD COLUMN key_epoch INTEGER"],
+			["mobile_to_server_key", "ALTER TABLE pairing_sessions ADD COLUMN mobile_to_server_key TEXT"],
+			["server_to_mobile_key", "ALTER TABLE pairing_sessions ADD COLUMN server_to_mobile_key TEXT"],
+			["last_mobile_counter", "ALTER TABLE pairing_sessions ADD COLUMN last_mobile_counter INTEGER"],
+			["next_server_counter", "ALTER TABLE pairing_sessions ADD COLUMN next_server_counter INTEGER"]
+		]) if (!columns.has(column)) await db.exec(sql);
+		const pendingRows = await db.prepare("PRAGMA table_info(pending_pairings)").all();
+		if (!new Set(resultRows(pendingRows).map((row) => String(row.name))).has("client_session_id")) await db.exec("ALTER TABLE pending_pairings ADD COLUMN client_session_id TEXT");
+	}
+}
+function encodeSecureSession(session) {
+	if (!session) return;
+	return {
+		keyEpoch: session.keyEpoch,
+		lastMobileCounter: session.lastMobileCounter,
+		mobileToServerKey: fromByteArray(session.mobileToServerKey),
+		nextServerCounter: session.nextServerCounter,
+		serverToMobileKey: fromByteArray(session.serverToMobileKey)
+	};
+}
+function decodeSecureSession(row) {
+	if (typeof row.mobileToServerKey !== "string" || typeof row.serverToMobileKey !== "string" || row.keyEpoch === null || row.lastMobileCounter === null || row.nextServerCounter === null) return;
+	return {
+		keyEpoch: Number(row.keyEpoch),
+		lastMobileCounter: Number(row.lastMobileCounter),
+		mobileToServerKey: toByteArray(row.mobileToServerKey),
+		nextServerCounter: Number(row.nextServerCounter),
+		serverToMobileKey: toByteArray(row.serverToMobileKey)
+	};
+}
+function resultRows(result) {
+	if (Array.isArray(result)) return result;
+	if (result && typeof result === "object" && Array.isArray(result.rows)) return result.rows;
+	return [];
+}
+//#endregion
+//#region src/pairing-url-candidates.ts
+function getConnectUrlGuidance(url) {
+	const host = parseUrlHost(url);
+	if (!host) return;
+	if (isLocalhost(host) || isUnspecifiedHost(host)) return "This address is only reachable from this computer. Use a same-Wi-Fi address, Tailscale, or CODEX_RELAY_PUBLIC_URL for mobile pairing.";
+	if (isTailscaleHost(host)) return "Using Tailscale. Keep Tailscale connected on both this computer and the phone.";
+	if (isPrivateIPv4Host(host) || isLocalIPv6Host(host)) return "Using a local Wi-Fi/LAN address. Keep the phone and computer on the same network; if pairing is flaky, try Tailscale.";
+	return "Using a configured or public address. Make sure the phone can reach it before pairing.";
+}
+function createPairingQrPayload(details) {
+	const primaryServerUrl = details.serverUrls[0];
+	if (!primaryServerUrl) throw new Error("Pairing QR requires at least one server URL.");
+	const url = new URL("codex-relay://pair");
+	url.searchParams.set("serverUrl", primaryServerUrl);
+	url.searchParams.set("serverPublicKey", details.serverPublicKey);
+	const hosts = compactCandidateHosts(primaryServerUrl, details.serverUrls);
+	if (hosts.length > 0) url.searchParams.set("h", hosts.join(","));
+	return url.toString();
+}
+function getConnectUrlCandidates(details) {
+	return dedupeCandidates([
+		...configuredConnectUrlCandidates(),
+		...tailscaleConnectUrlCandidates(details.port),
+		...localNetworkConnectUrlCandidates(details.port),
+		{
+			label: "Server",
+			url: details.listenUrl
+		}
+	]);
+}
+function normalizeUrl(value) {
+	if (!value) return;
+	const trimmed = value.trim().replace(/\/$/, "");
+	if (!trimmed) return;
+	try {
+		const url = new URL(trimmed);
+		return url.protocol === "http:" || url.protocol === "https:" ? url.toString().replace(/\/$/, "") : void 0;
+	} catch {
+		return;
+	}
+}
+function configuredConnectUrlCandidates() {
+	const configuredUrl = normalizeUrl(process.env.CODEX_RELAY_PUBLIC_URL);
+	return configuredUrl ? [{
+		label: "Configured",
+		url: configuredUrl
+	}] : [];
+}
+function tailscaleConnectUrlCandidates(port) {
+	const status = getTailscaleStatus();
+	const candidates = [];
+	for (const ip of status?.Self?.TailscaleIPs ?? []) if (ip.startsWith("100.") && ip.includes(".")) candidates.push({
+		label: "Tailscale",
+		url: `http://${ip}:${port}`
+	});
+	const dnsName = status?.Self?.DNSName?.replace(/\.$/, "");
+	if (dnsName) {
+		const servedUrl = getTailscaleServeHttpsUrl(dnsName, port);
+		candidates.push({
+			label: servedUrl ? "Tailscale Serve" : "Tailscale DNS",
+			url: servedUrl ?? `http://${dnsName}:${port}`
+		});
+	}
+	for (const ip of status?.Self?.TailscaleIPs ?? []) if (ip.includes(".")) candidates.push({
+		label: "Tailscale",
+		url: `http://${ip}:${port}`
+	});
+	return candidates;
+}
+function localNetworkConnectUrlCandidates(port) {
+	const candidates = [];
+	for (const [name, addresses] of Object.entries(networkInterfaces())) for (const address of addresses ?? []) if (address.family === "IPv4" && !address.internal) candidates.push({
+		label: name,
+		url: `http://${address.address}:${port}`
+	});
+	return candidates;
+}
+function dedupeCandidates(candidates) {
+	const deduped = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const url = normalizeUrl(candidate.url);
+		if (url && !deduped.has(url)) deduped.set(url, {
+			...candidate,
+			url
+		});
+	}
+	return [...deduped.values()];
+}
+function compactCandidateHosts(primaryServerUrl, serverUrls) {
+	const primary = parseUrl(primaryServerUrl);
+	if (!primary) return [];
+	const hosts = [];
+	for (const serverUrl of serverUrls.slice(1)) {
+		const candidate = parseUrl(serverUrl);
+		if (candidate && candidate.protocol === primary.protocol && candidate.port === primary.port && !hosts.includes(candidate.hostname)) hosts.push(candidate.hostname);
+	}
+	return hosts;
+}
+function parseUrl(url) {
+	try {
+		return new URL(url);
+	} catch {
+		return;
+	}
+}
+function parseUrlHost(url) {
+	try {
+		return new URL(url).hostname.toLowerCase();
+	} catch {
+		return;
+	}
+}
+function isLocalhost(host) {
+	return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+function isUnspecifiedHost(host) {
+	return host === "0.0.0.0" || host === "::";
+}
+function isTailscaleHost(host) {
+	return host.endsWith(".ts.net") || host.endsWith(".beta.tailscale.net") || isTailscaleIPv4Host(host);
+}
+function isPrivateIPv4Host(host) {
+	const octets = host.split(".").map(Number);
+	if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet))) return false;
+	return octets[0] === 10 || octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31 || octets[0] === 192 && octets[1] === 168 || octets[0] === 169 && octets[1] === 254;
+}
+function isTailscaleIPv4Host(host) {
+	const octets = host.split(".").map(Number);
+	return octets.length === 4 && octets[0] === 100 && octets[1] >= 64 && octets[1] <= 127;
+}
+function isLocalIPv6Host(host) {
+	const normalized = host.replace(/^\[/, "").replace(/\]$/, "");
+	return normalized.startsWith("fe80:") || normalized.startsWith("fc") || normalized.startsWith("fd");
+}
+function getTailscaleStatus() {
+	try {
+		const output = execFileSync("tailscale", ["status", "--json"], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			timeout: 1500
+		});
+		return JSON.parse(output);
+	} catch {
+		return;
+	}
+}
+function getTailscaleServeHttpsUrl(dnsName, port) {
+	try {
+		const output = execFileSync("tailscale", [
+			"serve",
+			"status",
+			"--json"
+		], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			timeout: 1500
+		});
+		const serveStatus = JSON.parse(output);
+		const portKey = String(port);
+		const hostPort = `${dnsName}:${portKey}`;
+		return serveStatus.TCP?.[portKey]?.HTTPS && serveStatus.Web?.[hostPort] ? `https://${hostPort}` : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
 //#region src/paths.ts
 const appDataDirectoryName = "codex-relay";
 function codexRelayHome() {
@@ -22,4 +444,4 @@ function defaultCodexRelayHome() {
 	}
 }
 //#endregion
-export { codexRelayHome as n, legacyCodexRelayDataPath as r, codexRelayDataPath as t };
+export { getConnectUrlCandidates as a, createPairingQrPayload as i, codexRelayHome as n, getConnectUrlGuidance as o, legacyCodexRelayDataPath as r, createTursoPairingSessionStore as s, codexRelayDataPath as t };

package/dist/src.js

@@ -1,16 +1,16 @@
 import { A as PairResponseSchema, C as ListQueuedThreadInputsResponseSchema, D as ListWorkspaceFilesResponseSchema, Dt as apiPaths, E as ListWorkspaceDirectoriesResponseSchema, G as ResolveApprovalRequestSchema, K as ResolveApprovalResponseSchema, Lt as stripPromptSkillMentions, Mt as promptMarkdownWithSkills, Ot as chatMessageDetailsFromPromptContext, Q as RuntimePreferencesSchema, S as ListModelsResponseSchema, St as WorkspaceGitActionResponseSchema, T as ListThreadsResponseSchema, U as RateLimitsResponseSchema, X as RuntimePreferencesByWorkspacePathSchema, Z as RuntimePreferencesResponseSchema, _ as EncryptedPayloadSchema, a as ArchiveThreadResponseSchema, at as ThreadContextWindowResponseSchema, b as InterruptThreadRunResponseSchema, bt as WorkspaceFileContentResponseSchema, ct as ThreadMessageDetailResponseSchema, d as CheckoutWorkspaceBranchRequestSchema, dt as ThreadSummarySchema, et as StatusResponseSchema, ft as UpdateRuntimePreferencesRequestSchema, h as CreateThreadRequestSchema, jt as normalizePromptContext, k as PairRequestSchema, kt as createOpenApiDocument, l as ChatMessageSchema, m as ContextWindowUsageSchema, mt as VersionResponseSchema, nt as StreamThreadRunRequestSchema, ot as ThreadDetailResponseSchema, p as CommitPushWorkspaceRequestSchema, pt as UpdateWorkspaceFileContentRequestSchema, q as RunThreadRequestSchema, rt as SubmitThreadInputResponseSchema, st as ThreadMessageDetailFieldSchema, tt as StreamThreadRunEventSchema, vt as WorkspaceChangesResponseSchema, w as ListSkillsResponseSchema, y as ImageAttachmentUploadResponseSchema, z as QueuedThreadInputActionResponseSchema } from "./api-schema2.js";
-import { r as legacyCodexRelayDataPath, t as codexRelayDataPath } from "./paths.js";
+import { a as getConnectUrlCandidates, i as createPairingQrPayload, o as getConnectUrlGuidance, r as legacyCodexRelayDataPath, s as createTursoPairingSessionStore, t as codexRelayDataPath } from "./paths.js";
 import { createRequire } from "node:module";
 import qrcode from "qrcode-terminal";
-import { execFile, execFileSync, spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import fs, { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { access, appendFile, copyFile, mkdir, open, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import path, { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
-import os, { homedir, hostname, networkInterfaces } from "node:os";
-import { serve } from "@hono/node-server";
 import { fromByteArray, toByteArray } from "base64-js";
+import os, { homedir, hostname } from "node:os";
+import { serve } from "@hono/node-server";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import pc from "picocolors";
 import { openRepository } from "es-git";
@@ -24,7 +24,6 @@ import { randomBytes as randomBytes$1, utf8ToBytes } from "@noble/ciphers/utils.
 import { ed25519, x25519 } from "@noble/curves/ed25519.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
 import { sha256 } from "@noble/hashes/sha2.js";
-import { connect } from "@tursodatabase/database";
 //#region src/app-server.ts
 var CodexAppServerClient = class {
 	child;
@@ -839,6 +838,7 @@ function createApp(options = {}) {
 	const appServerHistoryLoadsByThreadId = /* @__PURE__ */ new Map();
 	const steeringThreads = /* @__PURE__ */ new Set();
 	const secureSessionsByTokenHash = /* @__PURE__ */ new Map();
+	const activeStreamControllers = /* @__PURE__ */ new Set();
 	const threadOptions = { workingDirectory: workspacePath };
 	const scheduleAppServerHistoryLoad = (threadId, cachedMessages) => {
 		if (!appServer || appServerHistoryLoadsByThreadId.has(threadId)) return;
@@ -870,7 +870,7 @@ function createApp(options = {}) {
 	};
 	app.use("*", cors());
 	app.use("*", async (c, next) => {
-		if (!options.pairing || c.req.method === "OPTIONS" || c.req.path === apiPaths.version || c.req.path.startsWith(`${apiPaths.imageAttachments}/`) || c.req.path.startsWith(apiPaths.pair)) {
+		if (!options.pairing || c.req.method === "OPTIONS" || c.req.path === apiPaths.version || c.req.path.startsWith(`${apiPaths.imageAttachments}/`) || c.req.path === apiPaths.sessionsClear || c.req.path.startsWith(apiPaths.pair)) {
 			await next();
 			return;
 		}
@@ -978,6 +978,18 @@ function createApp(options = {}) {
 		});
 		return c.json({ ok: true });
 	});
+	app.post(apiPaths.sessionsClear, async (c) => {
+		if (!options.pairing) return c.json(apiError("pairing_disabled", "Pairing is not enabled on this server."), 404);
+		if (options.pairing.approvalSecret && c.req.header("x-codex-relay-approve-secret") !== options.pairing.approvalSecret) return c.json(apiError("unauthorized", "Pairing clear must come from this machine."), 401);
+		const result = await options.pairing.sessions.clearAll();
+		secureSessionsByTokenHash.clear();
+		closeActiveStreamControllers(activeStreamControllers);
+		options.pairing.onPairingsCleared?.(result);
+		return c.json({
+			ok: true,
+			...result
+		});
+	});
 	app.post(apiPaths.sessionRefresh, async (c) => {
 		if (!options.pairing) return c.json(apiError("pairing_disabled", "Pairing is not enabled on this server."), 404);
 		const oldToken = parseBearerToken(c.req.header("authorization"));
@@ -1748,9 +1760,12 @@ function createApp(options = {}) {
 		});
 		const encoder = new TextEncoder();
 		const secureSession = getSecureSessionForRequest(c, options.pairing, secureSessionsByTokenHash);
+		let streamController;
 		let streamSettled = false;
 		const stream = new ReadableStream({
 			start(controller) {
+				streamController = controller;
+				activeStreamControllers.add(controller);
 				relayDebugLog("thread.stream.started", {
 					mode: !runOptions.prompt && appServer ? "attach" : "run",
 					threadId
@@ -1781,6 +1796,7 @@ function createApp(options = {}) {
 							mode: "attach",
 							threadId
 						});
+						activeStreamControllers.delete(controller);
 						stopPreviewMonitor();
 					});
 					return;
@@ -1798,6 +1814,7 @@ function createApp(options = {}) {
 						mode: "unsupported",
 						threadId
 					});
+					activeStreamControllers.delete(controller);
 					stopPreviewMonitor();
 					return;
 				}
@@ -1830,10 +1847,12 @@ function createApp(options = {}) {
 						mode: "run",
 						threadId
 					});
+					activeStreamControllers.delete(controller);
 					stopPreviewMonitor();
 				});
 			},
 			cancel(reason) {
+				if (streamController) activeStreamControllers.delete(streamController);
 				relayDebugLog("thread.stream.cancelled_by_client", {
 					reason: debugReason(reason),
 					settled: streamSettled,
@@ -3476,10 +3495,32 @@ function updateThread(threads, messagesByThreadId, threadId, update) {
 }
 function sendSse(controller, encoder, secureSession, event) {
 	const parsed = StreamThreadRunEventSchema.parse(event);
+	const threadId = threadIdFromStreamEvent(parsed);
+	relayDebugLog("thread.stream.sse", {
+		direction: "server_to_mobile",
+		eventType: parsed.type,
+		threadId,
+		payload: parsed
+	});
 	const data = secureSession ? EncryptedPayloadSchema.parse(encryptForMobile(secureSession.session, JSON.stringify(parsed))) : parsed;
 	if (secureSession) secureSession.persist().catch(() => void 0);
-	if (!enqueueSseChunk(controller, encoder.encode(`event: ${parsed.type}\n`))) return;
-	enqueueSseChunk(controller, encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
+	if (!enqueueSseChunk(controller, encoder.encode(`event: ${parsed.type}\n`))) {
+		relayDebugLog("thread.stream.sse.enqueue_failed", {
+			eventType: parsed.type,
+			stage: "event",
+			threadId
+		});
+		return;
+	}
+	if (!enqueueSseChunk(controller, encoder.encode(`data: ${JSON.stringify(data)}\n\n`))) relayDebugLog("thread.stream.sse.enqueue_failed", {
+		eventType: parsed.type,
+		stage: "data",
+		threadId
+	});
+}
+function threadIdFromStreamEvent(event) {
+	if ("threadId" in event && typeof event.threadId === "string") return event.threadId;
+	if ("thread" in event && event.thread) return event.thread.id;
 }
 function enqueueSseChunk(controller, chunk) {
 	try {
@@ -3499,6 +3540,10 @@ function closeSseController(controller) {
 		throw error;
 	}
 }
+function closeActiveStreamControllers(controllers) {
+	for (const controller of controllers) closeSseController(controller);
+	controllers.clear();
+}
 function isClosedStreamControllerError(error) {
 	return error instanceof TypeError && error.code === "ERR_INVALID_STATE" && error.message.includes("Controller is already closed");
 }
@@ -5170,8 +5215,11 @@ async function git(cwd, args) {
 }
 async function listWorkspaceFiles(workspacePath, query, directory) {
 	const normalizedQuery = query.toLowerCase();
-	const filePaths = await workspaceFilePaths(workspacePath);
+	const isIgnored = await workspaceIgnoreMatcher(workspacePath);
+	if (directory && isWorkspacePathIgnored(directory, isIgnored)) return [];
+	const filePaths = await workspaceFilePaths(workspacePath, isIgnored);
 	const entriesByPath = /* @__PURE__ */ new Map();
+	for (const entry of await workspaceDirectoryEntries(workspacePath, directory, isIgnored)) entriesByPath.set(entry.path, entry);
 	for (const path of filePaths) {
 		if (!path || path.startsWith("../") || path.includes("/.git/")) continue;
 		if (!directory && normalizedQuery) {
@@ -5184,6 +5232,7 @@ async function listWorkspaceFiles(workspacePath, query, directory) {
 			const parts = path.split("/");
 			for (let index = 1; index < parts.length; index += 1) {
 				const directoryPath = parts.slice(0, index).join("/");
+				if (isWorkspacePathIgnored(directoryPath, isIgnored)) continue;
 				entriesByPath.set(directoryPath, {
 					directory: dirname(directoryPath) === "." ? "" : dirname(directoryPath),
 					kind: "directory",
@@ -5205,6 +5254,7 @@ async function listWorkspaceFiles(workspacePath, query, directory) {
 		});
 		else {
 			const directoryPath = [...directory ? directory.split("/") : [], childParts[0]].join("/");
+			if (isWorkspacePathIgnored(directoryPath, isIgnored)) continue;
 			entriesByPath.set(directoryPath, {
 				directory,
 				kind: "directory",
@@ -5383,19 +5433,32 @@ function languageFromWorkspaceFile(path) {
 		yml: "yaml"
 	}[extension] ?? extension;
 }
-async function workspaceFilePaths(workspacePath) {
-	const isIgnored = await workspaceIgnoreMatcher(workspacePath);
+async function workspaceFilePaths(workspacePath, isIgnored) {
 	try {
 		return (await git(workspacePath, [
 			"ls-files",
 			"--cached",
 			"--others",
 			"--exclude-standard"
-		])).split("\n").filter(Boolean).filter((path) => !isIgnored(path));
+		])).split("\n").filter(Boolean).filter((path) => !isWorkspacePathIgnored(path, isIgnored));
 	} catch {
 		return recursiveWorkspaceFilePaths(workspacePath, isIgnored);
 	}
 }
+async function workspaceDirectoryEntries(workspacePath, directory, isIgnored) {
+	const rootPath = resolve(workspacePath);
+	const absoluteDirectory = resolve(rootPath, directory);
+	if (absoluteDirectory !== rootPath && !isPathInside(rootPath, absoluteDirectory)) return [];
+	return (await readdir(absoluteDirectory, { withFileTypes: true })).filter((entry) => entry.isDirectory() && entry.name !== ".git").map((entry) => {
+		const path = [...directory ? directory.split("/") : [], entry.name].join("/");
+		return {
+			directory,
+			kind: "directory",
+			name: entry.name,
+			path
+		};
+	}).filter((entry) => !isWorkspacePathIgnored(entry.path, isIgnored));
+}
 async function recursiveWorkspaceFilePaths(rootPath, isIgnored) {
 	const ignoredDirectories = new Set([
 		".git",
@@ -5411,7 +5474,7 @@ async function recursiveWorkspaceFilePaths(rootPath, isIgnored) {
 			if (entry.name.startsWith(".") && entry.name !== ".github") continue;
 			const absolutePath = resolve(directory, entry.name);
 			const relativePath = relative(rootPath, absolutePath).split("\\").join("/");
-			if (isIgnored(relativePath)) continue;
+			if (isWorkspacePathIgnored(relativePath, isIgnored)) continue;
 			if (entry.isDirectory()) {
 				if (ignoredDirectories.has(entry.name)) continue;
 				await visit(absolutePath);
@@ -5427,6 +5490,17 @@ async function workspaceIgnoreMatcher(workspacePath) {
 	const matchers = (await readFile(join(workspacePath, ".gitignore"), "utf8").catch(() => "")).split(/\r?\n/).map((line) => gitignorePatternMatcher(line)).filter((matcher) => Boolean(matcher));
 	return (path) => matchers.some((matcher) => matcher(path.split("\\").join("/")));
 }
+function isWorkspacePathIgnored(path, isIgnored) {
+	const normalizedPath = path.replace(/^\/+/, "").replaceAll("\\", "/").replace(/\/+$/, "");
+	if (!normalizedPath) return false;
+	if (isIgnored(normalizedPath) || isIgnored(`${normalizedPath}/`)) return true;
+	const parts = normalizedPath.split("/");
+	for (let index = 1; index < parts.length; index += 1) {
+		const ancestorPath = parts.slice(0, index).join("/");
+		if (isIgnored(ancestorPath) || isIgnored(`${ancestorPath}/`)) return true;
+	}
+	return false;
+}
 function gitignorePatternMatcher(line) {
 	const trimmed = line.trim();
 	if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("!")) return;
@@ -5439,7 +5513,7 @@ function gitignorePatternMatcher(line) {
 	return (path) => {
 		const normalizedPath = path.replace(/^\/+/, "");
 		return (anchored || hasSlash ? [normalizedPath] : normalizedPath.split("/")).some((candidate) => {
-			if (directoryOnly) return matcher(candidate) || normalizedPath.startsWith(`${candidate}/`);
+			if (directoryOnly) return matcher(candidate);
 			return matcher(candidate);
 		});
 	};
@@ -5473,238 +5547,6 @@ function errorMessage(error) {
 	return error instanceof Error ? error.message : "Codex run failed.";
 }
 //#endregion
-//#region src/pairing-store.ts
-async function createTursoPairingSessionStore(path) {
-	if (path !== ":memory:") await mkdir(dirname(path), { recursive: true });
-	const db = await connect(path);
-	await db.exec(`
-    CREATE TABLE IF NOT EXISTS pairing_sessions (
-      token_hash TEXT PRIMARY KEY,
-      client_session_id TEXT,
-      client_name TEXT,
-      expires_at INTEGER NOT NULL,
-      key_epoch INTEGER,
-      mobile_to_server_key TEXT,
-      server_to_mobile_key TEXT,
-      last_mobile_counter INTEGER,
-      next_server_counter INTEGER,
-      created_at INTEGER NOT NULL,
-      updated_at INTEGER NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS pending_pairings (
-      approval_code TEXT PRIMARY KEY,
-      client_session_id TEXT,
-      client_name TEXT,
-      client_ephemeral_public_key TEXT NOT NULL,
-      client_nonce TEXT NOT NULL,
-      server_url TEXT NOT NULL,
-      approved INTEGER NOT NULL DEFAULT 0,
-      expires_at INTEGER NOT NULL,
-      created_at INTEGER NOT NULL,
-      updated_at INTEGER NOT NULL
-    );
-  `);
-	await ensurePairingSessionColumns();
-	async function countActive(now) {
-		const row = await db.prepare("SELECT COUNT(DISTINCT COALESCE(client_session_id, token_hash)) AS count FROM pairing_sessions WHERE expires_at > ?").get(now);
-		return Number(row?.count ?? 0);
-	}
-	async function deleteSession(tokenHash) {
-		await db.prepare("DELETE FROM pairing_sessions WHERE token_hash = ?").run(tokenHash);
-	}
-	async function deletePendingPairing(approvalCode) {
-		await db.prepare("DELETE FROM pending_pairings WHERE approval_code = ?").run(approvalCode);
-	}
-	async function getPendingPairing(approvalCode, now) {
-		const row = await db.prepare(`SELECT approval_code AS approvalCode,
-                client_session_id AS clientSessionId,
-                client_name AS clientName,
-                client_ephemeral_public_key AS clientEphemeralPublicKey,
-                client_nonce AS clientNonce,
-                server_url AS serverUrl,
-                approved,
-                expires_at AS expiresAt
-         FROM pending_pairings
-         WHERE approval_code = ?`).get(approvalCode);
-		if (!row) return;
-		const expiresAt = Number(row.expiresAt);
-		if (now > expiresAt) {
-			await deletePendingPairing(approvalCode);
-			return;
-		}
-		return {
-			approvalCode: String(row.approvalCode),
-			approved: Number(row.approved) === 1,
-			clientEphemeralPublicKey: String(row.clientEphemeralPublicKey),
-			clientSessionId: typeof row.clientSessionId === "string" ? row.clientSessionId : void 0,
-			clientName: typeof row.clientName === "string" ? row.clientName : void 0,
-			clientNonce: String(row.clientNonce),
-			expiresAt,
-			serverUrl: String(row.serverUrl)
-		};
-	}
-	return {
-		async approvePendingPairing(approvalCode, now) {
-			const pending = await getPendingPairing(approvalCode, now);
-			if (!pending) return;
-			await db.prepare("UPDATE pending_pairings SET approved = 1, updated_at = ? WHERE approval_code = ?").run(now, approvalCode);
-			return {
-				...pending,
-				approved: true
-			};
-		},
-		countActive,
-		async createPendingPairing(pairing) {
-			const now = Date.now();
-			await db.prepare(`INSERT INTO pending_pairings (
-             approval_code,
-             client_session_id,
-             client_name,
-             client_ephemeral_public_key,
-             client_nonce,
-             server_url,
-             approved,
-             expires_at,
-             created_at,
-             updated_at
-           )
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(pairing.approvalCode, pairing.clientSessionId ?? null, pairing.clientName ?? null, pairing.clientEphemeralPublicKey, pairing.clientNonce, pairing.serverUrl, pairing.approved ? 1 : 0, pairing.expiresAt, now, now);
-		},
-		async createSession(tokenHash, session) {
-			const now = Date.now();
-			const secure = encodeSecureSession(session.secureSession);
-			if (session.clientSessionId) {
-				await db.prepare("DELETE FROM pairing_sessions WHERE client_session_id = ?").run(session.clientSessionId);
-				if (session.clientName) await db.prepare("DELETE FROM pairing_sessions WHERE client_session_id IS NULL AND client_name = ?").run(session.clientName);
-			}
-			await db.prepare(`INSERT INTO pairing_sessions (
-             token_hash,
-             client_session_id,
-             client_name,
-             expires_at,
-             key_epoch,
-             mobile_to_server_key,
-             server_to_mobile_key,
-             last_mobile_counter,
-             next_server_counter,
-             created_at,
-             updated_at
-           )
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(tokenHash, session.clientSessionId ?? null, session.clientName ?? null, session.expiresAt, secure?.keyEpoch ?? null, secure?.mobileToServerKey ?? null, secure?.serverToMobileKey ?? null, secure?.lastMobileCounter ?? null, secure?.nextServerCounter ?? null, now, now);
-			return countActive(now);
-		},
-		deleteSession,
-		deletePendingPairing,
-		getPendingPairing,
-		async getValidSession(tokenHash, now) {
-			const row = await db.prepare(`SELECT client_name AS clientName,
-                  client_session_id AS clientSessionId,
-                  expires_at AS expiresAt,
-                  key_epoch AS keyEpoch,
-                  mobile_to_server_key AS mobileToServerKey,
-                  server_to_mobile_key AS serverToMobileKey,
-                  last_mobile_counter AS lastMobileCounter,
-                  next_server_counter AS nextServerCounter
-           FROM pairing_sessions
-           WHERE token_hash = ?`).get(tokenHash);
-			if (!row) return;
-			const expiresAt = Number(row.expiresAt);
-			if (now > expiresAt) {
-				await deleteSession(tokenHash);
-				return;
-			}
-			return {
-				clientSessionId: typeof row.clientSessionId === "string" ? row.clientSessionId : void 0,
-				clientName: typeof row.clientName === "string" ? row.clientName : void 0,
-				expiresAt,
-				secureSession: decodeSecureSession(row)
-			};
-		},
-		async pruneExpired(now) {
-			await db.prepare("DELETE FROM pairing_sessions WHERE expires_at <= ?").run(now);
-			await db.prepare("DELETE FROM pending_pairings WHERE expires_at <= ?").run(now);
-		},
-		async rotateSession(oldTokenHash, newTokenHash, session) {
-			const now = Date.now();
-			const secure = encodeSecureSession(session.secureSession);
-			await db.transaction(async () => {
-				await db.prepare("DELETE FROM pairing_sessions WHERE token_hash = ?").run(oldTokenHash);
-				if (session.clientSessionId) {
-					await db.prepare("DELETE FROM pairing_sessions WHERE client_session_id = ?").run(session.clientSessionId);
-					if (session.clientName) await db.prepare("DELETE FROM pairing_sessions WHERE client_session_id IS NULL AND client_name = ?").run(session.clientName);
-				}
-				await db.prepare(`INSERT INTO pairing_sessions (
-               token_hash,
-               client_session_id,
-               client_name,
-               expires_at,
-               key_epoch,
-               mobile_to_server_key,
-               server_to_mobile_key,
-               last_mobile_counter,
-               next_server_counter,
-               created_at,
-               updated_at
-             )
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(newTokenHash, session.clientSessionId ?? null, session.clientName ?? null, session.expiresAt, secure?.keyEpoch ?? null, secure?.mobileToServerKey ?? null, secure?.serverToMobileKey ?? null, secure?.lastMobileCounter ?? null, secure?.nextServerCounter ?? null, now, now);
-			})();
-			return countActive(now);
-		},
-		async updateSecureSession(tokenHash, secureSession) {
-			const secure = encodeSecureSession(secureSession);
-			const now = Date.now();
-			await db.prepare(`UPDATE pairing_sessions
-           SET key_epoch = ?,
-               mobile_to_server_key = ?,
-               server_to_mobile_key = ?,
-               last_mobile_counter = ?,
-               next_server_counter = ?,
-               updated_at = ?
-           WHERE token_hash = ?`).run(secure.keyEpoch, secure.mobileToServerKey, secure.serverToMobileKey, secure.lastMobileCounter, secure.nextServerCounter, now, tokenHash);
-		}
-	};
-	async function ensurePairingSessionColumns() {
-		const rows = await db.prepare("PRAGMA table_info(pairing_sessions)").all();
-		const columns = new Set(resultRows(rows).map((row) => String(row.name)));
-		for (const [column, sql] of [
-			["client_session_id", "ALTER TABLE pairing_sessions ADD COLUMN client_session_id TEXT"],
-			["key_epoch", "ALTER TABLE pairing_sessions ADD COLUMN key_epoch INTEGER"],
-			["mobile_to_server_key", "ALTER TABLE pairing_sessions ADD COLUMN mobile_to_server_key TEXT"],
-			["server_to_mobile_key", "ALTER TABLE pairing_sessions ADD COLUMN server_to_mobile_key TEXT"],
-			["last_mobile_counter", "ALTER TABLE pairing_sessions ADD COLUMN last_mobile_counter INTEGER"],
-			["next_server_counter", "ALTER TABLE pairing_sessions ADD COLUMN next_server_counter INTEGER"]
-		]) if (!columns.has(column)) await db.exec(sql);
-		const pendingRows = await db.prepare("PRAGMA table_info(pending_pairings)").all();
-		if (!new Set(resultRows(pendingRows).map((row) => String(row.name))).has("client_session_id")) await db.exec("ALTER TABLE pending_pairings ADD COLUMN client_session_id TEXT");
-	}
-}
-function encodeSecureSession(session) {
-	if (!session) return;
-	return {
-		keyEpoch: session.keyEpoch,
-		lastMobileCounter: session.lastMobileCounter,
-		mobileToServerKey: fromByteArray(session.mobileToServerKey),
-		nextServerCounter: session.nextServerCounter,
-		serverToMobileKey: fromByteArray(session.serverToMobileKey)
-	};
-}
-function decodeSecureSession(row) {
-	if (typeof row.mobileToServerKey !== "string" || typeof row.serverToMobileKey !== "string" || row.keyEpoch === null || row.lastMobileCounter === null || row.nextServerCounter === null) return;
-	return {
-		keyEpoch: Number(row.keyEpoch),
-		lastMobileCounter: Number(row.lastMobileCounter),
-		mobileToServerKey: toByteArray(row.mobileToServerKey),
-		nextServerCounter: Number(row.nextServerCounter),
-		serverToMobileKey: toByteArray(row.serverToMobileKey)
-	};
-}
-function resultRows(result) {
-	if (Array.isArray(result)) return result;
-	if (result && typeof result === "object" && Array.isArray(result.rows)) return result.rows;
-	return [];
-}
-//#endregion
 //#region src/index.ts
 const port = Number(process.env.PORT ?? 8787);
 const hostname$1 = process.env.HOST ?? "0.0.0.0";
@@ -5755,6 +5597,9 @@ serve({
 			onPairApproved: ({ clientName }) => {
 				logRuntimeEvent("Approved", `Pairing request approved${clientName ? ` for ${clientName}` : ""}. Waiting for secure session pickup.`);
 			},
+			onPairingsCleared: ({ pendingPairingsCleared, sessionsCleared }) => {
+				logRuntimeEvent("Cleared", `Signed out ${sessionsCleared} mobile session${sessionsCleared === 1 ? "" : "s"} and removed ${pendingPairingsCleared} pending pairing request${pendingPairingsCleared === 1 ? "" : "s"}.`);
+			},
 			onTokenRefreshed: ({ clientName, tokenCount }) => {
 				logRuntimeEvent("Refreshed", `Mobile session rotated${clientName ? ` for ${clientName}` : ""}; ${formatClientCount(tokenCount)} active.`);
 			}
@@ -5765,10 +5610,19 @@ serve({
 	port
 }, (info) => {
 	const listenUrl = `http://${info.address}:${info.port}`;
-	const connectUrl = getConfiguredConnectUrl() ?? getTailscaleConnectUrl(info.port) ?? getLocalNetworkConnectUrl(info.port) ?? listenUrl;
-	const pairingPayload = createPairingQrPayload(connectUrl);
+	const connectUrlCandidates = getConnectUrlCandidates({
+		listenUrl,
+		port: info.port
+	});
+	const connectUrl = connectUrlCandidates[0]?.url ?? listenUrl;
+	const connectUrls = connectUrlCandidates.map((candidate) => candidate.url);
+	const pairingPayload = createPairingQrPayload({
+		serverPublicKey: serverIdentity.publicKey,
+		serverUrls: connectUrls.length > 0 ? connectUrls : [connectUrl]
+	});
 	writeServerState({
 		connectUrl,
+		connectUrlCandidates,
 		host: hostname$1,
 		listenUrl,
 		pairingPayload,
@@ -5779,6 +5633,7 @@ serve({
 		logRuntimeEvent("Debug", `Writing diagnostics to ${debugLogPath}`);
 		relayDebugLog("relay.started", {
 			connectUrl,
+			connectUrlCandidates,
 			listenUrl,
 			port: info.port,
 			workspacePath: process.env.CODEX_RELAY_WORKSPACE_PATH ?? process.cwd()
@@ -5788,6 +5643,7 @@ serve({
 	qrcode.generate(pairingPayload, { small: true });
 	console.log(formatStartupInstructions({
 		connectUrl,
+		connectUrlCandidates,
 		dangerouslyAutoApprove,
 		listenUrl,
 		pairingPayload,
@@ -5801,6 +5657,8 @@ function formatStartupInstructions(details) {
 			`${color.prompt("›")} Scan the QR code above to pair ${color.brand("Codex Relay mobile")}.`,
 			"",
 			`${color.prompt("›")} Mobile: ${color.url(details.connectUrl)}`,
+			...formatConnectUrlGuidance(details.connectUrl),
+			...formatConnectUrlCandidates(details.connectUrlCandidates),
 			`${color.prompt("›")} Server: ${color.muted(details.listenUrl)}`,
 			"",
 			`${color.prompt("›")} Pairing: ${color.url(details.pairingPayload)}`,
@@ -5817,34 +5675,23 @@ function formatStartupInstructions(details) {
 		""
 	].join("\n");
 }
+function formatConnectUrlGuidance(connectUrl) {
+	const guidance = getConnectUrlGuidance(connectUrl);
+	return guidance ? [`${color.prompt("›")} Network: ${guidance}`] : [];
+}
+function formatConnectUrlCandidates(candidates) {
+	if (candidates.length <= 1) return [];
+	return [`${color.prompt("›")} QR includes ${candidates.length} candidate addresses; the app will use the first reachable one.`, ...candidates.slice(1).map((candidate) => `  ${color.muted(candidate.label)} ${color.url(candidate.url)}`)];
+}
 function logRuntimeEvent(label, message) {
 	console.log(`${color.prompt("›")} ${color.event(label.padEnd(8))} ${message}`);
 }
 function formatClientCount(tokenCount) {
 	return `${tokenCount} client${tokenCount === 1 ? "" : "s"}`;
 }
-function createPairingQrPayload(serverUrl) {
-	const url = new URL("codex-relay://pair");
-	url.searchParams.set("serverUrl", serverUrl);
-	url.searchParams.set("serverPublicKey", serverIdentity.publicKey);
-	return url.toString();
-}
 function hashClientToken(token) {
 	return createHash("sha256").update(token).digest("base64url");
 }
-function getConfiguredConnectUrl() {
-	const configuredUrl = normalizeUrl(process.env.CODEX_RELAY_PUBLIC_URL);
-	if (configuredUrl) return configuredUrl;
-}
-function getTailscaleConnectUrl(port) {
-	const status = getTailscaleStatus();
-	const tailscaleIp = status?.Self?.TailscaleIPs?.find((ip) => ip.startsWith("100.") && ip.includes("."));
-	if (tailscaleIp) return `http://${tailscaleIp}:${port}`;
-	const dnsName = status?.Self?.DNSName?.replace(/\.$/, "");
-	if (dnsName) return getTailscaleServeHttpsUrl(dnsName, port) ?? `http://${dnsName}:${port}`;
-	const tailscaleHost = status?.Self?.TailscaleIPs?.find((ip) => ip.includes("."));
-	return tailscaleHost ? `http://${tailscaleHost}:${port}` : void 0;
-}
 async function getApprovalSecret() {
 	if (process.env.CODEX_RELAY_APPROVAL_SECRET) return process.env.CODEX_RELAY_APPROVAL_SECRET;
 	const path = await prepareCodexRelayDataPath("approval-secret");
@@ -5897,58 +5744,5 @@ async function writeBackgroundPid() {
 function formatApprovalCommand(approvalCode, activePort) {
 	return activePort === 8787 ? `${npxCommand} approve ${approvalCode}` : `PORT=${activePort} ${npxCommand} approve ${approvalCode}`;
 }
-function getLocalNetworkConnectUrl(port) {
-	for (const addresses of Object.values(networkInterfaces())) for (const address of addresses ?? []) if (address.family === "IPv4" && !address.internal) return `http://${address.address}:${port}`;
-}
-function normalizeUrl(value) {
-	if (!value) return;
-	const trimmed = value.trim().replace(/\/$/, "");
-	if (!trimmed) return;
-	try {
-		const url = new URL(trimmed);
-		return url.protocol === "http:" || url.protocol === "https:" ? url.toString().replace(/\/$/, "") : void 0;
-	} catch {
-		return;
-	}
-}
-function getTailscaleStatus() {
-	try {
-		const output = execFileSync("tailscale", ["status", "--json"], {
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			],
-			timeout: 1500
-		});
-		return JSON.parse(output);
-	} catch {
-		return;
-	}
-}
-function getTailscaleServeHttpsUrl(dnsName, port) {
-	try {
-		const output = execFileSync("tailscale", [
-			"serve",
-			"status",
-			"--json"
-		], {
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			],
-			timeout: 1500
-		});
-		const serveStatus = JSON.parse(output);
-		const portKey = String(port);
-		const hostPort = `${dnsName}:${portKey}`;
-		return serveStatus.TCP?.[portKey]?.HTTPS && serveStatus.Web?.[hostPort] ? `https://${hostPort}` : void 0;
-	} catch {
-		return;
-	}
-}
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-relay",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Local Codex Relay CLI bridge for the Codex Relay mobile app.",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
     "@noble/ciphers": "2.2.0",
     "@noble/curves": "2.2.0",
     "@noble/hashes": "2.2.0",
-    "@openai/codex-sdk": "^0.125.0",
+    "@openai/codex-sdk": "^0.130.0",
     "@tursodatabase/database": "^0.5.3",
     "base64-js": "1.5.1",
     "commander": "^14.0.3",

package/src/api-schema.ts

@@ -906,6 +906,7 @@ export const apiPaths = {
   pair: "/v1/pair",
   pairApproval: (approvalCode: string) => `/v1/pair/${encodeURIComponent(approvalCode)}`,
   pairApprove: "/v1/pair/approve",
+  sessionsClear: "/v1/sessions/clear",
   sessionRefresh: "/v1/session/refresh",
   status: "/v1/status",
   preferences: "/v1/preferences",