@porulle/adapter-local-storage 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @porulle/adapter-local-storage
+
+`StorageAdapter` that writes to the local filesystem. Useful for development and single-node deployments. **Not for production** unless you've thought hard about backups, disk pressure, and multi-instance behavior — use S3 or R2 there.
+
+## Usage
+
+```ts
+import { defineConfig } from "@porulle/core";
+import { localStorageAdapter } from "@porulle/adapter-local-storage";
+
+export default defineConfig({
+  storage: localStorageAdapter({
+    basePath: "./.data/media",
+    baseUrl: "http://localhost:4000/assets",
+  }),
+  // …
+});
+```
+
+Then serve the `basePath` directory at `baseUrl` (the example apps mount Hono's `serveStatic` for `/assets/*`).
+
+## Path-traversal protection
+
+Every key passes through `resolveSafePath()` which:
+
+- Resolves the key against `basePath`
+- Verifies the result stays inside `basePath`
+- Rejects `..`, NUL bytes, absolute paths, and any input that would escape the storage root
+
+This closed a CVE-class arbitrary-file-write surface (a key like `../../../../etc/passwd` would otherwise write outside the storage root). See `packages/core/test/` for the regression tests.
+
+## What it implements
+
+`upload`, `getUrl`, `getSignedUrl`, `delete`, `list` — all return `Result<T>`.
+
+## See also
+
+- [`SECURITY.md`](../../../SECURITY.md) — storage hardening
+- `@porulle/adapter-s3`, `@porulle/adapter-r2` — production storage adapters

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { type StorageAdapter } from "@porulle/core";
+export interface LocalStorageAdapterOptions {
+    basePath: string;
+    baseUrl?: string;
+}
+export declare function localStorageAdapter(options: LocalStorageAdapterOptions): StorageAdapter;
+//# 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":"AAEA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAS1E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiCD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,cAAc,CA6EvF"}

package/dist/index.js

@@ -0,0 +1,101 @@
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { Err, Ok } from "@porulle/core";
+/**
+ * Resolves a key against basePath and verifies the result stays inside
+ * basePath. Rejects path-traversal payloads like `../../etc/passwd`,
+ * absolute paths, and any other input that would escape the storage root.
+ *
+ * Without this guard an upload with key `../../something` would write
+ * outside the storage root (CVE-class: arbitrary file write).
+ */
+function resolveSafePath(basePath, key) {
+    if (typeof key !== "string" || key.length === 0) {
+        throw new Error("Invalid storage key: empty");
+    }
+    // Reject NUL bytes, which can truncate path checks in some libc impls
+    if (key.includes("\0")) {
+        throw new Error("Invalid storage key: contains NUL byte");
+    }
+    const normalizedBase = resolve(basePath);
+    const candidate = resolve(normalizedBase, key);
+    // Candidate must be exactly basePath or a descendant; protect against
+    // boundary-collision (e.g. base=/data, candidate=/data-evil)
+    if (candidate !== normalizedBase &&
+        !candidate.startsWith(normalizedBase + sep)) {
+        throw new Error(`Invalid storage key: path escapes storage root (${key})`);
+    }
+    return candidate;
+}
+export function localStorageAdapter(options) {
+    const baseUrl = options.baseUrl ?? "http://localhost:3000/assets";
+    async function ensureParent(path) {
+        await mkdir(dirname(path), { recursive: true });
+    }
+    return {
+        providerId: "local-storage",
+        async upload(key, data, contentType) {
+            const path = resolveSafePath(options.basePath, key);
+            await ensureParent(path);
+            if (data instanceof ReadableStream) {
+                const reader = data.getReader();
+                const chunks = [];
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (value)
+                        chunks.push(value);
+                }
+                const merged = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+                await writeFile(path, merged);
+            }
+            else {
+                await writeFile(path, Buffer.from(data));
+            }
+            return Ok({
+                key,
+                url: `${baseUrl}/${key}`,
+                contentType,
+            });
+        },
+        async getUrl(key) {
+            return Ok(`${baseUrl}/${key}`);
+        },
+        async getSignedUrl(key, expiresIn) {
+            return Ok(`${baseUrl}/${key}?expiresIn=${expiresIn}`);
+        },
+        async delete(key) {
+            const path = resolveSafePath(options.basePath, key);
+            await rm(path, { force: true });
+            return Ok(undefined);
+        },
+        async list(prefix) {
+            const folder = resolveSafePath(options.basePath, prefix);
+            try {
+                const files = await readdir(folder, { recursive: true });
+                const output = [];
+                for (const file of files) {
+                    const filePath = join(folder, file);
+                    const info = await stat(filePath);
+                    if (info.isDirectory())
+                        continue;
+                    const content = await readFile(filePath);
+                    output.push({
+                        key: file,
+                        url: `${baseUrl}/${prefix}/${file}`,
+                        contentType: "application/octet-stream",
+                        size: content.byteLength,
+                    });
+                }
+                return Ok(output);
+            }
+            catch (error) {
+                return Err({
+                    code: "LIST_FAILED",
+                    message: error instanceof Error ? error.message : "Failed to list files.",
+                });
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@porulle/adapter-local-storage",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@porulle/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "description": "StorageAdapter that writes to the local filesystem. Useful for development and single-node deployments. **Not for production** unless you've thought hard about backups, disk pressure, and multi-instan",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/adapters/adapter-local-storage"
+  },
+  "author": "Porulle contributors"
+}

package/src/index.ts

@@ -0,0 +1,125 @@
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { Err, Ok, type Result, type StorageAdapter } from "@porulle/core";
+
+interface StoredFile {
+  key: string;
+  url: string;
+  contentType: string;
+  size?: number;
+}
+
+export interface LocalStorageAdapterOptions {
+  basePath: string;
+  baseUrl?: string;
+}
+
+/**
+ * Resolves a key against basePath and verifies the result stays inside
+ * basePath. Rejects path-traversal payloads like `../../etc/passwd`,
+ * absolute paths, and any other input that would escape the storage root.
+ *
+ * Without this guard an upload with key `../../something` would write
+ * outside the storage root (CVE-class: arbitrary file write).
+ */
+function resolveSafePath(basePath: string, key: string): string {
+  if (typeof key !== "string" || key.length === 0) {
+    throw new Error("Invalid storage key: empty");
+  }
+  // Reject NUL bytes, which can truncate path checks in some libc impls
+  if (key.includes("\0")) {
+    throw new Error("Invalid storage key: contains NUL byte");
+  }
+  const normalizedBase = resolve(basePath);
+  const candidate = resolve(normalizedBase, key);
+  // Candidate must be exactly basePath or a descendant; protect against
+  // boundary-collision (e.g. base=/data, candidate=/data-evil)
+  if (
+    candidate !== normalizedBase &&
+    !candidate.startsWith(normalizedBase + sep)
+  ) {
+    throw new Error(
+      `Invalid storage key: path escapes storage root (${key})`,
+    );
+  }
+  return candidate;
+}
+
+export function localStorageAdapter(options: LocalStorageAdapterOptions): StorageAdapter {
+  const baseUrl = options.baseUrl ?? "http://localhost:3000/assets";
+
+  async function ensureParent(path: string): Promise<void> {
+    await mkdir(dirname(path), { recursive: true });
+  }
+
+  return {
+    providerId: "local-storage",
+    async upload(key: string, data: ArrayBuffer | ReadableStream, contentType: string): Promise<Result<StoredFile>> {
+      const path = resolveSafePath(options.basePath, key);
+      await ensureParent(path);
+
+      if (data instanceof ReadableStream) {
+        const reader = data.getReader();
+        const chunks: Uint8Array[] = [];
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          if (value) chunks.push(value);
+        }
+        const merged = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+        await writeFile(path, merged);
+      } else {
+        await writeFile(path, Buffer.from(data));
+      }
+
+      return Ok({
+        key,
+        url: `${baseUrl}/${key}`,
+        contentType,
+      });
+    },
+
+    async getUrl(key: string): Promise<Result<string>> {
+      return Ok(`${baseUrl}/${key}`);
+    },
+
+    async getSignedUrl(key: string, expiresIn: number): Promise<Result<string>> {
+      return Ok(`${baseUrl}/${key}?expiresIn=${expiresIn}`);
+    },
+
+    async delete(key: string): Promise<Result<void>> {
+      const path = resolveSafePath(options.basePath, key);
+      await rm(path, { force: true });
+      return Ok(undefined);
+    },
+
+    async list(prefix: string): Promise<Result<StoredFile[]>> {
+      const folder = resolveSafePath(options.basePath, prefix);
+      try {
+        const files = await readdir(folder, { recursive: true }) as string[];
+        const output: StoredFile[] = [];
+
+        for (const file of files) {
+          const filePath = join(folder, file);
+          const info = await stat(filePath);
+          if (info.isDirectory()) continue;
+
+          const content = await readFile(filePath);
+          output.push({
+            key: file,
+            url: `${baseUrl}/${prefix}/${file}`,
+            contentType: "application/octet-stream",
+            size: content.byteLength,
+          });
+        }
+
+        return Ok(output);
+      } catch (error) {
+        return Err({
+          code: "LIST_FAILED",
+          message: error instanceof Error ? error.message : "Failed to list files.",
+        });
+      }
+    },
+  };
+}