@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/storage/core/StorageService.js

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Provides a singleton service for interacting with the application's storage layer.
+ * This service acts as a proxy to the configured storage provider, ensuring a consistent
+ * interface for all storage operations throughout the application. It receives its concrete
+ * provider via dependency injection.
+ * @module src/storage/core/StorageService
+ */
+import { validateKey, validateListOptions, validatePrefix, validateStorageOptions, validateTenantId, } from '../../storage/core/storageValidation.js';
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+/**
+ * Validates and returns the tenant ID from the request context.
+ *
+ * This helper ensures the tenant ID is present in the context and passes
+ * validation rules defined in {@link validateTenantId}. All StorageService
+ * operations require a valid tenant ID for multi-tenancy isolation.
+ *
+ * @param context - The request context containing the tenant ID
+ * @returns The validated tenant ID (trimmed of whitespace)
+ * @throws {McpError} JsonRpcErrorCode.InternalError - If tenant ID is missing (undefined or null)
+ * @throws {McpError} JsonRpcErrorCode.InvalidParams - If tenant ID fails validation (from validateTenantId)
+ * @internal
+ */
+function requireTenantId(context) {
+    const tenantId = context.tenantId;
+    // Check if tenant ID is missing (undefined or null)
+    if (tenantId === undefined || tenantId === null) {
+        throw new McpError(JsonRpcErrorCode.InternalError, 'Tenant ID is required for storage operations but was not found in the request context.', {
+            operation: context.operation || 'StorageService.requireTenantId',
+            requestId: context.requestId,
+            // Include call stack hint for debugging
+            calledFrom: 'StorageService',
+        });
+    }
+    // Delegate validation to shared utility
+    validateTenantId(tenantId, context);
+    return tenantId.trim();
+}
+export class StorageService {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+        // Note: Cannot use structured logging in constructor as we don't have RequestContext yet
+        // This is logged when the service is first instantiated by the DI container
+    }
+    get(key, context) {
+        const tenantId = requireTenantId(context);
+        validateKey(key, context);
+        logger.debug('[StorageService] get operation', {
+            ...context,
+            operation: 'StorageService.get',
+            tenantId,
+            key,
+        });
+        return this.provider.get(tenantId, key, context);
+    }
+    set(key, value, context, options) {
+        const tenantId = requireTenantId(context);
+        validateKey(key, context);
+        validateStorageOptions(options, context);
+        logger.debug('[StorageService] set operation', {
+            ...context,
+            operation: 'StorageService.set',
+            tenantId,
+            key,
+            hasTTL: options?.ttl !== undefined,
+            ttl: options?.ttl,
+        });
+        return this.provider.set(tenantId, key, value, context, options);
+    }
+    delete(key, context) {
+        const tenantId = requireTenantId(context);
+        validateKey(key, context);
+        logger.debug('[StorageService] delete operation', {
+            ...context,
+            operation: 'StorageService.delete',
+            tenantId,
+            key,
+        });
+        return this.provider.delete(tenantId, key, context);
+    }
+    list(prefix, context, options) {
+        const tenantId = requireTenantId(context);
+        validatePrefix(prefix, context);
+        validateListOptions(options, context);
+        logger.debug('[StorageService] list operation', {
+            ...context,
+            operation: 'StorageService.list',
+            tenantId,
+            prefix,
+            limit: options?.limit,
+            hasCursor: !!options?.cursor,
+        });
+        return this.provider.list(tenantId, prefix, context, options);
+    }
+    getMany(keys, context) {
+        const tenantId = requireTenantId(context);
+        // Validate all keys
+        for (const key of keys) {
+            validateKey(key, context);
+        }
+        logger.debug('[StorageService] getMany operation', {
+            ...context,
+            operation: 'StorageService.getMany',
+            tenantId,
+            keyCount: keys.length,
+        });
+        return this.provider.getMany(tenantId, keys, context);
+    }
+    setMany(entries, context, options) {
+        const tenantId = requireTenantId(context);
+        validateStorageOptions(options, context);
+        // Validate all keys
+        for (const key of entries.keys()) {
+            validateKey(key, context);
+        }
+        logger.debug('[StorageService] setMany operation', {
+            ...context,
+            operation: 'StorageService.setMany',
+            tenantId,
+            entryCount: entries.size,
+            hasTTL: options?.ttl !== undefined,
+            ttl: options?.ttl,
+        });
+        return this.provider.setMany(tenantId, entries, context, options);
+    }
+    deleteMany(keys, context) {
+        const tenantId = requireTenantId(context);
+        // Validate all keys
+        for (const key of keys) {
+            validateKey(key, context);
+        }
+        logger.debug('[StorageService] deleteMany operation', {
+            ...context,
+            operation: 'StorageService.deleteMany',
+            tenantId,
+            keyCount: keys.length,
+        });
+        return this.provider.deleteMany(tenantId, keys, context);
+    }
+    clear(context) {
+        const tenantId = requireTenantId(context);
+        logger.info('[StorageService] clear operation', {
+            ...context,
+            operation: 'StorageService.clear',
+            tenantId,
+        });
+        return this.provider.clear(tenantId, context);
+    }
+}
+//# sourceMappingURL=StorageService.js.map

package/dist/storage/core/StorageService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageService.js","sourceRoot":"","sources":["../../../src/storage/core/StorageService.ts"],"names":[],"mappings":"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"}

package/dist/storage/core/storageFactory.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Factory function for creating a storage provider based on application configuration.
+ * This module decouples the application from concrete storage implementations, allowing the
+ * storage backend to be selected via environment variables. In a serverless environment,
+ * it defaults to `in-memory` to ensure compatibility.
+ * @module src/storage/core/storageFactory
+ */
+import type { D1Database, KVNamespace, R2Bucket } from '@cloudflare/workers-types';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { AppConfig } from '../../config/index.js';
+import type { IStorageProvider } from '../../storage/core/IStorageProvider.js';
+import type { Database } from '../../storage/providers/supabase/supabase.types.js';
+/**
+ * Optional dependencies for storage provider creation.
+ * Allows pre-resolved dependencies to be passed in, useful for testing
+ * and Worker environments where DI container may not be available.
+ */
+export interface StorageFactoryDeps {
+    /** Cloudflare D1 database binding */
+    readonly d1Database?: D1Database;
+    /** Cloudflare KV namespace binding */
+    readonly kvNamespace?: KVNamespace;
+    /** Cloudflare R2 bucket binding */
+    readonly r2Bucket?: R2Bucket;
+    /** Pre-configured Supabase client */
+    readonly supabaseClient?: SupabaseClient<Database>;
+}
+/**
+ * Creates and returns a storage provider instance based on the provided configuration.
+ *
+ * This factory decouples the application from concrete storage implementations,
+ * allowing the backend to be selected via environment configuration. In serverless
+ * environments, automatically falls back to in-memory storage for non-compatible providers.
+ *
+ * Provider Selection Logic:
+ * - Serverless environment: Only `in-memory`, `cloudflare-r2`, `cloudflare-kv` allowed
+ * - Node environment: All providers available
+ * - Missing config: Throws ConfigurationError
+ *
+ * @param config - The application configuration object, typically resolved from DI container.
+ * @param deps - Optional pre-resolved dependencies for providers (useful for testing/Workers).
+ * @returns An instance of a class that implements the IStorageProvider interface.
+ *
+ * @throws {McpError} JsonRpcErrorCode.ConfigurationError - If:
+ *   - filesystem provider selected but STORAGE_FILESYSTEM_PATH not set
+ *   - supabase provider selected but SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY not set
+ *   - cloudflare-r2 provider selected in non-serverless environment
+ *   - cloudflare-kv provider selected in non-serverless environment
+ *   - unknown provider type specified
+ *
+ * @example
+ * ```typescript
+ * // Standard usage — DI container resolves clients and passes via deps
+ * const provider = createStorageProvider(config, {
+ *   supabaseClient: resolvedSupabaseClient,
+ * });
+ *
+ * // Worker usage with Cloudflare bindings
+ * const provider = createStorageProvider(config, {
+ *   r2Bucket: env.R2_BUCKET,
+ *   kvNamespace: env.KV_NAMESPACE,
+ * });
+ * ```
+ */
+export declare function createStorageProvider(config: AppConfig, deps?: StorageFactoryDeps): IStorageProvider;
+//# sourceMappingURL=storageFactory.d.ts.map

package/dist/storage/core/storageFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageFactory.d.ts","sourceRoot":"","sources":["../../../src/storage/core/storageFactory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAM3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAW/E;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,sCAAsC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;CACpD;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE,kBAAuB,GAC5B,gBAAgB,CAgGlB"}

package/dist/storage/core/storageFactory.js

@@ -0,0 +1,122 @@
+import { D1Provider } from '../../storage/providers/cloudflare/d1Provider.js';
+import { KvProvider } from '../../storage/providers/cloudflare/kvProvider.js';
+import { R2Provider } from '../../storage/providers/cloudflare/r2Provider.js';
+import { FileSystemProvider } from '../../storage/providers/fileSystem/fileSystemProvider.js';
+import { InMemoryProvider } from '../../storage/providers/inMemory/inMemoryProvider.js';
+import { SupabaseProvider } from '../../storage/providers/supabase/supabaseProvider.js';
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+import { requestContextService } from '../../utils/internal/requestContext.js';
+/** Evaluated at call time (not module load) so worker.ts can set IS_SERVERLESS before first use. */
+function isServerless() {
+    return typeof process === 'undefined' || process.env.IS_SERVERLESS === 'true';
+}
+/**
+ * Retrieves a Cloudflare binding from globalThis by key.
+ * Throws a ConfigurationError if the binding is not present.
+ */
+function getGlobalBinding(key, context) {
+    const g = globalThis;
+    if (!(key in g) || g[key] == null) {
+        throw new McpError(JsonRpcErrorCode.ConfigurationError, `${key} binding not available in globalThis. Ensure wrangler.toml is configured correctly.`, context);
+    }
+    return g[key];
+}
+/**
+ * Creates and returns a storage provider instance based on the provided configuration.
+ *
+ * This factory decouples the application from concrete storage implementations,
+ * allowing the backend to be selected via environment configuration. In serverless
+ * environments, automatically falls back to in-memory storage for non-compatible providers.
+ *
+ * Provider Selection Logic:
+ * - Serverless environment: Only `in-memory`, `cloudflare-r2`, `cloudflare-kv` allowed
+ * - Node environment: All providers available
+ * - Missing config: Throws ConfigurationError
+ *
+ * @param config - The application configuration object, typically resolved from DI container.
+ * @param deps - Optional pre-resolved dependencies for providers (useful for testing/Workers).
+ * @returns An instance of a class that implements the IStorageProvider interface.
+ *
+ * @throws {McpError} JsonRpcErrorCode.ConfigurationError - If:
+ *   - filesystem provider selected but STORAGE_FILESYSTEM_PATH not set
+ *   - supabase provider selected but SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY not set
+ *   - cloudflare-r2 provider selected in non-serverless environment
+ *   - cloudflare-kv provider selected in non-serverless environment
+ *   - unknown provider type specified
+ *
+ * @example
+ * ```typescript
+ * // Standard usage — DI container resolves clients and passes via deps
+ * const provider = createStorageProvider(config, {
+ *   supabaseClient: resolvedSupabaseClient,
+ * });
+ *
+ * // Worker usage with Cloudflare bindings
+ * const provider = createStorageProvider(config, {
+ *   r2Bucket: env.R2_BUCKET,
+ *   kvNamespace: env.KV_NAMESPACE,
+ * });
+ * ```
+ */
+export function createStorageProvider(config, deps = {}) {
+    const context = requestContextService.createRequestContext({
+        operation: 'createStorageProvider',
+    });
+    const providerType = config.storage.providerType;
+    if (isServerless() &&
+        !['in-memory', 'cloudflare-r2', 'cloudflare-kv', 'cloudflare-d1'].includes(providerType)) {
+        logger.warning(`Forcing 'in-memory' storage provider in serverless environment (configured: ${providerType}).`, context);
+        return new InMemoryProvider();
+    }
+    logger.info(`Creating storage provider of type: ${providerType}`, context);
+    switch (providerType) {
+        case 'in-memory':
+            return new InMemoryProvider();
+        case 'filesystem':
+            if (!config.storage.filesystemPath) {
+                throw new McpError(JsonRpcErrorCode.ConfigurationError, 'STORAGE_FILESYSTEM_PATH must be set for the filesystem storage provider.', context);
+            }
+            return new FileSystemProvider(config.storage.filesystemPath);
+        case 'supabase':
+            if (!config.supabase?.url || !config.supabase?.serviceRoleKey) {
+                throw new McpError(JsonRpcErrorCode.ConfigurationError, 'SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY must be set for the supabase storage provider.', context);
+            }
+            if (!deps.supabaseClient) {
+                throw new McpError(JsonRpcErrorCode.ConfigurationError, 'Supabase client must be provided via deps for the supabase storage provider.', context);
+            }
+            return new SupabaseProvider(deps.supabaseClient);
+        case 'cloudflare-r2':
+            if (isServerless()) {
+                if (deps.r2Bucket) {
+                    return new R2Provider(deps.r2Bucket);
+                }
+                const r2Binding = getGlobalBinding('R2_BUCKET', context);
+                return new R2Provider(r2Binding);
+            }
+            throw new McpError(JsonRpcErrorCode.ConfigurationError, 'Cloudflare R2 storage is only available in a Cloudflare Worker environment.', context);
+        case 'cloudflare-kv':
+            if (isServerless()) {
+                if (deps.kvNamespace) {
+                    return new KvProvider(deps.kvNamespace);
+                }
+                const kvBinding = getGlobalBinding('KV_NAMESPACE', context);
+                return new KvProvider(kvBinding);
+            }
+            throw new McpError(JsonRpcErrorCode.ConfigurationError, 'Cloudflare KV storage is only available in a Cloudflare Worker environment.', context);
+        case 'cloudflare-d1':
+            if (isServerless()) {
+                if (deps.d1Database) {
+                    return new D1Provider(deps.d1Database);
+                }
+                const d1Binding = getGlobalBinding('DB', context);
+                return new D1Provider(d1Binding);
+            }
+            throw new McpError(JsonRpcErrorCode.ConfigurationError, 'Cloudflare D1 storage is only available in a Cloudflare Worker environment.', context);
+        default: {
+            const exhaustiveCheck = providerType;
+            throw new McpError(JsonRpcErrorCode.ConfigurationError, `Unhandled storage provider type: ${String(exhaustiveCheck)}`, context);
+        }
+    }
+}
+//# sourceMappingURL=storageFactory.js.map

package/dist/storage/core/storageFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageFactory.js","sourceRoot":"","sources":["../../../src/storage/core/storageFactory.ts"],"names":[],"mappings":"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"}

package/dist/storage/core/storageValidation.d.ts

@@ -0,0 +1,77 @@
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+import type { ListOptions, StorageOptions } from './IStorageProvider.js';
+/**
+ * Validates a tenant ID for storage operations.
+ *
+ * Security constraints:
+ * - Must be non-empty string
+ * - Maximum length: 128 characters
+ * - Allowed characters: alphanumeric, hyphens, underscores, dots
+ * - Cannot contain slashes or path traversal sequences
+ * - Cannot start or end with special characters
+ *
+ * @param tenantId The tenant ID to validate.
+ * @param context The request context for error reporting.
+ * @throws {McpError} JsonRpcErrorCode.InvalidParams - If tenant ID is not a string, empty, too long, contains invalid characters, or has path traversal sequences.
+ */
+export declare function validateTenantId(tenantId: string, context: RequestContext): void;
+/**
+ * Validates a storage key.
+ * @param key The key to validate.
+ * @param context The request context for error reporting.
+ * @throws {McpError} JsonRpcErrorCode.ValidationError - If key is not a non-empty string, too long, contains invalid characters, or has path traversal sequences.
+ */
+export declare function validateKey(key: string, context: RequestContext): void;
+/**
+ * Validates a prefix for list operations.
+ *
+ * Security constraints:
+ * - Can be empty string (matches all keys within tenant)
+ * - Maximum length: 512 characters
+ * - No path traversal sequences allowed
+ * - Only valid path characters allowed
+ *
+ * @param prefix The prefix to validate (empty string is valid).
+ * @param context The request context for error reporting.
+ * @throws {McpError} JsonRpcErrorCode.ValidationError - If prefix is not a string, too long, contains invalid characters, or has path traversal sequences.
+ */
+export declare function validatePrefix(prefix: string, context: RequestContext): void;
+/**
+ * Validates storage options.
+ * @param options The storage options to validate.
+ * @param context The request context for error reporting.
+ * @throws {McpError} JsonRpcErrorCode.ValidationError - If TTL is not a number, negative, or not finite.
+ */
+export declare function validateStorageOptions(options: StorageOptions | undefined, context: RequestContext): void;
+/**
+ * Validates list operation options.
+ *
+ * Security constraints:
+ * - Limit must be positive integer between 1 and 10000
+ * - Cursor must be valid base64 string if provided
+ * - Prevents memory exhaustion via oversized page requests
+ *
+ * @param options The list options to validate.
+ * @param context The request context for error reporting.
+ * @throws {McpError} If the options are invalid.
+ */
+export declare function validateListOptions(options: ListOptions | undefined, context: RequestContext): void;
+/**
+ * Encodes pagination cursor data into an opaque string.
+ * Uses runtime-agnostic base64 encoding for Worker compatibility.
+ * @param lastKey The last key from the current page.
+ * @param tenantId The tenant ID for validation.
+ * @returns An opaque cursor string.
+ */
+export declare function encodeCursor(lastKey: string, tenantId: string): string;
+/**
+ * Decodes and validates an opaque cursor string.
+ * Uses runtime-agnostic base64 decoding for Worker compatibility.
+ * @param cursor The cursor string to decode.
+ * @param tenantId The expected tenant ID for validation.
+ * @param context The request context for error reporting.
+ * @returns The last key from the cursor.
+ * @throws {McpError} If the cursor is invalid or tampered with.
+ */
+export declare function decodeCursor(cursor: string, tenantId: string, context: RequestContext): string;
+//# sourceMappingURL=storageValidation.d.ts.map

package/dist/storage/core/storageValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageValidation.d.ts","sourceRoot":"","sources":["../../../src/storage/core/storageValidation.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAoCzE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAgDhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CA+BtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CA8C5E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,cAAc,GAAG,SAAS,EACnC,OAAO,EAAE,cAAc,GACtB,IAAI,CA4BN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,OAAO,EAAE,cAAc,GACtB,IAAI,CAuEN;AAcD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAmC9F"}