@kuratchi/js 0.0.15 → 0.0.17

package/README.md

@@ -28,6 +28,8 @@ bun run dev
 
 Point wrangler at the entry and you're done. **No `src/index.ts` needed.**
 
+For the framework's internal compiler/runtime orchestration and tracked implementation roadmap, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
 ```jsonc
 // wrangler.jsonc
 {
@@ -764,9 +766,166 @@ Kuratchi also exposes a framework build-mode flag:
 - `dev` is compile-time framework state, not a generic process env var
 - `@kuratchi/js/environment` is intended for server route code, not client `$:` scripts
 
+## Security
+
+Kuratchi includes built-in security features that are enabled by default or configurable via `kuratchi.config.ts`.
+
+### Default Security Headers
+
+All responses include these headers automatically:
+
+- `X-Content-Type-Options: nosniff`
+- `X-Frame-Options: DENY`
+- `Referrer-Policy: strict-origin-when-cross-origin`
+
+### CSRF Protection
+
+CSRF protection is **enabled by default** for all form actions and RPC calls.
+
+**How it works:**
+1. A cryptographically random token is generated per session and stored in a cookie
+2. The compiler auto-injects a hidden `_csrf` field into forms with `action={fn}`
+3. The client bridge includes the CSRF token header in fetch action requests
+4. Server validates the token using timing-safe comparison
+
+No configuration required — it just works.
+
+```html
+<!-- CSRF token is auto-injected -->
+<form action={submitForm}>
+  <input type="text" name="email" />
+  <button type="submit">Submit</button>
+</form>
+```
+
+### Authentication Enforcement
+
+Optionally require authentication for all RPC calls or form actions:
+
+```ts
+// kuratchi.config.ts
+export default defineConfig({
+  security: {
+    rpcRequireAuth: true,      // Require auth for all RPC calls (default: false)
+    actionRequireAuth: true,   // Require auth for all form actions (default: false)
+  },
+});
+```
+
+When enabled, unauthenticated requests return `401 Authentication required`. The check looks for `locals.user` or `locals.session.user`, which is populated by `@kuratchi/auth`.
+
+For per-function control, use guards in individual functions instead:
+
+```ts
+import { requireAuth } from '@kuratchi/auth';
+
+export async function deleteItem(formData: FormData) {
+  await requireAuth(); // Throws 401 if not authenticated
+  // ... action logic
+}
+```
+
+### Configurable Security Headers
+
+Add CSP, HSTS, and Permissions-Policy headers:
+
+```ts
+// kuratchi.config.ts
+export default defineConfig({
+  security: {
+    contentSecurityPolicy: "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'",
+    strictTransportSecurity: "max-age=31536000; includeSubDomains",
+    permissionsPolicy: "camera=(), microphone=(), geolocation=()",
+  },
+});
+```
+
+### HTML Sanitization
+
+The `{@html}` directive automatically sanitizes output to prevent XSS:
+
+- Removes dangerous elements: `<script>`, `<iframe>`, `<object>`, `<embed>`, `<style>`, `<template>`, etc.
+- Strips all `on*` event handlers
+- Neutralizes `javascript:` and `vbscript:` URLs
+- Removes `data:` URLs from `src` attributes
+
+For user-generated HTML, we recommend using DOMPurify on the client side for maximum security.
+
+### Fragment Refresh Security
+
+Fragment IDs used for `data-poll` are automatically signed to prevent attackers from probing for data:
+
+- Fragment IDs are signed at render time with the session's CSRF token
+- Server validates signatures before returning fragment content
+- Invalid or unsigned fragments return 403 when CSRF is enabled
+
+This is automatic — no configuration required.
+
+### Query Override Protection
+
+Query function calls via `x-kuratchi-query-fn` headers are validated against a whitelist:
+
+- Only query functions registered for the current route can be called
+- Prevents attackers from invoking arbitrary RPC functions
+- Returns 403 for unauthorized query function calls
+
+This is automatic — no configuration required.
+
+### Client Bridge Security
+
+Client-side handler invocation is protected against injection attacks:
+
+- Route and handler IDs are validated against safe patterns
+- Prototype pollution attempts are blocked (`__proto__`, `constructor`, `prototype`)
+- Uses `hasOwnProperty` checks to prevent prototype chain traversal
+
+This is automatic — no configuration required.
+
+### Error Information Protection
+
+Error messages are sanitized to prevent information leakage in production:
+
+- Generic errors show full details in dev mode only
+- Production uses safe fallback messages ("Internal Server Error", "Action failed")
+- `ActionError` and `PageError` messages are always shown (developer-controlled)
+
+```ts
+// Safe to show - developer-controlled message
+throw new ActionError('Invalid email format');
+
+// In production: "Internal Server Error" (details hidden)
+// In dev mode: Full error message for debugging
+throw new Error('Database connection failed at line 42');
+```
+
+### Full Security Configuration
+
+```ts
+// kuratchi.config.ts
+export default defineConfig({
+  security: {
+    // CSRF Protection (enabled by default)
+    csrfEnabled: true,
+    csrfCookieName: '__kuratchi_csrf',
+    csrfHeaderName: 'x-kuratchi-csrf',
+
+    // Authentication Enforcement
+    rpcRequireAuth: false,      // Require auth for RPC calls
+    actionRequireAuth: false,   // Require auth for form actions
+
+    // Security Headers
+    contentSecurityPolicy: "default-src 'self'",
+    strictTransportSecurity: "max-age=31536000; includeSubDomains",
+    permissionsPolicy: "camera=(), microphone=()",
+  },
+});
+```
+
+For a comprehensive security analysis and roadmap, see [SECURITY.md](./SECURITY.md).
+
 ## `kuratchi.config.ts`
 
-Optional. Required only when using framework integrations (ORM, auth, UI).
+Optional. Required only when using framework integrations (ORM, auth, UI, security).
 
 **Durable Objects are auto-discovered** — no config needed unless you need `stubId` for auth integration.
 

package/dist/cli.js

@@ -6,25 +6,31 @@ import { compile } from './compiler/index.js';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import * as net from 'node:net';
+import { createRequire } from 'node:module';
 import { spawn } from 'node:child_process';
 const args = process.argv.slice(2);
 const command = args[0];
 const projectDir = process.cwd();
-switch (command) {
-    case 'build':
-        runBuild();
-        break;
-    case 'watch':
-        runWatch(false);
-        break;
-    case 'dev':
-        runWatch(true);
-        break;
-    case 'create':
-        runCreate();
-        break;
-    default:
-        console.log(`
+void main().catch((err) => {
+    console.error(`[kuratchi] ${err?.message ?? err}`);
+    process.exit(1);
+});
+async function main() {
+    switch (command) {
+        case 'build':
+            runBuild();
+            return;
+        case 'watch':
+            await runWatch(false);
+            return;
+        case 'dev':
+            await runWatch(true);
+            return;
+        case 'create':
+            await runCreate();
+            return;
+        default:
+            console.log(`
 KuratchiJS CLI
 
 Usage:
@@ -33,7 +39,8 @@ Usage:
   kuratchi dev            Compile, watch for changes, and start wrangler dev server
   kuratchi watch          Compile + watch only (no wrangler — for custom setups)
 `);
-        process.exit(1);
+            process.exit(1);
+    }
 }
 async function runCreate() {
     const { create } = await import('./create.js');
@@ -42,10 +49,10 @@ async function runCreate() {
     const positional = remaining.filter(a => !a.startsWith('-'));
     await create(positional[0], flags);
 }
-function runBuild(isDev = false) {
+async function runBuild(isDev = false) {
     console.log('[kuratchi] Compiling...');
     try {
-        const outFile = compile({ projectDir, isDev });
+        const outFile = await compile({ projectDir, isDev });
         console.log(`[kuratchi] Built → ${path.relative(projectDir, outFile)}`);
     }
     catch (err) {
@@ -53,8 +60,8 @@ function runBuild(isDev = false) {
         process.exit(1);
     }
 }
-function runWatch(withWrangler = false) {
-    runBuild(true);
+async function runWatch(withWrangler = false) {
+    await runBuild(true);
     const routesDir = path.join(projectDir, 'src', 'routes');
     const serverDir = path.join(projectDir, 'src', 'server');
     const watchDirs = [routesDir, serverDir].filter(d => fs.existsSync(d));
@@ -62,10 +69,10 @@ function runWatch(withWrangler = false) {
     const triggerRebuild = () => {
         if (rebuildTimeout)
             clearTimeout(rebuildTimeout);
-        rebuildTimeout = setTimeout(() => {
+        rebuildTimeout = setTimeout(async () => {
             console.log('[kuratchi] File changed, rebuilding...');
             try {
-                compile({ projectDir, isDev: true });
+                await compile({ projectDir, isDev: true });
                 console.log('[kuratchi] Rebuilt.');
             }
             catch (err) {
@@ -80,11 +87,10 @@ function runWatch(withWrangler = false) {
     // `kuratchi dev` also starts the wrangler dev server.
     // `kuratchi watch` is the compiler-only mode for custom setups.
     if (withWrangler) {
-        startWranglerDev().catch((err) => {
-            console.error(`[kuratchi] Failed to start wrangler dev: ${err?.message ?? err}`);
-            process.exit(1);
-        });
+        await startWranglerDev();
+        return;
     }
+    await new Promise(() => { });
 }
 function hasPortFlag(inputArgs) {
     for (let i = 0; i < inputArgs.length; i++) {
@@ -117,25 +123,13 @@ async function findOpenPort(start = 8787, end = 8899) {
 }
 async function startWranglerDev() {
     const passthroughArgs = args.slice(1);
-    const wranglerArgs = ['wrangler', 'dev', ...passthroughArgs];
+    const wranglerArgs = ['dev', ...passthroughArgs];
     if (!hasPortFlag(passthroughArgs)) {
         const port = await findOpenPort();
         wranglerArgs.push('--port', String(port));
         console.log(`[kuratchi] Starting wrangler dev on port ${port}`);
     }
-    // Use 'pipe' for stdin so wrangler doesn't detect stdin EOF and exit
-    // prematurely when launched via a script runner (e.g. `bun run dev`).
-    const isWin = process.platform === 'win32';
-    const wrangler = isWin
-        ? spawn('npx ' + wranglerArgs.join(' '), {
-            cwd: projectDir,
-            stdio: ['pipe', 'inherit', 'inherit'],
-            shell: true,
-        })
-        : spawn('npx', wranglerArgs, {
-            cwd: projectDir,
-            stdio: ['pipe', 'inherit', 'inherit'],
-        });
+    const wrangler = spawnWranglerProcess(wranglerArgs);
     const cleanup = () => {
         if (!wrangler.killed)
             wrangler.kill();
@@ -143,10 +137,49 @@ async function startWranglerDev() {
     process.on('exit', cleanup);
     process.on('SIGINT', () => { cleanup(); process.exit(0); });
     process.on('SIGTERM', () => { cleanup(); process.exit(0); });
-    wrangler.on('exit', (code) => {
-        if (code !== 0 && code !== null) {
-            console.error(`[kuratchi] wrangler exited with code ${code}`);
-        }
-        process.exit(code ?? 0);
+    await new Promise((resolve, reject) => {
+        wrangler.on('exit', (code) => {
+            if (code !== 0 && code !== null) {
+                reject(new Error(`wrangler exited with code ${code}`));
+                return;
+            }
+            resolve();
+        });
+        wrangler.on('error', (err) => {
+            reject(err);
+        });
+    }).catch((err) => {
+        console.error(`[kuratchi] Failed to start wrangler dev: ${err?.message ?? err}`);
+        process.exit(1);
+    });
+}
+function resolveWranglerBin() {
+    try {
+        const projectPackageJson = path.join(projectDir, 'package.json');
+        const projectRequire = createRequire(projectPackageJson);
+        return projectRequire.resolve('wrangler/bin/wrangler.js');
+    }
+    catch {
+        return null;
+    }
+}
+function getNodeExecutable() {
+    if (!process.versions.bun)
+        return process.execPath;
+    return 'node';
+}
+function spawnWranglerProcess(wranglerArgs) {
+    const localWranglerBin = resolveWranglerBin();
+    const stdio = ['pipe', 'inherit', 'inherit'];
+    if (localWranglerBin) {
+        return spawn(getNodeExecutable(), [localWranglerBin, ...wranglerArgs], {
+            cwd: projectDir,
+            stdio,
+        });
+    }
+    const fallbackCommand = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    return spawn(fallbackCommand, ['wrangler', ...wranglerArgs], {
+        cwd: projectDir,
+        stdio,
     });
 }

package/dist/compiler/api-route-pipeline.d.ts

@@ -0,0 +1,8 @@
+export declare function compileApiRoute(opts: {
+    pattern: string;
+    fullPath: string;
+    projectDir: string;
+    transformModule: (entryAbsPath: string) => string;
+    allocateModuleId: () => string;
+    pushImport: (statement: string) => void;
+}): string;

package/dist/compiler/api-route-pipeline.js

@@ -0,0 +1,23 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const ALL_API_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+export function compileApiRoute(opts) {
+    const outFileDir = path.join(opts.projectDir, '.kuratchi');
+    const absRoutePath = opts.transformModule(opts.fullPath);
+    let importPath = path.relative(outFileDir, absRoutePath).replace(/\\/g, '/');
+    if (!importPath.startsWith('.'))
+        importPath = './' + importPath;
+    const moduleId = opts.allocateModuleId();
+    opts.pushImport(`import * as ${moduleId} from '${importPath}';`);
+    const apiSource = fs.readFileSync(opts.fullPath, 'utf-8');
+    const exportedMethods = ALL_API_METHODS.filter((method) => {
+        const fnPattern = new RegExp(`export\\s+(async\\s+)?function\\s+${method}\\b`);
+        const reExportPattern = new RegExp(`export\\s*\\{[^}]*\\b\\w+\\s+as\\s+${method}\\b`);
+        const namedExportPattern = new RegExp(`export\\s*\\{[^}]*\\b${method}\\b`);
+        return fnPattern.test(apiSource) || reExportPattern.test(apiSource) || namedExportPattern.test(apiSource);
+    });
+    const methodEntries = exportedMethods
+        .map((method) => `${method}: ${moduleId}.${method}`)
+        .join(', ');
+    return `{ pattern: '${opts.pattern}', __api: true, ${methodEntries} }`;
+}

package/dist/compiler/asset-pipeline.d.ts

@@ -0,0 +1,7 @@
+export interface CompiledAsset {
+    name: string;
+    content: string;
+    mime: string;
+    etag: string;
+}
+export declare function compileAssets(assetsDir: string): CompiledAsset[];

package/dist/compiler/asset-pipeline.js

@@ -0,0 +1,33 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const MIME_TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain; charset=utf-8',
+};
+export function compileAssets(assetsDir) {
+    const compiledAssets = [];
+    if (!fs.existsSync(assetsDir))
+        return compiledAssets;
+    const scanAssets = (dir, prefix) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.isDirectory()) {
+                scanAssets(path.join(dir, entry.name), prefix ? `${prefix}/${entry.name}` : entry.name);
+                continue;
+            }
+            const ext = path.extname(entry.name).toLowerCase();
+            const mime = MIME_TYPES[ext];
+            if (!mime)
+                continue;
+            const content = fs.readFileSync(path.join(dir, entry.name), 'utf-8');
+            const etag = '"' + crypto.createHash('md5').update(content).digest('hex').slice(0, 12) + '"';
+            const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+            compiledAssets.push({ name, content, mime, etag });
+        }
+    };
+    scanAssets(assetsDir, '');
+    return compiledAssets;
+}

package/dist/compiler/client-module-pipeline.d.ts

@@ -0,0 +1,25 @@
+import type { CompiledAsset } from './asset-pipeline.js';
+import { type RouteImportEntry } from './import-linking.js';
+export interface ClientEventRegistration {
+    routeId: string;
+    handlerId: string;
+    argsExpr: string | null;
+}
+export interface ClientModuleCompiler {
+    createRegistry(scopeId: string, importEntries: RouteImportEntry[]): ClientRouteRegistry;
+    createRouteRegistry(routeIndex: number, importEntries: RouteImportEntry[]): ClientRouteRegistry;
+    getCompiledAssets(): CompiledAsset[];
+}
+export interface ClientRouteRegistry {
+    hasBindings(): boolean;
+    hasBindingReference(expression: string): boolean;
+    registerEventHandler(eventName: string, expression: string): ClientEventRegistration | null;
+    buildEntryAsset(): {
+        assetName: string;
+        asset: CompiledAsset;
+    } | null;
+}
+export declare function createClientModuleCompiler(opts: {
+    projectDir: string;
+    srcDir: string;
+}): ClientModuleCompiler;