workerdeck 0.6.0 → 0.9.0

package/README.md

@@ -45,6 +45,8 @@ port. `--insecure` overrides that, for when something in front is doing the auth
 | `--host <addr>` | `WORKERDECK_HOST` | `127.0.0.1` |
 | `--auth-key <secret>` | `WORKERDECK_AUTH_KEY` | none (no auth) |
 | `--cwd-root <path>` (repeatable) | `WORKERDECK_CWD_ROOTS` (`:`-separated) | unrestricted |
+| `--fs-root <path>` (repeatable) | `WORKERDECK_FS_ROOTS` (`:`-separated) | narrows `/v1/fs`; unset, reading follows `--cwd-root` |
+| `--fs-write` | — | off (browse and read only) |
 | `--profile <name=dir>` (repeatable) | — | auto-detected from `~/.claude` |
 | `--state-dir <path>` | `WORKERDECK_STATE_DIR` | beside the config file, else `~/.workerdeck` |
 | `--no-parking-store` | — | durable parking on |

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-kupxU5UD.mjs";
+import { a as ConfigError, d as parseArgs, f as resolveInstanceConfig, r as startInstance, u as loadConfigFile } from "./instance-DbIqlX-e.mjs";
 import { dirname, join } from "node:path";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
@@ -36,6 +36,15 @@ Options
       --profile <name=dir>  Claude config dir a session may run under (repeatable)
       --cwd-root <path>     restrict session cwds to this root (repeatable,
                             WORKERDECK_CWD_ROOTS as a ':'-separated list)
+      --fs-root <path>      narrow which host directories /v1/fs serves
+                            (repeatable, WORKERDECK_FS_ROOTS as a ':'-separated
+                            list). Reading otherwise follows --cwd-root: a caller
+                            who may start a session in a tree can already read it
+                            through the agent. With neither, the routes 404.
+      --fs-write            also accept writes over /v1/fs. Its own switch because
+                            an agent's writes go through the permission flow and a
+                            PUT does not. Every write is still conditional on the
+                            hash the client last read.
       --state-dir <path>    where parked sessions are persisted
                             (default: beside the config file, else ~/.workerdeck)
       --no-parking-store    keep parked sessions in memory only; a restart drops them

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      --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      --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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDb,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 './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      --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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+Db,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/index.d.mts

@@ -1,7 +1,74 @@
 import { Authenticator, WorkerServer, WorkerServerOptions } from "@workerdeck/server";
+import { KeyObject } from "node:crypto";
 import { IncomingMessage, ServerResponse } from "node:http";
-import { ProfileInfo } from "@workerdeck/protocol";
+import { ProfileInfo, SessionNotification } from "@workerdeck/protocol";
 
+//#region src/apns/client.d.ts
+/**
+ * A minimal APNs provider client: an HTTP/2 POST carrying an ES256 JWT.
+ *
+ * Hand-rolled rather than a dependency, because that is the whole of the
+ * protocol and the published CLI's zero-runtime-dep posture is worth more than
+ * the eighty lines. Note `fetch`/undici will not do: it does not speak HTTP/2,
+ * and APNs accepts nothing else — hence `node:http2` directly.
+ *
+ * Token authentication, not certificates: one `.p8` serves every app in the team
+ * and both environments, and it does not expire. Certificates are per-app,
+ * per-environment, and expire annually.
+ */
+type ApnsEnvironment = 'development' | 'production';
+type ApnsConfig = {
+  /** Path to the `.p8`. A path, never the contents — a secret pasted into a
+   * config file is a secret in every backup of that file. */
+  keyFile: string; /** The 10-character Key ID shown beside the key in the developer portal. */
+  keyId: string; /** The 10-character Team ID from the top right of the portal. */
+  teamId: string; /** The APNs topic, which is the app's bundle id (`bi.atomic.workerdeck.ios`). */
+  topic: string;
+  /** Environment for a device that registered without naming one. Devices that
+   * do name one are always routed by their own answer — see the note on
+   * `ApnsEnvironment` below. */
+  production?: boolean;
+};
+type ApnsRequest = {
+  deviceToken: string;
+  environment: ApnsEnvironment;
+  payload: unknown; /** 10 for something a person is waiting on, 5 for everything else. */
+  priority?: 5 | 10; /** Unix seconds after which Apple stops trying. 0 means "one attempt". */
+  expiration?: number;
+  /** Later pushes with the same id replace an undelivered earlier one. Max 64
+   * bytes, so never pass a raw identifier of unbounded length. */
+  collapseId?: string;
+};
+type ApnsResult = {
+  ok: true;
+  apnsId?: string;
+} | {
+  ok: false;
+  status: number;
+  reason: string;
+  /** The token is dead: drop it from the registry rather than retrying it
+   * forever. The app re-registers on its next launch anyway. */
+  unregistered: boolean;
+};
+type ApnsClient = {
+  send(request: ApnsRequest): Promise<ApnsResult>;
+  close(): void;
+};
+/**
+ * Load and sanity-check the auth key. Done once at startup rather than at the
+ * first push, so a mistyped path is a launch error with a clear message instead
+ * of a notification that silently never arrives.
+ */
+declare function loadApnsKey(keyFile: string): Promise<KeyObject>;
+declare function createApnsClient(config: ApnsConfig, key: KeyObject,
+/** Test seam: point the two environments at a local HTTP/2 server. Nothing in
+ * production should pass this — the real endpoints are not configurable, and
+ * an operator who could redirect them could exfiltrate every push. */
+
+options?: {
+  hosts?: Record<ApnsEnvironment, string>;
+}): ApnsClient;
+//#endregion
 //#region src/auth.d.ts
 /**
  * Gateway auth for the turnkey CLI: one shared operator secret, two transports.
@@ -124,6 +191,17 @@ type WorkerDeckConfig = WorkerServerOptions & {
    */
   insecureHosts?: string[]; /** Serve a dashboard build from here instead of the bundled one. */
   webRoot?: string;
+  /**
+   * Forward session notifications to Apple Push Notification service, for the
+   * iOS app. Absent turns the forwarder off entirely — including its
+   * `/apns/devices` route, so a gateway without this answers 404 there and the
+   * app quietly stops asking.
+   *
+   * Lives here rather than in `packages/server` on purpose: this is the only
+   * place in the project that holds a push credential, and the OSS gateway
+   * stays credential-free. `keyFile` is a path, never key contents.
+   */
+  apns?: ApnsConfig;
 };
 type CliFlags = {
   config?: string;
@@ -132,6 +210,8 @@ type CliFlags = {
   authKey?: string;
   profiles: ProfileInfo[];
   cwdRoots: string[];
+  fsRoots: string[];
+  fsWrite?: boolean;
   allowedOrigins: string[];
   allowedHosts: string[];
   insecureHosts: string[];
@@ -185,6 +265,9 @@ type ResolvedConfig = {
    */
   allowedHosts: Set<string> | null; /** Dashboard build to serve; resolved from the package when unset. */
   webRoot?: string;
+  /** APNs forwarder settings with `keyFile` made absolute, or undefined for an
+   * instance that does not push. */
+  apns?: ApnsConfig;
   open: boolean;
   options: WorkerServerOptions;
 };
@@ -282,5 +365,89 @@ type LoginPageOptions = {
 };
 declare function renderLoginPage(options: LoginPageOptions): string;
 //#endregion
-export { type CliAuth, type CliAuthOptions, type CliFlags, type CliPrincipal, ConfigError, type Instance, type LoadedConfig, type LoginPageOptions, type MaterializedAuthKey, type ResolvedConfig, type WorkerDeckConfig, createCliAuth, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };
+//#region src/apns/devices.d.ts
+/**
+ * The device-token registry, and the route that fills it.
+ *
+ * This has to live *somewhere*, and the point of the webhooks-first decision is
+ * that it is not `packages/server`: the OSS gateway stays credential-free and
+ * knows nothing about APNs. So the turnkey CLI mounts its own route through the
+ * server's `fallback` hook — the same seam that serves the dashboard — and
+ * registration lands on the gateway's own origin, behind the auth key that
+ * already guards everything else.
+ *
+ * Storage is a JSON file under the state dir with the same 0600 posture as
+ * `auth-key`. Device tokens are not secrets in the way an auth key is, but they
+ * are a list of which phones belong to the operator, and there is no reason for
+ * every user on the machine to read it.
+ */
+type DeviceRecord = {
+  /** Hex APNs device token. */token: string;
+  environment: ApnsEnvironment;
+  /**
+   * Opaque to us: the client's own id for this gateway, echoed back in every
+   * payload. It is what lets an app configured with two gateways tell which one
+   * woke it — we store the string and never interpret it.
+   */
+  hostId?: string;
+  bundleId?: string;
+  platform?: string;
+  updatedAt: number;
+};
+type DeviceRegistry = {
+  list(): DeviceRecord[];
+  register(record: Omit<DeviceRecord, 'updatedAt'>): Promise<void>;
+  remove(token: string): Promise<void>;
+};
+/**
+ * `dir` null keeps the registry in memory: a restart then forgets every token,
+ * which is survivable because the app re-registers on launch, but it does mean
+ * an instance with no state dir goes quiet until each phone is next opened.
+ */
+declare function createDeviceRegistry(options: {
+  dir: string | null;
+  onError?: (error: unknown, context: {
+    op: string;
+    path: string;
+  }) => void;
+}): Promise<DeviceRegistry>;
+/**
+ * `POST /apns/devices` to register a token, `DELETE /apns/devices` to drop one.
+ * Returns true when it consumed the request.
+ *
+ * Deliberately outside `/v1`: this is the forwarder's own surface, not part of
+ * the protocol `packages/protocol` defines, and a client that finds a 404 here
+ * has simply reached a gateway running without push configured.
+ *
+ * DELETE exists so removing a gateway from the app can stop its pushes. Without
+ * it a forgotten server keeps buzzing a phone that no longer has any way to act
+ * on what it says.
+ */
+declare function createDeviceRoute(registry: DeviceRegistry, authenticate: (req: IncomingMessage) => unknown): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+//#endregion
+//#region src/apns/forwarder.d.ts
+type ApnsForwarder = {
+  /** Hand to `createWorkerServer({ notifications: { onNotification } })`. */onNotification: (notification: SessionNotification) => void; /** Mount ahead of the static host; true when it consumed the request. */
+  handleRequest: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>; /** How many devices are registered, for the startup banner. */
+  deviceCount: () => number;
+  close: () => void;
+};
+/**
+ * Build the push for one notification.
+ *
+ * The payload carries routing and nothing else — `sessionId` to deep-link,
+ * `requestId` because a lock-screen Approve has nothing to POST to without it,
+ * and `hostId` so a client with two gateways knows which one this came from.
+ * Everything else the app fetches over REST the moment it opens; a transcript
+ * has no business in a 4 KB envelope.
+ */
+declare function buildPush(notification: SessionNotification, hostId: string | undefined): Omit<ApnsRequest, 'deviceToken' | 'environment'>;
+declare function createApnsForwarder(options: {
+  config: ApnsConfig; /** Where the device registry is persisted; null keeps it in memory. */
+  stateDir: string | null; /** Guards `/apns/devices` — the instance's own `authenticate`. */
+  authenticate: (req: IncomingMessage) => unknown;
+  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 };
 //# sourceMappingURL=index.d.mts.map

package/build/index.mjs

@@ -1,3 +1,3 @@
 import { n as runGuard } from "./guard-D3VN855w.mjs";
-import { a as ConfigError, c as isLoopback, d as parseArgs, f as resolveInstanceConfig, 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 } from "./instance-kupxU5UD.mjs";
-export { ConfigError, createCliAuth, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };
+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-DbIqlX-e.mjs";
+export { ConfigError, buildPush, createApnsClient, createApnsForwarder, createCliAuth, createDeviceRegistry, createDeviceRoute, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadApnsKey, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };