@kuratchi/js 0.0.16 → 0.0.17

package/README.md

@@ -16,9 +16,9 @@ cd my-app
 bun run dev
 ```
 
-## How it works
-
-`kuratchi build` (or `kuratchi watch`) scans `src/routes/` and generates framework output:
+## How it works
+
+`kuratchi build` (or `kuratchi watch`) scans `src/routes/` and generates framework output:
 
 | File | Purpose |
 |---|---|
@@ -26,13 +26,13 @@ bun run dev
 | `.kuratchi/worker.js` | Stable wrangler entry - re-exports the fetch handler plus all Durable Object and Agent classes |
 | `.kuratchi/do/*.js` | Generated Durable Object RPC proxy modules for `$durable-objects/*` imports |
 
-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
-{
+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
+{
   "main": ".kuratchi/worker.js"
 }
 ```
@@ -766,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

@@ -30,14 +30,14 @@ async function main() {
             await runCreate();
             return;
         default:
-            console.log(`
-KuratchiJS CLI
-
-Usage:
-  kuratchi create [name]  Scaffold a new KuratchiJS project
-  kuratchi build          Compile routes once
-  kuratchi dev            Compile, watch for changes, and start wrangler dev server
-  kuratchi watch          Compile + watch only (no wrangler — for custom setups)
+            console.log(`
+KuratchiJS CLI
+
+Usage:
+  kuratchi create [name]  Scaffold a new KuratchiJS project
+  kuratchi build          Compile routes once
+  kuratchi dev            Compile, watch for changes, and start wrangler dev server
+  kuratchi watch          Compile + watch only (no wrangler — for custom setups)
 `);
             process.exit(1);
     }
@@ -49,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) {
@@ -61,7 +61,7 @@ function runBuild(isDev = false) {
     }
 }
 async function runWatch(withWrangler = false) {
-    runBuild(true);
+    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));
@@ -69,10 +69,10 @@ async 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) {

package/dist/compiler/client-module-pipeline.js

@@ -2,7 +2,6 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { collectReferencedIdentifiers, parseImportStatement } from './import-linking.js';
-import { transpileTypeScript } from './transpile.js';
 function resolveExistingModuleFile(absBase) {
     const candidates = [
         absBase,
@@ -179,12 +178,13 @@ class CompilerBackedClientRouteRegistry {
         const registrationEntries = Array.from(this.handlerByKey.values()).map((record) => {
             return `${JSON.stringify(record.id)}: (args, event, element) => ${record.calleeExpr}(...args, event, element)`;
         });
-        const source = transpileTypeScript([
+        // TypeScript is preserved — wrangler's esbuild handles transpilation
+        const source = [
             ...importLines,
             `window.__kuratchiClient?.register(${JSON.stringify(this.routeId)}, {`,
             registrationEntries.map((entry) => `  ${entry},`).join('\n'),
             `});`,
-        ].join('\n'), `client-route:${this.routeId}.ts`);
+        ].join('\n');
         const asset = buildAsset(assetName, source);
         this.compiler.registerAsset(asset);
         return { assetName, asset };
@@ -241,9 +241,9 @@ class CompilerBackedClientModuleCompiler {
         if (!fs.existsSync(resolved)) {
             throw new Error(`[kuratchi compiler] Browser module not found: ${resolved}`);
         }
+        // TypeScript is preserved — wrangler's esbuild handles transpilation
         const source = fs.readFileSync(resolved, 'utf-8');
-        let rewritten = transpileTypeScript(source, `client-module:${relFromSrc}`);
-        rewritten = rewriteImportSpecifiers(rewritten, (spec) => {
+        let rewritten = rewriteImportSpecifiers(source, (spec) => {
             const targetAbs = resolveClientImportTarget(this.srcDir, resolved, spec);
             const targetAssetName = this.transformClientModule(targetAbs);
             return toRelativeSpecifier(assetName, targetAssetName);

package/dist/compiler/compiler-shared.d.ts

@@ -18,6 +18,24 @@ export interface AuthConfigEntry {
     hasTurnstile: boolean;
     hasOrganization: boolean;
 }
+export interface SecurityConfigEntry {
+    /** 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 (default: null - no CSP) */
+    contentSecurityPolicy: string | null;
+    /** Strict-Transport-Security header (default: null - no HSTS) */
+    strictTransportSecurity: string | null;
+    /** Permissions-Policy header (default: null) */
+    permissionsPolicy: string | null;
+}
 export interface DoConfigEntry {
     binding: string;
     className: string;

package/dist/compiler/component-pipeline.js

@@ -3,7 +3,6 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parseFile, stripTopLevelImports } from './parser.js';
 import { compileTemplate } from './template.js';
-import { transpileTypeScript } from './transpile.js';
 import { buildDevAliasDeclarations } from './script-transform.js';
 function resolvePackageComponent(projectDir, pkgName, componentFile) {
     const nmPath = path.join(projectDir, 'node_modules', pkgName, 'src', 'lib', componentFile + '.html');
@@ -62,12 +61,8 @@ export function createComponentCompiler(options) {
         const parsed = parseFile(rawSource, { kind: 'component', filePath });
         const propsCode = parsed.script ? stripTopLevelImports(parsed.script) : '';
         const devDecls = buildDevAliasDeclarations(parsed.devAliases, isDev);
+        // TypeScript is preserved — wrangler's esbuild handles transpilation
         const effectivePropsCode = [devDecls, propsCode].filter(Boolean).join('\n');
-        const transpiledPropsCode = propsCode
-            ? transpileTypeScript(effectivePropsCode, `component-script:${fileName}.ts`)
-            : devDecls
-                ? transpileTypeScript(devDecls, `component-script:${fileName}.ts`)
-                : '';
         let source = parsed.template;
         let styleBlock = '';
         const styleMatch = source.match(/<style[\s>][\s\S]*?<\/style>/i);
@@ -99,11 +94,11 @@ export function createComponentCompiler(options) {
         }
         componentActionCache.set(fileName, actionPropNames);
         const body = compileTemplate(source, subComponentNames, undefined, undefined);
-        const scopeOpen = `__html += '<div class="${scopeHash}">';`;
-        const scopeClose = `__html += '</div>';`;
+        const scopeOpen = `__parts.push('<div class="${scopeHash}">');`;
+        const scopeClose = `__parts.push('</div>');`;
         const bodyLines = body.split('\n');
         const scopedBody = [bodyLines[0], scopeOpen, ...bodyLines.slice(1), scopeClose].join('\n');
-        const fnBody = transpiledPropsCode ? `${transpiledPropsCode}\n  ${scopedBody}` : scopedBody;
+        const fnBody = effectivePropsCode ? `${effectivePropsCode}\n  ${scopedBody}` : scopedBody;
         const compiled = `function ${funcName}(props, __esc) {\n  ${fnBody}\n  return __html;\n}`;
         compiledComponentCache.set(fileName, compiled);
         return compiled;

package/dist/compiler/config-reading.d.ts

@@ -1,4 +1,4 @@
-import { type AuthConfigEntry, type DoConfigEntry, type OrmDatabaseEntry, type WorkerClassConfigEntry } from './compiler-shared.js';
+import { type AuthConfigEntry, type DoConfigEntry, type OrmDatabaseEntry, type SecurityConfigEntry, type WorkerClassConfigEntry } from './compiler-shared.js';
 export declare function readUiTheme(projectDir: string): string | null;
 export declare function readUiConfigValues(projectDir: string): {
     theme: string;
@@ -9,3 +9,4 @@ export declare function readAuthConfig(projectDir: string): AuthConfigEntry | nu
 export declare function readDoConfig(projectDir: string): DoConfigEntry[];
 export declare function readWorkerClassConfig(projectDir: string, key: 'containers' | 'workflows'): WorkerClassConfigEntry[];
 export declare function readAssetsPrefix(projectDir: string): string;
+export declare function readSecurityConfig(projectDir: string): SecurityConfigEntry;

package/dist/compiler/config-reading.js

@@ -321,3 +321,60 @@ export function readAssetsPrefix(projectDir) {
         prefix += '/';
     return prefix;
 }
+export function readSecurityConfig(projectDir) {
+    const defaults = {
+        csrfEnabled: true,
+        csrfCookieName: '__kuratchi_csrf',
+        csrfHeaderName: 'x-kuratchi-csrf',
+        rpcRequireAuth: false,
+        actionRequireAuth: false,
+        contentSecurityPolicy: null,
+        strictTransportSecurity: null,
+        permissionsPolicy: null,
+    };
+    const configPath = path.join(projectDir, 'kuratchi.config.ts');
+    if (!fs.existsSync(configPath))
+        return defaults;
+    const source = fs.readFileSync(configPath, 'utf-8');
+    const securityBlock = readConfigBlock(source, 'security');
+    if (!securityBlock)
+        return defaults;
+    const body = securityBlock.body;
+    // Parse CSRF settings
+    const csrfEnabledMatch = body.match(/csrfEnabled\s*:\s*(true|false)/);
+    if (csrfEnabledMatch) {
+        defaults.csrfEnabled = csrfEnabledMatch[1] === 'true';
+    }
+    const csrfCookieMatch = body.match(/csrfCookieName\s*:\s*['"]([^'"]+)['"]/);
+    if (csrfCookieMatch) {
+        defaults.csrfCookieName = csrfCookieMatch[1];
+    }
+    const csrfHeaderMatch = body.match(/csrfHeaderName\s*:\s*['"]([^'"]+)['"]/);
+    if (csrfHeaderMatch) {
+        defaults.csrfHeaderName = csrfHeaderMatch[1];
+    }
+    // Parse RPC settings
+    const rpcAuthMatch = body.match(/rpcRequireAuth\s*:\s*(true|false)/);
+    if (rpcAuthMatch) {
+        defaults.rpcRequireAuth = rpcAuthMatch[1] === 'true';
+    }
+    // Parse action settings
+    const actionAuthMatch = body.match(/actionRequireAuth\s*:\s*(true|false)/);
+    if (actionAuthMatch) {
+        defaults.actionRequireAuth = actionAuthMatch[1] === 'true';
+    }
+    // Parse security headers
+    const cspMatch = body.match(/contentSecurityPolicy\s*:\s*['"`]([^'"`]+)['"`]/);
+    if (cspMatch) {
+        defaults.contentSecurityPolicy = cspMatch[1];
+    }
+    const hstsMatch = body.match(/strictTransportSecurity\s*:\s*['"`]([^'"`]+)['"`]/);
+    if (hstsMatch) {
+        defaults.strictTransportSecurity = hstsMatch[1];
+    }
+    const permMatch = body.match(/permissionsPolicy\s*:\s*['"`]([^'"`]+)['"`]/);
+    if (permMatch) {
+        defaults.permissionsPolicy = permMatch[1];
+    }
+    return defaults;
+}

package/dist/compiler/durable-object-pipeline.js

@@ -65,7 +65,7 @@ export function discoverDurableObjects(srcDir, configDoEntries, ormDatabases) {
 }
 export function generateHandlerProxy(handler, opts) {
     const doDir = path.join(opts.projectDir, '.kuratchi', 'do');
-    const origRelPath = path.relative(doDir, handler.absPath).replace(/\\/g, '/').replace(/\.ts$/, '.js');
+    const origRelPath = path.relative(doDir, handler.absPath).replace(/\\/g, '/');
     const handlerLocal = `__handler_${toSafeIdentifier(handler.fileName)}`;
     const lifecycle = new Set(['constructor', 'fetch', 'alarm', 'webSocketMessage', 'webSocketClose', 'webSocketError']);
     const rpcFunctions = handler.classMethods

package/dist/compiler/import-linking.js

@@ -93,6 +93,7 @@ export function filterImportsByNeededBindings(imports, neededBindings) {
     }
     return selected;
 }
+const RESERVED_RENDER_VARS = new Set(['params', 'breadcrumbs']);
 export function linkRouteServerImports(opts) {
     const fnToModule = {};
     const routeImportDeclMap = new Map();
@@ -119,7 +120,7 @@ export function linkRouteServerImports(opts) {
                 continue;
             }
             fnToModule[binding.local] = moduleId;
-            if (!routeImportDeclMap.has(binding.local)) {
+            if (!routeImportDeclMap.has(binding.local) && !RESERVED_RENDER_VARS.has(binding.local)) {
                 const accessExpr = binding.imported === 'default' ? `${moduleId}.default` : `${moduleId}.${binding.imported}`;
                 routeImportDeclMap.set(binding.local, `const ${binding.local} = ${accessExpr};`);
             }

package/dist/compiler/index.d.ts

@@ -7,7 +7,7 @@ export { compileTemplate, generateRenderFunction } from './template.js';
 export interface CompileOptions {
     /** Absolute path to the project root */
     projectDir: string;
-    /** Override path for routes.js (default: .kuratchi/routes.js). worker.js is always co-located. */
+    /** Override path for routes.ts (default: .kuratchi/routes.ts). worker.ts is always co-located. */
     outFile?: string;
     /** Whether this is a dev build (sets __kuratchi_DEV__ global) */
     isDev?: boolean;
@@ -25,12 +25,12 @@ export interface CompiledRoute {
     hasRpc: boolean;
 }
 /**
- * Compile a project's src/routes/ into .kuratchi/routes.js
+ * Compile a project's src/routes/ into .kuratchi/routes.ts
  *
- * The generated module exports { app } ?" an object with a fetch() method
+ * The generated module exports { app } — an object with a fetch() method
  * that handles routing, load functions, form actions, and rendering.
- * Returns the path to .kuratchi/worker.js ? the stable wrangler entry point that
- * re-exports everything from routes.js (default fetch handler + named DO class exports).
+ * Returns the path to .kuratchi/worker.ts — the stable wrangler entry point that
+ * re-exports everything from routes.ts (default fetch handler + named DO class exports).
  * No src/index.ts is needed in user projects.
  */
-export declare function compile(options: CompileOptions): string;
+export declare function compile(options: CompileOptions): Promise<string>;