gorsee 0.1.0

package/src/security/cors.ts

@@ -0,0 +1,80 @@
+// CORS middleware — configurable Cross-Origin Resource Sharing
+
+import type { MiddlewareFn } from "../server/middleware.ts"
+
+export interface CORSOptions {
+  origin?: string | string[] | ((origin: string) => boolean)
+  methods?: string[]
+  allowHeaders?: string[]
+  exposeHeaders?: string[]
+  credentials?: boolean
+  maxAge?: number
+}
+
+const DEFAULT_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"]
+const DEFAULT_HEADERS = ["Content-Type", "Authorization", "X-Requested-With"]
+
+function isOriginAllowed(origin: string, allowed: CORSOptions["origin"]): boolean {
+  if (!allowed) return false
+  if (allowed === "*") return true
+  if (typeof allowed === "string") return origin === allowed
+  if (Array.isArray(allowed)) return allowed.includes(origin)
+  if (typeof allowed === "function") return allowed(origin)
+  return false
+}
+
+export function cors(options: CORSOptions = {}): MiddlewareFn {
+  const {
+    origin = "*",
+    methods = DEFAULT_METHODS,
+    allowHeaders = DEFAULT_HEADERS,
+    exposeHeaders = [],
+    credentials = false,
+    maxAge = 86400,
+  } = options
+
+  return async (ctx, next) => {
+    const requestOrigin = ctx.request.headers.get("origin") ?? ""
+
+    // Preflight
+    if (ctx.request.method === "OPTIONS") {
+      const headers = new Headers()
+
+      if (origin === "*" && !credentials) {
+        headers.set("Access-Control-Allow-Origin", "*")
+      } else if (isOriginAllowed(requestOrigin, origin)) {
+        headers.set("Access-Control-Allow-Origin", requestOrigin)
+        headers.set("Vary", "Origin")
+      }
+
+      headers.set("Access-Control-Allow-Methods", methods.join(", "))
+      headers.set("Access-Control-Allow-Headers", allowHeaders.join(", "))
+      if (exposeHeaders.length > 0) {
+        headers.set("Access-Control-Expose-Headers", exposeHeaders.join(", "))
+      }
+      if (credentials) headers.set("Access-Control-Allow-Credentials", "true")
+      headers.set("Access-Control-Max-Age", String(maxAge))
+
+      return new Response(null, { status: 204, headers })
+    }
+
+    // Actual request
+    const response = await next()
+
+    if (origin === "*" && !credentials) {
+      response.headers.set("Access-Control-Allow-Origin", "*")
+    } else if (isOriginAllowed(requestOrigin, origin)) {
+      response.headers.set("Access-Control-Allow-Origin", requestOrigin)
+      response.headers.append("Vary", "Origin")
+    }
+
+    if (credentials) {
+      response.headers.set("Access-Control-Allow-Credentials", "true")
+    }
+    if (exposeHeaders.length > 0) {
+      response.headers.set("Access-Control-Expose-Headers", exposeHeaders.join(", "))
+    }
+
+    return response
+  }
+}

package/src/security/csrf.ts

@@ -0,0 +1,85 @@
+// CSRF protection using Signed Double-Submit Cookie pattern
+// Works for both SSR (token in HTML) and SPA (cookie-based)
+
+import { timingSafeEqual } from "node:crypto"
+
+const CSRF_COOKIE = "__gorsee_csrf"
+const CSRF_HEADER = "x-gorsee-csrf"
+const TOKEN_LENGTH = 32
+
+function randomBytes(length: number): string {
+  const bytes = new Uint8Array(length)
+  crypto.getRandomValues(bytes)
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")
+}
+
+async function hmacSign(token: string, secret: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  )
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(token)
+  )
+  return Array.from(new Uint8Array(sig), (b) => b.toString(16).padStart(2, "0")).join("")
+}
+
+export function generateCSRFToken(): string {
+  return randomBytes(TOKEN_LENGTH)
+}
+
+export async function validateCSRFToken(
+  request: Request,
+  secret: string
+): Promise<boolean> {
+  // Skip safe methods
+  if (["GET", "HEAD", "OPTIONS"].includes(request.method)) return true
+
+  const cookieHeader = request.headers.get("cookie") ?? ""
+  const headerToken = request.headers.get(CSRF_HEADER) ?? ""
+
+  // Parse cookie
+  let cookieToken = ""
+  for (const pair of cookieHeader.split(";")) {
+    const [key, ...rest] = pair.trim().split("=")
+    if (key === CSRF_COOKIE) {
+      cookieToken = rest.join("=")
+      break
+    }
+  }
+
+  if (!cookieToken || !headerToken) return false
+
+  // Verify: cookie contains "token.signature", header contains "token"
+  const [token, signature] = cookieToken.split(".")
+  if (!token || !signature) return false
+
+  // Header must match token part of cookie
+  if (headerToken !== token) return false
+
+  // Verify HMAC signature (timing-safe comparison)
+  const expectedSig = await hmacSign(token, secret)
+  if (signature.length !== expectedSig.length) return false
+  return timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSig))
+}
+
+export async function csrfProtection(secret: string): Promise<{
+  token: string
+  cookie: string
+  headerName: string
+}> {
+  const token = generateCSRFToken()
+  const signature = await hmacSign(token, secret)
+  const cookieValue = `${token}.${signature}`
+
+  return {
+    token,
+    cookie: `${CSRF_COOKIE}=${cookieValue}; Path=/; SameSite=Lax; Secure`,
+    headerName: CSRF_HEADER,
+  }
+}

package/src/security/headers.ts

@@ -0,0 +1,50 @@
+export interface SecurityConfig {
+  csp: boolean
+  hsts: boolean
+  csrf: boolean
+  rateLimit: { requests: number; window: string } | false
+  nonce?: string
+}
+
+const DEFAULT_CONFIG: SecurityConfig = {
+  csp: true,
+  hsts: true,
+  csrf: true,
+  rateLimit: { requests: 100, window: "1m" },
+}
+
+export function securityHeaders(
+  config: Partial<SecurityConfig> = {},
+  nonce?: string
+): Record<string, string> {
+  const cfg = { ...DEFAULT_CONFIG, ...config }
+  const headers: Record<string, string> = {}
+
+  if (cfg.csp) {
+    const scriptSrc = nonce ? `'nonce-${nonce}'` : "'self'"
+    headers["Content-Security-Policy"] = [
+      "default-src 'self'",
+      `script-src ${scriptSrc}`,
+      "style-src 'self' 'unsafe-inline'",
+      "img-src 'self' data: https:",
+      "font-src 'self'",
+      "connect-src 'self' ws: wss:",
+      "frame-ancestors 'none'",
+      "base-uri 'self'",
+      "form-action 'self'",
+    ].join("; ")
+  }
+
+  if (cfg.hsts) {
+    headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains; preload"
+  }
+
+  // Always set these
+  headers["X-Content-Type-Options"] = "nosniff"
+  headers["X-Frame-Options"] = "DENY"
+  headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+  headers["X-XSS-Protection"] = "0" // Modern browsers: CSP is better
+  headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()"
+
+  return headers
+}

package/src/security/index.ts

@@ -0,0 +1,4 @@
+export { securityHeaders, type SecurityConfig } from "./headers.ts"
+export { csrfProtection, generateCSRFToken, validateCSRFToken } from "./csrf.ts"
+export { createRateLimiter, type RateLimiter } from "./rate-limit.ts"
+export { cors, type CORSOptions } from "./cors.ts"

package/src/security/rate-limit.ts

@@ -0,0 +1,80 @@
+// In-memory token bucket rate limiter (for Bun runtime)
+// For Cloudflare Workers: use Durable Objects adapter (future)
+
+export interface RateLimiter {
+  check(key: string): { allowed: boolean; remaining: number; resetAt: number }
+  reset(key: string): void
+}
+
+interface Bucket {
+  tokens: number
+  lastRefill: number
+}
+
+function parseWindow(window: string): number {
+  const match = window.match(/^(\d+)(s|m|h)$/)
+  if (!match) throw new Error(`Invalid rate limit window: "${window}"`)
+  const value = Number(match[1])
+  switch (match[2]) {
+    case "s": return value * 1000
+    case "m": return value * 60_000
+    case "h": return value * 3_600_000
+    default: throw new Error(`Invalid unit: ${match[2]}`)
+  }
+}
+
+export function createRateLimiter(
+  maxRequests: number,
+  window: string
+): RateLimiter {
+  const windowMs = parseWindow(window)
+  const buckets = new Map<string, Bucket>()
+
+  // Cleanup old entries periodically
+  const CLEANUP_INTERVAL = Math.max(windowMs * 2, 60_000)
+  const cleanup = setInterval(() => {
+    const now = Date.now()
+    for (const [key, bucket] of buckets) {
+      if (now - bucket.lastRefill > windowMs * 2) {
+        buckets.delete(key)
+      }
+    }
+  }, CLEANUP_INTERVAL)
+
+  // Don't prevent process from exiting
+  if (typeof cleanup === "object" && "unref" in cleanup) {
+    (cleanup as NodeJS.Timeout).unref()
+  }
+
+  return {
+    check(key: string): { allowed: boolean; remaining: number; resetAt: number } {
+      const now = Date.now()
+      let bucket = buckets.get(key)
+
+      if (!bucket) {
+        bucket = { tokens: maxRequests, lastRefill: now }
+        buckets.set(key, bucket)
+      }
+
+      // Refill tokens based on elapsed time
+      const elapsed = now - bucket.lastRefill
+      if (elapsed >= windowMs) {
+        bucket.tokens = maxRequests
+        bucket.lastRefill = now
+      }
+
+      const resetAt = bucket.lastRefill + windowMs
+
+      if (bucket.tokens > 0) {
+        bucket.tokens--
+        return { allowed: true, remaining: bucket.tokens, resetAt }
+      }
+
+      return { allowed: false, remaining: 0, resetAt }
+    },
+
+    reset(key: string): void {
+      buckets.delete(key)
+    },
+  }
+}

package/src/server/action.ts

@@ -0,0 +1,48 @@
+// Server Actions -- form mutations with progressive enhancement
+// Usage in route:
+//   export const action = defineAction(async (ctx) => { ... })
+//
+// Client-side: submits via fetch, returns result
+// SSR: handles POST form submissions with redirect
+
+import type { Context } from "./middleware.ts"
+
+export type ActionFn<T = unknown> = (ctx: Context) => Promise<T | Response>
+
+export interface ActionResult<T = unknown> {
+  data?: T
+  error?: string
+  status: number
+}
+
+export function defineAction<T = unknown>(fn: ActionFn<T>): ActionFn<T> {
+  return fn
+}
+
+export async function handleAction<T>(
+  actionFn: ActionFn<T>,
+  ctx: Context,
+): Promise<ActionResult<T>> {
+  try {
+    const result = await actionFn(ctx)
+    if (result instanceof Response) {
+      return { status: result.status }
+    }
+    return { data: result, status: 200 }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return { error: message, status: 500 }
+  }
+}
+
+// Parse form data from request into a typed object
+export async function parseFormData(request: Request): Promise<Record<string, string>> {
+  const formData = await request.formData()
+  const result: Record<string, string> = {}
+  for (const [key, value] of formData.entries()) {
+    if (typeof value === "string") {
+      result[key] = value
+    }
+  }
+  return result
+}

package/src/server/cache.ts

@@ -0,0 +1,102 @@
+// Route-level response cache with stale-while-revalidate
+// Usage: export const cache = { maxAge: 60, staleWhileRevalidate: 300 }
+
+import type { MiddlewareFn } from "./middleware.ts"
+
+export interface CacheOptions {
+  maxAge: number               // fresh cache TTL in seconds
+  staleWhileRevalidate?: number // serve stale while revalidating (seconds)
+  vary?: string[]              // cache key varies by these headers
+  key?: (url: URL) => string   // custom cache key generator
+}
+
+interface CacheEntry {
+  body: string
+  headers: Record<string, string>
+  status: number
+  createdAt: number
+  revalidating?: boolean
+}
+
+const store = new Map<string, CacheEntry>()
+
+function buildKey(url: URL, vary: string[], request: Request, customKey?: (url: URL) => string): string {
+  const base = customKey ? customKey(url) : url.pathname + url.search
+  if (vary.length === 0) return base
+  const varyParts = vary.map((h) => `${h}=${request.headers.get(h) ?? ""}`).join("&")
+  return `${base}?__vary=${varyParts}`
+}
+
+export function routeCache(options: CacheOptions): MiddlewareFn {
+  const { maxAge, staleWhileRevalidate = 0, vary = [], key: customKey } = options
+
+  return async (ctx, next) => {
+    if (ctx.request.method !== "GET") return next()
+
+    const cacheKey = buildKey(ctx.url, vary, ctx.request, customKey)
+    const entry = store.get(cacheKey)
+    const now = Date.now()
+
+    if (entry) {
+      const age = (now - entry.createdAt) / 1000
+      // Fresh — serve from cache
+      if (age < maxAge) {
+        return new Response(entry.body, {
+          status: entry.status,
+          headers: { ...entry.headers, "X-Cache": "HIT", "Age": String(Math.floor(age)) },
+        })
+      }
+      // Stale but within revalidation window — serve stale, revalidate in background
+      if (age < maxAge + staleWhileRevalidate && !entry.revalidating) {
+        entry.revalidating = true
+        revalidate(cacheKey, ctx, next)
+        return new Response(entry.body, {
+          status: entry.status,
+          headers: { ...entry.headers, "X-Cache": "STALE", "Age": String(Math.floor(age)) },
+        })
+      }
+    }
+
+    // Miss — fetch and cache
+    const response = await next()
+    if (response.status === 200) {
+      const body = await response.text()
+      const headers: Record<string, string> = {}
+      response.headers.forEach((v, k) => { headers[k] = v })
+      store.set(cacheKey, { body, headers, status: response.status, createdAt: now })
+      return new Response(body, {
+        status: response.status,
+        headers: { ...headers, "X-Cache": "MISS" },
+      })
+    }
+    return response
+  }
+}
+
+async function revalidate(key: string, ctx: import("./middleware.ts").Context, next: () => Promise<Response>): Promise<void> {
+  try {
+    const response = await next()
+    if (response.status === 200) {
+      const body = await response.text()
+      const headers: Record<string, string> = {}
+      response.headers.forEach((v, k) => { headers[k] = v })
+      store.set(key, { body, headers, status: response.status, createdAt: Date.now() })
+    }
+  } catch {
+    // revalidation failed, stale entry stays
+    const entry = store.get(key)
+    if (entry) entry.revalidating = false
+  }
+}
+
+/** Invalidate cached entry by path */
+export function invalidateCache(path: string): void {
+  for (const key of store.keys()) {
+    if (key.startsWith(path)) store.delete(key)
+  }
+}
+
+/** Clear all cached entries */
+export function clearCache(): void {
+  store.clear()
+}

package/src/server/compress.ts

@@ -0,0 +1,60 @@
+// Response compression middleware — gzip/deflate
+// Uses Web Streams API (native in Bun)
+
+import type { MiddlewareFn } from "./middleware.ts"
+
+const COMPRESSIBLE_TYPES = new Set([
+  "text/html",
+  "text/css",
+  "text/javascript",
+  "application/javascript",
+  "application/json",
+  "text/xml",
+  "application/xml",
+  "image/svg+xml",
+])
+
+function isCompressible(contentType: string | null): boolean {
+  if (!contentType) return false
+  const type = contentType.split(";")[0]!.trim()
+  return COMPRESSIBLE_TYPES.has(type)
+}
+
+export function compress(): MiddlewareFn {
+  return async (_ctx, next) => {
+    const response = await next()
+    const contentType = response.headers.get("content-type")
+
+    if (!isCompressible(contentType)) return response
+    if (response.headers.has("content-encoding")) return response
+    if (!response.body) return response
+
+    const acceptEncoding = _ctx.request.headers.get("accept-encoding") ?? ""
+
+    if (acceptEncoding.includes("gzip")) {
+      const compressed = response.body.pipeThrough(new CompressionStream("gzip"))
+      const headers = new Headers(response.headers)
+      headers.set("Content-Encoding", "gzip")
+      headers.delete("Content-Length")
+      return new Response(compressed, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+      })
+    }
+
+    if (acceptEncoding.includes("deflate")) {
+      const compressed = response.body.pipeThrough(new CompressionStream("deflate"))
+      const headers = new Headers(response.headers)
+      headers.set("Content-Encoding", "deflate")
+      headers.delete("Content-Length")
+      return new Response(compressed, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+      })
+    }
+
+    return response
+  }
+}

package/src/server/etag.ts

@@ -0,0 +1,23 @@
+// ETag support for static file serving
+// Generates weak ETags based on file size + modification time
+
+import { stat } from "node:fs/promises"
+
+export function generateETag(size: number, mtimeMs: number): string {
+  return `W/"${size.toString(16)}-${Math.floor(mtimeMs).toString(16)}"`
+}
+
+export async function fileETag(filePath: string): Promise<string | null> {
+  try {
+    const s = await stat(filePath)
+    return generateETag(s.size, s.mtimeMs)
+  } catch {
+    return null
+  }
+}
+
+export function isNotModified(request: Request, etag: string): boolean {
+  const ifNoneMatch = request.headers.get("if-none-match")
+  if (!ifNoneMatch) return false
+  return ifNoneMatch.split(",").some((t) => t.trim() === etag)
+}

package/src/server/guard.ts

@@ -0,0 +1,69 @@
+// Route guards — declarative access control for routes
+// Usage: export const guard = requireRole("admin")
+
+import type { Context, MiddlewareFn } from "./middleware.ts"
+
+type GuardFn = (ctx: Context) => boolean | Promise<boolean>
+
+interface GuardOptions {
+  onFail?: (ctx: Context) => Response | Promise<Response>
+}
+
+const DEFAULT_DENY = (_ctx: Context) => new Response("Forbidden", { status: 403 })
+
+/** Create a guard middleware from a predicate */
+export function createGuard(check: GuardFn, options?: GuardOptions): MiddlewareFn {
+  const onFail = options?.onFail ?? DEFAULT_DENY
+  return async (ctx, next) => {
+    const allowed = await check(ctx)
+    if (!allowed) return onFail(ctx)
+    return next()
+  }
+}
+
+/** Guard: require authenticated session */
+export function requireAuth(loginPath = "/login"): MiddlewareFn {
+  return createGuard(
+    (ctx) => !!ctx.locals.session,
+    { onFail: (ctx) => ctx.redirect(loginPath) },
+  )
+}
+
+/** Guard: require specific role (reads from session.data.role) */
+export function requireRole(role: string, options?: GuardOptions): MiddlewareFn {
+  return createGuard((ctx) => {
+    const session = ctx.locals.session as { data?: { role?: string } } | undefined
+    return session?.data?.role === role
+  }, options)
+}
+
+/** Guard: combine multiple guards (all must pass) */
+export function allGuards(...guards: MiddlewareFn[]): MiddlewareFn {
+  return async (ctx, next) => {
+    for (const guard of guards) {
+      let passed = false
+      const guardNext = async () => {
+        passed = true
+        return new Response(null)
+      }
+      const result = await guard(ctx, guardNext)
+      if (!passed) return result
+    }
+    return next()
+  }
+}
+
+/** Guard: any one guard passing is sufficient */
+export function anyGuard(...guards: MiddlewareFn[]): MiddlewareFn {
+  return async (ctx, next) => {
+    for (const guard of guards) {
+      let passed = false
+      await guard(ctx, async () => {
+        passed = true
+        return new Response(null)
+      })
+      if (passed) return next()
+    }
+    return new Response("Forbidden", { status: 403 })
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,19 @@
+export { server, handleRPCRequest, __registerRPC, getRPCHandler } from "./rpc.ts"
+export {
+  middleware,
+  createContext,
+  runMiddlewareChain,
+  type Context,
+  type MiddlewareFn,
+  type NextFn,
+} from "./middleware.ts"
+export { defineAction, handleAction, parseFormData, type ActionFn, type ActionResult } from "./action.ts"
+export { joinRoom, leaveRoom, broadcastToRoom, getRoomSize, createWSContext, type WSContext, type WSHandler } from "./ws.ts"
+export { compress } from "./compress.ts"
+export { getMimeType } from "./mime.ts"
+export { fileETag, generateETag, isNotModified } from "./etag.ts"
+export { redirect, RedirectError, type CookieOptions } from "./middleware.ts"
+export { createSSEStream, createEventSource, type SSEOptions, type SSEStream, type EventSourceSignal } from "./sse.ts"
+export { routeCache, invalidateCache, clearCache, type CacheOptions } from "./cache.ts"
+export { createGuard, requireAuth, requireRole, allGuards, anyGuard } from "./guard.ts"
+export { pipe, when, forMethods, forPaths } from "./pipe.ts"