@vertz/cloudflare 0.2.0 → 0.2.3

package/.turbo/turbo-build.log

@@ -1,15 +1 @@
-$ bunup
-i Using bunup v0.16.26 and bun v1.3.9
-i Build started
-
-  src/index.ts
-
-  Output                Raw     Gzip
-
-  dist/index.js       676 B    349 B
-  dist/index.d.ts     327 B    225 B
-
-  2 files            1003 B    574 B
-
-
-✓ Build completed in 114ms
+$ tsc

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @vertz/cloudflare
+
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies [[`62dddcb`](https://github.com/vertz-dev/vertz/commit/62dddcbcb4943b12a04bca8466b09ae21901070b), [`2e86c55`](https://github.com/vertz-dev/vertz/commit/2e86c55e3c04f3c534bf0dc124d18dcdc5d9eefc), [`62dddcb`](https://github.com/vertz-dev/vertz/commit/62dddcbcb4943b12a04bca8466b09ae21901070b), [`b0b6115`](https://github.com/vertz-dev/vertz/commit/b0b6115e0389447ffb951e875b5ce224e4ace51c)]:
+  - @vertz/core@0.2.3
+  - @vertz/ui-server@0.2.3
+
+## 0.2.2
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @vertz/ui-server@0.2.2
+  - @vertz/core@0.2.2

package/dist/handler.d.ts

@@ -0,0 +1,73 @@
+import type { AppBuilder } from '@vertz/core';
+import type { SSRModule } from '@vertz/ui-server/ssr';
+export interface CloudflareHandlerOptions {
+    basePath?: string;
+}
+/**
+ * SSR module configuration for zero-boilerplate server-side rendering.
+ *
+ * Pass the app module directly and the handler generates the HTML template,
+ * wires up createSSRHandler, and handles the full SSR pipeline.
+ */
+export interface SSRModuleConfig {
+    /** App module exporting App, theme?, styles?, getInjectedCSS? */
+    module: SSRModule;
+    /** Client-side entry script path. Default: '/assets/entry-client.js' */
+    clientScript?: string;
+    /** HTML document title. Default: 'Vertz App' */
+    title?: string;
+    /** SSR query timeout in ms. Default: 5000 (generous for D1 cold starts). */
+    ssrTimeout?: number;
+}
+/**
+ * Full-stack configuration for createHandler.
+ *
+ * Supports lazy app initialization (for D1 bindings), SSR fallback,
+ * and automatic security headers.
+ */
+export interface CloudflareHandlerConfig {
+    /**
+     * Factory that creates the AppBuilder. Receives the Worker env bindings.
+     * Called once on first request, then cached.
+     */
+    app: (env: unknown) => AppBuilder;
+    /** API path prefix. Requests matching this prefix go to the app handler. */
+    basePath: string;
+    /**
+     * SSR configuration for non-API routes.
+     *
+     * - `SSRModuleConfig` — zero-boilerplate: pass the app module directly
+     * - `(request: Request) => Promise<Response>` — custom SSR callback
+     * - `undefined` — non-API requests return 404
+     */
+    ssr?: SSRModuleConfig | ((request: Request) => Promise<Response>);
+    /** When true, adds standard security headers to all responses. */
+    securityHeaders?: boolean;
+}
+/** Generate a cryptographically random nonce for CSP. */
+export declare function generateNonce(): string;
+/**
+ * Create a Cloudflare Worker handler from a Vertz app.
+ *
+ * Simple form — wraps an AppBuilder directly:
+ * ```ts
+ * export default createHandler(app, { basePath: '/api' });
+ * ```
+ *
+ * Config form — full-stack with lazy init, SSR, and security headers:
+ * ```ts
+ * export default createHandler({
+ *   app: (env) => createServer({ entities, db: createDb({ d1: env.DB }) }),
+ *   basePath: '/api',
+ *   ssr: (req) => renderToString(new URL(req.url).pathname),
+ *   securityHeaders: true,
+ * });
+ * ```
+ */
+/** Worker module shape returned by createHandler. */
+export interface CloudflareWorkerModule {
+    fetch(request: Request, env: unknown, ctx: ExecutionContext): Promise<Response>;
+}
+export declare function createHandler(appOrConfig: AppBuilder | CloudflareHandlerConfig, options?: CloudflareHandlerOptions): CloudflareWorkerModule;
+export declare function generateHTMLTemplate(clientScript: string, title: string, nonce?: string): string;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAMtD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,MAAM,EAAE,SAAS,CAAC;IAClB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,UAAU,CAAC;IAElC,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,eAAe,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAElE,kEAAkE;IAClE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAMD,yDAAyD;AACzD,wBAAgB,aAAa,IAAI,MAAM,CAStC;AA4CD;;;;;;;;;;;;;;;;;GAiBG;AACH,qDAAqD;AACrD,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACjF;AAED,wBAAgB,aAAa,CAC3B,WAAW,EAAE,UAAU,GAAG,uBAAuB,EACjD,OAAO,CAAC,EAAE,wBAAwB,GACjC,sBAAsB,CAQxB;AA+BD,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAchG"}

package/dist/handler.js

@@ -0,0 +1,196 @@
+// ---------------------------------------------------------------------------
+// Security headers
+// ---------------------------------------------------------------------------
+/** Generate a cryptographically random nonce for CSP. */
+export function generateNonce() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    // Base64-encode without padding for a compact, URL-safe nonce
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+const STATIC_SECURITY_HEADERS = {
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'X-XSS-Protection': '1; mode=block',
+    'Referrer-Policy': 'strict-origin-when-cross-origin',
+    'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
+};
+function buildCSPHeader(nonce) {
+    return `default-src 'self'; script-src 'self' 'nonce-${nonce}'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;`;
+}
+function withSecurityHeaders(response, nonce) {
+    const headers = new Headers(response.headers);
+    for (const [key, value] of Object.entries(STATIC_SECURITY_HEADERS)) {
+        headers.set(key, value);
+    }
+    headers.set('Content-Security-Policy', buildCSPHeader(nonce));
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function stripBasePath(request, basePath) {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith(basePath)) {
+        url.pathname = url.pathname.slice(basePath.length) || '/';
+        return new Request(url.toString(), request);
+    }
+    return request;
+}
+export function createHandler(appOrConfig, options) {
+    // Config object form
+    if ('app' in appOrConfig && typeof appOrConfig.app === 'function') {
+        return createFullStackHandler(appOrConfig);
+    }
+    // Simple AppBuilder form (backward compat)
+    return createSimpleHandler(appOrConfig, options);
+}
+// ---------------------------------------------------------------------------
+// Simple handler (backward compat)
+// ---------------------------------------------------------------------------
+function createSimpleHandler(app, options) {
+    const handler = app.handler;
+    return {
+        async fetch(request, _env, _ctx) {
+            if (options?.basePath) {
+                request = stripBasePath(request, options.basePath);
+            }
+            try {
+                return await handler(request);
+            }
+            catch (error) {
+                console.error('Unhandled error in worker:', error);
+                return new Response('Internal Server Error', { status: 500 });
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// HTML template generation
+// ---------------------------------------------------------------------------
+export function generateHTMLTemplate(clientScript, title, nonce) {
+    const nonceAttr = nonce != null ? ` nonce="${nonce}"` : '';
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${title}</title>
+</head>
+<body>
+<div id="app"><!--ssr-outlet--></div>
+<script type="module" src="${clientScript}"${nonceAttr}></script>
+</body>
+</html>`;
+}
+// ---------------------------------------------------------------------------
+// Full-stack handler
+// ---------------------------------------------------------------------------
+function isSSRModuleConfig(ssr) {
+    return typeof ssr === 'object' && 'module' in ssr;
+}
+function createFullStackHandler(config) {
+    const { basePath, ssr, securityHeaders } = config;
+    let cachedApp = null;
+    // SSR handler factory: when using SSRModuleConfig with nonce support, this
+    // is called per-request with the current nonce. For custom callbacks it
+    // is set once and always returns the same handler.
+    let ssrHandlerFactory = null;
+    let ssrResolved = false;
+    function getApp(env) {
+        if (!cachedApp) {
+            cachedApp = config.app(env);
+        }
+        return cachedApp;
+    }
+    async function resolveSSR() {
+        if (ssrResolved)
+            return;
+        ssrResolved = true;
+        if (!ssr)
+            return;
+        if (isSSRModuleConfig(ssr)) {
+            const { createSSRHandler } = await import('@vertz/ui-server/ssr');
+            const { module, clientScript = '/assets/entry-client.js', title = 'Vertz App', ssrTimeout = 5000, } = ssr;
+            // Return a factory that creates an SSR handler with the per-request nonce
+            ssrHandlerFactory = (nonce) => createSSRHandler({
+                module,
+                template: generateHTMLTemplate(clientScript, title, nonce),
+                ssrTimeout,
+                nonce,
+            });
+        }
+        else {
+            // Custom callback — wrap it in a factory that ignores the nonce
+            ssrHandlerFactory = () => ssr;
+        }
+    }
+    function applyHeaders(response, nonce) {
+        return securityHeaders ? withSecurityHeaders(response, nonce) : response;
+    }
+    return {
+        async fetch(request, env, _ctx) {
+            await resolveSSR();
+            const url = new URL(request.url);
+            const nonce = generateNonce();
+            // Route splitting: basePath/* → API handler (no URL rewriting — the
+            // app's own basePath/apiPrefix handles prefix matching internally)
+            if (url.pathname.startsWith(basePath)) {
+                try {
+                    const app = getApp(env);
+                    const response = await app.handler(request);
+                    return applyHeaders(response, nonce);
+                }
+                catch (error) {
+                    console.error('Unhandled error in worker:', error);
+                    return applyHeaders(new Response('Internal Server Error', { status: 500 }), nonce);
+                }
+            }
+            // Non-API routes → SSR or 404
+            if (ssrHandlerFactory) {
+                const app = getApp(env);
+                const ssrHandler = ssrHandlerFactory(nonce);
+                const origin = url.origin;
+                // Patch fetch during SSR so API requests (e.g. query() calling
+                // fetch('/api/todos')) are routed through the in-memory app handler
+                // instead of attempting a network self-fetch (which fails on Workers).
+                const originalFetch = globalThis.fetch;
+                globalThis.fetch = (input, init) => {
+                    // Determine the pathname from the input (string, URL, or Request)
+                    const rawUrl = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+                    const isRelative = rawUrl.startsWith('/');
+                    const pathname = isRelative ? rawUrl.split('?')[0] : new URL(rawUrl).pathname;
+                    const isLocal = isRelative || new URL(rawUrl).origin === origin;
+                    if (isLocal && pathname.startsWith(basePath)) {
+                        // Build an absolute URL so Request() doesn't reject relative URLs
+                        const absoluteUrl = isRelative ? `${origin}${rawUrl}` : rawUrl;
+                        const req = new Request(absoluteUrl, init);
+                        return app.handler(req);
+                    }
+                    return originalFetch(input, init);
+                };
+                try {
+                    const response = await ssrHandler(request);
+                    return applyHeaders(response, nonce);
+                }
+                catch (error) {
+                    console.error('Unhandled error in worker:', error);
+                    return applyHeaders(new Response('Internal Server Error', { status: 500 }), nonce);
+                }
+                finally {
+                    globalThis.fetch = originalFetch;
+                }
+            }
+            return applyHeaders(new Response('Not Found', { status: 404 }), nonce);
+        },
+    };
+}
+//# sourceMappingURL=handler.js.map

package/dist/handler.js.map

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

package/dist/index.d.ts

@@ -1,8 +1,3 @@
-import { AppBuilder } from "@vertz/core";
-interface CloudflareHandlerOptions {
-	basePath?: string;
-}
-declare function createHandler(app: AppBuilder, options?: CloudflareHandlerOptions): {
-	fetch(request: Request, _env: unknown, _ctx: ExecutionContext): Promise<Response>;
-};
-export { createHandler, CloudflareHandlerOptions };
+export type { CloudflareHandlerConfig, CloudflareHandlerOptions, CloudflareWorkerModule, SSRModuleConfig, } from './handler.js';
+export { createHandler, generateHTMLTemplate, generateNonce } from './handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,24 +1,2 @@
-// src/handler.ts
-function createHandler(app, options) {
-  const handler = app.handler;
-  return {
-    async fetch(request, _env, _ctx) {
-      if (options?.basePath) {
-        const url = new URL(request.url);
-        if (url.pathname.startsWith(options.basePath)) {
-          url.pathname = url.pathname.slice(options.basePath.length) || "/";
-          request = new Request(url.toString(), request);
-        }
-      }
-      try {
-        return await handler(request);
-      } catch (error) {
-        console.error("Unhandled error in worker:", error);
-        return new Response("Internal Server Error", { status: 500 });
-      }
-    }
-  };
-}
-export {
-  createHandler
-};
+export { createHandler, generateHTMLTemplate, generateNonce } from './handler.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/cloudflare",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Cloudflare Workers adapter for vertz",
   "type": "module",
   "main": "dist/index.js",
@@ -17,20 +17,21 @@
     }
   },
   "scripts": {
-    "build": "bunup",
+    "build": "tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
-    "@vertz/core": "workspace:*"
+    "@vertz/core": "0.2.2"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20250214.0",
-    "bunup": "latest",
+    "@cloudflare/workers-types": "^4.20260305.0",
+    "@vertz/ui-server": "0.2.2",
+    "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.7.3"
   },
   "peerDependencies": {
-    "@vertz/ui-server": "workspace:*"
+    "@vertz/ui-server": "0.2.2"
   },
   "peerDependenciesMeta": {
     "@vertz/ui-server": {

package/src/handler.ts

@@ -1,21 +1,168 @@
 import type { AppBuilder } from '@vertz/core';
+import type { SSRModule } from '@vertz/ui-server/ssr';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
 
 export interface CloudflareHandlerOptions {
   basePath?: string;
 }
 
-export function createHandler(app: AppBuilder, options?: CloudflareHandlerOptions) {
+/**
+ * SSR module configuration for zero-boilerplate server-side rendering.
+ *
+ * Pass the app module directly and the handler generates the HTML template,
+ * wires up createSSRHandler, and handles the full SSR pipeline.
+ */
+export interface SSRModuleConfig {
+  /** App module exporting App, theme?, styles?, getInjectedCSS? */
+  module: SSRModule;
+  /** Client-side entry script path. Default: '/assets/entry-client.js' */
+  clientScript?: string;
+  /** HTML document title. Default: 'Vertz App' */
+  title?: string;
+  /** SSR query timeout in ms. Default: 5000 (generous for D1 cold starts). */
+  ssrTimeout?: number;
+}
+
+/**
+ * Full-stack configuration for createHandler.
+ *
+ * Supports lazy app initialization (for D1 bindings), SSR fallback,
+ * and automatic security headers.
+ */
+export interface CloudflareHandlerConfig {
+  /**
+   * Factory that creates the AppBuilder. Receives the Worker env bindings.
+   * Called once on first request, then cached.
+   */
+  app: (env: unknown) => AppBuilder;
+
+  /** API path prefix. Requests matching this prefix go to the app handler. */
+  basePath: string;
+
+  /**
+   * SSR configuration for non-API routes.
+   *
+   * - `SSRModuleConfig` — zero-boilerplate: pass the app module directly
+   * - `(request: Request) => Promise<Response>` — custom SSR callback
+   * - `undefined` — non-API requests return 404
+   */
+  ssr?: SSRModuleConfig | ((request: Request) => Promise<Response>);
+
+  /** When true, adds standard security headers to all responses. */
+  securityHeaders?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Security headers
+// ---------------------------------------------------------------------------
+
+/** Generate a cryptographically random nonce for CSP. */
+export function generateNonce(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  // Base64-encode without padding for a compact, URL-safe nonce
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+const STATIC_SECURITY_HEADERS: Record<string, string> = {
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'X-XSS-Protection': '1; mode=block',
+  'Referrer-Policy': 'strict-origin-when-cross-origin',
+  'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
+};
+
+function buildCSPHeader(nonce: string): string {
+  return `default-src 'self'; script-src 'self' 'nonce-${nonce}'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;`;
+}
+
+function withSecurityHeaders(response: Response, nonce: string): Response {
+  const headers = new Headers(response.headers);
+  for (const [key, value] of Object.entries(STATIC_SECURITY_HEADERS)) {
+    headers.set(key, value);
+  }
+  headers.set('Content-Security-Policy', buildCSPHeader(nonce));
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function stripBasePath(request: Request, basePath: string): Request {
+  const url = new URL(request.url);
+  if (url.pathname.startsWith(basePath)) {
+    url.pathname = url.pathname.slice(basePath.length) || '/';
+    return new Request(url.toString(), request);
+  }
+  return request;
+}
+
+// ---------------------------------------------------------------------------
+// createHandler overloads
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Cloudflare Worker handler from a Vertz app.
+ *
+ * Simple form — wraps an AppBuilder directly:
+ * ```ts
+ * export default createHandler(app, { basePath: '/api' });
+ * ```
+ *
+ * Config form — full-stack with lazy init, SSR, and security headers:
+ * ```ts
+ * export default createHandler({
+ *   app: (env) => createServer({ entities, db: createDb({ d1: env.DB }) }),
+ *   basePath: '/api',
+ *   ssr: (req) => renderToString(new URL(req.url).pathname),
+ *   securityHeaders: true,
+ * });
+ * ```
+ */
+/** Worker module shape returned by createHandler. */
+export interface CloudflareWorkerModule {
+  fetch(request: Request, env: unknown, ctx: ExecutionContext): Promise<Response>;
+}
+
+export function createHandler(
+  appOrConfig: AppBuilder | CloudflareHandlerConfig,
+  options?: CloudflareHandlerOptions,
+): CloudflareWorkerModule {
+  // Config object form
+  if ('app' in appOrConfig && typeof appOrConfig.app === 'function') {
+    return createFullStackHandler(appOrConfig);
+  }
+
+  // Simple AppBuilder form (backward compat)
+  return createSimpleHandler(appOrConfig as AppBuilder, options);
+}
+
+// ---------------------------------------------------------------------------
+// Simple handler (backward compat)
+// ---------------------------------------------------------------------------
+
+function createSimpleHandler(
+  app: AppBuilder,
+  options?: CloudflareHandlerOptions,
+): CloudflareWorkerModule {
   const handler = app.handler;
 
   return {
     async fetch(request: Request, _env: unknown, _ctx: ExecutionContext): Promise<Response> {
-      // If basePath, strip it from the URL before routing
       if (options?.basePath) {
-        const url = new URL(request.url);
-        if (url.pathname.startsWith(options.basePath)) {
-          url.pathname = url.pathname.slice(options.basePath.length) || '/';
-          request = new Request(url.toString(), request);
-        }
+        request = stripBasePath(request, options.basePath);
       }
       try {
         return await handler(request);
@@ -26,3 +173,142 @@ export function createHandler(app: AppBuilder, options?: CloudflareHandlerOption
     },
   };
 }
+
+// ---------------------------------------------------------------------------
+// HTML template generation
+// ---------------------------------------------------------------------------
+
+export function generateHTMLTemplate(clientScript: string, title: string, nonce?: string): string {
+  const nonceAttr = nonce != null ? ` nonce="${nonce}"` : '';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${title}</title>
+</head>
+<body>
+<div id="app"><!--ssr-outlet--></div>
+<script type="module" src="${clientScript}"${nonceAttr}></script>
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// Full-stack handler
+// ---------------------------------------------------------------------------
+
+function isSSRModuleConfig(
+  ssr: SSRModuleConfig | ((request: Request) => Promise<Response>),
+): ssr is SSRModuleConfig {
+  return typeof ssr === 'object' && 'module' in ssr;
+}
+
+function createFullStackHandler(config: CloudflareHandlerConfig): CloudflareWorkerModule {
+  const { basePath, ssr, securityHeaders } = config;
+  let cachedApp: AppBuilder | null = null;
+  // SSR handler factory: when using SSRModuleConfig with nonce support, this
+  // is called per-request with the current nonce. For custom callbacks it
+  // is set once and always returns the same handler.
+  let ssrHandlerFactory: ((nonce?: string) => (request: Request) => Promise<Response>) | null =
+    null;
+  let ssrResolved = false;
+
+  function getApp(env: unknown): AppBuilder {
+    if (!cachedApp) {
+      cachedApp = config.app(env);
+    }
+    return cachedApp;
+  }
+
+  async function resolveSSR(): Promise<void> {
+    if (ssrResolved) return;
+    ssrResolved = true;
+
+    if (!ssr) return;
+
+    if (isSSRModuleConfig(ssr)) {
+      const { createSSRHandler } = await import('@vertz/ui-server/ssr');
+      const {
+        module,
+        clientScript = '/assets/entry-client.js',
+        title = 'Vertz App',
+        ssrTimeout = 5000,
+      } = ssr;
+      // Return a factory that creates an SSR handler with the per-request nonce
+      ssrHandlerFactory = (nonce?: string) =>
+        createSSRHandler({
+          module,
+          template: generateHTMLTemplate(clientScript, title, nonce),
+          ssrTimeout,
+          nonce,
+        });
+    } else {
+      // Custom callback — wrap it in a factory that ignores the nonce
+      ssrHandlerFactory = () => ssr;
+    }
+  }
+
+  function applyHeaders(response: Response, nonce: string): Response {
+    return securityHeaders ? withSecurityHeaders(response, nonce) : response;
+  }
+
+  return {
+    async fetch(request: Request, env: unknown, _ctx: ExecutionContext): Promise<Response> {
+      await resolveSSR();
+      const url = new URL(request.url);
+      const nonce = generateNonce();
+
+      // Route splitting: basePath/* → API handler (no URL rewriting — the
+      // app's own basePath/apiPrefix handles prefix matching internally)
+      if (url.pathname.startsWith(basePath)) {
+        try {
+          const app = getApp(env);
+          const response = await app.handler(request);
+          return applyHeaders(response, nonce);
+        } catch (error) {
+          console.error('Unhandled error in worker:', error);
+          return applyHeaders(new Response('Internal Server Error', { status: 500 }), nonce);
+        }
+      }
+
+      // Non-API routes → SSR or 404
+      if (ssrHandlerFactory) {
+        const app = getApp(env);
+        const ssrHandler = ssrHandlerFactory(nonce);
+        const origin = url.origin;
+        // Patch fetch during SSR so API requests (e.g. query() calling
+        // fetch('/api/todos')) are routed through the in-memory app handler
+        // instead of attempting a network self-fetch (which fails on Workers).
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (input, init) => {
+          // Determine the pathname from the input (string, URL, or Request)
+          const rawUrl =
+            typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+          const isRelative = rawUrl.startsWith('/');
+          const pathname = isRelative ? rawUrl.split('?')[0] : new URL(rawUrl).pathname;
+          const isLocal = isRelative || new URL(rawUrl).origin === origin;
+
+          if (isLocal && pathname.startsWith(basePath)) {
+            // Build an absolute URL so Request() doesn't reject relative URLs
+            const absoluteUrl = isRelative ? `${origin}${rawUrl}` : rawUrl;
+            const req = new Request(absoluteUrl, init);
+            return app.handler(req);
+          }
+          return originalFetch(input, init);
+        };
+        try {
+          const response = await ssrHandler(request);
+          return applyHeaders(response, nonce);
+        } catch (error) {
+          console.error('Unhandled error in worker:', error);
+          return applyHeaders(new Response('Internal Server Error', { status: 500 }), nonce);
+        } finally {
+          globalThis.fetch = originalFetch;
+        }
+      }
+
+      return applyHeaders(new Response('Not Found', { status: 404 }), nonce);
+    },
+  };
+}

package/src/index.ts

@@ -1,2 +1,7 @@
-export type { CloudflareHandlerOptions } from './handler.js';
-export { createHandler } from './handler.js';
+export type {
+  CloudflareHandlerConfig,
+  CloudflareHandlerOptions,
+  CloudflareWorkerModule,
+  SSRModuleConfig,
+} from './handler.js';
+export { createHandler, generateHTMLTemplate, generateNonce } from './handler.js';

package/tests/handler.test.ts

@@ -1,6 +1,12 @@
 import type { AppBuilder } from '@vertz/core';
-import { describe, expect, it, vi } from 'vitest';
-import { createHandler } from '../src/handler.js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createHandler, generateHTMLTemplate, generateNonce } from '../src/handler.js';
+
+function mockApp(handler?: (...args: unknown[]) => Promise<Response>): AppBuilder {
+  return {
+    handler: handler ?? vi.fn().mockResolvedValue(new Response('OK')),
+  } as unknown as AppBuilder;
+}
 
 describe('createHandler', () => {
   it('returns proper Worker export with fetch method', () => {
@@ -176,3 +182,494 @@ describe('createHandler', () => {
     consoleErrorSpy.mockRestore();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Full-stack config-based createHandler
+// ---------------------------------------------------------------------------
+
+describe('createHandler (config object)', () => {
+  const mockEnv = { DB: {} };
+  const mockCtx = {} as ExecutionContext;
+
+  it('routes API requests to app handler and SSR to ssr handler', async () => {
+    const apiHandler = vi.fn().mockResolvedValue(
+      new Response('{"items":[]}', {
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    const ssrHandler = vi.fn().mockResolvedValue(
+      new Response('<html>SSR</html>', {
+        headers: { 'Content-Type': 'text/html' },
+      }),
+    );
+
+    const worker = createHandler({
+      app: () => mockApp(apiHandler),
+      basePath: '/api',
+      ssr: ssrHandler,
+    });
+
+    // API request → app handler
+    const apiResponse = await worker.fetch(
+      new Request('https://example.com/api/todos'),
+      mockEnv,
+      mockCtx,
+    );
+    expect(apiHandler).toHaveBeenCalled();
+    expect(await apiResponse.text()).toBe('{"items":[]}');
+
+    // SSR request → ssr handler
+    const ssrResponse = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+    expect(ssrHandler).toHaveBeenCalled();
+    expect(await ssrResponse.text()).toBe('<html>SSR</html>');
+  });
+
+  it('passes env to the app factory and caches the result', async () => {
+    const apiHandler = vi.fn().mockResolvedValue(new Response('OK'));
+    const appFactory = vi.fn().mockReturnValue(mockApp(apiHandler));
+
+    const worker = createHandler({
+      app: appFactory,
+      basePath: '/api',
+    });
+
+    // First request — factory called
+    await worker.fetch(new Request('https://example.com/api/x'), mockEnv, mockCtx);
+    expect(appFactory).toHaveBeenCalledTimes(1);
+    expect(appFactory).toHaveBeenCalledWith(mockEnv);
+
+    // Second request — factory NOT called again (cached)
+    await worker.fetch(new Request('https://example.com/api/y'), mockEnv, mockCtx);
+    expect(appFactory).toHaveBeenCalledTimes(1);
+  });
+
+  it('adds security headers when securityHeaders is true', async () => {
+    const worker = createHandler({
+      app: () => mockApp(vi.fn().mockResolvedValue(new Response('OK'))),
+      basePath: '/api',
+      securityHeaders: true,
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/api/test'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(response.headers.get('X-Content-Type-Options')).toBe('nosniff');
+    expect(response.headers.get('X-Frame-Options')).toBe('DENY');
+    expect(response.headers.get('Referrer-Policy')).toBe('strict-origin-when-cross-origin');
+  });
+
+  it('adds security headers to SSR responses too', async () => {
+    const worker = createHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: () => Promise.resolve(new Response('<html></html>')),
+      securityHeaders: true,
+    });
+
+    const response = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(response.headers.get('X-Content-Type-Options')).toBe('nosniff');
+    expect(response.headers.get('X-Frame-Options')).toBe('DENY');
+  });
+
+  it('passes full URL to app handler (no basePath stripping)', async () => {
+    const apiHandler = vi.fn().mockResolvedValue(new Response('OK'));
+
+    const worker = createHandler({
+      app: () => mockApp(apiHandler),
+      basePath: '/api',
+    });
+
+    await worker.fetch(new Request('https://example.com/api/todos/123'), mockEnv, mockCtx);
+
+    const calledRequest = apiHandler.mock.calls[0][0] as Request;
+    const url = new URL(calledRequest.url);
+    expect(url.pathname).toBe('/api/todos/123');
+  });
+
+  it('returns 500 with error message when app handler throws', async () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const worker = createHandler({
+      app: () => mockApp(vi.fn().mockRejectedValue(new Error('DB connection failed'))),
+      basePath: '/api',
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/api/test'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(response.status).toBe(500);
+    expect(await response.text()).toBe('Internal Server Error');
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('returns 500 with error message when SSR handler throws', async () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const worker = createHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: () => Promise.reject(new Error('SSR render failed')),
+    });
+
+    const response = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(response.status).toBe(500);
+    expect(await response.text()).toBe('Internal Server Error');
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('returns 404 for non-API routes when no SSR handler is provided', async () => {
+    const worker = createHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/some-page'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(response.status).toBe(404);
+    expect(await response.text()).toBe('Not Found');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// generateHTMLTemplate
+// ---------------------------------------------------------------------------
+
+describe('generateHTMLTemplate', () => {
+  it('generates HTML with ssr-outlet, client script, and title', () => {
+    const html = generateHTMLTemplate('/assets/client.js', 'My App');
+
+    expect(html).toContain('<!--ssr-outlet-->');
+    expect(html).toContain('<script type="module" src="/assets/client.js"></script>');
+    expect(html).toContain('<title>My App</title>');
+    expect(html).toContain('<!doctype html>');
+    expect(html).toContain('<div id="app">');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// SSR module config
+// ---------------------------------------------------------------------------
+
+describe('createHandler (SSR module config)', () => {
+  const mockEnv = { DB: {} };
+  const mockCtx = {} as ExecutionContext;
+
+  // We mock @vertz/ui-server's createSSRHandler to isolate wiring logic.
+  // The mock returns a handler that echoes 'SSR Module' so we can verify routing.
+  const mockSSRRequestHandler = vi.fn().mockResolvedValue(
+    new Response('<html>SSR Module</html>', {
+      headers: { 'Content-Type': 'text/html' },
+    }),
+  );
+  const mockCreateSSRHandler = vi.fn().mockReturnValue(mockSSRRequestHandler);
+
+  beforeEach(() => {
+    vi.doMock('@vertz/ui-server/ssr', () => ({
+      createSSRHandler: mockCreateSSRHandler,
+    }));
+    mockSSRRequestHandler.mockClear();
+    mockCreateSSRHandler.mockClear();
+  });
+
+  afterEach(() => {
+    vi.doUnmock('@vertz/ui-server/ssr');
+  });
+
+  it('routes non-API requests through the SSR handler created from module config', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const ssrModule = { App: () => ({}) };
+    const worker = freshCreateHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: { module: ssrModule },
+    });
+
+    const response = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(mockCreateSSRHandler).toHaveBeenCalledOnce();
+    expect(mockSSRRequestHandler).toHaveBeenCalled();
+    expect(await response.text()).toBe('<html>SSR Module</html>');
+  });
+
+  it('passes default clientScript and title to createSSRHandler', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const ssrModule = { App: () => ({}) };
+    const worker = freshCreateHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: { module: ssrModule },
+    });
+
+    await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(mockCreateSSRHandler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        module: ssrModule,
+        template: expect.stringContaining('/assets/entry-client.js'),
+      }),
+    );
+    expect(mockCreateSSRHandler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        module: ssrModule,
+        template: expect.stringContaining('<title>Vertz App</title>'),
+      }),
+    );
+  });
+
+  it('passes custom clientScript and title to createSSRHandler', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const ssrModule = { App: () => ({}) };
+    const worker = freshCreateHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: {
+        module: ssrModule,
+        clientScript: '/custom/client.js',
+        title: 'My Custom App',
+      },
+    });
+
+    await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    expect(mockCreateSSRHandler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        module: ssrModule,
+        template: expect.stringContaining('/custom/client.js'),
+      }),
+    );
+    expect(mockCreateSSRHandler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        module: ssrModule,
+        template: expect.stringContaining('<title>My Custom App</title>'),
+      }),
+    );
+  });
+
+  it('still works with ssr callback (backward compat)', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const ssrCallback = vi.fn().mockResolvedValue(
+      new Response('<html>Callback SSR</html>', {
+        headers: { 'Content-Type': 'text/html' },
+      }),
+    );
+
+    const worker = freshCreateHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: ssrCallback,
+    });
+
+    const response = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    // createSSRHandler should NOT be called — callback is used directly
+    expect(mockCreateSSRHandler).not.toHaveBeenCalled();
+    expect(ssrCallback).toHaveBeenCalled();
+    expect(await response.text()).toBe('<html>Callback SSR</html>');
+  });
+
+  it('routes API requests to app handler even with SSR module config', async () => {
+    const { createHandler: freshCreateHandler } = await import('../src/handler.js');
+
+    const apiHandler = vi.fn().mockResolvedValue(
+      new Response('{"items":[]}', {
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+
+    const worker = freshCreateHandler({
+      app: () => mockApp(apiHandler),
+      basePath: '/api',
+      ssr: { module: { App: () => ({}) } },
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/api/todos'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(apiHandler).toHaveBeenCalled();
+    expect(mockSSRRequestHandler).not.toHaveBeenCalled();
+    expect(await response.text()).toBe('{"items":[]}');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Nonce-based CSP
+// ---------------------------------------------------------------------------
+
+describe('generateNonce', () => {
+  it('returns a base64-encoded string', () => {
+    const nonce = generateNonce();
+
+    expect(typeof nonce).toBe('string');
+    expect(nonce.length).toBeGreaterThan(0);
+    // Base64 alphabet: A-Z, a-z, 0-9, +, /, =
+    expect(nonce).toMatch(/^[A-Za-z0-9+/=]+$/);
+  });
+
+  it('generates different nonces on each call', () => {
+    const nonces = new Set<string>();
+    for (let i = 0; i < 50; i++) {
+      nonces.add(generateNonce());
+    }
+    // With 128-bit random values, collisions are astronomically unlikely
+    expect(nonces.size).toBe(50);
+  });
+});
+
+describe('nonce-based CSP headers', () => {
+  const mockEnv = { DB: {} };
+  const mockCtx = {} as ExecutionContext;
+
+  it('CSP header contains nonce (not unsafe-inline) for script-src', async () => {
+    const worker = createHandler({
+      app: () => mockApp(vi.fn().mockResolvedValue(new Response('OK'))),
+      basePath: '/api',
+      securityHeaders: true,
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/api/test'),
+      mockEnv,
+      mockCtx,
+    );
+
+    const csp = response.headers.get('Content-Security-Policy')!;
+    expect(csp).toBeTruthy();
+    // Extract the script-src directive and verify it uses nonce, not unsafe-inline
+    const scriptSrcMatch = csp.match(/script-src\s+([^;]+)/);
+    expect(scriptSrcMatch).toBeTruthy();
+    const scriptSrc = scriptSrcMatch![1];
+    expect(scriptSrc).not.toContain('unsafe-inline');
+    expect(scriptSrc).toMatch(/'nonce-[A-Za-z0-9+/=]+'/);
+  });
+
+  it('CSP header keeps unsafe-inline for style-src', async () => {
+    const worker = createHandler({
+      app: () => mockApp(vi.fn().mockResolvedValue(new Response('OK'))),
+      basePath: '/api',
+      securityHeaders: true,
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/api/test'),
+      mockEnv,
+      mockCtx,
+    );
+
+    const csp = response.headers.get('Content-Security-Policy');
+    expect(csp).toMatch(/style-src 'self' 'unsafe-inline'/);
+  });
+
+  it('each request gets a different nonce in the CSP header', async () => {
+    const worker = createHandler({
+      app: () => mockApp(vi.fn().mockResolvedValue(new Response('OK'))),
+      basePath: '/api',
+      securityHeaders: true,
+    });
+
+    const nonces: string[] = [];
+    for (let i = 0; i < 10; i++) {
+      const response = await worker.fetch(
+        new Request('https://example.com/api/test'),
+        mockEnv,
+        mockCtx,
+      );
+      const csp = response.headers.get('Content-Security-Policy')!;
+      const match = csp.match(/nonce-([A-Za-z0-9+/=]+)/);
+      expect(match).toBeTruthy();
+      nonces.push(match![1]);
+    }
+
+    // All nonces should be unique
+    expect(new Set(nonces).size).toBe(10);
+  });
+
+  it('applies nonce-based CSP to SSR responses', async () => {
+    const worker = createHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      ssr: () => Promise.resolve(new Response('<html></html>')),
+      securityHeaders: true,
+    });
+
+    const response = await worker.fetch(new Request('https://example.com/'), mockEnv, mockCtx);
+
+    const csp = response.headers.get('Content-Security-Policy');
+    expect(csp).toBeTruthy();
+    expect(csp).toMatch(/script-src 'self' 'nonce-[A-Za-z0-9+/=]+'/);
+  });
+
+  it('applies nonce-based CSP to 404 responses', async () => {
+    const worker = createHandler({
+      app: () => mockApp(),
+      basePath: '/api',
+      securityHeaders: true,
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/some-page'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(response.status).toBe(404);
+    const csp = response.headers.get('Content-Security-Policy');
+    expect(csp).toBeTruthy();
+    expect(csp).toMatch(/script-src 'self' 'nonce-[A-Za-z0-9+/=]+'/);
+  });
+
+  it('applies nonce-based CSP to 500 error responses', async () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const worker = createHandler({
+      app: () => mockApp(vi.fn().mockRejectedValue(new Error('fail'))),
+      basePath: '/api',
+      securityHeaders: true,
+    });
+
+    const response = await worker.fetch(
+      new Request('https://example.com/api/test'),
+      mockEnv,
+      mockCtx,
+    );
+
+    expect(response.status).toBe(500);
+    const csp = response.headers.get('Content-Security-Policy');
+    expect(csp).toMatch(/script-src 'self' 'nonce-[A-Za-z0-9+/=]+'/);
+
+    consoleErrorSpy.mockRestore();
+  });
+});
+
+describe('generateHTMLTemplate with nonce', () => {
+  it('adds nonce attribute to script tag when nonce is provided', () => {
+    const html = generateHTMLTemplate('/assets/client.js', 'My App', 'abc123');
+
+    expect(html).toContain('<script type="module" src="/assets/client.js" nonce="abc123"></script>');
+  });
+
+  it('omits nonce attribute when nonce is not provided', () => {
+    const html = generateHTMLTemplate('/assets/client.js', 'My App');
+
+    expect(html).toContain('<script type="module" src="/assets/client.js"></script>');
+    expect(html).not.toContain('nonce');
+  });
+});

package/vitest.config.ts

@@ -15,7 +15,7 @@ export default defineConfig({
       reporter: ['text', 'json-summary', 'json'],
       provider: 'v8',
       include: ['src/**/*.ts'],
-      exclude: ['src/**/*.test.ts', 'src/index.ts'],
+      exclude: ['src/**/*.test.ts', 'src/**/*.test-d.ts', 'src/index.ts'],
     },
   },
 });