sh3-server 0.6.0 → 0.8.1

package/dist/shard-router.d.ts

@@ -11,21 +11,37 @@ export interface MountContext {
      * route prefix. The returned value is a Hono middleware handler that
      * can be passed directly as the handler argument to `router.get(path, ...)`.
      *
-     * The `ws` argument passed to `onConnect` is the server-side WebSocket
-     * from `@hono/node-ws` (which wraps the `ws` package). `@hono/node-ws`
-     * does not re-export a type name for it and `@types/ws` is not a
-     * dependency, so we use `any` per the plan's explicit fallback rule.
-     * The returned handler is likewise typed as `any` — its concrete type
-     * is Hono's internal `MiddlewareHandler<..., { outputFormat: "ws" }>`,
-     * which would leak Hono ws internals into every shard that touches it.
+     * The `ws` argument passed to `onConnect` is the `WSContext` from
+     * `@hono/node-ws` enriched with two per-connection setter methods:
+     *
+     *   - `ws.send(data)` — inherited from WSContext, send a frame.
+     *   - `ws.close()` — inherited from WSContext, close the connection.
+     *   - `ws.onMessage(handler)` — register a callback that receives each
+     *     incoming frame as a string. Only one handler; last call wins.
+     *   - `ws.onClose(handler)` — register a callback fired when the
+     *     connection closes. Only one handler; last call wins.
+     *
+     * These setters exist because `@hono/node-ws` exposes the lifecycle
+     * via the `WSEvents` interface returned from `upgradeWebSocket`, not
+     * via `addEventListener` on WSContext. `wsRegister` in sh3-server
+     * bridges the two so shards can keep all per-connection state in a
+     * single closure. Do NOT try `ws.addEventListener('message', ...)` —
+     * WSContext has no such method and the call silently no-ops.
+     *
+     * `@hono/node-ws` does not re-export a type name for WSContext and
+     * `@types/ws` is not a dependency, so we use `any` per the plan's
+     * explicit fallback rule. The returned handler is likewise typed as
+     * `any` — its concrete type is Hono's internal
+     * `MiddlewareHandler<..., { outputFormat: "ws" }>`, which would leak
+     * Hono ws internals into every shard that touches it.
      *
      * The `c` argument is the Hono `Context` for the upgrade request.
      * Shards can read `c.get('session')` to route the connection to the
      * correct per-user state (e.g. `manager.getOrCreate(session.userId)`).
      *
-     * @param onConnect Called with the raw WebSocket and request Context
-     *                  when a client connects. Attach listeners in the body;
-     *                  return nothing.
+     * @param onConnect Called with the enriched WebSocket and request
+     *                  Context when a client connects. Attach listeners
+     *                  via `ws.onMessage` / `ws.onClose`; return nothing.
      */
     wsRegister(onConnect: (ws: any, c: any) => void): any;
 }

package/dist/shell-shard/index.d.ts

@@ -4,6 +4,8 @@ import type { WsLike } from './session-manager.js';
 export interface ShellServerContext {
     shardId: string;
     dataDir: string;
+    /** Base for per-user document roots; empty string → <dataDir>/users. */
+    tenantRootBase?: string;
     adminOnly: any;
     wsRegister: (onConnect: (ws: WsLike, c: Context) => void) => any;
 }

package/dist/shell-shard/index.js

@@ -10,6 +10,7 @@
 import { LocalRunner } from './runner.js';
 import { SessionManager } from './session-manager.js';
 import { handleClientMessage } from './ws.js';
+import { shardDocumentsPath } from '../tenant-fs/paths.js';
 function sessionUser(c) {
     const session = c.get('session') ?? c.env?.session;
     return session?.userId ?? 'admin';
@@ -20,7 +21,8 @@ export default {
         // Default config — overridable via shard env state in a future pass.
         const cfg = { ringSize: 500, historyMaxLines: 10_000, defaultCwd: '' };
         const runner = new LocalRunner();
-        const manager = new SessionManager(ctx.dataDir, runner, cfg);
+        const userCwd = (userId) => shardDocumentsPath(ctx.dataDir, userId, 'shell', ctx.tenantRootBase ?? '');
+        const manager = new SessionManager(ctx.dataDir, runner, cfg, userCwd);
         // NOTE: the JSON /history endpoint is convenience — the authoritative
         // delivery of history is via the `history` server message sent on WS
         // attach. Clients can skip the REST endpoint entirely. Kept for
@@ -39,11 +41,14 @@ export default {
             const userId = sessionUser(c);
             const session = manager.getOrCreate(userId);
             session.attach(ws);
-            // Wire incoming frames through the dispatch layer.
-            ws.addEventListener?.('message', (evt) => {
-                handleClientMessage(session, ws, String(evt.data));
+            // Wire incoming frames through the dispatch layer. `wsRegister`
+            // enriches the ws object with per-connection `onMessage` /
+            // `onClose` setters that forward the hono/node-ws WSEvents
+            // callbacks for this upgrade.
+            ws.onMessage((data) => {
+                handleClientMessage(session, ws, data);
             });
-            ws.addEventListener?.('close', () => {
+            ws.onClose(() => {
                 session.detach(ws);
             });
         }));

package/dist/shell-shard/runner.d.ts

@@ -3,6 +3,28 @@ export interface RunnerStartOpts {
     cmd: string;
     cwd: string;
     env: Record<string, string>;
+    /**
+     * Optional event callbacks wired up synchronously at the top of start()
+     * BEFORE the emitter can fire. Pass these when the caller cannot attach
+     * listeners on `handle.events` atomically with receiving the handle —
+     * e.g., ShellSession.submit, which uses `await runner.start(...)` and
+     * therefore only gets a chance to attach listeners in the next microtask.
+     *
+     * Why this matters: sync-failure paths (tokenize throw, empty command,
+     * Node 24's CVE-2024-27980 EINVAL for .cmd/.bat on Windows) emit their
+     * 'stderr'/'exit' events immediately via setImmediate. Without pre-
+     * registration, there's a subtle race between the emitter firing and
+     * the caller's post-await listener attachment — when `this.running = handle`
+     * is assigned only after await, an exit callback that fires on the wrong
+     * side of the boundary leaves `running` pointing at a dead handle and
+     * every subsequent submit gets silently dropped by the running-guard.
+     */
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    onExit?: (info: {
+        code: number | null;
+        signal: string | null;
+    }) => void;
 }
 export interface RunnerHandle {
     /** Send bytes to the process's stdin. No-op for LocalRunner in v1. */

package/dist/shell-shard/runner.js

@@ -14,12 +14,35 @@ import { tokenize } from './tokenize.js';
 export class LocalRunner {
     async start(opts) {
         const events = new EventEmitter();
+        // Pre-attach caller-supplied listeners BEFORE any code path that
+        // could emit. See note on RunnerStartOpts — this closes the race
+        // for every sync-failure path (tokenize throw, empty cmd, EINVAL).
+        if (opts.onStdout)
+            events.on('stdout', opts.onStdout);
+        if (opts.onStderr)
+            events.on('stderr', opts.onStderr);
+        if (opts.onExit)
+            events.on('exit', opts.onExit);
         let child;
         try {
-            const [bin, ...args] = tokenize(opts.cmd);
+            // tokenize is used for VALIDATION only — detect unterminated quotes
+            // and empty commands before handing off to the shell. We don't pass
+            // the tokenized args to spawn: with `shell: true` (below) the shell
+            // re-parses the raw command line, and tokenizing would strip quotes
+            // the shell needs for its own escaping.
+            const [bin] = tokenize(opts.cmd);
             if (!bin) {
-                // Empty command — emit an error exit without spawning
-                queueMicrotask(() => {
+                // Empty command — emit an error exit without spawning.
+                // Must use setImmediate, not queueMicrotask: the caller
+                // (ShellSession.submit) attaches its 'stdout'/'stderr'/'exit'
+                // listeners in the continuation after `await runner.start()`,
+                // which is itself a microtask. queueMicrotask would drain FIFO
+                // before that continuation, emitting to an emitter with zero
+                // listeners — the exit event silently vanishes and the session
+                // gets stuck with `running` pointing at a dead handle. setImmediate
+                // defers to the event loop's check phase, strictly after microtask
+                // drain, so listeners are always in place when we fire.
+                setImmediate(() => {
                     events.emit('stderr', 'shell: empty command\n');
                     events.emit('exit', { code: null, signal: 'spawn-error' });
                 });
@@ -30,15 +53,24 @@ export class LocalRunner {
                     events,
                 };
             }
-            child = spawn(bin, args, {
+            // Use shell: true so the platform shell resolves PATH, handles
+            // Windows .cmd/.bat files (npm, yarn, tsc, …), and gives the user
+            // the metacharacter semantics they expect from a terminal. Node
+            // 24's CVE-2024-27980 patch throws EINVAL synchronously for
+            // .cmd/.bat with shell: false — which is what the terminal IS
+            // supposed to run, so shell: true is the only correct mode here.
+            // We pass opts.cmd as the sole command string and [] as args so
+            // spawn hands the whole line to the shell untouched.
+            child = spawn(opts.cmd, [], {
                 cwd: opts.cwd,
                 env: opts.env,
-                shell: false,
+                shell: true,
             });
         }
         catch (err) {
             const message = err.message ?? String(err);
-            queueMicrotask(() => {
+            // See note above on setImmediate vs queueMicrotask — same race.
+            setImmediate(() => {
                 events.emit('stderr', `shell: ${message}\n`);
                 events.emit('exit', { code: null, signal: 'spawn-error' });
             });

package/dist/shell-shard/session-manager.d.ts

@@ -7,13 +7,20 @@ export interface SessionConfig {
     defaultCwd: string;
 }
 /**
- * Minimal WebSocket interface — any object with .send(string) satisfies it.
- * The server's real WS implementation (from @hono/node-ws) provides a richer
- * surface; we intentionally narrow it here so tests can use plain mocks.
+ * Minimal WebSocket interface — what ShellSession needs to talk to a
+ * connected client. Real connections come from sh3-server's wsRegister
+ * (see MountContext.wsRegister in shard-router.ts), which enriches the
+ * `@hono/node-ws` WSContext with per-connection `onMessage` / `onClose`
+ * setter methods. ShellSession itself only ever calls `send` / `close`;
+ * the setter methods are only used by the connection-wiring code in
+ * shell-shard/index.ts, but they stay on this interface so the same
+ * type flows through `wsRegister(onConnect: (ws: WsLike, ...))`.
  */
 export interface WsLike {
     send(data: string): void;
     close(): void;
+    onMessage(handler: (data: string) => void): void;
+    onClose(handler: () => void): void;
 }
 export declare class ShellSession {
     readonly userId: string;
@@ -51,6 +58,7 @@ export declare class SessionManager {
     private readonly dataDir;
     private readonly runner;
     private readonly cfg;
-    constructor(dataDir: string, runner: Runner, cfg: SessionConfig);
+    private readonly userCwd;
+    constructor(dataDir: string, runner: Runner, cfg: SessionConfig, userCwd: (userId: string) => string);
     getOrCreate(userId: string): ShellSession;
 }

package/dist/shell-shard/session-manager.js

@@ -80,6 +80,13 @@ export class ShellSession {
         // Claim the start slot synchronously so a concurrent submit during
         // the `await runner.start()` below cannot slip past the lock check.
         this.starting = true;
+        // Track whether the runner already exited before we latched `running`.
+        // Sync-failure paths (empty cmd, tokenize throw, Node 24's EINVAL for
+        // .cmd/.bat on Windows) can fire onExit via setImmediate BEFORE the
+        // await continuation runs — so we must not assign `this.running = handle`
+        // for a process that's already dead, or subsequent submits get wedged
+        // by the running-guard above. See runner.ts for the full race writeup.
+        let exited = false;
         try {
             this.history.append(line);
             // Emit a prompt event so every attached client echoes the line
@@ -94,24 +101,33 @@ export class ShellSession {
                 cmd: line,
                 cwd: this.cwd,
                 env: this.env,
+                // Callback listeners — attached synchronously inside start() BEFORE
+                // any emit can fire. Do NOT switch back to `handle.events.on(...)`
+                // after await: that re-opens the race the callbacks exist to close.
+                onStdout: (data) => {
+                    this.broadcast({ kind: 'stdout', data, ts: Date.now(), seq: 0 });
+                },
+                onStderr: (data) => {
+                    this.broadcast({ kind: 'stderr', data, ts: Date.now(), seq: 0 });
+                },
+                onExit: (info) => {
+                    this.broadcast({
+                        kind: 'exit',
+                        code: info.code,
+                        signal: info.signal,
+                        ts: Date.now(),
+                        seq: 0,
+                    });
+                    exited = true;
+                    this.running = null;
+                },
             });
-            this.running = handle;
-            handle.events.on('stdout', (data) => {
-                this.broadcast({ kind: 'stdout', data, ts: Date.now(), seq: 0 });
-            });
-            handle.events.on('stderr', (data) => {
-                this.broadcast({ kind: 'stderr', data, ts: Date.now(), seq: 0 });
-            });
-            handle.events.on('exit', (info) => {
-                this.broadcast({
-                    kind: 'exit',
-                    code: info.code,
-                    signal: info.signal,
-                    ts: Date.now(),
-                    seq: 0,
-                });
-                this.running = null;
-            });
+            // Only latch `running` if the process hasn't already died during the
+            // await boundary. Otherwise we'd resurrect a dead handle and wedge
+            // every subsequent submit.
+            if (!exited) {
+                this.running = handle;
+            }
         }
         finally {
             this.starting = false;
@@ -144,16 +160,29 @@ export class SessionManager {
     dataDir;
     runner;
     cfg;
-    constructor(dataDir, runner, cfg) {
+    userCwd;
+    constructor(dataDir, runner, cfg, userCwd) {
         this.dataDir = dataDir;
         this.runner = runner;
         this.cfg = cfg;
+        this.userCwd = userCwd;
     }
     getOrCreate(userId) {
         let session = this.sessions.get(userId);
         if (!session) {
             const history = new HistoryStore(this.dataDir, userId, this.cfg.historyMaxLines);
-            session = new ShellSession(userId, this.runner, history, this.cfg);
+            // Resolve user cwd; on disk failure fall back to cfg.defaultCwd so
+            // a sick data dir doesn't block login. The warning surfaces in the
+            // server log so ops can notice.
+            let cwd = this.cfg.defaultCwd;
+            try {
+                cwd = this.userCwd(userId);
+            }
+            catch (err) {
+                console.warn(`[shell-shard] userCwd failed for ${userId}: ${err.message} — falling back to ${cwd || 'process.cwd()'}`);
+            }
+            const cfg = { ...this.cfg, defaultCwd: cwd };
+            session = new ShellSession(userId, this.runner, history, cfg);
             this.sessions.set(userId, session);
         }
         return session;

package/dist/shell-shard/ws.js

@@ -15,21 +15,16 @@ export function handleClientMessage(session, ws, raw) {
         msg = JSON.parse(raw);
     }
     catch {
-        // Malformed frame — ignore, do not crash the session.
         return;
     }
     switch (msg.t) {
         case 'hello':
-            // attach() already sent welcome+replay+history at connection time.
-            // The only meaningful thing here is a late hello with replayFrom,
-            // which v1 ignores — the client can resync by reconnecting.
             return;
         case 'submit': {
             const trimmed = msg.line.trim();
             if (trimmed.startsWith('cd ') || trimmed === 'cd') {
-                // Server-managed cd — don't spawn, update session cwd directly.
                 const target = trimmed === 'cd' ? '' : trimmed.slice(3).trim();
-                handleCd(session, target);
+                applyCwdChange(session, target, 'cd');
                 return;
             }
             void session.submit(msg.line, ws);
@@ -42,12 +37,12 @@ export function handleClientMessage(session, ws, raw) {
             session.historyLog(msg.line);
             return;
         case 'cwd-query':
-            // Re-emit a cwd update message (reuses setCwd() broadcast path).
             session.setCwd(session.cwd);
             return;
+        case 'setCwd':
+            applyCwdChange(session, msg.path, 'setCwd');
+            return;
         default: {
-            // Exhaustiveness check. If a new ClientMessage variant is added to
-            // the protocol without a handler here, TypeScript flags this line.
             const _exhaustive = msg;
             void _exhaustive;
             return;
@@ -55,11 +50,16 @@ export function handleClientMessage(session, ws, raw) {
     }
 }
 /**
- * Handle a `cd` command server-side: resolve the target path, validate it
- * exists and is a directory, then update session.cwd via setCwd() which
- * broadcasts a 'cwd' message to every attached client.
+ * Resolve a cwd-change request against the session's current cwd, validate
+ * it exists and is a directory, then update session.cwd via setCwd(). Used
+ * for both interactive `cd` (from submit) and programmatic `setCwd` (from
+ * the docs tree / file explorer).
+ *
+ * Stderr wording keeps the familiar `cd: no such directory` for shell users
+ * and `setCwd: no such directory` for programmatic callers, so the source
+ * of a bad path is obvious in the terminal log.
  */
-function handleCd(session, target) {
+function applyCwdChange(session, target, source) {
     const dest = target === '' || target === '~'
         ? homedir()
         : isAbsolute(target)
@@ -69,7 +69,7 @@ function handleCd(session, target) {
         session.broadcast({
             seq: 0,
             kind: 'stderr',
-            data: `cd: no such directory: ${target}\n`,
+            data: `${source}: no such directory: ${target}\n`,
             ts: Date.now(),
         });
         return;

package/dist/tenant-fs/http.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tenant FS HTTP API — mounts /api/fs/list, /api/fs/stat, /api/fs/read.
+ *
+ * Gated by sessionRequired; scope is the caller's own documentsRoot.
+ * Read-only. Writes are out of scope for this iteration.
+ */
+import type { Hono } from 'hono';
+import type { SettingsStore } from '../settings.js';
+export interface TenantFsRouteContext {
+    dataDir: string;
+    rootBase: string;
+    settings: SettingsStore;
+    maxReadBytes: number;
+}
+export declare function registerTenantFsRoutes(app: Hono, ctx: TenantFsRouteContext): void;

package/dist/tenant-fs/http.js

@@ -0,0 +1,109 @@
+/**
+ * Tenant FS HTTP API — mounts /api/fs/list, /api/fs/stat, /api/fs/read.
+ *
+ * Gated by sessionRequired; scope is the caller's own documentsRoot.
+ * Read-only. Writes are out of scope for this iteration.
+ */
+import { readdir, stat, readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { documentsRoot } from './paths.js';
+import { resolveTenantPath, TenantPathEscapeError } from './resolve.js';
+import { makeSessionRequired } from './session-required.js';
+function userIdFromContext(c) {
+    const session = c.get('session') ?? c.env?.session;
+    if (!session?.userId)
+        throw new Error('sessionRequired missing before handler');
+    return session.userId;
+}
+export function registerTenantFsRoutes(app, ctx) {
+    const sessionRequired = makeSessionRequired(ctx.settings);
+    app.get('/api/fs/list', sessionRequired, async (c) => {
+        const rel = c.req.query('path') ?? '';
+        const root = documentsRoot(ctx.dataDir, userIdFromContext(c), ctx.rootBase);
+        let abs;
+        try {
+            abs = await resolveTenantPath(root, rel);
+        }
+        catch (err) {
+            if (err instanceof TenantPathEscapeError)
+                return c.json({ error: 'forbidden' }, 403);
+            throw err;
+        }
+        let names;
+        try {
+            names = await readdir(abs);
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return c.json({ error: 'not found' }, 404);
+            if (err?.code === 'ENOTDIR')
+                return c.json({ error: 'not a directory' }, 400);
+            throw err;
+        }
+        const entries = await Promise.all(names.map(async (name) => {
+            const s = await stat(`${abs}/${name}`);
+            return {
+                name,
+                kind: s.isDirectory() ? 'dir' : 'file',
+                size: s.size,
+                mtime: s.mtimeMs,
+            };
+        }));
+        return c.json({ entries });
+    });
+    app.get('/api/fs/stat', sessionRequired, async (c) => {
+        const rel = c.req.query('path') ?? '';
+        const root = documentsRoot(ctx.dataDir, userIdFromContext(c), ctx.rootBase);
+        let abs;
+        try {
+            abs = await resolveTenantPath(root, rel);
+        }
+        catch (err) {
+            if (err instanceof TenantPathEscapeError)
+                return c.json({ error: 'forbidden' }, 403);
+            throw err;
+        }
+        try {
+            const s = await stat(abs);
+            return c.json({
+                name: basename(abs),
+                kind: s.isDirectory() ? 'dir' : 'file',
+                size: s.size,
+                mtime: s.mtimeMs,
+            });
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return c.json({ error: 'not found' }, 404);
+            throw err;
+        }
+    });
+    app.get('/api/fs/read', sessionRequired, async (c) => {
+        const rel = c.req.query('path') ?? '';
+        const root = documentsRoot(ctx.dataDir, userIdFromContext(c), ctx.rootBase);
+        let abs;
+        try {
+            abs = await resolveTenantPath(root, rel);
+        }
+        catch (err) {
+            if (err instanceof TenantPathEscapeError)
+                return c.json({ error: 'forbidden' }, 403);
+            throw err;
+        }
+        let s;
+        try {
+            s = await stat(abs);
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return c.json({ error: 'not found' }, 404);
+            throw err;
+        }
+        if (s.isDirectory())
+            return c.json({ error: 'is a directory' }, 400);
+        if (s.size > ctx.maxReadBytes)
+            return c.json({ error: 'file too large' }, 413);
+        const buf = await readFile(abs);
+        return c.body(buf, 200, { 'Content-Type': 'application/octet-stream' });
+    });
+}

package/dist/tenant-fs/index.d.ts

@@ -0,0 +1,4 @@
+export * from './paths.js';
+export * from './resolve.js';
+export * from './session-required.js';
+export * from './http.js';

package/dist/tenant-fs/index.js

@@ -0,0 +1,4 @@
+export * from './paths.js';
+export * from './resolve.js';
+export * from './session-required.js';
+export * from './http.js';

package/dist/tenant-fs/paths.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tenant path helpers — the framework owns the `data/users/<id>/...` layout.
+ *
+ * Two tiers:
+ *   users/<id>/<shardId>/           — shard's private per-user state (internal)
+ *   users/<id>/documents/<shardId>/ — user-facing files (exposed via /api/fs)
+ *
+ * Shards call these helpers server-side. Clients use /api/fs/* to reach
+ * documents/ only — shard state is never served over HTTP.
+ */
+export type TenantRootResolver = (userId: string) => string;
+/**
+ * Back-compat resolver: <base>/<userId>/documents. Equivalent to
+ * documentsRoot() but parameterized by rootBase. Retained for sites that
+ * historically accepted a resolver function.
+ */
+export declare function makeTenantRootResolver(dataDir: string, rootBase: string): TenantRootResolver;
+/** <dataDir>/users/<userId>/documents — the document library root. */
+export declare function documentsRoot(dataDir: string, userId: string, rootBase?: string): string;
+/** <dataDir>/users/<userId>/documents/<shardId> — user docs produced by shard. */
+export declare function shardDocumentsPath(dataDir: string, userId: string, shardId: string, rootBase?: string): string;
+/** <dataDir>/users/<userId>/<shardId> — shard-internal per-user state. */
+export declare function shardStatePath(dataDir: string, userId: string, shardId: string, rootBase?: string): string;

package/dist/tenant-fs/paths.js

@@ -0,0 +1,51 @@
+/**
+ * Tenant path helpers — the framework owns the `data/users/<id>/...` layout.
+ *
+ * Two tiers:
+ *   users/<id>/<shardId>/           — shard's private per-user state (internal)
+ *   users/<id>/documents/<shardId>/ — user-facing files (exposed via /api/fs)
+ *
+ * Shards call these helpers server-side. Clients use /api/fs/* to reach
+ * documents/ only — shard state is never served over HTTP.
+ */
+import { mkdirSync } from 'node:fs';
+import { isAbsolute, join, normalize, resolve } from 'node:path';
+function resolveBase(dataDir, rootBase) {
+    if (rootBase === '')
+        return join(dataDir, 'users');
+    return isAbsolute(rootBase) ? normalize(rootBase) : resolve(dataDir, rootBase);
+}
+/**
+ * Back-compat resolver: <base>/<userId>/documents. Equivalent to
+ * documentsRoot() but parameterized by rootBase. Retained for sites that
+ * historically accepted a resolver function.
+ */
+export function makeTenantRootResolver(dataDir, rootBase) {
+    const base = resolveBase(dataDir, rootBase);
+    return (userId) => {
+        const root = join(base, userId, 'documents');
+        mkdirSync(root, { recursive: true });
+        return root;
+    };
+}
+/** <dataDir>/users/<userId>/documents — the document library root. */
+export function documentsRoot(dataDir, userId, rootBase = '') {
+    const base = resolveBase(dataDir, rootBase);
+    const p = join(base, userId, 'documents');
+    mkdirSync(p, { recursive: true });
+    return p;
+}
+/** <dataDir>/users/<userId>/documents/<shardId> — user docs produced by shard. */
+export function shardDocumentsPath(dataDir, userId, shardId, rootBase = '') {
+    const base = resolveBase(dataDir, rootBase);
+    const p = join(base, userId, 'documents', shardId);
+    mkdirSync(p, { recursive: true });
+    return p;
+}
+/** <dataDir>/users/<userId>/<shardId> — shard-internal per-user state. */
+export function shardStatePath(dataDir, userId, shardId, rootBase = '') {
+    const base = resolveBase(dataDir, rootBase);
+    const p = join(base, userId, shardId);
+    mkdirSync(p, { recursive: true });
+    return p;
+}

package/dist/tenant-fs/resolve.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Containment helper — resolves a relative path under a tenant root and
+ * asserts the real resolved path stays inside the root. Use this for ANY
+ * file I/O that accepts a path from the client.
+ *
+ * - Resolves `rel` against `root`.
+ * - Calls fs.realpath to follow symlinks.
+ * - If the target does not exist yet (e.g. future write ops), realpath
+ *   walks up to the deepest existing ancestor and appends the remainder.
+ * - Throws TenantPathEscapeError if the real path is not root or a descendant.
+ */
+export declare class TenantPathEscapeError extends Error {
+    readonly rel: string;
+    constructor(rel: string);
+}
+export declare function resolveTenantPath(root: string, rel: string): Promise<string>;