@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/lib/server/middleware/response-cache.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Response Caching Middleware for SvelteKit API Routes
+ *
+ * Provides high-performance response caching using Redis to cache JSON API responses.
+ * Integrates seamlessly with existing cache infrastructure and supports flexible
+ * cache key generation, TTL configuration, and conditional caching.
+ */
+import type { RequestEvent, RequestHandler } from '@sveltejs/kit';
+/** TTL presets in seconds (local copy; kit imports no cache package). */
+export declare const CacheTTL: {
+    readonly SHORT: number;
+    readonly MEDIUM: number;
+    readonly LONG: number;
+    readonly VERY_LONG: number;
+};
+/**
+ * Structural cache port the middleware needs. Structurally identical to the
+ * cache client's `store` capability, so a host wires
+ * `cache: (event) => getVibesCacheClient(event.locals.runtime).store`.
+ */
+export interface KitCachePort {
+    get<T>(key: string): Promise<T | null | undefined>;
+    set<T>(key: string, value: T, options: {
+        ttl: number;
+    }): Promise<void | boolean | number>;
+    del(key: string): Promise<void | boolean | number>;
+}
+/**
+ * Configuration options for response caching
+ */
+export interface ResponseCacheOptions {
+    /**
+     * Resolve the cache port for this request (typically from
+     * `event.locals.runtime`). Returning `undefined` skips caching for the
+     * request; omit the option to disable caching. Errors thrown while
+     * resolving propagate.
+     */
+    cache?: (event: RequestEvent) => KitCachePort | undefined;
+    /** TTL in seconds (default: CacheTTL.MEDIUM = 1 hour) */
+    ttl?: number;
+    /** Custom function to generate cache key from request event */
+    keyGenerator?: (event: RequestEvent) => string;
+    /** Query parameters to include in cache key */
+    varyBy?: string[];
+    /** Headers to include in cache key */
+    varyByHeaders?: string[];
+    /** Function to determine if request should be cached */
+    condition?: (event: RequestEvent) => boolean;
+    /** Whether to cache responses for unauthenticated users */
+    cacheUnauthenticated?: boolean;
+    /** Whether to include user ID in cache key for user-specific caching */
+    userSpecific?: boolean;
+    /** Custom cache prefix */
+    prefix?: string;
+    /** Whether to add cache-related headers to response */
+    addCacheHeaders?: boolean;
+    /** HTTP cache scope to emit when addCacheHeaders is enabled. Defaults to private. */
+    cacheScope?: 'private' | 'public';
+    /** Minimum response status to cache (default: 200) */
+    minStatus?: number;
+    /** Maximum response status to cache (default: 299) */
+    maxStatus?: number;
+}
+/**
+ * Response caching middleware decorator
+ *
+ * Wraps SvelteKit request handlers to provide automatic response caching.
+ * Supports flexible configuration and integrates with existing Redis cache.
+ *
+ * @param options - Cache configuration options
+ * @returns Decorated request handler with caching capability
+ *
+ * @example
+ * ```typescript
+ * export const GET: RequestHandler = withResponseCache({
+ *   ttl: CacheTTL.LONG,
+ *   varyBy: ['search', 'page'],
+ *   userSpecific: true
+ * })(async ({ url, locals }) => {
+ *   const data = await fetchExpensiveData(url.searchParams);
+ *   return json(data);
+ * });
+ * ```
+ */
+export declare function withResponseCache(options?: ResponseCacheOptions): <T extends RequestHandler>(handler: T) => T;
+/**
+ * Conditional caching utilities
+ */
+export declare const CacheConditions: {
+    /**
+     * Only cache for authenticated users
+     */
+    authenticated: (event: RequestEvent) => boolean;
+    /**
+     * Only cache when specific query parameter is present
+     */
+    hasQueryParam: (param: string) => (event: RequestEvent) => boolean;
+    /**
+     * Only cache during specific hours (useful for reducing cache during peak times)
+     */
+    duringHours: (startHour: number, endHour: number) => (_event: RequestEvent) => boolean;
+    /**
+     * Cache only if request rate is below threshold (prevent cache pollution)
+     */
+    lowTraffic: (_maxRequestsPerMinute: number) => (_event: RequestEvent) => boolean;
+};
+/**
+ * Cache key generators for common patterns
+ */
+export declare const CacheKeyGenerators: {
+    /**
+     * Generate key based on URL path and user ID
+     */
+    userSpecific: (event: RequestEvent) => string;
+    /**
+     * Generate key including all query parameters
+     */
+    withAllParams: (event: RequestEvent) => string;
+    /**
+     * Generate key for paginated results
+     */
+    paginated: (event: RequestEvent) => string;
+    /**
+     * Generate key for search results
+     */
+    searchResults: (event: RequestEvent) => string;
+    /**
+     * Generate global key (same for all users)
+     */
+    global: (event: RequestEvent) => string;
+};
+/**
+ * Pre-configured cache decorators for common use cases, bound to the host's cache port
+ */
+export declare function createCachePresets(cache: NonNullable<ResponseCacheOptions['cache']>): {
+    /**
+     * Long-term caching for static data (AI models, providers, etc.)
+     */
+    staticData: <T extends RequestHandler>(handler: T) => T;
+    /**
+     * Medium-term caching for user-specific data
+     */
+    userData: <T extends RequestHandler>(handler: T) => T;
+    /**
+     * Short-term caching for search results
+     */
+    searchResults: <T extends RequestHandler>(handler: T) => T;
+    /**
+     * Paginated data caching
+     */
+    paginated: <T extends RequestHandler>(handler: T) => T;
+    /**
+     * Health check caching
+     */
+    healthCheck: <T extends RequestHandler>(handler: T) => T;
+};

package/dist/lib/server/middleware/response-cache.js

@@ -0,0 +1,364 @@
+/**
+ * Response Caching Middleware for SvelteKit API Routes
+ *
+ * Provides high-performance response caching using Redis to cache JSON API responses.
+ * Integrates seamlessly with existing cache infrastructure and supports flexible
+ * cache key generation, TTL configuration, and conditional caching.
+ */
+import * as z from 'zod/v4';
+import { kitLogger } from '../../kit-logger';
+import { settle } from '../../attempt.js';
+const logger = kitLogger('vibeskit-response-cache');
+/** TTL presets in seconds (local copy; kit imports no cache package). */
+export const CacheTTL = {
+    SHORT: 5 * 60,
+    MEDIUM: 60 * 60,
+    LONG: 6 * 60 * 60,
+    VERY_LONG: 24 * 60 * 60
+};
+/**
+ * Response cache metadata. Entries come back from an external store, so they
+ * are parsed before use: an entry that does not fit (a status `Response`
+ * would refuse, a non-numeric ttl, foreign data under our key) is not served.
+ */
+const CachedResponseSchema = z.object({
+    body: z.unknown().optional(),
+    status: z.number().int().min(200).max(599),
+    headers: z.record(z.string(), z.string()),
+    timestamp: z.number().finite(),
+    ttl: z.number().finite()
+});
+/**
+ * Header values can be credentials (an Authorization bearer), so a key and the
+ * log lines that carry it hold only a digest of them.
+ */
+async function digestHeaderValue(value) {
+    const bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
+    return Array.from(new Uint8Array(bytes).slice(0, 16), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Response caching middleware decorator
+ *
+ * Wraps SvelteKit request handlers to provide automatic response caching.
+ * Supports flexible configuration and integrates with existing Redis cache.
+ *
+ * @param options - Cache configuration options
+ * @returns Decorated request handler with caching capability
+ *
+ * @example
+ * ```typescript
+ * export const GET: RequestHandler = withResponseCache({
+ *   ttl: CacheTTL.LONG,
+ *   varyBy: ['search', 'page'],
+ *   userSpecific: true
+ * })(async ({ url, locals }) => {
+ *   const data = await fetchExpensiveData(url.searchParams);
+ *   return json(data);
+ * });
+ * ```
+ */
+export function withResponseCache(options = {}) {
+    const { ttl = CacheTTL.MEDIUM, cache, keyGenerator, varyBy = [], varyByHeaders = [], condition, cacheUnauthenticated = false, userSpecific = true, prefix = 'response', addCacheHeaders = true, cacheScope = 'private', minStatus = 200, maxStatus = 299 } = options;
+    return function cacheDecorator(handler) {
+        // SAFETY: the decorated function is called with the same RequestEvent and
+        // resolves to what `handler` returns (a cached response is rebuilt as a
+        // `Response`, the type a RequestHandler resolves to), so it has `T`'s call
+        // signature; TypeScript cannot express that for a generic `T`.
+        return (async (event) => {
+            // Only cache GET requests
+            if (event.request.method !== 'GET') {
+                return handler(event);
+            }
+            // Check authentication requirement
+            if (!cacheUnauthenticated && !event.locals.user) {
+                return handler(event);
+            }
+            // Check custom condition
+            if (condition && !condition(event)) {
+                return handler(event);
+            }
+            // Generate cache key
+            const cacheKey = keyGenerator
+                ? keyGenerator(event)
+                : await generateCacheKey(event, {
+                    prefix,
+                    varyBy,
+                    varyByHeaders,
+                    userSpecific: userSpecific && !!event.locals.user,
+                    userId: event.locals.user?.id
+                });
+            const cacheClient = cache?.(event);
+            if (cacheClient) {
+                const served = await settle(async () => {
+                    // Try to get response from cache
+                    const stored = await cacheClient.get(cacheKey);
+                    const parsed = CachedResponseSchema.safeParse(stored);
+                    if (stored && !parsed.success) {
+                        // Not an entry this middleware wrote: never serve it; drop it so the
+                        // handler's response can take its place.
+                        logger.warn(`Response cache entry is not a cached response: ${cacheKey}`);
+                        await cacheClient.del(cacheKey);
+                    }
+                    if (parsed.success) {
+                        const cached = parsed.data;
+                        // Verify cache hasn't expired (additional check)
+                        const age = Date.now() - cached.timestamp;
+                        if (age < cached.ttl * 1000) {
+                            logger.debug(`Response cache hit: ${cacheKey}`);
+                            const headers = new Headers({
+                                'Content-Type': 'application/json',
+                                ...cached.headers
+                            });
+                            if (addCacheHeaders) {
+                                headers.set('X-Cache', 'HIT');
+                                headers.set('X-Cache-Age', Math.floor(age / 1000).toString());
+                                headers.set('Cache-Control', `${cacheScope}, max-age=${Math.floor((cached.ttl * 1000 - age) / 1000)}`);
+                            }
+                            return new Response(JSON.stringify(cached.body), {
+                                status: cached.status,
+                                headers
+                            });
+                        }
+                        else {
+                            // Cache expired, remove it
+                            await cacheClient.del(cacheKey);
+                        }
+                    }
+                    return null;
+                });
+                if (!served.ok) {
+                    logger.error(`Response cache error for key "${cacheKey}":`, served.error);
+                }
+                else if (served.value) {
+                    return served.value;
+                }
+            }
+            // Execute original handler exactly once.
+            const response = await handler(event);
+            // Only cache successful responses
+            if (cacheClient && response.status >= minStatus && response.status <= maxStatus) {
+                return cacheSuccessfulResponse(cacheClient, response, cacheKey, ttl, addCacheHeaders, cacheScope);
+            }
+            return response;
+        });
+    };
+}
+/**
+ * Generate cache key from request event
+ */
+async function generateCacheKey(event, options) {
+    const parts = [options.prefix, event.url.pathname];
+    // Add user ID for user-specific caching
+    if (options.userSpecific && options.userId) {
+        parts.push(`user:${options.userId}`);
+    }
+    // Add query parameters
+    if (options.varyBy.length > 0) {
+        const params = new URLSearchParams();
+        options.varyBy.forEach((param) => {
+            const value = event.url.searchParams.get(param);
+            if (value !== null) {
+                params.set(param, value);
+            }
+        });
+        if (params.toString()) {
+            parts.push(`query:${params.toString()}`);
+        }
+    }
+    // Add headers
+    if (options.varyByHeaders.length > 0) {
+        const headerValues = [];
+        for (const header of options.varyByHeaders) {
+            const value = event.request.headers.get(header);
+            if (value) {
+                // Only a digest of the value joins the key (and so the logs and the store).
+                headerValues.push(`${header}:${await digestHeaderValue(value)}`);
+            }
+        }
+        if (headerValues.length > 0) {
+            parts.push(`headers:${headerValues.join(';')}`);
+        }
+    }
+    return parts.join(':');
+}
+/**
+ * Cache a successful response
+ */
+async function cacheSuccessfulResponse(cacheClient, response, cacheKey, ttl, addCacheHeaders, cacheScope) {
+    const cached = await settle(async () => {
+        // Clone response to avoid consuming the stream
+        const responseClone = response.clone();
+        const body = await responseClone.json();
+        // Extract headers to cache
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            // Only cache safe headers
+            if (isSafeHeader(key)) {
+                headers[key] = value;
+            }
+        });
+        // Cache the response
+        const cachedResponse = {
+            body,
+            status: response.status,
+            headers,
+            timestamp: Date.now(),
+            ttl
+        };
+        await cacheClient.set(cacheKey, cachedResponse, { ttl });
+        logger.debug(`Cached response: ${cacheKey}`);
+        // Create new response with cache headers
+        const responseHeaders = new Headers(headers);
+        responseHeaders.set('Content-Type', 'application/json');
+        if (addCacheHeaders) {
+            responseHeaders.set('X-Cache', 'MISS');
+            responseHeaders.set('Cache-Control', `${cacheScope}, max-age=${ttl}`);
+        }
+        return new Response(JSON.stringify(body), {
+            status: response.status,
+            headers: responseHeaders
+        });
+    });
+    if (cached.ok)
+        return cached.value;
+    logger.error(`Failed to cache response for key "${cacheKey}":`, cached.error);
+    return response;
+}
+/**
+ * Check if header is safe to cache
+ */
+function isSafeHeader(name) {
+    const unsafeHeaders = [
+        'authorization',
+        'cookie',
+        'set-cookie',
+        'x-forwarded-for',
+        'x-real-ip',
+        'user-agent',
+        'referer',
+        'x-request-id'
+    ];
+    return !unsafeHeaders.includes(name.toLowerCase());
+}
+/**
+ * Conditional caching utilities
+ */
+export const CacheConditions = {
+    /**
+     * Only cache for authenticated users
+     */
+    authenticated: (event) => !!event.locals.user,
+    /**
+     * Only cache when specific query parameter is present
+     */
+    hasQueryParam: (param) => (event) => event.url.searchParams.has(param),
+    /**
+     * Only cache during specific hours (useful for reducing cache during peak times)
+     */
+    duringHours: (startHour, endHour) => (_event) => {
+        const hour = new Date().getHours();
+        return hour >= startHour && hour <= endHour;
+    },
+    /**
+     * Cache only if request rate is below threshold (prevent cache pollution)
+     */
+    lowTraffic: (_maxRequestsPerMinute) => (_event) => {
+        // Request-rate tracking is not yet wired up; cache everything for now.
+        return true;
+    }
+};
+/**
+ * Cache key generators for common patterns
+ */
+export const CacheKeyGenerators = {
+    /**
+     * Generate key based on URL path and user ID
+     */
+    userSpecific: (event) => `response:${event.url.pathname}:user:${event.locals.user?.id || 'anonymous'}`,
+    /**
+     * Generate key including all query parameters
+     */
+    withAllParams: (event) => {
+        const search = event.url.search || '';
+        const userId = event.locals.user?.id || 'anonymous';
+        return `response:${event.url.pathname}${search}:user:${userId}`;
+    },
+    /**
+     * Generate key for paginated results
+     */
+    paginated: (event) => {
+        const page = event.url.searchParams.get('page') || '1';
+        const perPage = event.url.searchParams.get('perPage') || '20';
+        const userId = event.locals.user?.id || 'anonymous';
+        return `response:${event.url.pathname}:page:${page}:perPage:${perPage}:user:${userId}`;
+    },
+    /**
+     * Generate key for search results
+     */
+    searchResults: (event) => {
+        const query = event.url.searchParams.get('query') || '';
+        const filters = event.url.searchParams.get('filters') || '';
+        const userId = event.locals.user?.id || 'anonymous';
+        return `response:search:${event.url.pathname}:query:${encodeURIComponent(query)}:filters:${encodeURIComponent(filters)}:user:${userId}`;
+    },
+    /**
+     * Generate global key (same for all users)
+     */
+    global: (event) => `response:global:${event.url.pathname}${event.url.search || ''}`
+};
+/**
+ * Pre-configured cache decorators for common use cases, bound to the host's cache port
+ */
+export function createCachePresets(cache) {
+    return {
+        /**
+         * Long-term caching for static data (AI models, providers, etc.)
+         */
+        staticData: withResponseCache({
+            cache,
+            ttl: CacheTTL.VERY_LONG,
+            cacheUnauthenticated: true,
+            userSpecific: false,
+            keyGenerator: CacheKeyGenerators.global,
+            cacheScope: 'public'
+        }),
+        /**
+         * Medium-term caching for user-specific data
+         */
+        userData: withResponseCache({
+            cache,
+            ttl: CacheTTL.MEDIUM,
+            userSpecific: true,
+            condition: CacheConditions.authenticated
+        }),
+        /**
+         * Short-term caching for search results
+         */
+        searchResults: withResponseCache({
+            cache,
+            ttl: CacheTTL.SHORT,
+            keyGenerator: CacheKeyGenerators.searchResults,
+            condition: CacheConditions.authenticated
+        }),
+        /**
+         * Paginated data caching
+         */
+        paginated: withResponseCache({
+            cache,
+            ttl: CacheTTL.MEDIUM,
+            keyGenerator: CacheKeyGenerators.paginated,
+            condition: CacheConditions.authenticated
+        }),
+        /**
+         * Health check caching
+         */
+        healthCheck: withResponseCache({
+            cache,
+            ttl: CacheTTL.SHORT,
+            cacheUnauthenticated: true,
+            userSpecific: false,
+            keyGenerator: CacheKeyGenerators.global,
+            cacheScope: 'public'
+        })
+    };
+}

package/dist/lib/server/middleware/security.d.ts

@@ -0,0 +1,88 @@
+import type { RequestEvent } from '@sveltejs/kit';
+/**
+ * Content Security Policy configuration
+ */
+interface CSPConfig {
+    directives: Record<string, string[]>;
+    reportOnly?: boolean;
+    reportUri?: string;
+}
+/**
+ * Security headers middleware
+ * @param config - Configuration for security headers
+ * @returns Middleware function
+ */
+export declare function securityHeaders(config?: {
+    csp?: CSPConfig;
+    hsts?: boolean;
+    noSniff?: boolean;
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | string;
+    xssProtection?: boolean;
+}): (_event: RequestEvent) => Headers;
+/**
+ * CSRF protection middleware
+ * @param config - CSRF configuration
+ * @returns Middleware function
+ */
+export declare function csrfProtection(config?: {
+    cookieName?: string;
+    headerName?: string;
+    ignoreMethods?: string[];
+}): (event: RequestEvent) => void;
+/**
+ * Request size validation middleware
+ * @param maxSize - Maximum request size in bytes
+ * @returns Middleware function
+ */
+export declare function requestSizeLimit(maxSize?: number): (event: RequestEvent) => void;
+/**
+ * Content type validation middleware
+ * @param allowedTypes - Array of allowed content types
+ * @param skipMethods - HTTP methods to skip validation for (default: ['GET', 'HEAD', 'OPTIONS', 'DELETE'])
+ * @returns Middleware function
+ */
+export declare function contentTypeValidation(allowedTypes?: string[], skipMethods?: string[]): (event: RequestEvent) => void;
+/**
+ * Origin validation middleware for CORS protection
+ * @param allowedOrigins - Array of allowed origins or '*' for all
+ * @returns Middleware function
+ */
+export declare function originValidation(allowedOrigins?: string[] | '*'): (event: RequestEvent) => void;
+/**
+ * User agent validation middleware to block known bots/crawlers
+ * @param blockedPatterns - Array of regex patterns to block
+ * @returns Middleware function
+ */
+export declare function userAgentValidation(blockedPatterns?: RegExp[]): (event: RequestEvent) => void;
+/**
+ * Method validation middleware
+ * @param allowedMethods - Array of allowed HTTP methods
+ * @returns Middleware function
+ */
+export declare function methodValidation(allowedMethods?: string[]): (event: RequestEvent) => void;
+/**
+ * IP allowlist/blocklist middleware
+ * @param config - IP filtering configuration
+ * @returns Middleware function
+ */
+export declare function ipFiltering(config?: {
+    allowlist?: string[];
+    blocklist?: string[];
+    trustProxy?: boolean;
+}): (event: RequestEvent) => void;
+/**
+ * Compose multiple security middleware functions
+ * @param middlewares - Array of middleware functions
+ * @returns Combined middleware function
+ */
+export declare function composeSecurityMiddleware(...middlewares: Array<(event: RequestEvent) => void>): (event: RequestEvent) => void;
+/**
+ * Common security middleware configurations
+ */
+export declare const securityConfigs: {
+    api: (event: RequestEvent) => void;
+    upload: (event: RequestEvent) => void;
+    publicReadOnly: (event: RequestEvent) => void;
+    admin: (event: RequestEvent) => void;
+};
+export {};