raffel 0.1.2

package/dist/http/stream-auth.js

@@ -0,0 +1,404 @@
+/**
+ * Stream Authentication
+ *
+ * Provides authentication helpers for SSE/EventSource streams.
+ *
+ * EventSource API limitations:
+ * - Cannot set custom headers (only browser-native credentials via cookies)
+ * - Auth must be passed via cookies or query parameters
+ *
+ * Supported auth methods for streams:
+ * - Cookie session: Automatic with same-origin requests
+ * - Bearer token via query param: ?token=xxx or ?authorization=Bearer xxx
+ * - API key via query param: ?apiKey=xxx or ?api_key=xxx
+ * - Bearer token via header: For fetch + ReadableStream clients
+ *
+ * @example
+ * import { createStreamAuthFactory, streamBearerAuth, streamCookieSession } from 'raffel/http/stream-auth'
+ *
+ * // Create auth factory for HTTP adapter
+ * const authFactory = createStreamAuthFactory({
+ *   // Bearer token via query param (for EventSource)
+ *   bearer: {
+ *     queryParam: 'token',
+ *     verify: async (token) => {
+ *       const user = await verifyJWT(token)
+ *       return user ? { principal: user.id, claims: user } : null
+ *     }
+ *   },
+ *   // Or cookie session
+ *   cookie: {
+ *     secret: process.env.SESSION_SECRET!,
+ *     cookieName: 'session'
+ *   }
+ * })
+ *
+ * // Use with HTTP adapter
+ * const adapter = createHttpAdapter(router, {
+ *   port: 3000,
+ *   contextFactory: authFactory
+ * })
+ */
+import { getSignedCookie } from './cookie.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Cookie Context Adapter
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Adapt IncomingMessage to CookieContext for reading cookies
+ */
+function toReqCookieContext(req) {
+    return {
+        req: {
+            header: (name) => {
+                const value = req.headers[name.toLowerCase()];
+                return Array.isArray(value) ? value[0] : value;
+            },
+            raw: {
+                headers: {
+                    cookie: req.headers.cookie,
+                },
+            },
+        },
+        header: () => { }, // No-op for reading
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Auth Extractors
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract bearer token from request
+ */
+export async function extractBearerToken(req, url, options) {
+    const { queryParams = ['token', 'authorization', 'access_token'], headerName = 'authorization', headerPrefix = 'Bearer', verify, } = options;
+    let token = null;
+    // Try query params first (for EventSource compatibility)
+    for (const param of queryParams) {
+        const value = url.searchParams.get(param);
+        if (value) {
+            // Handle "Bearer xxx" format in query param
+            if (value.toLowerCase().startsWith('bearer ')) {
+                token = value.slice(7).trim();
+            }
+            else {
+                token = value;
+            }
+            break;
+        }
+    }
+    // Try header if no query param token
+    if (!token) {
+        const headerValue = req.headers[headerName.toLowerCase()];
+        const headerStr = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+        if (headerStr) {
+            const prefixLower = headerPrefix.toLowerCase();
+            if (headerStr.toLowerCase().startsWith(prefixLower + ' ')) {
+                token = headerStr.slice(headerPrefix.length + 1).trim();
+            }
+            else if (!headerPrefix) {
+                token = headerStr.trim();
+            }
+        }
+    }
+    if (!token) {
+        return null;
+    }
+    return verify(token);
+}
+/**
+ * Extract API key from request
+ */
+export async function extractApiKey(req, url, options) {
+    const { queryParams = ['apiKey', 'api_key', 'key'], headerName = 'x-api-key', verify, } = options;
+    let apiKey = null;
+    // Try query params first (for EventSource compatibility)
+    for (const param of queryParams) {
+        const value = url.searchParams.get(param);
+        if (value) {
+            apiKey = value;
+            break;
+        }
+    }
+    // Try header if no query param
+    if (!apiKey) {
+        const headerValue = req.headers[headerName.toLowerCase()];
+        apiKey = Array.isArray(headerValue) ? headerValue[0] : (headerValue || null);
+    }
+    if (!apiKey) {
+        return null;
+    }
+    return verify(apiKey);
+}
+/**
+ * Extract session from signed cookie
+ */
+export async function extractCookieSession(req, options) {
+    const { secret, cookieName = 'session', validate, } = options;
+    const cookieCtx = toReqCookieContext(req);
+    // Get signed cookie
+    const cookieValue = await getSignedCookie(cookieCtx, secret, cookieName);
+    if (!cookieValue) {
+        return null;
+    }
+    // Parse session data
+    let sessionData;
+    try {
+        sessionData = JSON.parse(cookieValue);
+    }
+    catch {
+        return null;
+    }
+    // Check expiration if present
+    if (typeof sessionData.expiresAt === 'number' && sessionData.expiresAt < Date.now()) {
+        return null;
+    }
+    // Custom validation
+    if (validate) {
+        const data = sessionData.data;
+        return validate(data || sessionData);
+    }
+    // Default: extract principal from userId or id
+    const data = sessionData.data;
+    const userId = data?.userId || data?.user_id || data?.id || sessionData.id;
+    return {
+        principal: typeof userId === 'string' ? userId : undefined,
+        claims: data || sessionData,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Path Params Parser
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Parse path parameters from URL path using pattern
+ *
+ * @param path - URL path (e.g., '/logs/service-123')
+ * @param pattern - Route pattern (e.g., '/logs/:serviceId')
+ * @returns Params object or null if no match
+ *
+ * @example
+ * parsePathParams('/logs/service-123', '/logs/:serviceId')
+ * // => { serviceId: 'service-123' }
+ */
+export function parsePathParams(path, pattern) {
+    // Normalize paths
+    const pathParts = path.split('/').filter(Boolean);
+    const patternParts = pattern.split('/').filter(Boolean);
+    // Length must match (unless pattern ends with wildcard)
+    const hasWildcard = patternParts[patternParts.length - 1] === '*';
+    if (!hasWildcard && pathParts.length !== patternParts.length) {
+        return null;
+    }
+    if (hasWildcard && pathParts.length < patternParts.length - 1) {
+        return null;
+    }
+    const params = {};
+    for (let i = 0; i < patternParts.length; i++) {
+        const patternPart = patternParts[i];
+        const pathPart = pathParts[i];
+        if (patternPart === '*') {
+            // Wildcard matches rest of path
+            params['*'] = pathParts.slice(i).join('/');
+            break;
+        }
+        if (patternPart.startsWith(':')) {
+            // Parameter
+            const paramName = patternPart.slice(1);
+            params[paramName] = pathPart;
+        }
+        else if (patternPart !== pathPart) {
+            // Literal mismatch
+            return null;
+        }
+    }
+    return params;
+}
+/**
+ * Parse query parameters from URL
+ *
+ * @param url - URL object
+ * @returns Query params object
+ */
+export function parseQueryParams(url) {
+    const query = {};
+    for (const [key, value] of url.searchParams) {
+        if (key in query) {
+            const existing = query[key];
+            if (Array.isArray(existing)) {
+                existing.push(value);
+            }
+            else {
+                query[key] = [existing, value];
+            }
+        }
+        else {
+            query[key] = value;
+        }
+    }
+    return query;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Stream Auth Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a context factory for stream authentication
+ *
+ * Returns a function that can be used as `contextFactory` in HttpAdapterOptions.
+ *
+ * @param options - Auth configuration options
+ * @returns Context factory function
+ *
+ * @example
+ * const authFactory = createStreamAuthFactory({
+ *   bearer: {
+ *     queryParam: 'token',
+ *     verify: async (token) => {
+ *       const user = await verifyJWT(token)
+ *       return user ? { principal: user.id, claims: user } : null
+ *     }
+ *   }
+ * })
+ *
+ * const adapter = createHttpAdapter(router, {
+ *   port: 3000,
+ *   contextFactory: authFactory
+ * })
+ */
+export function createStreamAuthFactory(options) {
+    const { bearer, apiKey, cookie, custom, order = ['bearer', 'apiKey', 'cookie', 'custom'], } = options;
+    return async (req) => {
+        const url = new URL(req.url || '/', `http://${req.headers.host}`);
+        let authResult = null;
+        // Try auth methods in order
+        for (const method of order) {
+            if (authResult)
+                break;
+            switch (method) {
+                case 'bearer':
+                    if (bearer) {
+                        authResult = await extractBearerToken(req, url, bearer);
+                    }
+                    break;
+                case 'apiKey':
+                    if (apiKey) {
+                        authResult = await extractApiKey(req, url, apiKey);
+                    }
+                    break;
+                case 'cookie':
+                    if (cookie) {
+                        authResult = await extractCookieSession(req, cookie);
+                    }
+                    break;
+                case 'custom':
+                    if (custom) {
+                        const customResult = await custom(req, url);
+                        if (customResult) {
+                            return { auth: customResult };
+                        }
+                    }
+                    break;
+            }
+        }
+        if (authResult) {
+            return {
+                auth: {
+                    authenticated: true,
+                    principal: authResult.principal,
+                    claims: authResult.claims,
+                },
+            };
+        }
+        return {
+            auth: {
+                authenticated: false,
+            },
+        };
+    };
+}
+/**
+ * Create bearer-only stream auth factory
+ *
+ * Convenience wrapper for bearer token auth.
+ *
+ * @param options - Bearer auth options
+ * @returns Context factory function
+ *
+ * @example
+ * const authFactory = streamBearerAuth({
+ *   verify: async (token) => {
+ *     const user = await verifyJWT(token)
+ *     return user ? { principal: user.id } : null
+ *   }
+ * })
+ */
+export function streamBearerAuth(options) {
+    return createStreamAuthFactory({ bearer: options });
+}
+/**
+ * Create API key-only stream auth factory
+ *
+ * Convenience wrapper for API key auth.
+ *
+ * @param options - API key auth options
+ * @returns Context factory function
+ *
+ * @example
+ * const authFactory = streamApiKeyAuth({
+ *   verify: async (key) => {
+ *     const apiKey = await db.findApiKey(key)
+ *     return apiKey ? { principal: apiKey.userId } : null
+ *   }
+ * })
+ */
+export function streamApiKeyAuth(options) {
+    return createStreamAuthFactory({ apiKey: options });
+}
+/**
+ * Create cookie session-only stream auth factory
+ *
+ * Convenience wrapper for cookie session auth.
+ *
+ * @param options - Cookie session auth options
+ * @returns Context factory function
+ *
+ * @example
+ * const authFactory = streamCookieSession({
+ *   secret: process.env.SESSION_SECRET!,
+ *   validate: (session) => {
+ *     return session.userId ? { principal: session.userId } : null
+ *   }
+ * })
+ */
+export function streamCookieSession(options) {
+    return createStreamAuthFactory({ cookie: options });
+}
+/**
+ * Match request against stream routes
+ *
+ * @param path - Request path
+ * @param routes - Stream route definitions
+ * @returns Matched route and params, or null
+ */
+export function matchStreamRoute(path, routes) {
+    for (const route of routes) {
+        const params = parsePathParams(path, route.pattern);
+        if (params) {
+            return { route, params };
+        }
+    }
+    return null;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────────────────────
+export default {
+    createStreamAuthFactory,
+    streamBearerAuth,
+    streamApiKeyAuth,
+    streamCookieSession,
+    extractBearerToken,
+    extractApiKey,
+    extractCookieSession,
+    parsePathParams,
+    parseQueryParams,
+    matchStreamRoute,
+};
+//# sourceMappingURL=stream-auth.js.map

package/dist/http/stream-auth.js.map

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

package/dist/http/templates.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Template Rendering System
+ *
+ * Provides pluggable template engine support with caching, layouts,
+ * and context helpers for server-side rendering.
+ *
+ * @example
+ * import { createTemplateEngine, renderMiddleware } from 'raffel/http/templates'
+ *
+ * // Create with built-in simple engine
+ * const templates = createTemplateEngine({
+ *   templatesDir: './views',
+ *   extension: '.html',
+ *   cache: true,
+ * })
+ *
+ * // Use with middleware
+ * app.use('*', renderMiddleware(templates))
+ *
+ * // Render in handler
+ * app.get('/', (c) => {
+ *   return c.render('home', { title: 'Welcome' })
+ * })
+ *
+ * // Or use custom engine (EJS, Pug, etc.)
+ * import ejs from 'ejs'
+ * const templates = createTemplateEngine({
+ *   templatesDir: './views',
+ *   engine: {
+ *     name: 'ejs',
+ *     render: (template, data) => ejs.render(template, data),
+ *     renderFile: (path, data) => ejs.renderFile(path, data),
+ *   },
+ * })
+ */
+import type { HttpMiddleware } from './app.js';
+/**
+ * Template data passed to render
+ */
+export type TemplateData = Record<string, unknown>;
+/**
+ * Template engine interface
+ */
+export interface TemplateEngineAdapter {
+    /** Engine name */
+    readonly name: string;
+    /**
+     * Render a template string with data
+     */
+    render(template: string, data: TemplateData): string | Promise<string>;
+    /**
+     * Render a template file (optional, falls back to reading file + render)
+     */
+    renderFile?(filePath: string, data: TemplateData): string | Promise<string>;
+    /**
+     * Compile a template for caching (optional)
+     */
+    compile?(template: string): CompiledTemplate;
+}
+/**
+ * Compiled template function
+ */
+export type CompiledTemplate = (data: TemplateData) => string | Promise<string>;
+/**
+ * Template engine configuration
+ */
+export interface TemplateEngineOptions {
+    /**
+     * Directory containing templates
+     * @default './views'
+     */
+    templatesDir?: string;
+    /**
+     * File extension for templates
+     * @default '.html'
+     */
+    extension?: string;
+    /**
+     * Custom template engine adapter
+     * @default Built-in simple engine
+     */
+    engine?: TemplateEngineAdapter;
+    /**
+     * Enable template caching (recommended for production)
+     * @default true in production, false in development
+     */
+    cache?: boolean;
+    /**
+     * Default layout template name
+     */
+    layout?: string;
+    /**
+     * Layout directory (defaults to templatesDir)
+     */
+    layoutsDir?: string;
+    /**
+     * Partials directory
+     */
+    partialsDir?: string;
+    /**
+     * Global data available in all templates
+     */
+    globals?: TemplateData;
+    /**
+     * Custom helpers/functions available in templates
+     */
+    helpers?: Record<string, (...args: unknown[]) => unknown>;
+}
+/**
+ * Template manager interface
+ */
+export interface TemplateManager {
+    /**
+     * Render a template by name
+     */
+    render(name: string, data?: TemplateData): Promise<string>;
+    /**
+     * Render a template string directly
+     */
+    renderString(template: string, data?: TemplateData): Promise<string>;
+    /**
+     * Render with a specific layout
+     */
+    renderWithLayout(name: string, data?: TemplateData, layout?: string): Promise<string>;
+    /**
+     * Clear template cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        hits: number;
+        misses: number;
+    };
+    /**
+     * Register a partial template
+     */
+    registerPartial(name: string, template: string): void;
+    /**
+     * Register a helper function
+     */
+    registerHelper(name: string, fn: (...args: unknown[]) => unknown): void;
+}
+/**
+ * Render middleware options
+ */
+export interface RenderMiddlewareOptions {
+    /**
+     * Key to store render function in context
+     * @default 'render'
+     */
+    contextKey?: string;
+    /**
+     * Content-Type header for rendered responses
+     * @default 'text/html; charset=utf-8'
+     */
+    contentType?: string;
+}
+/**
+ * Create a template engine manager
+ *
+ * @param options - Template engine configuration
+ * @returns Template manager instance
+ *
+ * @example
+ * const templates = createTemplateEngine({
+ *   templatesDir: './views',
+ *   cache: process.env.NODE_ENV === 'production',
+ *   layout: 'main',
+ *   globals: { appName: 'My App' },
+ * })
+ */
+export declare function createTemplateEngine(options?: TemplateEngineOptions): TemplateManager;
+/**
+ * Create render middleware that adds render function to context
+ *
+ * @param templates - Template manager instance
+ * @param options - Middleware options
+ * @returns Middleware function
+ *
+ * @example
+ * const templates = createTemplateEngine({ templatesDir: './views' })
+ * app.use('*', renderMiddleware(templates))
+ *
+ * app.get('/', async (c) => {
+ *   const render = c.get('render')
+ *   return render('home', { title: 'Welcome' })
+ * })
+ */
+export declare function renderMiddleware<E extends Record<string, unknown> = Record<string, unknown>>(templates: TemplateManager, options?: RenderMiddlewareOptions): HttpMiddleware<E>;
+/**
+ * Render a template directly and return Response
+ *
+ * @param templates - Template manager
+ * @param name - Template name
+ * @param data - Template data
+ * @param options - Render options
+ * @returns Response with rendered HTML
+ *
+ * @example
+ * app.get('/', (c) => {
+ *   return renderTemplate(templates, 'home', { title: 'Welcome' })
+ * })
+ */
+export declare function renderTemplate(templates: TemplateManager, name: string, data?: TemplateData, options?: {
+    layout?: string;
+    contentType?: string;
+}): Promise<Response>;
+/**
+ * Create an EJS adapter (requires ejs package)
+ *
+ * @example
+ * import ejs from 'ejs'
+ * const templates = createTemplateEngine({
+ *   engine: createEjsAdapter(ejs),
+ * })
+ */
+export declare function createEjsAdapter(ejs: {
+    render: (template: string, data: object) => string;
+    renderFile: (path: string, data: object) => Promise<string>;
+    compile: (template: string) => (data: object) => string;
+}): TemplateEngineAdapter;
+/**
+ * Create a Pug adapter (requires pug package)
+ *
+ * @example
+ * import pug from 'pug'
+ * const templates = createTemplateEngine({
+ *   engine: createPugAdapter(pug),
+ *   extension: '.pug',
+ * })
+ */
+export declare function createPugAdapter(pug: {
+    render: (template: string, data: object) => string;
+    renderFile: (path: string, data: object) => string;
+    compile: (template: string) => (data: object) => string;
+}): TemplateEngineAdapter;
+/**
+ * Create a Handlebars adapter (requires handlebars package)
+ *
+ * @example
+ * import Handlebars from 'handlebars'
+ * const templates = createTemplateEngine({
+ *   engine: createHandlebarsAdapter(Handlebars),
+ *   extension: '.hbs',
+ * })
+ */
+export declare function createHandlebarsAdapter(handlebars: {
+    compile: (template: string) => (data: object) => string;
+}): TemplateEngineAdapter;
+declare const _default: {
+    createTemplateEngine: typeof createTemplateEngine;
+    renderMiddleware: typeof renderMiddleware;
+    renderTemplate: typeof renderTemplate;
+    createEjsAdapter: typeof createEjsAdapter;
+    createPugAdapter: typeof createPugAdapter;
+    createHandlebarsAdapter: typeof createHandlebarsAdapter;
+};
+export default _default;
+//# sourceMappingURL=templates.d.ts.map

package/dist/http/templates.d.ts.map

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