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

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/cookie.cy.ts

@@ -0,0 +1,68 @@
+/**
+ * useCookie() e2e tests — verifies isomorphic cookie read/write/remove
+ * works correctly in all rendering modes.
+ *
+ * Client-side path: set/remove via document.cookie.
+ * SSR path: reads from req.headers.cookie on initial request.
+ */
+
+const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
+
+// Helper: find an element inside the page-cookie-test shadow DOM (post-hydration).
+const cookiePage = () =>
+  cy.get('cer-layout-view').shadow().find('page-cookie-test').shadow()
+
+describe('useCookie() — client-side read/write/remove', () => {
+  beforeEach(() => {
+    cy.clearCookies()
+  })
+
+  it('shows "not set" when the cookie is absent', () => {
+    cy.visit('/cookie-test')
+    cookiePage().find('[data-cy=cookie-value]').should('contain', 'not set')
+  })
+
+  it('reads a cookie set via cy.setCookie()', () => {
+    cy.setCookie('ks-test-cookie', 'cypress-value')
+    cy.visit('/cookie-test')
+    cookiePage().find('[data-cy=cookie-value]').should('contain', 'cypress-value')
+  })
+
+  it('sets the cookie when the set button is clicked', () => {
+    cy.visit('/cookie-test')
+    cookiePage().find('[data-cy=set-cookie]').click({ force: true })
+    // After reload the SSR-rendered light DOM shows the new value
+    cy.get('[data-cy=cookie-value]').should('contain', 'hello-from-cer-app')
+    cy.getCookie('ks-test-cookie').should('have.property', 'value', 'hello-from-cer-app')
+  })
+
+  it('removes the cookie when the remove button is clicked', () => {
+    cy.setCookie('ks-test-cookie', 'to-remove')
+    cy.visit('/cookie-test')
+    cookiePage().find('[data-cy=cookie-value]').should('contain', 'to-remove')
+    cookiePage().find('[data-cy=remove-cookie]').click({ force: true })
+    // After reload the SSR-rendered light DOM shows "not set"
+    cy.get('[data-cy=cookie-value]').should('contain', 'not set')
+  })
+})
+
+if (mode === 'ssr') {
+  describe('useCookie() — server-side read (SSR)', () => {
+    it('reads the cookie from the request and renders its value', () => {
+      cy.setCookie('ks-test-cookie', 'ssr-cookie-value')
+      cy.visit('/cookie-test')
+      // The SSR-rendered HTML should include the cookie value server-side
+      cy.get('[data-cy=cookie-value]').should('contain', 'ssr-cookie-value')
+    })
+
+    it('initial HTML contains the cookie value when cookie is sent with the request', () => {
+      cy.setCookie('ks-test-cookie', 'in-html')
+      cy.request({
+        url: '/cookie-test',
+        headers: { Cookie: 'ks-test-cookie=in-html' },
+      }).then((response) => {
+        expect(response.body).to.include('in-html')
+      })
+    })
+  })
+}

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/cypress/e2e/preview-hardening.cy.ts

@@ -0,0 +1,79 @@
+/**
+ * Preview server hardening e2e tests — verifies security headers,
+ * Cache-Control values, and graceful shutdown behaviour.
+ *
+ * Security headers and Cache-Control are server-level concerns, so these
+ * tests only run in SSR and SSG modes (both use `cer-app preview`).
+ * SPA mode also runs through the preview server, so the tests apply there too.
+ */
+
+describe('Preview server — security headers', () => {
+  it('responds with X-Content-Type-Options: nosniff', () => {
+    cy.request('/').then((response) => {
+      expect(response.headers['x-content-type-options']).to.eq('nosniff')
+    })
+  })
+
+  it('responds with X-Frame-Options: DENY', () => {
+    cy.request('/').then((response) => {
+      expect(response.headers['x-frame-options']).to.eq('DENY')
+    })
+  })
+
+  it('responds with Referrer-Policy: strict-origin-when-cross-origin', () => {
+    cy.request('/').then((response) => {
+      expect(response.headers['referrer-policy']).to.eq('strict-origin-when-cross-origin')
+    })
+  })
+
+  it('includes security headers on 404 responses', () => {
+    cy.request({ url: '/definitely-not-a-real-page-xyz', failOnStatusCode: false }).then((response) => {
+      expect(response.headers['x-content-type-options']).to.eq('nosniff')
+    })
+  })
+})
+
+describe('Preview server — path traversal protection', () => {
+  // HTTP clients (including Cypress/got) normalize `..` segments before sending,
+  // so a raw traversal like `/../../../../etc/passwd` arrives at the server as
+  // `/etc/passwd`. The `isPathBounded` guard is exercised via unit tests
+  // (src/__tests__/cli/preview-isr.test.ts). Here we verify the observable
+  // guarantee: files that do not exist inside dist/ are never served.
+  it('does not serve a file that does not exist inside dist/', () => {
+    cy.request({ url: '/etc/passwd', failOnStatusCode: false }).then((response) => {
+      // Either 404 (static) or 200 (SSR SPA fallback) — never a served file from
+      // outside the dist directory. Critically, the response body must NOT contain
+      // typical /etc/passwd content.
+      expect(response.body).not.to.include('root:x:')
+      expect(response.body).not.to.include('/bin/bash')
+    })
+  })
+
+  // NOTE: HTTP clients (including Cypress/got) normalize `..` segments before
+  // sending, so raw traversal sequences never arrive at the server unchanged.
+  // The isPathBounded() guard is exhaustively covered at the unit level in
+  // src/__tests__/cli/preview-isr.test.ts. No additional e2e assertion is needed.
+})
+
+describe('Preview server — Cache-Control', () => {
+  it('serves HTML with Cache-Control: no-cache', () => {
+    cy.request('/').then((response) => {
+      expect(response.headers['cache-control']).to.include('no-cache')
+    })
+  })
+
+  it('serves content-hashed assets with immutable Cache-Control', () => {
+    // Get the page to discover an actual asset URL (Vite hashes asset filenames)
+    cy.request('/').then((htmlResponse) => {
+      const assetMatch = htmlResponse.body.match(/\/assets\/[^"'\s]+\.js/)
+      if (!assetMatch) return  // no JS asset found in this page, skip
+
+      const assetUrl = assetMatch[0]
+      cy.request(assetUrl).then((assetResponse) => {
+        const cc = assetResponse.headers['cache-control'] as string
+        expect(cc).to.include('max-age=31536000')
+        expect(cc).to.include('immutable')
+      })
+    })
+  })
+})

package/e2e/cypress/e2e/seo-meta.cy.ts

@@ -0,0 +1,108 @@
+/**
+ * useSeoMeta() e2e tests — verifies Open Graph, Twitter Card, canonical, and
+ * title/description tags are injected correctly in all modes.
+ *
+ * In SSR/SSG: tags must be present in the initial server-rendered HTML.
+ * In all modes: tags must be present after client hydration.
+ */
+
+const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
+
+describe('useSeoMeta() — title and description', () => {
+  it('sets document title', () => {
+    cy.visit('/seo-test')
+    cy.title().should('eq', 'SEO Test — Kitchen Sink')
+  })
+
+  it('sets meta description', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[name="description"]').should('have.attr', 'content', 'A test page for useSeoMeta().')
+  })
+})
+
+describe('useSeoMeta() — Open Graph tags', () => {
+  it('sets og:title', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[property="og:title"]').should('have.attr', 'content', 'SEO Test OG Title')
+  })
+
+  it('sets og:description', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[property="og:description"]').should('have.attr', 'content', 'SEO Test OG description.')
+  })
+
+  it('sets og:image', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[property="og:image"]').should('have.attr', 'content', 'https://example.com/og/seo-test.png')
+  })
+
+  it('sets og:url', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[property="og:url"]').should('have.attr', 'content', 'https://example.com/seo-test')
+  })
+
+  it('sets og:type', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[property="og:type"]').should('have.attr', 'content', 'website')
+  })
+
+  it('sets og:site_name', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[property="og:site_name"]').should('have.attr', 'content', 'Kitchen Sink')
+  })
+})
+
+describe('useSeoMeta() — Twitter Card tags', () => {
+  it('sets twitter:card', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[name="twitter:card"]').should('have.attr', 'content', 'summary_large_image')
+  })
+
+  it('sets twitter:title', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[name="twitter:title"]').should('have.attr', 'content', 'SEO Test Twitter Title')
+  })
+
+  it('sets twitter:site', () => {
+    cy.visit('/seo-test')
+    cy.get('meta[name="twitter:site"]').should('have.attr', 'content', '@ks')
+  })
+})
+
+describe('useSeoMeta() — canonical link', () => {
+  it('sets canonical link element', () => {
+    cy.visit('/seo-test')
+    cy.get('link[rel="canonical"]').should('have.attr', 'href', 'https://example.com/seo-test')
+  })
+})
+
+if (mode !== 'spa') {
+  describe('useSeoMeta() — server-side injection (SSR/SSG)', () => {
+    it('title is in the initial HTML', () => {
+      cy.request('/seo-test').then((response) => {
+        expect(response.body).to.include('<title>SEO Test — Kitchen Sink</title>')
+      })
+    })
+
+    it('og:title meta is in the initial HTML', () => {
+      cy.request('/seo-test').then((response) => {
+        expect(response.body).to.include('og:title')
+        expect(response.body).to.include('SEO Test OG Title')
+      })
+    })
+
+    it('twitter:card meta is in the initial HTML', () => {
+      cy.request('/seo-test').then((response) => {
+        expect(response.body).to.include('twitter:card')
+        expect(response.body).to.include('summary_large_image')
+      })
+    })
+
+    it('canonical link is in the initial HTML', () => {
+      cy.request('/seo-test').then((response) => {
+        expect(response.body).to.include('canonical')
+        expect(response.body).to.include('https://example.com/seo-test')
+      })
+    })
+  })
+}

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/e2e/kitchen-sink/app/pages/cookie-test.ts

@@ -0,0 +1,22 @@
+component('page-cookie-test', () => {
+  const testCookie = useCookie('ks-test-cookie')
+
+  function setCookie() {
+    testCookie.set('hello-from-cer-app')
+    window.location.reload()
+  }
+
+  function removeCookie() {
+    testCookie.remove()
+    window.location.reload()
+  }
+
+  return html`
+    <div>
+      <h1 data-cy="cookie-test-heading">Cookie Test</h1>
+      <p data-cy="cookie-value">Value: ${testCookie.value ?? 'not set'}</p>
+      <button data-cy="set-cookie" @click="${setCookie}">Set cookie</button>
+      <button data-cy="remove-cookie" @click="${removeCookie}">Remove cookie</button>
+    </div>
+  `
+})

package/e2e/kitchen-sink/app/pages/seo-test.ts

@@ -0,0 +1,23 @@
+component('page-seo-test', () => {
+  useSeoMeta({
+    title: 'SEO Test — Kitchen Sink',
+    description: 'A test page for useSeoMeta().',
+    ogTitle: 'SEO Test OG Title',
+    ogDescription: 'SEO Test OG description.',
+    ogImage: 'https://example.com/og/seo-test.png',
+    ogUrl: 'https://example.com/seo-test',
+    ogType: 'website',
+    ogSiteName: 'Kitchen Sink',
+    twitterCard: 'summary_large_image',
+    twitterTitle: 'SEO Test Twitter Title',
+    twitterSite: '@ks',
+    canonical: 'https://example.com/seo-test',
+  })
+
+  return html`
+    <div>
+      <h1 data-cy="seo-test-heading">SEO Test</h1>
+      <p data-cy="seo-test-description">This page sets SEO tags via <code>useSeoMeta()</code>.</p>
+    </div>
+  `
+})

package/package.json

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