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

package/src/__tests__/runtime/use-cookie.test.ts

@@ -0,0 +1,218 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { useCookie } from '../../runtime/composables/use-cookie.js'
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeReqRes(cookieHeader = ''): { req: IncomingMessage; res: ServerResponse } {
+  const req = { headers: { cookie: cookieHeader } } as unknown as IncomingMessage
+  const headers: Record<string, string | string[]> = {}
+  const res = {
+    getHeader: (name: string) => headers[name.toLowerCase()],
+    setHeader(name: string, value: string | string[]) { headers[name.toLowerCase()] = value },
+  } as unknown as ServerResponse
+  return { req, res }
+}
+
+// ─── SSR path ─────────────────────────────────────────────────────────────────
+
+describe('useCookie — SSR (via AsyncLocalStorage)', () => {
+  const store = new AsyncLocalStorage<{ req: IncomingMessage; res: ServerResponse }>()
+
+  beforeEach(() => {
+    ;(globalThis as Record<string, unknown>)['__CER_REQ_STORE__'] = store
+  })
+
+  afterEach(() => {
+    delete (globalThis as Record<string, unknown>)['__CER_REQ_STORE__']
+  })
+
+  it('reads a cookie from the request', () => {
+    const { req, res } = makeReqRes('token=abc123; other=xyz')
+    store.run({ req, res }, () => {
+      const cookie = useCookie('token')
+      expect(cookie.value).toBe('abc123')
+    })
+  })
+
+  it('returns undefined for a missing cookie', () => {
+    const { req, res } = makeReqRes('other=xyz')
+    store.run({ req, res }, () => {
+      const cookie = useCookie('missing')
+      expect(cookie.value).toBeUndefined()
+    })
+  })
+
+  it('writes a Set-Cookie header on set()', () => {
+    const { req, res } = makeReqRes()
+    store.run({ req, res }, () => {
+      useCookie('session').set('s1')
+    })
+    const header = res.getHeader('Set-Cookie') as string[]
+    expect(header).toBeDefined()
+    const value = Array.isArray(header) ? header[0] : header
+    expect(value).toContain('session=s1')
+    expect(value).toContain('Path=/')
+  })
+
+  it('appends to existing Set-Cookie headers', () => {
+    const { req, res } = makeReqRes()
+    store.run({ req, res }, () => {
+      useCookie('a').set('1')
+      useCookie('b').set('2')
+    })
+    const header = res.getHeader('Set-Cookie') as string[]
+    expect(Array.isArray(header)).toBe(true)
+    expect(header).toHaveLength(2)
+    expect(header[0]).toContain('a=1')
+    expect(header[1]).toContain('b=2')
+  })
+
+  it('writes Max-Age=0 on remove()', () => {
+    const { req, res } = makeReqRes('session=old')
+    store.run({ req, res }, () => {
+      useCookie('session').remove()
+    })
+    const header = res.getHeader('Set-Cookie') as string[]
+    const value = Array.isArray(header) ? header[0] : header
+    expect(value).toContain('Max-Age=0')
+  })
+
+  it('forwards options (httpOnly, secure, sameSite) when setting', () => {
+    const { req, res } = makeReqRes()
+    store.run({ req, res }, () => {
+      useCookie('auth').set('tok', { httpOnly: true, secure: true, sameSite: 'Strict' })
+    })
+    const header = res.getHeader('Set-Cookie') as string[]
+    const value = Array.isArray(header) ? header[0] : header
+    expect(value).toContain('HttpOnly')
+    expect(value).toContain('Secure')
+    expect(value).toContain('SameSite=Strict')
+  })
+
+  it('forwards options (maxAge, path, domain) when removing', () => {
+    const { req, res } = makeReqRes('auth=tok')
+    store.run({ req, res }, () => {
+      useCookie('auth').remove({ path: '/app', domain: 'example.com' })
+    })
+    const header = res.getHeader('Set-Cookie') as string[]
+    const value = Array.isArray(header) ? header[0] : header
+    expect(value).toContain('Max-Age=0')
+    expect(value).toContain('Path=/app')
+    expect(value).toContain('Domain=example.com')
+  })
+
+  it('decodes percent-encoded cookie values', () => {
+    const { req, res } = makeReqRes(`msg=${encodeURIComponent('hello world')}`)
+    store.run({ req, res }, () => {
+      const cookie = useCookie('msg')
+      expect(cookie.value).toBe('hello world')
+    })
+  })
+
+  it('round-trips values with special characters (spaces, slashes, unicode)', () => {
+    const specialValue = 'hello world/path?q=1&r=2 ✓'
+    const { req, res } = makeReqRes(`special=${encodeURIComponent(specialValue)}`)
+    store.run({ req, res }, () => {
+      const cookie = useCookie('special')
+      expect(cookie.value).toBe(specialValue)
+    })
+  })
+
+  it('encodes special characters in Set-Cookie when setting a value', () => {
+    const { req, res } = makeReqRes()
+    const specialValue = 'hello world/path?q=1'
+    store.run({ req, res }, () => {
+      useCookie('data').set(specialValue)
+    })
+    const header = res.getHeader('Set-Cookie') as string[]
+    const cookieStr = Array.isArray(header) ? header[0] : header
+    // Value must be percent-encoded in the Set-Cookie header
+    expect(cookieStr).toContain(encodeURIComponent(specialValue))
+    expect(cookieStr).not.toContain(specialValue)
+  })
+
+  it('survives a malformed cookie segment without throwing', () => {
+    // A segment with no '=' should be skipped gracefully
+    const { req, res } = makeReqRes('broken; valid=ok; =noname')
+    store.run({ req, res }, () => {
+      const cookie = useCookie('valid')
+      expect(cookie.value).toBe('ok')
+      expect(useCookie('broken').value).toBeUndefined()
+    })
+  })
+
+  it('returns undefined value outside a store context', () => {
+    // store is registered but no run() context — getStore() returns null
+    const cookie = useCookie('x')
+    expect(cookie.value).toBeUndefined()
+  })
+})
+
+// ─── Client path ──────────────────────────────────────────────────────────────
+
+describe('useCookie — client (document.cookie)', () => {
+  beforeEach(() => {
+    // Ensure no SSR store leaks into client tests
+    delete (globalThis as Record<string, unknown>)['__CER_REQ_STORE__']
+    // Clear document cookies
+    document.cookie.split(';').forEach((c) => {
+      const name = c.split('=')[0].trim()
+      if (name) document.cookie = `${name}=; Max-Age=0; Path=/`
+    })
+  })
+
+  it('reads a cookie set via document.cookie', () => {
+    document.cookie = 'theme=dark'
+    const cookie = useCookie('theme')
+    expect(cookie.value).toBe('dark')
+  })
+
+  it('returns undefined when the cookie is not set', () => {
+    const cookie = useCookie('nonexistent')
+    expect(cookie.value).toBeUndefined()
+  })
+
+  it('writes to document.cookie on set()', () => {
+    useCookie('lang').set('en')
+    const cookie = useCookie('lang')
+    expect(cookie.value).toBe('en')
+  })
+
+  it('removes a cookie on remove()', () => {
+    document.cookie = 'removeme=yes'
+    useCookie('removeme').remove()
+    const cookie = useCookie('removeme')
+    // After removal the cookie value should be empty or undefined
+    expect(cookie.value === undefined || cookie.value === '').toBe(true)
+  })
+
+  it('percent-encodes values with special characters', () => {
+    useCookie('data').set('hello world')
+    const raw = document.cookie
+    expect(raw).toContain('hello%20world')
+  })
+})
+
+// ─── Build-time / unknown context ─────────────────────────────────────────────
+
+describe('useCookie — unknown context (no store, no document)', () => {
+  it('returns undefined value and no-op set/remove when neither SSR nor client context is available', () => {
+    delete (globalThis as Record<string, unknown>)['__CER_REQ_STORE__']
+    // Simulate a non-browser, non-SSR context by verifying the composable
+    // falls through to the default branch (value === undefined, methods are no-ops).
+    // We can verify this by calling with a store that has no active context.
+    const store = new AsyncLocalStorage()
+    ;(globalThis as Record<string, unknown>)['__CER_REQ_STORE__'] = store
+    // getStore() returns null because we're outside a run() context
+    const cookie = useCookie('x')
+    expect(cookie.value).toBeUndefined()
+    expect(() => cookie.set('val')).not.toThrow()
+    expect(() => cookie.remove()).not.toThrow()
+    delete (globalThis as Record<string, unknown>)['__CER_REQ_STORE__']
+  })
+})

package/src/__tests__/runtime/use-runtime-config.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect, beforeEach } from 'vitest'
-import { useRuntimeConfig, initRuntimeConfig } from '../../runtime/composables/use-runtime-config.js'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useRuntimeConfig, initRuntimeConfig, resolvePrivateConfig } from '../../runtime/composables/use-runtime-config.js'
 
 beforeEach(() => {
   // Reset global state between tests
@@ -56,4 +56,88 @@ describe('useRuntimeConfig', () => {
     const config = useRuntimeConfig()
     expect(config.public).toEqual({})
   })
+
+  it('returns private config when initialized with it', () => {
+    initRuntimeConfig({ public: {}, private: { dbUrl: 'postgres://localhost', secretKey: 'abc' } })
+    const config = useRuntimeConfig()
+    expect(config.private).toEqual({ dbUrl: 'postgres://localhost', secretKey: 'abc' })
+  })
+
+  it('private is undefined when not supplied', () => {
+    initRuntimeConfig({ public: { apiBase: '/api' } })
+    const config = useRuntimeConfig()
+    expect(config.private).toBeUndefined()
+  })
+
+  it('returns empty private config when initialized with empty object', () => {
+    initRuntimeConfig({ public: {}, private: {} })
+    expect(useRuntimeConfig().private).toEqual({})
+  })
+})
+
+// ─── resolvePrivateConfig ─────────────────────────────────────────────────────
+
+describe('resolvePrivateConfig', () => {
+  it('resolves a key from the exact-case env var', () => {
+    const result = resolvePrivateConfig({ dbUrl: '' }, { dbUrl: 'postgres://localhost' })
+    expect(result.dbUrl).toBe('postgres://localhost')
+  })
+
+  it('resolves a key from the ALL_CAPS env var when exact case is absent', () => {
+    const result = resolvePrivateConfig({ dbUrl: '' }, { DB_URL: 'postgres://prod' })
+    expect(result.dbUrl).toBe('postgres://prod')
+  })
+
+  it('falls back to the declared default when neither env var is set', () => {
+    const result = resolvePrivateConfig({ dbUrl: 'default-db' }, {})
+    expect(result.dbUrl).toBe('default-db')
+  })
+
+  it('exact-case env var takes precedence over ALL_CAPS', () => {
+    const result = resolvePrivateConfig({ dbUrl: '' }, { dbUrl: 'exact', DB_URL: 'caps' })
+    expect(result.dbUrl).toBe('exact')
+  })
+
+  it('handles multiple keys independently', () => {
+    const result = resolvePrivateConfig(
+      { dbUrl: '', secretKey: '', apiToken: 'default-token' },
+      { dbUrl: 'pg://host', SECRET_KEY: 's3cr3t' },
+    )
+    expect(result.dbUrl).toBe('pg://host')
+    expect(result.secretKey).toBe('s3cr3t')
+    expect(result.apiToken).toBe('default-token')
+  })
+
+  it('returns an empty object when defaults is empty', () => {
+    expect(resolvePrivateConfig({}, { ANY: 'value' })).toEqual({})
+  })
+
+  it('preserves key names exactly as declared in output (does not rename keys)', () => {
+    const result = resolvePrivateConfig({ camelCase: 'def' }, { CAMEL_CASE: 'val' })
+    expect(Object.keys(result)).toEqual(['camelCase'])
+    expect(result.camelCase).toBe('val')
+  })
+
+  it('emits a console.warn when a key has an empty-string default and no env var is set', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    resolvePrivateConfig({ dbUrl: '' }, {})
+    expect(warn).toHaveBeenCalledOnce()
+    expect(warn.mock.calls[0][0]).toContain('dbUrl')
+    expect(warn.mock.calls[0][0]).toContain('DB_URL')
+    warn.mockRestore()
+  })
+
+  it('does NOT warn when the env var supplies a value for an empty-default key', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    resolvePrivateConfig({ dbUrl: '' }, { DB_URL: 'postgres://prod' })
+    expect(warn).not.toHaveBeenCalled()
+    warn.mockRestore()
+  })
+
+  it('does NOT warn when the declared default is non-empty and no env var is set', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    resolvePrivateConfig({ apiToken: 'fallback-token' }, {})
+    expect(warn).not.toHaveBeenCalled()
+    warn.mockRestore()
+  })
 })

package/src/__tests__/runtime/use-seo-meta.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, afterEach } from 'vitest'
+import { beginHeadCollection, endHeadCollection } from '../../runtime/composables/use-head.js'
+import { useSeoMeta } from '../../runtime/composables/use-seo-meta.js'
+
+// All tests run in SSR collection mode so we can inspect the output without a DOM.
+
+describe('useSeoMeta — SSR collection', () => {
+  afterEach(() => {
+    endHeadCollection()
+  })
+
+  it('sets the document title', () => {
+    beginHeadCollection()
+    useSeoMeta({ title: 'My Page' })
+    const [head] = endHeadCollection()
+    expect(head.title).toBe('My Page')
+  })
+
+  it('emits a description meta tag', () => {
+    beginHeadCollection()
+    useSeoMeta({ description: 'A great page.' })
+    const [head] = endHeadCollection()
+    expect(head.meta).toContainEqual({ name: 'description', content: 'A great page.' })
+  })
+
+  it('emits Open Graph meta tags', () => {
+    beginHeadCollection()
+    useSeoMeta({
+      ogTitle: 'OG Title',
+      ogDescription: 'OG Desc',
+      ogImage: 'https://example.com/og.png',
+      ogUrl: 'https://example.com/',
+      ogType: 'website',
+      ogSiteName: 'Example',
+    })
+    const [head] = endHeadCollection()
+    expect(head.meta).toContainEqual({ property: 'og:title', content: 'OG Title' })
+    expect(head.meta).toContainEqual({ property: 'og:description', content: 'OG Desc' })
+    expect(head.meta).toContainEqual({ property: 'og:image', content: 'https://example.com/og.png' })
+    expect(head.meta).toContainEqual({ property: 'og:url', content: 'https://example.com/' })
+    expect(head.meta).toContainEqual({ property: 'og:type', content: 'website' })
+    expect(head.meta).toContainEqual({ property: 'og:site_name', content: 'Example' })
+  })
+
+  it('emits Twitter Card meta tags', () => {
+    beginHeadCollection()
+    useSeoMeta({
+      twitterCard: 'summary_large_image',
+      twitterTitle: 'Tweet Title',
+      twitterDescription: 'Tweet Desc',
+      twitterImage: 'https://example.com/tw.png',
+      twitterSite: '@mysite',
+    })
+    const [head] = endHeadCollection()
+    expect(head.meta).toContainEqual({ name: 'twitter:card', content: 'summary_large_image' })
+    expect(head.meta).toContainEqual({ name: 'twitter:title', content: 'Tweet Title' })
+    expect(head.meta).toContainEqual({ name: 'twitter:description', content: 'Tweet Desc' })
+    expect(head.meta).toContainEqual({ name: 'twitter:image', content: 'https://example.com/tw.png' })
+    expect(head.meta).toContainEqual({ name: 'twitter:site', content: '@mysite' })
+  })
+
+  it('emits a canonical link element', () => {
+    beginHeadCollection()
+    useSeoMeta({ canonical: 'https://example.com/my-page' })
+    const [head] = endHeadCollection()
+    expect(head.link).toContainEqual({ rel: 'canonical', href: 'https://example.com/my-page' })
+  })
+
+  it('omits meta/link arrays when no tags are provided', () => {
+    beginHeadCollection()
+    useSeoMeta({ title: 'Only Title' })
+    const [head] = endHeadCollection()
+    expect(head.meta).toBeUndefined()
+    expect(head.link).toBeUndefined()
+  })
+
+  it('only emits tags for fields that are explicitly set', () => {
+    beginHeadCollection()
+    useSeoMeta({ ogTitle: 'Just OG' })
+    const [head] = endHeadCollection()
+    // description was not provided — must not appear
+    expect(head.meta?.some((m) => m.name === 'description')).toBeFalsy()
+    expect(head.meta).toContainEqual({ property: 'og:title', content: 'Just OG' })
+  })
+
+  it('allows all fields to be set together', () => {
+    beginHeadCollection()
+    useSeoMeta({
+      title: 'Full Page',
+      description: 'Full description.',
+      ogTitle: 'Full OG Title',
+      ogDescription: 'Full OG Desc',
+      ogImage: 'https://example.com/og.png',
+      ogUrl: 'https://example.com/',
+      ogType: 'article',
+      ogSiteName: 'My Site',
+      twitterCard: 'summary',
+      twitterTitle: 'Full Twitter Title',
+      twitterDescription: 'Full Twitter Desc',
+      twitterImage: 'https://example.com/tw.png',
+      twitterSite: '@site',
+      canonical: 'https://example.com/full',
+    })
+    const [head] = endHeadCollection()
+    expect(head.title).toBe('Full Page')
+    expect(head.meta).toHaveLength(12) // description + 6 OG + 5 Twitter
+    expect(head.link).toHaveLength(1)
+  })
+})

package/src/cli/commands/preview-isr.ts

@@ -5,6 +5,7 @@
  * from the HTTP server wiring in preview.ts.
  */
 
+import { resolve, join } from 'pathe'
 import { Readable } from 'node:stream'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
@@ -24,6 +25,19 @@ export type IsrCacheStatus = 'HIT' | 'STALE' | 'MISS'
 
 export type SsrHandlerFn = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
 
+// ─── Path traversal guard ─────────────────────────────────────────────────────
+
+/**
+ * Returns `true` when `urlPath` joined onto `rootDir` resolves to a path that
+ * is strictly inside (or equal to) `rootDir`. A traversal attempt such as
+ * `../../../../etc/passwd` would resolve outside `rootDir` and return `false`.
+ */
+export function isPathBounded(rootDir: string, urlPath: string): boolean {
+  const safeRoot = resolve(rootDir)
+  const resolved = resolve(join(rootDir, urlPath))
+  return resolved === safeRoot || resolved.startsWith(safeRoot + '/')
+}
+
 // ─── Route pattern matching ───────────────────────────────────────────────────
 
 /**

package/src/cli/commands/preview.ts

@@ -6,6 +6,7 @@ import { pathToFileURL } from 'node:url'
 import {
   type IsrCacheEntry,
   type SsrHandlerFn,
+  isPathBounded,
   findRevalidate,
   findRenderMode,
   renderForIsr,
@@ -59,6 +60,25 @@ function getMimeType(filePath: string): string {
   return MIME_TYPES[ext] ?? 'application/octet-stream'
 }
 
+/**
+ * Returns the appropriate Cache-Control header value for a file.
+ * Vite content-hashes assets placed in the /assets/ directory, so they
+ * can be cached indefinitely. Everything else (HTML, etc.) must not be cached.
+ */
+function getCacheControl(filePath: string): string {
+  if (filePath.includes('/assets/')) return 'public, max-age=31536000, immutable'
+  return 'no-cache'
+}
+
+/**
+ * Sets standard security headers on every response.
+ */
+function setSecurityHeaders(res: ServerResponse): void {
+  res.setHeader('X-Content-Type-Options', 'nosniff')
+  res.setHeader('X-Frame-Options', 'DENY')
+  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin')
+}
+
 /**
  * Serves a static file from the dist directory.
  * Returns true if the file was served, false otherwise.
@@ -70,6 +90,13 @@ function serveStaticFile(
 ): boolean {
   const urlPath = (req.url ?? '/').split('?')[0]
 
+  // Guard against path traversal: resolved path must stay within distDir.
+  if (!isPathBounded(distDir, urlPath)) {
+    res.statusCode = 400
+    res.end('Bad Request')
+    return true
+  }
+
   // Try exact file path
   let filePath = join(distDir, urlPath)
 
@@ -87,11 +114,36 @@ function serveStaticFile(
   }
 
   res.setHeader('Content-Type', getMimeType(filePath))
-  res.setHeader('Cache-Control', 'no-cache')
+  res.setHeader('Cache-Control', getCacheControl(filePath))
+  setSecurityHeaders(res)
   createReadStream(filePath).pipe(res)
   return true
 }
 
+/**
+ * Registers SIGTERM/SIGINT handlers that gracefully drain the server before exiting.
+ * Waits up to 10 seconds for in-flight requests to complete, then force-exits.
+ */
+function registerGracefulShutdown(server: ReturnType<typeof createHttpServer>): void {
+  function shutdown(signal: string): void {
+    console.log(`[cer-app] Received ${signal}, shutting down gracefully...`)
+    server.close(() => {
+      console.log('[cer-app] Server closed.')
+      process.exit(0)
+    })
+    // Force exit if connections haven't drained within 10 seconds.
+    const t = setTimeout(() => {
+      console.error('[cer-app] Forced shutdown after 10 s — connections did not drain.')
+      process.exit(1)
+    }, 10_000)
+    // Allow the Node.js event loop to exit before the timeout fires if all other work is done.
+    t.unref()
+  }
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'))
+  process.on('SIGINT', () => shutdown('SIGINT'))
+}
+
 export function previewCommand(): Command {
   return new Command('preview')
     .description('Preview the production build')
@@ -149,6 +201,11 @@ export function previewCommand(): Command {
         const isrCache = new Map<string, IsrCacheEntry>()
 
         const server = createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+          setSecurityHeaders(res)
+          // Default: HTML and API responses must not be cached. Asset paths below
+          // override this with getCacheControl() for content-hashed files.
+          res.setHeader('Cache-Control', 'no-cache')
+
           const url = req.url ?? '/'
           const urlPath = url.split('?')[0]
           const method = req.method ?? 'GET'
@@ -308,9 +365,16 @@ export function previewCommand(): Command {
           }
         })
 
+        // Protect against slow-send attacks: abort requests that stall during
+        // header delivery or that take too long to complete.
+        server.headersTimeout = 10_000   // 10 s to receive all request headers
+        server.requestTimeout = 30_000   // 30 s for the full request/response cycle
+
         server.listen(port, options.host, () => {
           console.log(`[cer-app] SSR preview running at http://${options.host}:${port}`)
         })
+
+        registerGracefulShutdown(server)
       } else {
         // Static file server (SPA / SSG)
         console.log('[cer-app] Starting static preview server...')
@@ -321,6 +385,9 @@ export function previewCommand(): Command {
         }
 
         const server = createHttpServer((req: IncomingMessage, res: ServerResponse) => {
+          setSecurityHeaders(res)
+          res.setHeader('Cache-Control', 'no-cache')
+
           const urlPath = (req.url ?? '/').split('?')[0]
           // SSG builds put assets in dist/client/ while HTML lives in dist/.
           // For requests with a non-HTML file extension, check dist/client/ first
@@ -329,9 +396,12 @@ export function previewCommand(): Command {
           const ext = extname(urlPath).toLowerCase()
           if (ext && ext !== '.html' && existsSync(clientDist)) {
             const assetPath = join(clientDist, urlPath)
-            if (existsSync(assetPath) && !statSync(assetPath).isDirectory()) {
+            if (
+              isPathBounded(clientDist, urlPath) &&
+              existsSync(assetPath) && !statSync(assetPath).isDirectory()
+            ) {
               res.setHeader('Content-Type', getMimeType(assetPath))
-              res.setHeader('Cache-Control', 'no-cache')
+              res.setHeader('Cache-Control', getCacheControl(assetPath))
               createReadStream(assetPath).pipe(res)
               return
             }
@@ -343,12 +413,14 @@ export function previewCommand(): Command {
           }
         })
 
+        server.headersTimeout = 10_000
+        server.requestTimeout = 30_000
+
         server.listen(port, options.host, () => {
           console.log(`[cer-app] Static preview running at http://${options.host}:${port}`)
         })
-      }
 
-      process.on('SIGTERM', () => process.exit(0))
-      process.on('SIGINT', () => process.exit(0))
+        registerGracefulShutdown(server)
+      }
     })
 }

package/src/index.ts

@@ -7,7 +7,9 @@ export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig } from '.
 export type { HydrateStrategy, SsgPathsContext, PageSsgConfig, PageMeta, PageLoaderContext, PageLoader } from './types/page.js'
 export type { ApiRequest, ApiResponse, ApiHandler, ApiContext } from './types/api.js'
 export type { AppContext, AppPlugin } from './types/plugin.js'
-export type { NextFunction, RouteMiddleware, ServerMiddleware } from './types/middleware.js'
+export type { MiddlewareFn, GuardResult, ServerMiddleware } from './types/middleware.js'
+export type { SeoMetaInput } from './runtime/composables/use-seo-meta.js'
+export type { CookieOptions, CookieRef } from './runtime/composables/use-cookie.js'
 
 // Re-export resolved config type for use in build scripts
 export type { ResolvedCerConfig } from './plugin/dev-server.js'

package/src/plugin/dev-server.ts

@@ -19,7 +19,7 @@ export interface ResolvedCerConfig {
   router: { base?: string; scrollToFragment?: boolean | object }
   jitCss: { content: string[]; extendedColors: boolean }
   autoImports: { components: boolean; composables: boolean; directives: boolean; runtime: boolean }
-  runtimeConfig: { public: Record<string, unknown> }
+  runtimeConfig: { public: Record<string, unknown>; private: Record<string, string> }
 }
 
 /**

package/src/plugin/dts-generator.ts

@@ -76,7 +76,7 @@ const RUNTIME_GLOBALS = [
 
 const DIRECTIVE_GLOBALS = ['when', 'each', 'match', 'anchorBlock']
 
-const FRAMEWORK_GLOBALS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig']
+const FRAMEWORK_GLOBALS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig', 'defineMiddleware', 'useSeoMeta', 'useCookie']
 
 /**
  * Scans a composables directory and returns a map of export name → file path.
@@ -214,9 +214,11 @@ export async function generateVirtualModuleDts(
   lines.push(`}`)
   lines.push('')
   lines.push(`declare module 'virtual:cer-app-config' {`)
-  lines.push(`  import type { RuntimePublicConfig } from '@jasonshimmy/vite-plugin-cer-app/types'`)
+  lines.push(`  import type { RuntimePublicConfig, RuntimePrivateConfig } from '@jasonshimmy/vite-plugin-cer-app/types'`)
   lines.push(`  export const appConfig: { mode: string; router: Record<string, unknown>; ssg: Record<string, unknown> }`)
   lines.push(`  export const runtimeConfig: { public: RuntimePublicConfig }`)
+  lines.push(`  /** Server-only — present only in the SSR bundle. Always \`undefined\` in the client bundle. */`)
+  lines.push(`  export const _runtimePrivateDefaults: RuntimePrivateConfig | undefined`)
   lines.push(`  export default appConfig`)
   lines.push(`}`)
   lines.push('')