@kb-labs/adapters 0.5.0

package/packages/adapters-sqlite/src/manifest.ts

@@ -0,0 +1,47 @@
+/**
+ * @module @kb-labs/adapters-sqlite/manifest
+ * Adapter manifest for SQLite database.
+ */
+
+import type { AdapterManifest } from "@kb-labs/core-platform";
+
+/**
+ * Adapter manifest for SQLite database.
+ */
+export const manifest: AdapterManifest = {
+  manifestVersion: "1.0.0",
+  id: "sqlite-database",
+  name: "SQLite Database",
+  version: "1.0.0",
+  description: "Lightweight embedded SQL database using better-sqlite3",
+  author: "KB Labs Team",
+  license: "KBPL-1.1",
+  type: "core",
+  implements: "ISQLDatabase",
+  contexts: ["workspace"],
+  capabilities: {
+    transactions: true,
+    search: true,
+    custom: {
+      prepared: true,
+      fts: true,
+      json: true,
+    },
+  },
+  configSchema: {
+    filename: {
+      type: "string",
+      description: "Database file path (use :memory: for in-memory database)",
+    },
+    readonly: {
+      type: "boolean",
+      default: false,
+      description: "Open database in readonly mode",
+    },
+    timeout: {
+      type: "number",
+      default: 5000,
+      description: "Busy timeout in milliseconds",
+    },
+  },
+};

package/packages/adapters-sqlite/src/secure-sql.test.ts

@@ -0,0 +1,290 @@
+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 { createSecureSQL, SQLPermissionError } from "./secure-sql.js";
+
+describe("SecureSQLAdapter", () => {
+  let tmpDir: string;
+  let dbPath: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "kb-test-secure-sql-"));
+    dbPath = join(tmpDir, "test.db");
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("Permission Checks", () => {
+    it("should allow read when permission granted", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query(
+        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+        [],
+      );
+      await base.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+      const secure = createSecureSQL(base, { read: true });
+
+      const result = await secure.query<{ name: string }>(
+        "SELECT * FROM users",
+        [],
+      );
+
+      expect(result.rows).toHaveLength(1);
+      await base.close();
+    });
+
+    it("should deny read when permission not granted", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query(
+        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+        [],
+      );
+      const secure = createSecureSQL(base, { read: false });
+
+      await expect(secure.query("SELECT * FROM users", [])).rejects.toThrow(
+        SQLPermissionError,
+      );
+      await base.close();
+    });
+
+    it("should allow write when permission granted", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query(
+        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+        [],
+      );
+      const secure = createSecureSQL(base, { write: true });
+
+      await secure.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+
+      const result = await base.query<{ name: string }>(
+        "SELECT * FROM users",
+        [],
+      );
+      expect(result.rows).toHaveLength(1);
+      await base.close();
+    });
+
+    it("should deny write when permission not granted", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query(
+        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+        [],
+      );
+      const secure = createSecureSQL(base, { write: false });
+
+      await expect(
+        secure.query("INSERT INTO users (name) VALUES (?)", ["Alice"]),
+      ).rejects.toThrow(SQLPermissionError);
+      await base.close();
+    });
+
+    it("should allow delete when permission granted", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query(
+        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+        [],
+      );
+      await base.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+      const secure = createSecureSQL(base, { write: true });
+
+      await secure.query("DELETE FROM users WHERE name = ?", ["Alice"]);
+
+      const result = await base.query<{ name: string }>(
+        "SELECT * FROM users",
+        [],
+      );
+      expect(result.rows).toHaveLength(0);
+      await base.close();
+    });
+
+    it("should deny delete when permission not granted", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query(
+        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+        [],
+      );
+      const secure = createSecureSQL(base, { write: false });
+
+      await expect(secure.query("DELETE FROM users", [])).rejects.toThrow(
+        SQLPermissionError,
+      );
+      await base.close();
+    });
+  });
+
+  describe("Table Allowlist", () => {
+    it("should allow access to allowlisted tables", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query("CREATE TABLE users (id INTEGER PRIMARY KEY)", []);
+      await base.query("CREATE TABLE posts (id INTEGER PRIMARY KEY)", []);
+      const secure = createSecureSQL(base, {
+        allowlist: ["users"],
+        read: true,
+      });
+
+      const result = await secure.query("SELECT * FROM users", []);
+
+      expect(result.rows).toBeDefined();
+      await base.close();
+    });
+
+    it("should deny access to non-allowlisted tables", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query("CREATE TABLE users (id INTEGER PRIMARY KEY)", []);
+      await base.query("CREATE TABLE restricted (id INTEGER PRIMARY KEY)", []);
+      const secure = createSecureSQL(base, {
+        allowlist: ["users"],
+        read: true,
+      });
+
+      await expect(
+        secure.query("SELECT * FROM restricted", []),
+      ).rejects.toThrow(SQLPermissionError);
+      await base.close();
+    });
+
+    it("should handle joins with allowlisted tables", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query("CREATE TABLE users (id INTEGER PRIMARY KEY)", []);
+      await base.query(
+        "CREATE TABLE posts (id INTEGER PRIMARY KEY, user_id INTEGER)",
+        [],
+      );
+      const secure = createSecureSQL(base, {
+        allowlist: ["users", "posts"],
+        read: true,
+      });
+
+      const result = await secure.query(
+        "SELECT * FROM users JOIN posts ON users.id = posts.user_id",
+        [],
+      );
+
+      expect(result.rows).toBeDefined();
+      await base.close();
+    });
+  });
+
+  describe("Table Denylist", () => {
+    it("should deny access to denylisted tables", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query("CREATE TABLE admin_users (id INTEGER PRIMARY KEY)", []);
+      const secure = createSecureSQL(base, {
+        denylist: ["admin_users"],
+        read: true,
+      });
+
+      await expect(
+        secure.query("SELECT * FROM admin_users", []),
+      ).rejects.toThrow(SQLPermissionError);
+      await base.close();
+    });
+
+    it("should denylist take precedence over allowlist", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query("CREATE TABLE conflict (id INTEGER PRIMARY KEY)", []);
+      const secure = createSecureSQL(base, {
+        allowlist: ["conflict"],
+        denylist: ["conflict"],
+        read: true,
+      });
+
+      await expect(secure.query("SELECT * FROM conflict", [])).rejects.toThrow(
+        SQLPermissionError,
+      );
+      await base.close();
+    });
+  });
+
+  describe("Schema Modification Prevention", () => {
+    it("should deny CREATE TABLE when schema=false", async () => {
+      const base = createAdapter({ filename: dbPath });
+      const secure = createSecureSQL(base, { schema: false });
+
+      await expect(
+        secure.query("CREATE TABLE bad (id INTEGER)", []),
+      ).rejects.toThrow(SQLPermissionError);
+      await base.close();
+    });
+
+    it("should deny ALTER TABLE when schema=false", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query("CREATE TABLE users (id INTEGER PRIMARY KEY)", []);
+      const secure = createSecureSQL(base, { schema: false });
+
+      await expect(
+        secure.query("ALTER TABLE users ADD COLUMN name TEXT", []),
+      ).rejects.toThrow(SQLPermissionError);
+      await base.close();
+    });
+
+    it("should deny DROP TABLE when schema=false", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query("CREATE TABLE users (id INTEGER PRIMARY KEY)", []);
+      const secure = createSecureSQL(base, { schema: false });
+
+      await expect(secure.query("DROP TABLE users", [])).rejects.toThrow(
+        SQLPermissionError,
+      );
+      await base.close();
+    });
+
+    it("should allow schema modifications when schema=true", async () => {
+      const base = createAdapter({ filename: dbPath });
+      const secure = createSecureSQL(base, { schema: true });
+
+      await secure.query("CREATE TABLE users (id INTEGER PRIMARY KEY)", []);
+
+      const result = await base.query(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='users'",
+        [],
+      );
+      expect(result.rows).toHaveLength(1);
+      await base.close();
+    });
+  });
+
+  describe("Transactions with Permissions", () => {
+    it("should enforce permissions in transactions", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query(
+        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+        [],
+      );
+      const secure = createSecureSQL(base, { write: false, read: true });
+
+      const tx = await secure.transaction();
+
+      await expect(
+        tx.query("INSERT INTO users (name) VALUES (?)", ["Alice"]),
+      ).rejects.toThrow(SQLPermissionError);
+      await tx.rollback();
+      await base.close();
+    });
+
+    it("should allow valid operations in transactions", async () => {
+      const base = createAdapter({ filename: dbPath });
+      await base.query(
+        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+        [],
+      );
+      const secure = createSecureSQL(base, { write: true });
+
+      const tx = await secure.transaction();
+      await tx.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+      await tx.commit();
+
+      const result = await base.query<{ name: string }>(
+        "SELECT * FROM users",
+        [],
+      );
+      expect(result.rows).toHaveLength(1);
+      await base.close();
+    });
+  });
+});

package/packages/adapters-sqlite/src/secure-sql.ts

@@ -0,0 +1,281 @@
+/**
+ * @module @kb-labs/adapters-sqlite/secure-sql
+ * SecureSQLAdapter - ISQLDatabase wrapper with permission validation.
+ *
+ * Design Philosophy: Validation-only security (like fs-shim)
+ * - Validates table access against allowlists/denylists
+ * - Does NOT rewrite SQL queries
+ * - Fails fast with clear errors
+ * - Transparent pass-through when permitted
+ *
+ * Security Model:
+ * - Extracts table names from SQL using regex (basic, not perfect)
+ * - Checks table names against permissions
+ * - Does NOT parse SQL fully (use a SQL parser library for production)
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@kb-labs/adapters-sqlite';
+ * import { SecureSQLAdapter } from '@kb-labs/adapters-sqlite/secure-sql';
+ *
+ * const base = createAdapter({ filename: 'app.db' });
+ * const secure = new SecureSQLAdapter(base, {
+ *   allowlist: ['users', 'posts', 'comments'],
+ *   denylist: ['admin_users', 'secrets'],
+ * });
+ *
+ * await secure.query('SELECT * FROM users WHERE id = ?', [123]); // ✅ Allowed
+ * await secure.query('SELECT * FROM admin_users LIMIT 1', []); // ❌ Denied
+ * ```
+ */
+
+import type {
+  ISQLDatabase,
+  SQLQueryResult,
+  SQLTransaction,
+} from "@kb-labs/core-platform/adapters";
+
+/**
+ * Permission configuration for SQL database access.
+ */
+export interface SQLPermissions {
+  /**
+   * Allowed table names (e.g., ['users', 'posts']).
+   * If empty or undefined, all tables are allowed (unless denied).
+   */
+  allowlist?: string[];
+
+  /**
+   * Denied table names (e.g., ['admin_users', 'secrets']).
+   * Takes precedence over allowlist.
+   */
+  denylist?: string[];
+
+  /**
+   * Allow read operations (SELECT, PRAGMA) (default: true)
+   */
+  read?: boolean;
+
+  /**
+   * Allow write operations (INSERT, UPDATE, DELETE) (default: true)
+   */
+  write?: boolean;
+
+  /**
+   * Allow schema modifications (CREATE, ALTER, DROP) (default: false - safer default)
+   */
+  schema?: boolean;
+}
+
+/**
+ * Error thrown when SQL access is denied.
+ */
+export class SQLPermissionError extends Error {
+  constructor(
+    public readonly operation: string,
+    public readonly tables: string[],
+    public readonly reason: string,
+  ) {
+    super(
+      `SQL access denied: ${operation} on tables [${tables.join(", ")}] - ${reason}`,
+    );
+    this.name = "SQLPermissionError";
+  }
+}
+
+/**
+ * SecureSQLAdapter - validates permissions before delegating to base database.
+ *
+ * Design:
+ * - Validation-only (no SQL rewriting)
+ * - Fails fast with clear errors
+ * - Transparent pass-through when permitted
+ * - Basic table extraction via regex (not a full SQL parser)
+ *
+ * Limitations:
+ * - Table extraction is regex-based (may miss complex queries)
+ * - Does not handle subqueries, CTEs, or dynamic SQL
+ * - For production, consider using a proper SQL parser library
+ */
+export class SecureSQLAdapter implements ISQLDatabase {
+  constructor(
+    private readonly baseDb: ISQLDatabase,
+    private readonly permissions: SQLPermissions,
+  ) {}
+
+  /**
+   * Extract table names from SQL query.
+   * Uses basic regex - not perfect, but good enough for validation.
+   */
+  private extractTableNames(sql: string): string[] {
+    const tables = new Set<string>();
+
+    // Normalize SQL: uppercase, remove extra spaces
+    const normalized = sql.toUpperCase().replace(/\s+/g, " ").trim();
+
+    // Pattern: FROM/JOIN/INTO/UPDATE <table_name>
+    const patterns = [
+      /FROM\s+([a-zA-Z_][a-zA-Z0-9_]*)/g,
+      /JOIN\s+([a-zA-Z_][a-zA-Z0-9_]*)/g,
+      /INTO\s+([a-zA-Z_][a-zA-Z0-9_]*)/g,
+      /UPDATE\s+([a-zA-Z_][a-zA-Z0-9_]*)/g,
+      /TABLE\s+(?:IF\s+(?:NOT\s+)?EXISTS\s+)?([a-zA-Z_][a-zA-Z0-9_]*)/g, // CREATE/DROP TABLE
+    ];
+
+    for (const pattern of patterns) {
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(normalized)) !== null) {
+        if (match[1]) {
+          tables.add(match[1].toLowerCase());
+        }
+      }
+    }
+
+    return Array.from(tables);
+  }
+
+  /**
+   * Detect SQL operation type.
+   */
+  private detectOperation(sql: string): "read" | "write" | "schema" {
+    const normalized = sql.trim().toUpperCase();
+
+    // Schema operations
+    if (
+      normalized.startsWith("CREATE ") ||
+      normalized.startsWith("ALTER ") ||
+      normalized.startsWith("DROP ")
+    ) {
+      return "schema";
+    }
+
+    // Write operations
+    if (
+      normalized.startsWith("INSERT ") ||
+      normalized.startsWith("UPDATE ") ||
+      normalized.startsWith("DELETE ")
+    ) {
+      return "write";
+    }
+
+    // Read operations (SELECT, PRAGMA, etc.)
+    return "read";
+  }
+
+  /**
+   * Check if SQL query is allowed by permissions.
+   */
+  private checkPermissions(sql: string): void {
+    const operation = this.detectOperation(sql);
+
+    // Check operation-level permissions
+    const operationAllowed = this.permissions[operation] !== false;
+    if (!operationAllowed) {
+      throw new SQLPermissionError(
+        operation,
+        [],
+        `${operation} operations are disabled`,
+      );
+    }
+
+    // Extract table names
+    const tables = this.extractTableNames(sql);
+
+    // Check denylist first (takes precedence)
+    if (this.permissions.denylist) {
+      for (const table of tables) {
+        if (this.permissions.denylist.includes(table)) {
+          throw new SQLPermissionError(
+            operation,
+            tables,
+            `table '${table}' is in denylist`,
+          );
+        }
+      }
+    }
+
+    // Check allowlist (if defined)
+    if (this.permissions.allowlist && this.permissions.allowlist.length > 0) {
+      for (const table of tables) {
+        if (!this.permissions.allowlist.includes(table)) {
+          throw new SQLPermissionError(
+            operation,
+            tables,
+            `table '${table}' not in allowlist: [${this.permissions.allowlist.join(", ")}]`,
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Execute a SQL query with permission checks.
+   */
+  async query<T = unknown>(
+    sql: string,
+    params?: unknown[],
+  ): Promise<SQLQueryResult<T>> {
+    this.checkPermissions(sql);
+    return this.baseDb.query<T>(sql, params);
+  }
+
+  /**
+   * Begin a transaction with permission checks.
+   * Each query inside the transaction is also validated.
+   */
+  async transaction(): Promise<SQLTransaction> {
+    const baseTrx = await this.baseDb.transaction();
+
+    // Wrap transaction object to intercept queries
+    return {
+      query: async <T = unknown>(
+        sql: string,
+        params?: unknown[],
+      ): Promise<SQLQueryResult<T>> => {
+        this.checkPermissions(sql);
+        return baseTrx.query<T>(sql, params);
+      },
+
+      commit: async (): Promise<void> => {
+        await baseTrx.commit();
+      },
+
+      rollback: async (): Promise<void> => {
+        await baseTrx.rollback();
+      },
+    };
+  }
+
+  /**
+   * Close the database connection.
+   */
+  async close(): Promise<void> {
+    await this.baseDb.close();
+  }
+}
+
+/**
+ * Create secure SQL adapter with permission validation.
+ *
+ * @param baseDb - Base SQL adapter (SQLite, PostgreSQL, etc.)
+ * @param permissions - Permission configuration
+ * @returns Wrapped SQL adapter with permission checks
+ *
+ * @example
+ * ```typescript
+ * const secure = createSecureSQL(base, {
+ *   allowlist: ['users', 'posts'],
+ *   denylist: ['admin_users'],
+ *   schema: false, // Prevent schema modifications
+ * });
+ * ```
+ */
+export function createSecureSQL(
+  baseDb: ISQLDatabase,
+  permissions: SQLPermissions,
+): SecureSQLAdapter {
+  return new SecureSQLAdapter(baseDb, permissions);
+}
+
+// Default export for direct import
+export default createSecureSQL;

package/packages/adapters-sqlite/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-sqlite/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-sqlite/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,
+});

package/packages/adapters-sqlite/vitest.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        '**/*.d.ts',
+        '**/*.config.*',
+      ],
+    },
+  },
+});