@nmvuong92/fluxe 0.2.0 → 0.4.0

package/lib/core/cli.js

@@ -17,6 +17,10 @@ export const COMMANDS = {
         desc: "Auto-discovery: quét app/cells/* → app/app.ts (dev/resolve tự gọi)",
         shell: () => SYNC,
     },
+    config: {
+        desc: "In config đã giải (default ← ENV FLUXE_* ← override)",
+        shell: () => `tsx scripts/config.ts`,
+    },
     gen: {
         desc: "Codegen contract → types TS/Go/Rust (.fluxe/gen)",
         shell: () => `tsx scripts/codegen.ts`,

package/lib/core/client.d.ts

@@ -16,6 +16,15 @@ export interface RpcMeta {
 }
 export declare const lastRpcMeta: () => RpcMeta;
 export declare function rpc<T = any>(cell: string, action: string, input: unknown): Promise<T>;
+export declare function upload(field: string, files: File | File[]): Promise<{
+    key: string;
+    url: string;
+    size: number;
+} | Array<{
+    key: string;
+    url: string;
+    size: number;
+}>>;
 export declare function mutate<T>(opts: {
     optimistic?: () => void;
     run: () => Promise<T>;

package/lib/core/client.js

@@ -70,6 +70,20 @@ export async function rpc(cell, action, input) {
         throw parseRpcError(res.status, await res.text());
     return res.json();
 }
+/* Upload file qua POST /__upload/<field> (multipart). Trả { key, url, size } (hoặc mảng nếu nhiều). */
+export async function upload(field, files) {
+    const fd = new FormData();
+    for (const f of Array.isArray(files) ? files : [files])
+        fd.append(field, f);
+    const res = await fetch(`/__upload/${field}`, {
+        method: "POST",
+        headers: { "x-csrf-token": cookie("csrf") }, // KHÔNG set content-type — browser tự thêm boundary
+        body: fd,
+    });
+    if (!res.ok)
+        throw parseRpcError(res.status, await res.text());
+    return res.json();
+}
 // Optimistic update: chạy optimistic() ngay, run() ngầm; lỗi → rollback() + ném lại.
 export async function mutate(opts) {
     opts.optimistic?.();

package/lib/core/config.d.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+declare const Schema: z.ZodObject<{
+    env: z.ZodEnum<["development", "production", "test"]>;
+    secret: z.ZodString;
+    port: z.ZodNumber;
+    defaultBackend: z.ZodEnum<["memory", "go", "rust"]>;
+    rateLimit: z.ZodObject<{
+        capacity: z.ZodNumber;
+        refillPerSec: z.ZodNumber;
+        maxKeys: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        capacity: number;
+        refillPerSec: number;
+        maxKeys: number;
+    }, {
+        capacity: number;
+        refillPerSec: number;
+        maxKeys: number;
+    }>;
+    renderCache: z.ZodObject<{
+        maxKeys: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        maxKeys: number;
+    }, {
+        maxKeys: number;
+    }>;
+    upload: z.ZodObject<{
+        maxBytes: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        maxBytes: number;
+    }, {
+        maxBytes: number;
+    }>;
+    i18n: z.ZodObject<{
+        defaultLocale: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        defaultLocale: string;
+    }, {
+        defaultLocale: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    env: "development" | "production" | "test";
+    secret: string;
+    port: number;
+    defaultBackend: "memory" | "go" | "rust";
+    rateLimit: {
+        capacity: number;
+        refillPerSec: number;
+        maxKeys: number;
+    };
+    renderCache: {
+        maxKeys: number;
+    };
+    upload: {
+        maxBytes: number;
+    };
+    i18n: {
+        defaultLocale: string;
+    };
+}, {
+    env: "development" | "production" | "test";
+    secret: string;
+    port: number;
+    defaultBackend: "memory" | "go" | "rust";
+    rateLimit: {
+        capacity: number;
+        refillPerSec: number;
+        maxKeys: number;
+    };
+    renderCache: {
+        maxKeys: number;
+    };
+    upload: {
+        maxBytes: number;
+    };
+    i18n: {
+        defaultLocale: string;
+    };
+}>;
+export type FluxeConfig = z.infer<typeof Schema>;
+type Src = Record<string, string | undefined>;
+export declare const ENV_KEYS: {
+    readonly NODE_ENV: "env";
+    readonly FLUXE_SECRET: "secret";
+    readonly "PORT (ho\u1EB7c FLUXE_PORT)": "port";
+    readonly FLUXE_BACKEND: "defaultBackend";
+    readonly FLUXE_RATELIMIT_CAPACITY: "rateLimit.capacity";
+    readonly FLUXE_RATELIMIT_REFILL: "rateLimit.refillPerSec";
+    readonly FLUXE_RATELIMIT_MAX_KEYS: "rateLimit.maxKeys";
+    readonly FLUXE_RENDERCACHE_MAX_KEYS: "renderCache.maxKeys";
+    readonly FLUXE_UPLOAD_MAX_BYTES: "upload.maxBytes";
+    readonly FLUXE_LOCALE_DEFAULT: "i18n.defaultLocale";
+};
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? Partial<T[K]> : T[K];
+};
+export declare function loadConfig(source?: Src, overrides?: DeepPartial<FluxeConfig>): FluxeConfig;
+export {};

package/lib/core/config.js

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Config core — DEFAULT + override qua ENV (quy ước FLUXE_*), kiểu Laravel config().
+ * Một nguồn sự thật cho mọi tham số tinh chỉnh của engine. Thứ tự ưu tiên:
+ *   default  <  ENV (FLUXE_*)  <  override truyền tay.
+ * Mọi giá trị quan trọng ĐỀU expose ra ENV + tài liệu (xem docs/reference/configuration). */
+import { z } from "zod";
+const Schema = z.object({
+    env: z.enum(["development", "production", "test"]),
+    secret: z.string().min(8),
+    port: z.coerce.number().int().positive(),
+    defaultBackend: z.enum(["memory", "go", "rust"]),
+    rateLimit: z.object({
+        capacity: z.coerce.number().int().positive(),
+        refillPerSec: z.coerce.number().positive(),
+        maxKeys: z.coerce.number().int().positive(),
+    }),
+    renderCache: z.object({ maxKeys: z.coerce.number().int().positive() }),
+    upload: z.object({ maxBytes: z.coerce.number().int().positive() }),
+    i18n: z.object({ defaultLocale: z.string().min(2) }),
+});
+/* Bảng ENV — TÊN biến ↔ field. Dùng cho loadConfig + sinh tài liệu. */
+export const ENV_KEYS = {
+    "NODE_ENV": "env",
+    "FLUXE_SECRET": "secret",
+    "PORT (hoặc FLUXE_PORT)": "port",
+    "FLUXE_BACKEND": "defaultBackend",
+    "FLUXE_RATELIMIT_CAPACITY": "rateLimit.capacity",
+    "FLUXE_RATELIMIT_REFILL": "rateLimit.refillPerSec",
+    "FLUXE_RATELIMIT_MAX_KEYS": "rateLimit.maxKeys",
+    "FLUXE_RENDERCACHE_MAX_KEYS": "renderCache.maxKeys",
+    "FLUXE_UPLOAD_MAX_BYTES": "upload.maxBytes",
+    "FLUXE_LOCALE_DEFAULT": "i18n.defaultLocale",
+};
+const num = (s, k, d) => {
+    const v = s[k];
+    return v == null || v === "" ? d : Number(v);
+};
+function merge(base, o) {
+    return {
+        ...base,
+        ...o,
+        rateLimit: { ...base.rateLimit, ...o.rateLimit },
+        renderCache: { ...base.renderCache, ...o.renderCache },
+        upload: { ...base.upload, ...o.upload },
+        i18n: { ...base.i18n, ...o.i18n },
+    };
+}
+/* Giải config: default ← ENV (FLUXE_*) ← override. Validate Zod (sai → ném ngay, fail-fast). */
+export function loadConfig(source = process.env, overrides = {}) {
+    const fromEnv = {
+        env: source.NODE_ENV || "development",
+        secret: source.FLUXE_SECRET || "dev-secret-change-me",
+        port: num(source, "PORT", num(source, "FLUXE_PORT", 5180)),
+        defaultBackend: source.FLUXE_BACKEND || "memory",
+        rateLimit: {
+            capacity: num(source, "FLUXE_RATELIMIT_CAPACITY", 30),
+            refillPerSec: num(source, "FLUXE_RATELIMIT_REFILL", 10),
+            maxKeys: num(source, "FLUXE_RATELIMIT_MAX_KEYS", 5000),
+        },
+        renderCache: { maxKeys: num(source, "FLUXE_RENDERCACHE_MAX_KEYS", 256) },
+        upload: { maxBytes: num(source, "FLUXE_UPLOAD_MAX_BYTES", 10 * 1024 * 1024) },
+        i18n: { defaultLocale: source.FLUXE_LOCALE_DEFAULT || "en" },
+    };
+    return Schema.parse(merge(fromEnv, overrides));
+}

package/lib/core/multipart.d.ts

@@ -0,0 +1,8 @@
+export interface Part {
+    name: string;
+    filename?: string;
+    contentType?: string;
+    data: Buffer;
+}
+export declare function boundaryFromContentType(contentType: string | undefined): string | null;
+export declare function parseMultipart(body: Buffer, boundary: string): Part[];

package/lib/core/multipart.js

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Parser multipart/form-data — THUẦN, chỉ Buffer (không lib). Tách body theo boundary thành
+ * các part { name, filename?, contentType?, data }. Dùng cho upload. */
+const CRLFCRLF = Buffer.from("\r\n\r\n");
+/* boundary lấy từ header Content-Type: multipart/form-data; boundary=XXXX */
+export function boundaryFromContentType(contentType) {
+    if (!contentType)
+        return null;
+    const m = /boundary=(?:"([^"]+)"|([^;]+))/i.exec(contentType);
+    return m ? (m[1] ?? m[2]).trim() : null;
+}
+export function parseMultipart(body, boundary) {
+    const parts = [];
+    const delim = Buffer.from(`--${boundary}`);
+    const positions = [];
+    let idx = body.indexOf(delim, 0);
+    while (idx !== -1) {
+        positions.push(idx);
+        idx = body.indexOf(delim, idx + delim.length);
+    }
+    for (let i = 0; i < positions.length - 1; i++) {
+        let start = positions[i] + delim.length;
+        if (body[start] === 0x2d && body[start + 1] === 0x2d)
+            continue; // "--" → delim đóng, bỏ
+        if (body[start] === 0x0d && body[start + 1] === 0x0a)
+            start += 2; // bỏ \r\n sau delim
+        let end = positions[i + 1];
+        if (body[end - 2] === 0x0d && body[end - 1] === 0x0a)
+            end -= 2; // bỏ \r\n trước delim kế
+        const seg = body.subarray(start, end);
+        const sep = seg.indexOf(CRLFCRLF);
+        if (sep === -1)
+            continue;
+        const headerStr = seg.subarray(0, sep).toString("utf8");
+        const data = seg.subarray(sep + CRLFCRLF.length);
+        const cd = /content-disposition:[^\r\n]*?name="([^"]*)"(?:[^\r\n]*?filename="([^"]*)")?/i.exec(headerStr);
+        if (!cd)
+            continue;
+        const ct = /content-type:\s*([^\r\n]+)/i.exec(headerStr);
+        parts.push({
+            name: cd[1],
+            filename: cd[2] || undefined,
+            contentType: ct?.[1]?.trim(),
+            data,
+        });
+    }
+    return parts;
+}

package/lib/index.d.ts

@@ -5,6 +5,7 @@ export * from "./core/resolver.ts";
 export * from "./core/wiring.ts";
 export * from "./core/auth.ts";
 export * from "./core/env.ts";
+export * from "./core/config.ts";
 export * from "./core/i18n.ts";
 export * from "./core/seo.ts";
 export * from "./core/broker.ts";
@@ -15,6 +16,10 @@ export * from "./core/layouts.ts";
 export * from "./core/router.ts";
 export * from "./core/testing.ts";
 export * from "./backends/types.ts";
+export * from "./storage/types.ts";
+export { createMemoryStorage } from "./storage/memory.ts";
+export { createLocalStorage } from "./storage/local.ts";
+export { createS3Storage } from "./storage/s3.ts";
 export { createMemoryBackend } from "./backends/memory.ts";
 export { createHttpBackend } from "./backends/http.ts";
 export { createPostgresBackend } from "./backends/postgres.ts";

package/lib/index.js

@@ -9,6 +9,7 @@ export * from "./core/resolver.js"; // resolve, ResolutionProfile/Manifest, Cell
 export * from "./core/wiring.js"; // backendFromManifest, backendsFromManifest
 export * from "./core/auth.js"; // session HMAC, scrypt password, CSRF, RBAC
 export * from "./core/env.js"; // loadEnv
+export * from "./core/config.js"; // FluxeConfig, loadConfig (default ← ENV FLUXE_* ← override)
 export * from "./core/i18n.js"; // createI18n, resolveLocale, translate, makeT, t(key, vars)
 export * from "./core/seo.js"; // renderHead, renderSitemap, renderRobots, HeadMeta
 export * from "./core/broker.js"; // pub/sub
@@ -19,6 +20,10 @@ export * from "./core/layouts.js"; // layoutChain, LayoutMeta
 export * from "./core/router.js"; // makeRouter
 export * from "./core/testing.js"; // createTestBackend
 export * from "./backends/types.js"; // Backend, Todo
+export * from "./storage/types.js"; // Storage, PutResult, GetResult, safeKey, makeKey
+export { createMemoryStorage } from "./storage/memory.js";
+export { createLocalStorage } from "./storage/local.js";
+export { createS3Storage } from "./storage/s3.js"; // adapter tham chiếu (cần @aws-sdk/client-s3)
 export { createMemoryBackend } from "./backends/memory.js";
 export { createHttpBackend } from "./backends/http.js";
 export { createPostgresBackend } from "./backends/postgres.js";

package/lib/server_factory.d.ts

@@ -9,7 +9,11 @@ type LayoutEntry = LayoutMeta & {
 };
 type LayoutMap = Record<string, LayoutEntry>;
 import { type I18n } from "./core/i18n.ts";
+import { type Storage } from "./storage/types.ts";
+import { type FluxeConfig } from "./core/config.ts";
 export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: {
     i18n?: I18n;
+    storage?: Storage;
+    config?: FluxeConfig;
 }): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
 export {};

package/lib/server_factory.js

@@ -21,6 +21,9 @@ import { etagOf, etagMatches } from "./core/etag.js";
 import { createRenderCache } from "./core/rendercache.js";
 import { parseChaos } from "./core/chaos.js";
 import { resolveLocale, makeT } from "./core/i18n.js";
+import { parseMultipart, boundaryFromContentType } from "./core/multipart.js";
+import { makeKey } from "./storage/types.js";
+import { loadConfig } from "./core/config.js";
 import { createMemoryBackend } from "./backends/memory.js";
 import { createHttpBackend } from "./backends/http.js";
 // Build backend theo ngôn ngữ (cho live swap trong devtools).
@@ -37,7 +40,7 @@ function devBackend(lang) {
     const url = process.env[`${lang.toUpperCase()}_URL`] ?? DEV_BACKENDS[lang];
     return url ? createHttpBackend(lang, url) : createMemoryBackend();
 }
-import { randomUUID } from "node:crypto";
+import { randomUUID, randomBytes } from "node:crypto";
 const DEV = process.env.NODE_ENV !== "production";
 const SECRET = process.env.FLUXE_SECRET ?? "dev-secret-change-me";
 // Demo user store (password hash scrypt tạo lúc boot). App thật: lấy từ DB.
@@ -89,6 +92,24 @@ function renderBodyToString(node) {
 }
 export function makeServer(manifest, cells, layouts = {}, opts = {}) {
     const i18n = opts.i18n;
+    const storage = opts.storage;
+    const config = opts.config ?? loadConfig(); // default ← ENV (FLUXE_*) ← override
+    const MAX_UPLOAD = config.upload.maxBytes;
+    const readBodyBuffer = (req) => new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_UPLOAD) {
+                req.destroy();
+                reject(new FluxeError("upload", "File quá lớn", 413));
+            }
+            else
+                chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
     // Cells được TIÊM từ app (DI) — engine không import ngược vào app/. Thêm trang = sửa app/app.ts.
     const matchRoute = makeRouter(cells);
     const byId = new Map(cells.map((c) => [c.id, c]));
@@ -96,10 +117,10 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
     const backends = backendsFromManifest(manifest);
     const backendFor = (id) => backends.byCell.get(id) ?? backends.default;
     const broker = createBroker(); // realtime pub/sub (Trục 4g, bản 1-node)
-    const actionLimit = createRateLimiter({ capacity: 30, refillPerSec: 10 }); // per-IP cho action
+    const actionLimit = createRateLimiter(config.rateLimit); // per-IP cho action (FLUXE_RATELIMIT_*)
     const recorder = createRecorder(); // request log (observability)
     const presence = createPresence(); // ai đang online per topic (Trục 4g)
-    const renderCache = createRenderCache({ maxKeys: 256 }); // memoize HTML cell static (key route, gate etag)
+    const renderCache = createRenderCache({ maxKeys: config.renderCache.maxKeys }); // FLUXE_RENDERCACHE_MAX_KEYS
     let clientJs; // ý A: đọc dist/client.js 1 lần (zero-copy: tái dùng buffer)
     return http.createServer(async (req, res) => {
         const url = new URL(req.url, "http://localhost");
@@ -182,6 +203,43 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
                 });
                 return res.end(`<p>Đã đăng xuất. <a href="/">trang chủ</a></p>`);
             }
+            // File upload: POST /__upload/<field> → parse multipart → storage.put. CSRF + giới hạn size.
+            if (url.pathname.startsWith("/__upload/") && req.method === "POST") {
+                if (!storage) {
+                    res.writeHead(501);
+                    return res.end(JSON.stringify({ error: { code: "no_storage", message: "Chưa cấu hình storage", status: 501 } }));
+                }
+                if (!cookies.csrf || req.headers["x-csrf-token"] !== cookies.csrf)
+                    throw new FluxeError("csrf", "CSRF không hợp lệ", 403);
+                const boundary = boundaryFromContentType(req.headers["content-type"]);
+                if (!boundary)
+                    throw new FluxeError("upload", "Cần multipart/form-data", 400);
+                const files = parseMultipart(await readBodyBuffer(req), boundary).filter((p) => p.filename);
+                if (!files.length)
+                    throw new FluxeError("upload", "Không có file", 400);
+                const out = [];
+                for (const f of files) {
+                    const key = makeKey(f.filename, randomBytes(8).toString("hex"));
+                    out.push(await storage.put(key, f.data, { contentType: f.contentType }));
+                }
+                res.writeHead(200, { "content-type": "application/json" });
+                return res.end(JSON.stringify(out.length === 1 ? out[0] : out));
+            }
+            // Serve file: GET /__file/<key> → storage.get → stream về.
+            if (url.pathname.startsWith("/__file/") && req.method === "GET") {
+                if (!storage) {
+                    res.writeHead(404);
+                    return res.end();
+                }
+                const key = decodeURIComponent(url.pathname.slice("/__file/".length));
+                const file = await storage.get(key);
+                if (!file) {
+                    res.writeHead(404);
+                    return res.end();
+                }
+                res.writeHead(200, { "content-type": file.contentType ?? "application/octet-stream", "content-length": String(file.size) });
+                return res.end(file.data);
+            }
             if (url.pathname.startsWith("/__sse/")) {
                 // Realtime channel (SSE): giữ kết nối, đẩy event khi publish trên topic. ?id= → presence.
                 const topic = decodeURIComponent(url.pathname.slice("/__sse/".length));

package/lib/storage/local.d.ts

@@ -0,0 +1,5 @@
+import type { Storage } from "./types.ts";
+export declare function createLocalStorage(opts: {
+    dir: string;
+    baseUrl?: string;
+}): Storage;

package/lib/storage/local.js

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+import { mkdir, writeFile, readFile, unlink } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { safeKey } from "./types.js";
+/* Driver đĩa local — ghi dưới `dir`, serve qua baseUrl (/__file/<key>). Key được làm sạch
+ * (safeKey) nên không thoát thư mục (path traversal). */
+export function createLocalStorage(opts) {
+    const baseUrl = opts.baseUrl ?? "/__file";
+    const pathOf = (key) => join(opts.dir, safeKey(key)); // chặn ../
+    const u = (key) => `${baseUrl}/${encodeURIComponent(safeKey(key))}`;
+    return {
+        name: "local",
+        async put(key, data, _opts) {
+            const p = pathOf(key);
+            await mkdir(dirname(p), { recursive: true });
+            await writeFile(p, data);
+            return { key: safeKey(key), url: u(key), size: data.length };
+        },
+        async get(key) {
+            try {
+                const data = await readFile(pathOf(key));
+                return { data, size: data.length };
+            }
+            catch {
+                return null;
+            }
+        },
+        async delete(key) {
+            try {
+                await unlink(pathOf(key));
+            }
+            catch { /* không có thì thôi */ }
+        },
+        url: u,
+    };
+}

package/lib/storage/memory.d.ts

@@ -0,0 +1,2 @@
+import type { Storage } from "./types.ts";
+export declare function createMemoryStorage(baseUrl?: string): Storage;

package/lib/storage/memory.js

@@ -0,0 +1,19 @@
+/* Driver in-RAM (dev/test). 0 đĩa, mất khi restart. */
+export function createMemoryStorage(baseUrl = "/__file") {
+    const m = new Map();
+    const u = (key) => `${baseUrl}/${encodeURIComponent(key)}`;
+    return {
+        name: "memory",
+        async put(key, data, opts) {
+            m.set(key, { data, contentType: opts?.contentType, size: data.length });
+            return { key, url: u(key), size: data.length };
+        },
+        async get(key) {
+            return m.get(key) ?? null;
+        },
+        async delete(key) {
+            m.delete(key);
+        },
+        url: u,
+    };
+}

package/lib/storage/s3.d.ts

@@ -0,0 +1,6 @@
+import type { Storage } from "./types.ts";
+export declare function createS3Storage(opts: {
+    bucket: string;
+    region: string;
+    publicBaseUrl?: string;
+}): Storage;

package/lib/storage/s3.js

@@ -0,0 +1,28 @@
+import { safeKey } from "./types.js";
+export function createS3Storage(opts) {
+    const base = opts.publicBaseUrl ?? `https://${opts.bucket}.s3.${opts.region}.amazonaws.com`;
+    const u = (key) => `${base}/${safeKey(key)}`;
+    // Khi đã `npm i @aws-sdk/client-s3`, thay phần ném lỗi bằng lệnh thật (mẫu trong comment).
+    const notReady = () => {
+        throw new Error("createS3Storage: cài '@aws-sdk/client-s3' rồi bỏ comment phần triển khai trong src/storage/s3.ts");
+    };
+    return {
+        name: "s3",
+        async put(key, _data, _o) {
+            notReady();
+            // await client.send(new PutObjectCommand({ Bucket: opts.bucket, Key: safeKey(key), Body: _data, ContentType: _o?.contentType }));
+            return { key: safeKey(key), url: u(key), size: _data.length };
+        },
+        async get(_key) {
+            notReady();
+            // const r = await client.send(new GetObjectCommand({ Bucket: opts.bucket, Key: safeKey(_key) }));
+            // return { data: Buffer.from(await r.Body!.transformToByteArray()), contentType: r.ContentType, size: r.ContentLength ?? 0 };
+            return null;
+        },
+        async delete(_key) {
+            notReady();
+            // await client.send(new DeleteObjectCommand({ Bucket: opts.bucket, Key: safeKey(_key) }));
+        },
+        url: u,
+    };
+}

package/lib/storage/types.d.ts

@@ -0,0 +1,21 @@
+export interface PutResult {
+    key: string;
+    url: string;
+    size: number;
+}
+export interface GetResult {
+    data: Buffer;
+    contentType?: string;
+    size: number;
+}
+export interface Storage {
+    name: string;
+    put(key: string, data: Buffer, opts?: {
+        contentType?: string;
+    }): Promise<PutResult>;
+    get(key: string): Promise<GetResult | null>;
+    delete(key: string): Promise<void>;
+    url(key: string): string;
+}
+export declare function safeKey(name: string): string;
+export declare function makeKey(filename: string, randomHex: string): string;

package/lib/storage/types.js

@@ -0,0 +1,14 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Storage Adapter — interface chuẩn để SWITCH driver lưu file (như Backend).
+ * Cell/endpoint chỉ biết interface này; đổi local ↔ S3 ↔ … = thay implementation. */
+/* Làm sạch tên file → key an toàn (không slash, không '..', chỉ [A-Za-z0-9._-]). */
+export function safeKey(name) {
+    const base = name.split(/[\\/]/).pop() ?? name; // bỏ path
+    const clean = base.replace(/[^A-Za-z0-9._-]/g, "_").replace(/\.{2,}/g, "_");
+    return clean.slice(0, 120) || "file";
+}
+/* Sinh key duy nhất: <randomHex>-<safeName>. randomHex truyền vào để thuần (test dễ). */
+export function makeKey(filename, randomHex) {
+    return `${randomHex}-${safeKey(filename)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmvuong92/fluxe",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "fluxe — khung fullstack tối giản polyglot (RCA: Resolved Cell Architecture).",
   "license": "Apache-2.0",
   "author": "nmvuong92",