@frontmcp/storage-sqlite 0.1.0

package/index.js

@@ -0,0 +1,553 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// libs/storage-sqlite/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SqliteElicitationStore: () => SqliteElicitationStore,
+  SqliteEventStore: () => SqliteEventStore,
+  SqliteKvStore: () => SqliteKvStore,
+  SqliteSessionStore: () => SqliteSessionStore,
+  decryptValue: () => decryptValue,
+  deriveEncryptionKey: () => deriveEncryptionKey,
+  encryptValue: () => encryptValue,
+  sqliteStorageOptionsSchema: () => sqliteStorageOptionsSchema
+});
+module.exports = __toCommonJS(index_exports);
+
+// libs/storage-sqlite/src/encryption.ts
+var import_utils = require("@frontmcp/utils");
+var HKDF_SALT = new TextEncoder().encode("frontmcp-sqlite-storage-v1");
+var HKDF_INFO = new TextEncoder().encode("aes-256-gcm-value-encryption");
+var KEY_LENGTH = 32;
+function deriveEncryptionKey(secret) {
+  const ikm = new TextEncoder().encode(secret);
+  return (0, import_utils.hkdfSha256)(ikm, HKDF_SALT, HKDF_INFO, KEY_LENGTH);
+}
+var SEPARATOR = ":";
+function encryptValue(key, plaintext) {
+  const iv = (0, import_utils.randomBytes)(12);
+  const plaintextBytes = new TextEncoder().encode(plaintext);
+  const { ciphertext, tag } = (0, import_utils.encryptAesGcm)(key, plaintextBytes, iv);
+  return [(0, import_utils.base64urlEncode)(iv), (0, import_utils.base64urlEncode)(tag), (0, import_utils.base64urlEncode)(ciphertext)].join(SEPARATOR);
+}
+function decryptValue(key, encrypted) {
+  const parts = encrypted.split(SEPARATOR);
+  if (parts.length !== 3) {
+    throw new Error("Invalid encrypted value format");
+  }
+  const iv = (0, import_utils.base64urlDecode)(parts[0]);
+  const tag = (0, import_utils.base64urlDecode)(parts[1]);
+  const ciphertext = (0, import_utils.base64urlDecode)(parts[2]);
+  const plaintext = (0, import_utils.decryptAesGcm)(key, ciphertext, iv, tag);
+  return new TextDecoder().decode(plaintext);
+}
+
+// libs/storage-sqlite/src/sqlite-kv.store.ts
+var SqliteKvStore = class {
+  db;
+  encryptionKey = null;
+  cleanupTimer = null;
+  stmts = null;
+  constructor(options) {
+    const BetterSqlite3 = require("better-sqlite3");
+    try {
+      this.db = new BetterSqlite3(options.path);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`SqliteKvStore: failed to open database at "${options.path}": ${message}`);
+    }
+    if (options.walMode !== false) {
+      this.db.pragma("journal_mode = WAL");
+    }
+    if (options.encryption?.secret) {
+      this.encryptionKey = deriveEncryptionKey(options.encryption.secret);
+    }
+    this.initSchema();
+    this.prepareStatements();
+    const cleanupInterval = options.ttlCleanupIntervalMs ?? 6e4;
+    if (cleanupInterval > 0) {
+      this.cleanupTimer = setInterval(() => this.purgeExpired(), cleanupInterval);
+      if (this.cleanupTimer.unref) {
+        this.cleanupTimer.unref();
+      }
+    }
+  }
+  initSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS kv (
+        key        TEXT PRIMARY KEY,
+        value      TEXT NOT NULL,
+        expires_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_kv_expires ON kv(expires_at) WHERE expires_at IS NOT NULL;
+    `);
+  }
+  prepareStatements() {
+    this.stmts = {
+      get: this.db.prepare("SELECT value, expires_at FROM kv WHERE key = ?"),
+      set: this.db.prepare("INSERT OR REPLACE INTO kv (key, value, expires_at) VALUES (?, ?, ?)"),
+      del: this.db.prepare("DELETE FROM kv WHERE key = ?"),
+      has: this.db.prepare("SELECT 1 FROM kv WHERE key = ? AND (expires_at IS NULL OR expires_at > ?)"),
+      keys: this.db.prepare("SELECT key FROM kv WHERE (expires_at IS NULL OR expires_at > ?)"),
+      keysPattern: this.db.prepare("SELECT key FROM kv WHERE key LIKE ? AND (expires_at IS NULL OR expires_at > ?)"),
+      cleanup: this.db.prepare("DELETE FROM kv WHERE expires_at IS NOT NULL AND expires_at <= ?"),
+      ttl: this.db.prepare("SELECT expires_at FROM kv WHERE key = ?"),
+      expire: this.db.prepare("UPDATE kv SET expires_at = ? WHERE key = ?")
+    };
+  }
+  /**
+   * Return prepared statements, throwing if not yet initialized.
+   */
+  prepared() {
+    if (!this.stmts) {
+      throw new Error("SqliteKvStore: prepared statements not initialized. Was prepareStatements() called?");
+    }
+    return this.stmts;
+  }
+  /**
+   * Get a value by key.
+   * Returns null if key doesn't exist or is expired.
+   */
+  get(key) {
+    const stmts = this.prepared();
+    const row = stmts.get.get(key);
+    if (!row) return null;
+    if (row.expires_at !== null && row.expires_at <= Date.now()) {
+      stmts.del.run(key);
+      return null;
+    }
+    if (this.encryptionKey) {
+      return decryptValue(this.encryptionKey, row.value);
+    }
+    return row.value;
+  }
+  /**
+   * Get a value and parse it as JSON.
+   */
+  getJSON(key) {
+    const value = this.get(key);
+    if (value === null) return null;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Set a key-value pair with optional TTL.
+   *
+   * @param key - The key
+   * @param value - The value to store
+   * @param ttlMs - Time to live in milliseconds (optional)
+   */
+  set(key, value, ttlMs) {
+    const expiresAt = ttlMs !== void 0 ? Date.now() + ttlMs : null;
+    const storedValue = this.encryptionKey ? encryptValue(this.encryptionKey, value) : value;
+    this.prepared().set.run(key, storedValue, expiresAt);
+  }
+  /**
+   * Set a key-value pair with JSON serialization and optional TTL.
+   */
+  setJSON(key, value, ttlMs) {
+    this.set(key, JSON.stringify(value), ttlMs);
+  }
+  /**
+   * Delete a key.
+   */
+  del(key) {
+    this.prepared().del.run(key);
+  }
+  /**
+   * Check if a key exists (and is not expired).
+   */
+  has(key) {
+    const row = this.prepared().has.get(key, Date.now());
+    return row !== void 0;
+  }
+  /**
+   * List keys matching an optional glob-like pattern.
+   * Pattern uses SQL LIKE syntax: `%` for any characters, `_` for single character.
+   *
+   * @param pattern - Optional pattern (uses SQL LIKE). Without pattern, returns all keys.
+   * @returns Array of matching key strings
+   */
+  keys(pattern) {
+    const stmts = this.prepared();
+    const now = Date.now();
+    let rows;
+    if (pattern) {
+      rows = stmts.keysPattern.all(pattern, now);
+    } else {
+      rows = stmts.keys.all(now);
+    }
+    return rows.map((r) => r.key);
+  }
+  /**
+   * Set TTL on an existing key.
+   *
+   * @param key - The key to set expiry on
+   * @param ttlMs - Time to live in milliseconds
+   * @returns true if key exists and TTL was set, false if key doesn't exist
+   */
+  expire(key, ttlMs) {
+    const expiresAt = Date.now() + ttlMs;
+    const result = this.prepared().expire.run(expiresAt, key);
+    return result.changes > 0;
+  }
+  /**
+   * Get remaining TTL for a key in milliseconds.
+   *
+   * @returns TTL in ms, -1 if no expiry, -2 if key doesn't exist
+   */
+  ttl(key) {
+    const stmts = this.prepared();
+    const row = stmts.ttl.get(key);
+    if (!row) return -2;
+    if (row.expires_at === null) return -1;
+    const remaining = row.expires_at - Date.now();
+    if (remaining <= 0) {
+      stmts.del.run(key);
+      return -2;
+    }
+    return remaining;
+  }
+  /**
+   * Purge all expired keys.
+   * Called periodically by the cleanup timer.
+   */
+  purgeExpired() {
+    const result = this.prepared().cleanup.run(Date.now());
+    return result.changes;
+  }
+  /**
+   * Close the database connection and stop cleanup timer.
+   */
+  close() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.db.close();
+  }
+  /**
+   * Get the underlying database instance (for advanced use cases / testing).
+   */
+  getDatabase() {
+    return this.db;
+  }
+};
+
+// libs/storage-sqlite/src/sqlite-session.store.ts
+var import_utils2 = require("@frontmcp/utils");
+var SqliteSessionStore = class {
+  kv;
+  keyPrefix;
+  defaultTtlMs;
+  constructor(options) {
+    this.kv = new SqliteKvStore(options);
+    this.keyPrefix = options.keyPrefix ?? "mcp:session:";
+    this.defaultTtlMs = options.defaultTtlMs ?? 36e5;
+  }
+  sessionKey(sessionId) {
+    return `${this.keyPrefix}${sessionId}`;
+  }
+  async get(sessionId) {
+    return this.kv.getJSON(this.sessionKey(sessionId));
+  }
+  async set(sessionId, session, ttlMs) {
+    this.kv.setJSON(this.sessionKey(sessionId), session, ttlMs ?? this.defaultTtlMs);
+  }
+  async delete(sessionId) {
+    this.kv.del(this.sessionKey(sessionId));
+  }
+  async exists(sessionId) {
+    return this.kv.has(this.sessionKey(sessionId));
+  }
+  allocId() {
+    return (0, import_utils2.randomUUID)();
+  }
+  /**
+   * Close the underlying SQLite connection.
+   */
+  close() {
+    this.kv.close();
+  }
+  /**
+   * Get the underlying KV store (for testing/advanced use).
+   */
+  getKvStore() {
+    return this.kv;
+  }
+};
+
+// libs/storage-sqlite/src/sqlite-elicitation.store.ts
+var import_node_events = require("node:events");
+var SqliteElicitationStore = class {
+  kv;
+  emitter;
+  keyPrefix;
+  constructor(options) {
+    this.kv = new SqliteKvStore(options);
+    this.emitter = new import_node_events.EventEmitter();
+    this.emitter.setMaxListeners(100);
+    this.keyPrefix = options.keyPrefix ?? "mcp:elicit:";
+  }
+  pendingKey(sessionId) {
+    return `${this.keyPrefix}pending:${sessionId}`;
+  }
+  fallbackKey(elicitId) {
+    return `${this.keyPrefix}fallback:${elicitId}`;
+  }
+  resolvedKey(elicitId) {
+    return `${this.keyPrefix}resolved:${elicitId}`;
+  }
+  resultChannel(elicitId) {
+    return `result:${elicitId}`;
+  }
+  fallbackResultChannel(elicitId) {
+    return `fallback-result:${elicitId}`;
+  }
+  async setPending(record) {
+    const ttlMs = record.expiresAt - Date.now();
+    if (ttlMs <= 0) return;
+    this.kv.setJSON(this.pendingKey(record.sessionId), record, ttlMs);
+  }
+  async getPending(sessionId) {
+    return this.kv.getJSON(this.pendingKey(sessionId));
+  }
+  async deletePending(sessionId) {
+    this.kv.del(this.pendingKey(sessionId));
+  }
+  async subscribeResult(elicitId, callback, _sessionId) {
+    const channel = this.resultChannel(elicitId);
+    const handler = (result) => callback(result);
+    this.emitter.on(channel, handler);
+    return async () => {
+      this.emitter.removeListener(channel, handler);
+    };
+  }
+  async publishResult(elicitId, sessionId, result) {
+    this.kv.del(this.pendingKey(sessionId));
+    this.emitter.emit(this.resultChannel(elicitId), result);
+  }
+  async setPendingFallback(record) {
+    const elicitId = record["elicitId"];
+    if (!elicitId) return;
+    this.kv.setJSON(this.fallbackKey(elicitId), record, 3e5);
+  }
+  async getPendingFallback(elicitId, _sessionId) {
+    return this.kv.getJSON(this.fallbackKey(elicitId));
+  }
+  async deletePendingFallback(elicitId) {
+    this.kv.del(this.fallbackKey(elicitId));
+  }
+  async setResolvedResult(elicitId, result, _sessionId) {
+    this.kv.setJSON(this.resolvedKey(elicitId), result, 3e5);
+  }
+  async getResolvedResult(elicitId, _sessionId) {
+    return this.kv.getJSON(this.resolvedKey(elicitId));
+  }
+  async deleteResolvedResult(elicitId) {
+    this.kv.del(this.resolvedKey(elicitId));
+  }
+  async subscribeFallbackResult(elicitId, callback, _sessionId) {
+    const channel = this.fallbackResultChannel(elicitId);
+    const handler = (result) => callback(result);
+    this.emitter.on(channel, handler);
+    return async () => {
+      this.emitter.removeListener(channel, handler);
+    };
+  }
+  async publishFallbackResult(elicitId, _sessionId, result) {
+    this.emitter.emit(this.fallbackResultChannel(elicitId), result);
+  }
+  async destroy() {
+    this.emitter.removeAllListeners();
+    this.kv.close();
+  }
+  /**
+   * Get the underlying KV store (for testing/advanced use).
+   */
+  getKvStore() {
+    return this.kv;
+  }
+};
+
+// libs/storage-sqlite/src/sqlite-event.store.ts
+var SqliteEventStore = class {
+  db;
+  maxEvents;
+  ttlMs;
+  counters = /* @__PURE__ */ new Map();
+  cleanupTimer = null;
+  stmts = null;
+  constructor(options) {
+    const BetterSqlite3 = require("better-sqlite3");
+    try {
+      this.db = new BetterSqlite3(options.path);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`SqliteEventStore: failed to open database at "${options.path}": ${message}`);
+    }
+    if (options.walMode !== false) {
+      this.db.pragma("journal_mode = WAL");
+    }
+    this.maxEvents = options.maxEvents ?? 1e4;
+    this.ttlMs = options.ttlMs ?? 3e5;
+    this.initSchema();
+    this.prepareStatements();
+    const cleanupInterval = options.ttlCleanupIntervalMs ?? 6e4;
+    if (cleanupInterval > 0) {
+      this.cleanupTimer = setInterval(() => this.evictExpired(), cleanupInterval);
+      if (this.cleanupTimer.unref) {
+        this.cleanupTimer.unref();
+      }
+    }
+  }
+  initSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS events (
+        id         TEXT PRIMARY KEY,
+        stream_id  TEXT NOT NULL,
+        message    TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_events_stream ON events(stream_id, created_at);
+      CREATE INDEX IF NOT EXISTS idx_events_created ON events(created_at);
+    `);
+  }
+  prepareStatements() {
+    this.stmts = {
+      insert: this.db.prepare("INSERT INTO events (id, stream_id, message, created_at) VALUES (?, ?, ?, ?)"),
+      getAfter: this.db.prepare(
+        "SELECT id, message, created_at FROM events WHERE stream_id = ? AND rowid > (SELECT rowid FROM events WHERE id = ?) AND created_at > ? ORDER BY rowid ASC"
+      ),
+      getStreamId: this.db.prepare("SELECT stream_id FROM events WHERE id = ?"),
+      count: this.db.prepare("SELECT COUNT(*) as count FROM events"),
+      evictOldest: this.db.prepare(
+        "DELETE FROM events WHERE id IN (SELECT id FROM events ORDER BY created_at ASC LIMIT ?)"
+      ),
+      evictExpired: this.db.prepare("DELETE FROM events WHERE created_at <= ?"),
+      getLastId: this.db.prepare("SELECT id FROM events WHERE stream_id = ? ORDER BY rowid DESC LIMIT 1")
+    };
+  }
+  /**
+   * Return prepared statements, throwing if not yet initialized.
+   */
+  prepared() {
+    if (!this.stmts) {
+      throw new Error("SqliteEventStore: prepared statements not initialized. Was prepareStatements() called?");
+    }
+    return this.stmts;
+  }
+  /**
+   * Get the next counter value for a stream, rehydrating from SQLite on first use.
+   */
+  getNextCounter(streamId) {
+    let counter = this.counters.get(streamId);
+    if (counter === void 0) {
+      const stmts = this.prepared();
+      const row = stmts.getLastId.get(streamId);
+      if (row) {
+        const lastSegment = row.id.split(":").pop();
+        counter = lastSegment ? parseInt(lastSegment, 10) : 0;
+        if (isNaN(counter)) counter = 0;
+      } else {
+        counter = 0;
+      }
+    }
+    counter += 1;
+    this.counters.set(streamId, counter);
+    return counter;
+  }
+  async storeEvent(streamId, message) {
+    const stmts = this.prepared();
+    this.evictExpired();
+    const counter = this.getNextCounter(streamId);
+    const id = `${streamId}:${counter}`;
+    const now = Date.now();
+    stmts.insert.run(id, streamId, JSON.stringify(message), now);
+    const countRow = stmts.count.get();
+    if (countRow.count > this.maxEvents) {
+      const excess = countRow.count - this.maxEvents;
+      stmts.evictOldest.run(excess);
+    }
+    return id;
+  }
+  async replayEventsAfter(lastEventId, { send }) {
+    const stmts = this.prepared();
+    const streamRow = stmts.getStreamId.get(lastEventId);
+    if (!streamRow) {
+      return "default-stream";
+    }
+    const streamId = streamRow.stream_id;
+    const expiryCutoff = Date.now() - this.ttlMs;
+    const rows = stmts.getAfter.all(streamId, lastEventId, expiryCutoff);
+    for (const row of rows) {
+      await send(row.id, JSON.parse(row.message));
+    }
+    return streamId;
+  }
+  evictExpired() {
+    const stmts = this.prepared();
+    const cutoff = Date.now() - this.ttlMs;
+    stmts.evictExpired.run(cutoff);
+  }
+  /**
+   * Close the database connection and stop cleanup timer.
+   */
+  close() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.db.close();
+  }
+  /**
+   * Get the current number of stored events.
+   */
+  get size() {
+    const stmts = this.prepared();
+    const row = stmts.count.get();
+    return row.count;
+  }
+};
+
+// libs/storage-sqlite/src/sqlite.options.ts
+var import_zod = require("zod");
+var sqliteStorageOptionsSchema = import_zod.z.object({
+  path: import_zod.z.string().min(1),
+  encryption: import_zod.z.object({
+    secret: import_zod.z.string().min(1)
+  }).optional(),
+  ttlCleanupIntervalMs: import_zod.z.number().int().positive().optional().default(6e4),
+  walMode: import_zod.z.boolean().optional().default(true)
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SqliteElicitationStore,
+  SqliteEventStore,
+  SqliteKvStore,
+  SqliteSessionStore,
+  decryptValue,
+  deriveEncryptionKey,
+  encryptValue,
+  sqliteStorageOptionsSchema
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@frontmcp/storage-sqlite",
+  "version": "0.1.0",
+  "description": "SQLite storage backend for FrontMCP - local session, elicitation, and event persistence without Redis",
+  "author": "AgentFront <info@agentfront.dev>",
+  "homepage": "https://docs.agentfront.dev",
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp",
+    "sqlite",
+    "storage",
+    "session",
+    "local",
+    "agentfront",
+    "frontmcp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentfront/frontmcp.git",
+    "directory": "libs/storage-sqlite"
+  },
+  "bugs": {
+    "url": "https://github.com/agentfront/frontmcp/issues"
+  },
+  "type": "commonjs",
+  "main": "./index.js",
+  "module": "./esm/index.mjs",
+  "types": "./index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./esm/index.mjs"
+      }
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@frontmcp/utils": "0.9.0",
+    "better-sqlite3": "^12.6.2"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "typescript": "^5.9.3"
+  }
+}