@jasonshimmy/vite-plugin-cer-app 0.7.0 → 0.8.0

package/dist/types/config.d.ts

@@ -17,6 +17,9 @@ export interface AutoImportsConfig {
 export interface RuntimePublicConfig {
     [key: string]: unknown;
 }
+export interface RuntimePrivateConfig {
+    [key: string]: string;
+}
 export interface RuntimeConfig {
     /**
      * Public runtime config — available on both server and client via
@@ -31,6 +34,17 @@ export interface RuntimeConfig {
      * }
      */
     public?: RuntimePublicConfig;
+    /**
+     * Server-only secrets — never serialized into the client bundle.
+     * Declare keys with empty-string defaults here; at server startup each key
+     * is resolved from `process.env[KEY]` (case-insensitive, ALL_CAPS preferred).
+     *
+     * @example
+     * runtimeConfig: {
+     *   private: { dbUrl: '', secretKey: '' },
+     * }
+     */
+    private?: RuntimePrivateConfig;
 }
 export interface CerAppConfig {
     mode?: 'spa' | 'ssr' | 'ssg';

package/dist/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAA;AAE/E,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,CAAC,CAAA;IACxD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAA;AAE/E,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAA;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,CAAC,CAAA;IACxD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D"}

package/dist/types/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAwDA,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAuEA,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
-export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig, RuntimeConfig, RuntimePublicConfig } from './config.js';
+export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig, RuntimeConfig, RuntimePublicConfig, RuntimePrivateConfig } from './config.js';
 export { defineConfig } from './config.js';
 export type { HydrateStrategy, SsgPathsContext, PageSsgConfig, PageMeta, PageLoaderContext, PageLoader } from './page.js';
 export type { ApiRequest, ApiResponse, ApiHandler, ApiContext } from './api.js';
 export type { AppContext, AppPlugin } from './plugin.js';
-export type { NextFunction, RouteMiddleware, ServerMiddleware } from './middleware.js';
+export type { MiddlewareFn, GuardResult, ServerMiddleware } from './middleware.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC/H,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACzH,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC/E,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACrJ,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACzH,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC/E,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/types/middleware.d.ts

@@ -1,6 +1,12 @@
 import type { RouteState } from '@jasonshimmy/custom-elements-runtime/router';
 import type { IncomingMessage, ServerResponse } from 'node:http';
-export type NextFunction = (redirectTo?: string) => void;
-export type RouteMiddleware = (to: RouteState, from: RouteState | null, next: NextFunction) => void | Promise<void>;
+/**
+ * Return value from a route middleware function:
+ * - `true`   — allow navigation
+ * - `false`  — block navigation
+ * - `string` — redirect to that path
+ */
+export type GuardResult = boolean | string | Promise<boolean | string>;
+export type MiddlewareFn = (to: RouteState, from: RouteState | null) => GuardResult;
 export type ServerMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void | Promise<void>;
 //# sourceMappingURL=middleware.d.ts.map

package/dist/types/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/types/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6CAA6C,CAAA;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,MAAM,MAAM,YAAY,GAAG,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;AAExD,MAAM,MAAM,eAAe,GAAG,CAC5B,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,UAAU,GAAG,IAAI,EACvB,IAAI,EAAE,YAAY,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEzB,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,IAAI,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/types/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6CAA6C,CAAA;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAAA;AAEtE,MAAM,MAAM,YAAY,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,KAAK,WAAW,CAAA;AAEnF,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,IAAI,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA"}

package/docs/cli.md

@@ -110,6 +110,7 @@ cer-app preview --port 8080
 - Static assets from `dist/client/` are served first; HTML requests fall through to the SSR handler
 - Otherwise, starts a static file server with SPA fallback (serves `index.html` for unknown paths)
 - Returns 404 for paths not found in `dist/` (static mode only)
+- **Path traversal protection:** all file requests are validated against the `dist/` root — requests attempting to escape it (e.g. `GET /../../../../etc/passwd`) receive a `400` response
 
 ---
 

package/docs/composables.md

@@ -144,7 +144,9 @@ import { useInject } from '@jasonshimmy/vite-plugin-cer-app/composables'
 
 ### `useRuntimeConfig()`
 
-Returns the `public` runtime configuration object set in `cer.config.ts` under `runtimeConfig.public`. Available in all rendering modes (SPA, SSR, SSG) and on both server and client.
+Returns the runtime configuration set in `cer.config.ts`. Returns `{ public, private? }`:
+- `public` — available everywhere (server and client)
+- `private` — server-only secrets resolved from `process.env` at startup; `undefined` on the client
 
 ```ts
 // cer.config.ts
@@ -152,28 +154,51 @@ export default defineConfig({
   runtimeConfig: {
     public: {
       apiBase: process.env.VITE_API_BASE ?? '/api',
-      featureFlags: { darkMode: true },
+    },
+    private: {
+      dbUrl: '',       // resolved from process.env.DB_URL at server startup
     },
   },
 })
 ```
 
 ```ts
-// app/pages/index.ts — auto-imported, no import statement needed
+// app/pages/index.ts — public config, works on client and server
 component('page-index', () => {
   const { public: cfg } = useRuntimeConfig()
-  // cfg.apiBase → '/api'
-
   return html`<p>API base: ${cfg.apiBase}</p>`
 })
 ```
 
-The config is initialized at app boot (both client and server) by calling `initRuntimeConfig(runtimeConfig)` with the value from `virtual:cer-app-config`. You only need `useRuntimeConfig()` to read it.
+```ts
+// app/pages/data.ts — private config, server-only (loader)
+export const loader = async () => {
+  const { private: priv } = useRuntimeConfig()
+  const rows = await db.query(priv!.dbUrl)
+  return { rows }
+}
+```
 
-**Only use `runtimeConfig.public` for values safe to expose to the browser.** Secrets, tokens, and private keys must stay in server-only code (loaders, API handlers, server middleware).
+**Only use `runtimeConfig.public` for values safe to expose to the browser.** Use `runtimeConfig.private` for secrets — they are never sent to the client.
 
 If you need it outside auto-imported directories:
 
 ```ts
 import { useRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
 ```
+
+---
+
+### `defineMiddleware(fn)`
+
+Identity helper that gives TypeScript the correct `MiddlewareFn` type. Auto-imported — no import needed in `app/middleware/` files.
+
+```ts
+// app/middleware/auth.ts
+export default defineMiddleware(async (to, from) => {
+  const isLoggedIn = !!localStorage.getItem('token')
+  return isLoggedIn ? true : '/login'
+})
+```
+
+See [Middleware](./middleware.md) for full documentation.

package/docs/configuration.md

@@ -210,7 +210,7 @@ Set any flag to `false` to opt out and manage imports manually.
 
 ## `runtimeConfig` options
 
-Expose typed, centralized public configuration to both server and client code via `useRuntimeConfig()`.
+Expose typed, centralized configuration to your app. Public values are available everywhere; private values are server-only secrets resolved from environment variables at startup.
 
 ```ts
 export default defineConfig({
@@ -219,6 +219,10 @@ export default defineConfig({
       apiBase: process.env.VITE_API_BASE ?? 'https://api.example.com',
       appVersion: '1.0.0',
     },
+    private: {
+      dbUrl: '',         // resolved from process.env.DB_URL at server startup
+      secretKey: '',     // resolved from process.env.SECRET_KEY at server startup
+    },
   },
 })
 ```
@@ -230,9 +234,9 @@ export default defineConfig({
 
 Values placed here are serialized into `virtual:cer-app-config` at build time and accessible on both server and client via `useRuntimeConfig().public`.
 
-> **Security:** Only put values here that are safe to expose to the browser. Do not put secrets, tokens, or private keys in `public`. Those should be read directly from `process.env` inside server-only code (loaders, server middleware, API handlers).
+> **Security:** Only put values here that are safe to expose to the browser. Do not put secrets, tokens, or private keys in `public`.
 
-> **Serialization:** Values must be JSON-serializable (strings, numbers, booleans, plain objects, arrays). Functions, class instances, `undefined`, and circular references are not supported and will be lost or throw during the build.
+> **Serialization:** Values must be JSON-serializable (strings, numbers, booleans, plain objects, arrays). Functions, class instances, `undefined`, and circular references are not supported.
 
 ```ts
 // Any page, layout, component, or composable
@@ -252,6 +256,52 @@ import type { RuntimePublicConfig } from '@jasonshimmy/vite-plugin-cer-app/types
 
 ---
 
+### `runtimeConfig.private`
+
+**Type:** `Record<string, string>`
+**Default:** `{}`
+
+Server-only secrets. Declare keys with empty-string defaults in `cer.config.ts` for typing purposes. **Private values are never included in the client bundle.**
+
+**Environment variable resolution order** (at server startup, for each declared key):
+
+1. `process.env[key]` — exact case (e.g. `process.env.dbUrl`)
+2. `process.env[UPPER_SNAKE_CASE(key)]` — conventional env var form (e.g. `process.env.DB_URL`)
+3. The declared default value — used as a last-resort fallback
+
+camelCase keys are automatically converted: `dbUrl` → `DB_URL`, `secretKey` → `SECRET_KEY`.
+
+```ts
+// cer.config.ts
+export default defineConfig({
+  runtimeConfig: {
+    private: {
+      dbUrl: '',       // resolved from process.env.dbUrl or process.env.DB_URL
+      secretKey: '',   // resolved from process.env.secretKey or process.env.SECRET_KEY
+    },
+  },
+})
+```
+
+```ts
+// app/pages/data.ts — loader (server-only)
+export const loader = async () => {
+  const { private: priv } = useRuntimeConfig()
+  const rows = await db.query(priv!.dbUrl)
+  return { rows }
+}
+```
+
+> `useRuntimeConfig().private` is `undefined` on the client. Only access it in server-only contexts (loaders, server middleware, API handlers).
+
+**TypeScript:** Import `RuntimePrivateConfig` to type your private config:
+
+```ts
+import type { RuntimePrivateConfig } from '@jasonshimmy/vite-plugin-cer-app/types'
+```
+
+---
+
 ## Passing config to the Vite plugin directly
 
 When using `vite.config.ts` instead of (or alongside) `cer.config.ts`:

package/docs/middleware.md

@@ -9,39 +9,35 @@ The framework has two kinds of middleware:
 
 ## Route middleware
 
-### Defining global middleware
+### Defining middleware
 
-Create a file in `app/middleware/`. It runs before every route navigation:
+Create a file in `app/middleware/`. Export a default `MiddlewareFn` using `defineMiddleware`:
 
 ```ts
 // app/middleware/auth.ts
-import type { RouteMiddleware } from '@jasonshimmy/vite-plugin-cer-app/types'
-
-const auth: RouteMiddleware = async (to, from, next) => {
+export default defineMiddleware(async (to, from) => {
   const session = await getSession()
-  if (!session) {
-    next('/login')   // redirect
-  } else {
-    next()           // allow navigation
-  }
-}
-
-export default auth
+  if (!session) return '/login'  // redirect
+  return true                    // allow navigation
+})
 ```
 
-### `RouteMiddleware` signature
+`defineMiddleware` is a no-op identity helper — it just provides TypeScript types without
+any runtime overhead. It is auto-imported, so you don't need to import it manually.
+
+### `MiddlewareFn` signature
 
 ```ts
-type NextFunction = (redirectTo?: string) => void
+type GuardResult = boolean | string | Promise<boolean | string>
 
-type RouteMiddleware = (
-  to: Route,
-  from: Route | null,
-  next: NextFunction,
-) => void | Promise<void>
+type MiddlewareFn = (to: RouteState, from: RouteState | null) => GuardResult
 ```
 
-Call `next()` to allow navigation, or `next('/path')` to redirect.
+| Return value | Effect |
+|---|---|
+| `true` | Allow navigation |
+| `false` | Block navigation (stay on current route) |
+| `string` | Redirect to that path |
 
 ---
 
@@ -56,28 +52,60 @@ export const meta = {
 }
 ```
 
-Named middleware runs in addition to any global middleware.
-
 ---
 
 ### Multiple middleware
 
+Middleware runs in the order listed. The first non-`true` result wins:
+
 ```ts
 // app/pages/admin.ts
 export const meta = {
   middleware: ['auth', 'admin-role'],
-  // Runs: auth → admin-role → page
+  // Runs: auth → admin-role → page render
 }
 ```
 
 ---
 
+### Execution order within a navigation
+
+1. `beforeEnter` fires on the matched route — runs all declared middleware in order
+2. Route state updates (component renders)
+3. `afterEnter` fires (analytics, logging)
+
+Redirect loop protection: the router stops after 10 consecutive redirects.
+
+---
+
+### Error handling
+
+If a middleware function throws (synchronously or asynchronously), navigation is **blocked** — the framework catches the error, logs it, and returns `false` to keep the user on the current route:
+
+```
+[cer-app] Middleware "auth" threw an error: Error: session store unavailable
+```
+
+This means a crashing middleware is always safe: the user stays put rather than landing on a broken page or being incorrectly redirected. Subsequent middleware in the same chain does not run.
+
+---
+
+### TypeScript types
+
+`MiddlewareFn` and `GuardResult` are exported from the package if you need them outside of auto-imported files:
+
+```ts
+import type { MiddlewareFn, GuardResult } from '@jasonshimmy/vite-plugin-cer-app/types'
+```
+
+---
+
 ### All middleware files
 
 All files in `app/middleware/` are registered and available by name. They are exported from `virtual:cer-middleware`:
 
 ```ts
-import middleware from 'virtual:cer-middleware'
+import { middleware } from 'virtual:cer-middleware'
 // { auth: [Function], 'admin-role': [Function], ... }
 ```
 

package/e2e/cypress/e2e/middleware.cy.ts

@@ -0,0 +1,45 @@
+/**
+ * E2E tests for client-side route middleware (navigation guards).
+ *
+ * The kitchen-sink app ships an `auth` middleware that redirects unauthenticated
+ * users to /login. The /protected page declares `meta: { middleware: ['auth'] }`.
+ */
+
+describe('Route middleware', () => {
+  beforeEach(() => {
+    // Ensure no stale auth token from a previous test
+    cy.clearLocalStorage()
+  })
+
+  context('unauthenticated navigation', () => {
+    it('redirects to /login when visiting /protected without a token', () => {
+      cy.visit('/protected')
+      cy.url().should('include', '/login')
+    })
+
+    it('shows the login page after redirect', () => {
+      cy.visit('/protected')
+      cy.get('[data-cy=login-heading]').should('contain', 'Login')
+    })
+  })
+
+  context('authenticated navigation', () => {
+    beforeEach(() => {
+      cy.visit('/')
+      cy.window().then((win) => {
+        win.localStorage.setItem('ks-token', '1')
+      })
+    })
+
+    it('allows navigation to /protected when a token is present', () => {
+      cy.visit('/protected')
+      cy.url().should('include', '/protected')
+      cy.get('[data-cy=protected-heading]').should('contain', 'Protected')
+    })
+
+    it('renders the protected page content', () => {
+      cy.visit('/protected')
+      cy.get('[data-cy=protected-note]').should('exist')
+    })
+  })
+})

package/e2e/kitchen-sink/app/middleware/auth.ts

@@ -1,13 +1,9 @@
 // Route middleware — redirects to /login if not authenticated.
 // Set localStorage.setItem('ks-token', '1') to simulate login.
-export default (to: any, _from: any, next: (path?: string) => void) => {
+export default defineMiddleware((_to, _from) => {
   const isLoggedIn = typeof localStorage !== 'undefined'
     ? !!localStorage.getItem('ks-token')
     : false
 
-  if (!isLoggedIn) {
-    next('/login')
-  } else {
-    next()
-  }
-}
+  return isLoggedIn ? true : '/login'
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonshimmy/vite-plugin-cer-app",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Nuxt-style meta-framework for @jasonshimmy/custom-elements-runtime",
   "type": "module",
   "keywords": [

package/src/__tests__/cli/preview-isr.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from 'vitest'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import {
+  isPathBounded,
   matchRoutePattern,
   findRevalidate,
   findRenderMode,
@@ -9,6 +10,35 @@ import {
   type IsrCacheEntry,
 } from '../../cli/commands/preview-isr.js'
 
+// ─── isPathBounded ────────────────────────────────────────────────────────────
+
+describe('isPathBounded', () => {
+  it('allows normal file paths inside the root', () => {
+    expect(isPathBounded('/dist', '/index.html')).toBe(true)
+  })
+
+  it('allows nested paths inside the root', () => {
+    expect(isPathBounded('/dist', '/assets/app.js')).toBe(true)
+  })
+
+  it('allows the root path itself', () => {
+    expect(isPathBounded('/dist', '/')).toBe(true)
+  })
+
+  it('blocks simple path traversal (../ escape)', () => {
+    expect(isPathBounded('/dist', '/../../../../etc/passwd')).toBe(false)
+  })
+
+  it('blocks a path that escapes by one level', () => {
+    expect(isPathBounded('/dist', '/../secret')).toBe(false)
+  })
+
+  it('does not confuse a sibling directory for the root', () => {
+    // /dist-other starts with /dist but is NOT inside /dist
+    expect(isPathBounded('/dist', '/../dist-other/file')).toBe(false)
+  })
+})
+
 // ─── matchRoutePattern ────────────────────────────────────────────────────────
 
 describe('matchRoutePattern', () => {

package/src/__tests__/plugin/cer-app-plugin.test.ts

@@ -245,6 +245,36 @@ describe('cerApp plugin — load hook', () => {
     expect(result).toContain('appConfig')
     expect(result).toContain('ssg')
   })
+
+  it('excludes _runtimePrivateDefaults from the client bundle', async () => {
+    const plugin = getCerPlugin({ runtimeConfig: { private: { dbUrl: '', secretKey: '' } } })
+    plugin.config({ root: '/project' }, { command: 'serve', mode: 'development' })
+    plugin.configResolved(FAKE_RESOLVED)
+    // Client load (ssr: false / omitted)
+    const clientResult = await plugin.load('\0virtual:cer-app-config') as string
+    expect(clientResult).not.toContain('_runtimePrivateDefaults')
+    expect(clientResult).not.toContain('dbUrl')
+  })
+
+  it('includes _runtimePrivateDefaults in the SSR bundle', async () => {
+    const plugin = getCerPlugin({ runtimeConfig: { private: { dbUrl: '', secretKey: '' } } })
+    plugin.config({ root: '/project' }, { command: 'serve', mode: 'development' })
+    plugin.configResolved(FAKE_RESOLVED)
+    // SSR load (ssr: true)
+    const ssrResult = await plugin.load('\0virtual:cer-app-config', { ssr: true }) as string
+    expect(ssrResult).toContain('_runtimePrivateDefaults')
+    expect(ssrResult).toContain('dbUrl')
+  })
+
+  it('caches SSR and client virtual:cer-app-config separately', async () => {
+    const plugin = getCerPlugin({ runtimeConfig: { private: { token: '' } } })
+    plugin.config({ root: '/project' }, { command: 'serve', mode: 'development' })
+    plugin.configResolved(FAKE_RESOLVED)
+    const client = await plugin.load('\0virtual:cer-app-config') as string
+    const ssr = await plugin.load('\0virtual:cer-app-config', { ssr: true }) as string
+    expect(client).not.toContain('_runtimePrivateDefaults')
+    expect(ssr).toContain('_runtimePrivateDefaults')
+  })
 })
 
 describe('cerApp plugin — transform hook', () => {
@@ -363,6 +393,26 @@ describe('cerApp plugin — buildStart hook', () => {
     await plugin.buildStart()
     expect(writeTsconfigPaths).toHaveBeenCalledTimes(1)
   })
+
+  it('warms virtual:cer-app-config cache under :client key so load() hits it', async () => {
+    // After buildStart(), a subsequent client load (ssr: false) should be served
+    // from cache (generateAppConfigModule is not a public mock, so we verify by
+    // ensuring the load hook returns a non-null result without triggering the
+    // real generator — which is mocked at module level to a fixed string '// mock'
+    // for other modules; appConfig is not mocked, so it generates real code).
+    const plugin = getCerPlugin({ runtimeConfig: { private: { token: '' } } })
+    plugin.config({ root: '/project' }, { command: 'build', mode: 'production' })
+    plugin.configResolved(FAKE_RESOLVED)
+    await plugin.buildStart()
+
+    // Client load should return a result that does NOT include _runtimePrivateDefaults
+    const result = await plugin.load('\0virtual:cer-app-config') as string
+    expect(result).not.toContain('_runtimePrivateDefaults')
+
+    // SSR load (different cache key) should include _runtimePrivateDefaults
+    const ssrResult = await plugin.load('\0virtual:cer-app-config', { ssr: true }) as string
+    expect(ssrResult).toContain('_runtimePrivateDefaults')
+  })
 })
 
 describe('cerApp plugin — configureServer hook', () => {

package/src/__tests__/plugin/resolve-config.test.ts

@@ -155,4 +155,22 @@ describe('resolveConfig', () => {
     const cfg = resolveConfig({ runtimeConfig: { public: { foo: 42 } } }, ROOT)
     expect(cfg.runtimeConfig.public.foo).toBe(42)
   })
+
+  it('defaults runtimeConfig.private to an empty object', () => {
+    const cfg = resolveConfig({}, ROOT)
+    expect(cfg.runtimeConfig.private).toEqual({})
+  })
+
+  it('passes runtimeConfig.private values through', () => {
+    const cfg = resolveConfig({ runtimeConfig: { private: { dbUrl: '', secretKey: '' } } }, ROOT)
+    expect(cfg.runtimeConfig.private).toEqual({ dbUrl: '', secretKey: '' })
+  })
+
+  it('preserves both public and private when both are supplied', () => {
+    const cfg = resolveConfig({
+      runtimeConfig: { public: { apiBase: '/api' }, private: { token: '' } },
+    }, ROOT)
+    expect(cfg.runtimeConfig.public).toEqual({ apiBase: '/api' })
+    expect(cfg.runtimeConfig.private).toEqual({ token: '' })
+  })
 })

package/src/__tests__/plugin/transforms/auto-import.test.ts

@@ -55,6 +55,22 @@ describe('autoImportTransform — target directory gating', () => {
     )
     expect(result).not.toBeNull()
   })
+
+  it('transforms files in middleware/ (so defineMiddleware is auto-imported)', () => {
+    const result = autoImportTransform(
+      "export default defineMiddleware(() => true)",
+      '/project/app/middleware/auth.ts',
+      opts,
+    )
+    expect(result).not.toBeNull()
+    expect(result).toContain('defineMiddleware')
+  })
+
+  it('still returns null for composables/ (not in scope)', () => {
+    expect(
+      autoImportTransform("export default defineMiddleware(() => true)", '/project/app/composables/useTheme.ts', opts),
+    ).toBeNull()
+  })
 })
 
 // ─── No injection needed ─────────────────────────────────────────────────────

package/src/__tests__/plugin/virtual/middleware.test.ts

@@ -65,4 +65,19 @@ describe('generateMiddlewareCode', () => {
     expect(code).toContain('export const middleware')
     expect(code).toContain('export default middleware')
   })
+
+  it('prefixes identifier with underscore when filename starts with a digit', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${MIDDLEWARE}/2fa.ts`])
+    const code = await generateMiddlewareCode(MIDDLEWARE)
+    // Leading digit is not valid in a JS identifier — must be prefixed
+    expect(code).toContain('_m__2fa')
+    expect(code).toContain('"2fa"')
+  })
+
+  it('strips .js extension as well as .ts', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${MIDDLEWARE}/auth.js`])
+    const code = await generateMiddlewareCode(MIDDLEWARE)
+    expect(code).toContain('_m_auth')
+    expect(code).toContain('"auth": _m_auth')
+  })
 })

package/src/__tests__/plugin/virtual/routes.test.ts

@@ -129,6 +129,38 @@ describe('generateRoutesCode', () => {
     const code = await generateRoutesCode(PAGES)
     expect(code).not.toContain('beforeEnter')
   })
+
+  it('uses return-value API (await handler) not callback-style (new Promise)', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/dashboard.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `component('page-dashboard', () => html\`<div/>\`)\nexport const meta = { middleware: ['auth'] }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('await handler(to, from)')
+    expect(code).not.toContain('new Promise')
+  })
+
+  it('wraps handler call in try-catch (blocks navigation on error)', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/dashboard.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `component('page-dashboard', () => html\`<div/>\`)\nexport const meta = { middleware: ['auth'] }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('try {')
+    expect(code).toContain('} catch (err) {')
+    expect(code).toContain('return false')
+  })
+
+  it('logs the middleware name in the error message', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/dashboard.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `component('page-dashboard', () => html\`<div/>\`)\nexport const meta = { middleware: ['auth'] }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('console.error')
+    expect(code).toContain('Middleware')
+    expect(code).toContain('err)')
+  })
 })
 
 // ─── meta.layout ─────────────────────────────────────────────────────────────