planche 0.7.13 → 0.7.14

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { createRequire as createRequire2 } from "module";
 import { spawn } from "child_process";
 import { parseArgs } from "util";
@@ -1028,6 +1028,468 @@ var d1DriverFactory = {
   }
 };
 
+// src/drivers/do.ts
+var LOCAL_EXPLORER = "/cdn-cgi/local/explorer/api";
+var CLOUDFLARE_API = "https://api.cloudflare.com/client/v4";
+var MAX_OBJECTS = 5e3;
+var DoError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+  status;
+};
+var DATABASE_LIST2 = /^\s*PRAGMA\s+database_list\s*;?\s*$/i;
+var RESULT_KIND2 = /^\s*(SELECT|WITH|PRAGMA|EXPLAIN|VALUES)\b/i;
+var TRANSACTION = /^\s*(BEGIN|COMMIT|END|ROLLBACK|SAVEPOINT|RELEASE)\b/i;
+var DDL = /^\s*(CREATE|ALTER|DROP)\b/i;
+var HEX_ID = /^[0-9a-f]{64}$/i;
+function singleSourceTable3(sql2) {
+  const m = /\bFROM\s+("[^"]+"|`[^`]+`|\[[^\]]+\]|[\w$]+)([\s\S]*)$/i.exec(sql2);
+  if (!m) return null;
+  const rest = m[2].replace(
+    /\b(WHERE|ORDER\s+BY|GROUP\s+BY|HAVING|LIMIT|OFFSET|UNION|EXCEPT|INTERSECT|WINDOW)\b[\s\S]*$/i,
+    ""
+  );
+  if (/,|\bJOIN\b|\(/i.test(rest) || rest.trim().split(/\s+/).filter(Boolean).length > 2) return null;
+  const raw = m[1];
+  const first = raw[0];
+  if (first === '"') return raw.slice(1, -1).replaceAll('""', '"');
+  if (first === "`") return raw.slice(1, -1).replaceAll("``", "`");
+  if (first === "[") return raw.slice(1, -1);
+  return raw;
+}
+function normalizeDeclaredType3(declared) {
+  if (typeof declared !== "string") return null;
+  const base = declared.trim().toLowerCase().replace(/\(.*$/, "").trim();
+  return base || null;
+}
+function inferTypeFromValue3(value) {
+  if (value === null || value === void 0) return "null";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "real";
+  if (Array.isArray(value)) return "blob";
+  return "text";
+}
+function firstNonNull3(records, index) {
+  for (const row of records) {
+    const value = row[index];
+    if (value !== null && value !== void 0) return value;
+  }
+  return null;
+}
+function closingQuote(sql2, start, close) {
+  let i = start + 1;
+  while (i < sql2.length) {
+    if (sql2[i] === close) {
+      if (sql2[i + 1] === close && close !== "]") {
+        i += 2;
+        continue;
+      }
+      return i + 1;
+    }
+    i += 1;
+  }
+  return sql2.length;
+}
+function skipSpace(sql2, from) {
+  let i = from;
+  while (i < sql2.length && /\s/.test(sql2[i])) i += 1;
+  return i;
+}
+function routeStatement(sql2, known) {
+  let out = "";
+  let target = null;
+  let i = 0;
+  while (i < sql2.length) {
+    const ch = sql2[i];
+    if (ch === "'") {
+      const end = closingQuote(sql2, i, "'");
+      out += sql2.slice(i, end);
+      i = end;
+      continue;
+    }
+    if (ch === "-" && sql2[i + 1] === "-") {
+      const end = sql2.indexOf("\n", i);
+      const stop = end === -1 ? sql2.length : end;
+      out += sql2.slice(i, stop);
+      i = stop;
+      continue;
+    }
+    if (ch === "/" && sql2[i + 1] === "*") {
+      const end = sql2.indexOf("*/", i + 2);
+      const stop = end === -1 ? sql2.length : end + 2;
+      out += sql2.slice(i, stop);
+      i = stop;
+      continue;
+    }
+    if (ch === '"' || ch === "`" || ch === "[") {
+      const close = ch === "[" ? "]" : ch;
+      const end = closingQuote(sql2, i, close);
+      const raw = sql2.slice(i, end);
+      const inner = ch === "[" ? raw.slice(1, -1) : raw.slice(1, -1).replaceAll(close + close, close);
+      const dot = skipSpace(sql2, end);
+      if (sql2[dot] === "." && known(inner)) {
+        target ??= inner;
+        i = dot + 1;
+        continue;
+      }
+      out += raw;
+      i = end;
+      continue;
+    }
+    out += ch;
+    i += 1;
+  }
+  return { sql: out, target };
+}
+async function fetchJson(url, init, unreachable) {
+  let res;
+  try {
+    res = await fetch(url, { ...init, signal: AbortSignal.timeout(6e4) });
+  } catch (err) {
+    throw unreachable(err instanceof Error ? err.message : String(err));
+  }
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+  }
+  return { res, body };
+}
+var LocalTransport = class {
+  label;
+  base;
+  constructor(devUrl) {
+    this.label = `do:${devUrl}`;
+    this.base = `${devUrl.replace(/\/+$/, "")}${LOCAL_EXPLORER}`;
+  }
+  async call(path, body) {
+    const origin = this.base.replace(LOCAL_EXPLORER, "");
+    const { res, body: parsed } = await fetchJson(
+      `${this.base}${path}`,
+      {
+        method: body === void 0 ? "GET" : "POST",
+        headers: body === void 0 ? void 0 : { "Content-Type": "application/json" },
+        body: body === void 0 ? void 0 : JSON.stringify(body)
+      },
+      (reason) => new DoError(
+        `Cannot reach a wrangler dev server at ${origin} (${reason}). Run \`wrangler dev\` in your Worker project and try again.`,
+        400
+      )
+    );
+    const envelope = parsed && typeof parsed.success === "boolean" && (parsed.result !== void 0 || Array.isArray(parsed.errors)) ? parsed : null;
+    if (!envelope) {
+      throw new DoError(
+        `${origin} answered (HTTP ${res.status}) but is not a wrangler dev server. Check the port, and that \`wrangler dev\` (wrangler 4.x) is what is running there.`,
+        400
+      );
+    }
+    if (!res.ok || !envelope.success) {
+      throw new DoError(errorText(envelope.errors) || `wrangler dev responded ${res.status}`, res.ok ? void 0 : 400);
+    }
+    if (envelope.result === void 0) throw new DoError("wrangler dev returned no result");
+    return envelope.result;
+  }
+  async namespaces() {
+    const list = await this.call("/workers/durable_objects/namespaces");
+    return list.map((ns) => ({ id: ns.id, sqlite: ns.use_sqlite !== false }));
+  }
+  objects(namespaceId) {
+    return this.call(`/workers/durable_objects/namespaces/${encodeURIComponent(namespaceId)}/objects`);
+  }
+  async run(target, sql2) {
+    const selector = target.name ? { durable_object_name: target.name } : { durable_object_id: target.id };
+    const results = await this.call(
+      `/workers/durable_objects/namespaces/${encodeURIComponent(target.namespaceId)}/query`,
+      { ...selector, queries: [{ sql: sql2 }] }
+    );
+    const result = results[0];
+    if (!result) throw new DoError("wrangler dev returned no result");
+    return result;
+  }
+};
+var RemoteTransport = class {
+  label;
+  base;
+  headers;
+  only;
+  constructor(config) {
+    this.label = `do:${config.accountId}${config.namespaceId ? `/${config.namespaceId}` : ""}`;
+    this.base = `${CLOUDFLARE_API}/accounts/${encodeURIComponent(config.accountId)}/workers/durable_objects/namespaces`;
+    this.headers = { Authorization: `Bearer ${config.apiToken}`, "Content-Type": "application/json" };
+    this.only = config.namespaceId || void 0;
+  }
+  async call(path, body) {
+    const { res, body: parsed } = await fetchJson(
+      `${this.base}${path}`,
+      {
+        method: body === void 0 ? "GET" : "POST",
+        headers: this.headers,
+        body: body === void 0 ? void 0 : JSON.stringify(body)
+      },
+      (reason) => new DoError(`Cannot reach the Cloudflare API: ${reason}`, 400)
+    );
+    if (res.status === 401 || res.status === 403) {
+      throw new DoError(
+        errorText(parsed?.errors) || "Cloudflare refused the API token. It needs the Workers Scripts Read permission on this account.",
+        401
+      );
+    }
+    if (res.status === 404 || res.status === 405) {
+      throw new DoError(
+        "Cloudflare did not accept this request (HTTP " + res.status + "). The Durable Object query endpoint is unofficial and may have changed; the Data Studio tab in the Cloudflare dashboard still works.",
+        400
+      );
+    }
+    if (!res.ok || !parsed?.success) {
+      throw new DoError(errorText(parsed?.errors) || `Cloudflare API responded ${res.status}`, 400);
+    }
+    return parsed;
+  }
+  async namespaces() {
+    if (this.only) return [{ id: this.only, sqlite: true }];
+    const body = await this.call("");
+    return (body.result ?? []).map((ns) => ({ id: ns.id, sqlite: ns.use_sqlite !== false }));
+  }
+  /**
+   * Cloudflare's listing returns ids and `hasStoredData`, never names. It also
+   * answers an empty page for small `limit` values, so the parameter is left
+   * off and the default page size is used, following `result_info.cursor`.
+   */
+  async objects(namespaceId) {
+    const out = [];
+    let cursor;
+    do {
+      const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
+      const body = await this.call(
+        `/${encodeURIComponent(namespaceId)}/objects${query}`
+      );
+      for (const object of body.result ?? []) out.push({ id: object.id });
+      cursor = body.result_info?.cursor || void 0;
+    } while (cursor && out.length < MAX_OBJECTS);
+    return out;
+  }
+  async run(target, sql2) {
+    if (!target.id) {
+      throw new DoError(
+        `"${target.name}" is a name, and deployed Durable Objects can only be opened by id: idFromName() is a one-way hash and Cloudflare does not resolve it here. Pick an object from the schema tree.`,
+        400
+      );
+    }
+    const body = await this.call(
+      `/${encodeURIComponent(target.namespaceId)}/query`,
+      { durable_object_id: target.id, queries: [{ sql: sql2 }] }
+    );
+    const result = body.result?.results?.[0];
+    if (!result) throw new DoError("Cloudflare returned no result");
+    return result;
+  }
+};
+function errorText(errors) {
+  if (!Array.isArray(errors)) return "";
+  return errors.map((e) => typeof e === "string" ? e : String(e?.message ?? "")).filter(Boolean).join("; ").slice(0, 500);
+}
+var DoDriver = class {
+  constructor(type, transport) {
+    this.type = type;
+    this.transport = transport;
+    this.label = transport.label;
+  }
+  type;
+  transport;
+  label;
+  /** Database name -> the object it addresses, refreshed by every listing. */
+  targets = /* @__PURE__ */ new Map();
+  /** Declared column types per `database table`, for result-source resolution. */
+  columns = /* @__PURE__ */ new Map();
+  /**
+   * Every object of every SQLite-backed namespace, as app-level database
+   * names. Locally, a `wrangler dev` session registers itself in wrangler's
+   * dev registry, so sessions of other projects show up here too.
+   */
+  async listDatabases() {
+    const namespaces = await this.transport.namespaces();
+    const names = [];
+    this.targets.clear();
+    for (const ns of namespaces) {
+      if (!ns.sqlite) continue;
+      let objects;
+      try {
+        objects = await this.transport.objects(ns.id);
+      } catch {
+        continue;
+      }
+      for (const object of objects) {
+        const ref = object.name || object.id;
+        if (!ref) continue;
+        const database = `${ns.id}/${ref}`;
+        this.targets.set(database, { namespaceId: ns.id, name: object.name, id: object.id });
+        names.push(database);
+      }
+    }
+    return names.sort();
+  }
+  /**
+   * Resolve a database name to the object it addresses. Names are cached by
+   * the last listing; one that was never listed is still usable, so a saved
+   * query tab keeps working — the trailing part is read as an id when it looks
+   * like one and as a name otherwise.
+   */
+  targetFor(database) {
+    const cached2 = this.targets.get(database);
+    if (cached2) return cached2;
+    const slash = database.indexOf("/");
+    if (slash <= 0 || slash === database.length - 1) {
+      throw new DoError(
+        `"${database}" is not a Durable Object. Pick one from the schema tree (they are named "<namespace>/<object>").`,
+        400
+      );
+    }
+    const namespaceId = database.slice(0, slash);
+    const ref = database.slice(slash + 1);
+    return HEX_ID.test(ref) ? { namespaceId, id: ref } : { namespaceId, name: ref };
+  }
+  async tableColumns(database, target, table) {
+    const key = `${database} ${table}`;
+    const cached2 = this.columns.get(key);
+    if (cached2 !== void 0) return cached2;
+    let out = null;
+    try {
+      const info = await this.transport.run(target, `PRAGMA table_info("${table.replaceAll('"', '""')}")`);
+      const cols = info.columns ?? [];
+      const name = cols.indexOf("name");
+      const type = cols.indexOf("type");
+      const rows = info.rows ?? [];
+      if (rows.length > 0 && name >= 0) {
+        out = new Map(rows.map((r) => [String(r[name]), normalizeDeclaredType3(type >= 0 ? r[type] : null)]));
+      }
+    } catch {
+      out = null;
+    }
+    if (this.columns.size > 200) this.columns.clear();
+    this.columns.set(key, out);
+    return out;
+  }
+  async query(sql2, database) {
+    if (DATABASE_LIST2.test(sql2)) {
+      const names = await this.listDatabases();
+      return {
+        fields: ["seq", "name", "file"].map((name2) => ({
+          name: name2,
+          orgName: name2,
+          type: name2 === "seq" ? "integer" : "text",
+          table: "",
+          orgTable: "",
+          db: "",
+          maxLength: 0
+        })),
+        records: names.map((name2, seq) => [seq, name2, ""]),
+        affectedRows: 0,
+        insertId: 0,
+        isResultQuery: true
+      };
+    }
+    const routed = routeStatement(sql2, (name2) => this.targets.has(name2) || name2.includes("/"));
+    const text = routed.sql;
+    if (TRANSACTION.test(text)) {
+      throw new DoError(
+        "Durable Object storage does not take transaction statements over this API; every request auto-commits."
+      );
+    }
+    const name = routed.target ?? database;
+    if (!name) {
+      throw new DoError(
+        'No Durable Object selected. Pick one in the schema tree, or qualify the table as "<namespace>/<object>"."<table>".',
+        400
+      );
+    }
+    const target = this.targetFor(name);
+    if (DDL.test(text)) this.columns.clear();
+    const result = await this.transport.run(target, text);
+    const columns = result.columns ?? [];
+    const records = result.rows ?? [];
+    if (columns.length === 0 && !RESULT_KIND2.test(text)) {
+      return {
+        fields: [],
+        records: [],
+        affectedRows: result.meta?.rows_written ?? 0,
+        insertId: 0,
+        isResultQuery: false
+      };
+    }
+    const source = RESULT_KIND2.test(text) ? singleSourceTable3(text) : null;
+    const known = source ? await this.tableColumns(name, target, source) : null;
+    const fields = columns.map((column, index) => {
+      const fromTable = known?.has(column) ?? false;
+      const type = (fromTable ? known?.get(column) : null) ?? inferTypeFromValue3(firstNonNull3(records, index));
+      return {
+        name: column,
+        orgName: column,
+        type,
+        table: fromTable && source ? source : "",
+        orgTable: fromTable && source ? source : "",
+        db: fromTable ? name : "",
+        maxLength: 0
+      };
+    });
+    return { fields, records, affectedRows: 0, insertId: 0, isResultQuery: true };
+  }
+  async close() {
+    this.targets.clear();
+    this.columns.clear();
+  }
+};
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "::1", "0.0.0.0"]);
+function parseDevUrl(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`Not a valid URL: ${raw}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("devUrl must be an http(s) URL");
+  }
+  if (!LOOPBACK.has(url.hostname.toLowerCase())) {
+    throw new Error(
+      "devUrl must point at a wrangler dev server on this machine (localhost). Use the deployed Durable Objects connection for objects that are not local."
+    );
+  }
+  return url.origin;
+}
+var doDriverFactory = {
+  async open(config) {
+    const driver = new DoDriver("do", new LocalTransport(config.devUrl));
+    await driver.query("PRAGMA database_list");
+    return driver;
+  },
+  async test(config) {
+    await new DoDriver("do", new LocalTransport(config.devUrl)).query("PRAGMA database_list");
+  },
+  parseConfig(body) {
+    const devUrl = typeof body.devUrl === "string" ? body.devUrl.trim() : "";
+    if (!devUrl) throw new Error("devUrl is required");
+    return { driver: "do", devUrl: parseDevUrl(devUrl) };
+  }
+};
+var doRemoteDriverFactory = {
+  async open(config) {
+    const driver = new DoDriver("do-remote", new RemoteTransport(config));
+    await driver.query("PRAGMA database_list");
+    return driver;
+  },
+  async test(config) {
+    await new DoDriver("do-remote", new RemoteTransport(config)).query("PRAGMA database_list");
+  },
+  parseConfig(body) {
+    const accountId = typeof body.accountId === "string" ? body.accountId.trim() : "";
+    const apiToken = typeof body.apiToken === "string" ? body.apiToken.trim() : "";
+    const namespaceId = typeof body.namespaceId === "string" ? body.namespaceId.trim() : "";
+    if (!accountId || !apiToken) throw new Error("accountId and apiToken are required");
+    return { driver: "do-remote", accountId, apiToken, ...namespaceId ? { namespaceId } : {} };
+  }
+};
+
 // src/ssh-tunnel.ts
 import { createServer } from "net";
 import { mkdir, readFile as readFile2, appendFile } from "fs/promises";
@@ -1551,23 +2013,28 @@ var factories = {
   sqlite: sqliteDriverFactory,
   mssql: mssqlDriverFactory,
   oracle: oracleDriverFactory,
-  d1: d1DriverFactory
+  d1: d1DriverFactory,
+  do: doDriverFactory,
+  "do-remote": doRemoteDriverFactory
 };
 function isDriverType(value) {
   return typeof value === "string" && value in factories;
 }
+function isDirectDriver(config) {
+  return config.driver === "sqlite" || config.driver === "d1" || config.driver === "do" || config.driver === "do-remote";
+}
 function parseDriverConfig(body) {
   const driver = body.driver ?? "mysql";
   if (!isDriverType(driver)) {
     throw new Error(`Unsupported driver: ${String(driver)}`);
   }
   const config = factories[driver].parseConfig(body);
-  if (config.driver === "sqlite" || config.driver === "d1") return config;
+  if (isDirectDriver(config)) return config;
   const ssh = parseSshConfig(body.ssh);
   return ssh ? { ...config, ssh } : config;
 }
 async function withTunnel(config, run) {
-  if (config.driver === "sqlite" || config.driver === "d1" || !config.ssh) return run(config, void 0);
+  if (isDirectDriver(config) || !config.ssh) return run(config, void 0);
   const tunnel = await openSshTunnel(config.ssh, { host: config.host, port: config.port });
   recordUsage("ssh_tunnel");
   try {
@@ -1595,7 +2062,7 @@ function tunneled(driver, tunnel, label) {
 function openDriver(config) {
   return withTunnel(config, async (direct, tunnel) => {
     const driver = await openDirect(direct);
-    if (!tunnel || config.driver === "sqlite" || config.driver === "d1" || !config.ssh) return driver;
+    if (!tunnel || isDirectDriver(config) || !config.ssh) return driver;
     const label = `${config.user}@${config.host}:${config.port} via ssh ${config.ssh.user}@${config.ssh.host}:${config.ssh.port}`;
     return tunneled(driver, tunnel, label);
   });
@@ -1623,6 +2090,10 @@ function openDirect(config) {
       return factories.oracle.open(config);
     case "d1":
       return factories.d1.open(config);
+    case "do":
+      return factories.do.open(config);
+    case "do-remote":
+      return factories["do-remote"].open(config);
   }
 }
 function testDirect(config) {
@@ -1639,6 +2110,10 @@ function testDirect(config) {
       return factories.oracle.test(config);
     case "d1":
       return factories.d1.test(config);
+    case "do":
+      return factories.do.test(config);
+    case "do-remote":
+      return factories["do-remote"].test(config);
   }
 }
 
@@ -1886,7 +2361,7 @@ async function updateNotice(current) {
 
 // src/server.ts
 import express from "express";
-import { createHash as createHash2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { createHash as createHash2, randomUUID as randomUUID2, timingSafeEqual as timingSafeEqual2 } from "crypto";
 
 // src/tunneling.ts
 import { randomUUID } from "crypto";
@@ -2253,7 +2728,9 @@ function createAgent(options) {
   const allowedOrigins = new Set(options.allowedOrigins.map((o) => o.replace(/\/+$/, "")));
   const allowedHosts = options.allowedHosts ? new Set(options.allowedHosts.map((h) => h.toLowerCase())) : null;
   const throttle = new AuthThrottle();
+  const pairThrottle = new AuthThrottle();
   let pairing = options.pairingCode;
+  let lastPairOffer = 0;
   app.set("env", "production");
   app.disable("x-powered-by");
   app.disable("etag");
@@ -2288,6 +2765,19 @@ function createAgent(options) {
   });
   app.use(accessControl(allowedOrigins));
   if (options.appDir) serveApp(app, options.appDir);
+  const PAIR_OFFER_INTERVAL_MS = 6e4;
+  function offerPairing(req) {
+    if (!options.onUnpaired) return false;
+    const origin = req.headers.origin;
+    if (typeof origin !== "string" || !allowedOrigins.has(origin.replace(/\/+$/, ""))) return false;
+    const now = Date.now();
+    if (pairing && now <= pairing.expiresAt) return false;
+    if (now - lastPairOffer < PAIR_OFFER_INTERVAL_MS) return false;
+    lastPairOffer = now;
+    pairing = { code: randomUUID2(), expiresAt: now + 10 * 60 * 1e3 };
+    options.onUnpaired(pairing, origin);
+    return true;
+  }
   app.get("/health", (req, res) => {
     const body = {
       success: true,
@@ -2300,23 +2790,21 @@ function createAgent(options) {
     if (options.install) body.install = options.install;
     if (options.gateway) body.gateway = { name: options.gateway.name, profiles: options.gateway.profiles.length };
     if (req.headers.authorization !== void 0) {
-      if (throttle.locked(peerOf(req))) {
-        fail(res, 429, "Too many failed authentication attempts; try again shortly");
-        return;
-      }
       body.authorized = authorized(req);
     }
+    if (body.authorized !== true) void offerPairing(req);
     res.json(body);
   });
   app.post("/pair", express.json({ limit: "1kb" }), (req, res) => {
-    if (throttle.locked(peerOf(req))) {
-      fail(res, 429, "Too many failed authentication attempts; try again shortly");
+    if (pairThrottle.locked(peerOf(req))) {
+      fail(res, 429, "Too many failed pairing attempts; try again shortly");
       return;
     }
     const code = typeof req.body?.code === "string" ? req.body.code : "";
     if (!pairing || Date.now() > pairing.expiresAt || !code || !secretEquals(code, pairing.code)) {
-      throttle.fail(peerOf(req));
-      fail(res, 401, "Pairing code is invalid or has expired; restart the agent for a new link");
+      pairThrottle.fail(peerOf(req));
+      const printed = offerPairing(req);
+      fail(res, 401, printed ? "Pairing code is invalid or has expired; a fresh link has been printed in the agent's terminal" : "Pairing code is invalid or has expired; open the pairing link shown in the agent's terminal");
       return;
     }
     pairing = void 0;
@@ -2633,7 +3121,7 @@ async function main() {
   const port = Number(flags.port ?? process.env.PLANCHE_PORT) || 8888;
   const addr = flags.addr ?? process.env.PLANCHE_ADDR ?? "127.0.0.1";
   const tokenFromEnv = !flags.token && !!process.env.PLANCHE_AUTH_TOKEN;
-  const authToken = flags.token ?? process.env.PLANCHE_AUTH_TOKEN ?? randomUUID2();
+  const authToken = flags.token ?? process.env.PLANCHE_AUTH_TOKEN ?? randomUUID3();
   const gatewayFile = flags.gateway ?? process.env.PLANCHE_GATEWAY;
   let gateway;
   if (gatewayFile) {
@@ -2684,9 +3172,11 @@ async function main() {
   const devApp = LOOPBACK_ADDRS.has(new URL(appUrl).hostname);
   const allowedOrigins = [appOrigin, ...devApp ? DEV_ORIGINS : [], ...extraOrigins];
   if (serveApp2) allowedOrigins.push(`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`);
-  const pairingCode = { code: randomUUID2(), expiresAt: Date.now() + 10 * 60 * 1e3 };
+  const pairingCode = { code: randomUUID3(), expiresAt: Date.now() + 10 * 60 * 1e3 };
   const listenAddr = addr.replace(/^\[(.*)\]$/, "$1");
   const agentUrl = `http://${listenAddr.includes(":") ? `[${listenAddr}]` : listenAddr}:${port}`;
+  const divider = "-".repeat(72);
+  const pairLink = (code, appBase) => serveApp2 ? `${appBase}/#pair=${encodeURIComponent(code)}` : `${appBase}/#agent=${encodeURIComponent(agentUrl)}&pair=${encodeURIComponent(code)}`;
   const { app, manager } = createAgent({
     authToken,
     allowedOrigins,
@@ -2698,17 +3188,30 @@ async function main() {
     allowedHosts: loopback ? ["127.0.0.1", "localhost", "[::1]", `127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`] : void 0,
     pairingCode,
     gateway,
-    appDir
+    appDir,
+    // An app that cannot authenticate gets a fresh link on this terminal
+    // rather than needing the agent restarted. The link is built from the
+    // origin the request came from, so it points at the app that is really
+    // running — a dev server bumped to another port included.
+    onUnpaired: (fresh, appOrigin2) => {
+      const url = pairLink(fresh.code, serveApp2 ? publicUrl || appOrigin2 : appOrigin2);
+      console.log(divider);
+      console.log(`The app at ${appOrigin2} is not paired with this agent.`);
+      console.log(`Pair it with (valid for 10 minutes, single use):
+
+  ${url}
+`);
+      console.log(divider);
+    }
   });
-  const pairUrl = serveApp2 ? `${publicUrl || agentUrl}/#pair=${encodeURIComponent(pairingCode.code)}` : `${appUrl}/#agent=${encodeURIComponent(agentUrl)}&pair=${encodeURIComponent(pairingCode.code)}`;
+  const pairUrl = pairLink(pairingCode.code, serveApp2 ? publicUrl || agentUrl : appUrl);
   if (offlineFallback) {
     console.log(`${DEFAULT_APP_URL === hostedAppUrl ? "planche.dev" : hostedAppUrl} is unreachable \u2014 serving the app bundled with this agent (v${VERSION}) instead.`);
   }
   const server = app.listen(port, listenAddr, () => {
-    const line = "-".repeat(72);
-    console.log(line);
+    console.log(divider);
     console.log(`Planche agent ${VERSION} listening on ${agentUrl}`);
-    console.log(line);
+    console.log(divider);
     console.log(`Open the app with (link valid for 10 minutes, single use):
 
   ${pairUrl}
@@ -2719,7 +3222,7 @@ async function main() {
     if (!loopback) {
       console.error(`WARNING: bound to ${addr} without TLS \u2014 anyone who can reach this port and knows the token can use your databases, and anyone on the path can read the traffic.`);
     }
-    console.log(line);
+    console.log(divider);
     if (shouldOpen) openInBrowser(pairUrl);
     void updateNotice(VERSION).then((notice) => {
       if (notice) console.log(notice);