@edge-base/server 0.1.1

package/src/middleware/auth.ts

@@ -0,0 +1,169 @@
+/**
+ * Auth Middleware — JWT Access Token verification + auth context injection
+ *
+ * Parses `Authorization: Bearer {token}` from request headers.
+ * If valid → sets `auth` context with user info.
+ * If missing → sets `auth` to null (allows public endpoints).
+ * If invalid/expired → returns 401.
+ * If token present but JWT_USER_SECRET not configured → returns 401 (fail-closed,).
+ */
+import type { Context, Next } from 'hono';
+import { getAuthEnrichHandler, type AuthContext as SharedAuthContext } from '@edge-base/shared';
+import type { Env } from '../types.js';
+import {
+  verifyAccessToken,
+  TokenExpiredError,
+  TokenInvalidError,
+} from '../lib/jwt.js';
+import {
+  buildKeymap,
+  extractBearerToken,
+  extractServiceKeyHeader,
+  matchesConfiguredSecret,
+} from '../lib/service-key.js';
+import { parseConfig } from '../lib/do-router.js';
+
+// Extend Hono context variables
+declare module 'hono' {
+  interface ContextVariableMap {
+    auth: AuthContext | null;
+    serviceKeyToken: string | null;
+  }
+}
+
+export interface AuthContext extends SharedAuthContext {
+  role: string;
+  isAnonymous: boolean;
+  /** auth enrich hook output — request-scoped extension data (#133 §38). Default: {} */
+  meta: Record<string, unknown>;
+}
+
+interface AuthResolutionEnv {
+  JWT_USER_SECRET?: string;
+}
+
+export function buildAuthContextFromPayload(payload: Record<string, unknown>): AuthContext {
+  return {
+    id: payload.sub as string,
+    email: typeof payload.email === 'string' ? payload.email : undefined,
+    role: (payload.role as string) ?? 'user',
+    isAnonymous: (payload.isAnonymous as boolean) ?? false,
+    custom: (payload.custom as Record<string, unknown> | undefined) ?? undefined,
+    meta: {},
+  };
+}
+
+export async function enrichAuthContext(
+  env: AuthResolutionEnv,
+  auth: AuthContext,
+  request: Request,
+): Promise<AuthContext> {
+  const config = parseConfig(env);
+  const enrich = getAuthEnrichHandler(config);
+  if (!enrich) return auth;
+
+  try {
+    const meta = await Promise.race([
+      Promise.resolve(enrich(auth, request)),
+      new Promise<Record<string, unknown>>((_, reject) =>
+        setTimeout(() => reject(new Error('auth.handlers.hooks.enrich timeout')), 50),
+      ),
+    ]);
+    auth.meta = meta ?? {};
+  } catch {
+    auth.meta = {};
+  }
+
+  return auth;
+}
+
+export async function resolveAuthContextFromToken(
+  env: AuthResolutionEnv,
+  token: string,
+  request: Request,
+): Promise<AuthContext> {
+  const secret = env.JWT_USER_SECRET;
+  if (!secret) {
+    throw new TokenInvalidError('Authentication service not configured.');
+  }
+
+  const payload = await verifyAccessToken(token, secret);
+  const auth = buildAuthContextFromPayload(payload as Record<string, unknown>);
+  return enrichAuthContext(env, auth, request);
+}
+
+function matchesConfiguredServiceKeyCandidate(token: string, c: Context<{ Bindings: Env }>): boolean {
+  const config = parseConfig(c.env);
+  const keymap = buildKeymap(config, c.env);
+  return matchesConfiguredSecret(token, keymap);
+}
+
+/**
+ * Auth middleware — extracts and verifies JWT Access Token.
+ * Non-blocking: if no token, sets auth to null (for public endpoints).
+ * If token present but invalid/expired, returns 401.
+ */
+export async function authMiddleware(c: Context<{ Bindings: Env }>, next: Next): Promise<Response | void> {
+  c.set('serviceKeyToken', null);
+
+  // An explicit service key header wins over Bearer auth. Route-specific scope
+  // validation happens downstream, but we must avoid parsing the paired
+  // Authorization header as a user JWT first.
+  const serviceKeyHeader =
+    c.req.header('X-EdgeBase-Service-Key') ??
+    c.req.header('x-edgebase-service-key') ??
+    c.req.raw.headers.get('X-EdgeBase-Service-Key') ??
+    c.req.raw.headers.get('x-edgebase-service-key') ??
+    extractServiceKeyHeader(c.req);
+  if (serviceKeyHeader !== undefined && serviceKeyHeader !== null) {
+    c.set('serviceKeyToken', serviceKeyHeader);
+    c.set('auth', null);
+    return next();
+  }
+
+  // No token → public request
+  const token = extractBearerToken(c.req);
+  if (token === null) {
+    c.set('auth', null);
+    return next();
+  }
+
+  // Service Key shortcut — exact Service Key secret matches bypass JWT parsing
+  // and are validated by downstream route/rules middleware.
+  if (matchesConfiguredServiceKeyCandidate(token, c)) {
+    c.set('serviceKeyToken', token);
+    c.set('auth', null);
+    return next();
+  }
+
+  try {
+    if (!c.env.JWT_USER_SECRET) {
+      // Fail-closed: token provided but cannot verify — reject
+      return c.json(
+        { code: 401, message: 'Authentication service not configured.', error: 'AUTH_NOT_CONFIGURED' },
+        401,
+      );
+    }
+
+    const auth = await resolveAuthContextFromToken(c.env, token, c.req.raw);
+    c.set('auth', auth);
+    return next();
+  } catch (err) {
+    if (err instanceof TokenExpiredError) {
+      return c.json(
+        { code: 401, message: 'Token expired.', error: 'TOKEN_EXPIRED' },
+        401,
+      );
+    }
+    if (err instanceof TokenInvalidError) {
+      return c.json(
+        { code: 401, message: 'Invalid token.', error: 'TOKEN_INVALID' },
+        401,
+      );
+    }
+    return c.json(
+      { code: 401, message: 'Authentication failed.', error: 'AUTH_FAILED' },
+      401,
+    );
+  }
+}

package/src/middleware/captcha-verify.ts

@@ -0,0 +1,217 @@
+/**
+ * Captcha (Turnstile) verification middleware.
+ *
+ * NOT a global middleware — applied internally within auth and function routes.
+ * Validates Turnstile tokens via siteverify API.
+ *
+ * Token extraction order: body.captchaToken → query.captcha_token → X-EdgeBase-Captcha-Token header.
+ */
+import type { Context, Next } from 'hono';
+import type { Env } from '../types.js';
+import { parseConfig } from '../lib/do-router.js';
+
+interface CaptchaConfig {
+  siteKey: string;
+  secretKey: string;
+  failMode?: 'open' | 'closed';
+  siteverifyTimeout?: number;
+}
+
+type HonoContext = Context<{ Bindings: Env }>;
+
+interface SiteverifyResponse {
+  success: boolean;
+  action?: string;
+  'error-codes'?: string[];
+}
+
+/**
+ * Resolve captcha config. (#133 §31: uses parseConfig() singleton)
+ */
+function resolveCaptchaConfig(env: Env): CaptchaConfig | null {
+  try {
+    const config = parseConfig(env);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const captcha = (config as any)?.captcha;
+
+    if (!captcha) return null;
+    if (captcha === false) return null;
+
+    // captcha: true — check for auto-provisioned keys
+    if (captcha === true) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const siteKey = (config as any)?.captchaSiteKey as string | undefined;
+      const secretKey = env.TURNSTILE_SECRET;
+      if (!siteKey || !secretKey) return null;
+      return { siteKey, secretKey };
+    }
+
+    // captcha: { siteKey, secretKey, ... }
+    if (typeof captcha === 'object' && captcha.siteKey && captcha.secretKey) {
+      return captcha as CaptchaConfig;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract captcha token from request.
+ * Order: body.captchaToken → query.captcha_token → X-EdgeBase-Captcha-Token header
+ */
+async function extractCaptchaToken(c: HonoContext): Promise<string | null> {
+  // Try body (POST requests)
+  if (c.req.method === 'POST' || c.req.method === 'PUT' || c.req.method === 'PATCH') {
+    try {
+      const body = await c.req.json();
+      if (body?.captchaToken) return body.captchaToken;
+    } catch {
+      // Body parsing failed — try other sources
+    }
+  }
+
+  // Try query parameter (GET requests, e.g. OAuth)
+  const queryToken = c.req.query('captcha_token');
+  if (queryToken) return queryToken;
+
+  // Try header (fallback)
+  const headerToken = c.req.header('X-EdgeBase-Captcha-Token');
+  if (headerToken) return headerToken;
+
+  return null;
+}
+
+/**
+ * Call Cloudflare Turnstile siteverify API.
+ */
+async function siteverify(
+  secretKey: string,
+  token: string,
+  remoteip: string | undefined,
+  timeout: number,
+): Promise<SiteverifyResponse> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        secret: secretKey,
+        response: token,
+        ...(remoteip ? { remoteip } : {}),
+      }),
+      signal: controller.signal,
+    });
+    return (await response.json()) as SiteverifyResponse;
+  } catch {
+    // Timeout or network error
+    return { success: false, 'error-codes': ['timeout-or-network-error'] };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Check if request has a Service Key (bypass captcha per).
+ */
+function hasServiceKey(c: HonoContext): boolean {
+  return !!(
+    c.req.header('X-EdgeBase-Service-Key') ||
+    c.req.header('Authorization')?.startsWith('ServiceKey ')
+  );
+}
+
+/**
+ * Create a captcha middleware for Auth routes.
+ * @param expectedAction - Expected Turnstile action value (e.g. 'signup', 'signin')
+ */
+export function captchaMiddleware(expectedAction: string) {
+  return async (c: HonoContext, next: Next) => {
+    const captchaConfig = resolveCaptchaConfig(c.env);
+
+    // Step 1-2: No config or keys not provisioned → pass through
+    if (!captchaConfig) {
+      // Log warning if captcha is enabled but keys missing
+      try {
+        const config = parseConfig(c.env);
+        if (config?.captcha === true) {
+          console.warn('⚠️ Captcha skipped: no Turnstile keys provisioned.');
+        }
+      } catch { /* ignore */ }
+      await next();
+      return;
+    }
+
+    // Step 3: Service Key → bypass
+    if (hasServiceKey(c)) {
+      await next();
+      return;
+    }
+
+    // Step 4: Extract token
+    const token = await extractCaptchaToken(c);
+
+    // Step 5: No token → 403
+    if (!token) {
+      return c.json({ code: 403, message: 'Captcha verification required.', data: { captcha_required: true } }, 403);
+    }
+
+    // Step 6: siteverify
+    const timeout = captchaConfig.siteverifyTimeout ?? 3000;
+    const failMode = captchaConfig.failMode ?? 'open';
+    const remoteip = c.req.header('cf-connecting-ip') || undefined;
+
+    const result = await siteverify(captchaConfig.secretKey, token, remoteip, timeout);
+
+    // Handle siteverify API failure (timeout, network error)
+    if (result['error-codes']?.includes('timeout-or-network-error')) {
+      if (failMode === 'open') {
+        console.warn('⚠️ Turnstile siteverify failed (timeout/network). Allowing request (failMode=open).');
+        await next();
+        return;
+      }
+      return c.json({ code: 503, message: 'Captcha service unavailable.' }, 503);
+    }
+
+    // Step 7: Verify success + action
+    if (!result.success) {
+      return c.json({ code: 403, message: 'Captcha verification failed.', data: { captcha_required: true } }, 403);
+    }
+
+    // Action verification
+    if (result.action && result.action !== expectedAction) {
+      return c.json({
+        code: 403,
+        message: `Captcha action mismatch: expected '${expectedAction}'.`,
+        data: { captcha_required: true },
+      }, 403);
+    }
+
+    // Step 8: Passed
+    await next();
+  };
+}
+
+/**
+ * Captcha middleware for Functions routes.
+ * Checks the function definition's captcha flag before verifying.
+ */
+export function functionCaptchaMiddleware(functionName: string, captchaEnabled: boolean) {
+  if (!captchaEnabled) {
+    return async (_c: HonoContext, next: Next) => { await next(); };
+  }
+  return captchaMiddleware(`function:${functionName}`);
+}
+
+// ─── Test exports (for unit testing only) ───
+export const _test = {
+  resolveCaptchaConfig,
+  extractCaptchaToken,
+  hasServiceKey,
+  siteverify,
+};
+

package/src/middleware/cors.ts

@@ -0,0 +1,159 @@
+import type { MiddlewareHandler } from 'hono';
+import type { Env } from '../types.js';
+import { parseConfig } from '../lib/do-router.js';
+
+type HonoEnv = { Bindings: Env };
+
+interface CorsConfig {
+  origin?: string | string[];
+  methods?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+}
+
+interface ResolvedCorsHeaders {
+  allowOrigin: string;
+  allowMethods: string;
+  allowHeaders: string;
+  allowCredentials: boolean;
+  maxAge: string;
+}
+
+/**
+ * Convert wildcard origin pattern to regex.
+ * e.g. '*.example.com' → /^https?:\/\/.*\.example\.com$/
+ */
+export function wildcardToRegex(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*');
+  return new RegExp(`^https?:\\/\\/${escaped}$`);
+}
+
+/**
+ * Check if origin matches allowed origins list.
+ */
+export function isOriginAllowed(origin: string, allowedOrigins: string | string[]): boolean {
+  if (allowedOrigins === '*') return true;
+
+  const origins = Array.isArray(allowedOrigins) ? allowedOrigins : [allowedOrigins];
+
+  for (const pattern of origins) {
+    // Exact match
+    if (pattern === origin) return true;
+    // Wildcard match
+    if (pattern.includes('*')) {
+      if (wildcardToRegex(pattern).test(origin)) return true;
+    }
+  }
+  return false;
+}
+
+function resolveCorsHeaders(
+  origin: string,
+  configuredOrigins: CorsConfig['origin'],
+  methods: string[],
+  credentials: boolean,
+  maxAge: number,
+): ResolvedCorsHeaders | null {
+  if (!origin) return null;
+
+  const isWildcardOrigin = configuredOrigins === '*';
+  const effectiveCredentials = isWildcardOrigin ? false : credentials;
+
+  let isAllowed = false;
+  if (configuredOrigins) {
+    isAllowed = isOriginAllowed(origin, configuredOrigins);
+  } else {
+    isAllowed =
+      /^http:\/\/localhost(:[0-9]+)?(\/|$)/.test(origin) ||
+      /^http:\/\/127\.0\.0\.1(:[0-9]+)?(\/|$)/.test(origin);
+  }
+
+  if (!isAllowed) return null;
+
+  return {
+    allowOrigin: effectiveCredentials ? origin : (isWildcardOrigin ? '*' : origin),
+    allowMethods: methods.join(', '),
+    allowHeaders: 'Content-Type, Authorization, X-EdgeBase-Service-Key',
+    allowCredentials: effectiveCredentials,
+    maxAge: String(maxAge),
+  };
+}
+
+function applyCorsHeaders(
+  target: { set(name: string, value: string): void; get?(name: string): string | null | undefined },
+  headers: ResolvedCorsHeaders | null,
+): void {
+  if (!headers) return;
+
+  target.set('Access-Control-Allow-Origin', headers.allowOrigin);
+  target.set('Access-Control-Allow-Methods', headers.allowMethods);
+  target.set('Access-Control-Allow-Headers', headers.allowHeaders);
+  target.set('Access-Control-Max-Age', headers.maxAge);
+  if (headers.allowCredentials) {
+    target.set('Access-Control-Allow-Credentials', 'true');
+  }
+  target.set('Vary', 'Origin');
+}
+
+export function decorateResponseHeaders(
+  response: Response,
+  headers: ResolvedCorsHeaders | null,
+): Response {
+  // WebSocket upgrade responses are not normal fetch responses:
+  // Response() cannot be re-constructed with status 101, and browsers do not
+  // use CORS response headers for successful WS upgrades.
+  if (response.status === 101) {
+    return response;
+  }
+
+  try {
+    applyCorsHeaders(response.headers, headers);
+    response.headers.set('X-Content-Type-Options', 'nosniff');
+    return response;
+  } catch {
+    const cloned = new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: new Headers(response.headers),
+    });
+    applyCorsHeaders(cloned.headers, headers);
+    cloned.headers.set('X-Content-Type-Options', 'nosniff');
+    return cloned;
+  }
+}
+
+/**
+ * CORS middleware — config-aware.
+ *
+ * Reads cors config from bundled edgebase.config.ts.
+ * Default: allow localhost origins for development.
+ *
+ * Validates:
+ * - origin: '*' + credentials: true conflict (browser policy violation)
+ * - Wildcard patterns converted to regex matching
+ */
+export const corsMiddleware: MiddlewareHandler<HonoEnv> = async (c, next) => {
+  const origin = c.req.header('Origin') || '';
+
+  // ── Parse config ──
+  const config = parseConfig(c.env);
+  const corsConfig = (config as Record<string, unknown>).cors as CorsConfig | undefined;
+
+  // ── Determine allowed origins ──
+  const configuredOrigins = corsConfig?.origin;
+  const methods = corsConfig?.methods ?? ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS'];
+  const credentials = corsConfig?.credentials ?? true;
+  const maxAge = corsConfig?.maxAge ?? 86400;
+  const corsHeaders = resolveCorsHeaders(origin, configuredOrigins, methods, credentials, maxAge);
+
+  // Handle preflight
+  if (c.req.method === 'OPTIONS') {
+    applyCorsHeaders({ set: c.header.bind(c) }, corsHeaders);
+    return c.body(null, 204);
+  }
+
+  await next();
+  c.res = decorateResponseHeaders(c.res, corsHeaders);
+};

package/src/middleware/error-handler.ts

@@ -0,0 +1,54 @@
+import type { MiddlewareHandler } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { Env } from '../types.js';
+import { EdgeBaseError } from '@edge-base/shared';
+import { normalizeDatabaseError } from '../lib/errors.js';
+
+type HonoEnv = { Bindings: Env };
+
+/**
+ * Global error handler middleware.
+ * Catches all errors and returns a standardized response.
+ */
+export const errorHandlerMiddleware: MiddlewareHandler<HonoEnv> = async (c, next) => {
+  try {
+    await next();
+  } catch (err) {
+    if (err instanceof EdgeBaseError) {
+      return c.json(err.toJSON(), err.code as 400);
+    }
+
+    // Hono HTTPException (thrown by @hono/zod-openapi validators on malformed JSON, etc.)
+    if (err instanceof HTTPException) {
+      return c.json({ code: err.status, message: err.message, slug: 'validation-failed' }, err.status as 400);
+    }
+
+    // Duck-type fallback for cross-module instanceof failures (Cloudflare Workers)
+    if (err && typeof err === 'object') {
+      const e = err as Record<string, unknown>;
+      if (typeof e.code === 'number' && e.code >= 400 && e.code < 600 && typeof e.message === 'string') {
+        const body: { code: number; message: string; slug?: string; data?: unknown } = { code: e.code, message: e.message };
+        if (typeof e.slug === 'string') body.slug = e.slug;
+        if (e.data) body.data = e.data;
+        return c.json(body, e.code as 400);
+      }
+    }
+
+    const normalizedDbError = normalizeDatabaseError(err);
+    if (normalizedDbError) {
+      return c.json(normalizedDbError.toJSON(), normalizedDbError.code as 400);
+    }
+
+    // Unexpected error
+    console.error('Unhandled error:', err);
+
+    return c.json(
+      {
+        code: 500,
+        message: 'Internal server error.',
+        slug: 'internal-error',
+      },
+      500,
+    );
+  }
+};

package/src/middleware/internal-guard.ts

@@ -0,0 +1,26 @@
+import type { MiddlewareHandler } from 'hono';
+import type { Env } from '../types.js';
+
+type HonoEnv = { Bindings: Env };
+
+/**
+ * Internal guard middleware.
+ * Blocks ALL external access to /internal/* endpoints unconditionally.
+ *
+ * SECURITY: The X-EdgeBase-Internal header MUST NOT be trusted from external
+ * requests — any client can set arbitrary headers. Workers cannot strip
+ * incoming headers (Request.headers is immutable), so we simply block all
+ * /internal/* requests at this middleware regardless of headers.
+ *
+ * DO-to-DO calls use the Worker's own internal routing (same-process), not the
+ * public /internal/* path, so legitimate internal calls never reach this guard.
+ */
+export const internalGuardMiddleware: MiddlewareHandler<HonoEnv> = async (c) => {
+  return c.json(
+    {
+      code: 403,
+      message: 'Access denied. Internal endpoints are not publicly accessible.',
+    },
+    403,
+  );
+};