@kb-labs/adapters 0.5.0

package/packages/adapters-fs/src/secure-storage.test.ts

@@ -0,0 +1,380 @@
+/**
+ * @module @kb-labs/adapters-fs/__tests__/secure-storage
+ * Unit tests for SecureStorageAdapter
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import { createAdapter } from "./index.js";
+import {
+  SecureStorageAdapter,
+  StoragePermissionError,
+} from "./secure-storage.js";
+
+describe("SecureStorageAdapter", () => {
+  let tmpDir: string;
+  let baseStorage: ReturnType<typeof createAdapter>;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "kb-test-secure-"));
+    baseStorage = createAdapter({ baseDir: tmpDir });
+
+    // Create some test files
+    await baseStorage.write("public/file.txt", Buffer.from("public"));
+    await baseStorage.write("private/secret.txt", Buffer.from("secret"));
+    await baseStorage.write("docs/readme.md", Buffer.from("readme"));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("Operation Permissions", () => {
+    it("should allow read when permission granted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, { read: true });
+
+      const content = await secure.read("public/file.txt");
+
+      expect(content?.toString()).toBe("public");
+    });
+
+    it("should deny read when permission not granted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, { read: false });
+
+      await expect(secure.read("public/file.txt")).rejects.toThrow(
+        StoragePermissionError,
+      );
+      await expect(secure.read("public/file.txt")).rejects.toThrow(
+        "read operations are disabled",
+      );
+    });
+
+    it("should allow write when permission granted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, { write: true });
+
+      await secure.write("new/file.txt", Buffer.from("new content"));
+
+      const content = await baseStorage.read("new/file.txt");
+      expect(content?.toString()).toBe("new content");
+    });
+
+    it("should deny write when permission not granted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, { write: false });
+
+      await expect(
+        secure.write("new/file.txt", Buffer.from("test")),
+      ).rejects.toThrow(StoragePermissionError);
+    });
+
+    it("should allow delete when permission granted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, { delete: true });
+
+      await secure.delete("public/file.txt");
+
+      expect(await baseStorage.exists("public/file.txt")).toBe(false);
+    });
+
+    it("should deny delete when permission explicitly set to false", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, { delete: false });
+
+      await expect(secure.delete("public/file.txt")).rejects.toThrow(
+        StoragePermissionError,
+      );
+      await expect(secure.delete("public/file.txt")).rejects.toThrow(
+        "delete operations are disabled",
+      );
+    });
+  });
+
+  describe("Path Allowlist", () => {
+    it("should allow access to allowlisted paths", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/", "docs/"],
+        read: true,
+      });
+
+      const content1 = await secure.read("public/file.txt");
+      const content2 = await secure.read("docs/readme.md");
+
+      expect(content1?.toString()).toBe("public");
+      expect(content2?.toString()).toBe("readme");
+    });
+
+    it("should deny access to non-allowlisted paths", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+      });
+
+      await expect(secure.read("private/secret.txt")).rejects.toThrow(
+        StoragePermissionError,
+      );
+      await expect(secure.read("private/secret.txt")).rejects.toThrow(
+        "not in allowlist",
+      );
+    });
+
+    it("should work with empty allowlist (allow all)", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: [],
+        read: true,
+      });
+
+      const content = await secure.read("private/secret.txt");
+
+      expect(content?.toString()).toBe("secret");
+    });
+
+    it("should work with undefined allowlist (allow all)", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        read: true,
+      });
+
+      const content = await secure.read("private/secret.txt");
+
+      expect(content?.toString()).toBe("secret");
+    });
+  });
+
+  describe("Path Denylist", () => {
+    it("should deny access to denylisted paths", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        denylist: ["private/"],
+        read: true,
+      });
+
+      await expect(secure.read("private/secret.txt")).rejects.toThrow(
+        StoragePermissionError,
+      );
+      await expect(secure.read("private/secret.txt")).rejects.toThrow(
+        "path matches denylist",
+      );
+    });
+
+    it("should allow access to non-denylisted paths", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        denylist: ["private/"],
+        read: true,
+      });
+
+      const content = await secure.read("public/file.txt");
+
+      expect(content?.toString()).toBe("public");
+    });
+
+    it("should give denylist precedence over allowlist", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["private/"],
+        denylist: ["private/"],
+        read: true,
+      });
+
+      await expect(secure.read("private/secret.txt")).rejects.toThrow(
+        StoragePermissionError,
+      );
+      await expect(secure.read("private/secret.txt")).rejects.toThrow(
+        "path matches denylist",
+      );
+    });
+  });
+
+  describe("List Operations with Permissions", () => {
+    it("should list files respecting permissions", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+      });
+
+      const files = await secure.list("public/");
+
+      expect(files).toContain("public/file.txt");
+    });
+
+    it("should deny list for non-allowlisted paths", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+      });
+
+      await expect(secure.list("private/")).rejects.toThrow(
+        StoragePermissionError,
+      );
+    });
+  });
+
+  describe("Exists with Permissions", () => {
+    it("should check existence when allowed", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+      });
+
+      expect(await secure.exists("public/file.txt")).toBe(true);
+    });
+
+    it("should return false for denied paths (security by obscurity)", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+      });
+
+      // exists() returns false for denied paths instead of throwing error
+      // This prevents information leakage about file existence
+      expect(await secure.exists("private/secret.txt")).toBe(false);
+    });
+  });
+
+  describe("Extended Methods with Permissions", () => {
+    it("should allow stat when permitted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+      });
+
+      const metadata = await secure.stat?.("public/file.txt");
+
+      expect(metadata).not.toBeNull();
+      expect(metadata?.path).toBe("public/file.txt");
+    });
+
+    it("should deny stat when not permitted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+      });
+
+      await expect(secure.stat?.("private/secret.txt")).rejects.toThrow(
+        StoragePermissionError,
+      );
+    });
+
+    it("should allow copy when both paths permitted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+        write: true,
+      });
+
+      await secure.copy?.("public/file.txt", "public/copy.txt");
+
+      expect(await baseStorage.exists("public/copy.txt")).toBe(true);
+    });
+
+    it("should deny copy when source not permitted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+        write: true,
+      });
+
+      await expect(
+        secure.copy?.("private/secret.txt", "public/copy.txt"),
+      ).rejects.toThrow(StoragePermissionError);
+    });
+
+    it("should deny copy when destination not permitted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+        write: true,
+      });
+
+      await expect(
+        secure.copy?.("public/file.txt", "private/copy.txt"),
+      ).rejects.toThrow(StoragePermissionError);
+    });
+
+    it("should allow move when both paths permitted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+        write: true,
+      });
+
+      await secure.move?.("public/file.txt", "public/moved.txt");
+
+      expect(await baseStorage.exists("public/file.txt")).toBe(false);
+      expect(await baseStorage.exists("public/moved.txt")).toBe(true);
+    });
+
+    it("should allow listWithMetadata when permitted", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/"],
+        read: true,
+      });
+
+      const files = await secure.listWithMetadata?.("public/");
+
+      expect(files).toBeDefined();
+      expect(files!.length).toBeGreaterThan(0);
+      expect(files![0]!.path).toBeDefined();
+    });
+  });
+
+  describe("Complex Permission Scenarios", () => {
+    it("should handle multiple allowlist patterns", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/", "docs/"],
+        read: true,
+      });
+
+      const content1 = await secure.read("public/file.txt");
+      const content2 = await secure.read("docs/readme.md");
+
+      expect(content1).not.toBeNull();
+      expect(content2).not.toBeNull();
+    });
+
+    it("should handle multiple denylist patterns", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        denylist: ["private/", "secrets/"],
+        read: true,
+      });
+
+      await expect(secure.read("private/secret.txt")).rejects.toThrow(
+        StoragePermissionError,
+      );
+    });
+
+    it("should combine allowlist and denylist correctly", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        allowlist: ["public/", "private/"],
+        denylist: ["private/"],
+        read: true,
+      });
+
+      // public/ is in allowlist and not in denylist - allowed
+      const content = await secure.read("public/file.txt");
+      expect(content).not.toBeNull();
+
+      // private/ is in both - denylist takes precedence - denied
+      await expect(secure.read("private/secret.txt")).rejects.toThrow(
+        StoragePermissionError,
+      );
+    });
+
+    it("should handle read-only permissions", async () => {
+      const secure = new SecureStorageAdapter(baseStorage, {
+        read: true,
+        write: false,
+        delete: false,
+      });
+
+      // Can read
+      const content = await secure.read("public/file.txt");
+      expect(content).not.toBeNull();
+
+      // Cannot write
+      await expect(
+        secure.write("new.txt", Buffer.from("test")),
+      ).rejects.toThrow(StoragePermissionError);
+
+      // Cannot delete
+      await expect(secure.delete("public/file.txt")).rejects.toThrow(
+        StoragePermissionError,
+      );
+    });
+  });
+});

package/packages/adapters-fs/src/secure-storage.ts

@@ -0,0 +1,268 @@
+/**
+ * @module @kb-labs/adapters-fs/secure-storage
+ * SecureStorageAdapter - IStorage wrapper with permission validation.
+ *
+ * Design Philosophy: Validation-only security (like fs-shim)
+ * - Validates paths against allowlists/denylists
+ * - Does NOT rewrite paths or queries
+ * - Fails fast with clear errors
+ * - Transparent pass-through when permitted
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@kb-labs/adapters-fs';
+ * import { SecureStorageAdapter } from '@kb-labs/adapters-fs/secure-storage';
+ *
+ * const base = createAdapter({ baseDir: '/var/data' });
+ * const secure = new SecureStorageAdapter(base, {
+ *   allowlist: ['docs/', 'uploads/'],
+ *   denylist: ['uploads/private/'],
+ * });
+ *
+ * await secure.write('docs/readme.md', Buffer.from('# Hello')); // ✅ Allowed
+ * await secure.write('config/secrets.json', Buffer.from('{}')); // ❌ Denied
+ * ```
+ */
+
+import type {
+  IStorage,
+  StorageMetadata,
+} from "@kb-labs/core-platform/adapters";
+
+/**
+ * Permission configuration for storage access.
+ */
+export interface StoragePermissions {
+  /**
+   * Allowed path prefixes (e.g., ['docs/', 'uploads/']).
+   * If empty or undefined, all paths are allowed (unless denied).
+   */
+  allowlist?: string[];
+
+  /**
+   * Denied path prefixes (e.g., ['config/', 'secrets/']).
+   * Takes precedence over allowlist.
+   */
+  denylist?: string[];
+
+  /**
+   * Allow read operations (default: true)
+   */
+  read?: boolean;
+
+  /**
+   * Allow write operations (default: true)
+   */
+  write?: boolean;
+
+  /**
+   * Allow delete operations (default: false - safer default)
+   */
+  delete?: boolean;
+}
+
+/**
+ * Error thrown when storage access is denied.
+ */
+export class StoragePermissionError extends Error {
+  constructor(
+    public readonly operation: string,
+    public readonly path: string,
+    public readonly reason: string,
+  ) {
+    super(`Storage access denied: ${operation} ${path} - ${reason}`);
+    this.name = "StoragePermissionError";
+  }
+}
+
+/**
+ * SecureStorageAdapter - validates permissions before delegating to base storage.
+ *
+ * Design:
+ * - Validation-only (no path rewriting)
+ * - Fails fast with clear errors
+ * - Transparent pass-through when permitted
+ * - Supports both coarse (read/write/delete) and fine (path-based) permissions
+ */
+export class SecureStorageAdapter implements IStorage {
+  constructor(
+    private readonly baseStorage: IStorage,
+    private readonly permissions: StoragePermissions,
+  ) {}
+
+  /**
+   * Check if a path is allowed by permissions.
+   */
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- Security-critical permission check with denylist/allowlist logic
+  private checkPath(
+    path: string,
+    operation: "read" | "write" | "delete",
+  ): void {
+    // Check operation-level permissions
+    const operationAllowed = this.permissions[operation] !== false;
+    if (!operationAllowed) {
+      throw new StoragePermissionError(
+        operation,
+        path,
+        `${operation} operations are disabled`,
+      );
+    }
+
+    // Check denylist first (takes precedence)
+    if (this.permissions.denylist) {
+      for (const denied of this.permissions.denylist) {
+        if (path.startsWith(denied)) {
+          throw new StoragePermissionError(
+            operation,
+            path,
+            `path matches denylist: ${denied}`,
+          );
+        }
+      }
+    }
+
+    // Check allowlist (if defined)
+    if (this.permissions.allowlist && this.permissions.allowlist.length > 0) {
+      let allowed = false;
+      for (const prefix of this.permissions.allowlist) {
+        if (path.startsWith(prefix)) {
+          allowed = true;
+          break;
+        }
+      }
+
+      if (!allowed) {
+        throw new StoragePermissionError(
+          operation,
+          path,
+          `path not in allowlist: [${this.permissions.allowlist.join(", ")}]`,
+        );
+      }
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // Core IStorage methods (required)
+  // ═══════════════════════════════════════════════════════════════════════
+
+  async read(path: string): Promise<Buffer | null> {
+    this.checkPath(path, "read");
+    return this.baseStorage.read(path);
+  }
+
+  async write(path: string, data: Buffer): Promise<void> {
+    this.checkPath(path, "write");
+    await this.baseStorage.write(path, data);
+  }
+
+  async delete(path: string): Promise<void> {
+    this.checkPath(path, "delete");
+    await this.baseStorage.delete(path);
+  }
+
+  async list(prefix: string): Promise<string[]> {
+    this.checkPath(prefix, "read");
+    const files = await this.baseStorage.list(prefix);
+
+    // Filter results by permissions (double-check each file)
+    return files.filter((file) => {
+      try {
+        this.checkPath(file, "read");
+        return true;
+      } catch {
+        return false; // Silently exclude files that don't pass permission check
+      }
+    });
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      this.checkPath(path, "read");
+      return await this.baseStorage.exists(path);
+    } catch (error) {
+      if (error instanceof StoragePermissionError) {
+        return false; // Treat permission denied as "not exists" for safety
+      }
+      throw error;
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // Extended IStorage methods (optional)
+  // ═══════════════════════════════════════════════════════════════════════
+
+  async stat?(path: string): Promise<StorageMetadata | null> {
+    if (!this.baseStorage.stat) {
+      return null;
+    }
+
+    this.checkPath(path, "read");
+    return this.baseStorage.stat(path);
+  }
+
+  async copy?(sourcePath: string, destPath: string): Promise<void> {
+    if (!this.baseStorage.copy) {
+      throw new Error("copy() not supported by base storage adapter");
+    }
+
+    this.checkPath(sourcePath, "read");
+    this.checkPath(destPath, "write");
+    await this.baseStorage.copy(sourcePath, destPath);
+  }
+
+  async move?(sourcePath: string, destPath: string): Promise<void> {
+    if (!this.baseStorage.move) {
+      throw new Error("move() not supported by base storage adapter");
+    }
+
+    this.checkPath(sourcePath, "read");
+    this.checkPath(sourcePath, "delete"); // Move = read + delete source
+    this.checkPath(destPath, "write");
+    await this.baseStorage.move(sourcePath, destPath);
+  }
+
+  async listWithMetadata?(prefix: string): Promise<StorageMetadata[]> {
+    if (!this.baseStorage.listWithMetadata) {
+      return [];
+    }
+
+    this.checkPath(prefix, "read");
+    const files = await this.baseStorage.listWithMetadata(prefix);
+
+    // Filter results by permissions (double-check each file)
+    return files.filter((file) => {
+      try {
+        this.checkPath(file.path, "read");
+        return true;
+      } catch {
+        return false; // Silently exclude files that don't pass permission check
+      }
+    });
+  }
+}
+
+/**
+ * Create secure storage adapter with permission validation.
+ *
+ * @param baseStorage - Base storage adapter (filesystem, S3, etc.)
+ * @param permissions - Permission configuration
+ * @returns Wrapped storage adapter with permission checks
+ *
+ * @example
+ * ```typescript
+ * const secure = createSecureStorage(base, {
+ *   allowlist: ['docs/', 'uploads/'],
+ *   denylist: ['uploads/private/'],
+ *   delete: false, // Prevent deletions
+ * });
+ * ```
+ */
+export function createSecureStorage(
+  baseStorage: IStorage,
+  permissions: StoragePermissions,
+): SecureStorageAdapter {
+  return new SecureStorageAdapter(baseStorage, permissions);
+}
+
+// Default export for direct import
+export default createSecureStorage;

package/packages/adapters-fs/test.json

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

package/packages/adapters-fs/test.txt

@@ -0,0 +1 @@
+text

package/packages/adapters-fs/test.xyz

@@ -0,0 +1 @@
+data

package/packages/adapters-fs/test1.txt

@@ -0,0 +1 @@
+content1

package/packages/adapters-fs/test2.txt

@@ -0,0 +1 @@
+content2

package/packages/adapters-fs/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/adapters-fs/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/packages/adapters-fs/tsup.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  dts: true,
+});