@pyreon/zero 0.12.1 → 0.12.2

package/src/csp.ts

@@ -0,0 +1,207 @@
+/**
+ * Content Security Policy middleware.
+ *
+ * Generates a CSP header from a typed configuration object.
+ * Supports all CSP directives, nonces for inline scripts,
+ * and report-only mode for testing.
+ *
+ * @example
+ * ```ts
+ * import { cspMiddleware } from "@pyreon/zero"
+ *
+ * const csp = cspMiddleware({
+ *   directives: {
+ *     defaultSrc: ["'self'"],
+ *     scriptSrc: ["'self'", "'nonce'"],
+ *     styleSrc: ["'self'", "'unsafe-inline'"],
+ *     imgSrc: ["'self'", "data:", "https:"],
+ *     connectSrc: ["'self'", "https://api.example.com"],
+ *   },
+ *   reportOnly: false,
+ * })
+ * ```
+ */
+import type { Middleware, MiddlewareContext } from '@pyreon/server'
+import { useRequestLocals } from '@pyreon/server'
+
+/** Client-side fallback nonce (dev server, SPA). */
+let _clientNonce = ''
+
+/**
+ * Read the current CSP nonce in a component.
+ *
+ * SSR: reads from per-request `ctx.locals.cspNonce` via Pyreon's context
+ * system — fully isolated between concurrent requests via AsyncLocalStorage.
+ * Client/dev: falls back to module-level variable set by middleware.
+ *
+ * @example
+ * ```tsx
+ * import { useNonce } from "@pyreon/zero/csp"
+ *
+ * function InlineScript() {
+ *   const nonce = useNonce()
+ *   return <script nonce={nonce}>console.log("safe")</script>
+ * }
+ * ```
+ */
+export function useNonce(): string {
+  const locals = useRequestLocals()
+  if (locals.cspNonce) return locals.cspNonce as string
+  return _clientNonce
+}
+
+export interface CspDirectives {
+  defaultSrc?: string[]
+  scriptSrc?: string[]
+  styleSrc?: string[]
+  imgSrc?: string[]
+  fontSrc?: string[]
+  connectSrc?: string[]
+  mediaSrc?: string[]
+  objectSrc?: string[]
+  frameSrc?: string[]
+  childSrc?: string[]
+  workerSrc?: string[]
+  frameAncestors?: string[]
+  formAction?: string[]
+  baseUri?: string[]
+  manifestSrc?: string[]
+  /** Reporting endpoint URL. */
+  reportUri?: string
+  /** Reporting endpoint name (CSP Level 3). */
+  reportTo?: string
+  /** Upgrade insecure requests. */
+  upgradeInsecureRequests?: boolean
+  /** Block all mixed content. */
+  blockAllMixedContent?: boolean
+}
+
+export interface CspConfig {
+  /** CSP directives. */
+  directives: CspDirectives
+  /**
+   * Report-only mode — logs violations without blocking.
+   * Uses Content-Security-Policy-Report-Only header instead.
+   * Default: false
+   */
+  reportOnly?: boolean
+}
+
+const DIRECTIVE_MAP: Record<string, string> = {
+  defaultSrc: 'default-src',
+  scriptSrc: 'script-src',
+  styleSrc: 'style-src',
+  imgSrc: 'img-src',
+  fontSrc: 'font-src',
+  connectSrc: 'connect-src',
+  mediaSrc: 'media-src',
+  objectSrc: 'object-src',
+  frameSrc: 'frame-src',
+  childSrc: 'child-src',
+  workerSrc: 'worker-src',
+  frameAncestors: 'frame-ancestors',
+  formAction: 'form-action',
+  baseUri: 'base-uri',
+  manifestSrc: 'manifest-src',
+  reportUri: 'report-uri',
+  reportTo: 'report-to',
+}
+
+/**
+ * Build a CSP header string from directives.
+ * Exported for testing.
+ */
+export function buildCspHeader(directives: CspDirectives, nonce?: string): string {
+  const parts: string[] = []
+
+  for (const [key, cssProp] of Object.entries(DIRECTIVE_MAP)) {
+    const value = (directives as Record<string, unknown>)[key]
+    if (!value) continue
+
+    if (Array.isArray(value)) {
+      // Replace "'nonce'" placeholder with actual nonce
+      const resolved = nonce
+        ? value.map((v: string) => (v === "'nonce'" ? `'nonce-${nonce}'` : v))
+        : value.filter((v: string) => v !== "'nonce'")
+      parts.push(`${cssProp} ${resolved.join(' ')}`)
+    } else if (typeof value === 'string') {
+      parts.push(`${cssProp} ${value}`)
+    }
+  }
+
+  if (directives.upgradeInsecureRequests) {
+    parts.push('upgrade-insecure-requests')
+  }
+  if (directives.blockAllMixedContent) {
+    parts.push('block-all-mixed-content')
+  }
+
+  return parts.join('; ')
+}
+
+/**
+ * Generate a random nonce string (base64, 16 bytes).
+ */
+function generateNonce(): string {
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    const bytes = new Uint8Array(16)
+    crypto.getRandomValues(bytes)
+    // Convert to base64 using btoa
+    let binary = ''
+    for (const byte of bytes) binary += String.fromCharCode(byte)
+    return typeof btoa === 'function'
+      ? btoa(binary)
+      : Buffer.from(bytes).toString('base64')
+  }
+  // Fallback for environments without crypto
+  return Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2)
+}
+
+/**
+ * CSP middleware — sets Content-Security-Policy header.
+ *
+ * When directives contain `"'nonce'"`, a fresh nonce is generated per-request
+ * and attached to `ctx.locals.cspNonce` for use in inline script tags.
+ *
+ * @example
+ * ```ts
+ * // Apply to all routes
+ * export default defineConfig({
+ *   middleware: [
+ *     cspMiddleware({
+ *       directives: {
+ *         defaultSrc: ["'self'"],
+ *         scriptSrc: ["'self'", "'nonce'"],
+ *         styleSrc: ["'self'", "'unsafe-inline'"],
+ *         imgSrc: ["'self'", "data:", "https:"],
+ *       },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export function cspMiddleware(config: CspConfig): Middleware {
+  const headerName = config.reportOnly
+    ? 'Content-Security-Policy-Report-Only'
+    : 'Content-Security-Policy'
+
+  // Check if nonce is needed
+  const needsNonce = Object.values(config.directives).some(
+    (v) => Array.isArray(v) && v.includes("'nonce'"),
+  )
+
+  // Pre-build header for static case (no nonce)
+  const staticHeader = needsNonce ? null : buildCspHeader(config.directives)
+
+  return (ctx: MiddlewareContext) => {
+    if (staticHeader) {
+      _clientNonce = ''
+      ctx.headers.set(headerName, staticHeader)
+    } else {
+      const nonce = generateNonce()
+      _clientNonce = nonce
+      ;(ctx.locals as Record<string, unknown>).cspNonce = nonce
+      ctx.headers.set(headerName, buildCspHeader(config.directives, nonce))
+    }
+  }
+}

package/src/env.ts

@@ -0,0 +1,344 @@
+/**
+ * Environment variable validation.
+ *
+ * Infers types from default values — no verbose validator imports needed.
+ * Explicit validators (`url()`, `oneOf()`) available for special cases.
+ *
+ * @example
+ * ```ts
+ * import { validateEnv, url, oneOf } from "@pyreon/zero/env"
+ *
+ * const env = validateEnv({
+ *   PORT: 3000,                                // number, default 3000
+ *   DEBUG: false,                              // boolean, default false
+ *   HOST: "localhost",                         // string, default "localhost"
+ *   DATABASE_URL: url(),                       // validated URL, required
+ *   NODE_ENV: oneOf(["development", "production", "test"]),
+ *   API_KEY: String,                           // required string, no default
+ *   MAX_RETRIES: Number,                       // required number, no default
+ * })
+ * ```
+ */
+
+export interface EnvValidatorOptions<T = string> {
+  /** Whether this variable is required. Default: true */
+  required?: boolean
+  /** Default value when not set. Makes the variable optional. */
+  default?: T
+  /** Human-readable description for error messages. */
+  description?: string
+}
+
+export interface EnvValidator<T> {
+  __type: 'env-validator'
+  parse: (raw: string | undefined, key: string) => T
+  required: boolean
+  defaultValue?: T | undefined
+}
+
+// ─── Explicit validators (for special cases) ────────────────────────────────
+
+/**
+ * String validator — accepts any non-empty string.
+ */
+export function str(options?: EnvValidatorOptions<string>): EnvValidator<string> {
+  const required = options?.default === undefined && options?.required !== false
+  return {
+    __type: 'env-validator',
+    required,
+    defaultValue: options?.default,
+    parse(raw, key) {
+      if (raw === undefined || raw === '') {
+        if (options?.default !== undefined) return options.default
+        throw new EnvError(key, 'is required but not set', options?.description)
+      }
+      return raw
+    },
+  }
+}
+
+/**
+ * Number validator — parses to a number, rejects NaN.
+ */
+export function num(options?: EnvValidatorOptions<number>): EnvValidator<number> {
+  const required = options?.default === undefined && options?.required !== false
+  return {
+    __type: 'env-validator',
+    required,
+    defaultValue: options?.default,
+    parse(raw, key) {
+      if (raw === undefined || raw === '') {
+        if (options?.default !== undefined) return options.default
+        throw new EnvError(key, 'is required but not set', options?.description)
+      }
+      const n = Number(raw)
+      if (Number.isNaN(n)) {
+        throw new EnvError(key, `must be a number, got "${raw}"`, options?.description)
+      }
+      return n
+    },
+  }
+}
+
+/**
+ * Boolean validator — accepts "true"/"1" as true, "false"/"0" as false.
+ */
+export function bool(options?: EnvValidatorOptions<boolean>): EnvValidator<boolean> {
+  const required = options?.default === undefined && options?.required !== false
+  return {
+    __type: 'env-validator',
+    required,
+    defaultValue: options?.default,
+    parse(raw, key) {
+      if (raw === undefined || raw === '') {
+        if (options?.default !== undefined) return options.default
+        throw new EnvError(key, 'is required but not set', options?.description)
+      }
+      const lower = raw.toLowerCase()
+      if (lower === 'true' || lower === '1') return true
+      if (lower === 'false' || lower === '0') return false
+      throw new EnvError(key, `must be "true" or "false", got "${raw}"`, options?.description)
+    },
+  }
+}
+
+/**
+ * URL validator — validates that the value is a valid URL.
+ */
+export function url(options?: EnvValidatorOptions<string>): EnvValidator<string> {
+  const required = options?.default === undefined && options?.required !== false
+  return {
+    __type: 'env-validator',
+    required,
+    defaultValue: options?.default,
+    parse(raw, key) {
+      if (raw === undefined || raw === '') {
+        if (options?.default !== undefined) return options.default
+        throw new EnvError(key, 'is required but not set', options?.description)
+      }
+      try {
+        new URL(raw)
+        return raw
+      } catch {
+        throw new EnvError(key, `must be a valid URL, got "${raw}"`, options?.description)
+      }
+    },
+  }
+}
+
+/**
+ * Enum validator — value must be one of the allowed values.
+ */
+export function oneOf<T extends string>(
+  values: readonly T[],
+  options?: EnvValidatorOptions<T>,
+): EnvValidator<T> {
+  const required = options?.default === undefined && options?.required !== false
+  return {
+    __type: 'env-validator',
+    required,
+    defaultValue: options?.default,
+    parse(raw, key) {
+      if (raw === undefined || raw === '') {
+        if (options?.default !== undefined) return options.default
+        throw new EnvError(key, 'is required but not set', options?.description)
+      }
+      if (!values.includes(raw as T)) {
+        throw new EnvError(
+          key,
+          `must be one of [${values.join(', ')}], got "${raw}"`,
+          options?.description,
+        )
+      }
+      return raw as T
+    },
+  }
+}
+
+// ─── Internal helpers ───────────────────────────────────────────────────────
+
+class EnvError extends Error {
+  constructor(key: string, message: string, description?: string) {
+    const desc = description ? ` (${description})` : ''
+    super(`[zero:env] ${key}${desc}: ${message}`)
+    this.name = 'EnvError'
+  }
+}
+
+function isEnvValidator(v: unknown): v is EnvValidator<unknown> {
+  return typeof v === 'object' && v !== null && (v as any).__type === 'env-validator'
+}
+
+/**
+ * Convert a plain schema value to an EnvValidator.
+ *
+ * - `3000` → num({ default: 3000 })
+ * - `false` → bool({ default: false })
+ * - `"localhost"` → str({ default: "localhost" })
+ * - `String` → str() (required)
+ * - `Number` → num() (required)
+ * - `Boolean` → bool() (required)
+ * - EnvValidator → pass through
+ */
+function toValidator(value: unknown): EnvValidator<unknown> {
+  if (isEnvValidator(value)) return value
+
+  // Constructor markers → required, no default
+  if (value === String) return str()
+  if (value === Number) return num()
+  if (value === Boolean) return bool()
+
+  // Plain values → infer type + use as default
+  if (typeof value === 'number') return num({ default: value })
+  if (typeof value === 'boolean') return bool({ default: value })
+  if (typeof value === 'string') return str({ default: value })
+
+  throw new Error(`[zero:env] Invalid schema value: ${String(value)}. Use a default value, String/Number/Boolean, or a validator like url().`)
+}
+
+// ─── Type inference ─────────────────────────────────────────────────────────
+
+/** Schema entry: plain value, constructor, or explicit validator. */
+type SchemaEntry =
+  | string | number | boolean
+  | StringConstructor | NumberConstructor | BooleanConstructor
+  | EnvValidator<any>
+
+/** Infer the output type from a schema entry. */
+type InferEntry<T> =
+  T extends EnvValidator<infer V> ? V :
+  T extends StringConstructor ? string :
+  T extends NumberConstructor ? number :
+  T extends BooleanConstructor ? boolean :
+  T extends string ? string :
+  T extends number ? number :
+  T extends boolean ? boolean :
+  never
+
+type InferEnvSchema<T> = {
+  [K in keyof T]: InferEntry<T[K]>
+}
+
+// ─── Main API ───────────────────────────────────────────────────────────────
+
+/**
+ * Validate environment variables.
+ *
+ * Schema values can be:
+ * - **Default values**: `3000`, `false`, `"localhost"` → type inferred, used as default
+ * - **Constructors**: `String`, `Number`, `Boolean` → required, no default
+ * - **Validators**: `url()`, `oneOf([...])`, `str()`, `num()`, `bool()` → explicit validation
+ * - **Custom**: `schema(raw => z.coerce.number().parse(raw))` — bridge to any schema library
+ *
+ * @example
+ * ```ts
+ * import { validateEnv, url, oneOf } from "@pyreon/zero/env"
+ *
+ * const env = validateEnv({
+ *   PORT: 3000,                                // optional, default 3000
+ *   DATABASE_URL: url(),                       // required, validated URL
+ *   NODE_ENV: oneOf(["dev", "prod", "test"]),  // required, must be one of
+ *   API_KEY: String,                           // required string
+ *   DEBUG: false,                              // optional, default false
+ * })
+ * ```
+ */
+export function validateEnv<T extends Record<string, SchemaEntry>>(
+  schema: T,
+  source?: Record<string, string | undefined>,
+): InferEnvSchema<T> {
+  const env = source ?? (typeof process !== 'undefined' ? process.env : {})
+  const result: Record<string, unknown> = {}
+  const errors: string[] = []
+
+  for (const [key, entry] of Object.entries(schema)) {
+    const validator = toValidator(entry)
+    try {
+      result[key] = validator.parse(env[key], key)
+    } catch (e) {
+      errors.push((e as Error).message)
+    }
+  }
+
+  if (errors.length > 0) {
+    const header = `\n[zero:env] Environment validation failed (${errors.length} error${errors.length > 1 ? 's' : ''}):\n`
+    const body = errors.map((e) => `  ✗ ${e.replace('[zero:env] ', '')}`).join('\n')
+    throw new Error(header + body + '\n')
+  }
+
+  return result as InferEnvSchema<T>
+}
+
+// ─── Public env (client-safe) ────────────────────────────────────────────────
+
+/**
+ * Extract public environment variables (prefixed with `ZERO_PUBLIC_`).
+ *
+ * @example
+ * ```ts
+ * const pub = publicEnv()
+ * // → { API_URL: "https://...", APP_NAME: "MyApp" }
+ *
+ * const pub = publicEnv({ API_URL: url(), APP_NAME: "Default" })
+ * // → validated against ZERO_PUBLIC_API_URL, ZERO_PUBLIC_APP_NAME
+ * ```
+ */
+export function publicEnv(): Record<string, string>
+export function publicEnv<T extends Record<string, SchemaEntry>>(schema: T): InferEnvSchema<T>
+export function publicEnv(schema?: Record<string, SchemaEntry>): Record<string, unknown> {
+  const prefix = 'ZERO_PUBLIC_'
+  const env = typeof process !== 'undefined' ? process.env : {}
+
+  if (!schema) {
+    const result: Record<string, string> = {}
+    for (const [key, value] of Object.entries(env)) {
+      if (key.startsWith(prefix) && value !== undefined) {
+        result[key.slice(prefix.length)] = value
+      }
+    }
+    return result
+  }
+
+  const prefixedSource: Record<string, string | undefined> = {}
+  for (const key of Object.keys(schema)) {
+    prefixedSource[key] = env[`${prefix}${key}`]
+  }
+  return validateEnv(schema, prefixedSource)
+}
+
+// ─── Custom validator escape hatch ──────────────────────────────────────────
+
+/**
+ * Create an env validator from a custom parse function.
+ * Use this to integrate any schema library (Zod, Valibot, ArkType, etc.).
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod"
+ * import { validateEnv, schema } from "@pyreon/zero/env"
+ *
+ * const env = validateEnv({
+ *   PORT: schema(raw => z.coerce.number().parse(raw)),
+ *   DATABASE_URL: schema(raw => z.string().url().parse(raw)),
+ *   HOST: "localhost",  // plain defaults still work alongside
+ * })
+ * ```
+ */
+export function schema<T>(parse: (raw: string) => T): EnvValidator<T> {
+  return {
+    __type: 'env-validator',
+    required: true,
+    defaultValue: undefined,
+    parse(raw: string | undefined, key: string) {
+      if (raw === undefined || raw === '') {
+        throw new Error(`[zero:env] ${key}: is required but not set`)
+      }
+      try {
+        return parse(raw)
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e)
+        throw new Error(`[zero:env] ${key}: ${msg}`)
+      }
+    },
+  }
+}