workerdeck 0.13.0 → 0.16.0

package/README.md

@@ -30,6 +30,10 @@ The cookie is not a convenience. A browser cannot set a header on a WebSocket ha
 a cookie is the only credential a tab can present when it attaches to a session — and a cookie only
 rides requests to the origin that set it. That is why the dashboard and the API share a port.
 
+Those logins persist in `<state-dir>/auth-sessions.json` (mode 600), so a restart doesn't sign
+every open tab out. Each row is an HMAC of the cookie under the operator secret — so the file is
+worth nothing on its own, and rotating the secret invalidates every outstanding login.
+
 Neither transport authenticates *who* the person is; the secret is a door key. Put an
 identity-aware proxy in front if you need more than that.
 
@@ -105,3 +109,17 @@ a normal dependency of this package. Point `webRoot` in the config file at your
 a fork instead.
 
 MIT
+
+## Rules you cannot infer from the types
+
+- **Single origin is load-bearing.** The gateway and the dashboard share one port because a tab
+  cannot header a WebSocket handshake, so a cookie is the only credential an attach can carry —
+  and cookies are per-origin. This is why there is no "dashboard on another port" mode.
+- **Loopback runs keyless; off loopback the CLI generates a key rather than serving open.** Only an
+  explicit `--insecure` / `insecureHosts` declaration serves unauthenticated, and those entries
+  double as accepted `Host` headers.
+- **Browser logins are keyed by `HMAC(secret, token)`.** That is what makes the session file
+  worthless to a reader — and what makes rotating the auth key invalidate every cookie for free.
+- **A config file supplying its own `authenticate` turns the built-in auth off entirely**, rather
+  than layering on top of it. Two auth systems agreeing is harder to reason about than one.
+

package/build/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as ConfigError, d as parseArgs, f as resolveInstanceConfig, r as startInstance, u as loadConfigFile } from "./instance-CS-1IaTm.mjs";
+import { a as ConfigError, d as parseArgs, f as resolveInstanceConfig, r as startInstance, u as loadConfigFile } from "./instance-CJkPdp34.mjs";
 import { dirname, join } from "node:path";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
@@ -99,7 +99,7 @@ function openInBrowser(url) {
 }
 async function main(argv) {
 	if (argv[0] === "guard") {
-		const { runGuard } = await import("./guard-D3VN855w.mjs").then((n) => n.t);
+		const { runGuard } = await import("./guard-DkovUj7o.mjs").then((n) => n.t);
 		return await runGuard(argv.slice(1));
 	}
 	const flags = parseArgs(argv);

package/build/cli.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { spawn } from 'node:child_process'\nimport { readFile } from 'node:fs/promises'\nimport { dirname, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { ConfigError, loadConfigFile, parseArgs, resolveInstanceConfig } from './config.ts'\nimport { startInstance } from './instance.ts'\n\nconst HELP = `workerdeck — run a workerdeck instance: session gateway + dashboard, one port.\n\nUsage\n  workerdeck [options]\n  workerdeck guard [options]     check whether it is safe to restart an instance\n\nOptions\n  -p, --port <n>            port to listen on (default 8787, WORKERDECK_PORT)\n      --host <addr>         interface to bind (default 127.0.0.1, WORKERDECK_HOST)\n      --auth-key <secret>   shared secret, min 12 chars; browsers log in with it,\n                            services send it as x-workerdeck-key\n                            (WORKERDECK_AUTH_KEY). Unset = no auth on loopback;\n                            on any other interface a key is generated instead,\n                            printed once, and stored in <state-dir>/auth-key for\n                            later starts to reuse.\n      --trust-proxy         trust x-forwarded-proto/-host/-for from one reverse\n                            proxy. Required behind TLS termination, or the session\n                            cookie loses its Secure flag and the origin check\n                            computes http:// where the browser says https://.\n      --allowed-origin <o>  extra origin accepted on browser requests, for when a\n                            proxy rewrites Host (repeatable)\n      --allowed-host <name> extra Host header accepted when running without auth\n                            (repeatable; loopback names are always accepted)\n      --insecure-host <name>\n                            bind host that may serve without auth — no key demanded,\n                            none generated — and, while unauthenticated, also\n                            accepted as a Host header (repeatable; config:\n                            insecureHosts). Names the host alone, no port.\n      --profile <name=dir>  Claude config dir a session may run under (repeatable)\n      --cwd-root <path>     restrict session cwds to this root (repeatable,\n                            WORKERDECK_CWD_ROOTS as a ':'-separated list)\n      --fs-root <path>      narrow which host directories /v1/fs serves\n                            (repeatable, WORKERDECK_FS_ROOTS as a ':'-separated\n                            list). Reading otherwise follows --cwd-root: a caller\n                            who may start a session in a tree can already read it\n                            through the agent. With neither, the routes 404.\n      --fs-write            also accept writes over /v1/fs. Its own switch because\n                            an agent's writes go through the permission flow and a\n                            PUT does not. Every write is still conditional on the\n                            hash the client last read.\n      --state-dir <path>    where parked sessions are persisted\n                            (default: beside the config file, else ~/.workerdeck)\n      --no-parking-store    keep parked sessions in memory only; a restart drops them\n  -c, --config <path>       config file (default: ./workerdeck.config.mjs)\n      --insecure            allow no-auth on a non-loopback address. Only when\n                            something in front is doing the authenticating.\n      --cors-origin <o>     browser origin allowed to call /v1 cross-origin, for a\n                            dashboard served elsewhere (repeatable, exact origin, no\n                            wildcard; config: corsOrigins). Refused without auth. The\n                            key is still required — this only permits the call.\n      --no-web              don't serve the web dashboard (config: web: false).\n                            /v1 and the auth routes are unchanged; everything else\n                            404s. For a gateway reached only from the VS Code\n                            extension, the phone, or another host's dashboard.\n      --open                open the dashboard in a browser once it is up\n  -h, --help                show this\n  -v, --version             print the version\n\nConfig file\n  Options that cannot fit on a command line — \\`authenticate\\`, \\`buildRunnerConfig\\`,\n  \\`createEngineRunner\\` are functions — live in workerdeck.config.mjs, which\n  default-exports the createWorkerServer options (or a function returning them).\n  Flags and env override it. Supplying your own \\`authenticate\\` turns the built-in\n  shared-secret auth off entirely.\n\nCredentials\n  workerdeck implements no Anthropic auth of its own: the official SDK/CLI\n  resolves credentials from the environment, per profile. --auth-key protects this\n  gateway, nothing else.\n`\n\nasync function readVersion(): Promise<string> {\n  // src/cli.ts and build/cli.mjs are both one level under the package root.\n  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')\n  try {\n    const raw = await readFile(pkgPath, 'utf8')\n    return (JSON.parse(raw) as { version?: string }).version ?? 'unknown'\n  } catch {\n    return 'unknown'\n  }\n}\n\n/** Best-effort: a browser that won't open is a convenience missed, not a failure. */\nfunction openInBrowser(url: string): void {\n  const command =\n    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'\n  try {\n    const child = spawn(command, [url], {\n      stdio: 'ignore',\n      detached: true,\n      shell: process.platform === 'win32',\n    })\n    child.on('error', () => {})\n    child.unref()\n  } catch {\n    // ignored\n  }\n}\n\nasync function main(argv: string[]): Promise<number> {\n  if (argv[0] === 'guard') {\n    const { runGuard } = await import('./guard.ts')\n    return await runGuard(argv.slice(1))\n  }\n\n  const flags = parseArgs(argv)\n  if (flags.help) {\n    process.stdout.write(HELP)\n    return 0\n  }\n  if (flags.version) {\n    process.stdout.write(`${await readVersion()}\\n`)\n    return 0\n  }\n\n  const loaded = await loadConfigFile(flags.config)\n  const config = resolveInstanceConfig(flags, loaded)\n  const instance = await startInstance(config)\n\n  if (config.open) openInBrowser(instance.url)\n\n  const shutdown = (signal: string): void => {\n    process.stdout.write(`\\n[workerdeck] ${signal} — shutting down\\n`)\n    // Parked sessions are already on disk; this is about letting in-flight\n    // requests finish rather than dropping sockets on the floor.\n    instance\n      .close()\n      .then(() => process.exit(0))\n      .catch(() => process.exit(1))\n  }\n  process.on('SIGINT', () => shutdown('SIGINT'))\n  process.on('SIGTERM', () => shutdown('SIGTERM'))\n\n  // Resolves only on close; the process stays up serving.\n  await instance.closed\n  return 0\n}\n\nmain(process.argv.slice(2))\n  .then((code) => {\n    if (code !== 0) process.exit(code)\n  })\n  .catch((error: unknown) => {\n    if (error instanceof ConfigError) {\n      process.stderr.write(`[workerdeck] ${error.message}\\n`)\n      process.exit(2)\n    }\n    process.stderr.write(\n      `[workerdeck] ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\\n`,\n    )\n    process.exit(1)\n  })\n"],"mappings":";;;;;;;AAQA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEb,eAAe,cAA+B;CAE5C,MAAM,UAAU,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,MAAM,eAAe;AACnF,KAAI;EACF,MAAM,MAAM,MAAM,SAAS,SAAS,OAAO;AAC3C,SAAQ,KAAK,MAAM,IAAI,CAA0B,WAAW;SACtD;AACN,SAAO;;;;AAKX,SAAS,cAAc,KAAmB;CACxC,MAAM,UACJ,QAAQ,aAAa,WAAW,SAAS,QAAQ,aAAa,UAAU,UAAU;AACpF,KAAI;EACF,MAAM,QAAQ,MAAM,SAAS,CAAC,IAAI,EAAE;GAClC,OAAO;GACP,UAAU;GACV,OAAO,QAAQ,aAAa;GAC7B,CAAC;AACF,QAAM,GAAG,eAAe,GAAG;AAC3B,QAAM,OAAO;SACP;;AAKV,eAAe,KAAK,MAAiC;AACnD,KAAI,KAAK,OAAO,SAAS;EACvB,MAAM,EAAE,aAAa,MAAM,OAAO,wBAAA,MAAA,MAAA,EAAA,EAAA;AAClC,SAAO,MAAM,SAAS,KAAK,MAAM,EAAE,CAAC;;CAGtC,MAAM,QAAQ,UAAU,KAAK;AAC7B,KAAI,MAAM,MAAM;AACd,UAAQ,OAAO,MAAM,KAAK;AAC1B,SAAO;;AAET,KAAI,MAAM,SAAS;AACjB,UAAQ,OAAO,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI;AAChD,SAAO;;CAIT,MAAM,SAAS,sBAAsB,OAAO,MADvB,eAAe,MAAM,OAAO,CACE;CACnD,MAAM,WAAW,MAAM,cAAc,OAAO;AAE5C,KAAI,OAAO,KAAM,eAAc,SAAS,IAAI;CAE5C,MAAM,YAAY,WAAyB;AACzC,UAAQ,OAAO,MAAM,kBAAkB,OAAO,oBAAoB;AAGlE,WACG,OAAO,CACP,WAAW,QAAQ,KAAK,EAAE,CAAC,CAC3B,YAAY,QAAQ,KAAK,EAAE,CAAC;;AAEjC,SAAQ,GAAG,gBAAgB,SAAS,SAAS,CAAC;AAC9C,SAAQ,GAAG,iBAAiB,SAAS,UAAU,CAAC;AAGhD,OAAM,SAAS;AACf,QAAO;;AAGT,KAAK,QAAQ,KAAK,MAAM,EAAE,CAAC,CACxB,MAAM,SAAS;AACd,KAAI,SAAS,EAAG,SAAQ,KAAK,KAAK;EAClC,CACD,OAAO,UAAmB;AACzB,KAAI,iBAAiB,aAAa;AAChC,UAAQ,OAAO,MAAM,gBAAgB,MAAM,QAAQ,IAAI;AACvD,UAAQ,KAAK,EAAE;;AAEjB,SAAQ,OAAO,MACb,gBAAgB,iBAAiB,QAAS,MAAM,SAAS,MAAM,UAAW,OAAO,MAAM,CAAC,IACzF;AACD,SAAQ,KAAK,EAAE;EACf"}
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { spawn } from 'node:child_process'\nimport { readFile } from 'node:fs/promises'\nimport { dirname, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { ConfigError, loadConfigFile, parseArgs, resolveInstanceConfig } from './config.ts'\nimport { startInstance } from './lib/instance.ts'\n\nconst HELP = `workerdeck — run a workerdeck instance: session gateway + dashboard, one port.\n\nUsage\n  workerdeck [options]\n  workerdeck guard [options]     check whether it is safe to restart an instance\n\nOptions\n  -p, --port <n>            port to listen on (default 8787, WORKERDECK_PORT)\n      --host <addr>         interface to bind (default 127.0.0.1, WORKERDECK_HOST)\n      --auth-key <secret>   shared secret, min 12 chars; browsers log in with it,\n                            services send it as x-workerdeck-key\n                            (WORKERDECK_AUTH_KEY). Unset = no auth on loopback;\n                            on any other interface a key is generated instead,\n                            printed once, and stored in <state-dir>/auth-key for\n                            later starts to reuse.\n      --trust-proxy         trust x-forwarded-proto/-host/-for from one reverse\n                            proxy. Required behind TLS termination, or the session\n                            cookie loses its Secure flag and the origin check\n                            computes http:// where the browser says https://.\n      --allowed-origin <o>  extra origin accepted on browser requests, for when a\n                            proxy rewrites Host (repeatable)\n      --allowed-host <name> extra Host header accepted when running without auth\n                            (repeatable; loopback names are always accepted)\n      --insecure-host <name>\n                            bind host that may serve without auth — no key demanded,\n                            none generated — and, while unauthenticated, also\n                            accepted as a Host header (repeatable; config:\n                            insecureHosts). Names the host alone, no port.\n      --profile <name=dir>  Claude config dir a session may run under (repeatable)\n      --cwd-root <path>     restrict session cwds to this root (repeatable,\n                            WORKERDECK_CWD_ROOTS as a ':'-separated list)\n      --fs-root <path>      narrow which host directories /v1/fs serves\n                            (repeatable, WORKERDECK_FS_ROOTS as a ':'-separated\n                            list). Reading otherwise follows --cwd-root: a caller\n                            who may start a session in a tree can already read it\n                            through the agent. With neither, the routes 404.\n      --fs-write            also accept writes over /v1/fs. Its own switch because\n                            an agent's writes go through the permission flow and a\n                            PUT does not. Every write is still conditional on the\n                            hash the client last read.\n      --state-dir <path>    where parked sessions are persisted\n                            (default: beside the config file, else ~/.workerdeck)\n      --no-parking-store    keep parked sessions in memory only; a restart drops them\n  -c, --config <path>       config file (default: ./workerdeck.config.mjs)\n      --insecure            allow no-auth on a non-loopback address. Only when\n                            something in front is doing the authenticating.\n      --cors-origin <o>     browser origin allowed to call /v1 cross-origin, for a\n                            dashboard served elsewhere (repeatable, exact origin, no\n                            wildcard; config: corsOrigins). Refused without auth. The\n                            key is still required — this only permits the call.\n      --no-web              don't serve the web dashboard (config: web: false).\n                            /v1 and the auth routes are unchanged; everything else\n                            404s. For a gateway reached only from the VS Code\n                            extension, the phone, or another host's dashboard.\n      --open                open the dashboard in a browser once it is up\n  -h, --help                show this\n  -v, --version             print the version\n\nConfig file\n  Options that cannot fit on a command line — \\`authenticate\\`, \\`buildRunnerConfig\\`,\n  \\`createEngineRunner\\` are functions — live in workerdeck.config.mjs, which\n  default-exports the createWorkerServer options (or a function returning them).\n  Flags and env override it. Supplying your own \\`authenticate\\` turns the built-in\n  shared-secret auth off entirely.\n\nCredentials\n  workerdeck implements no Anthropic auth of its own: the official SDK/CLI\n  resolves credentials from the environment, per profile. --auth-key protects this\n  gateway, nothing else.\n`\n\nasync function readVersion(): Promise<string> {\n  // src/cli.ts and build/cli.mjs are both one level under the package root.\n  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')\n  try {\n    const raw = await readFile(pkgPath, 'utf8')\n    return (JSON.parse(raw) as { version?: string }).version ?? 'unknown'\n  } catch {\n    return 'unknown'\n  }\n}\n\n/** Best-effort: a browser that won't open is a convenience missed, not a failure. */\nfunction openInBrowser(url: string): void {\n  const command =\n    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'\n  try {\n    const child = spawn(command, [url], {\n      stdio: 'ignore',\n      detached: true,\n      shell: process.platform === 'win32',\n    })\n    child.on('error', () => {})\n    child.unref()\n  } catch {\n    // ignored\n  }\n}\n\nasync function main(argv: string[]): Promise<number> {\n  if (argv[0] === 'guard') {\n    const { runGuard } = await import('./lib/guard.ts')\n    return await runGuard(argv.slice(1))\n  }\n\n  const flags = parseArgs(argv)\n  if (flags.help) {\n    process.stdout.write(HELP)\n    return 0\n  }\n  if (flags.version) {\n    process.stdout.write(`${await readVersion()}\\n`)\n    return 0\n  }\n\n  const loaded = await loadConfigFile(flags.config)\n  const config = resolveInstanceConfig(flags, loaded)\n  const instance = await startInstance(config)\n\n  if (config.open) openInBrowser(instance.url)\n\n  const shutdown = (signal: string): void => {\n    process.stdout.write(`\\n[workerdeck] ${signal} — shutting down\\n`)\n    // Parked sessions are already on disk; this is about letting in-flight\n    // requests finish rather than dropping sockets on the floor.\n    instance\n      .close()\n      .then(() => process.exit(0))\n      .catch(() => process.exit(1))\n  }\n  process.on('SIGINT', () => shutdown('SIGINT'))\n  process.on('SIGTERM', () => shutdown('SIGTERM'))\n\n  // Resolves only on close; the process stays up serving.\n  await instance.closed\n  return 0\n}\n\nmain(process.argv.slice(2))\n  .then((code) => {\n    if (code !== 0) process.exit(code)\n  })\n  .catch((error: unknown) => {\n    if (error instanceof ConfigError) {\n      process.stderr.write(`[workerdeck] ${error.message}\\n`)\n      process.exit(2)\n    }\n    process.stderr.write(\n      `[workerdeck] ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\\n`,\n    )\n    process.exit(1)\n  })\n"],"mappings":";;;;;;;AAQA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEb,eAAe,cAA+B;CAE5C,MAAM,UAAU,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,MAAM,eAAe;AACnF,KAAI;EACF,MAAM,MAAM,MAAM,SAAS,SAAS,OAAO;AAC3C,SAAQ,KAAK,MAAM,IAAI,CAA0B,WAAW;SACtD;AACN,SAAO;;;;AAKX,SAAS,cAAc,KAAmB;CACxC,MAAM,UACJ,QAAQ,aAAa,WAAW,SAAS,QAAQ,aAAa,UAAU,UAAU;AACpF,KAAI;EACF,MAAM,QAAQ,MAAM,SAAS,CAAC,IAAI,EAAE;GAClC,OAAO;GACP,UAAU;GACV,OAAO,QAAQ,aAAa;GAC7B,CAAC;AACF,QAAM,GAAG,eAAe,GAAG;AAC3B,QAAM,OAAO;SACP;;AAKV,eAAe,KAAK,MAAiC;AACnD,KAAI,KAAK,OAAO,SAAS;EACvB,MAAM,EAAE,aAAa,MAAM,OAAO,wBAAA,MAAA,MAAA,EAAA,EAAA;AAClC,SAAO,MAAM,SAAS,KAAK,MAAM,EAAE,CAAC;;CAGtC,MAAM,QAAQ,UAAU,KAAK;AAC7B,KAAI,MAAM,MAAM;AACd,UAAQ,OAAO,MAAM,KAAK;AAC1B,SAAO;;AAET,KAAI,MAAM,SAAS;AACjB,UAAQ,OAAO,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI;AAChD,SAAO;;CAIT,MAAM,SAAS,sBAAsB,OAAO,MADvB,eAAe,MAAM,OAAO,CACE;CACnD,MAAM,WAAW,MAAM,cAAc,OAAO;AAE5C,KAAI,OAAO,KAAM,eAAc,SAAS,IAAI;CAE5C,MAAM,YAAY,WAAyB;AACzC,UAAQ,OAAO,MAAM,kBAAkB,OAAO,oBAAoB;AAGlE,WACG,OAAO,CACP,WAAW,QAAQ,KAAK,EAAE,CAAC,CAC3B,YAAY,QAAQ,KAAK,EAAE,CAAC;;AAEjC,SAAQ,GAAG,gBAAgB,SAAS,SAAS,CAAC;AAC9C,SAAQ,GAAG,iBAAiB,SAAS,UAAU,CAAC;AAGhD,OAAM,SAAS;AACf,QAAO;;AAGT,KAAK,QAAQ,KAAK,MAAM,EAAE,CAAC,CACxB,MAAM,SAAS;AACd,KAAI,SAAS,EAAG,SAAQ,KAAK,KAAK;EAClC,CACD,OAAO,UAAmB;AACzB,KAAI,iBAAiB,aAAa;AAChC,UAAQ,OAAO,MAAM,gBAAgB,MAAM,QAAQ,IAAI;AACvD,UAAQ,KAAK,EAAE;;AAEjB,SAAQ,OAAO,MACb,gBAAgB,iBAAiB,QAAS,MAAM,SAAS,MAAM,UAAW,OAAO,MAAM,CAAC,IACzF;AACD,SAAQ,KAAK,EAAE;EACf"}

package/build/{guard-D3VN855w.mjs → guard-DkovUj7o.mjs}

@@ -11,7 +11,7 @@ var __exportAll = (all, no_symbols) => {
 	return target;
 };
 //#endregion
-//#region src/guard.ts
+//#region src/lib/guard.ts
 var guard_exports = /* @__PURE__ */ __exportAll({ runGuard: () => runGuard });
 /**
 * Restart guard for a deploy: ask a running instance whether anything would be
@@ -238,4 +238,4 @@ async function runGuard(argv) {
 //#endregion
 export { runGuard as n, guard_exports as t };
 
-//# sourceMappingURL=guard-D3VN855w.mjs.map
+//# sourceMappingURL=guard-DkovUj7o.mjs.map

package/build/guard-DkovUj7o.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-DkovUj7o.mjs","names":[],"sources":["../src/lib/guard.ts"],"sourcesContent":["import { parseArgs } from 'node:util'\n\n/**\n * Restart guard for a deploy: ask a running instance whether anything would be\n * lost by stopping it, and exit non-zero while the answer is yes.\n *\n *   workerdeck guard --wait 300 --allow-parked && launchctl kickstart -k …\n *\n * What a restart costs, and why this is policy and not a server route: an\n * in-flight turn dies with the process (the CLI subprocess and the provider\n * request both go), a pending permission request dies with it, and a running job\n * is left claimed. Two more depend on configuration rather than on state, so each\n * has an opt-out flag that says \"I made that durable\":\n *\n *   --allow-parked   parked sessions survive with a durable SessionStore, not\n *                    with the in-memory default. Note this covers the *session*:\n *                    a parked job's queue-side record lives in the QueueAdapter,\n *                    so with the bundled in-memory adapter the woken session\n *                    completes with no job attached to finish.\n *   --allow-queued   queued jobs survive only in a durable QueueAdapter; the\n *                    bundled one loses them with the process.\n *\n * Exit codes: 0 safe to restart, 1 still busy, 2 could not tell (bad URL, auth,\n * or an unexpected response — never treated as safe).\n */\n\nconst BUSY_STATUSES = new Set(['starting', 'running', 'awaiting_approval'])\n\nconst HELP = `usage: workerdeck guard [--url URL] [--token TOKEN] [--header name=value]\n                           [--wait SECONDS] [--interval SECONDS]\n                           [--allow-parked] [--allow-queued] [--json]\n\nexit 0 = safe to restart, 1 = busy, 2 = could not tell\n`\n\ntype GetResult =\n  | { ok: true; body: Record<string, unknown> }\n  | { ok: false; status: 'unreachable' }\n  | { ok: false; code?: number; detail: string }\n\ntype Verdict = {\n  reasons: string[]\n  notes: string[]\n  unreachable?: boolean\n  error?: string\n  sessions?: number\n  parked?: number\n}\n\nclass GuardError extends Error {}\n\nexport async function runGuard(argv: string[]): Promise<number> {\n  let values: {\n    url: string\n    token?: string\n    header: string[]\n    wait: string\n    interval: string\n    'allow-parked': boolean\n    'allow-queued': boolean\n    json: boolean\n    help: boolean\n  }\n  try {\n    values = parseArgs({\n      args: argv,\n      options: {\n        url: {\n          type: 'string',\n          default: process.env.WORKERDECK_URL ?? 'http://127.0.0.1:8787/v1',\n        },\n        token: { type: 'string', default: process.env.WORKERDECK_TOKEN },\n        header: { type: 'string', multiple: true, default: [] },\n        wait: { type: 'string', default: '0' },\n        interval: { type: 'string', default: '5' },\n        'allow-parked': { type: 'boolean', default: false },\n        'allow-queued': { type: 'boolean', default: false },\n        json: { type: 'boolean', default: false },\n        help: { type: 'boolean', default: false },\n      },\n    }).values as typeof values\n  } catch (error) {\n    process.stderr.write(`guard: ${error instanceof Error ? error.message : String(error)}\\n`)\n    return 2\n  }\n\n  if (values.help) {\n    process.stdout.write(HELP)\n    return 0\n  }\n\n  const base = values.url.replace(/\\/$/, '')\n  const headers: Record<string, string> = { accept: 'application/json' }\n  // The token covers the common `Authorization: Bearer` case, including this\n  // CLI's own --auth-key; --header covers hosts whose `authenticate` hook reads\n  // something else.\n  if (values.token) headers.authorization = `Bearer ${values.token}`\n\n  const seconds = (flag: string, raw: string): number => {\n    const value = Number(raw)\n    if (!Number.isFinite(value) || value < 0) {\n      throw new GuardError(`${flag} must be a non-negative number of seconds`)\n    }\n    return value\n  }\n\n  let waitMs: number\n  let intervalMs: number\n  try {\n    for (const entry of values.header) {\n      const at = entry.indexOf('=')\n      if (at < 1) throw new GuardError(`--header must be name=value, got '${entry}'`)\n      headers[entry.slice(0, at).trim()] = entry.slice(at + 1).trim()\n    }\n    waitMs = seconds('--wait', values.wait) * 1000\n    intervalMs = Math.max(seconds('--interval', values.interval), 1) * 1000\n  } catch (error) {\n    process.stderr.write(`guard: ${error instanceof Error ? error.message : String(error)}\\n`)\n    return 2\n  }\n\n  const get = async (path: string): Promise<GetResult> => {\n    let res: Response\n    try {\n      res = await fetch(base + path, { headers })\n    } catch (error) {\n      // Nothing listening on the URL we were pointed at: there is no session to lose.\n      const code = (error as { cause?: { code?: string } })?.cause?.code\n      if (code === 'ECONNREFUSED') return { ok: false, status: 'unreachable' }\n      return { ok: false, detail: String(error instanceof Error ? error.message : error) }\n    }\n    if (!res.ok) return { ok: false, code: res.status, detail: `HTTP ${res.status}` }\n    try {\n      return { ok: true, body: (await res.json()) as Record<string, unknown> }\n    } catch {\n      return { ok: false, code: res.status, detail: 'response was not JSON' }\n    }\n  }\n\n  /** One look at the server. Returns the reasons a restart would cost something. */\n  const inspect = async (): Promise<Verdict> => {\n    const sessions = await get('/sessions')\n    if (!sessions.ok && 'status' in sessions) return { unreachable: true, reasons: [], notes: [] }\n    if (!sessions.ok) return { error: `GET ${base}/sessions → ${sessions.detail}`, reasons: [], notes: [] }\n    const listed = sessions.body.sessions\n    if (!Array.isArray(listed)) {\n      return { error: `GET ${base}/sessions returned no session list`, reasons: [], notes: [] }\n    }\n    const all = listed as { id: string; status: string }[]\n\n    const reasons: string[] = []\n    /** Worth saying out loud, but not worth blocking a deploy over. */\n    const notes: string[] = []\n    for (const session of all.filter((s) => BUSY_STATUSES.has(s.status))) {\n      reasons.push(`session ${session.id} is ${session.status}`)\n    }\n    const parked = all.filter((s) => s.status === 'parked')\n    if (parked.length > 0 && !values['allow-parked']) {\n      reasons.push(\n        `${parked.length} parked session(s) — pass --allow-parked once the server ` +\n          'runs a durable SessionStore, or they are lost on restart',\n      )\n    }\n\n    // A queue is optional: 404 here means this server declares none.\n    const queue = await get('/queue')\n    if (!queue.ok && !('status' in queue) && queue.code !== 404) {\n      return { error: `GET ${base}/queue → ${queue.detail}`, reasons: [], notes: [] }\n    }\n    const stats = queue.ok\n      ? (queue.body.stats as { running?: number; queued?: number; parked?: number } | undefined)\n      : undefined\n    if ((stats?.running ?? 0) > 0) reasons.push(`${stats!.running} job(s) running`)\n    if ((stats?.queued ?? 0) > 0 && !values['allow-queued']) {\n      reasons.push(\n        `${stats!.queued} job(s) queued — pass --allow-queued once the server runs a ` +\n          'durable QueueAdapter, or they are lost on restart',\n      )\n    }\n    if ((stats?.parked ?? 0) > 0 && values['allow-parked']) {\n      // Not a blocking reason: the operator has already said parks are durable.\n      // But session durability is not job durability, and only one of the two is theirs.\n      notes.push(\n        `${stats!.parked} parked job(s): their queue-side records are the QueueAdapter's, ` +\n          \"not the SessionStore's — with the in-memory adapter they never finish\",\n      )\n    }\n    return { reasons, notes, sessions: all.length, parked: parked.length }\n  }\n\n  const report = (verdict: string, detail: Verdict): void => {\n    if (values.json) {\n      process.stdout.write(`${JSON.stringify({ verdict, ...detail })}\\n`)\n      return\n    }\n    const lines = [\n      ...detail.reasons.map((reason) => `  - ${reason}`),\n      ...detail.notes.map((note) => `  note: ${note}`),\n    ].join('\\n')\n    process.stdout.write(`guard: ${verdict}${lines ? `\\n${lines}` : ''}\\n`)\n  }\n\n  const deadline = Date.now() + waitMs\n  for (;;) {\n    const result = await inspect()\n    if (result.error) {\n      report('unknown', { ...result, reasons: [result.error] })\n      return 2\n    }\n    if (result.unreachable) {\n      report('safe to restart (nothing listening on the given URL)', result)\n      return 0\n    }\n    if (result.reasons.length === 0) {\n      report('safe to restart', result)\n      return 0\n    }\n    if (Date.now() + intervalMs > deadline) {\n      report('busy — not safe to restart', result)\n      return 1\n    }\n    report(`busy, waiting up to ${Math.round((deadline - Date.now()) / 1000)}s`, result)\n    await new Promise((resolve) => setTimeout(resolve, intervalMs))\n  }\n}\n"],"mappings":"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"}

package/build/index.d.mts

@@ -69,7 +69,7 @@ options?: {
   hosts?: Record<ApnsEnvironment, string>;
 }): ApnsClient;
 //#endregion
-//#region src/auth.d.ts
+//#region src/auth/auth.d.ts
 /**
  * Gateway auth for the turnkey CLI: one shared operator secret, three transports.
  *
@@ -117,9 +117,9 @@ type CliAuthOptions = {
    * Browser session lifetime, default 7 days. Fixed, not sliding: the auth
    * hooks only see the request, so a renewed cookie has nowhere to ride — and
    * for a dashboard whose whole login is retyping one secret, a periodic
-   * re-login is cheaper than a refresh endpoint. Expiry (or a process restart —
-   * sessions are in-memory by design) simply lands the operator back on the
-   * login page.
+   * re-login is cheaper than a refresh endpoint. Expiry simply lands the
+   * operator back on the login page — as does a restart, unless a `sessions`
+   * store is supplied (the CLI supplies one whenever it has a state dir).
    */
   ttlMs?: number;
   /**
@@ -146,6 +146,27 @@ type CliAuthOptions = {
     maxFailuresPerIp?: number;
     maxFailuresGlobal?: number;
   };
+  /**
+   * Makes browser logins survive a restart. Absent, the session table is
+   * in-memory and a restart signs every browser out — see the table's own note.
+   * `createAuthSessionStore` is the CLI's file-backed implementation.
+   */
+  sessions?: CliSessionStore;
+};
+/** One session-table row as it is handed to a store; the key is opaque here. */
+type StoredSession = {
+  expiresAt: number;
+};
+/**
+ * The durability seam for browser logins. Deliberately narrow and
+ * fire-and-forget: the auth paths are synchronous, so a store may not make them
+ * wait, and a store that cannot write must degrade to "logins do not survive a
+ * restart" rather than refuse a login.
+ */
+type CliSessionStore = {
+  /** Rows recovered at startup, already pruned of expired ones. */initial?: Iterable<[string, StoredSession]>; /** The whole live table after a mutation. Must not throw. */
+  save(entries: [string, StoredSession][]): void; /** Resolves once queued writes have landed — for tests and shutdown. */
+  flush?(): Promise<void>;
 };
 /** What `authenticate` hands the worker server as the request principal. */
 type CliPrincipal = {
@@ -324,7 +345,7 @@ declare function hostnameOf(hostHeader: string): string;
 declare function isLoopbackHostname(hostname: string): boolean;
 declare function resolveInstanceConfig(flags: CliFlags, loaded: LoadedConfig, env?: NodeJS.ProcessEnv, cwd?: string): ResolvedConfig;
 //#endregion
-//#region src/instance.d.ts
+//#region src/lib/instance.d.ts
 type Instance = {
   server: WorkerServer;
   url: string;
@@ -355,10 +376,10 @@ declare function startInstance(config: ResolvedConfig, options?: {
   quiet?: boolean;
 }): Promise<Instance>;
 //#endregion
-//#region src/guard.d.ts
+//#region src/lib/guard.d.ts
 declare function runGuard(argv: string[]): Promise<number>;
 //#endregion
-//#region src/auth-key.d.ts
+//#region src/auth/auth-key.d.ts
 /**
  * Materializes the key that `resolveInstanceConfig` promised via
  * `generateAuthKey`: resolution is pure and synchronous, reading a key file is
@@ -383,7 +404,15 @@ declare function materializeAuthKey(stateDir: string | null, options?: {
   warn?: (message: string) => void;
 }): Promise<MaterializedAuthKey>;
 //#endregion
-//#region src/login-page.d.ts
+//#region src/auth/auth-sessions.d.ts
+type AuthSessionStoreOptions = {
+  /** Where `<stateDir>/auth-sessions.json` lives. */stateDir: string; /** Defaults to a `[workerdeck]` line on stderr. */
+  warn?: (message: string) => void; /** Test seam; defaults to `Date.now`. */
+  now?: () => number;
+};
+declare function createAuthSessionStore(options: AuthSessionStoreOptions): Promise<CliSessionStore>;
+//#endregion
+//#region src/auth/login-page.d.ts
 /**
  * The login page is the CLI's, not the dashboard's. That split is deliberate:
  * the SPA ships prebuilt and is also served straight from vite in dev, so making
@@ -487,5 +516,5 @@ declare function createApnsForwarder(options: {
   warn?: (message: string) => void;
 }): Promise<ApnsForwarder>;
 //#endregion
-export { type ApnsClient, type ApnsConfig, type ApnsEnvironment, type ApnsForwarder, type ApnsRequest, type ApnsResult, type CliAuth, type CliAuthOptions, type CliFlags, type CliPrincipal, ConfigError, type DeviceRecord, type DeviceRegistry, type Instance, type LoadedConfig, type LoginPageOptions, type MaterializedAuthKey, type ResolvedConfig, type WorkerDeckConfig, buildPush, createApnsClient, createApnsForwarder, createCliAuth, createDeviceRegistry, createDeviceRoute, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadApnsKey, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };
+export { type ApnsClient, type ApnsConfig, type ApnsEnvironment, type ApnsForwarder, type ApnsRequest, type ApnsResult, type AuthSessionStoreOptions, type CliAuth, type CliAuthOptions, type CliFlags, type CliPrincipal, type CliSessionStore, ConfigError, type DeviceRecord, type DeviceRegistry, type Instance, type LoadedConfig, type LoginPageOptions, type MaterializedAuthKey, type ResolvedConfig, type StoredSession, type WorkerDeckConfig, buildPush, createApnsClient, createApnsForwarder, createAuthSessionStore, createCliAuth, createDeviceRegistry, createDeviceRoute, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadApnsKey, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };
 //# sourceMappingURL=index.d.mts.map

package/build/index.mjs

@@ -1,3 +1,3 @@
-import { n as runGuard } from "./guard-D3VN855w.mjs";
-import { _ as createDeviceRegistry, a as ConfigError, b as loadApnsKey, c as isLoopback, d as parseArgs, f as resolveInstanceConfig, g as createApnsForwarder, h as buildPush, i as renderLoginPage, l as isLoopbackHostname, m as materializeAuthKey, n as resolveWebRoot, o as defaultStateDir, p as createCliAuth, r as startInstance, s as hostnameOf, t as createHostGuard, u as loadConfigFile, v as createDeviceRoute, y as createApnsClient } from "./instance-CS-1IaTm.mjs";
-export { ConfigError, buildPush, createApnsClient, createApnsForwarder, createCliAuth, createDeviceRegistry, createDeviceRoute, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadApnsKey, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };
+import { n as runGuard } from "./guard-DkovUj7o.mjs";
+import { _ as createApnsForwarder, a as ConfigError, b as createApnsClient, c as isLoopback, d as parseArgs, f as resolveInstanceConfig, g as buildPush, h as materializeAuthKey, i as renderLoginPage, l as isLoopbackHostname, m as createAuthSessionStore, n as resolveWebRoot, o as defaultStateDir, p as createCliAuth, r as startInstance, s as hostnameOf, t as createHostGuard, u as loadConfigFile, v as createDeviceRegistry, x as loadApnsKey, y as createDeviceRoute } from "./instance-CJkPdp34.mjs";
+export { ConfigError, buildPush, createApnsClient, createApnsForwarder, createAuthSessionStore, createCliAuth, createDeviceRegistry, createDeviceRoute, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadApnsKey, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };

package/build/{instance-CS-1IaTm.mjs → instance-CJkPdp34.mjs}

@@ -2,8 +2,8 @@ import { createReadStream, existsSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createFileSessionStore, createWorkerServer } from "@workerdeck/server";
 import { dashboardDir } from "@workerdeck/web";
-import { createHash, createPrivateKey, randomBytes, sign, timingSafeEqual } from "node:crypto";
-import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { createHash, createHmac, createPrivateKey, randomBytes, sign, timingSafeEqual } from "node:crypto";
+import { chmod, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { connect } from "node:http2";
 import { homedir } from "node:os";
 import { pathToFileURL } from "node:url";
@@ -512,7 +512,7 @@ async function createApnsForwarder(options) {
 	};
 }
 //#endregion
-//#region src/auth-key.ts
+//#region src/auth/auth-key.ts
 /** 48 hex chars — far past `createCliAuth`'s 12-char floor, and header-safe. */
 const generateKey = () => randomBytes(24).toString("hex");
 /** A stored key must be one printable-ASCII line long enough to be a secret:
@@ -564,7 +564,96 @@ async function materializeAuthKey(stateDir, options = {}) {
 	};
 }
 //#endregion
-//#region src/auth.ts
+//#region src/auth/auth-sessions.ts
+/**
+* Durable browser-login sessions for the turnkey CLI — the other half of
+* `materializeAuthKey`, and here for the same reason: the key survives a
+* restart so clients stay paired, and the login cookie should too. Without
+* this the cookie outlives the table it points into, so a restart signs every
+* browser out while the browser still holds a perfectly valid-looking cookie.
+*
+* What lands on disk is **not credential material**: `createCliAuth` keys its
+* table by `HMAC-SHA256(secret, token)`, so a stolen file yields neither the
+* operator secret nor any cookie value (inverting either needs a preimage of a
+* 256-bit-entropy input). That keying is also what makes key rotation
+* invalidate every outstanding cookie for free — entries written under the old
+* secret simply never match a lookup again, and age out on their own expiry.
+*
+* Writes are whole-file and serialized behind one promise chain (the table is
+* capped at `MAX_SESSIONS`, so "whole file" is a few kilobytes), and go through
+* a temp file + rename so a crash mid-write cannot leave a truncated table.
+* Every failure is a warning, never a throw: losing durability signs the
+* operator out, losing the gateway does much worse.
+*/
+const FORMAT_VERSION = 1;
+const FILE_NAME = "auth-sessions.json";
+const parseSessions = (raw, now) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return [];
+	}
+	const file = parsed;
+	if (file?.version !== FORMAT_VERSION || !Array.isArray(file.sessions)) return [];
+	const entries = [];
+	for (const entry of file.sessions) {
+		if (!Array.isArray(entry) || entry.length !== 2) continue;
+		const [key, expiresAt] = entry;
+		if (typeof key !== "string" || key === "") continue;
+		if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= now) continue;
+		entries.push([key, { expiresAt }]);
+	}
+	return entries;
+};
+async function createAuthSessionStore(options) {
+	const now = options.now ?? Date.now;
+	const warn = options.warn ?? ((message) => process.stderr.write(`[workerdeck] ${message}\n`));
+	const path = join(options.stateDir, FILE_NAME);
+	let initial = [];
+	try {
+		initial = parseSessions(await readFile(path, "utf8"), now());
+		try {
+			const { mode } = await stat(path);
+			if ((mode & 63) !== 0) warn(`session file ${path} is readable by other users (mode ${(mode & 511).toString(8)}) — run: chmod 600 ${path}`);
+		} catch {}
+	} catch {
+		initial = [];
+	}
+	let pending = Promise.resolve();
+	let warned = false;
+	const write = async (entries) => {
+		const body = {
+			version: FORMAT_VERSION,
+			sessions: entries.map(([key, s]) => [key, s.expiresAt])
+		};
+		const tmp = `${path}.${process.pid}.tmp`;
+		try {
+			await mkdir(dirname(path), {
+				recursive: true,
+				mode: 448
+			});
+			await writeFile(tmp, `${JSON.stringify(body)}\n`, { mode: 384 });
+			await chmod(tmp, 384);
+			await rename(tmp, path);
+			warned = false;
+		} catch (error) {
+			if (!warned) {
+				warned = true;
+				warn(`could not persist browser logins to ${path}: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+	};
+	return {
+		initial,
+		save(entries) {
+			pending = pending.then(() => write(entries));
+		},
+		flush: () => pending
+	};
+}
+//#endregion
+//#region src/auth/auth.ts
 const MIN_SECRET_LENGTH = 12;
 const DEFAULT_COOKIE_NAME = "workerdeck_session";
 const DEFAULT_TTL_MS = 10080 * 60 * 1e3;
@@ -609,13 +698,25 @@ function createCliAuth(options = {}) {
 	* Browser sessions are a server-side table, not signed tokens: logout must
 	* actually invalidate, and a stateless HMAC token stays valid until expiry no
 	* matter what the server thinks. This is one long-lived process (multi-node
-	* is a non-goal), so "table" means one Map — the cost is that a restart signs
-	* every browser out, which for an operator dashboard one secret away from
-	* re-login is the right trade. Keys are token digests: recovering an entry's
-	* token from lookup timing would need a SHA-256 preimage.
+	* is a non-goal), so "table" means one Map — optionally mirrored to a
+	* `CliSessionStore` so a restart does not sign every browser out while the
+	* browser still holds a cookie the ttl says is good for a week.
+	*
+	* Keys are `HMAC-SHA256(secret, token)`, which buys three things at once:
+	* recovering a token from a key (or from lookup timing) needs a preimage;
+	* what a store writes to disk is not credential material; and rotating the
+	* operator secret invalidates every outstanding cookie **for free**, since
+	* rows written under the old secret can no longer be looked up and age out on
+	* their own expiry.
 	*/
 	const sessions = /* @__PURE__ */ new Map();
-	const tokenKey = (token) => sha256(token).toString("hex");
+	const store = options.sessions;
+	const tokenKey = (token) => secret === void 0 ? sha256(token).toString("hex") : createHmac("sha256", secret).update(token).digest("hex");
+	if (store?.initial !== void 0) for (const [key, entry] of store.initial) {
+		if (sessions.size >= MAX_SESSIONS) break;
+		sessions.set(key, { expiresAt: entry.expiresAt });
+	}
+	const persist = () => store?.save([...sessions]);
 	const createSession = () => {
 		if (sessions.size >= MAX_SESSIONS) {
 			const oldest = sessions.keys().next().value;
@@ -623,6 +724,7 @@ function createCliAuth(options = {}) {
 		}
 		const token = randomBytes(32).toString("base64url");
 		sessions.set(tokenKey(token), { expiresAt: Date.now() + ttlMs });
+		persist();
 		return token;
 	};
 	const cookieToken = (req) => {
@@ -642,6 +744,7 @@ function createCliAuth(options = {}) {
 		if (entry === void 0) return false;
 		if (entry.expiresAt <= Date.now()) {
 			sessions.delete(key);
+			persist();
 			return false;
 		}
 		return true;
@@ -901,7 +1004,7 @@ function createCliAuth(options = {}) {
 				return;
 			}
 			const token = cookieToken(req);
-			if (token !== void 0 && token !== "") sessions.delete(tokenKey(token));
+			if (token !== void 0 && token !== "" && sessions.delete(tokenKey(token))) persist();
 		}
 		const cookie = clearCookieValue(req);
 		if (json) res.writeHead(204, {
@@ -1276,7 +1379,7 @@ function resolveApns(loaded) {
 	};
 }
 //#endregion
-//#region src/login-page.ts
+//#region src/auth/login-page.ts
 const escapeHtml = (value) => value.replace(/[&<>"']/g, (c) => ({
 	"&": "&amp;",
 	"<": "&lt;",
@@ -1349,7 +1452,7 @@ function renderLoginPage(options) {
 `;
 }
 //#endregion
-//#region src/static.ts
+//#region src/lib/static.ts
 /**
 * Static file serving for the bundled dashboard. Deliberately policy-free: what
 * counts as a document, and whether an unauthenticated visitor gets the app or a
@@ -1456,7 +1559,7 @@ async function serveFile(req, res, filePath, options = {}) {
 	return "served";
 }
 //#endregion
-//#region src/instance.ts
+//#region src/lib/instance.ts
 /**
 * The dashboard comes from `@workerdeck/web`, which ships it prebuilt and
 * exports the path to it. Depending on the package rather than vendoring a copy
@@ -1551,13 +1654,18 @@ function createFallback(auth, webRoot, hostAllowed, apnsRoute) {
 async function startInstance(config, options = {}) {
 	const webRoot = config.web ? config.webRoot ?? resolveWebRoot() : void 0;
 	const generated = config.generateAuthKey && !config.hostAuthenticates ? await materializeAuthKey(config.stateDir) : null;
-	const auth = createCliAuth(config.hostAuthenticates ? {
+	const authOptions = config.hostAuthenticates ? {
 		...config.auth,
 		secret: void 0
 	} : generated ? {
 		...config.auth,
 		secret: generated.key
-	} : config.auth);
+	} : config.auth;
+	const sessions = authOptions.secret !== void 0 && config.stateDir ? await createAuthSessionStore({ stateDir: config.stateDir }) : void 0;
+	const auth = createCliAuth(sessions ? {
+		...authOptions,
+		sessions
+	} : authOptions);
 	if (config.allowedHosts === null && !config.hostAuthenticates && !auth.enabled) throw new Error("refusing to serve: the resolved config expects auth but no shared secret was materialized — this instance would be open while believing itself authenticated");
 	if (config.corsOrigins.length > 0 && !config.hostAuthenticates && !auth.enabled) throw new Error("refusing to serve: corsOrigins is set but this instance has no auth — a cross-origin page could drive it with no credential. Set --auth-key.");
 	const hostAllowed = createHostGuard(config.allowedHosts);
@@ -1627,12 +1735,13 @@ async function startInstance(config, options = {}) {
 		closed,
 		close: async () => {
 			await server.close();
+			await sessions?.flush?.();
 			apns?.close();
 			resolveClosed();
 		}
 	};
 }
 //#endregion
-export { createDeviceRegistry as _, ConfigError as a, loadApnsKey as b, isLoopback as c, parseArgs as d, resolveInstanceConfig as f, createApnsForwarder as g, buildPush as h, renderLoginPage as i, isLoopbackHostname as l, materializeAuthKey as m, resolveWebRoot as n, defaultStateDir as o, createCliAuth as p, startInstance as r, hostnameOf as s, createHostGuard as t, loadConfigFile as u, createDeviceRoute as v, createApnsClient as y };
+export { createApnsForwarder as _, ConfigError as a, createApnsClient as b, isLoopback as c, parseArgs as d, resolveInstanceConfig as f, buildPush as g, materializeAuthKey as h, renderLoginPage as i, isLoopbackHostname as l, createAuthSessionStore as m, resolveWebRoot as n, defaultStateDir as o, createCliAuth as p, startInstance as r, hostnameOf as s, createHostGuard as t, loadConfigFile as u, createDeviceRegistry as v, loadApnsKey as x, createDeviceRoute as y };
 
-//# sourceMappingURL=instance-CS-1IaTm.mjs.map
+//# sourceMappingURL=instance-CJkPdp34.mjs.map