@frontmcp/utils 0.7.2 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -23,12 +23,27 @@
     "url": "https://github.com/agentfront/frontmcp/issues"
   },
   "homepage": "https://github.com/agentfront/frontmcp/blob/main/libs/utils/README.md",
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "dependencies": {
     "@noble/hashes": "^2.0.1",
     "@noble/ciphers": "^2.1.1",
-    "ast-guard": "^2.4.0",
+    "@enclave-vm/ast": "^2.10.1",
     "zod": "^4.0.0"
   },
+  "peerDependencies": {
+    "@vercel/kv": "^2.0.0 || ^3.0.0",
+    "ioredis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@vercel/kv": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
   "type": "commonjs",
   "main": "./index.js",
   "module": "./esm/index.mjs",

package/regex/safe-regex.d.ts

@@ -4,7 +4,7 @@
  * These utilities protect against ReDoS (Regular Expression Denial of Service)
  * attacks by validating patterns and enforcing input length limits.
  */
-import { REDOS_THRESHOLDS } from 'ast-guard';
+import { REDOS_THRESHOLDS } from '@enclave-vm/ast';
 /**
  * Default maximum input length for safe regex operations.
  * Inputs longer than this will be rejected to prevent ReDoS attacks.

package/storage/adapters/filesystem.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Filesystem Storage Adapter
+ *
+ * File-based storage implementation for Node.js environments.
+ * Each key is stored as a separate JSON file in a directory.
+ *
+ * **Node.js only** - throws an error if used in browser environments.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new FileSystemStorageAdapter({
+ *   baseDir: '.frontmcp/storage',
+ * });
+ *
+ * await adapter.connect();
+ * await adapter.set('user:123', JSON.stringify({ name: 'John' }));
+ * const value = await adapter.get('user:123');
+ * await adapter.disconnect();
+ * ```
+ */
+import { BaseStorageAdapter } from './base';
+import type { SetOptions } from '../types';
+/**
+ * Options for FileSystemStorageAdapter.
+ */
+export interface FileSystemAdapterOptions {
+    /**
+     * Base directory for storage (absolute or relative to cwd).
+     * Each key is stored as a file in this directory.
+     */
+    baseDir: string;
+    /**
+     * File extension for stored files.
+     * @default '.json'
+     */
+    extension?: string;
+    /**
+     * Directory permissions (Unix mode).
+     * @default 0o700
+     */
+    dirMode?: number;
+    /**
+     * File permissions (Unix mode).
+     * @default 0o600
+     */
+    fileMode?: number;
+}
+/**
+ * Filesystem-based storage adapter.
+ *
+ * Features:
+ * - Persists data to individual JSON files
+ * - Atomic writes using temp file + rename
+ * - Restricted file permissions (0o600)
+ * - TTL support with lazy expiration
+ *
+ * Limitations:
+ * - No pub/sub support
+ * - TTL not enforced with background sweeper
+ * - Not suitable for high-throughput scenarios
+ *
+ * @example
+ * ```typescript
+ * import { FileSystemStorageAdapter } from '@frontmcp/utils';
+ *
+ * const adapter = new FileSystemStorageAdapter({
+ *   baseDir: '.frontmcp/keys',
+ *   extension: '.json',
+ * });
+ *
+ * await adapter.connect();
+ *
+ * // Store data
+ * await adapter.set('my-key', 'my-value');
+ *
+ * // Retrieve data
+ * const value = await adapter.get('my-key');
+ *
+ * // List all keys
+ * const keys = await adapter.keys();
+ *
+ * await adapter.disconnect();
+ * ```
+ */
+export declare class FileSystemStorageAdapter extends BaseStorageAdapter {
+    protected readonly backendName = "filesystem";
+    private readonly baseDir;
+    private readonly extension;
+    private readonly dirMode;
+    private readonly fileMode;
+    constructor(options: FileSystemAdapterOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    get(key: string): Promise<string | null>;
+    protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number | null>;
+    keys(pattern?: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    /**
+     * Convert a storage key to a file path.
+     * Sanitizes the key to be filesystem-safe.
+     */
+    private keyToPath;
+    /**
+     * Convert a filename back to a storage key.
+     */
+    private pathToKey;
+    /**
+     * Encode a key to be filesystem-safe.
+     * Uses URL encoding to handle special characters.
+     */
+    private encodeKey;
+    /**
+     * Decode a filesystem-safe key back to original.
+     */
+    private decodeKey;
+    /**
+     * Read an entry from a file.
+     */
+    private readEntry;
+    /**
+     * Check if an entry is expired.
+     */
+    private isExpired;
+    /**
+     * Delete a file, returning true if it existed.
+     */
+    private deleteFile;
+    /**
+     * Atomic write: write to temp file then rename.
+     * This ensures we don't corrupt the file if write is interrupted.
+     */
+    private atomicWrite;
+    /**
+     * Get suggestion message for pub/sub not supported error.
+     */
+    protected getPubSubSuggestion(): string;
+}

package/storage/adapters/index.d.ts

@@ -8,3 +8,5 @@ export { MemoryStorageAdapter } from './memory';
 export { RedisStorageAdapter } from './redis';
 export { VercelKvStorageAdapter } from './vercel-kv';
 export { UpstashStorageAdapter } from './upstash';
+export { FileSystemStorageAdapter } from './filesystem';
+export type { FileSystemAdapterOptions } from './filesystem';

package/storage/encrypted-typed-storage.d.ts

@@ -0,0 +1,196 @@
+/**
+ * EncryptedTypedStorage
+ *
+ * A storage wrapper that provides transparent encryption/decryption
+ * with key rotation support on top of StorageAdapter.
+ *
+ * Uses AES-256-GCM for encryption with automatic JSON serialization.
+ *
+ * @example
+ * ```typescript
+ * import { createStorage, EncryptedTypedStorage, randomBytes } from '@frontmcp/utils';
+ *
+ * interface Secret {
+ *   apiKey: string;
+ *   refreshToken: string;
+ * }
+ *
+ * const storage = await createStorage({ type: 'memory' });
+ * const keys = [
+ *   { kid: 'key-2024', key: randomBytes(32) },
+ *   { kid: 'key-2023', key: oldKey }, // For decrypting old data
+ * ];
+ *
+ * const secrets = new EncryptedTypedStorage<Secret>(storage, { keys });
+ *
+ * // Data is encrypted before storage
+ * await secrets.set('user:123', { apiKey: 'sk-...', refreshToken: 'rt-...' });
+ *
+ * // Data is decrypted on retrieval
+ * const secret = await secrets.get('user:123');
+ * ```
+ */
+import type { StorageAdapter, NamespacedStorage, SetOptions } from './types';
+import type { EncryptedTypedStorageOptions, EncryptedSetEntry, EncryptionKey } from './encrypted-typed-storage.types';
+/**
+ * EncryptedTypedStorage provides transparent encryption/decryption
+ * on top of StorageAdapter.
+ *
+ * Features:
+ * - AES-256-GCM encryption for all stored values
+ * - Automatic JSON serialization/deserialization
+ * - Key rotation support (multiple keys, first is active)
+ * - Optional Zod schema validation after decryption
+ * - Batch operations (mget/mset)
+ */
+export declare class EncryptedTypedStorage<T> {
+    private readonly storage;
+    private activeKey;
+    private readonly keyMap;
+    private readonly schema?;
+    private readonly throwOnError;
+    private readonly onKeyRotationNeeded?;
+    private readonly clientBinding?;
+    constructor(storage: StorageAdapter | NamespacedStorage, options: EncryptedTypedStorageOptions<T>);
+    /**
+     * Get a decrypted value by key.
+     *
+     * @param key - Storage key
+     * @returns The decrypted value, or null if not found or decryption fails
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Encrypt and store a value.
+     *
+     * @param key - Storage key
+     * @param value - Value to encrypt and store
+     * @param options - Optional TTL and conditional flags
+     */
+    set(key: string, value: T, options?: SetOptions): Promise<void>;
+    /**
+     * Delete a key.
+     *
+     * @param key - Storage key
+     * @returns true if key existed and was deleted
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists.
+     *
+     * @param key - Storage key
+     * @returns true if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get multiple decrypted values.
+     *
+     * @param keys - Array of storage keys
+     * @returns Array of decrypted values (null for missing/invalid keys)
+     */
+    mget(keys: string[]): Promise<(T | null)[]>;
+    /**
+     * Encrypt and store multiple values.
+     *
+     * @param entries - Array of key-value-options entries
+     */
+    mset(entries: EncryptedSetEntry<T>[]): Promise<void>;
+    /**
+     * Delete multiple keys.
+     *
+     * @param keys - Array of storage keys
+     * @returns Number of keys actually deleted
+     */
+    mdelete(keys: string[]): Promise<number>;
+    /**
+     * 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
+     */
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * 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
+     */
+    ttl(key: string): Promise<number | null>;
+    /**
+     * List keys matching a pattern.
+     *
+     * @param pattern - Glob pattern (default: '*' for all keys)
+     * @returns Array of matching keys
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Count keys matching a pattern.
+     *
+     * @param pattern - Glob pattern (default: '*' for all keys)
+     * @returns Number of matching keys
+     */
+    count(pattern?: string): Promise<number>;
+    /**
+     * 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
+     */
+    reencrypt(key: string, options?: SetOptions): Promise<boolean>;
+    /**
+     * 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: EncryptionKey): void;
+    /**
+     * Get the active key ID.
+     */
+    get activeKeyId(): string;
+    /**
+     * Get all known key IDs.
+     */
+    get keyIds(): string[];
+    /**
+     * Get the underlying storage adapter.
+     * Use with caution - operations bypass encryption.
+     */
+    get raw(): StorageAdapter | NamespacedStorage;
+    /**
+     * Check if client-side key binding is enabled.
+     * When true, encryption keys are derived from both server key and client secret.
+     */
+    get hasClientBinding(): boolean;
+    /**
+     * 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
+     */
+    private deriveKey;
+    /**
+     * Encrypt a value using the active key.
+     * If client binding is configured, uses derived key from server key + client secret.
+     */
+    private encryptValue;
+    /**
+     * Decrypt and parse a stored value.
+     */
+    private decryptAndParse;
+    /**
+     * Validate blob structure.
+     */
+    private isValidBlob;
+}

package/storage/encrypted-typed-storage.types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * EncryptedTypedStorage Types
+ *
+ * Type definitions for the EncryptedTypedStorage wrapper that provides
+ * transparent encryption/decryption with key rotation support.
+ */
+import type { SetOptions } from './types';
+import type { z } from 'zod';
+/**
+ * Encryption key with identifier for key rotation support.
+ */
+export interface EncryptionKey {
+    /**
+     * Unique key identifier.
+     * Used to identify which key was used to encrypt a value.
+     */
+    kid: string;
+    /**
+     * 32-byte (256-bit) AES key.
+     */
+    key: Uint8Array;
+}
+/**
+ * Client-side key binding configuration for SOC2/ISO compliance.
+ *
+ * When provided, the actual encryption key is derived from BOTH
+ * the server key AND a client-provided secret using HKDF-SHA256.
+ *
+ * Security properties:
+ * - Server cannot decrypt without client secret (e.g., sessionId)
+ * - Client cannot decrypt without server key
+ * - Prevents RCE attacks from stealing user data
+ * - Deterministic derivation (same inputs -> same key)
+ *
+ * @example
+ * ```typescript
+ * const storage = new EncryptedTypedStorage(adapter, {
+ *   keys: [{ kid: 'server-2024', key: serverKey }],
+ *   clientBinding: {
+ *     secret: sessionId,  // From MCP client
+ *     info: 'user-secrets-v1'
+ *   }
+ * });
+ * ```
+ */
+export interface ClientKeyBinding {
+    /**
+     * Client-provided secret (e.g., sessionId, token hash).
+     * This MUST be provided by the MCP client for every operation.
+     *
+     * Can be provided as a string (will be UTF-8 encoded) or raw bytes.
+     */
+    secret: Uint8Array | string;
+    /**
+     * Optional salt for HKDF derivation.
+     * If not provided, uses empty salt (per RFC 5869).
+     */
+    salt?: Uint8Array;
+    /**
+     * Domain separation info for HKDF.
+     * Different values produce different keys even with same inputs.
+     * Use to separate keys for different purposes (e.g., 'vault', 'tokens').
+     * @default 'frontmcp-client-bound-v1'
+     */
+    info?: string;
+}
+/**
+ * Options for EncryptedTypedStorage wrapper.
+ */
+export interface EncryptedTypedStorageOptions<T> {
+    /**
+     * Encryption keys for the storage.
+     * First key is the "active" key used for new encryptions.
+     * All keys are tried for decryption (supports key rotation).
+     *
+     * Must have at least one key.
+     */
+    keys: EncryptionKey[];
+    /**
+     * Optional Zod schema for validation after decryption.
+     * If provided, values will be validated after decryption.
+     */
+    schema?: z.ZodType<T>;
+    /**
+     * Whether to throw an error when data fails validation or decryption.
+     * If false (default), returns null for invalid/undecryptable data.
+     * @default false
+     */
+    throwOnError?: boolean;
+    /**
+     * Optional callback when a value is decrypted with a non-active key.
+     * Useful for implementing transparent re-encryption during reads.
+     */
+    onKeyRotationNeeded?: (key: string, oldKid: string, newKid: string) => void;
+    /**
+     * Optional client-side key binding for SOC2/ISO compliance.
+     *
+     * When provided, the actual encryption key is derived from BOTH
+     * the server key AND this client secret using HKDF-SHA256 (RFC 5869).
+     *
+     * Security implications:
+     * - Without the client secret, data CANNOT be decrypted even
+     *   if the server key is compromised
+     * - Prevents RCE attacks from stealing user data
+     * - Each session can only access its own encrypted data
+     *
+     * Omit for debugging/development to use server key directly.
+     */
+    clientBinding?: ClientKeyBinding;
+}
+/**
+ * Options for encrypted set operations.
+ * Re-export for convenience.
+ */
+export type EncryptedSetOptions = SetOptions;
+/**
+ * Entry for batch set operations with encrypted values.
+ */
+export interface EncryptedSetEntry<T> {
+    key: string;
+    value: T;
+    options?: EncryptedSetOptions;
+}
+/**
+ * Encrypted blob stored in the underlying storage.
+ * Includes key ID for identifying which key was used.
+ */
+export interface StoredEncryptedBlob {
+    /** Algorithm used (always A256GCM) */
+    alg: 'A256GCM';
+    /** Key ID used for encryption */
+    kid: string;
+    /** Base64url-encoded initialization vector */
+    iv: string;
+    /** Base64url-encoded authentication tag */
+    tag: string;
+    /** Base64url-encoded ciphertext */
+    data: string;
+}

package/storage/errors.d.ts

@@ -115,3 +115,14 @@ export declare class StorageNotConnectedError extends StorageError {
     readonly backend: string;
     constructor(backend: string);
 }
+/**
+ * Error thrown when encryption/decryption operations fail.
+ *
+ * @example
+ * ```typescript
+ * throw new EncryptedStorageError('Failed to decrypt: invalid key');
+ * ```
+ */
+export declare class EncryptedStorageError extends StorageError {
+    constructor(message: string);
+}

package/storage/index.d.ts

@@ -7,7 +7,12 @@
 export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, } from './types';
 export { createStorage, createMemoryStorage, getDetectedStorageType } from './factory';
 export { NamespacedStorageImpl, createRootStorage, createNamespacedStorage, buildPrefix, NAMESPACE_SEPARATOR, } from './namespace';
-export { StorageError, StorageConnectionError, StorageOperationError, StorageNotSupportedError, StorageConfigError, StorageTTLError, StoragePatternError, StorageNotConnectedError, } from './errors';
-export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, VercelKvStorageAdapter, UpstashStorageAdapter, } from './adapters';
+export { StorageError, StorageConnectionError, StorageOperationError, StorageNotSupportedError, StorageConfigError, StorageTTLError, StoragePatternError, StorageNotConnectedError, EncryptedStorageError, } from './errors';
+export { TypedStorage } from './typed-storage';
+export type { TypedStorageOptions, TypedSetOptions, TypedSetEntry } from './typed-storage.types';
+export { EncryptedTypedStorage } from './encrypted-typed-storage';
+export type { EncryptedTypedStorageOptions, EncryptedSetOptions, EncryptedSetEntry, EncryptionKey, StoredEncryptedBlob, ClientKeyBinding, } from './encrypted-typed-storage.types';
+export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, VercelKvStorageAdapter, UpstashStorageAdapter, FileSystemStorageAdapter, } from './adapters';
+export type { FileSystemAdapterOptions } from './adapters';
 export { globToRegex, matchesPattern, validatePattern, escapeGlob } from './utils/pattern';
 export { MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, } from './utils/ttl';

package/storage/typed-storage.d.ts

@@ -0,0 +1,129 @@
+/**
+ * TypedStorage
+ *
+ * A generic wrapper that provides type-safe JSON serialization
+ * on top of StorageAdapter or NamespacedStorage.
+ *
+ * @example
+ * ```typescript
+ * import { createStorage, TypedStorage } from '@frontmcp/utils';
+ *
+ * interface User {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * const storage = await createStorage({ type: 'memory' });
+ * const users = new TypedStorage<User>(storage);
+ *
+ * await users.set('user:1', { id: '1', name: 'Alice' });
+ * const user = await users.get('user:1');
+ * ```
+ */
+import type { StorageAdapter, NamespacedStorage, SetOptions } from './types';
+import type { TypedStorageOptions, TypedSetEntry } from './typed-storage.types';
+/**
+ * TypedStorage provides type-safe JSON serialization on top of StorageAdapter.
+ *
+ * Features:
+ * - Automatic JSON serialization/deserialization
+ * - Optional Zod schema validation on read
+ * - Custom serializer support
+ * - Batch operations (mget/mset)
+ * - Full StorageAdapter method access
+ */
+export declare class TypedStorage<T> {
+    private readonly storage;
+    private readonly serialize;
+    private readonly deserialize;
+    private readonly schema?;
+    private readonly throwOnInvalid;
+    constructor(storage: StorageAdapter | NamespacedStorage, options?: TypedStorageOptions<T>);
+    /**
+     * Get a typed value by key.
+     *
+     * @param key - Storage key
+     * @returns The typed value, or null if not found or invalid
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Set a typed value with optional TTL.
+     *
+     * @param key - Storage key
+     * @param value - Typed value to store
+     * @param options - Optional TTL and conditional flags
+     */
+    set(key: string, value: T, options?: SetOptions): Promise<void>;
+    /**
+     * Delete a key.
+     *
+     * @param key - Storage key
+     * @returns true if key existed and was deleted
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists.
+     *
+     * @param key - Storage key
+     * @returns true if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get multiple typed values.
+     *
+     * @param keys - Array of storage keys
+     * @returns Array of typed values (null for missing/invalid keys)
+     */
+    mget(keys: string[]): Promise<(T | null)[]>;
+    /**
+     * Set multiple typed values.
+     *
+     * @param entries - Array of key-value-options entries
+     */
+    mset(entries: TypedSetEntry<T>[]): Promise<void>;
+    /**
+     * Delete multiple keys.
+     *
+     * @param keys - Array of storage keys
+     * @returns Number of keys actually deleted
+     */
+    mdelete(keys: string[]): Promise<number>;
+    /**
+     * 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
+     */
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * 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
+     */
+    ttl(key: string): Promise<number | null>;
+    /**
+     * List keys matching a pattern.
+     *
+     * @param pattern - Glob pattern (default: '*' for all keys)
+     * @returns Array of matching keys
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Count keys matching a pattern.
+     *
+     * @param pattern - Glob pattern (default: '*' for all keys)
+     * @returns Number of matching keys
+     */
+    count(pattern?: string): Promise<number>;
+    /**
+     * Get the underlying storage adapter.
+     * Use with caution - operations bypass type safety.
+     */
+    get raw(): StorageAdapter | NamespacedStorage;
+    /**
+     * Parse and validate a raw value.
+     */
+    private parseValue;
+}