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

package/dist/storage/core/storageValidation.js

@@ -0,0 +1,303 @@
+/**
+ * @fileoverview Input validation utilities for storage operations.
+ *
+ * This module provides centralized validation for all storage inputs to prevent:
+ * - Path traversal attacks (via tenant ID, key, and prefix validation)
+ * - Resource exhaustion (via length limits and pagination controls)
+ * - Injection attacks (via character allowlists)
+ * - Cross-tenant data access (via cursor validation with tenant binding)
+ *
+ * Security Model:
+ * - Defense in depth: validation at service layer AND provider layer
+ * - Fail closed: invalid input throws McpError, never coerced
+ * - Audit trail: all validation failures logged with context
+ * - Immutable: validation functions are pure (no side effects)
+ *
+ * All validation functions are synchronous and throw McpError on failure.
+ * Callers should NOT catch validation errors - let them bubble to handlers.
+ *
+ * @module src/storage/core/storageValidation
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { base64ToString, stringToBase64 } from '../../utils/internal/encoding.js';
+/**
+ * Maximum length for tenant IDs and keys to prevent abuse.
+ * These constants are security-critical and must not be modified at runtime.
+ *
+ * Rationale:
+ * - MAX_TENANT_ID_LENGTH (128): Accommodates UUIDs, org slugs, and email-based IDs
+ * - MAX_KEY_LENGTH (1024): Balances between deep hierarchies and URL limits
+ * - MAX_PREFIX_LENGTH (512): Half of key length, enough for namespace prefixes
+ * - MAX_LIST_LIMIT (10000): Prevents memory exhaustion while allowing bulk operations
+ */
+const MAX_TENANT_ID_LENGTH = 128;
+const MAX_KEY_LENGTH = 1024;
+const MAX_PREFIX_LENGTH = 512;
+/**
+ * Maximum page size to prevent memory exhaustion attacks.
+ */
+const MAX_LIST_LIMIT = 10000;
+/**
+ * Pattern for valid tenant IDs (alphanumeric, hyphens, underscores, dots).
+ * More restrictive than key pattern - no slashes allowed to prevent path traversal.
+ * Single character: must be alphanumeric.
+ * Multiple characters: must start and end with alphanumeric, middle can include ._-
+ * @readonly
+ */
+const VALID_TENANT_ID_PATTERN = /^[a-zA-Z0-9]$|^[a-zA-Z0-9][a-zA-Z0-9._-]*[a-zA-Z0-9]$/;
+/**
+ * Pattern for valid keys and prefixes (alphanumeric, hyphens, underscores, dots, slashes).
+ * @readonly
+ */
+const VALID_KEY_PATTERN = /^[a-zA-Z0-9_.\-/]+$/;
+/**
+ * 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 function validateTenantId(tenantId, context) {
+    if (typeof tenantId !== 'string') {
+        throw new McpError(JsonRpcErrorCode.InvalidParams, 'Tenant ID must be a string.', {
+            ...context,
+            tenantId,
+        });
+    }
+    const trimmedTenantId = tenantId.trim();
+    if (trimmedTenantId.length === 0) {
+        throw new McpError(JsonRpcErrorCode.InvalidParams, 'Tenant ID cannot be an empty string.', {
+            ...context,
+            tenantId,
+        });
+    }
+    if (trimmedTenantId.length > MAX_TENANT_ID_LENGTH) {
+        throw new McpError(JsonRpcErrorCode.InvalidParams, `Tenant ID exceeds maximum length of ${MAX_TENANT_ID_LENGTH} characters.`, { ...context, tenantIdLength: trimmedTenantId.length });
+    }
+    if (!VALID_TENANT_ID_PATTERN.test(trimmedTenantId)) {
+        throw new McpError(JsonRpcErrorCode.InvalidParams, 'Tenant ID contains invalid characters. Only alphanumeric characters, hyphens, underscores, and dots are allowed. Must start and end with alphanumeric characters.', { ...context, tenantId: trimmedTenantId });
+    }
+    if (trimmedTenantId.includes('..')) {
+        throw new McpError(JsonRpcErrorCode.InvalidParams, 'Tenant ID contains consecutive dots, which are not allowed.', { ...context, tenantId: trimmedTenantId });
+    }
+    if (trimmedTenantId.includes('../') || trimmedTenantId.includes('..\\')) {
+        throw new McpError(JsonRpcErrorCode.InvalidParams, 'Tenant ID contains path traversal sequences, which are not allowed.', { ...context, tenantId: trimmedTenantId });
+    }
+}
+/**
+ * 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 function validateKey(key, context) {
+    if (!key || typeof key !== 'string') {
+        throw new McpError(JsonRpcErrorCode.ValidationError, 'Key must be a non-empty string.', {
+            ...context,
+            key,
+        });
+    }
+    if (key.length > MAX_KEY_LENGTH) {
+        throw new McpError(JsonRpcErrorCode.ValidationError, `Key exceeds maximum length of ${MAX_KEY_LENGTH} characters.`, { ...context, key: `${key.substring(0, 50)}...` });
+    }
+    if (!VALID_KEY_PATTERN.test(key)) {
+        throw new McpError(JsonRpcErrorCode.ValidationError, 'Key contains invalid characters. Only alphanumeric, hyphens, underscores, dots, and slashes are allowed.', { ...context, key });
+    }
+    if (key.includes('..')) {
+        throw new McpError(JsonRpcErrorCode.ValidationError, 'Key must not contain ".." (path traversal attempt).', { ...context, key });
+    }
+}
+/**
+ * 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 function validatePrefix(prefix, context) {
+    if (typeof prefix !== 'string') {
+        throw new McpError(JsonRpcErrorCode.ValidationError, 'Prefix must be a string.', {
+            ...context,
+            operation: 'validatePrefix',
+            prefix,
+        });
+    }
+    // Empty prefix is valid (matches all keys)
+    if (prefix === '') {
+        return;
+    }
+    if (prefix.length > MAX_PREFIX_LENGTH) {
+        throw new McpError(JsonRpcErrorCode.ValidationError, `Prefix exceeds maximum length of ${MAX_PREFIX_LENGTH} characters.`, {
+            ...context,
+            operation: 'validatePrefix',
+            prefix: `${prefix.substring(0, 50)}...`,
+        });
+    }
+    // Only validate pattern if non-empty
+    if (!VALID_KEY_PATTERN.test(prefix)) {
+        throw new McpError(JsonRpcErrorCode.ValidationError, 'Prefix contains invalid characters. Only alphanumeric, hyphens, underscores, dots, and slashes are allowed.', {
+            ...context,
+            operation: 'validatePrefix',
+            prefix: prefix.length > 50 ? `${prefix.substring(0, 50)}...` : prefix,
+        });
+    }
+    if (prefix.includes('..')) {
+        throw new McpError(JsonRpcErrorCode.ValidationError, 'Prefix must not contain ".." (path traversal attempt).', { ...context, operation: 'validatePrefix', prefix });
+    }
+}
+/**
+ * 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 function validateStorageOptions(options, context) {
+    if (!options) {
+        return;
+    }
+    if (options.ttl !== undefined) {
+        if (typeof options.ttl !== 'number') {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'TTL must be a number (seconds).', {
+                ...context,
+                ttl: options.ttl,
+            });
+        }
+        if (options.ttl < 0) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'TTL must be a non-negative number. Use 0 for immediate expiration.', { ...context, ttl: options.ttl });
+        }
+        if (!Number.isFinite(options.ttl)) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'TTL must be a finite number.', {
+                ...context,
+                ttl: options.ttl,
+            });
+        }
+    }
+}
+/**
+ * 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 function validateListOptions(options, context) {
+    if (!options) {
+        return;
+    }
+    if (options.limit !== undefined) {
+        if (typeof options.limit !== 'number') {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'List limit must be a number.', {
+                ...context,
+                operation: 'validateListOptions',
+                limit: options.limit,
+            });
+        }
+        if (!Number.isInteger(options.limit)) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'List limit must be an integer.', {
+                ...context,
+                operation: 'validateListOptions',
+                limit: options.limit,
+            });
+        }
+        if (options.limit < 1) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'List limit must be at least 1.', {
+                ...context,
+                operation: 'validateListOptions',
+                limit: options.limit,
+            });
+        }
+        if (options.limit > MAX_LIST_LIMIT) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, `List limit exceeds maximum of ${MAX_LIST_LIMIT}.`, { ...context, operation: 'validateListOptions', limit: options.limit });
+        }
+        if (!Number.isFinite(options.limit)) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'List limit must be a finite number.', {
+                ...context,
+                operation: 'validateListOptions',
+                limit: options.limit,
+            });
+        }
+    }
+    if (options.cursor !== undefined) {
+        if (typeof options.cursor !== 'string') {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'Cursor must be a string.', {
+                ...context,
+                operation: 'validateListOptions',
+            });
+        }
+        if (options.cursor.trim() === '') {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'Cursor must not be an empty string.', {
+                ...context,
+                operation: 'validateListOptions',
+            });
+        }
+        // Basic base64 validation (more thorough check happens in decodeCursor)
+        if (!/^[A-Za-z0-9+/=]+$/.test(options.cursor)) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'Cursor contains invalid characters for base64.', { ...context, operation: 'validateListOptions' });
+        }
+    }
+}
+/**
+ * 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 function encodeCursor(lastKey, tenantId) {
+    const data = { k: lastKey, t: tenantId };
+    return stringToBase64(JSON.stringify(data));
+}
+/**
+ * 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 function decodeCursor(cursor, tenantId, context) {
+    try {
+        const decoded = base64ToString(cursor);
+        const data = JSON.parse(decoded);
+        if (!data || typeof data !== 'object' || !('k' in data) || !('t' in data)) {
+            throw new McpError(JsonRpcErrorCode.InvalidParams, 'Invalid cursor format.', {
+                ...context,
+                operation: 'decodeCursor',
+            });
+        }
+        if (data.t !== tenantId) {
+            throw new McpError(JsonRpcErrorCode.InvalidParams, 'Cursor tenant ID mismatch. Cursor may have been tampered with.', { ...context, operation: 'decodeCursor' });
+        }
+        return data.k;
+    }
+    catch (error) {
+        if (error instanceof McpError) {
+            throw error;
+        }
+        throw new McpError(JsonRpcErrorCode.InvalidParams, 'Failed to decode cursor. Cursor may be corrupted or invalid.', {
+            ...context,
+            operation: 'decodeCursor',
+            rawError: error instanceof Error ? error.stack : String(error),
+        });
+    }
+}
+//# sourceMappingURL=storageValidation.js.map

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

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

package/dist/storage/providers/cloudflare/d1Provider.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Implements the IStorageProvider interface for Cloudflare D1.
+ * Provides SQL-based key-value storage with multi-tenancy, TTL support, and batch operations.
+ * @module src/storage/providers/cloudflare/d1Provider
+ */
+import type { D1Database } from '@cloudflare/workers-types';
+import type { IStorageProvider, ListOptions, ListResult, StorageOptions } from '../../../storage/core/IStorageProvider.js';
+import type { RequestContext } from '../../../utils/internal/requestContext.js';
+/**
+ * Cloudflare D1 storage provider implementation.
+ *
+ * Features:
+ * - SQL-based key-value storage with multi-tenancy
+ * - TTL support via expires_at column (Unix timestamp in milliseconds)
+ * - Batch operations using D1's batch() API for transactional writes
+ * - Cursor-based pagination with tenant-bound security
+ * - Strong consistency (vs KV's eventual consistency)
+ *
+ * Schema Requirements:
+ * - Table: kv_store (tenant_id, key, value, expires_at)
+ * - See docs/cloudflare-d1-schema.sql for setup
+ *
+ * Performance Characteristics:
+ * - Reads: ~50-100ms (depends on query complexity)
+ * - Writes: ~50-200ms (single), ~100-500ms (batch)
+ * - List operations: Efficient with proper indexes
+ * - Batch operations: 20-100x faster than individual calls
+ */
+export declare class D1Provider implements IStorageProvider {
+    private readonly db;
+    private readonly tableName;
+    /**
+     * Creates a new D1Provider instance.
+     *
+     * @param db - The D1Database binding from Cloudflare Workers
+     * @param tableName - The name of the kv_store table (default: 'kv_store')
+     * @throws {McpError} If db is not provided or invalid
+     */
+    private static readonly SAFE_TABLE_NAME;
+    constructor(db: D1Database, tableName?: string);
+    /**
+     * Helper to get current timestamp in milliseconds.
+     */
+    private getNow;
+    /**
+     * Helper to check if a value has expired based on expires_at timestamp.
+     */
+    private isExpired;
+    /**
+     * Retrieves a value from the D1 database.
+     * Returns null if the key doesn't exist or has expired.
+     */
+    get<T>(tenantId: string, key: string, context: RequestContext): Promise<T | null>;
+    /**
+     * Stores a value in the D1 database.
+     * Uses UPSERT (INSERT OR REPLACE) to handle both new and existing keys.
+     */
+    set(tenantId: string, key: string, value: unknown, context: RequestContext, options?: StorageOptions): Promise<void>;
+    /**
+     * Deletes a key from the D1 database.
+     * Returns true if the key existed, false otherwise.
+     */
+    delete(tenantId: string, key: string, context: RequestContext): Promise<boolean>;
+    /**
+     * Lists keys matching a prefix with pagination support.
+     * Filters out expired keys based on TTL.
+     */
+    list(tenantId: string, prefix: string, context: RequestContext, options?: ListOptions): Promise<ListResult>;
+    /**
+     * Retrieves multiple values in a single operation.
+     * More efficient than multiple individual get() calls.
+     * Uses SQL IN clause for batch fetching.
+     */
+    getMany<T>(tenantId: string, keys: string[], context: RequestContext): Promise<Map<string, T>>;
+    /**
+     * Stores multiple key-value pairs in a single transaction.
+     * Uses D1's batch() API for atomic, transactional writes.
+     * Significantly faster than individual set() calls (20-100x).
+     */
+    setMany(tenantId: string, entries: Map<string, unknown>, context: RequestContext, options?: StorageOptions): Promise<void>;
+    /**
+     * Deletes multiple keys in a single transaction.
+     * Uses D1's batch() API for atomic deletion.
+     * Returns the count of successfully deleted keys.
+     */
+    deleteMany(tenantId: string, keys: string[], context: RequestContext): Promise<number>;
+    /**
+     * Clears all keys for a given tenant.
+     * WARNING: This is a destructive operation that cannot be undone.
+     * Useful for testing or tenant cleanup operations.
+     */
+    clear(tenantId: string, context: RequestContext): Promise<number>;
+}
+//# sourceMappingURL=d1Provider.d.ts.map

package/dist/storage/providers/cloudflare/d1Provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1Provider.d.ts","sourceRoot":"","sources":["../../../../src/storage/providers/cloudflare/d1Provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,cAAc,EACf,MAAM,oCAAoC,CAAC;AAK5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AASzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,UAAW,YAAW,gBAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAmC;gBAE9D,EAAE,EAAE,UAAU,EAAE,SAAS,SAAa;IAiBlD;;OAEG;IACH,OAAO,CAAC,MAAM;IAId;;OAEG;IACH,OAAO,CAAC,SAAS;IAKjB;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IA+CvF;;;OAGG;IACG,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IAiChB;;;OAGG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BtF;;;OAGG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,CAAC;IAoFtB;;;;OAIG;IACG,OAAO,CAAC,CAAC,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAsD1B;;;;OAIG;IACG,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IAwChB;;;;OAIG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAqC5F;;;;OAIG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;CAuBxE"}