@workerdeck/server 0.6.0 → 0.7.0

package/README.md

@@ -39,7 +39,8 @@ import { createWorkerServer } from '@workerdeck/server'
 
 const worker = createWorkerServer({
   authenticate: async (req) => verifyMyAppToken(req.headers.authorization),
-  allowedCwdRoots: ['/srv/checkouts'],          // clamp where sessions may run
+  allowedCwdRoots: ['/srv/checkouts'],          // where sessions may run — and what /fs serves
+  hostFiles: { write: true },                   // /fs reads follow the roots above; writing opts in
   buildRunnerConfig: (req) => ({ ...req, env: { ...process.env } }),
   requireApiKey: true,                          // fail closed on subscription credentials
 })
@@ -57,6 +58,9 @@ Routes (default `basePath: '/v1'`):
 | `POST /v1/sessions/:id/permissions/:requestId` | Resolve a pending approval over REST |
 | `GET /v1/sdk-sessions?dir=…` | List the Agent SDK's on-disk sessions to offer resume |
 | `GET /v1/sessions/:id/files`, `…/files/<path>` | List and download a session's scratch-filesystem deliverables |
+| `GET /v1/fs/roots`, `/fs/list?path=`, `/fs/read?path=` | Browse and read the **host's** real tree (the `allowedCwdRoots` trees, unless `hostFiles.roots` narrows them; 404 when neither is set) |
+| `GET /v1/fs/find?path=&q=` | Recursive fuzzy file search under one directory — what backs `@file` completion |
+| `PUT /v1/fs/write` | Save a host file — needs `hostFiles.write`, and always carries the hash it replaces |
 | `POST /v1/executions/:executionId/result` | Deliver a deferred execution's result, waking a parked session |
 | `GET /v1/profiles`, `GET /v1/profiles/:name` | What sessions may run as (+ a view-only config snapshot) |
 | `GET/POST /v1/jobs`, `GET/DELETE /v1/jobs/:id` | Job queue (when `queue` is configured) |

package/build/index.d.mts

@@ -327,6 +327,48 @@ type WorkerServerOptions = {
   /** Required unless `allowUnauthenticated: true` — the worker must never be exposed bare. */authenticate?: Authenticator; /** Explicit opt-in to run without auth (local dev only). */
   allowUnauthenticated?: boolean; /** If set, session cwd must resolve inside one of these roots. Strongly recommended. */
   allowedCwdRoots?: string[];
+  /**
+   * The host filesystem routes (`{basePath}/fs/*`) — browse and read the
+   * operator's real project tree, and optionally write to it.
+   *
+   * **Reading follows {@link allowedCwdRoots} and needs no grant of its own.**
+   * A caller holding the auth key can already start a session in any allowed root
+   * and have the agent read whatever is in it, so serving those same trees over
+   * `/fs` adds no authority — it only removes the absurdity of going through a
+   * language model to `cat` a file. Set `roots` here only to *narrow* that (or to
+   * expose a tree sessions may not run in).
+   *
+   * With neither set the routes 404. That is not the same as inheriting
+   * `allowedCwdRoots`' permissive "unset means anywhere": no cwd policy means
+   * there is nothing to inherit, and "anywhere" is a statement about paths the
+   * operator types at a keyboard, not one about what a phone may read.
+   *
+   * **Writing is a separate opt-in**, because it is the one part that is not
+   * already implied. An agent's writes go through the permission flow; a `PUT` to
+   * `/fs/write` does not. These routes are operator-privileged by design — the
+   * caller is the operator — but that is a reason to make the bypass deliberate,
+   * not a reason to skip the switch.
+   *
+   * Containment is *not* `cwdAllowed`, whichever roots are in play: these routes
+   * walk paths the agent may have authored, so a symlink can escape a lexical
+   * prefix check. See `host-files.ts` — canonicalize, then re-check.
+   */
+  hostFiles?: {
+    /** Absolute paths. Unset inherits {@link allowedCwdRoots}; an explicit empty
+     * array disables the routes (a policy, not an absence). */
+    roots?: string[]; /** Enable `PUT {basePath}/fs/write`. Default false — read-only. */
+    write?: boolean;
+    /** Refuse reads above this (413) rather than streaming a gigabyte to a phone.
+     * Default 1 MiB. Writes are bounded by {@link maxBodyBytes} instead. */
+    maxFileBytes?: number;
+    /** Cap on entries returned per directory (the response says `truncated`).
+     * Default 5000. */
+    maxEntries?: number;
+    /** Directory names `GET /fs/find` will not descend into. Defaults to
+     * `DEFAULT_IGNORED_DIRS` (`.git`, `node_modules`, build output…) — the thing
+     * that keeps a per-keystroke search cheap on a real source tree. */
+    ignore?: string[];
+  };
   /**
    * Named Claude Code config directories sessions can run under (each becomes the
    * session's CLAUDE_CONFIG_DIR — settings, memory, skills, and the credentials the