@celestea/studio 2.7.1

package/dist/handlers/exec.js

@@ -0,0 +1,131 @@
+/**
+ * `POST /api/exec` (iteration G2) — run a shell command NOW, with no model in
+ * the loop. `/run <cmd>` and `!<cmd>` are the UI's callers.
+ *
+ * Three rules from `docs/iteration-g-workbench.md` §1:
+ *   1. it reuses the run_shell execution path — the SAME `selectSandboxDetailed`
+ *      policy, `sessionSandboxConfig` (workdir/root), `sanitizedEnv` allowlist
+ *      and output cap the engine's `run_shell` uses, so isolation cannot fork;
+ *   2. it passes the PERMISSION gate: a preset that denies `run_shell`, or a
+ *      sandbox policy that refuses to execute, is a structured refusal — never a
+ *      silent run;
+ *   3. it is NOT a tool: nothing here touches the model-visible tool face.
+ *
+ * The `sandbox` block carries ONLY the contract fields (provider / net_isolated
+ * / tmp_private / seccomp + optional cpu_sec), never host diagnostics.
+ */
+import { selectSandboxDetailed, sessionSandboxConfig } from "@celestea/tools";
+import { effectiveGrantsOf } from "../runtime/engine-grants.js";
+import { nowSec } from "../store/grants-service.js";
+import { sessionWorkspaceOf } from "../store/sessions.js";
+import { errText } from "../store/result.js";
+import { failJson, readJsonBody, strField } from "./common.js";
+/** The structured refusal when this session's preset denies the shell. */
+export const SHELL_DENIED_CODE = "shell_denied";
+function readCommand(body) {
+    const value = body["command"];
+    if (typeof value !== "string")
+        return { error: "field 'command' must be a string" };
+    if (value.trim() === "")
+        return { error: "field 'command' must not be empty" };
+    return value;
+}
+/** Resolve the target session (explicit id, else the detached/default scope). */
+function targetSession(deps, id) {
+    if (id === undefined || id === "")
+        return { resolved: null, status: 0, error: "" };
+    const resolved = deps.sessions.require(id);
+    if (resolved.ok)
+        return { resolved: resolved.value, status: 0, error: "" };
+    return { resolved: null, status: resolved.status, error: resolved.error };
+}
+/**
+ * The session's shell is denied when the permission baseline's `toolDeny`
+ * contains `run_shell`. Read through the SAME grant reader the tool face uses,
+ * so the UI cannot disagree with what a turn would allow.
+ */
+function shellDeniedReason(deps, resolved) {
+    const dir = resolved?.dir ?? null;
+    const sessionId = resolved?.id ?? null;
+    const grants = effectiveGrantsOf(dir, sessionId, deps.grants.env, nowSec(deps.grants));
+    if (grants.grants.toolDeny.includes("run_shell")) {
+        return "this session's permission preset denies run_shell; grant a preset that allows the shell (or widen it) and retry";
+    }
+    return null;
+}
+/**
+ * The execution boundary of the target session, exactly as the engine composes
+ * it: provider policy + session scope + grants. Denied -> `{sandbox}` is a
+ * RefusingSandbox whose `run` throws the structured policy error.
+ */
+function sandboxFor(deps, resolved) {
+    const env = deps.grants.env;
+    const sessionId = resolved?.id ?? null;
+    const dir = resolved?.dir ?? null;
+    const grants = effectiveGrantsOf(dir, sessionId, env, nowSec(deps.grants)).grants;
+    const scope = resolved === null ? null : (sessionWorkspaceOf(resolved) === null ? null : { workspace: resolved.wsPath });
+    const config = sessionSandboxConfig(scope, env);
+    const selection = selectSandboxDetailed({
+        env,
+        grants: { network: grants.network, unsandboxed: grants.unsandboxed, workspaceWritable: grants.workspaceWritable, writeRoots: grants.writeRoots },
+        config,
+    });
+    return selection.sandbox;
+}
+/** Only the contract's four fields + optional cpu_sec (never host diagnostics). */
+function sandboxView(result) {
+    const meta = result.sandbox;
+    return {
+        provider: meta.provider,
+        net_isolated: meta.net_isolated,
+        tmp_private: meta.tmp_private,
+        seccomp: meta.seccomp,
+        ...(meta.cpu_sec === undefined ? {} : { cpu_sec: meta.cpu_sec }),
+    };
+}
+export function registerExec(app, deps, table) {
+    const route = table.get("post_exec");
+    app.on(route.method, route.honoPath, async (c) => {
+        const body = await readJsonBody(c);
+        if (!body.ok)
+            return body.response;
+        const sessionField = strField(c, body.body, "session");
+        if (!sessionField.ok)
+            return sessionField.response;
+        const workdirField = strField(c, body.body, "workdir");
+        if (!workdirField.ok)
+            return workdirField.response;
+        const command = readCommand(body.body);
+        if (typeof command !== "string")
+            return failJson(c, 422, command.error);
+        const target = targetSession(deps, sessionField.value);
+        if (target.status !== 0)
+            return failJson(c, target.status, target.error);
+        const denied = shellDeniedReason(deps, target.resolved);
+        if (denied !== null)
+            return failJson(c, 403, denied, { code: SHELL_DENIED_CODE });
+        const sandbox = sandboxFor(deps, target.resolved);
+        const started = Date.now();
+        try {
+            const run = await sandbox.run({
+                command,
+                ...(workdirField.value === undefined ? {} : { workdir: workdirField.value }),
+                ...(typeof body.body["timeout_ms"] === "number" ? { timeoutMs: body.body["timeout_ms"] } : {}),
+            });
+            return c.json({
+                ok: true,
+                exit_code: run.exit_code,
+                signal: run.signal ?? null,
+                stdout: run.stdout,
+                stderr: run.stderr,
+                duration_ms: Date.now() - started,
+                sandbox: sandboxView(run),
+            });
+        }
+        catch (e) {
+            // A sandbox/policy failure is a structured refusal, never a 500 guess.
+            return failJson(c, 400, errText(e));
+        }
+    });
+    return [route.id];
+}

package/dist/handlers/fs-read.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `GET /api/fs/read` (iteration G follow-up) — read ONE file for the file
+ * manager's viewer. Before this endpoint the Win-style manager could list a
+ * directory but not OPEN a file (F2's preview P0 only rendered content the
+ * session already had).
+ *
+ * Frozen wire format (`docs/iteration-g-workbench.md` §0.1 follow-up):
+ *   200: { path, size, kind: "text"|"binary", text, offset, limit, totalLines, truncated }
+ *   4xx: { error, code? }
+ *
+ * Semantics are the `read_file` TOOL's, not a second rulebook:
+ *   - read-only; `path` must be absolute;
+ *   - a directory is an error (EISDIR), never a listing;
+ *   - binary detection shares the tool's sniff window (`BINARY_SNIFF_BYTES`):
+ *     a NUL/C0 control (except \t \n \r \f ESC) or a fatal UTF-8 decode means
+ *     `kind: "binary"` and NO body text;
+ *   - the byte budget is `MAX_READ_BYTES` (256 KiB) and pagination is
+ *     `offset` (1-based line) + `limit` (lines, default `DEFAULT_READ_LIMIT`);
+ *     an over-budget / beyond-window read sets `truncated: true` EXPLICITLY.
+ *
+ * Trust boundary: this endpoint shares `GET /api/fs/list`'s exactly — it is
+ * read-only, it never follows a symbolic link (the same discipline the listing
+ * applies to entries), and it has NO auth of its own: the server binds loopback
+ * by default, and a non-loopback bind is refused unless a token is configured
+ * (see `auth/api-token.ts`). It must never be widened without that gate.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import type { Deps } from "./common.js";
+/** The frozen 200 body. */
+export interface FsReadBody {
+    path: string;
+    size: number;
+    kind: "text" | "binary";
+    /** The requested window; "" for a binary file (never decoded). */
+    text: string;
+    /** 1-based first line of the returned window. */
+    offset: number;
+    /** Effective line budget. */
+    limit: number;
+    /** Lines in the file (0 for a binary file). */
+    totalLines: number;
+    /** true when the response is a WINDOW (more lines and/or the 256 KiB budget). */
+    truncated: boolean;
+}
+type ReadOutcome = {
+    ok: true;
+    body: FsReadBody;
+} | {
+    ok: false;
+    error: string;
+    code: string;
+};
+/** NUL, or a C0 control other than \t (09) \n (0a) \r (0d) \f (0c) ESC (1b). */
+export declare function hasBinaryControl(bytes: Buffer): boolean;
+/** true when the window is not valid UTF-8 (fatal decode throws). */
+export declare function isFatalUtf8(bytes: Buffer): boolean;
+/** The shared `read_file` rule: control bytes or invalid UTF-8 ⇒ binary. */
+export declare function classifyBytes(bytes: Buffer): "text" | "binary";
+/** Read one file for the API (exported for the unit tests). */
+export declare function readFileForApi(path: string, offset: number, limit: number): Promise<ReadOutcome>;
+export declare function registerFsRead(app: Hono, _deps: Deps, table: RouteTable): string;
+export {};

package/dist/handlers/fs-read.js

@@ -0,0 +1,159 @@
+/**
+ * `GET /api/fs/read` (iteration G follow-up) — read ONE file for the file
+ * manager's viewer. Before this endpoint the Win-style manager could list a
+ * directory but not OPEN a file (F2's preview P0 only rendered content the
+ * session already had).
+ *
+ * Frozen wire format (`docs/iteration-g-workbench.md` §0.1 follow-up):
+ *   200: { path, size, kind: "text"|"binary", text, offset, limit, totalLines, truncated }
+ *   4xx: { error, code? }
+ *
+ * Semantics are the `read_file` TOOL's, not a second rulebook:
+ *   - read-only; `path` must be absolute;
+ *   - a directory is an error (EISDIR), never a listing;
+ *   - binary detection shares the tool's sniff window (`BINARY_SNIFF_BYTES`):
+ *     a NUL/C0 control (except \t \n \r \f ESC) or a fatal UTF-8 decode means
+ *     `kind: "binary"` and NO body text;
+ *   - the byte budget is `MAX_READ_BYTES` (256 KiB) and pagination is
+ *     `offset` (1-based line) + `limit` (lines, default `DEFAULT_READ_LIMIT`);
+ *     an over-budget / beyond-window read sets `truncated: true` EXPLICITLY.
+ *
+ * Trust boundary: this endpoint shares `GET /api/fs/list`'s exactly — it is
+ * read-only, it never follows a symbolic link (the same discipline the listing
+ * applies to entries), and it has NO auth of its own: the server binds loopback
+ * by default, and a non-loopback bind is refused unless a token is configured
+ * (see `auth/api-token.ts`). It must never be widened without that gate.
+ */
+import { lstatSync } from "node:fs";
+import { open } from "node:fs/promises";
+import { BINARY_SNIFF_BYTES, DEFAULT_READ_LIMIT, isToolFailure, readTextLines } from "@celestea/tools";
+import { isAbsolutePath } from "../store/session-id.js";
+import { errText } from "../store/result.js";
+/** NUL, or a C0 control other than \t (09) \n (0a) \r (0d) \f (0c) ESC (1b). */
+export function hasBinaryControl(bytes) {
+    for (const byte of bytes) {
+        if (byte === 0)
+            return true;
+        if (byte < 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d && byte !== 0x0c && byte !== 0x1b)
+            return true;
+    }
+    return false;
+}
+/** true when the window is not valid UTF-8 (fatal decode throws). */
+export function isFatalUtf8(bytes) {
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/** The shared `read_file` rule: control bytes or invalid UTF-8 ⇒ binary. */
+export function classifyBytes(bytes) {
+    if (hasBinaryControl(bytes))
+        return "binary";
+    return isFatalUtf8(bytes) ? "binary" : "text";
+}
+/** Sniff the first `BINARY_SNIFF_BYTES` bytes (the tool's own window). */
+async function sniffKind(path, size) {
+    if (size === 0)
+        return "text";
+    const handle = await open(path, "r");
+    try {
+        const length = Math.min(size, BINARY_SNIFF_BYTES);
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, 0);
+        return classifyBytes(buffer.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/** Validate one positive-integer query param. */
+function positiveInt(raw, fallback, name) {
+    if (raw === undefined || raw.trim() === "")
+        return { value: fallback };
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || String(parsed) !== raw.trim()) {
+        return { error: `query '${name}' must be a positive integer (got ${JSON.stringify(raw)})`, code: `invalid_${name}` };
+    }
+    return { value: parsed };
+}
+function lstatOutcome(path) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return { error: `path '${path}' does not exist`, code: "not_found" };
+        return { error: `cannot read '${path}': ${errText(e)}`, code: "io_error" };
+    }
+    // Same discipline as the listing: a link is reported, never traversed.
+    if (stat.isSymbolicLink())
+        return { error: `path '${path}' is a symbolic link; links are not followed`, code: "symlink" };
+    if (stat.isDirectory())
+        return { error: `path '${path}' is a directory, not a file`, code: "is_directory" };
+    return { size: stat.size };
+}
+/** Read one file for the API (exported for the unit tests). */
+export async function readFileForApi(path, offset, limit) {
+    if (!isAbsolutePath(path))
+        return { ok: false, error: `path '${path}' must be absolute`, code: "not_absolute" };
+    const meta = lstatOutcome(path);
+    if ("error" in meta)
+        return { ok: false, error: meta.error, code: meta.code };
+    const binaryBody = (kind) => ({ path, size: meta.size, kind, text: "", offset, limit, totalLines: 0, truncated: false });
+    let kind;
+    try {
+        kind = await sniffKind(path, meta.size);
+    }
+    catch (e) {
+        return { ok: false, error: `cannot read '${path}': ${errText(e)}`, code: "io_error" };
+    }
+    if (kind === "binary")
+        return { ok: true, body: binaryBody("binary") };
+    try {
+        const window = await readTextLines(path, offset - 1, limit);
+        return {
+            ok: true,
+            body: {
+                path,
+                size: meta.size,
+                kind: "text",
+                text: window.text,
+                offset: window.offset + 1,
+                limit: window.limit,
+                totalLines: window.totalLines,
+                truncated: window.truncated || window.hasMore,
+            },
+        };
+    }
+    catch (e) {
+        // A NUL beyond the sniff window: the tool says binary; classify the same way.
+        if (isToolFailure(e) && e.kind === "binary_file")
+            return { ok: true, body: binaryBody("binary") };
+        return { ok: false, error: `cannot read '${path}': ${errText(e)}`, code: "io_error" };
+    }
+}
+export function registerFsRead(app, _deps, table) {
+    const route = table.get("get_fs_read");
+    app.on(route.method, route.honoPath, async (c) => {
+        const path = (c.req.query("path") ?? "").trim();
+        if (path === "")
+            return c.json({ error: "query 'path' is required", code: "missing_path" }, 400);
+        const offset = positiveInt(c.req.query("offset"), 1, "offset");
+        if ("error" in offset)
+            return c.json({ error: offset.error, code: offset.code }, 400);
+        const limit = positiveInt(c.req.query("limit"), DEFAULT_READ_LIMIT, "limit");
+        if ("error" in limit)
+            return c.json({ error: limit.error, code: limit.code }, 400);
+        const out = await readFileForApi(path, offset.value, limit.value);
+        if (!out.ok)
+            return c.json({ error: out.error, code: out.code }, 400);
+        return c.json(out.body);
+    });
+    return route.id;
+}

package/dist/handlers/fs.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `GET /api/fs/browse` — `src/workspaces.rs:700-766` — iteration G's
+ * `GET /api/fs/list` (the Win-style file manager's read-only listing) and its
+ * follow-up `GET /api/fs/read` (the viewer; see `fs-read.ts`).
+ *
+ * `browse` lists DIRECTORY names only (the legacy shape). `list` lists
+ * directories AND files as `{name,type,size,mtime}`, reusing the same
+ * discipline: absolute path, dot-names hidden, symlinks never followed, sorted,
+ * capped at `MAX_DIR_ENTRIES` (with an explicit `truncated` flag). `read`
+ * applies that SAME discipline to one file (never follows a link, same trust
+ * boundary) and shares the `read_file` tool's binary/pagination rules.
+ *
+ * Wire format is FROZEN by `docs/iteration-g-workbench.md` §0.1:
+ *   type: "dir" | "file"      (a symlink is reported as the link itself, i.e.
+ *                              "file" when it is not a directory — never followed)
+ *   mtime: ISO-8601 string    (null when `lstat` cannot read it)
+ * `roots` and `truncated` are ADDITIVE fields on top of that frozen minimum.
+ *
+ * `roots` is a hardcoded informational constant — listing is NOT restricted to
+ * it; the endpoints have no auth, which is why the default bind is loopback.
+ *
+ * W885 (W883 E3): "absolute" and "parent" are PLATFORM questions, not
+ * `startsWith("/")` and `lastIndexOf("/")`. The path helpers take the platform
+ * as an argument, so the win32 rules are unit-tested on Linux; the routes
+ * themselves still run under the host's own platform.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import type { Deps } from "./common.js";
+/** One entry of `GET /api/fs/list` (frozen shape, §0.1). */
+export interface FsListEntry {
+    name: string;
+    /** `dir` for a directory; `file` for everything else (symlinks NOT followed). */
+    type: "dir" | "file";
+    /** Bytes for files / symlinks; `null` for directories. */
+    size: number | null;
+    /** ISO-8601 mtime from `lstat`; null when it could not be read. */
+    mtime: string | null;
+}
+/** Absolute under `platform` (`C:\…`, `\\\\server\\share`, `/…`). */
+export declare function isBrowsablePath(path: string, platform?: string): boolean;
+/**
+ * The parent directory of `path`, never above the filesystem root: `C:\` is
+ * its own parent on Windows, `/` on POSIX, `\\\\server\\share\\` on a UNC share.
+ */
+export declare function browseParent(path: string, platform?: string): string;
+/**
+ * The Win-style listing: directories first, then files, each by name; dot-names
+ * hidden; a symlink is `file` (its own lstat, never the target).
+ */
+export declare function listDirectory(path: string): {
+    entries: FsListEntry[];
+    truncated: boolean;
+} | {
+    error: string;
+};
+export declare function registerFs(app: Hono, _deps: Deps, table: RouteTable): string[];

package/dist/handlers/fs.js

@@ -0,0 +1,153 @@
+/**
+ * `GET /api/fs/browse` — `src/workspaces.rs:700-766` — iteration G's
+ * `GET /api/fs/list` (the Win-style file manager's read-only listing) and its
+ * follow-up `GET /api/fs/read` (the viewer; see `fs-read.ts`).
+ *
+ * `browse` lists DIRECTORY names only (the legacy shape). `list` lists
+ * directories AND files as `{name,type,size,mtime}`, reusing the same
+ * discipline: absolute path, dot-names hidden, symlinks never followed, sorted,
+ * capped at `MAX_DIR_ENTRIES` (with an explicit `truncated` flag). `read`
+ * applies that SAME discipline to one file (never follows a link, same trust
+ * boundary) and shares the `read_file` tool's binary/pagination rules.
+ *
+ * Wire format is FROZEN by `docs/iteration-g-workbench.md` §0.1:
+ *   type: "dir" | "file"      (a symlink is reported as the link itself, i.e.
+ *                              "file" when it is not a directory — never followed)
+ *   mtime: ISO-8601 string    (null when `lstat` cannot read it)
+ * `roots` and `truncated` are ADDITIVE fields on top of that frozen minimum.
+ *
+ * `roots` is a hardcoded informational constant — listing is NOT restricted to
+ * it; the endpoints have no auth, which is why the default bind is loopback.
+ *
+ * W885 (W883 E3): "absolute" and "parent" are PLATFORM questions, not
+ * `startsWith("/")` and `lastIndexOf("/")`. The path helpers take the platform
+ * as an argument, so the win32 rules are unit-tested on Linux; the routes
+ * themselves still run under the host's own platform.
+ */
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { FS_ROOTS, MAX_DIR_ENTRIES } from "../config.js";
+import { isAbsolutePath, parentDir, rootOf } from "../store/session-id.js";
+import { errText } from "../store/result.js";
+import { registerFsRead } from "./fs-read.js";
+/** Absolute under `platform` (`C:\…`, `\\\\server\\share`, `/…`). */
+export function isBrowsablePath(path, platform = process.platform) {
+    return isAbsolutePath(path, platform);
+}
+/**
+ * The parent directory of `path`, never above the filesystem root: `C:\` is
+ * its own parent on Windows, `/` on POSIX, `\\\\server\\share\\` on a UNC share.
+ */
+export function browseParent(path, platform = process.platform) {
+    const root = rootOf(path, platform);
+    const trimmed = stripTrailingSeparators(path, platform);
+    if (trimmed === "" || trimmed === root)
+        return root === "" ? path : root;
+    const parent = parentDir(trimmed, platform);
+    return parent === "" ? root : parent;
+}
+/** `/a/b/` -> `/a/b`; a bare root keeps its separator (`C:\`, `/`). */
+function stripTrailingSeparators(path, platform) {
+    if (path === rootOf(path, platform))
+        return path;
+    let out = path;
+    while (out.length > 1 && (out.endsWith("/") || out.endsWith("\\")))
+        out = out.slice(0, -1);
+    return out;
+}
+function browseDirs(path) {
+    if (!isBrowsablePath(path))
+        return { error: "path '" + path + "' must be absolute" };
+    const read = readDirectory(path);
+    if ("error" in read)
+        return read;
+    const dirs = [];
+    for (const entry of read.entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        dirs.push(entry.name);
+    }
+    dirs.sort();
+    return { dirs: dirs.slice(0, MAX_DIR_ENTRIES) };
+}
+/** Read a directory, mapping the two expected failures onto the frozen texts. */
+function readDirectory(path) {
+    try {
+        return { entries: readdirSync(path, { withFileTypes: true }) };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { error: "path '" + path + "' is not an existing directory" };
+        return { error: "cannot read '" + path + "': " + errText(e) };
+    }
+}
+/**
+ * The Win-style listing: directories first, then files, each by name; dot-names
+ * hidden; a symlink is `file` (its own lstat, never the target).
+ */
+export function listDirectory(path) {
+    if (!isBrowsablePath(path))
+        return { error: "path '" + path + "' must be absolute" };
+    const read = readDirectory(path);
+    if ("error" in read)
+        return read;
+    const entries = [];
+    for (const entry of read.entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        entries.push(describeEntry(path, entry.name, entry));
+    }
+    entries.sort(compareEntries);
+    const truncated = entries.length > MAX_DIR_ENTRIES;
+    return { entries: entries.slice(0, MAX_DIR_ENTRIES), truncated };
+}
+function describeEntry(dir, name, dirent) {
+    const type = dirent.isDirectory() ? "dir" : "file";
+    let size = null;
+    let mtime = null;
+    try {
+        // lstat, not stat: a symlink is never followed to its target.
+        const info = lstatSync(join(dir, name));
+        size = info.isDirectory() ? null : info.size;
+        mtime = new Date(info.mtimeMs).toISOString();
+    }
+    catch {
+        // The entry vanished between readdir and lstat: keep it, with unknown stats.
+    }
+    return { name, type, size, mtime };
+}
+function compareEntries(a, b) {
+    const aDir = a.type === "dir" ? 0 : 1;
+    const bDir = b.type === "dir" ? 0 : 1;
+    if (aDir !== bDir)
+        return aDir - bDir;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+export function registerFs(app, _deps, table) {
+    const browse = table.get("get_fs_browse");
+    const list = table.get("get_fs_list");
+    app.on(browse.method, browse.honoPath, (c) => {
+        const asked = (c.req.query("path") ?? "").trim();
+        const raw = asked === "" ? "/" : asked;
+        const out = browseDirs(raw);
+        if ("error" in out) {
+            const body = { path: raw, parent: null, dirs: [], roots: FS_ROOTS, error: out.error };
+            return c.json(body, 400);
+        }
+        const body = { path: raw, parent: browseParent(raw), dirs: out.dirs, roots: FS_ROOTS };
+        return c.json(body);
+    });
+    app.on(list.method, list.honoPath, (c) => {
+        const asked = (c.req.query("path") ?? "").trim();
+        const raw = asked === "" ? "/" : asked;
+        const out = listDirectory(raw);
+        if ("error" in out) {
+            const body = { path: raw, parent: null, entries: [], roots: FS_ROOTS, truncated: false, error: out.error };
+            return c.json(body, 400);
+        }
+        const body = { path: raw, parent: browseParent(raw), entries: out.entries, roots: FS_ROOTS, truncated: out.truncated };
+        return c.json(body);
+    });
+    return [browse.id, list.id, registerFsRead(app, _deps, table)];
+}

package/dist/handlers/grants-shape.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Request parsing / response shaping for the grant endpoints (W516 §6).
+ *
+ * Kept apart from the routes so both stay inside the architecture budget: the
+ * error strings here are the FROZEN contract strings of §6.2, and a rejected
+ * scope value is never echoed (§5.4 — it may be a credential).
+ */
+import type { Context } from "hono";
+import type { EffectiveGrants } from "../runtime/engine-grants.js";
+import { type GrantCap, type GrantRecord, type GrantScope } from "../store/grants.js";
+import { type JsonObject } from "./common.js";
+/** Who the grant is attributed to. Server-side constant: never model text. */
+export declare const GRANT_ACTOR = "ui:operator";
+export interface GrantRequest {
+    cap: GrantCap;
+    scope: GrantScope;
+    ttlSec: number;
+    usesLeft: number | null;
+    note: string;
+    /** Canonical hash of `(cap, scope)` — what the confirm token is bound to. */
+    scopeHash: string;
+}
+/** A refused body: the response to send plus the SANITIZED reason to audit. */
+export type GrantRequestBody = {
+    ok: true;
+    value: GrantRequest;
+} | {
+    ok: false;
+    response: Response;
+    reason: string;
+};
+/** §6.2 body: `{cap, scope?, ttl_sec?, uses_left?, note?}` + the frozen 400s. */
+export declare function parseGrantRequest(c: Context, body: JsonObject, env: NodeJS.ProcessEnv): GrantRequestBody;
+/**
+ * The cap must be known AND offered here: `unsandboxed` only exists behind
+ * `CELESTEA_GRANTS_ALLOW_UNSANDBOXED=1` (§2.2), so without it the cap is simply
+ * not valid — the frozen `invalid cap '<x>'` error, never a special case.
+ */
+export declare function offeredCap(raw: string, env: NodeJS.ProcessEnv): GrantCap | null;
+/** `ttl_sec`: positive integer, 0 = no expiry, capped per cap (§2.3). */
+export declare function readTtl(c: Context, body: JsonObject, cap: GrantCap): number | Response;
+/** One GET entry: the stored record plus the read-time `expired` flag (§6.1). */
+export declare function entryJson(record: GrantRecord, now: number): JsonObject;
+/** The `effective` snapshot of §6.1 (snake_case; the UI shows it verbatim). */
+export declare function effectiveJson(grants: EffectiveGrants): JsonObject;