@nifrajs/storage 1.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @nifrajs/storage
+
+Blob storage for nifra — one `StorageAdapter` interface, several adapters. The **persistence half of
+[`@nifrajs/uploads`](../uploads)**: `uploads` decides what's allowed (MIME, size, signed URLs, EXIF
+stripping); `storage` puts the bytes somewhere. **Dependency-free.**
+
+```ts
+import { FileStorage } from "@nifrajs/storage"
+
+const storage = new FileStorage("./uploads")
+await storage.put("avatars/u1.png", bytes, { contentType: "image/png" })
+
+const object = await storage.get("avatars/u1.png") // { body, size, contentType?, metadata? } | null
+await storage.delete("avatars/u1.png")
+const keys = await storage.list({ prefix: "avatars/" })
+```
+
+## Adapters
+
+| Adapter | Use | Notes |
+|---|---|---|
+| `MemoryStorage` | dev / tests | not durable, not shared across instances |
+| `FileStorage(root)` | a long-running server (Bun/Node/Deno) | bytes-only: `contentType` inferred from the extension, custom metadata not persisted |
+| `R2Storage(env.BUCKET)` | the edge (Cloudflare R2) | round-trips `contentType` + metadata; binding typed structurally (no `@cloudflare/workers-types`) |
+
+Implement `StorageAdapter` (`put` / `get` / `delete` / `exists` / `list`) for **S3 / GCS / anything else** —
+the same five methods, and your routes don't change.
+
+## Key safety
+
+Keys are POSIX-ish relative paths (`avatars/u1.png`). **Every** adapter rejects unsafe keys — absolute
+paths, `..` traversal, NUL bytes, backslashes — via `assertSafeKey`, so a `FileStorage` key can never
+escape its root and a key valid in one adapter is valid in all.
+
+```ts
+import { assertSafeKey, StorageKeyError } from "@nifrajs/storage"
+```
+
+## API
+
+- `new MemoryStorage()` · `new FileStorage(root)` · `new R2Storage(bucket)`.
+- `put(key, data, { contentType?, metadata? })` — `data` is `Uint8Array | ArrayBuffer | string`.
+- `get(key)` → `{ body, size, contentType?, metadata? } | null` · `delete(key)` · `exists(key)` · `list({ prefix?, limit? })`.
+- `assertSafeKey(key)` / `StorageKeyError` · `toBytes(data)`.

package/dist/file.d.ts

@@ -0,0 +1,14 @@
+import { type ListOptions, type PutOptions, type StorageAdapter, type StorageData, type StorageObject } from "./types.js";
+export declare class FileStorage implements StorageAdapter {
+    private readonly root;
+    constructor(root: string);
+    /** Resolve `key` to an absolute path, asserting it stays inside `root` (defense-in-depth on top of `assertSafeKey`). */
+    private pathFor;
+    put(key: string, data: StorageData, _options?: PutOptions): Promise<void>;
+    get(key: string): Promise<StorageObject | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    list(options?: ListOptions): Promise<string[]>;
+    private walk;
+}
+//# sourceMappingURL=file.d.ts.map

package/dist/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../src/file.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAA;AA4BnB,qBAAa,WAAY,YAAW,cAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;gBAEjB,IAAI,EAAE,MAAM;IAIxB,wHAAwH;IACxH,OAAO,CAAC,OAAO;IAST,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAc/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASrC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAU1C,IAAI;CAgBnB"}

package/dist/file.js

@@ -0,0 +1,110 @@
+/**
+ * Local-filesystem {@link StorageAdapter} for long-running servers (Bun/Node/Deno). Keys map to paths
+ * under `root`; `assertSafeKey` plus a resolved-path containment check keep writes inside `root` (no
+ * traversal). Bytes-only: `contentType` is inferred from the key's extension on read, and custom metadata
+ * is NOT persisted — use `MemoryStorage`/`R2Storage` (or your own adapter) if you need metadata round-tripped.
+ */
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, posix, resolve, sep } from "node:path";
+import { assertSafeKey, StorageKeyError } from "./key.js";
+import { toBytes, } from "./types.js";
+const CONTENT_TYPES = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    avif: "image/avif",
+    svg: "image/svg+xml",
+    pdf: "application/pdf",
+    json: "application/json",
+    txt: "text/plain",
+    csv: "text/csv",
+    html: "text/html",
+    css: "text/css",
+    js: "text/javascript",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    zip: "application/zip",
+};
+function inferContentType(key) {
+    const ext = key.slice(key.lastIndexOf(".") + 1).toLowerCase();
+    return CONTENT_TYPES[ext];
+}
+export class FileStorage {
+    root;
+    constructor(root) {
+        this.root = resolve(root);
+    }
+    /** Resolve `key` to an absolute path, asserting it stays inside `root` (defense-in-depth on top of `assertSafeKey`). */
+    pathFor(key) {
+        assertSafeKey(key);
+        const full = resolve(this.root, key);
+        if (full !== this.root && !full.startsWith(this.root + sep)) {
+            throw new StorageKeyError(`storage key ${JSON.stringify(key)} escapes the storage root`);
+        }
+        return full;
+    }
+    async put(key, data, _options = {}) {
+        const path = this.pathFor(key);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, toBytes(data));
+    }
+    async get(key) {
+        const path = this.pathFor(key);
+        let body;
+        try {
+            body = new Uint8Array(await readFile(path));
+        }
+        catch {
+            return null; // ENOENT (or unreadable) → treated as missing
+        }
+        const contentType = inferContentType(key);
+        return contentType === undefined
+            ? { body, size: body.byteLength }
+            : { body, size: body.byteLength, contentType };
+    }
+    async delete(key) {
+        await rm(this.pathFor(key), { force: true });
+    }
+    async exists(key) {
+        try {
+            await stat(this.pathFor(key));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async list(options = {}) {
+        const keys = [];
+        await this.walk(this.root, "", keys);
+        let out = keys.sort();
+        if (options.prefix !== undefined)
+            out = out.filter((k) => k.startsWith(options.prefix));
+        if (options.limit !== undefined)
+            out = out.slice(0, options.limit);
+        return out;
+    }
+    async walk(dir, prefix, out) {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            return; // missing root → empty listing
+        }
+        for (const name of names) {
+            const full = join(dir, name);
+            // POSIX-join the key segments so listed keys are portable regardless of the host separator.
+            const key = prefix === "" ? name : posix.join(prefix, name);
+            const info = await stat(full);
+            if (info.isDirectory())
+                await this.walk(full, key, out);
+            else if (info.isFile())
+                out.push(key);
+        }
+    }
+}
+//# sourceMappingURL=file.js.map

package/dist/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../src/file.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAML,OAAO,GACR,MAAM,YAAY,CAAA;AAEnB,MAAM,aAAa,GAAqC;IACtD,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,YAAY;IACjB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,eAAe;IACpB,GAAG,EAAE,iBAAiB;IACtB,IAAI,EAAE,kBAAkB;IACxB,GAAG,EAAE,YAAY;IACjB,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,WAAW;IACjB,GAAG,EAAE,UAAU;IACf,EAAE,EAAE,iBAAiB;IACrB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,YAAY;IACjB,GAAG,EAAE,iBAAiB;CACvB,CAAA;AAED,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAA;IAC7D,OAAO,aAAa,CAAC,GAAG,CAAC,CAAA;AAC3B,CAAC;AAED,MAAM,OAAO,WAAW;IACL,IAAI,CAAQ;IAE7B,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;IAED,wHAAwH;IAChH,OAAO,CAAC,GAAW;QACzB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QACpC,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,eAAe,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAA;QAC1F,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,IAAiB,EAAE,WAAuB,EAAE;QACjE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC9B,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAC/C,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;IACtC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,IAAgB,CAAA;QACpB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAA,CAAC,8CAA8C;QAC5D,CAAC;QACD,MAAM,WAAW,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;QACzC,OAAO,WAAW,KAAK,SAAS;YAC9B,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE;YACjC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE,CAAA;IAClD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAC9C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAA;YAC7B,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAAuB,EAAE;QAClC,MAAM,IAAI,GAAa,EAAE,CAAA;QACzB,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,CAAA;QACpC,IAAI,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACrB,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAC9B,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,MAAgB,CAAC,CAAC,CAAA;QACjE,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QAClE,OAAO,GAAG,CAAA;IACZ,CAAC;IAEO,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,MAAc,EAAE,GAAa;QAC3D,IAAI,KAAe,CAAA;QACnB,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,OAAM,CAAC,+BAA+B;QACxC,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;YAC5B,4FAA4F;YAC5F,MAAM,GAAG,GAAG,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;YAC3D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAA;YAC7B,IAAI,IAAI,CAAC,WAAW,EAAE;gBAAE,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;iBAClD,IAAI,IAAI,CAAC,MAAM,EAAE;gBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACvC,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * `@nifrajs/uploads`: `uploads` validates + signs, `storage` puts the bytes somewhere. Adapters cover
+ * dev (memory), a long-running server (local disk), and the edge (Cloudflare R2); implement
+ * {@link StorageAdapter} for S3/GCS/etc. Dependency-free.
+ *
+ *   import { FileStorage } from "@nifrajs/storage"
+ *   const storage = new FileStorage("./uploads")
+ *   await storage.put("avatars/u1.png", bytes, { contentType: "image/png" })
+ *   const object = await storage.get("avatars/u1.png")
+ */
+export { FileStorage } from "./file.js";
+export { assertSafeKey, StorageKeyError } from "./key.js";
+export { MemoryStorage } from "./memory.js";
+export { type R2BucketLike, type R2ObjectLike, R2Storage } from "./r2.js";
+export { type ListOptions, type PutOptions, type StorageAdapter, type StorageData, type StorageObject, toBytes, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,OAAO,GACR,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * `@nifrajs/uploads`: `uploads` validates + signs, `storage` puts the bytes somewhere. Adapters cover
+ * dev (memory), a long-running server (local disk), and the edge (Cloudflare R2); implement
+ * {@link StorageAdapter} for S3/GCS/etc. Dependency-free.
+ *
+ *   import { FileStorage } from "@nifrajs/storage"
+ *   const storage = new FileStorage("./uploads")
+ *   await storage.put("avatars/u1.png", bytes, { contentType: "image/png" })
+ *   const object = await storage.get("avatars/u1.png")
+ */
+export { FileStorage } from "./file.js";
+export { assertSafeKey, StorageKeyError } from "./key.js";
+export { MemoryStorage } from "./memory.js";
+export { R2Storage } from "./r2.js";
+export { toBytes, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAwC,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EAML,OAAO,GACR,MAAM,YAAY,CAAA"}

package/dist/key.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Storage-key safety. A key is a POSIX-ish relative path (`avatars/u1.png`); we reject anything that
+ * could escape a `FileStorage` root or otherwise misbehave — absolute paths, `..` traversal, NUL bytes,
+ * and backslashes (Windows traversal). Enforced by EVERY adapter (not just `FileStorage`) so a key is
+ * portable across them, and so the check can't be forgotten on the one adapter where it's a vulnerability.
+ */
+export declare class StorageKeyError extends Error {
+    readonly name = "StorageKeyError";
+}
+/** Throw {@link StorageKeyError} unless `key` is a safe relative storage key. */
+export declare function assertSafeKey(key: string): void;
+//# sourceMappingURL=key.d.ts.map

package/dist/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAoB;CAC3C;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAc/C"}

package/dist/key.js

@@ -0,0 +1,24 @@
+/**
+ * Storage-key safety. A key is a POSIX-ish relative path (`avatars/u1.png`); we reject anything that
+ * could escape a `FileStorage` root or otherwise misbehave — absolute paths, `..` traversal, NUL bytes,
+ * and backslashes (Windows traversal). Enforced by EVERY adapter (not just `FileStorage`) so a key is
+ * portable across them, and so the check can't be forgotten on the one adapter where it's a vulnerability.
+ */
+export class StorageKeyError extends Error {
+    name = "StorageKeyError";
+}
+/** Throw {@link StorageKeyError} unless `key` is a safe relative storage key. */
+export function assertSafeKey(key) {
+    if (key.length === 0 || key.length > 1024) {
+        throw new StorageKeyError(`storage key must be 1–1024 chars (got ${key.length})`);
+    }
+    if (key.startsWith("/") || key.includes("\\") || key.includes("\0")) {
+        throw new StorageKeyError(`unsafe storage key ${JSON.stringify(key)} (absolute, backslash, or NUL)`);
+    }
+    for (const segment of key.split("/")) {
+        if (segment === "..") {
+            throw new StorageKeyError(`unsafe storage key ${JSON.stringify(key)} (".." path traversal)`);
+        }
+    }
+}
+//# sourceMappingURL=key.js.map

package/dist/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACtB,IAAI,GAAG,iBAAiB,CAAA;CAC3C;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,eAAe,CAAC,yCAAyC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAA;IACnF,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,eAAe,CACvB,sBAAsB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,gCAAgC,CAC1E,CAAA;IACH,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,eAAe,CAAC,sBAAsB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAA;QAC9F,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/memory.d.ts

@@ -0,0 +1,10 @@
+import { type ListOptions, type PutOptions, type StorageAdapter, type StorageData, type StorageObject } from "./types.js";
+export declare class MemoryStorage implements StorageAdapter {
+    private readonly objects;
+    put(key: string, data: StorageData, options?: PutOptions): Promise<void>;
+    get(key: string): Promise<StorageObject | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    list(options?: ListOptions): Promise<string[]>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAA;AAQnB,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAE7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAY/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAMzD"}

package/dist/memory.js

@@ -0,0 +1,47 @@
+/**
+ * In-process {@link StorageAdapter} — a Map of key → bytes + metadata. For dev and tests; not durable
+ * (a restart empties it) and not shared across instances. Methods are `async` so an unsafe key REJECTS
+ * (consistent with the disk/R2 adapters), never throws synchronously.
+ */
+import { assertSafeKey } from "./key.js";
+import { toBytes, } from "./types.js";
+export class MemoryStorage {
+    objects = new Map();
+    async put(key, data, options = {}) {
+        assertSafeKey(key);
+        const entry = { body: toBytes(data) };
+        this.objects.set(key, {
+            ...entry,
+            ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
+            ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
+        });
+    }
+    async get(key) {
+        assertSafeKey(key);
+        const entry = this.objects.get(key);
+        if (entry === undefined)
+            return null;
+        return {
+            body: entry.body,
+            size: entry.body.byteLength,
+            ...(entry.contentType !== undefined ? { contentType: entry.contentType } : {}),
+            ...(entry.metadata !== undefined ? { metadata: entry.metadata } : {}),
+        };
+    }
+    async delete(key) {
+        assertSafeKey(key);
+        this.objects.delete(key);
+    }
+    async exists(key) {
+        assertSafeKey(key);
+        return this.objects.has(key);
+    }
+    async list(options = {}) {
+        const prefix = options.prefix ?? "";
+        let keys = [...this.objects.keys()].filter((k) => k.startsWith(prefix)).sort();
+        if (options.limit !== undefined)
+            keys = keys.slice(0, options.limit);
+        return keys;
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAML,OAAO,GACR,MAAM,YAAY,CAAA;AAQnB,MAAM,OAAO,aAAa;IACP,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAA;IAEnD,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,IAAiB,EAAE,UAAsB,EAAE;QAChE,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,KAAK,GAAU,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAA;QAC5C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;YACpB,GAAG,KAAK;YACR,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QACpC,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;YAC3B,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtE,CAAA;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC9B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAAuB,EAAE;QAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAA;QACnC,IAAI,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC9E,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QACpE,OAAO,IAAI,CAAA;IACb,CAAC;CACF"}

package/dist/r2.d.ts

@@ -0,0 +1,41 @@
+import { type ListOptions, type PutOptions, type StorageAdapter, type StorageData, type StorageObject } from "./types.js";
+/** The slice of R2's object metadata this adapter reads. */
+export interface R2ObjectLike {
+    readonly size: number;
+    readonly httpMetadata?: {
+        readonly contentType?: string;
+    };
+    readonly customMetadata?: Record<string, string>;
+}
+/** The slice of the R2 bucket binding this adapter calls. `env.<BUCKET>` satisfies it. */
+export interface R2BucketLike {
+    put(key: string, value: ArrayBuffer | ArrayBufferView, options?: {
+        httpMetadata?: {
+            contentType?: string;
+        };
+        customMetadata?: Record<string, string>;
+    }): Promise<unknown>;
+    get(key: string): Promise<(R2ObjectLike & {
+        arrayBuffer(): Promise<ArrayBuffer>;
+    }) | null>;
+    head(key: string): Promise<R2ObjectLike | null>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+    }): Promise<{
+        objects: ReadonlyArray<{
+            key: string;
+        }>;
+    }>;
+}
+export declare class R2Storage implements StorageAdapter {
+    private readonly bucket;
+    constructor(bucket: R2BucketLike);
+    put(key: string, data: StorageData, options?: PutOptions): Promise<void>;
+    get(key: string): Promise<StorageObject | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    list(options?: ListOptions): Promise<string[]>;
+}
+//# sourceMappingURL=r2.d.ts.map

package/dist/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../src/r2.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAA;AAEnB,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,YAAY,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACzD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjD;AAED,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,WAAW,GAAG,eAAe,EACpC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAC7F,OAAO,CAAC,OAAO,CAAC,CAAA;IACnB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,YAAY,GAAG;QAAE,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC,CAAA;IAC1F,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;IAC/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,IAAI,CAAC,OAAO,CAAC,EAAE;QACb,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,aAAa,CAAC;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAA;CACzD;AAED,qBAAa,SAAU,YAAW,cAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,YAAY;IAE3C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAe/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAOzD"}

package/dist/r2.js

@@ -0,0 +1,57 @@
+/**
+ * Cloudflare R2 {@link StorageAdapter} — wraps an R2 bucket binding. The binding is typed structurally
+ * (the slice we use), so this stays dependency-free: no `@cloudflare/workers-types`. Pass `env.MY_BUCKET`.
+ *
+ *   const storage = new R2Storage(env.UPLOADS)
+ */
+import { assertSafeKey } from "./key.js";
+import { toBytes, } from "./types.js";
+export class R2Storage {
+    bucket;
+    constructor(bucket) {
+        this.bucket = bucket;
+    }
+    async put(key, data, options = {}) {
+        assertSafeKey(key);
+        const put = {};
+        if (options.contentType !== undefined)
+            put.httpMetadata = { contentType: options.contentType };
+        if (options.metadata !== undefined)
+            put.customMetadata = { ...options.metadata };
+        // R2 wants a copied ArrayBuffer (not a view into a larger buffer).
+        await this.bucket.put(key, toBytes(data).slice().buffer, put);
+    }
+    async get(key) {
+        assertSafeKey(key);
+        const object = await this.bucket.get(key);
+        if (object === null)
+            return null;
+        const body = new Uint8Array(await object.arrayBuffer());
+        return {
+            body,
+            size: object.size,
+            ...(object.httpMetadata?.contentType !== undefined
+                ? { contentType: object.httpMetadata.contentType }
+                : {}),
+            ...(object.customMetadata !== undefined ? { metadata: object.customMetadata } : {}),
+        };
+    }
+    async delete(key) {
+        assertSafeKey(key);
+        await this.bucket.delete(key);
+    }
+    async exists(key) {
+        assertSafeKey(key);
+        return (await this.bucket.head(key)) !== null;
+    }
+    async list(options = {}) {
+        const listOpts = {};
+        if (options.prefix !== undefined)
+            listOpts.prefix = options.prefix;
+        if (options.limit !== undefined)
+            listOpts.limit = options.limit;
+        const result = await this.bucket.list(listOpts);
+        return result.objects.map((o) => o.key);
+    }
+}
+//# sourceMappingURL=r2.js.map

package/dist/r2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.js","sourceRoot":"","sources":["../src/r2.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAML,OAAO,GACR,MAAM,YAAY,CAAA;AAyBnB,MAAM,OAAO,SAAS;IACS;IAA7B,YAA6B,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAErD,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,IAAiB,EAAE,UAAsB,EAAE;QAChE,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,GAAG,GAGL,EAAE,CAAA;QACN,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;YAAE,GAAG,CAAC,YAAY,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAA;QAC9F,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,GAAG,CAAC,cAAc,GAAG,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAA;QAChF,mEAAmE;QACnE,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC/D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACzC,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAA;QAChC,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC,CAAA;QACvD,OAAO;YACL,IAAI;YACJ,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,WAAW,KAAK,SAAS;gBAChD,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,YAAY,CAAC,WAAW,EAAE;gBAClD,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpF,CAAA;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC/B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAA;IAC/C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAAuB,EAAE;QAClC,MAAM,QAAQ,GAAwC,EAAE,CAAA;QACxD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;QAClE,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,QAAQ,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAA;QAC/D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC/C,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACzC,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * `@nifrajs/uploads` (which validates + signs but doesn't store): `uploads` decides what's allowed,
+ * `storage` puts the bytes somewhere. Adapters: {@link MemoryStorage} (dev/test), `FileStorage` (local
+ * disk), `R2Storage` (Cloudflare R2). Bring your own for S3/GCS by implementing {@link StorageAdapter}.
+ */
+/** Accepted `put` payloads — normalized to bytes by each adapter. */
+export type StorageData = Uint8Array | ArrayBuffer | string;
+export interface PutOptions {
+    /** MIME type stored alongside the object (returned by `get`). */
+    readonly contentType?: string;
+    /** Arbitrary string metadata stored with the object. */
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/** An object read back from storage. `body` is buffered (not streamed) — fine for typical uploads. */
+export interface StorageObject {
+    readonly body: Uint8Array;
+    readonly size: number;
+    readonly contentType?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+export interface ListOptions {
+    /** Only keys starting with this prefix. */
+    readonly prefix?: string;
+    /** Cap the number of keys returned. */
+    readonly limit?: number;
+}
+/**
+ * A blob store keyed by string. Keys are POSIX-ish paths (`avatars/u1.png`); every adapter rejects unsafe
+ * keys (absolute, `..` traversal, NUL, backslash) so a key valid in one adapter is valid in all. All
+ * methods are async.
+ */
+export interface StorageAdapter {
+    /** Store `data` under `key`, overwriting any existing object. */
+    put(key: string, data: StorageData, options?: PutOptions): Promise<void>;
+    /** Read the object at `key`, or `null` if it doesn't exist. */
+    get(key: string): Promise<StorageObject | null>;
+    /** Remove `key`. No-op if it doesn't exist. */
+    delete(key: string): Promise<void>;
+    /** Whether an object exists at `key`. */
+    exists(key: string): Promise<boolean>;
+    /** List stored keys (optionally filtered by prefix + capped). */
+    list(options?: ListOptions): Promise<string[]>;
+}
+/** Normalize any accepted payload to bytes. */
+export declare function toBytes(data: StorageData): Uint8Array;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAA;AAE3D,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACrD;AAED,sGAAsG;AACtG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACrD;AAED,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,uCAAuC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxE,+DAA+D;IAC/D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAC/C,+CAA+C;IAC/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,yCAAyC;IACzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrC,iEAAiE;IACjE,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAC/C;AAED,+CAA+C;AAC/C,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAIrD"}

package/dist/types.js

@@ -0,0 +1,15 @@
+/**
+ * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * `@nifrajs/uploads` (which validates + signs but doesn't store): `uploads` decides what's allowed,
+ * `storage` puts the bytes somewhere. Adapters: {@link MemoryStorage} (dev/test), `FileStorage` (local
+ * disk), `R2Storage` (Cloudflare R2). Bring your own for S3/GCS by implementing {@link StorageAdapter}.
+ */
+/** Normalize any accepted payload to bytes. */
+export function toBytes(data) {
+    if (typeof data === "string")
+        return new TextEncoder().encode(data);
+    if (data instanceof Uint8Array)
+        return data;
+    return new Uint8Array(data);
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6CH,+CAA+C;AAC/C,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACnE,IAAI,IAAI,YAAY,UAAU;QAAE,OAAO,IAAI,CAAA;IAC3C,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAA;AAC7B,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@nifrajs/storage",
+  "version": "1.1.0",
+  "description": "Blob storage for nifra — one StorageAdapter interface with memory, local-filesystem, and Cloudflare R2 adapters (key-traversal-safe). The persistence half of @nifrajs/uploads. Dependency-free; bring your own adapter for S3/GCS.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/storage"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/file.ts

@@ -0,0 +1,121 @@
+/**
+ * Local-filesystem {@link StorageAdapter} for long-running servers (Bun/Node/Deno). Keys map to paths
+ * under `root`; `assertSafeKey` plus a resolved-path containment check keep writes inside `root` (no
+ * traversal). Bytes-only: `contentType` is inferred from the key's extension on read, and custom metadata
+ * is NOT persisted — use `MemoryStorage`/`R2Storage` (or your own adapter) if you need metadata round-tripped.
+ */
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises"
+import { dirname, join, posix, resolve, sep } from "node:path"
+import { assertSafeKey, StorageKeyError } from "./key.ts"
+import {
+  type ListOptions,
+  type PutOptions,
+  type StorageAdapter,
+  type StorageData,
+  type StorageObject,
+  toBytes,
+} from "./types.ts"
+
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  svg: "image/svg+xml",
+  pdf: "application/pdf",
+  json: "application/json",
+  txt: "text/plain",
+  csv: "text/csv",
+  html: "text/html",
+  css: "text/css",
+  js: "text/javascript",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mp3: "audio/mpeg",
+  zip: "application/zip",
+}
+
+function inferContentType(key: string): string | undefined {
+  const ext = key.slice(key.lastIndexOf(".") + 1).toLowerCase()
+  return CONTENT_TYPES[ext]
+}
+
+export class FileStorage implements StorageAdapter {
+  private readonly root: string
+
+  constructor(root: string) {
+    this.root = resolve(root)
+  }
+
+  /** Resolve `key` to an absolute path, asserting it stays inside `root` (defense-in-depth on top of `assertSafeKey`). */
+  private pathFor(key: string): string {
+    assertSafeKey(key)
+    const full = resolve(this.root, key)
+    if (full !== this.root && !full.startsWith(this.root + sep)) {
+      throw new StorageKeyError(`storage key ${JSON.stringify(key)} escapes the storage root`)
+    }
+    return full
+  }
+
+  async put(key: string, data: StorageData, _options: PutOptions = {}): Promise<void> {
+    const path = this.pathFor(key)
+    await mkdir(dirname(path), { recursive: true })
+    await writeFile(path, toBytes(data))
+  }
+
+  async get(key: string): Promise<StorageObject | null> {
+    const path = this.pathFor(key)
+    let body: Uint8Array
+    try {
+      body = new Uint8Array(await readFile(path))
+    } catch {
+      return null // ENOENT (or unreadable) → treated as missing
+    }
+    const contentType = inferContentType(key)
+    return contentType === undefined
+      ? { body, size: body.byteLength }
+      : { body, size: body.byteLength, contentType }
+  }
+
+  async delete(key: string): Promise<void> {
+    await rm(this.pathFor(key), { force: true })
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      await stat(this.pathFor(key))
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async list(options: ListOptions = {}): Promise<string[]> {
+    const keys: string[] = []
+    await this.walk(this.root, "", keys)
+    let out = keys.sort()
+    if (options.prefix !== undefined)
+      out = out.filter((k) => k.startsWith(options.prefix as string))
+    if (options.limit !== undefined) out = out.slice(0, options.limit)
+    return out
+  }
+
+  private async walk(dir: string, prefix: string, out: string[]): Promise<void> {
+    let names: string[]
+    try {
+      names = await readdir(dir)
+    } catch {
+      return // missing root → empty listing
+    }
+    for (const name of names) {
+      const full = join(dir, name)
+      // POSIX-join the key segments so listed keys are portable regardless of the host separator.
+      const key = prefix === "" ? name : posix.join(prefix, name)
+      const info = await stat(full)
+      if (info.isDirectory()) await this.walk(full, key, out)
+      else if (info.isFile()) out.push(key)
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * `@nifrajs/uploads`: `uploads` validates + signs, `storage` puts the bytes somewhere. Adapters cover
+ * dev (memory), a long-running server (local disk), and the edge (Cloudflare R2); implement
+ * {@link StorageAdapter} for S3/GCS/etc. Dependency-free.
+ *
+ *   import { FileStorage } from "@nifrajs/storage"
+ *   const storage = new FileStorage("./uploads")
+ *   await storage.put("avatars/u1.png", bytes, { contentType: "image/png" })
+ *   const object = await storage.get("avatars/u1.png")
+ */
+
+export { FileStorage } from "./file.ts"
+export { assertSafeKey, StorageKeyError } from "./key.ts"
+export { MemoryStorage } from "./memory.ts"
+export { type R2BucketLike, type R2ObjectLike, R2Storage } from "./r2.ts"
+export {
+  type ListOptions,
+  type PutOptions,
+  type StorageAdapter,
+  type StorageData,
+  type StorageObject,
+  toBytes,
+} from "./types.ts"

package/src/key.ts

@@ -0,0 +1,27 @@
+/**
+ * Storage-key safety. A key is a POSIX-ish relative path (`avatars/u1.png`); we reject anything that
+ * could escape a `FileStorage` root or otherwise misbehave — absolute paths, `..` traversal, NUL bytes,
+ * and backslashes (Windows traversal). Enforced by EVERY adapter (not just `FileStorage`) so a key is
+ * portable across them, and so the check can't be forgotten on the one adapter where it's a vulnerability.
+ */
+
+export class StorageKeyError extends Error {
+  override readonly name = "StorageKeyError"
+}
+
+/** Throw {@link StorageKeyError} unless `key` is a safe relative storage key. */
+export function assertSafeKey(key: string): void {
+  if (key.length === 0 || key.length > 1024) {
+    throw new StorageKeyError(`storage key must be 1–1024 chars (got ${key.length})`)
+  }
+  if (key.startsWith("/") || key.includes("\\") || key.includes("\0")) {
+    throw new StorageKeyError(
+      `unsafe storage key ${JSON.stringify(key)} (absolute, backslash, or NUL)`,
+    )
+  }
+  for (const segment of key.split("/")) {
+    if (segment === "..") {
+      throw new StorageKeyError(`unsafe storage key ${JSON.stringify(key)} (".." path traversal)`)
+    }
+  }
+}

package/src/memory.ts

@@ -0,0 +1,63 @@
+/**
+ * In-process {@link StorageAdapter} — a Map of key → bytes + metadata. For dev and tests; not durable
+ * (a restart empties it) and not shared across instances. Methods are `async` so an unsafe key REJECTS
+ * (consistent with the disk/R2 adapters), never throws synchronously.
+ */
+import { assertSafeKey } from "./key.ts"
+import {
+  type ListOptions,
+  type PutOptions,
+  type StorageAdapter,
+  type StorageData,
+  type StorageObject,
+  toBytes,
+} from "./types.ts"
+
+interface Entry {
+  readonly body: Uint8Array
+  readonly contentType?: string
+  readonly metadata?: Readonly<Record<string, string>>
+}
+
+export class MemoryStorage implements StorageAdapter {
+  private readonly objects = new Map<string, Entry>()
+
+  async put(key: string, data: StorageData, options: PutOptions = {}): Promise<void> {
+    assertSafeKey(key)
+    const entry: Entry = { body: toBytes(data) }
+    this.objects.set(key, {
+      ...entry,
+      ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
+      ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
+    })
+  }
+
+  async get(key: string): Promise<StorageObject | null> {
+    assertSafeKey(key)
+    const entry = this.objects.get(key)
+    if (entry === undefined) return null
+    return {
+      body: entry.body,
+      size: entry.body.byteLength,
+      ...(entry.contentType !== undefined ? { contentType: entry.contentType } : {}),
+      ...(entry.metadata !== undefined ? { metadata: entry.metadata } : {}),
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    assertSafeKey(key)
+    this.objects.delete(key)
+  }
+
+  async exists(key: string): Promise<boolean> {
+    assertSafeKey(key)
+    return this.objects.has(key)
+  }
+
+  async list(options: ListOptions = {}): Promise<string[]> {
+    const prefix = options.prefix ?? ""
+    let keys = [...this.objects.keys()].filter((k) => k.startsWith(prefix)).sort()
+    if (options.limit !== undefined) keys = keys.slice(0, options.limit)
+    return keys
+  }
+}

package/src/r2.ts

@@ -0,0 +1,87 @@
+/**
+ * Cloudflare R2 {@link StorageAdapter} — wraps an R2 bucket binding. The binding is typed structurally
+ * (the slice we use), so this stays dependency-free: no `@cloudflare/workers-types`. Pass `env.MY_BUCKET`.
+ *
+ *   const storage = new R2Storage(env.UPLOADS)
+ */
+import { assertSafeKey } from "./key.ts"
+import {
+  type ListOptions,
+  type PutOptions,
+  type StorageAdapter,
+  type StorageData,
+  type StorageObject,
+  toBytes,
+} from "./types.ts"
+
+/** The slice of R2's object metadata this adapter reads. */
+export interface R2ObjectLike {
+  readonly size: number
+  readonly httpMetadata?: { readonly contentType?: string }
+  readonly customMetadata?: Record<string, string>
+}
+
+/** The slice of the R2 bucket binding this adapter calls. `env.<BUCKET>` satisfies it. */
+export interface R2BucketLike {
+  put(
+    key: string,
+    value: ArrayBuffer | ArrayBufferView,
+    options?: { httpMetadata?: { contentType?: string }; customMetadata?: Record<string, string> },
+  ): Promise<unknown>
+  get(key: string): Promise<(R2ObjectLike & { arrayBuffer(): Promise<ArrayBuffer> }) | null>
+  head(key: string): Promise<R2ObjectLike | null>
+  delete(key: string): Promise<void>
+  list(options?: {
+    prefix?: string
+    limit?: number
+  }): Promise<{ objects: ReadonlyArray<{ key: string }> }>
+}
+
+export class R2Storage implements StorageAdapter {
+  constructor(private readonly bucket: R2BucketLike) {}
+
+  async put(key: string, data: StorageData, options: PutOptions = {}): Promise<void> {
+    assertSafeKey(key)
+    const put: {
+      httpMetadata?: { contentType?: string }
+      customMetadata?: Record<string, string>
+    } = {}
+    if (options.contentType !== undefined) put.httpMetadata = { contentType: options.contentType }
+    if (options.metadata !== undefined) put.customMetadata = { ...options.metadata }
+    // R2 wants a copied ArrayBuffer (not a view into a larger buffer).
+    await this.bucket.put(key, toBytes(data).slice().buffer, put)
+  }
+
+  async get(key: string): Promise<StorageObject | null> {
+    assertSafeKey(key)
+    const object = await this.bucket.get(key)
+    if (object === null) return null
+    const body = new Uint8Array(await object.arrayBuffer())
+    return {
+      body,
+      size: object.size,
+      ...(object.httpMetadata?.contentType !== undefined
+        ? { contentType: object.httpMetadata.contentType }
+        : {}),
+      ...(object.customMetadata !== undefined ? { metadata: object.customMetadata } : {}),
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    assertSafeKey(key)
+    await this.bucket.delete(key)
+  }
+
+  async exists(key: string): Promise<boolean> {
+    assertSafeKey(key)
+    return (await this.bucket.head(key)) !== null
+  }
+
+  async list(options: ListOptions = {}): Promise<string[]> {
+    const listOpts: { prefix?: string; limit?: number } = {}
+    if (options.prefix !== undefined) listOpts.prefix = options.prefix
+    if (options.limit !== undefined) listOpts.limit = options.limit
+    const result = await this.bucket.list(listOpts)
+    return result.objects.map((o) => o.key)
+  }
+}

package/src/types.ts

@@ -0,0 +1,56 @@
+/**
+ * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * `@nifrajs/uploads` (which validates + signs but doesn't store): `uploads` decides what's allowed,
+ * `storage` puts the bytes somewhere. Adapters: {@link MemoryStorage} (dev/test), `FileStorage` (local
+ * disk), `R2Storage` (Cloudflare R2). Bring your own for S3/GCS by implementing {@link StorageAdapter}.
+ */
+
+/** Accepted `put` payloads — normalized to bytes by each adapter. */
+export type StorageData = Uint8Array | ArrayBuffer | string
+
+export interface PutOptions {
+  /** MIME type stored alongside the object (returned by `get`). */
+  readonly contentType?: string
+  /** Arbitrary string metadata stored with the object. */
+  readonly metadata?: Readonly<Record<string, string>>
+}
+
+/** An object read back from storage. `body` is buffered (not streamed) — fine for typical uploads. */
+export interface StorageObject {
+  readonly body: Uint8Array
+  readonly size: number
+  readonly contentType?: string
+  readonly metadata?: Readonly<Record<string, string>>
+}
+
+export interface ListOptions {
+  /** Only keys starting with this prefix. */
+  readonly prefix?: string
+  /** Cap the number of keys returned. */
+  readonly limit?: number
+}
+
+/**
+ * A blob store keyed by string. Keys are POSIX-ish paths (`avatars/u1.png`); every adapter rejects unsafe
+ * keys (absolute, `..` traversal, NUL, backslash) so a key valid in one adapter is valid in all. All
+ * methods are async.
+ */
+export interface StorageAdapter {
+  /** Store `data` under `key`, overwriting any existing object. */
+  put(key: string, data: StorageData, options?: PutOptions): Promise<void>
+  /** Read the object at `key`, or `null` if it doesn't exist. */
+  get(key: string): Promise<StorageObject | null>
+  /** Remove `key`. No-op if it doesn't exist. */
+  delete(key: string): Promise<void>
+  /** Whether an object exists at `key`. */
+  exists(key: string): Promise<boolean>
+  /** List stored keys (optionally filtered by prefix + capped). */
+  list(options?: ListOptions): Promise<string[]>
+}
+
+/** Normalize any accepted payload to bytes. */
+export function toBytes(data: StorageData): Uint8Array {
+  if (typeof data === "string") return new TextEncoder().encode(data)
+  if (data instanceof Uint8Array) return data
+  return new Uint8Array(data)
+}