@lotics/cli 0.86.0 → 0.86.2

package/dist/cli.js

@@ -127,7 +127,7 @@ COMMANDS
                                        <alias>=apply|keep|archive|recreate|unbind); an APP package
                                        FLEET-upgrades every installation across your org (clean
                                        apply, findings skip). --apply-all accepts the package's version
-  lotics package doctor [app_id]       Installation health: version pin vs latest, binding
+  lotics package doctor [app_id|package_id]  Installation health: version pin vs latest, binding
                                        drift, locally modified core, knowledge drift/edits
                                        (exit 1 on findings)
   lotics package config <app_id> [--set key=value ...]
@@ -717,7 +717,7 @@ async function main() {
         console.error("    lotics install <package_id> [--version N] [--bind-to <alias>=<kdc_id>] [--config key=value ...]   Install a package (app or content)");
         console.error("    lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]   Uninstall — dispatched by id (app vs content)");
         console.error("    lotics upgrade <app_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Upgrade — app install / content install / whole app fleet (apg_)");
-        console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding/knowledge drift");
+        console.error("  lotics package doctor [app_id|package_id]        Health: version pin vs latest + binding/knowledge drift (apg_ = this workspace's content install)");
         console.error("  lotics package config <app_id> [--set key=value ...]   Show or edit an installation's config knobs");
         console.error("  lotics package eject <app_id>                    Sever an installation's package link");
         console.error("  lotics package show <package_id>                 Registry metadata + version history (channel, yank, changelog)");

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeUpgradeEntry, ModifiedArtifact, PackageContentBinding, UpgradeResolutions } from "@lotics/shared/schemas/packages";
+import type { ContractConfigEntry, KnowledgeUpgradeEntry, ModifiedArtifact, PackageContentBinding, UpgradeResolutions } from "@lotics/shared/schemas/packages";
 /**
  * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
  * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
@@ -385,6 +385,7 @@ export declare class LoticsClient {
                 breaking: number;
                 drift: number;
                 modified: number;
+                knowledge: number;
             };
             message?: string;
         }>;
@@ -555,6 +556,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations re-declaring the config (from the manifest). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         package_id: string;
         version: number;
@@ -566,6 +569,12 @@ export declare class LoticsClient {
             removed: string[];
             changed: string[];
         };
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        config?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
         findings: ExtractFinding[];
     }>;
     /**
@@ -585,6 +594,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations re-declaring the config (from the manifest). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         package_id: string;
         version: number;
@@ -596,6 +607,12 @@ export declare class LoticsClient {
             removed: string[];
             changed: string[];
         };
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        config?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
     }>;
     /**
      * Dry-run preview of a first-release — the `GET` behind `lotics app publish`
@@ -615,6 +632,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations v1 would freeze (from the manifest's `lotics.config`). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         app_id: string;
         package_name: string;
@@ -649,6 +668,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations v1 freezes (from the manifest's `lotics.config`). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         package_id: string;
         version: number;

package/dist/client.js

@@ -365,6 +365,9 @@ export class LoticsClient {
         if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
             params.set("knowledge", JSON.stringify(opts.knowledge));
         }
+        if (opts.config !== undefined) {
+            params.set("config", JSON.stringify(opts.config));
+        }
         const query = params.toString();
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release${query ? `?${query}` : ""}`);
     }
@@ -394,6 +397,9 @@ export class LoticsClient {
         if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
             params.set("knowledge", JSON.stringify(opts.knowledge));
         }
+        if (opts.config !== undefined && opts.config.length > 0) {
+            params.set("config", JSON.stringify(opts.config));
+        }
         if (opts.renames !== undefined && opts.renames.length > 0) {
             params.set("renames", JSON.stringify(opts.renames));
         }

package/dist/dev/file_relay.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Dev-only GET relay: the read half of the same problem `upload_relay.ts` solves.
+ *
+ * The server presigns every file cell an app query returns (`url` / `thumbnail_url` /
+ * `preview_url` on each file object), and those URLs point at the PROD bucket, whose
+ * CORS admits `https://*.lotics.app` and not `http://localhost:<port>`. Displaying
+ * such a URL is fine — `<img>` and `<video>` loads are not CORS-gated, and neither is
+ * the top-level navigation `openExternal` performs. But **fetching the bytes** is, and
+ * that is exactly what every preview engine does (PDF, Word, Excel all read the file
+ * into memory), so file preview could never work in `lotics app dev`.
+ *
+ * So the dev server hands the app same-origin URLs and fetches the bytes itself.
+ *
+ * The security property is the one that governs the upload relay: the app never names
+ * a destination. It receives an opaque token, and the relay reads ONLY from a URL the
+ * server itself observed the API return for that token. No client-controlled target,
+ * nothing to allowlist, no SSRF surface.
+ *
+ * Production is untouched: it serves presigned URLs straight from storage.
+ */
+export interface FileRelay {
+    /**
+     * Deep-copy an RPC result with every presigned file URL swapped for one served by
+     * this dev server. Immutable: the input is never mutated. Anything that isn't a
+     * presigned URL on a file object passes through byte-identical.
+     */
+    rewrite(result: unknown): unknown;
+    /** The URL this token stands for — `null` if unknown or expired. */
+    destinationFor(token: string): string | null;
+    /** Live tokens — for tests. */
+    size(): number;
+}
+/**
+ * `wrapperOrigin` — e.g. `http://localhost:5174`. The URL must be ABSOLUTE: these
+ * URLs are consumed inside the app **iframe**, which is served from Vite's origin, so
+ * a relative `/_file/…` would resolve against Vite and 404. (The upload relay's URL is
+ * consumed by the wrapper page itself, where relative is correct.)
+ */
+export declare function createFileRelay(wrapperOrigin: string, now?: () => number): FileRelay;

package/dist/dev/file_relay.js

@@ -0,0 +1,87 @@
+/**
+ * Dev-only GET relay: the read half of the same problem `upload_relay.ts` solves.
+ *
+ * The server presigns every file cell an app query returns (`url` / `thumbnail_url` /
+ * `preview_url` on each file object), and those URLs point at the PROD bucket, whose
+ * CORS admits `https://*.lotics.app` and not `http://localhost:<port>`. Displaying
+ * such a URL is fine — `<img>` and `<video>` loads are not CORS-gated, and neither is
+ * the top-level navigation `openExternal` performs. But **fetching the bytes** is, and
+ * that is exactly what every preview engine does (PDF, Word, Excel all read the file
+ * into memory), so file preview could never work in `lotics app dev`.
+ *
+ * So the dev server hands the app same-origin URLs and fetches the bytes itself.
+ *
+ * The security property is the one that governs the upload relay: the app never names
+ * a destination. It receives an opaque token, and the relay reads ONLY from a URL the
+ * server itself observed the API return for that token. No client-controlled target,
+ * nothing to allowlist, no SSRF surface.
+ *
+ * Production is untouched: it serves presigned URLs straight from storage.
+ */
+import { createHash } from "node:crypto";
+/** Presigned GETs live ~24h; a token outlives its URL by nothing. */
+const TTL_MS = 24 * 60 * 60 * 1000;
+/** A long dev session re-queries constantly; each query re-presigns. Bound the table. */
+const MAX_ENTRIES = 5000;
+/**
+ * The keys the backend presigns on a file object (`file_url_resolver.ts`). Only these,
+ * and only on something that is actually a file, get rewritten — a record's own text
+ * cell holding a link (a public app URL, say) must keep pointing where it points.
+ */
+const PRESIGNED_KEYS = new Set(["url", "thumbnail_url", "preview_url"]);
+const isFileObject = (o) => typeof o.filename === "string" && typeof o.mime_type === "string";
+const isRemoteUrl = (v) => typeof v === "string" && /^https?:\/\//i.test(v);
+/**
+ * `wrapperOrigin` — e.g. `http://localhost:5174`. The URL must be ABSOLUTE: these
+ * URLs are consumed inside the app **iframe**, which is served from Vite's origin, so
+ * a relative `/_file/…` would resolve against Vite and 404. (The upload relay's URL is
+ * consumed by the wrapper page itself, where relative is correct.)
+ */
+export function createFileRelay(wrapperOrigin, now = Date.now) {
+    const seen = new Map();
+    // A stable token per URL: the same file re-queried doesn't mint a new entry, so the
+    // table tracks distinct presigns, not query volume. (Truncated — this is a lookup
+    // key in a localhost-only process, not a secret.)
+    const tokenFor = (url) => createHash("sha256").update(url).digest("hex").slice(0, 24);
+    const remember = (url) => {
+        const token = tokenFor(url);
+        seen.set(token, { url, at: now() });
+        if (seen.size > MAX_ENTRIES) {
+            // Insertion-ordered: drop the oldest.
+            const oldest = seen.keys().next();
+            if (!oldest.done)
+                seen.delete(oldest.value);
+        }
+        return token;
+    };
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (!node || typeof node !== "object")
+            return node;
+        const obj = node;
+        const file = isFileObject(obj);
+        const out = {};
+        for (const [key, value] of Object.entries(obj)) {
+            out[key] =
+                file && PRESIGNED_KEYS.has(key) && isRemoteUrl(value)
+                    ? `${wrapperOrigin}/_file/${remember(value)}`
+                    : walk(value);
+        }
+        return out;
+    };
+    return {
+        rewrite: (result) => walk(result),
+        destinationFor(token) {
+            const entry = seen.get(token);
+            if (!entry)
+                return null;
+            if (now() - entry.at > TTL_MS) {
+                seen.delete(token);
+                return null;
+            }
+            return entry.url;
+        },
+        size: () => seen.size,
+    };
+}

package/dist/dev/file_relay.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dev/file_relay.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { createFileRelay } from "./file_relay.js";
+const ORIGIN = "http://localhost:5174";
+const PRESIGNED = "https://production.r2.cloudflarestorage.com/org/files/fil_a/photo.jpg?X-Amz-Signature=abc";
+const THUMB = "https://production.r2.cloudflarestorage.com/org/files/fil_a/thumb.jpg?X-Amz-Signature=def";
+const fileCell = {
+    id: "fil_a",
+    filename: "photo.jpg",
+    mime_type: "image/jpeg",
+    url: PRESIGNED,
+    thumbnail_url: THUMB,
+};
+/** A query result, shaped like the real thing: rows, each with a files cell. */
+const queryResult = { rows: [{ id: "rec_1", giay_to: [fileCell] }] };
+describe("file relay — the app reads bytes from us, not from storage", () => {
+    it("rewrites every presigned URL on a file cell to an absolute URL on the dev server", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite(queryResult);
+        const cell = out.rows[0].giay_to[0];
+        // ABSOLUTE: the app runs in the Vite-origin iframe, so a relative path would
+        // resolve against Vite and 404.
+        expect(cell.url).toMatch(/^http:\/\/localhost:5174\/_file\/[a-f0-9]{24}$/);
+        expect(cell.thumbnail_url).toMatch(/^http:\/\/localhost:5174\/_file\/[a-f0-9]{24}$/);
+        expect(cell.url).not.toBe(cell.thumbnail_url);
+    });
+    it("reads back the exact storage URL the token stands for", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite(queryResult);
+        const token = out.rows[0].giay_to[0].url.split("/_file/")[1];
+        expect(relay.destinationFor(token)).toBe(PRESIGNED);
+    });
+    it("leaves the rest of the payload byte-identical and never mutates the input", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite(queryResult);
+        expect(out.rows[0].id).toBe("rec_1");
+        expect(out.rows[0].giay_to[0].filename).toBe("photo.jpg");
+        expect(fileCell.url).toBe(PRESIGNED); // input untouched
+    });
+});
+describe("file relay — it rewrites file URLs, not every URL it sees", () => {
+    it("does NOT touch a link that lives in a record's own text cell", () => {
+        // The customer's "Link tự khai" field holds a real URL the user clicks. Relaying it
+        // would send them to the dev server instead of the site.
+        const relay = createFileRelay(ORIGIN);
+        const row = { id: "rec_1", link_tu_khai: "https://dang-ky-noxh.lotics.app?kh=KH-2026-919" };
+        const out = relay.rewrite({ rows: [row] });
+        expect(out.rows[0].link_tu_khai).toBe("https://dang-ky-noxh.lotics.app?kh=KH-2026-919");
+        expect(relay.size()).toBe(0);
+    });
+    it("does NOT touch a `url` key on something that isn't a file", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite({ webhook: { url: "https://example.com/hook" } });
+        expect(out.webhook.url).toBe("https://example.com/hook");
+        expect(relay.size()).toBe(0);
+    });
+    it("reaches file cells wherever they are nested — a workflow's generated files, too", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite({
+            data: { status: "ok" },
+            files: [{ id: "fil_z", filename: "don.docx", mime_type: "application/vnd...", url: PRESIGNED }],
+        });
+        expect(out.files[0].url).toContain("/_file/");
+    });
+});
+describe("file relay — it reads ONLY what it handed out", () => {
+    it("refuses a token it never minted", () => {
+        const relay = createFileRelay(ORIGIN);
+        expect(relay.destinationFor("deadbeefdeadbeefdeadbeef")).toBeNull();
+    });
+    it("refuses a token whose presign has aged out", () => {
+        let clock = 0;
+        const relay = createFileRelay(ORIGIN, () => clock);
+        const out = relay.rewrite(queryResult);
+        const token = out.rows[0].giay_to[0].url.split("/_file/")[1];
+        clock += 25 * 60 * 60 * 1000; // presigned GETs live ~24h
+        expect(relay.destinationFor(token)).toBeNull();
+    });
+});
+describe("file relay — a long dev session re-queries constantly", () => {
+    it("mints one stable token per URL rather than growing on every query", () => {
+        const relay = createFileRelay(ORIGIN);
+        const a = relay.rewrite(queryResult);
+        const b = relay.rewrite(queryResult);
+        expect(b.rows[0].giay_to[0].url).toBe(a.rows[0].giay_to[0].url);
+        expect(relay.size()).toBe(2); // the file and its thumbnail — not four
+    });
+});

package/dist/dev/server.d.ts

@@ -5,11 +5,29 @@
  *   1. Vite dev server (npx vite --port <vite-port>) — child_process.spawn,
  *      stdio inherited so Vite's own logging surfaces to the developer.
  *   2. node:http server on <port> serving:
- *        GET  /        → wrapper HTML (cached: no)
- *        POST /_rpc    → JSON in, dispatched via rpc_handler, JSON out
- *        *             → 404
+ *        GET  /               → wrapper HTML (cached: no)
+ *        POST /_rpc           → JSON in, dispatched via rpc_handler, JSON out
+ *        POST /_agent_run     → SSE, piped from the run
+ *        PUT  /_upload/:id    → file bytes in  (relayed to storage)
+ *        GET  /_file/:token   → file bytes out (relayed from storage)
+ *        *                    → 404
  *
  * SIGINT (Ctrl-C) → kill Vite child, close HTTP server, exit 0.
+ *
+ * Why the byte relays exist: dev runs against the PROD bucket (there is no dev
+ * bucket), whose CORS allowlist holds the real app origins (`https://*.lotics.app`),
+ * not `http://localhost:<port>`. So a browser transfer straight to/from the presigned
+ * URL is blocked before it leaves the page — no upload could complete, and no preview
+ * engine (PDF/Word/Excel all FETCH the bytes) could read a file. Relaying through THIS
+ * server fixes both: Node has no same-origin policy, and the one cross-origin hop that
+ * remains (the app iframe reading from us) is OUR response to allow.
+ *
+ * Neither relay ever takes a destination from the client: the page sends a `file_id`
+ * or an opaque token, and the server transfers only to/from a URL IT minted or observed
+ * for that id. No client-controlled target ⇒ no SSRF surface, nothing to allowlist.
+ *
+ * Production is untouched — it transfers direct-to-storage, keeping every byte off the
+ * API server.
  */
 import { type ChildProcess } from "node:child_process";
 import { LoticsClient } from "../client.js";

package/dist/dev/server.js

@@ -5,11 +5,29 @@
  *   1. Vite dev server (npx vite --port <vite-port>) — child_process.spawn,
  *      stdio inherited so Vite's own logging surfaces to the developer.
  *   2. node:http server on <port> serving:
- *        GET  /        → wrapper HTML (cached: no)
- *        POST /_rpc    → JSON in, dispatched via rpc_handler, JSON out
- *        *             → 404
+ *        GET  /               → wrapper HTML (cached: no)
+ *        POST /_rpc           → JSON in, dispatched via rpc_handler, JSON out
+ *        POST /_agent_run     → SSE, piped from the run
+ *        PUT  /_upload/:id    → file bytes in  (relayed to storage)
+ *        GET  /_file/:token   → file bytes out (relayed from storage)
+ *        *                    → 404
  *
  * SIGINT (Ctrl-C) → kill Vite child, close HTTP server, exit 0.
+ *
+ * Why the byte relays exist: dev runs against the PROD bucket (there is no dev
+ * bucket), whose CORS allowlist holds the real app origins (`https://*.lotics.app`),
+ * not `http://localhost:<port>`. So a browser transfer straight to/from the presigned
+ * URL is blocked before it leaves the page — no upload could complete, and no preview
+ * engine (PDF/Word/Excel all FETCH the bytes) could read a file. Relaying through THIS
+ * server fixes both: Node has no same-origin policy, and the one cross-origin hop that
+ * remains (the app iframe reading from us) is OUR response to allow.
+ *
+ * Neither relay ever takes a destination from the client: the page sends a `file_id`
+ * or an opaque token, and the server transfers only to/from a URL IT minted or observed
+ * for that id. No client-controlled target ⇒ no SSRF surface, nothing to allowlist.
+ *
+ * Production is untouched — it transfers direct-to-storage, keeping every byte off the
+ * API server.
  */
 import http from "node:http";
 import net from "node:net";
@@ -17,6 +35,8 @@ import { spawn } from "node:child_process";
 import { ipv4ChildEnv } from "../child_env.js";
 import { dispatchRpc } from "./rpc_handler.js";
 import { buildWrapperPage } from "./wrapper_page.js";
+import { createUploadRelay } from "./upload_relay.js";
+import { createFileRelay } from "./file_relay.js";
 const DEFAULT_PORT = 5174;
 const DEFAULT_VITE_PORT = 5173;
 /**
@@ -84,6 +104,28 @@ export async function startDevServer(args) {
         }
     };
     process.once("exit", killViteOnExit);
+    const uploads = createUploadRelay();
+    // The app iframe is served from Vite's origin, so the file URLs it receives must be
+    // absolute against THIS server, and its byte reads are cross-origin to us — which is
+    // ours to allow (unlike the storage bucket's policy, which is not).
+    const wrapperOrigin = `http://localhost:${wrapperPort}`;
+    const viteOrigin = `http://localhost:${vitePort}`;
+    const files = createFileRelay(wrapperOrigin);
+    const fileCors = {
+        "Access-Control-Allow-Origin": viteOrigin,
+        "Access-Control-Allow-Headers": "range, content-type",
+        "Access-Control-Expose-Headers": "content-length, content-range, accept-ranges, content-type, content-disposition, etag",
+    };
+    // Headers a byte-reader actually needs: the type to decode, the length/range to seek.
+    const PASS_THROUGH = [
+        "content-type",
+        "content-length",
+        "content-range",
+        "accept-ranges",
+        "etag",
+        "last-modified",
+        "content-disposition",
+    ];
     // ── HTTP server ────────────────────────────────────────────────────────
     const server = http.createServer(async (req, res) => {
         const url = req.url ?? "/";
@@ -110,7 +152,9 @@ export async function startDevServer(args) {
                 const ms = Date.now() - startedAt;
                 process.stderr.write(`[rpc] ${body.op} ${ms}ms\n`);
                 res.writeHead(200, { "Content-Type": "application/json" });
-                res.end(serializeRpcResult(result));
+                // `upload_url` mints a PUT destination (upload relay); every other op may carry
+                // presigned file URLs the app will read bytes from (file relay).
+                res.end(serializeRpcResult(body.op === "upload_url" ? uploads.rewriteMint(result) : files.rewrite(result)));
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -171,12 +215,138 @@ export async function startDevServer(args) {
             }
             return;
         }
+        // File relay — the app reads file bytes from here instead of straight from storage,
+        // whose CORS doesn't admit a localhost origin. The app is on Vite's origin, so this
+        // IS cross-origin — but it's our response, so we allow it. Serving from here also
+        // means <img>/<video> and openExternal keep working unchanged.
+        if (pathname.startsWith("/_file/")) {
+            if (req.method === "OPTIONS") {
+                res.writeHead(204, fileCors);
+                res.end();
+                return;
+            }
+            if (req.method !== "GET" && req.method !== "HEAD") {
+                res.writeHead(405, { ...fileCors, Allow: "GET, HEAD, OPTIONS" });
+                res.end();
+                return;
+            }
+            const token = decodeURIComponent(pathname.slice("/_file/".length));
+            const destination = files.destinationFor(token);
+            if (!destination) {
+                // Not a URL this server handed out (or its presign has aged out). Reading from
+                // anywhere else is the thing this design refuses to do.
+                process.stderr.write(`[file] ERROR unknown or expired token ${token}\n`);
+                res.writeHead(404, { ...fileCors, "Content-Type": "application/json" });
+                res.end(JSON.stringify({ message: "No file for this token" }));
+                return;
+            }
+            try {
+                // Forward Range verbatim: a PDF reader seeks rather than reading the whole file,
+                // and media scrubbing depends on 206s coming back intact.
+                const range = req.headers.range;
+                const upstream = await fetch(destination, {
+                    method: req.method,
+                    headers: range ? { Range: range } : undefined,
+                });
+                const headers = { ...fileCors };
+                for (const name of PASS_THROUGH) {
+                    const value = upstream.headers.get(name);
+                    if (value)
+                        headers[name] = value;
+                }
+                // Same one-line-per-transfer visibility as [rpc] and [upload] — a preview that
+                // silently serves nothing is exactly the thing this relay exists to make legible.
+                const size = headers["content-length"] ?? "?";
+                process.stderr.write(`[file] ${token} ${upstream.status} ${size}B\n`);
+                res.writeHead(upstream.status, headers);
+                if (req.method === "HEAD" || !upstream.body) {
+                    res.end();
+                    return;
+                }
+                const reader = upstream.body.getReader();
+                for (;;) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    res.write(Buffer.from(value));
+                }
+                res.end();
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[file] ERROR ${token} ${message}\n`);
+                if (!res.headersSent) {
+                    res.writeHead(502, { ...fileCors, "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ message }));
+                }
+                else {
+                    res.end();
+                }
+            }
+            return;
+        }
+        // Upload relay — the wrapper page PUTs the bytes here (same-origin, so the
+        // browser never applies CORS), and Node forwards them to the presigned URL.
+        if (req.method === "PUT" && pathname.startsWith("/_upload/")) {
+            const fileId = decodeURIComponent(pathname.slice("/_upload/".length));
+            const destination = uploads.destinationFor(fileId);
+            if (!destination) {
+                // Not a URL this server minted (or its presign has aged out). Relaying
+                // anywhere else is exactly the thing this design refuses to do.
+                process.stderr.write(`[upload] ERROR unknown or expired file_id ${fileId}\n`);
+                res.writeHead(404, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ message: `No presigned upload pending for ${fileId}` }));
+                return;
+            }
+            try {
+                // Buffer rather than stream: the presign signs `content-length`, and a
+                // streamed body would go out chunked and fail the signature. Dev-only,
+                // and the size ceiling is the API's own upload limit.
+                const chunks = [];
+                for await (const chunk of req)
+                    chunks.push(chunk);
+                const bytes = Buffer.concat(chunks);
+                const startedAt = Date.now();
+                const upstream = await fetch(destination, {
+                    method: "PUT",
+                    body: bytes,
+                    headers: { "Content-Type": req.headers["content-type"] ?? "application/octet-stream" },
+                });
+                const ms = Date.now() - startedAt;
+                if (upstream.ok) {
+                    uploads.settle(fileId);
+                    process.stderr.write(`[upload] ${fileId} ${bytes.length}B ${ms}ms\n`);
+                }
+                else {
+                    // Keep the mint: the wrapper retries 5xx, and the presign is still valid.
+                    process.stderr.write(`[upload] ERROR ${fileId} storage returned ${upstream.status}\n`);
+                }
+                res.writeHead(upstream.status);
+                res.end();
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[upload] ERROR ${fileId} ${message}\n`);
+                if (!res.headersSent) {
+                    res.writeHead(502, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ message }));
+                }
+                else {
+                    res.end();
+                }
+            }
+            return;
+        }
         res.writeHead(404, { "Content-Type": "text/plain" });
         res.end("Not Found");
     });
     await new Promise((resolve, reject) => {
         server.once("error", reject);
-        server.listen(wrapperPort, () => {
+        // Loopback ONLY — never 0.0.0.0. `/_rpc` dispatches with the developer's API key, so a
+        // server bound to every interface hands anyone on the same network full read/write on the
+        // workspace (and, since the relays, the file bytes too). Vite already binds loopback; this
+        // socket is strictly more sensitive than that one.
+        server.listen(wrapperPort, "127.0.0.1", () => {
             server.off("error", reject);
             resolve();
         });

package/dist/dev/upload_relay.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Dev-only upload relay: the bookkeeping that lets `lotics app dev` upload a file.
+ *
+ * Dev runs against the PROD bucket (there is no dev bucket), whose CORS allowlist
+ * holds the real app origins (`https://*.lotics.app`), not `http://localhost:<port>`.
+ * A browser PUT straight to the presigned URL is blocked before it leaves the page,
+ * so without a relay no file-touching app can be exercised locally at all.
+ *
+ * The dev server therefore relays the bytes: the wrapper page PUTs same-origin (no
+ * preflight, no CORS) and Node — which has no same-origin policy — forwards them on.
+ *
+ * The security property, and the reason the page never names its destination: a
+ * relay that forwarded to a client-supplied URL would be an open proxy. So the page
+ * sends only a `file_id`, and the relay writes ONLY to a presigned URL it minted
+ * itself for that id, moments earlier, via its own authenticated API call. There is
+ * no client-controlled target — hence nothing to allowlist, and no SSRF surface.
+ *
+ * Production is untouched: it PUTs direct-to-storage, keeping every byte off the
+ * API server.
+ */
+export interface UploadRelay {
+    /**
+     * Record the presigned PUT from an `upload_url` mint and return the result the
+     * page should see — identical but for a same-origin `upload_url`. A result that
+     * carries no mint passes through untouched: nothing is recorded, nothing is
+     * rewritten, and the page's PUT fails loudly rather than uploading into a void.
+     */
+    rewriteMint(result: unknown): unknown;
+    /** The presigned URL minted for this id — `null` if unknown or expired. */
+    destinationFor(fileId: string): string | null;
+    /** Drop a mint once its bytes have landed. One presign, one object. */
+    settle(fileId: string): void;
+    /** Outstanding mints — for tests. */
+    size(): number;
+}
+export declare function createUploadRelay(now?: () => number): UploadRelay;