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

package/src/__tests__/runtime/define-middleware.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { defineMiddleware } from '../../runtime/composables/define-middleware.js'
+import type { MiddlewareFn } from '../../types/middleware.js'
+
+describe('defineMiddleware', () => {
+  it('returns the function passed to it unchanged', () => {
+    const fn: MiddlewareFn = async () => true
+    expect(defineMiddleware(fn)).toBe(fn)
+  })
+
+  it('the returned function returns true to allow navigation', async () => {
+    const mw = defineMiddleware(async () => true)
+    const result = await mw({} as never, null)
+    expect(result).toBe(true)
+  })
+
+  it('the returned function returns false to block navigation', async () => {
+    const mw = defineMiddleware(async () => false)
+    const result = await mw({} as never, null)
+    expect(result).toBe(false)
+  })
+
+  it('the returned function returns a string to redirect', async () => {
+    const mw = defineMiddleware(async () => '/login')
+    const result = await mw({} as never, null)
+    expect(result).toBe('/login')
+  })
+
+  it('the returned function receives to and from route states', async () => {
+    let capturedTo: unknown
+    let capturedFrom: unknown
+    const mw = defineMiddleware((to, from) => {
+      capturedTo = to
+      capturedFrom = from
+      return true
+    })
+    const to = { path: '/dashboard', params: {}, query: {} }
+    const from = { path: '/login', params: {}, query: {} }
+    await mw(to as never, from as never)
+    expect(capturedTo).toBe(to)
+    expect(capturedFrom).toBe(from)
+  })
+})

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 { useRuntimeConfig, initRuntimeConfig, resolvePrivateConfig } from '../../runtime/composables/use-runtime-config.js'
 
 beforeEach(() => {
   // Reset global state between tests
@@ -56,4 +56,65 @@ 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')
+  })
 })

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,
@@ -70,6 +71,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)
 
@@ -329,7 +337,10 @@ 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')
               createReadStream(assetPath).pipe(res)

package/src/index.ts

@@ -7,7 +7,7 @@ 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'
 
 // 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']
 
 /**
  * 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('')

package/src/plugin/index.ts

@@ -94,6 +94,7 @@ export function resolveConfig(userConfig: CerAppConfig, root: string = process.c
     },
     runtimeConfig: {
       public: userConfig.runtimeConfig?.public ?? {},
+      private: userConfig.runtimeConfig?.private ?? {},
     },
   }
 }
@@ -104,6 +105,7 @@ export function resolveConfig(userConfig: CerAppConfig, root: string = process.c
 async function generateVirtualModule(
   id: string,
   config: ResolvedCerConfig,
+  ssr = false,
 ): Promise<string | null> {
   switch (id) {
     case RESOLVED_IDS.routes:
@@ -123,7 +125,7 @@ async function generateVirtualModule(
     case RESOLVED_IDS.serverMiddleware:
       return generateServerMiddlewareCode(config.serverMiddlewareDir)
     case RESOLVED_IDS.appConfig:
-      return generateAppConfigModule(config)
+      return generateAppConfigModule(config, ssr)
     case RESOLVED_IDS.loading:
       return generateLoadingCode(config.srcDir)
     case RESOLVED_IDS.error:
@@ -135,21 +137,29 @@ async function generateVirtualModule(
 
 /**
  * Generates a virtual module that exports the resolved app config.
+ * When `ssr` is true, also exports `_runtimePrivateDefaults` (server-only).
+ * The client bundle never receives private keys.
  */
-function generateAppConfigModule(config: ResolvedCerConfig): string {
+function generateAppConfigModule(config: ResolvedCerConfig, ssr = false): string {
   const exportedConfig = {
     mode: config.mode,
     router: config.router,
     ssg: config.ssg,
   }
   const publicConfig = config.runtimeConfig.public
-  return (
+  let code =
     `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\n` +
     `export const appConfig = ${JSON.stringify(exportedConfig, null, 2)}\n` +
     `export default appConfig\n` +
     `\n` +
     `export const runtimeConfig = { public: ${JSON.stringify(publicConfig, null, 2)} }\n`
-  )
+
+  if (ssr) {
+    const privateDefaults = config.runtimeConfig.private
+    code += `\nexport const _runtimePrivateDefaults = ${JSON.stringify(privateDefaults, null, 2)}\n`
+  }
+
+  return code
 }
 
 /**
@@ -245,21 +255,26 @@ export function cerApp(userConfig: CerAppConfig = {}): Plugin[] {
       }
     },
 
-    async load(id: string) {
+    async load(id: string, options?: { ssr?: boolean }) {
       if (id === RESOLVED_APP_ENTRY) return APP_ENTRY_TEMPLATE
 
       const allResolved = Object.values(RESOLVED_IDS) as string[]
       if (!allResolved.includes(id)) return null
 
+      const ssr = options?.ssr ?? false
+      // For virtual:cer-app-config the SSR and client variants differ (private
+      // defaults are only included in the SSR bundle), so use separate cache keys.
+      const cacheKey = id === RESOLVED_IDS.appConfig ? `${id}:${ssr ? 'ssr' : 'client'}` : id
+
       // Return from cache if available
-      if (moduleCache.has(id)) {
-        return moduleCache.get(id)!
+      if (moduleCache.has(cacheKey)) {
+        return moduleCache.get(cacheKey)!
       }
 
       // Generate and cache
-      const code = await generateVirtualModule(id, config)
+      const code = await generateVirtualModule(id, config, ssr)
       if (code !== null) {
-        moduleCache.set(id, code)
+        moduleCache.set(cacheKey, code)
         return code
       }
 
@@ -364,11 +379,17 @@ export function cerApp(userConfig: CerAppConfig = {}): Plugin[] {
       composableExports = await scanComposableExports(config.composablesDir)
       await writeAutoImportDts(config.root, config.composablesDir, composableExports)
       writeTsconfigPaths(config.root, config.srcDir)
-      // Warm the virtual module cache
+      // Warm the virtual module cache.
+      // virtual:cer-app-config is cached under separate :client/:ssr keys (SSR
+      // build omits _runtimePrivateDefaults from the client variant), so use the
+      // correct key suffix here so load() hits the cache instead of regenerating.
       for (const resolvedId of Object.values(RESOLVED_IDS)) {
         const code = await generateVirtualModule(resolvedId, config)
         if (code !== null) {
-          moduleCache.set(resolvedId, code)
+          const cacheKey = resolvedId === RESOLVED_IDS.appConfig
+            ? `${resolvedId}:client`
+            : resolvedId
+          moduleCache.set(cacheKey, code)
         }
       }
     },

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

@@ -11,9 +11,9 @@ const RUNTIME_IMPORTS = `import { component, html, css, ref, computed, watch, wa
 
 const DIRECTIVE_IMPORTS = `import { when, each, match, anchorBlock } from '@jasonshimmy/custom-elements-runtime/directives';`
 
-const FRAMEWORK_IMPORTS = `import { useHead, usePageData, useInject, useRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables';`
+const FRAMEWORK_IMPORTS = `import { useHead, usePageData, useInject, useRuntimeConfig, defineMiddleware } from '@jasonshimmy/vite-plugin-cer-app/composables';`
 
-const FRAMEWORK_IDENTIFIERS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig']
+const FRAMEWORK_IDENTIFIERS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig', 'defineMiddleware']
 
 const RUNTIME_IDENTIFIERS = [
   'component',
@@ -63,12 +63,13 @@ export function autoImportTransform(
   const normalizedId = normalize(id)
   const srcDir = normalize(opts.srcDir)
 
-  // Transform files inside app/pages/, app/layouts/, app/components/,
+  // Transform files inside app/pages/, app/layouts/, app/components/, app/middleware/
   // AND special convention files directly in app/ (loading.ts, error.ts, etc.)
   const isSubDir =
     normalizedId.startsWith(srcDir + '/pages/') ||
     normalizedId.startsWith(srcDir + '/layouts/') ||
-    normalizedId.startsWith(srcDir + '/components/')
+    normalizedId.startsWith(srcDir + '/components/') ||
+    normalizedId.startsWith(srcDir + '/middleware/')
   // Files directly in srcDir root (e.g. app/loading.ts, app/error.ts)
   const isRootConventionFile =
     normalizedId.startsWith(srcDir + '/') &&

package/src/plugin/virtual/routes.ts

@@ -256,7 +256,13 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
       `      for (const name of ${mwLiteral}) {\n` +
       `        const handler = middleware[name]\n` +
       `        if (typeof handler !== 'function') continue\n` +
-      `        const result = await new Promise((resolve) => handler(to, from, resolve))\n` +
+      `        let result\n` +
+      `        try {\n` +
+      `          result = await handler(to, from)\n` +
+      `        } catch (err) {\n` +
+      `          console.error('[cer-app] Middleware "' + name + '" threw an error:', err)\n` +
+      `          return false\n` +
+      `        }\n` +
       `        if (typeof result === 'string') return result\n` +
       `        if (result === false) return false\n` +
       `      }\n` +

package/src/runtime/composables/define-middleware.ts

@@ -0,0 +1,17 @@
+import type { MiddlewareFn } from '../../types/middleware.js'
+
+/**
+ * Identity helper that gives TypeScript the correct `MiddlewareFn` type
+ * without any runtime cost.
+ *
+ * @example
+ * // app/middleware/auth.ts
+ * export default defineMiddleware(async (to, from) => {
+ *   const isLoggedIn = checkSession()
+ *   if (!isLoggedIn) return '/login'   // redirect
+ *   return true                         // allow
+ * })
+ */
+export function defineMiddleware(fn: MiddlewareFn): MiddlewareFn {
+  return fn
+}

package/src/runtime/composables/index.ts

@@ -2,4 +2,6 @@ export { useHead, beginHeadCollection, endHeadCollection, serializeHeadTags } fr
 export type { HeadInput } from './use-head.js'
 export { usePageData } from './use-page-data.js'
 export { useInject } from './use-inject.js'
-export { useRuntimeConfig, initRuntimeConfig } from './use-runtime-config.js'
+export { useRuntimeConfig, initRuntimeConfig, resolvePrivateConfig } from './use-runtime-config.js'
+export type { RuntimeConfigResult, RuntimeConfigPublic, RuntimeConfigPrivate } from './use-runtime-config.js'
+export { defineMiddleware } from './define-middleware.js'

package/src/runtime/composables/use-runtime-config.ts

@@ -1,29 +1,42 @@
+export interface RuntimeConfigPublic {
+  [key: string]: unknown
+}
+
+export interface RuntimeConfigPrivate {
+  [key: string]: string
+}
+
+export interface RuntimeConfigResult {
+  public: RuntimeConfigPublic
+  private?: RuntimeConfigPrivate
+}
+
 /**
- * Returns the public runtime configuration set in `cer.config.ts` under
- * `runtimeConfig.public`. Available on both server and client.
+ * Returns the runtime configuration set in `cer.config.ts`.
  *
- * Values are baked in at build time from `virtual:cer-app-config`, so only
- * static/env-var values should be placed here. For truly dynamic config,
- * use a loader or API route.
+ * - `public` — available on both server and client.
+ * - `private` — available on the server only (resolved from `process.env` at
+ *   startup). Never present on the client.
  *
  * @example
  * // cer.config.ts
  * export default defineConfig({
  *   runtimeConfig: {
  *     public: { apiBase: process.env.VITE_API_BASE ?? '/api' },
+ *     private: { dbUrl: '', secretKey: '' },
  *   },
  * })
  *
- * // app/pages/index.ts
- * const config = useRuntimeConfig()
- * fetch(config.public.apiBase + '/posts')
+ * // app/pages/index.ts (loader — server-only)
+ * const { private: priv } = useRuntimeConfig()
+ * const rows = await db.query(priv.dbUrl)
  */
-export function useRuntimeConfig(): { public: Record<string, unknown> } {
+export function useRuntimeConfig(): RuntimeConfigResult {
   // Dynamic import resolved at runtime — avoids a static circular dependency
   // between the composable and the virtual module.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const mod = (globalThis as any).__cerRuntimeConfig
-  if (mod) return mod as { public: Record<string, unknown> }
+  if (mod) return mod as RuntimeConfigResult
 
   // Fallback: empty config (e.g. in test environments without the virtual module).
   return { public: {} }
@@ -34,7 +47,40 @@ export function useRuntimeConfig(): { public: Record<string, unknown> } {
  * globalThis so useRuntimeConfig() can access it synchronously in any context
  * (component render, composable, server handler).
  */
-export function initRuntimeConfig(config: { public: Record<string, unknown> }): void {
+export function initRuntimeConfig(config: RuntimeConfigResult): void {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ;(globalThis as any).__cerRuntimeConfig = config
 }
+
+/**
+ * Converts a camelCase or mixed key to UPPER_SNAKE_CASE for env var lookup.
+ * Examples: `dbUrl` → `DB_URL`, `secretKey` → `SECRET_KEY`, `API_KEY` → `API_KEY`.
+ */
+function toUpperSnakeCase(key: string): string {
+  return key
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .toUpperCase()
+}
+
+/**
+ * Resolves a private config object by looking up each key in the supplied
+ * environment variable map, with the following precedence:
+ *
+ * 1. `env[key]`                   — exact case (e.g. `process.env.dbUrl`)
+ * 2. `env[UPPER_SNAKE_CASE(key)]` — conventional env var form (e.g. `process.env.DB_URL`)
+ * 3. `defaultValue`               — the declared default from `cer.config.ts`
+ *
+ * Accepts an optional `env` parameter so the function is unit-testable
+ * without mutating `process.env`.
+ */
+export function resolvePrivateConfig(
+  defaults: Record<string, string>,
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(defaults).map(([key, defaultValue]) => [
+      key,
+      env[key] ?? env[toUpperSnakeCase(key)] ?? defaultValue,
+    ]),
+  )
+}

package/src/runtime/entry-server-template.ts

@@ -21,17 +21,21 @@ import routes from 'virtual:cer-routes'
 import layouts from 'virtual:cer-layouts'
 import plugins from 'virtual:cer-plugins'
 import apiRoutes from 'virtual:cer-server-api'
-import { runtimeConfig } from 'virtual:cer-app-config'
+import { runtimeConfig, _runtimePrivateDefaults } from 'virtual:cer-app-config'
 import { registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'
 import { registerEntityMap, renderToStreamWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'
 import entitiesJson from '@jasonshimmy/custom-elements-runtime/entities.json'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
-import { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
+import { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig, resolvePrivateConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
 import { errorTag } from 'virtual:cer-error'
 import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
 
 registerBuiltinComponents()
-initRuntimeConfig(runtimeConfig)
+
+// Resolve private config from environment variables at server startup.
+// Each key declared in runtimeConfig.private is looked up in process.env,
+// first as-is, then as ALL_CAPS. The declared default is used as fallback.
+initRuntimeConfig({ ...runtimeConfig, private: resolvePrivateConfig(_runtimePrivateDefaults ?? {}) })
 
 // Pre-load the full HTML entity map so named entities like — decode
 // correctly during SSR. Without this the bundled runtime falls back to a

package/src/types/config.ts

@@ -22,6 +22,10 @@ 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
@@ -36,6 +40,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 {

package/src/types/index.ts

@@ -1,6 +1,6 @@
-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'

package/src/types/middleware.ts

@@ -1,13 +1,15 @@
 import type { RouteState } from '@jasonshimmy/custom-elements-runtime/router'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
-export type NextFunction = (redirectTo?: string) => 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 RouteMiddleware = (
-  to: RouteState,
-  from: RouteState | null,
-  next: NextFunction,
-) => void | Promise<void>
+export type MiddlewareFn = (to: RouteState, from: RouteState | null) => GuardResult
 
 export type ServerMiddleware = (
   req: IncomingMessage,