@frontmcp/utils 1.10.16 → 1.11.0-rc.2

package/browser/storage/encrypted-typed-storage.mjs

@@ -0,0 +1,329 @@
+// libs/utils/src/storage/encrypted-typed-storage.ts
+import { encryptAesGcm, decryptAesGcm, randomBytes, base64urlEncode, base64urlDecode, hkdfSha256 } from "../crypto/index.mjs";
+import { EncryptedStorageError } from "./errors.mjs";
+var textEncoder = new TextEncoder();
+var textDecoder = new TextDecoder();
+var EncryptedTypedStorage = class {
+  storage;
+  activeKey;
+  keyMap;
+  schema;
+  throwOnError;
+  onKeyRotationNeeded;
+  clientBinding;
+  constructor(storage, options) {
+    if (!options.keys || options.keys.length === 0) {
+      throw new EncryptedStorageError("At least one encryption key is required");
+    }
+    for (const k of options.keys) {
+      if (k.key.length !== 32) {
+        throw new EncryptedStorageError(
+          `Encryption key "${k.kid}" must be 32 bytes (AES-256), got ${k.key.length} bytes`
+        );
+      }
+    }
+    this.storage = storage;
+    this.activeKey = options.keys[0];
+    this.keyMap = new Map(options.keys.map((k) => [k.kid, k.key]));
+    this.schema = options.schema;
+    this.throwOnError = options.throwOnError ?? false;
+    this.onKeyRotationNeeded = options.onKeyRotationNeeded;
+    this.clientBinding = options.clientBinding;
+  }
+  /**
+   * Get a decrypted value by key.
+   *
+   * @param key - Storage key
+   * @returns The decrypted value, or null if not found or decryption fails
+   */
+  async get(key) {
+    const raw = await this.storage.get(key);
+    if (raw === null) {
+      return null;
+    }
+    return this.decryptAndParse(raw, key);
+  }
+  /**
+   * Encrypt and store a value.
+   *
+   * @param key - Storage key
+   * @param value - Value to encrypt and store
+   * @param options - Optional TTL and conditional flags
+   */
+  async set(key, value, options) {
+    const encrypted = this.encryptValue(value);
+    const serialized = JSON.stringify(encrypted);
+    await this.storage.set(key, serialized, options);
+  }
+  /**
+   * Delete a key.
+   *
+   * @param key - Storage key
+   * @returns true if key existed and was deleted
+   */
+  async delete(key) {
+    return this.storage.delete(key);
+  }
+  /**
+   * Check if a key exists.
+   *
+   * @param key - Storage key
+   * @returns true if key exists
+   */
+  async exists(key) {
+    return this.storage.exists(key);
+  }
+  /**
+   * Get multiple decrypted values.
+   *
+   * @param keys - Array of storage keys
+   * @returns Array of decrypted values (null for missing/invalid keys)
+   */
+  async mget(keys) {
+    if (keys.length === 0) {
+      return [];
+    }
+    const rawValues = await this.storage.mget(keys);
+    return rawValues.map((raw, index) => {
+      if (raw === null) {
+        return null;
+      }
+      return this.decryptAndParse(raw, keys[index]);
+    });
+  }
+  /**
+   * Encrypt and store multiple values.
+   *
+   * @param entries - Array of key-value-options entries
+   */
+  async mset(entries) {
+    if (entries.length === 0) {
+      return;
+    }
+    const rawEntries = entries.map((entry) => ({
+      key: entry.key,
+      value: JSON.stringify(this.encryptValue(entry.value)),
+      options: entry.options
+    }));
+    await this.storage.mset(rawEntries);
+  }
+  /**
+   * Delete multiple keys.
+   *
+   * @param keys - Array of storage keys
+   * @returns Number of keys actually deleted
+   */
+  async mdelete(keys) {
+    return this.storage.mdelete(keys);
+  }
+  /**
+   * Update TTL on an existing key.
+   *
+   * @param key - Storage key
+   * @param ttlSeconds - New TTL in seconds
+   * @returns true if key exists and TTL was set
+   */
+  async expire(key, ttlSeconds) {
+    return this.storage.expire(key, ttlSeconds);
+  }
+  /**
+   * Get remaining TTL for a key.
+   *
+   * @param key - Storage key
+   * @returns TTL in seconds, -1 if no TTL, or null if key doesn't exist
+   */
+  async ttl(key) {
+    return this.storage.ttl(key);
+  }
+  /**
+   * List keys matching a pattern.
+   *
+   * @param pattern - Glob pattern (default: '*' for all keys)
+   * @returns Array of matching keys
+   */
+  async keys(pattern) {
+    return this.storage.keys(pattern);
+  }
+  /**
+   * Count keys matching a pattern.
+   *
+   * @param pattern - Glob pattern (default: '*' for all keys)
+   * @returns Number of matching keys
+   */
+  async count(pattern) {
+    return this.storage.count(pattern);
+  }
+  /**
+   * Re-encrypt a value with the active key.
+   * Useful for key rotation - reads with old key, writes with new key.
+   *
+   * @param key - Storage key to re-encrypt
+   * @param options - Optional TTL for the re-encrypted value
+   * @returns true if value was re-encrypted, false if not found
+   */
+  async reencrypt(key, options) {
+    const value = await this.get(key);
+    if (value === null) {
+      return false;
+    }
+    await this.set(key, value, options);
+    return true;
+  }
+  /**
+   * Rotate the active encryption key.
+   * New encryptions will use the new key; old keys remain for decryption.
+   *
+   * @param newKey - New encryption key to use for writes
+   */
+  rotateKey(newKey) {
+    if (newKey.key.length !== 32) {
+      throw new EncryptedStorageError(`New encryption key must be 32 bytes (AES-256), got ${newKey.key.length} bytes`);
+    }
+    if (!this.keyMap.has(newKey.kid)) {
+      this.keyMap.set(newKey.kid, newKey.key);
+    }
+    this.activeKey = newKey;
+  }
+  /**
+   * Get the active key ID.
+   */
+  get activeKeyId() {
+    return this.activeKey.kid;
+  }
+  /**
+   * Get all known key IDs.
+   */
+  get keyIds() {
+    return Array.from(this.keyMap.keys());
+  }
+  /**
+   * Get the underlying storage adapter.
+   * Use with caution - operations bypass encryption.
+   */
+  get raw() {
+    return this.storage;
+  }
+  /**
+   * Check if client-side key binding is enabled.
+   * When true, encryption keys are derived from both server key and client secret.
+   */
+  get hasClientBinding() {
+    return this.clientBinding !== void 0;
+  }
+  /**
+   * Derive the actual encryption key.
+   *
+   * If clientBinding is configured, combines server key with client secret
+   * using HKDF-SHA256 (RFC 5869) to produce the actual encryption key.
+   * Otherwise, returns the server key as-is.
+   *
+   * This provides zero-knowledge encryption where:
+   * - Server cannot decrypt without client secret (sessionId)
+   * - Client cannot decrypt without server key
+   * - Key derivation is deterministic (same inputs -> same derived key)
+   *
+   * @param serverKey - The server-side encryption key
+   * @returns The key to use for actual encryption/decryption
+   */
+  deriveKey(serverKey) {
+    if (!this.clientBinding) {
+      return serverKey;
+    }
+    const clientSecret = typeof this.clientBinding.secret === "string" ? textEncoder.encode(this.clientBinding.secret) : this.clientBinding.secret;
+    const ikm = new Uint8Array(serverKey.length + clientSecret.length);
+    ikm.set(serverKey, 0);
+    ikm.set(clientSecret, serverKey.length);
+    const salt = this.clientBinding.salt ?? new Uint8Array(0);
+    const info = textEncoder.encode(this.clientBinding.info ?? "frontmcp-client-bound-v1");
+    return hkdfSha256(ikm, salt, info, 32);
+  }
+  /**
+   * Encrypt a value using the active key.
+   * If client binding is configured, uses derived key from server key + client secret.
+   */
+  encryptValue(value) {
+    let jsonString;
+    try {
+      jsonString = JSON.stringify(value);
+    } catch (error) {
+      throw new EncryptedStorageError(`Failed to serialize value: ${error.message}`);
+    }
+    const plaintext = textEncoder.encode(jsonString);
+    const iv = randomBytes(12);
+    const encryptionKey = this.deriveKey(this.activeKey.key);
+    const { ciphertext, tag } = encryptAesGcm(encryptionKey, plaintext, iv);
+    return {
+      alg: "A256GCM",
+      kid: this.activeKey.kid,
+      iv: base64urlEncode(iv),
+      tag: base64urlEncode(tag),
+      data: base64urlEncode(ciphertext)
+    };
+  }
+  /**
+   * Decrypt and parse a stored value.
+   */
+  decryptAndParse(raw, storageKey) {
+    let blob;
+    try {
+      blob = JSON.parse(raw);
+    } catch (_error) {
+      if (this.throwOnError) {
+        throw new EncryptedStorageError(`Failed to parse stored blob for key "${storageKey}"`);
+      }
+      return null;
+    }
+    if (!this.isValidBlob(blob)) {
+      if (this.throwOnError) {
+        throw new EncryptedStorageError(`Invalid encrypted blob structure for key "${storageKey}"`);
+      }
+      return null;
+    }
+    const serverKey = this.keyMap.get(blob.kid);
+    if (!serverKey) {
+      if (this.throwOnError) {
+        throw new EncryptedStorageError(
+          `Unknown encryption key "${blob.kid}" for key "${storageKey}". Known keys: ${Array.from(this.keyMap.keys()).join(", ")}`
+        );
+      }
+      return null;
+    }
+    const decryptionKey = this.deriveKey(serverKey);
+    let decrypted;
+    try {
+      const iv = base64urlDecode(blob.iv);
+      const tag = base64urlDecode(blob.tag);
+      const ciphertext = base64urlDecode(blob.data);
+      const plaintext = decryptAesGcm(decryptionKey, ciphertext, iv, tag);
+      decrypted = JSON.parse(textDecoder.decode(plaintext));
+    } catch (error) {
+      if (this.throwOnError) {
+        throw new EncryptedStorageError(`Decryption failed for key "${storageKey}": ${error.message}`);
+      }
+      return null;
+    }
+    if (this.schema) {
+      const result = this.schema.safeParse(decrypted);
+      if (!result.success) {
+        if (this.throwOnError) {
+          throw new EncryptedStorageError(`Schema validation failed for key "${storageKey}": ${result.error.message}`);
+        }
+        return null;
+      }
+      decrypted = result.data;
+    }
+    if (blob.kid !== this.activeKey.kid && this.onKeyRotationNeeded) {
+      this.onKeyRotationNeeded(storageKey, blob.kid, this.activeKey.kid);
+    }
+    return decrypted;
+  }
+  /**
+   * Validate blob structure.
+   */
+  isValidBlob(blob) {
+    return typeof blob === "object" && blob !== null && "alg" in blob && "kid" in blob && "iv" in blob && "tag" in blob && "data" in blob && blob.alg === "A256GCM" && typeof blob.kid === "string" && typeof blob.iv === "string" && typeof blob.tag === "string" && typeof blob.data === "string";
+  }
+};
+export {
+  EncryptedTypedStorage
+};

package/browser/storage/errors.mjs

@@ -0,0 +1,92 @@
+// libs/utils/src/storage/errors.ts
+var StorageError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "StorageError";
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var StorageConnectionError = class extends StorageError {
+  constructor(message, cause, backend) {
+    const fullMessage = cause ? `${message}: ${cause.message}` : message;
+    super(fullMessage, cause);
+    this.backend = backend;
+    this.name = "StorageConnectionError";
+  }
+  backend;
+};
+var StorageOperationError = class extends StorageError {
+  constructor(operation, key, message, cause) {
+    super(`${operation} failed for key "${key}": ${message}`, cause);
+    this.operation = operation;
+    this.key = key;
+    this.name = "StorageOperationError";
+  }
+  operation;
+  key;
+};
+var StorageNotSupportedError = class extends StorageError {
+  constructor(operation, backend, suggestion) {
+    const msg = suggestion ? `${operation} is not supported by ${backend}. ${suggestion}` : `${operation} is not supported by ${backend}`;
+    super(msg);
+    this.operation = operation;
+    this.backend = backend;
+    this.name = "StorageNotSupportedError";
+  }
+  operation;
+  backend;
+};
+var StorageConfigError = class extends StorageError {
+  constructor(backend, message) {
+    super(`Invalid ${backend} configuration: ${message}`);
+    this.backend = backend;
+    this.name = "StorageConfigError";
+  }
+  backend;
+};
+var StorageTTLError = class extends StorageError {
+  constructor(ttl, message) {
+    super(message ?? `Invalid TTL value: ${ttl}. TTL must be a positive integer.`);
+    this.ttl = ttl;
+    this.name = "StorageTTLError";
+  }
+  ttl;
+};
+var StoragePatternError = class extends StorageError {
+  constructor(pattern, message) {
+    super(`Invalid pattern "${pattern}": ${message}`);
+    this.pattern = pattern;
+    this.name = "StoragePatternError";
+  }
+  pattern;
+};
+var StorageNotConnectedError = class extends StorageError {
+  constructor(backend) {
+    super(`Storage backend "${backend}" is not connected. Call connect() first.`);
+    this.backend = backend;
+    this.name = "StorageNotConnectedError";
+  }
+  backend;
+};
+var EncryptedStorageError = class extends StorageError {
+  constructor(message) {
+    super(message);
+    this.name = "EncryptedStorageError";
+  }
+};
+export {
+  EncryptedStorageError,
+  StorageConfigError,
+  StorageConnectionError,
+  StorageError,
+  StorageNotConnectedError,
+  StorageNotSupportedError,
+  StorageOperationError,
+  StoragePatternError,
+  StorageTTLError
+};

package/browser/storage/factory.mjs

@@ -0,0 +1,155 @@
+var __frontmcpModule = typeof process !== "undefined" && typeof process.getBuiltinModule === "function" ? process.getBuiltinModule("module") : undefined;
+const require = __frontmcpModule ? __frontmcpModule.createRequire(import.meta.url || 'file:///') : undefined;
+// __frontmcpCreateRequire
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// libs/utils/src/storage/factory.ts
+import { z } from "@frontmcp/lazy-zod";
+import { getEnv, isProduction } from "../env/browser-env.mjs";
+import { getRuntimeContext } from "../env/browser-runtime-context.mjs";
+import { MemoryStorageAdapter } from "./adapters/memory.mjs";
+import { StorageConfigError } from "./errors.mjs";
+import { createNamespacedStorage, createRootStorage } from "./namespace.mjs";
+var SQLITE_STORAGE_PACKAGE = "@frontmcp/storage-sqlite";
+var PATH_REQUIRED = { error: "is required (the path of the database file)" };
+var sqliteAdapterOptionsSchema = z.object({
+  path: z.string(PATH_REQUIRED).min(1, PATH_REQUIRED),
+  walMode: z.boolean().optional(),
+  busyTimeoutMs: z.number().int().nonnegative().optional(),
+  ttlCleanupIntervalMs: z.number().int().nonnegative().optional(),
+  encryption: z.object({ secret: z.string().min(1) }).optional()
+});
+function parseSqliteOptions(options) {
+  const result = sqliteAdapterOptionsSchema.safeParse(options ?? {});
+  if (result.success) return result.data;
+  const problems = result.error.issues.map((issue) => `sqlite.${issue.path.join(".")}: ${issue.message}`);
+  throw new StorageConfigError("sqlite", problems.join("; "));
+}
+function loadSqliteStorage() {
+  try {
+    return __require(SQLITE_STORAGE_PACKAGE);
+  } catch (error) {
+    const missing = error.code === "MODULE_NOT_FOUND";
+    if (!missing || !String(error.message).includes(SQLITE_STORAGE_PACKAGE)) throw error;
+    throw new StorageConfigError(
+      "sqlite",
+      `the sqlite type needs ${SQLITE_STORAGE_PACKAGE}. Install it with: npm install ${SQLITE_STORAGE_PACKAGE}`
+    );
+  }
+}
+var noDistributedStorageWarned = false;
+function warnNoDistributedStorage() {
+  if (noDistributedStorageWarned || getRuntimeContext().runtime === "browser") return;
+  noDistributedStorageWarned = true;
+  console.warn(
+    "[storage] Warning: No distributed storage backend detected in production. Using in-memory storage. Set REDIS_URL, UPSTASH_REDIS_REST_URL, or KV_REST_API_URL."
+  );
+}
+function detectStorageType() {
+  if (getEnv("UPSTASH_REDIS_REST_URL") && getEnv("UPSTASH_REDIS_REST_TOKEN")) {
+    return "upstash";
+  }
+  if (getEnv("KV_REST_API_URL") && getEnv("KV_REST_API_TOKEN")) {
+    return "vercel-kv";
+  }
+  if (getEnv("REDIS_URL") || getEnv("REDIS_HOST")) {
+    return "redis";
+  }
+  return "memory";
+}
+async function createAdapter(type, config) {
+  switch (type) {
+    case "memory": {
+      return new MemoryStorageAdapter(config.memory);
+    }
+    case "redis": {
+      const { RedisStorageAdapter } = await import("./adapters/redis.mjs");
+      return new RedisStorageAdapter(config.redis);
+    }
+    case "vercel-kv": {
+      const { VercelKvStorageAdapter } = await import("./adapters/vercel-kv.mjs");
+      return new VercelKvStorageAdapter(config.vercelKv);
+    }
+    case "upstash": {
+      const { UpstashStorageAdapter } = await import("./adapters/upstash.mjs");
+      return new UpstashStorageAdapter(config.upstash);
+    }
+    case "sqlite": {
+      const { SqliteStorageAdapter } = loadSqliteStorage();
+      return new SqliteStorageAdapter(parseSqliteOptions(config.sqlite));
+    }
+    case "cloudflare-kv": {
+      if (!config.cloudflareKv) {
+        throw new StorageConfigError(
+          "cloudflare-kv",
+          "cloudflare-kv requires `cloudflareKv: { namespace }` (the KV binding can't be auto-detected)"
+        );
+      }
+      const { CloudflareKvStorageAdapter } = await import("./adapters/cloudflare-kv.mjs");
+      return new CloudflareKvStorageAdapter(config.cloudflareKv);
+    }
+    case "auto":
+      throw new StorageConfigError("auto", "Auto type should be resolved before calling createAdapter");
+    default:
+      throw new StorageConfigError("unknown", `Unknown storage type: ${type}`);
+  }
+}
+async function createStorage(config = {}) {
+  let type = config.type ?? "auto";
+  const fallback = config.fallback ?? (isProduction() ? "error" : "memory");
+  if (type === "auto") {
+    type = detectStorageType();
+    if (type === "memory" && isProduction()) warnNoDistributedStorage();
+  }
+  if (type === "sqlite") parseSqliteOptions(config.sqlite);
+  let adapter;
+  try {
+    adapter = await createAdapter(type, config);
+  } catch (e) {
+    if (fallback === "memory" && type !== "memory") {
+      console.warn(
+        `[storage] Warning: Failed to create ${type} adapter, falling back to memory. Error: ${e instanceof Error ? e.message : String(e)}`
+      );
+      adapter = new MemoryStorageAdapter(config.memory);
+    } else {
+      throw e;
+    }
+  }
+  try {
+    await adapter.connect();
+  } catch (e) {
+    if (fallback === "memory" && type !== "memory") {
+      console.warn(
+        `[storage] Warning: Failed to connect to ${type}, falling back to memory. Error: ${e instanceof Error ? e.message : String(e)}`
+      );
+      adapter = new MemoryStorageAdapter(config.memory);
+      await adapter.connect();
+    } else {
+      throw e;
+    }
+  }
+  if (config.prefix) {
+    return createNamespacedStorage(adapter, config.prefix);
+  }
+  return createRootStorage(adapter);
+}
+function createMemoryStorage(config = {}) {
+  const adapter = new MemoryStorageAdapter(config);
+  if (config.prefix) {
+    return createNamespacedStorage(adapter, config.prefix);
+  }
+  return createRootStorage(adapter);
+}
+function getDetectedStorageType() {
+  return detectStorageType();
+}
+export {
+  createMemoryStorage,
+  createStorage,
+  getDetectedStorageType
+};

package/browser/storage/index.mjs

@@ -0,0 +1,96 @@
+// libs/utils/src/storage/index.ts
+import { createStorage, createMemoryStorage, getDetectedStorageType } from "./factory.mjs";
+import { createChangeFeed, DEFAULT_CHANGE_FEED_COALESCE_MS, DEFAULT_CHANGE_FEED_POLL_INTERVAL_MS } from "./change-feed.mjs";
+import { attachRedisErrorListener, DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS } from "./redis-error-listener.mjs";
+import { mergeRedisUrlFields, describeRedisUrlConflicts } from "./redis-url.mjs";
+import {
+  NamespacedStorageImpl,
+  createRootStorage,
+  createNamespacedStorage,
+  buildPrefix,
+  NAMESPACE_SEPARATOR
+} from "./namespace.mjs";
+import {
+  StorageError,
+  StorageConnectionError,
+  StorageOperationError,
+  StorageNotSupportedError,
+  StorageConfigError,
+  StorageTTLError,
+  StoragePatternError,
+  StorageNotConnectedError,
+  EncryptedStorageError
+} from "./errors.mjs";
+import { TypedStorage } from "./typed-storage.mjs";
+import { EncryptedTypedStorage } from "./encrypted-typed-storage.mjs";
+import {
+  BaseStorageAdapter,
+  MemoryStorageAdapter,
+  RedisStorageAdapter,
+  createRedisClient,
+  VercelKvStorageAdapter,
+  createVercelKvClient,
+  UpstashStorageAdapter,
+  FileSystemStorageAdapter,
+  LocalStorageAdapter,
+  IndexedDBStorageAdapter
+} from "./adapters/index.mjs";
+import { globToRegex, matchesPattern, validatePattern, escapeGlob } from "./utils/pattern.mjs";
+import {
+  MAX_TTL_SECONDS,
+  validateTTL,
+  validateOptionalTTL,
+  ttlToExpiresAt,
+  expiresAtToTTL,
+  isExpired,
+  normalizeTTL
+} from "./utils/ttl.mjs";
+export {
+  BaseStorageAdapter,
+  DEFAULT_CHANGE_FEED_COALESCE_MS,
+  DEFAULT_CHANGE_FEED_POLL_INTERVAL_MS,
+  DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS,
+  EncryptedStorageError,
+  EncryptedTypedStorage,
+  FileSystemStorageAdapter,
+  IndexedDBStorageAdapter,
+  LocalStorageAdapter,
+  MAX_TTL_SECONDS,
+  MemoryStorageAdapter,
+  NAMESPACE_SEPARATOR,
+  NamespacedStorageImpl,
+  RedisStorageAdapter,
+  StorageConfigError,
+  StorageConnectionError,
+  StorageError,
+  StorageNotConnectedError,
+  StorageNotSupportedError,
+  StorageOperationError,
+  StoragePatternError,
+  StorageTTLError,
+  TypedStorage,
+  UpstashStorageAdapter,
+  VercelKvStorageAdapter,
+  attachRedisErrorListener,
+  buildPrefix,
+  createChangeFeed,
+  createMemoryStorage,
+  createNamespacedStorage,
+  createRedisClient,
+  createRootStorage,
+  createStorage,
+  createVercelKvClient,
+  describeRedisUrlConflicts,
+  escapeGlob,
+  expiresAtToTTL,
+  getDetectedStorageType,
+  globToRegex,
+  isExpired,
+  matchesPattern,
+  mergeRedisUrlFields,
+  normalizeTTL,
+  ttlToExpiresAt,
+  validateOptionalTTL,
+  validatePattern,
+  validateTTL
+};