@lotics/cli 0.86.0 → 0.86.1

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;

package/dist/dev/upload_relay.js

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+/**
+ * How long a mint is worth keeping. This is a pruning window, not a correctness gate —
+ * storage is the authority on whether a presign is still valid (an expired one is refused
+ * there, and the wrapper surfaces that). It only needs to outlive the presign (~10 min) so
+ * the relay never 404s a PUT that storage would still have accepted.
+ */
+const PRESIGN_TTL_MS = 15 * 60 * 1000;
+export function createUploadRelay(now = Date.now) {
+    const minted = new Map();
+    const prune = (at) => {
+        for (const [id, entry] of minted) {
+            if (at - entry.mintedAt > PRESIGN_TTL_MS)
+                minted.delete(id);
+        }
+    };
+    return {
+        rewriteMint(result) {
+            const mint = result;
+            if (typeof mint?.file_id !== "string" || typeof mint?.upload_url !== "string")
+                return result;
+            const at = now();
+            prune(at);
+            minted.set(mint.file_id, { url: mint.upload_url, mintedAt: at });
+            return { ...mint, upload_url: `/_upload/${encodeURIComponent(mint.file_id)}` };
+        },
+        destinationFor(fileId) {
+            const entry = minted.get(fileId);
+            if (!entry)
+                return null;
+            if (now() - entry.mintedAt > PRESIGN_TTL_MS) {
+                minted.delete(fileId);
+                return null;
+            }
+            return entry.url;
+        },
+        settle(fileId) {
+            minted.delete(fileId);
+        },
+        size: () => minted.size,
+    };
+}

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

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

package/dist/dev/upload_relay.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { createUploadRelay } from "./upload_relay.js";
+const MINT = {
+    file_id: "fil_abc",
+    file_storage_key: "org/files/fil_abc/photo.jpg",
+    upload_url: "https://production.r2.cloudflarestorage.com/org/files/fil_abc/photo.jpg?X-Amz-Signature=deadbeef",
+};
+describe("upload relay — the page PUTs same-origin", () => {
+    it("hands the page a same-origin URL and keeps everything else it needs to finalize", () => {
+        const relay = createUploadRelay();
+        const seen = relay.rewriteMint(MINT);
+        expect(seen.upload_url).toBe("/_upload/fil_abc");
+        // file_storage_key + file_id still reach the page — `upload_complete` needs both.
+        expect(seen.file_id).toBe("fil_abc");
+        expect(seen.file_storage_key).toBe(MINT.file_storage_key);
+    });
+    it("does not mutate the mint it was handed", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        expect(MINT.upload_url).toContain("r2.cloudflarestorage.com");
+    });
+});
+describe("upload relay — it writes ONLY where it was told to by itself", () => {
+    it("relays to the presigned URL it minted for that id", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        expect(relay.destinationFor("fil_abc")).toBe(MINT.upload_url);
+    });
+    it("refuses an id it never minted — there is no client-supplied destination to honour", () => {
+        const relay = createUploadRelay();
+        expect(relay.destinationFor("fil_never_seen")).toBeNull();
+    });
+    it("refuses a mint that has aged past its presign", () => {
+        let clock = 1_000_000;
+        const relay = createUploadRelay(() => clock);
+        relay.rewriteMint(MINT);
+        clock += 16 * 60 * 1000; // presigns die at ~10 min; the relay holds 15
+        expect(relay.destinationFor("fil_abc")).toBeNull();
+    });
+});
+describe("upload relay — lifecycle", () => {
+    it("forgets a mint once its bytes have landed", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        relay.settle("fil_abc");
+        expect(relay.destinationFor("fil_abc")).toBeNull();
+        expect(relay.size()).toBe(0);
+    });
+    it("keeps the mint on a failed PUT so the page's retry can reuse it", () => {
+        const relay = createUploadRelay();
+        relay.rewriteMint(MINT);
+        // No settle() — the storage PUT 5xx'd and the wrapper page retries.
+        expect(relay.destinationFor("fil_abc")).toBe(MINT.upload_url);
+    });
+    it("prunes dead mints instead of growing forever across a long dev session", () => {
+        let clock = 0;
+        const relay = createUploadRelay(() => clock);
+        relay.rewriteMint({ ...MINT, file_id: "fil_old" });
+        clock += 16 * 60 * 1000;
+        relay.rewriteMint({ ...MINT, file_id: "fil_new" });
+        expect(relay.size()).toBe(1); // the stale one was swept on the next mint
+        expect(relay.destinationFor("fil_new")).toBe(MINT.upload_url);
+    });
+});
+describe("upload relay — a response that carries no mint", () => {
+    it("passes through untouched rather than inventing a relay for it", () => {
+        const relay = createUploadRelay();
+        const odd = { message: "upstream changed shape" };
+        expect(relay.rewriteMint(odd)).toBe(odd);
+        expect(relay.size()).toBe(0);
+    });
+    it("tolerates null without throwing", () => {
+        const relay = createUploadRelay();
+        expect(relay.rewriteMint(null)).toBeNull();
+    });
+});

package/dist/dev/wrapper_page.js

@@ -120,7 +120,13 @@ export function buildWrapperPage(args) {
 
       // The iframe SDK sends one "upload" op carrying a File. A File can't
       // cross the JSON /_rpc hop, so the upload runs here in the browser:
-      // mint a presigned URL, PUT the bytes to storage, then finalize.
+      // mint an upload URL, PUT the bytes, then finalize.
+      //
+      // In dev the minted URL is same-origin (/_upload/<file_id>) — the dev
+      // server relays the bytes to storage on our behalf, because the prod
+      // bucket's CORS does not admit a localhost origin. Production PUTs the
+      // presigned storage URL directly. Same three lines either way: the page
+      // PUTs wherever the mint points.
       //
       // Retry policy parity with the production SDK
       // (packages/app-sdk/src/upload/transport.ts): 3 PUT attempts with

package/dist/src/cli.js

@@ -31598,7 +31598,13 @@ function buildWrapperPage(args) {
 
       // The iframe SDK sends one "upload" op carrying a File. A File can't
       // cross the JSON /_rpc hop, so the upload runs here in the browser:
-      // mint a presigned URL, PUT the bytes to storage, then finalize.
+      // mint an upload URL, PUT the bytes, then finalize.
+      //
+      // In dev the minted URL is same-origin (/_upload/<file_id>) \u2014 the dev
+      // server relays the bytes to storage on our behalf, because the prod
+      // bucket's CORS does not admit a localhost origin. Production PUTs the
+      // presigned storage URL directly. Same three lines either way: the page
+      // PUTs wherever the mint points.
       //
       // Retry policy parity with the production SDK
       // (packages/app-sdk/src/upload/transport.ts): 3 PUT attempts with
@@ -31803,6 +31809,85 @@ function escapeHtml2(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
+// src/dev/upload_relay.ts
+var PRESIGN_TTL_MS = 15 * 60 * 1e3;
+function createUploadRelay(now = Date.now) {
+  const minted = /* @__PURE__ */ new Map();
+  const prune = (at) => {
+    for (const [id, entry] of minted) {
+      if (at - entry.mintedAt > PRESIGN_TTL_MS) minted.delete(id);
+    }
+  };
+  return {
+    rewriteMint(result) {
+      const mint = result;
+      if (typeof mint?.file_id !== "string" || typeof mint?.upload_url !== "string") return result;
+      const at = now();
+      prune(at);
+      minted.set(mint.file_id, { url: mint.upload_url, mintedAt: at });
+      return { ...mint, upload_url: `/_upload/${encodeURIComponent(mint.file_id)}` };
+    },
+    destinationFor(fileId) {
+      const entry = minted.get(fileId);
+      if (!entry) return null;
+      if (now() - entry.mintedAt > PRESIGN_TTL_MS) {
+        minted.delete(fileId);
+        return null;
+      }
+      return entry.url;
+    },
+    settle(fileId) {
+      minted.delete(fileId);
+    },
+    size: () => minted.size
+  };
+}
+
+// src/dev/file_relay.ts
+import { createHash } from "node:crypto";
+var TTL_MS = 24 * 60 * 60 * 1e3;
+var MAX_ENTRIES = 5e3;
+var PRESIGNED_KEYS = /* @__PURE__ */ new Set(["url", "thumbnail_url", "preview_url"]);
+var isFileObject = (o) => typeof o.filename === "string" && typeof o.mime_type === "string";
+var isRemoteUrl = (v) => typeof v === "string" && /^https?:\/\//i.test(v);
+function createFileRelay(wrapperOrigin, now = Date.now) {
+  const seen = /* @__PURE__ */ new Map();
+  const tokenFor = (url2) => createHash("sha256").update(url2).digest("hex").slice(0, 24);
+  const remember = (url2) => {
+    const token = tokenFor(url2);
+    seen.set(token, { url: url2, at: now() });
+    if (seen.size > MAX_ENTRIES) {
+      const oldest = seen.keys().next();
+      if (!oldest.done) seen.delete(oldest.value);
+    }
+    return token;
+  };
+  const walk2 = (node) => {
+    if (Array.isArray(node)) return node.map(walk2);
+    if (!node || typeof node !== "object") return node;
+    const obj = node;
+    const file2 = isFileObject(obj);
+    const out = {};
+    for (const [key, value] of Object.entries(obj)) {
+      out[key] = file2 && PRESIGNED_KEYS.has(key) && isRemoteUrl(value) ? `${wrapperOrigin}/_file/${remember(value)}` : walk2(value);
+    }
+    return out;
+  };
+  return {
+    rewrite: (result) => walk2(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
+  };
+}
+
 // src/dev/server.ts
 var DEFAULT_PORT = 5174;
 var DEFAULT_VITE_PORT = 5173;
@@ -31849,6 +31934,24 @@ async function startDevServer(args) {
     }
   };
   process.once("exit", killViteOnExit);
+  const uploads = createUploadRelay();
+  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"
+  };
+  const PASS_THROUGH = [
+    "content-type",
+    "content-length",
+    "content-range",
+    "accept-ranges",
+    "etag",
+    "last-modified",
+    "content-disposition"
+  ];
   const server = http.createServer(async (req, res) => {
     const url2 = req.url ?? "/";
     const pathname = url2.split("?")[0];
@@ -31877,7 +31980,11 @@ async function startDevServer(args) {
         process.stderr.write(`[rpc] ${body.op} ${ms}ms
 `);
         res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(serializeRpcResult(result));
+        res.end(
+          serializeRpcResult(
+            body.op === "upload_url" ? uploads.rewriteMint(result) : files.rewrite(result)
+          )
+        );
       } catch (err2) {
         const message = err2 instanceof Error ? err2.message : String(err2);
         process.stderr.write(`[rpc] ERROR ${message}
@@ -31930,12 +32037,115 @@ async function startDevServer(args) {
       }
       return;
     }
+    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) {
+        process.stderr.write(`[file] ERROR unknown or expired token ${token}
+`);
+        res.writeHead(404, { ...fileCors, "Content-Type": "application/json" });
+        res.end(JSON.stringify({ message: "No file for this token" }));
+        return;
+      }
+      try {
+        const range = req.headers.range;
+        const upstream = await fetch(destination, {
+          method: req.method,
+          headers: range ? { Range: range } : void 0
+        });
+        const headers = { ...fileCors };
+        for (const name of PASS_THROUGH) {
+          const value = upstream.headers.get(name);
+          if (value) headers[name] = value;
+        }
+        const size = headers["content-length"] ?? "?";
+        process.stderr.write(`[file] ${token} ${upstream.status} ${size}B
+`);
+        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 (err2) {
+        const message = err2 instanceof Error ? err2.message : String(err2);
+        process.stderr.write(`[file] ERROR ${token} ${message}
+`);
+        if (!res.headersSent) {
+          res.writeHead(502, { ...fileCors, "Content-Type": "application/json" });
+          res.end(JSON.stringify({ message }));
+        } else {
+          res.end();
+        }
+      }
+      return;
+    }
+    if (req.method === "PUT" && pathname.startsWith("/_upload/")) {
+      const fileId = decodeURIComponent(pathname.slice("/_upload/".length));
+      const destination = uploads.destinationFor(fileId);
+      if (!destination) {
+        process.stderr.write(`[upload] ERROR unknown or expired file_id ${fileId}
+`);
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ message: `No presigned upload pending for ${fileId}` }));
+        return;
+      }
+      try {
+        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
+`);
+        } else {
+          process.stderr.write(`[upload] ERROR ${fileId} storage returned ${upstream.status}
+`);
+        }
+        res.writeHead(upstream.status);
+        res.end();
+      } catch (err2) {
+        const message = err2 instanceof Error ? err2.message : String(err2);
+        process.stderr.write(`[upload] ERROR ${fileId} ${message}
+`);
+        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((resolve2, reject2) => {
     server.once("error", reject2);
-    server.listen(wrapperPort, () => {
+    server.listen(wrapperPort, "127.0.0.1", () => {
       server.off("error", reject2);
       resolve2();
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.86.0",
+  "version": "0.86.1",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {