@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/server/routes/extension-routes.js

@@ -0,0 +1,127 @@
+/**
+ * Extension HTTP routes (core hardening W5 Task 2, spec §9.2): every
+ * `routes` contribution a loaded extension declared, mounted at
+ * `/v1/ext/<slug>/<path>` behind a web-standard Request/Response
+ * adapter — no Fastify type crosses the extension contract.
+ *
+ * Mount shape: each extension's routes register inside ONE ENCAPSULATED
+ * Fastify plugin scope that parses EVERY content type as a raw buffer —
+ * the built-in JSON/text/plain parsers AND the app-level text/plain
+ * parser are removed inside the scope, then a `"*"` catch-all buffer
+ * parser covers every content type — so the app's core routes keep
+ * their own parsers (encapsulation contains the override) and the
+ * adapter always sees the raw bytes. `bodyLimit` rides the route
+ * options (default 1 MiB, spec §9.2); Fastify's
+ * `FST_ERR_CTP_BODY_TOO_LARGE` maps to `413 too_large` through the app
+ * error handler.
+ *
+ * Auth (the §5 pipeline plus the route's declared `auth`):
+ * - `public` — the pipeline skips stage 5 (authentication) ONLY: stages
+ *   1 (Host/Origin) and 4 (the unclaimed setup gate) still ran, and the
+ *   handler verifies its own caller (a webhook signature, an OAuth
+ *   `state`). No principal is attached.
+ * - `user` — the pipeline authenticates like every other `/v1` route.
+ * - `admin` — authenticated AND `principal.admin`, else 403.
+ *
+ * The adapter builds `new Request(absoluteUrl, {method, headers,
+ * body})` — `absoluteUrl` is `server.publicUrl` (`SIGRUN_PUBLIC_URL`)
+ * when set, else `http://<Host header>` — and writes the returned
+ * `Response`'s status, headers, and body back to the reply. A handler
+ * that THROWS or returns a non-`Response` maps to
+ * `500 {error: "extension_route_failed", extension}` (logged; the
+ * process never crashes). The handler's `Request` body may be read ONCE
+ * per the web standard (a second `text()` rejects "Body is unusable");
+ * the adapter hands it a fresh `Request` over the buffered body and
+ * needs no handling for that.
+ */
+/** The default ext-route body ceiling (spec §9.2): 1 MiB. */
+export const DEFAULT_EXT_ROUTE_BODY_LIMIT = 1_048_576;
+/** Headers the reply owns — forwarding them would fight Fastify's framing. */
+const HOP_BY_HOP = new Set(["transfer-encoding", "connection"]);
+/**
+ * Mount every collected extension route. Called from `createServer`
+ * AFTER the auth pipeline (the root-level onRequest hook applies to the
+ * encapsulated scopes' routes too); a boot with no route bindings
+ * registers nothing.
+ */
+export function registerExtensionRoutes(app, ctx) {
+    const { opened, config } = ctx;
+    for (const binding of opened.extensionRoutes) {
+        // The handler context's `host` is the extension's seam host — the
+        // contract's `SigrunHost` seam surface. The conversation/identity/
+        // access members land with the host bridge (W5 Task 5 extends
+        // SeamHost to the full contract shape); the cast spans that gap
+        // without widening this task, and routes that never touch the
+        // not-yet-bridged members are unaffected.
+        const host = opened.seamHosts.get(binding.extension);
+        app.register(async (scope) => {
+            // Raw bodies for this extension's routes ONLY: the encapsulated
+            // scope drops the inherited parsers (the built-ins and whatever
+            // the app registered) and installs one catch-all buffer parser —
+            // `addContentTypeParser("*")` alone would NOT override them, and
+            // a JSON webhook body would arrive pre-parsed.
+            scope.removeContentTypeParser("application/json");
+            scope.removeContentTypeParser("text/plain");
+            scope.addContentTypeParser("*", { parseAs: "buffer" }, (_request, body, done) => done(null, body));
+            for (const route of binding.routes) {
+                scope.route({
+                    method: route.method,
+                    url: `/v1/ext/${binding.extension}/${route.path}`,
+                    bodyLimit: route.bodyLimit ?? DEFAULT_EXT_ROUTE_BODY_LIMIT,
+                    // The auth pipeline's stage-4b read (public skips stage 5).
+                    config: { extAuth: route.auth },
+                    handler: async (request, reply) => {
+                        if (route.auth === "admin" && request.principal?.admin !== true) {
+                            return await reply.code(403).send({ error: "forbidden" });
+                        }
+                        try {
+                            const base = config.publicUrl ??
+                                `http://${request.headers.host ?? "localhost"}`;
+                            const incoming = new Request(`${base}${request.url}`, {
+                                method: request.method,
+                                headers: request.headers,
+                                // The scope's catch-all parser hands the raw bytes; unknown
+                                // at the type level (Fastify cannot know the parser shape),
+                                // and undici accepts a Buffer as BodyInit at runtime.
+                                ...(request.body === undefined
+                                    ? {}
+                                    : { body: request.body }),
+                            });
+                            const response = await route.handler(incoming, {
+                                ...(request.principal === undefined
+                                    ? {}
+                                    : { principal: request.principal }),
+                                host: host,
+                            });
+                            if (!(response instanceof Response)) {
+                                throw new Error(`returned a non-Response (${typeof response})`);
+                            }
+                            reply.code(response.status);
+                            for (const [name, value] of response.headers) {
+                                if (HOP_BY_HOP.has(name))
+                                    continue;
+                                reply.header(name, value);
+                            }
+                            // set-cookie is the one multi-valued header the
+                            // spec's iterator joins (information loss); serve
+                            // each cookie as its own header.
+                            for (const cookie of response.headers.getSetCookie()) {
+                                reply.header("set-cookie", cookie);
+                            }
+                            const body = Buffer.from(await response.arrayBuffer());
+                            return await reply.send(body.length > 0 ? body : null);
+                        }
+                        catch (cause) {
+                            const mounted = `/v1/ext/${binding.extension}/${route.path}`;
+                            console.warn(`extension route failed: ${binding.extension} ${request.method} ${mounted}: ${cause instanceof Error ? cause.message : String(cause)}`);
+                            return await reply.code(500).send({
+                                error: "extension_route_failed",
+                                extension: binding.extension,
+                            });
+                        }
+                    },
+                });
+            }
+        });
+    }
+}

package/dist/server/routes/extensions.js

@@ -0,0 +1,168 @@
+/**
+ * Extension settings/secrets routes (core hardening W3 Task 7, spec
+ * §7.7): the operator surface over the loaded extension set.
+ *
+ * - `GET /v1/extensions` — one entry per loaded outcome with `status`,
+ *   `error?`, the manifest `version?`, the declared
+ *   `interactionKinds`/`ambientKeys`, and the idle-worker projection.
+ * - `GET`/`PUT /v1/extensions/:slug/settings` (PUT admin) — the
+ *   `settings/<slug>.json` object verbatim. Values an extension reads at
+ *   factory time apply at RESTART; per-run reads see the write live.
+ * - `GET /v1/extensions/:slug/secrets` — `{secrets: [{key, source}]}`:
+ *   stored keys plus the `SIGRUN_EXT_<SLUG>_` env fallbacks that are not
+ *   stored. VALUES ARE NEVER RETURNED by any route here — the API lists
+ *   and writes secrets, never reads them back.
+ * - `PUT`/`DELETE /v1/extensions/:slug/secrets/:key` (admin).
+ *
+ * Every `:slug` route 404s `extension_not_found` when the slug is not
+ * among the loaded outcomes (the same list `GET /v1/meta` reports).
+ */
+import { BUILTIN_EXTENSIONS } from "../../harness/builtins.js";
+/** Register the extension settings/secrets routes. */
+export function registerExtensionRoutes(app, ctx) {
+    const { opened } = ctx;
+    // The loaded-outcome lookup every :slug route gates on: ok outcomes
+    // carry the slug; quarantined outcomes carry the display specifier —
+    // both are "among the loaded outcomes" for the 404 rule.
+    const isKnownSlug = (slug) => opened.extensionOutcomes.some((outcome) => outcome.name === slug);
+    // The inventory: outcomes + declared kinds + workers + routes, one
+    // entry per configured extension, in load order. Pure synchronous
+    // derivations over boot-retained state (the /v1/meta discipline) — a
+    // client may cache it per boot. Built-in extensions (Task 2) carry
+    // `builtin: true` from their outcomes; a REPLACED built-in (a
+    // configured extension resolved to the same package name) appends a
+    // row here — `builtin: true`, `replacedBy` the configured specifier,
+    // status "replaced" — while a DISABLED one is absent entirely
+    // (ruling 6).
+    app.get("/v1/extensions", async () => {
+        const workerStatuses = opened.workerStatuses();
+        const extensions = opened.extensionOutcomes.map((outcome) => {
+            const kinds = opened.seamKinds.get(outcome.name);
+            const workers = workerStatuses.get(outcome.name);
+            const routes = opened.extensionRoutes.find((binding) => binding.extension === outcome.name);
+            return {
+                name: outcome.name,
+                status: outcome.status,
+                ...(outcome.error === undefined ? {} : { error: outcome.error }),
+                ...(outcome.version === undefined
+                    ? {}
+                    : { version: outcome.version }),
+                ...(outcome.builtin === true ? { builtin: true } : {}),
+                interactionKinds: [...(kinds?.interaction ?? [])],
+                ambientKeys: [...(kinds?.ambient ?? [])],
+                workers: workers ?? [],
+                routes: routes?.routes.map((route) => ({
+                    method: route.method,
+                    path: route.path,
+                    auth: route.auth,
+                })) ?? [],
+            };
+        });
+        // Replaced built-ins (Task 2 ruling 5): one row each, under the slug
+        // the built-in itself would have loaded under (`BUILTIN_EXTENSIONS
+        // .slug` — the declared extension name's slug, e.g. `sigrun-mcp` for
+        // the package `@sigrun/ext-mcp`), appended after the loaded set.
+        for (const skipped of opened.builtinSkipped) {
+            if (skipped.reason !== "replaced")
+                continue;
+            const slug = BUILTIN_EXTENSIONS.find((builtin) => builtin.key === skipped.key)?.slug;
+            if (slug === undefined)
+                continue;
+            extensions.push({
+                name: slug,
+                status: "replaced",
+                builtin: true,
+                ...(skipped.by === undefined ? {} : { replacedBy: skipped.by }),
+                interactionKinds: [],
+                ambientKeys: [],
+                workers: [],
+                routes: [],
+            });
+        }
+        return { extensions };
+    });
+    // The per-extension settings object (`settings/<slug>.json`), absent
+    // file → `{}`. GET is ungated beyond the pipeline: settings values are
+    // operator-facing config, not secrets.
+    app.get("/v1/extensions/:slug/settings", async (request, reply) => {
+        const { slug } = request.params;
+        if (!isKnownSlug(slug)) {
+            return await reply.code(404).send({ error: "extension_not_found" });
+        }
+        return opened.extensionStores.settingsFor(slug).get();
+    });
+    // Replace the settings object VERBATIM (admin — a settings file is
+    // code-adjacent input the extension consumes). The body must be a
+    // JSON object; arrays/scalars are 400 (the PATCH /v1/settings
+    // vocabulary). The write lands live for per-run reads; a
+    // factory-time reader applies it at restart.
+    app.put("/v1/extensions/:slug/settings", async (request, reply) => {
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        const { slug } = request.params;
+        if (!isKnownSlug(slug)) {
+            return await reply.code(404).send({ error: "extension_not_found" });
+        }
+        const body = request.body;
+        if (typeof body !== "object" ||
+            body === null ||
+            Array.isArray(body)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const value = body;
+        await opened.extensionStores.settingsFor(slug).set(value);
+        return value;
+    });
+    // The secret key list: stored keys plus the env fallbacks that are not
+    // stored. Key names and sources only — the response never carries a
+    // value, and the store surface has no value-returning read at all.
+    app.get("/v1/extensions/:slug/secrets", async (request, reply) => {
+        const { slug } = request.params;
+        if (!isKnownSlug(slug)) {
+            return await reply.code(404).send({ error: "extension_not_found" });
+        }
+        return { secrets: await opened.extensionStores.secretKeys(slug) };
+    });
+    // Set one secret (admin): `{value: string}` — a non-empty string,
+    // nothing else (errors name the field, never the value). Returns the
+    // updated key list so the UI refreshes in one round-trip. The stored
+    // write takes precedence over any env twin from the next read on —
+    // the same `resolveSecretFor` rule the listing reports.
+    app.put("/v1/extensions/:slug/secrets/:key", async (request, reply) => {
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        const { slug, key } = request.params;
+        if (!isKnownSlug(slug)) {
+            return await reply.code(404).send({ error: "extension_not_found" });
+        }
+        const body = request.body;
+        if (typeof body !== "object" ||
+            body === null ||
+            Array.isArray(body) ||
+            typeof body.value !== "string" ||
+            body.value === "") {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "value" });
+        }
+        const { value } = body;
+        await opened.extensionStores.setSecret(slug, key, value);
+        return { secrets: await opened.extensionStores.secretKeys(slug) };
+    });
+    // Delete one secret (admin): an idempotent section-key removal —
+    // deleting an absent key is a no-op success, and an env-sourced key
+    // has nothing stored to delete (the env var is the deploy's).
+    app.delete("/v1/extensions/:slug/secrets/:key", async (request, reply) => {
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        const { slug, key } = request.params;
+        if (!isKnownSlug(slug)) {
+            return await reply.code(404).send({ error: "extension_not_found" });
+        }
+        await opened.extensionStores.deleteSecret(slug, key);
+        return { secrets: await opened.extensionStores.secretKeys(slug) };
+    });
+}

package/dist/server/routes/files.js

@@ -0,0 +1,308 @@
+/**
+ * Workspace file routes: upload — the raw §6.2 PUT (octet-stream bytes,
+ * `server.maxUploadBytes`-limited) plus the base64 POST it replaces in
+ * one release — the read-only directory listing, and file content (text
+ * when strictly valid UTF-8, else base64; size-capped). Every route
+ * resolves its conversation through the `loadConversation` pre-handler
+ * (404 for an unknown id) and reads the workspace through
+ * `conversationEnv` — one seam, so a workspace-service swap moves them
+ * all at once.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { extname } from "node:path";
+import { loadConversation } from "../conversation-handler.js";
+import { isConfinedPath } from "../content-parts.js";
+import { base64BodyLimit } from "../../config.js";
+import { ID_PARAMS_SCHEMA, FILE_CONTENT_MAX_BYTES, conversationEnv, decodeBase64Strict, } from "../helpers.js";
+/**
+ * The one upload-name rule, shared by the base64 POST body's `name` and
+ * the raw PUT's `:name` param: no `/` or `\\`, not `.` or `..`, non-empty.
+ * The PUT checks it AFTER Fastify decodes the percent-encoded param
+ * (`..%2Fx` arrives as `../x`, `%2e%2e` as `..`) — the check runs on the
+ * decoded value, never the raw path text.
+ */
+function validUploadName(name) {
+    return (name.length > 0 &&
+        !name.includes("/") &&
+        !name.includes("\\") &&
+        name !== "." &&
+        name !== "..");
+}
+/** The `:id` + `:name` params of the raw upload route. */
+const UPLOAD_PARAMS_SCHEMA = {
+    type: "object",
+    properties: { id: { type: "integer" }, name: { type: "string" } },
+    required: ["id", "name"],
+    additionalProperties: false,
+};
+/**
+ * The extension→mime map for the raw file read (spec §7.8): the common
+ * workspace-file extensions a client renders inline. A file whose
+ * extension is absent from the map serves `application/octet-stream`.
+ * The KEY is the LOWERCASE extension including the dot (the lookup
+ * lowercases, so `Photo.PNG` maps too).
+ */
+const MIME_BY_EXTENSION = new Map([
+    [".png", "image/png"],
+    [".jpg", "image/jpeg"],
+    [".jpeg", "image/jpeg"],
+    [".gif", "image/gif"],
+    [".webp", "image/webp"],
+    [".svg", "image/svg+xml"],
+    [".pdf", "application/pdf"],
+    [".txt", "text/plain"],
+    [".md", "text/markdown"],
+    [".json", "application/json"],
+    [".html", "text/html"],
+    [".css", "text/css"],
+    [".js", "text/javascript"],
+]);
+/** The raw read's streaming chunk size (1 MiB): bounds reader memory. */
+const RAW_READ_CHUNK_BYTES = 1024 * 1024;
+/** Register the upload/listing/content workspace file routes. */
+export function registerFileRoutes(app, ctx) {
+    const { opened, config } = ctx;
+    // Raw octet-stream bodies (the upload PUT route below): parse as a
+    // buffer, no interpretation. Registered once on the app — the route's
+    // own `bodyLimit` carries the knob.
+    app.addContentTypeParser("application/octet-stream", { parseAs: "buffer" }, (_request, body, done) => done(null, body));
+    // Uploads (raw): the §6.2 route phone photos need — the body is the
+    // file's bytes, the name rides the param, and the route's `bodyLimit`
+    // is the `server.maxUploadBytes` knob verbatim (no base64 inflation).
+    // An absent content-type defaults to `application/octet-stream` via the
+    // route-scoped onRequest below (Fastify would otherwise 415 an untyped
+    // non-empty body); the default applies ONLY to this route.
+    app.put("/v1/conversations/:id/uploads/:name", {
+        schema: { params: UPLOAD_PARAMS_SCHEMA },
+        // Uploads mutate the conversation: write access (spec §6.2).
+        preHandler: loadConversation(ctx, "write"),
+        bodyLimit: config.maxUploadBytes,
+        onRequest: async (request) => {
+            if (request.headers["content-type"] === undefined) {
+                request.headers["content-type"] = "application/octet-stream";
+            }
+        },
+    }, async (request, reply) => {
+        const conversation = request.conversation;
+        const { name } = request.params;
+        if (!validUploadName(name)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        // Fastify hands the parsed buffer (or nothing for a truly empty
+        // body — an empty file is a valid upload).
+        const bytes = request.body === undefined
+            ? new Uint8Array(0)
+            : new Uint8Array(request.body);
+        // Same namespace as the base64 route: v1 namespaces uploads per
+        // conversation, and the returned path is exactly what a content
+        // part takes.
+        const path = `uploads/${conversation.id}/${name}`;
+        const env = await conversationEnv(opened, conversation);
+        const written = await env.writeFile(path, bytes, BACKGROUND_CONTEXT);
+        if (!written.ok) {
+            // A failed upload is a server-side fault: fail loud.
+            throw written.error;
+        }
+        return await reply.code(201).send({ path });
+    });
+    // Uploads (base64, one more release): materialize a base64 body into
+    // the conversation's upload namespace via the workspace env (spec §5:
+    // correct for remote workspaces). The `bodyLimit` is the knob-derived
+    // ceiling — the base64 inflation of the capped content plus the JSON
+    // wrapper (spec §6.2).
+    app.post("/v1/conversations/:id/uploads", {
+        schema: { params: ID_PARAMS_SCHEMA },
+        preHandler: loadConversation(ctx, "write"),
+        bodyLimit: base64BodyLimit(config.maxUploadBytes),
+    }, async (request, reply) => {
+        const conversation = request.conversation;
+        const body = request.body;
+        const name = body?.name;
+        const contentBase64 = body?.contentBase64;
+        if (body === undefined ||
+            typeof name !== "string" ||
+            !validUploadName(name) ||
+            typeof contentBase64 !== "string") {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        let bytes;
+        try {
+            bytes = decodeBase64Strict(contentBase64);
+        }
+        catch {
+            bytes = undefined;
+        }
+        if (bytes === undefined) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        // v1 namespaces uploads per conversation: workspaces are static and
+        // shared in v1, so un-namespaced names would clobber across
+        // conversations. The returned path is exactly what a content part
+        // takes.
+        const path = `uploads/${conversation.id}/${name}`;
+        const env = await conversationEnv(opened, conversation);
+        const written = await env.writeFile(path, new Uint8Array(bytes), BACKGROUND_CONTEXT);
+        if (!written.ok) {
+            // A failed upload is a server-side fault: fail loud.
+            throw written.error;
+        }
+        return await reply.code(201).send({ path });
+    });
+    // Files: read-only workspace listing through the conversation env.
+    app.get("/v1/conversations/:id/files", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx) }, async (request, reply) => {
+        const conversation = request.conversation;
+        const query = request.query;
+        const path = query.path ?? ".";
+        if (!isConfinedPath(path)) {
+            return await reply.code(400).send({ error: "invalid_path" });
+        }
+        const env = await conversationEnv(opened, conversation);
+        const listed = await env.listDir(path, BACKGROUND_CONTEXT);
+        if (!listed.ok) {
+            if (listed.error.code === "not_found") {
+                return await reply.code(404).send({ error: "not_found" });
+            }
+            throw listed.error;
+        }
+        // pi-durable's listDir returns ABSOLUTE paths (resolve(cwd, name)),
+        // but the §5 files/content endpoint requires workspace-RELATIVE
+        // paths (isConfinedPath rejects absolute). Relativize each entry
+        // against the workspace root so the tree's paths feed back into the
+        // content endpoint (a listed file can be read).
+        const workspaceRoot = config.workspace.path;
+        const entries = listed.value.map((entry) => ({
+            ...entry,
+            path: entry.path.startsWith(`${workspaceRoot}/`)
+                ? entry.path.slice(workspaceRoot.length + 1)
+                : entry.path,
+        }));
+        return { entries };
+    });
+    // Files content: text when strictly valid UTF-8, else base64; size-capped.
+    app.get("/v1/conversations/:id/files/content", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx) }, async (request, reply) => {
+        const conversation = request.conversation;
+        const query = request.query;
+        const path = query.path ?? "";
+        if (!isConfinedPath(path)) {
+            return await reply.code(400).send({ error: "invalid_path" });
+        }
+        if (path.length === 0 || path === ".") {
+            return await reply.code(400).send({ error: "invalid_path" });
+        }
+        const env = await conversationEnv(opened, conversation);
+        const info = await env.fileInfo(path, BACKGROUND_CONTEXT);
+        if (!info.ok) {
+            if (info.error.code === "not_found") {
+                return await reply.code(404).send({ error: "not_found" });
+            }
+            throw info.error;
+        }
+        if (info.value.size > FILE_CONTENT_MAX_BYTES) {
+            return await reply.code(413).send({
+                error: "file_too_large",
+                maxBytes: FILE_CONTENT_MAX_BYTES,
+            });
+        }
+        const read = await env.readBinaryFile(path, BACKGROUND_CONTEXT);
+        if (!read.ok) {
+            if (read.error.code === "not_found") {
+                return await reply.code(404).send({ error: "not_found" });
+            }
+            throw read.error;
+        }
+        const bytes = read.value;
+        // Text when strictly valid UTF-8, else base64 — the same rule as
+        // file-part inlining, applied at the read boundary.
+        try {
+            const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+            return { encoding: "text", content: text, size: bytes.length };
+        }
+        catch {
+            return {
+                encoding: "base64",
+                content: Buffer.from(bytes).toString("base64"),
+                size: bytes.length,
+            };
+        }
+    });
+    // Files raw (spec §7.8, core hardening W3 Task 7): the bounded raw
+    // read the workspace file surface serves when a file is bigger (or
+    // binary-er) than files/content's 1 MiB text/base64 cap — phone photos
+    // a client wants to RENDER, export blobs, whatever the agent wrote.
+    // Semantics: `isConfinedPath` (the content route's rule — `../x` and
+    // absolute paths are 400 `invalid_path`); a directory is 400
+    // `invalid_path` (Review Focus 5: rejected explicitly, never streamed);
+    // over `server.maxFileReadBytes` is 413 `file_too_large` + `maxBytes`;
+    // otherwise CHUNKS from `env.openBinaryReader` (never `readBinaryFile`
+    // — the whole point is not buffering the file in memory) stream into
+    // `reply.raw` with the extension-derived `content-type` and an exact
+    // `content-length`. The symlink policy is unchanged from
+    // files/content: the default (follows-symlinks) reader.
+    app.get("/v1/conversations/:id/files/raw", {
+        schema: { params: ID_PARAMS_SCHEMA },
+        preHandler: loadConversation(ctx),
+    }, async (request, reply) => {
+        const conversation = request.conversation;
+        const query = request.query;
+        const path = query.path ?? "";
+        if (!isConfinedPath(path) || path.length === 0 || path === ".") {
+            return await reply.code(400).send({ error: "invalid_path" });
+        }
+        const env = await conversationEnv(opened, conversation);
+        const info = await env.fileInfo(path, BACKGROUND_CONTEXT);
+        if (!info.ok) {
+            if (info.error.code === "not_found") {
+                return await reply.code(404).send({ error: "not_found" });
+            }
+            throw info.error;
+        }
+        if (info.value.kind === "directory") {
+            return await reply.code(400).send({ error: "invalid_path" });
+        }
+        const maxBytes = config.maxFileReadBytes;
+        if (info.value.size > maxBytes) {
+            return await reply
+                .code(413)
+                .send({ error: "file_too_large", maxBytes });
+        }
+        const readerOpened = await env.openBinaryReader(path, undefined, BACKGROUND_CONTEXT);
+        if (!readerOpened.ok) {
+            if (readerOpened.error.code === "not_found") {
+                return await reply.code(404).send({ error: "not_found" });
+            }
+            throw readerOpened.error;
+        }
+        const reader = readerOpened.value;
+        // Hijack BEFORE the first write: every reply.send above ran on the
+        // normal path, but from here the response is raw bytes the JSON
+        // layer must not touch. All headers are known by now (size is).
+        reply.hijack();
+        const raw = reply.raw;
+        raw.on("error", () => { });
+        try {
+            raw.writeHead(200, {
+                "content-type": MIME_BY_EXTENSION.get(extname(path).toLowerCase()) ??
+                    "application/octet-stream",
+                "content-length": String(info.value.size),
+            });
+            for (let offset = 0; offset < info.value.size; offset += RAW_READ_CHUNK_BYTES) {
+                const chunk = await reader.read(offset, Math.min(RAW_READ_CHUNK_BYTES, info.value.size - offset), BACKGROUND_CONTEXT);
+                if (!chunk.ok)
+                    throw chunk.error;
+                raw.write(Buffer.from(chunk.value));
+            }
+            raw.end();
+        }
+        catch (error) {
+            // The raw 'error' handler above already swallows socket teardown;
+            // anything reaching THIS catch is a read-side failure mid-stream
+            // (headers already sent — the log is the honest record, the
+            // destroy the honest wire signal).
+            console.warn(`sigrun: files/raw ${path}: ${error instanceof Error ? error.message : String(error)}`);
+            raw.destroy();
+        }
+        finally {
+            await reader.close(BACKGROUND_CONTEXT).catch(() => { });
+        }
+    });
+}