@kuratchi/js 0.0.15 → 0.0.17

package/dist/runtime/router.js

@@ -5,47 +5,141 @@
  *   /todos          → static
  *   /blog/:slug     → named param
  *   /files/*rest    → catch-all
+ *
+ * Uses a radix tree for O(log n) dynamic route matching instead of O(n) linear scan.
  */
+function createNode(segment, type, paramName) {
+    return {
+        segment,
+        type,
+        paramName,
+        children: new Map(),
+    };
+}
 export class Router {
-    routes = [];
+    staticRoutes = new Map();
+    root = createNode('', 0 /* NodeType.Static */);
     /** Register a pattern (e.g. '/blog/:slug') and associate it with an index. */
     add(pattern, index) {
-        const paramNames = [];
-        // Convert pattern to regex
-        // :param  → named capture group
-        // *param  → catch-all capture group
-        let regexStr = pattern
-            // Catch-all: /files/*rest → /files/(?<rest>.+)
-            .replace(/\*(\w+)/g, (_match, name) => {
-            paramNames.push(name);
-            return `(?<${name}>.+)`;
-        })
-            // Named params: /blog/:slug → /blog/(?<slug>[^/]+)
-            .replace(/:(\w+)/g, (_match, name) => {
-            paramNames.push(name);
-            return `(?<${name}>[^/]+)`;
-        });
-        // Anchor
-        regexStr = `^${regexStr}$`;
-        this.routes.push({
-            regex: new RegExp(regexStr),
-            paramNames,
-            index,
-        });
+        if (!pattern.includes(':') && !pattern.includes('*')) {
+            this.staticRoutes.set(pattern, index);
+            return;
+        }
+        // Parse pattern into segments
+        const segments = pattern.split('/').filter(Boolean);
+        let node = this.root;
+        for (let i = 0; i < segments.length; i++) {
+            const seg = segments[i];
+            if (seg.startsWith('*')) {
+                // Catch-all: *param
+                const paramName = seg.slice(1);
+                if (!node.catchAllChild) {
+                    node.catchAllChild = createNode('', 2 /* NodeType.CatchAll */, paramName);
+                }
+                node = node.catchAllChild;
+                // Catch-all must be last segment
+                break;
+            }
+            else if (seg.startsWith(':')) {
+                // Param: :param
+                const paramName = seg.slice(1);
+                if (!node.paramChild) {
+                    node.paramChild = createNode('', 1 /* NodeType.Param */, paramName);
+                }
+                node = node.paramChild;
+            }
+            else {
+                // Static segment
+                const key = seg[0] || '';
+                let child = node.children.get(key);
+                if (!child) {
+                    child = createNode(seg, 0 /* NodeType.Static */);
+                    node.children.set(key, child);
+                }
+                else if (child.segment !== seg) {
+                    // Handle prefix splitting for true radix tree (simplified: exact match only)
+                    // For simplicity, we use segment-level matching which is sufficient for route patterns
+                    let found = false;
+                    for (const [, c] of node.children) {
+                        if (c.segment === seg) {
+                            child = c;
+                            found = true;
+                            break;
+                        }
+                    }
+                    if (!found) {
+                        child = createNode(seg, 0 /* NodeType.Static */);
+                        // Use full segment as key for collision handling
+                        node.children.set(seg, child);
+                    }
+                }
+                node = child;
+            }
+        }
+        node.routeIndex = index;
     }
     /** Match a pathname against registered routes. Returns null if no match. */
     match(pathname) {
         // Normalize: strip trailing slash (except root)
         const normalized = pathname === '/' ? '/' : pathname.replace(/\/$/, '');
-        for (const route of this.routes) {
-            const m = normalized.match(route.regex);
-            if (m) {
-                const params = {};
-                for (const name of route.paramNames) {
-                    params[name] = m.groups?.[name] ?? '';
-                }
-                return { params, index: route.index };
+        // Fast path: static routes (O(1))
+        const staticIdx = this.staticRoutes.get(normalized);
+        if (staticIdx !== undefined) {
+            return { params: {}, index: staticIdx };
+        }
+        // Radix tree traversal for dynamic routes
+        const segments = normalized.split('/').filter(Boolean);
+        const params = {};
+        const result = this.matchNode(this.root, segments, 0, params);
+        if (result !== null) {
+            return { params, index: result };
+        }
+        return null;
+    }
+    /** Recursive radix tree matching with backtracking */
+    matchNode(node, segments, segIdx, params) {
+        // Base case: consumed all segments
+        if (segIdx >= segments.length) {
+            return node.routeIndex ?? null;
+        }
+        const seg = segments[segIdx];
+        // 1. Try static children first (highest priority)
+        // Check by first char, then by full segment
+        const staticChild = node.children.get(seg[0]) ?? node.children.get(seg);
+        if (staticChild && staticChild.segment === seg) {
+            const result = this.matchNode(staticChild, segments, segIdx + 1, params);
+            if (result !== null)
+                return result;
+        }
+        // Also check full segment key for collision handling
+        for (const [key, child] of node.children) {
+            if (key !== seg[0] && child.segment === seg) {
+                const result = this.matchNode(child, segments, segIdx + 1, params);
+                if (result !== null)
+                    return result;
+            }
+        }
+        // 2. Try param child (second priority)
+        if (node.paramChild) {
+            const paramName = node.paramChild.paramName;
+            const oldValue = params[paramName];
+            params[paramName] = seg;
+            const result = this.matchNode(node.paramChild, segments, segIdx + 1, params);
+            if (result !== null)
+                return result;
+            // Backtrack
+            if (oldValue !== undefined) {
+                params[paramName] = oldValue;
             }
+            else {
+                delete params[paramName];
+            }
+        }
+        // 3. Try catch-all child (lowest priority, consumes rest)
+        if (node.catchAllChild) {
+            const paramName = node.catchAllChild.paramName;
+            params[paramName] = segments.slice(segIdx).join('/');
+            return node.catchAllChild.routeIndex ?? null;
         }
         return null;
     }

package/dist/runtime/security.d.ts

@@ -0,0 +1,101 @@
+/**
+ * KuratchiJS Security Module
+ *
+ * Provides CSRF protection, request signing, and security utilities
+ * for the framework runtime.
+ */
+/**
+ * Initialize CSRF protection for the current request.
+ * Generates a new token if one doesn't exist in cookies.
+ */
+export declare function initCsrf(request: Request, cookieName?: string): string;
+/**
+ * Get the current CSRF token for the request
+ */
+export declare function getCsrfToken(): string;
+/**
+ * Validate CSRF token from request against stored token.
+ * Checks both header and form field.
+ */
+export declare function validateCsrf(request: Request, formData?: FormData, headerName?: string, formField?: string): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Get the Set-Cookie header for CSRF token if needed
+ */
+export declare function getCsrfCookieHeader(): string | null;
+export interface RpcSecurityConfig {
+    requireAuth: boolean;
+    validateCsrf: boolean;
+    allowedMethods: ('GET' | 'POST')[];
+}
+/**
+ * Generate a per-request RPC nonce for additional request signing
+ */
+export declare function generateRpcNonce(): string;
+/**
+ * Validate an RPC request meets security requirements
+ */
+export declare function validateRpcRequest(request: Request, config: RpcSecurityConfig): {
+    valid: boolean;
+    status: number;
+    reason?: string;
+};
+export interface ActionSecurityConfig {
+    validateCsrf: boolean;
+    requireSameOrigin: boolean;
+}
+/**
+ * Validate an action request meets security requirements
+ */
+export declare function validateActionRequest(request: Request, url: URL, formData: FormData, config: ActionSecurityConfig): {
+    valid: boolean;
+    status: number;
+    reason?: string;
+};
+export interface SecurityHeadersConfig {
+    contentSecurityPolicy?: string | null;
+    strictTransportSecurity?: string | null;
+    permissionsPolicy?: string | null;
+}
+/**
+ * Apply security headers to a response
+ */
+export declare function applySecurityHeaders(response: Response, config?: SecurityHeadersConfig): Response;
+/**
+ * Sign a fragment ID with the route path and CSRF token to prevent tampering.
+ * Format: fragmentId:signature
+ */
+export declare function signFragmentId(fragmentId: string, routePath: string): string;
+/**
+ * Validate a signed fragment ID against the current route and session.
+ * If no CSRF token is present (e.g., in tests), allows unsigned fragments.
+ */
+export declare function validateSignedFragment(signedFragment: string, routePath: string): {
+    valid: boolean;
+    fragmentId: string | null;
+    reason?: string;
+};
+/**
+ * Validate that a query function is allowed for the current route.
+ * The allowedQueries set should contain the function names registered for this route.
+ */
+export declare function validateQueryOverride(queryFn: string, allowedQueries: Set<string> | string[]): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Validate query arguments are safe JSON.
+ * Returns parsed arguments or null if invalid.
+ */
+export declare function parseQueryArgs(argsRaw: string): {
+    valid: boolean;
+    args: unknown[];
+    reason?: string;
+};
+export declare const CSRF_DEFAULTS: {
+    readonly cookieName: "__kuratchi_csrf";
+    readonly headerName: "x-kuratchi-csrf";
+    readonly formField: "_csrf";
+};

package/dist/runtime/security.js

@@ -0,0 +1,298 @@
+/**
+ * KuratchiJS Security Module
+ *
+ * Provides CSRF protection, request signing, and security utilities
+ * for the framework runtime.
+ */
+import { __getLocals, __setLocal } from './context.js';
+// ── CSRF Token Management ──────────────────────────────────────────
+const CSRF_TOKEN_LENGTH = 32;
+const CSRF_COOKIE_NAME = '__kuratchi_csrf';
+const CSRF_HEADER_NAME = 'x-kuratchi-csrf';
+const CSRF_FORM_FIELD = '_csrf';
+/**
+ * Generate a cryptographically secure random token
+ */
+function generateToken(length = CSRF_TOKEN_LENGTH) {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Initialize CSRF protection for the current request.
+ * Generates a new token if one doesn't exist in cookies.
+ */
+export function initCsrf(request, cookieName = CSRF_COOKIE_NAME) {
+    const cookies = parseCookies(request.headers.get('cookie'));
+    let token = cookies[cookieName];
+    if (!token || token.length < CSRF_TOKEN_LENGTH) {
+        token = generateToken();
+        // Mark that we need to set the cookie
+        __setLocal('__csrfTokenNew', true);
+    }
+    __setLocal('__csrfToken', token);
+    __setLocal('__csrfCookieName', cookieName);
+    return token;
+}
+/**
+ * Get the current CSRF token for the request
+ */
+export function getCsrfToken() {
+    const token = __getLocals().__csrfToken;
+    if (!token) {
+        throw new Error('[kuratchi] CSRF token not initialized. Ensure security middleware is active.');
+    }
+    return token;
+}
+/**
+ * Validate CSRF token from request against stored token.
+ * Checks both header and form field.
+ */
+export function validateCsrf(request, formData, headerName = CSRF_HEADER_NAME, formField = CSRF_FORM_FIELD) {
+    const storedToken = __getLocals().__csrfToken;
+    if (!storedToken) {
+        return { valid: false, reason: 'No CSRF token in session' };
+    }
+    // Check header first (for fetch requests)
+    const headerToken = request.headers.get(headerName);
+    if (headerToken) {
+        if (timingSafeEqual(headerToken, storedToken)) {
+            return { valid: true };
+        }
+        return { valid: false, reason: 'CSRF header token mismatch' };
+    }
+    // Check form field (for traditional form submissions)
+    if (formData) {
+        const formToken = formData.get(formField);
+        if (typeof formToken === 'string' && timingSafeEqual(formToken, storedToken)) {
+            return { valid: true };
+        }
+        return { valid: false, reason: 'CSRF form token mismatch or missing' };
+    }
+    return { valid: false, reason: 'No CSRF token provided in request' };
+}
+/**
+ * Timing-safe string comparison to prevent timing attacks
+ */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+/**
+ * Get the Set-Cookie header for CSRF token if needed
+ */
+export function getCsrfCookieHeader() {
+    const locals = __getLocals();
+    if (!locals.__csrfTokenNew) {
+        return null;
+    }
+    const token = locals.__csrfToken;
+    const cookieName = locals.__csrfCookieName || CSRF_COOKIE_NAME;
+    // SameSite=Lax allows the cookie to be sent on top-level navigations
+    // HttpOnly=false so client JS can read it for fetch requests
+    return `${cookieName}=${token}; Path=/; SameSite=Lax; Secure`;
+}
+// ── RPC Security ───────────────────────────────────────────────────
+const RPC_NONCE_LENGTH = 16;
+/**
+ * Generate a per-request RPC nonce for additional request signing
+ */
+export function generateRpcNonce() {
+    return generateToken(RPC_NONCE_LENGTH);
+}
+/**
+ * Validate an RPC request meets security requirements
+ */
+export function validateRpcRequest(request, config) {
+    const method = request.method;
+    // Check allowed methods
+    if (!config.allowedMethods.includes(method)) {
+        return {
+            valid: false,
+            status: 405,
+            reason: `RPC method ${method} not allowed. Use: ${config.allowedMethods.join(', ')}`,
+        };
+    }
+    // Check CSRF if enabled
+    if (config.validateCsrf) {
+        const csrfResult = validateCsrf(request);
+        if (!csrfResult.valid) {
+            return { valid: false, status: 403, reason: csrfResult.reason };
+        }
+    }
+    // Check authentication if required
+    if (config.requireAuth) {
+        const locals = __getLocals();
+        const user = locals.user || locals.session?.user;
+        if (!user) {
+            return { valid: false, status: 401, reason: 'Authentication required for RPC' };
+        }
+    }
+    return { valid: true, status: 200 };
+}
+/**
+ * Validate an action request meets security requirements
+ */
+export function validateActionRequest(request, url, formData, config) {
+    // Check same-origin
+    if (config.requireSameOrigin && !isSameOrigin(request, url)) {
+        return { valid: false, status: 403, reason: 'Cross-origin action requests forbidden' };
+    }
+    // Check CSRF if enabled
+    if (config.validateCsrf) {
+        const csrfResult = validateCsrf(request, formData);
+        if (!csrfResult.valid) {
+            return { valid: false, status: 403, reason: csrfResult.reason };
+        }
+    }
+    return { valid: true, status: 200 };
+}
+const DEFAULT_SEC_HEADERS = {
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'Referrer-Policy': 'strict-origin-when-cross-origin',
+};
+/**
+ * Apply security headers to a response
+ */
+export function applySecurityHeaders(response, config) {
+    for (const [key, value] of Object.entries(DEFAULT_SEC_HEADERS)) {
+        if (!response.headers.has(key)) {
+            response.headers.set(key, value);
+        }
+    }
+    if (config?.contentSecurityPolicy && !response.headers.has('Content-Security-Policy')) {
+        response.headers.set('Content-Security-Policy', config.contentSecurityPolicy);
+    }
+    if (config?.strictTransportSecurity && !response.headers.has('Strict-Transport-Security')) {
+        response.headers.set('Strict-Transport-Security', config.strictTransportSecurity);
+    }
+    if (config?.permissionsPolicy && !response.headers.has('Permissions-Policy')) {
+        response.headers.set('Permissions-Policy', config.permissionsPolicy);
+    }
+    return response;
+}
+// ── Utility Functions ──────────────────────────────────────────────
+function parseCookies(header) {
+    const map = {};
+    if (!header)
+        return map;
+    for (const pair of header.split(';')) {
+        const eq = pair.indexOf('=');
+        if (eq === -1)
+            continue;
+        map[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+    }
+    return map;
+}
+function isSameOrigin(request, url) {
+    const fetchSite = request.headers.get('sec-fetch-site');
+    if (fetchSite && fetchSite !== 'same-origin' && fetchSite !== 'same-site' && fetchSite !== 'none') {
+        return false;
+    }
+    const origin = request.headers.get('origin');
+    if (!origin)
+        return true;
+    try {
+        return new URL(origin).origin === url.origin;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Fragment Security ───────────────────────────────────────────────
+/**
+ * Sign a fragment ID with the route path and CSRF token to prevent tampering.
+ * Format: fragmentId:signature
+ */
+export function signFragmentId(fragmentId, routePath) {
+    const token = __getLocals().__csrfToken || '';
+    const payload = `${fragmentId}:${routePath}:${token}`;
+    const signature = simpleHash(payload);
+    return `${fragmentId}:${signature}`;
+}
+/**
+ * Validate a signed fragment ID against the current route and session.
+ * If no CSRF token is present (e.g., in tests), allows unsigned fragments.
+ */
+export function validateSignedFragment(signedFragment, routePath) {
+    const token = __getLocals().__csrfToken || '';
+    // If no CSRF token is set, allow unsigned fragments (backward compat / tests)
+    if (!token) {
+        const colonIdx = signedFragment.lastIndexOf(':');
+        // If it looks signed, extract the fragment ID; otherwise use as-is
+        const fragmentId = colonIdx !== -1 ? signedFragment.slice(0, colonIdx) : signedFragment;
+        return { valid: true, fragmentId };
+    }
+    const colonIdx = signedFragment.lastIndexOf(':');
+    if (colonIdx === -1) {
+        // Unsigned fragment with CSRF enabled - reject for security
+        return { valid: false, fragmentId: null, reason: 'Fragment ID not signed' };
+    }
+    const fragmentId = signedFragment.slice(0, colonIdx);
+    const providedSignature = signedFragment.slice(colonIdx + 1);
+    const payload = `${fragmentId}:${routePath}:${token}`;
+    const expectedSignature = simpleHash(payload);
+    if (!timingSafeEqual(providedSignature, expectedSignature)) {
+        return { valid: false, fragmentId: null, reason: 'Fragment signature invalid' };
+    }
+    return { valid: true, fragmentId };
+}
+/**
+ * Simple hash function for signing (not cryptographic, but sufficient for HMAC-like signing
+ * when combined with a secret token). Uses FNV-1a for speed.
+ */
+function simpleHash(str) {
+    let hash = 2166136261;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = (hash * 16777619) >>> 0;
+    }
+    return hash.toString(36);
+}
+// ── Query Override Security ────────────────────────────────────────
+/**
+ * Validate that a query function is allowed for the current route.
+ * The allowedQueries set should contain the function names registered for this route.
+ */
+export function validateQueryOverride(queryFn, allowedQueries) {
+    const allowed = allowedQueries instanceof Set ? allowedQueries : new Set(allowedQueries);
+    if (!queryFn) {
+        return { valid: false, reason: 'No query function specified' };
+    }
+    if (!allowed.has(queryFn)) {
+        return { valid: false, reason: `Query function '${queryFn}' not registered for this route` };
+    }
+    return { valid: true };
+}
+/**
+ * Validate query arguments are safe JSON.
+ * Returns parsed arguments or null if invalid.
+ */
+export function parseQueryArgs(argsRaw) {
+    if (!argsRaw || argsRaw === '[]') {
+        return { valid: true, args: [] };
+    }
+    try {
+        const parsed = JSON.parse(argsRaw);
+        if (!Array.isArray(parsed)) {
+            return { valid: false, args: [], reason: 'Query args must be an array' };
+        }
+        return { valid: true, args: parsed };
+    }
+    catch {
+        return { valid: false, args: [], reason: 'Invalid JSON in query args' };
+    }
+}
+// ── Exports for Framework Use ──────────────────────────────────────
+export const CSRF_DEFAULTS = {
+    cookieName: CSRF_COOKIE_NAME,
+    headerName: CSRF_HEADER_NAME,
+    formField: CSRF_FORM_FIELD,
+};

package/dist/runtime/types.d.ts

@@ -18,6 +18,12 @@ export interface RouteContext<E extends Env = Env> {
     /** Parsed URL */
     url: URL;
 }
+export interface PageRenderResult {
+    html: string;
+    head?: string;
+    fragments?: Record<string, string>;
+}
+export type PageRenderOutput = string | PageRenderResult;
 /** A compiled route module */
 export interface RouteModule {
     /** Pattern string (e.g., '/todos', '/blog/:slug') */
@@ -28,8 +34,8 @@ export interface RouteModule {
     actions?: Record<string, (formData: FormData, env: Env, ctx: RouteContext) => Promise<any>>;
     /** RPC functions â€" callable from client via fetch */
     rpc?: Record<string, (args: any[], env: Env, ctx: RouteContext) => Promise<any>>;
-    /** Render function â€" returns HTML string from data */
-    render: (data: Record<string, any>) => string;
+    /** Render function â€" returns route HTML and optional head content from data */
+    render: (data: Record<string, any>) => PageRenderOutput;
     /** Layout name (default: 'default') */
     layout?: string;
 }
@@ -224,6 +230,27 @@ export interface AuthConfig {
         binding?: string;
         [key: string]: any;
     } | Record<string, any>;
+    /** Security configuration â€" CSRF protection, RPC security */
+    security?: SecurityConfig;
+}
+/** Security configuration for kuratchi.config.ts */
+export interface SecurityConfig {
+    /** Enable CSRF protection for actions and RPC (default: true) */
+    csrfEnabled?: boolean;
+    /** CSRF cookie name (default: '__kuratchi_csrf') */
+    csrfCookieName?: string;
+    /** CSRF header name for fetch requests (default: 'x-kuratchi-csrf') */
+    csrfHeaderName?: string;
+    /** Require authentication for RPC calls (default: false) */
+    rpcRequireAuth?: boolean;
+    /** Require authentication for form actions (default: false) */
+    actionRequireAuth?: boolean;
+    /** Content Security Policy directive string */
+    contentSecurityPolicy?: string;
+    /** Strict-Transport-Security header value */
+    strictTransportSecurity?: string;
+    /** Permissions-Policy header value */
+    permissionsPolicy?: string;
 }
 /** Runtime pipeline context - shared across runtime step handlers */
 export interface RuntimeContext<E extends Env = Env> {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kuratchi/js",
-    "version": "0.0.15",
+    "version": "0.0.17",
     "description": "A thin, Cloudflare Workers-native web framework with Svelte-inspired syntax",
     "license": "MIT",
     "type": "module",
@@ -38,6 +38,10 @@
             "types": "./dist/runtime/do.d.ts",
             "import": "./dist/runtime/do.js"
         },
+        "./runtime/generated-worker.js": {
+            "types": "./dist/runtime/generated-worker.d.ts",
+            "import": "./dist/runtime/generated-worker.js"
+        },
         "./compiler": {
             "types": "./dist/compiler/index.d.ts",
             "import": "./dist/compiler/index.js"