@edge-base/server 0.1.1

package/src/routes/config.ts

@@ -0,0 +1,53 @@
+/**
+ * Public Config Route
+ *
+ * GET /api/config — Returns publicly-safe configuration.
+ * No authentication required.
+ * Currently exposes captcha siteKey for client-side Turnstile rendering.
+ *
+ * siteKey is served from CAPTCHA_SITE_KEY env var (set by deploy.ts after provisioning).
+ * Falls back to bundled runtime config for advanced captcha object configs.
+ */
+import { OpenAPIHono, createRoute, type HonoEnv } from '../lib/hono.js';
+import { parseConfig } from '../lib/do-router.js';
+import { zodDefaultHook, jsonResponseSchema } from '../lib/schemas.js';
+
+
+export const configRoute = new OpenAPIHono<HonoEnv>({ defaultHook: zodDefaultHook });
+
+const getConfig = createRoute({
+  operationId: 'getConfig',
+  method: 'get',
+  path: '/',
+  tags: ['client'],
+  summary: 'Get public configuration',
+  responses: {
+    200: { description: 'Public config', content: { 'application/json': { schema: jsonResponseSchema } } },
+  },
+});
+
+configRoute.openapi(getConfig, (c) => {
+  let captcha: { siteKey: string } | null = null;
+
+  try {
+    // §34: CAPTCHA_SITE_KEY env var takes priority (set by deploy.ts)
+    if (c.env.CAPTCHA_SITE_KEY) {
+      captcha = { siteKey: c.env.CAPTCHA_SITE_KEY };
+    } else {
+      // Fallback: parseConfig() singleton for advanced captcha object configs
+      const config = parseConfig(c.env);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const captchaCfg = (config as any)?.captcha;
+      if (captchaCfg && typeof captchaCfg === 'object' && captchaCfg.siteKey) {
+        captcha = { siteKey: captchaCfg.siteKey };
+      }
+    }
+  } catch {
+    // Return null captcha on error
+  }
+
+  return c.json({ captcha }, 200, {
+    'Cache-Control': 'public, max-age=60, s-maxage=60',
+    'CDN-Cache-Control': 'public, max-age=60',
+  });
+});

package/src/routes/d1.ts

@@ -0,0 +1,109 @@
+/**
+ * D1 route — POST /api/d1/:database
+ *
+ * Allows server SDK (with Service Key) to execute raw SQL on user-defined D1 databases.
+ * NOT available to client SDK (server-only,).
+ *
+ * Security:
+ * - Config Allowlist: database must be declared in config.d1
+ * - Service Key required with scoped validation
+ * - Internal D1 binding (AUTH_DB) is never exposed
+ * - DDL allowed — Service Key holders are admin-level trusted (#75)
+ * - ? bind variables enforced (SQL injection prevention)
+ *
+ * Flow: Server SDK → POST /api/d1/:database → Worker → D1 binding → JSON
+ */
+import { OpenAPIHono, createRoute, z, type HonoEnv } from '../lib/hono.js';
+import { EdgeBaseError } from '@edge-base/shared';
+import { parseConfig } from '../lib/do-router.js';
+import { validateKey, buildConstraintCtx } from '../lib/service-key.js';
+import { zodDefaultHook, d1BodySchema, jsonResponseSchema, errorResponseSchema } from '../lib/schemas.js';
+
+
+export const d1Route = new OpenAPIHono<HonoEnv>({ defaultHook: zodDefaultHook });
+
+/**
+ * POST /api/d1/:database
+ * Body: { query: string, params?: unknown[] }
+ */
+const executeD1Query = createRoute({
+  operationId: 'executeD1Query',
+  method: 'post',
+  path: '/{database}',
+  tags: ['admin'],
+  summary: 'Execute raw SQL on D1 database',
+  request: {
+    params: z.object({ database: z.string() }),
+    body: { content: { 'application/json': { schema: d1BodySchema } }, required: true },
+  },
+  responses: {
+    200: { description: 'Query results', content: { 'application/json': { schema: jsonResponseSchema } } },
+    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
+    401: { description: 'Unauthorized', content: { 'application/json': { schema: errorResponseSchema } } },
+    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
+  },
+});
+
+d1Route.openapi(executeD1Query, async (c) => {
+  const nameParam = c.req.param('database')!;
+
+  let body: { query?: string; params?: unknown[] };
+  try {
+    body = await c.req.json();
+  } catch {
+    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+  }
+
+  const { query, params } = body;
+  if (!query || typeof query !== 'string') {
+    return c.json({ code: 400, message: 'query is required' }, 400);
+  }
+
+  // §2 Allowlist: validate database is declared in config
+  const config = parseConfig(c.env);
+  const d1Config = config.d1?.[nameParam];
+  if (!d1Config) {
+    return c.json({ code: 404, message: `D1 database '${nameParam}' not found in config.` }, 404);
+  }
+
+  // §4 Scope: d1:database:{name}:exec
+  const { result: skResult } = validateKey(
+    c.req.header('X-EdgeBase-Service-Key'),
+    `d1:database:${nameParam}:exec`,
+    config,
+    c.env,
+    undefined,
+    buildConstraintCtx(c.env, c.req),
+  );
+  if (skResult === 'missing') {
+    return c.json({ code: 403, message: 'Service Key required to access D1' }, 403);
+  }
+  if (skResult === 'invalid') {
+    return c.json({ code: 401, message: 'Unauthorized. Invalid Service Key.' }, 401);
+  }
+
+  // §1 Env type — dynamic binding access via type assertion
+  const binding = (c.env as unknown as Record<string, unknown>)[d1Config.binding] as D1Database | undefined;
+  if (!binding) {
+    return c.json({ code: 500, message: `D1 binding '${d1Config.binding}' not available.` }, 500);
+  }
+
+  // Execute D1 query — all SQL allowed (DDL included), ? bind variables enforced
+  try {
+    const stmt = binding.prepare(query);
+    const boundStmt = params && params.length > 0 ? stmt.bind(...params) : stmt;
+    const result = await boundStmt.all();
+    return c.json({
+      results: result.results,
+      meta: {
+        changes: result.meta?.changes,
+        duration: result.meta?.duration,
+        rows_read: result.meta?.rows_read,
+        rows_written: result.meta?.rows_written,
+      },
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'D1 query execution failed';
+    throw new EdgeBaseError(400, message);
+  }
+});

package/src/routes/database-live.ts

@@ -0,0 +1,281 @@
+import { OpenAPIHono, createRoute, z, type HonoEnv } from '../lib/hono.js';
+import {
+  acquirePendingWebSocketSlot,
+  getPendingWebSocketCount,
+  releasePendingWebSocketSlot,
+} from '../lib/websocket-pending.js';
+import {
+  buildDbLiveChannel,
+  DATABASE_LIVE_HUB_DO_NAME,
+  isDbLiveChannel,
+} from '../lib/database-live-emitter.js';
+import { parseConfig } from '../lib/do-router.js';
+import { validateKey, buildConstraintCtx } from '../lib/service-key.js';
+import { getTrustedClientIp } from '../lib/client-ip.js';
+import {
+  zodDefaultHook,
+  broadcastBodySchema,
+  jsonResponseSchema,
+  errorResponseSchema,
+} from '../lib/schemas.js';
+
+export const databaseLiveRoute = new OpenAPIHono<HonoEnv>({ defaultHook: zodDefaultHook });
+
+const MAX_PENDING_PER_IP = 5;
+const PENDING_TTL_SECONDS = 10;
+const dbLiveQuerySchema = z.object({
+  channel: z.string().optional().openapi({ description: 'Legacy DB subscription channel name' }),
+  namespace: z.string().optional().openapi({ description: 'Database namespace', example: 'shared' }),
+  instanceId: z.string().optional().openapi({ description: 'Database instance ID for dynamic DB blocks', example: 'ws-456' }),
+  table: z.string().optional().openapi({ description: 'Table name', example: 'posts' }),
+  docId: z.string().optional().openapi({ description: 'Optional document ID for single-document subscriptions', example: 'post-1' }),
+}).refine(
+  (value) => {
+    if (value.channel) return true;
+    return !!value.namespace && !!value.table;
+  },
+  {
+    message: 'Provide channel or namespace + table',
+    path: ['channel'],
+  },
+);
+
+const dbConnectDiagnosticSchema = z.object({
+  ok: z.boolean(),
+  type: z.string(),
+  category: z.string(),
+  message: z.string(),
+  channel: z.string().optional(),
+  pendingCount: z.number().optional(),
+  maxPending: z.number().optional(),
+});
+
+function resolveDatabaseLiveChannel(query: {
+  channel?: string;
+  namespace?: string;
+  instanceId?: string;
+  table?: string;
+  docId?: string;
+}): string | null {
+  if (query.channel) {
+    return isDbLiveChannel(query.channel) ? query.channel : null;
+  }
+  if (!query.namespace || !query.table) return null;
+  return buildDbLiveChannel(query.namespace, query.table, query.instanceId, query.docId);
+}
+
+function getPendingKey(ip: string): string {
+  return `ws:pending:${ip}`;
+}
+
+const checkDatabaseConnection = createRoute({
+  operationId: 'checkDatabaseSubscriptionConnection',
+  method: 'get',
+  path: '/connect-check',
+  tags: ['client'],
+  summary: 'Check database live subscription WebSocket prerequisites',
+  request: {
+    query: dbLiveQuerySchema,
+  },
+  responses: {
+    200: { description: 'Database live connection looks ready', content: { 'application/json': { schema: dbConnectDiagnosticSchema } } },
+    400: { description: 'Bad request', content: { 'application/json': { schema: dbConnectDiagnosticSchema } } },
+    429: { description: 'Rate limited', content: { 'application/json': { schema: dbConnectDiagnosticSchema } } },
+  },
+});
+
+databaseLiveRoute.openapi(checkDatabaseConnection, async (c) => {
+  const channel = resolveDatabaseLiveChannel({
+    channel: c.req.query('channel') ?? undefined,
+    namespace: c.req.query('namespace') ?? undefined,
+    instanceId: c.req.query('instanceId') ?? undefined,
+    table: c.req.query('table') ?? undefined,
+    docId: c.req.query('docId') ?? undefined,
+  });
+
+  if (!channel) {
+    return c.json({
+      ok: false,
+      type: 'db_connect_invalid_request',
+      category: 'request',
+      message: 'Database subscription target required',
+    }, 400);
+  }
+
+  const ip = getTrustedClientIp(c.env, c.req) ?? 'unknown';
+  const kvKey = getPendingKey(ip);
+  const pendingCount = await getPendingWebSocketCount(c.env.KV, kvKey).catch(() => 0);
+  if (pendingCount >= MAX_PENDING_PER_IP) {
+    return c.json({
+      ok: false,
+      type: 'db_connect_rate_limited',
+      category: 'rate_limit',
+      message: 'Too many pending WebSocket connections',
+      channel,
+      pendingCount,
+      maxPending: MAX_PENDING_PER_IP,
+    }, 429);
+  }
+
+  return c.json({
+    ok: true,
+    type: 'db_connect_ready',
+    category: 'ready',
+    message: 'Database live subscription preflight passed',
+    channel,
+    pendingCount,
+    maxPending: MAX_PENDING_PER_IP,
+  }, 200);
+});
+
+const connectDatabaseSubscription = createRoute({
+  operationId: 'connectDatabaseSubscription',
+  method: 'get',
+  path: '/subscribe',
+  tags: ['client'],
+  summary: 'Connect to database live subscriptions WebSocket',
+  description: 'Database-owned WebSocket entrypoint for onSnapshot subscriptions. Requires Upgrade: websocket header.',
+  request: {
+    query: dbLiveQuerySchema,
+  },
+  responses: {
+    101: { description: 'WebSocket upgrade successful' },
+    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
+    429: { description: 'Rate limited', content: { 'application/json': { schema: errorResponseSchema } } },
+  },
+});
+
+/**
+ * POST /broadcast
+ * Server-side broadcast to a database-live channel.
+ * Service Key required AND validated.
+ * Body: { channel: string, event: string, payload?: Record<string, unknown> }
+ */
+const databaseLiveBroadcast = createRoute({
+  operationId: 'databaseLiveBroadcast',
+  method: 'post',
+  path: '/broadcast',
+  tags: ['admin'],
+  summary: 'Broadcast to database live channel',
+  request: {
+    body: { content: { 'application/json': { schema: broadcastBodySchema } }, required: true },
+  },
+  responses: {
+    200: { description: 'Broadcast sent', content: { 'application/json': { schema: jsonResponseSchema } } },
+    400: { description: 'Bad request', content: { 'application/json': { schema: errorResponseSchema } } },
+    401: { description: 'Unauthorized', content: { 'application/json': { schema: errorResponseSchema } } },
+    403: { description: 'Forbidden', content: { 'application/json': { schema: errorResponseSchema } } },
+  },
+});
+
+databaseLiveRoute.openapi(databaseLiveBroadcast, async (c) => {
+  let body: { channel?: string; event?: string; payload?: Record<string, unknown> };
+  try {
+    body = await c.req.json();
+  } catch {
+    return c.json({ code: 400, message: 'Invalid JSON body' }, 400);
+  }
+
+  const { channel, event, payload } = body;
+  if (!channel || typeof channel !== 'string') {
+    return c.json({ code: 400, message: 'channel is required' }, 400);
+  }
+  if (!event || typeof event !== 'string') {
+    return c.json({ code: 400, message: 'event is required' }, 400);
+  }
+
+  // Service Key required AND validated
+  const config = parseConfig(c.env);
+  const { result: skResult } = validateKey(
+    c.req.header('X-EdgeBase-Service-Key'),
+    `db:channel:${channel}:broadcast`,
+    config,
+    c.env,
+    undefined,
+    buildConstraintCtx(c.env, c.req),
+  );
+  if (skResult === 'missing') {
+    return c.json({ code: 403, message: 'Service Key required for server broadcast' }, 403);
+  }
+  if (skResult === 'invalid') {
+    return c.json({ code: 401, message: 'Unauthorized. Invalid Service Key.' }, 401);
+  }
+
+  // Route broadcast through the DatabaseLiveDO hub
+  const doId = c.env.DATABASE_LIVE.idFromName(DATABASE_LIVE_HUB_DO_NAME);
+  const doStub = c.env.DATABASE_LIVE.get(doId);
+
+  const doResponse = await doStub.fetch(new Request('http://do/internal/broadcast', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ channel, event, payload: payload ?? {} }),
+  }));
+
+  if (!doResponse.ok) {
+    return c.json({ code: doResponse.status, message: 'Broadcast failed' }, doResponse.status as 400 | 500);
+  }
+
+  return c.json({ ok: true });
+});
+
+databaseLiveRoute.openapi(connectDatabaseSubscription, async (c) => {
+  const upgradeHeader = c.req.header('Upgrade');
+  if (upgradeHeader !== 'websocket') {
+    return c.json({ code: 400, message: 'Expected WebSocket upgrade' }, 400);
+  }
+
+  const channel = resolveDatabaseLiveChannel({
+    channel: c.req.query('channel') ?? undefined,
+    namespace: c.req.query('namespace') ?? undefined,
+    instanceId: c.req.query('instanceId') ?? undefined,
+    table: c.req.query('table') ?? undefined,
+    docId: c.req.query('docId') ?? undefined,
+  });
+  if (!channel) {
+    return c.json({ code: 400, message: 'Database subscription target required' }, 400);
+  }
+
+  const ip = getTrustedClientIp(c.env, c.req) ?? 'unknown';
+  const kvKey = getPendingKey(ip);
+  let pendingTracked = false;
+
+  try {
+    pendingTracked = await acquirePendingWebSocketSlot(
+      c.env.KV,
+      kvKey,
+      MAX_PENDING_PER_IP,
+      PENDING_TTL_SECONDS,
+    );
+    if (!pendingTracked) {
+      return c.json({
+        code: 429,
+        message: 'Too many pending WebSocket connections',
+      }, 429);
+    }
+  } catch {
+    // KV failure shouldn't block legitimate connections
+  }
+
+  const doId = c.env.DATABASE_LIVE.idFromName(DATABASE_LIVE_HUB_DO_NAME);
+  const doStub = c.env.DATABASE_LIVE.get(doId);
+
+  const url = new URL(c.req.url);
+  url.pathname = '/websocket';
+  url.search = '';
+  url.searchParams.set('channel', channel);
+  const doRequest = new Request(url.toString(), {
+    headers: c.req.raw.headers,
+  });
+
+  try {
+    return await doStub.fetch(doRequest);
+  } finally {
+    if (pendingTracked) {
+      try {
+        await releasePendingWebSocketSlot(c.env.KV, kvKey, PENDING_TTL_SECONDS);
+      } catch {
+        // KV failure shouldn't break an already accepted connection.
+      }
+    }
+  }
+});

package/src/routes/functions.ts

@@ -0,0 +1,155 @@
+/**
+ * Functions Route - HTTP trigger handler with file-system routing.
+ *
+ * Handles requests to /api/functions/:functionName
+ * Supports:
+ * - Static routes: /api/functions/hello
+ * - Dynamic params: /api/functions/users/abc123/profile
+ * - Catch-all: /api/functions/docs/a/b/c
+ * - Directory middleware (_middleware.ts)
+ * - FunctionError structured error responses
+ */
+import { OpenAPIHono, type HonoEnv } from '../lib/hono.js';
+import {
+  matchRoute,
+  routeExistsForPath,
+  buildFunctionContext,
+  getMiddlewareChain,
+  getWorkerUrl,
+} from '../lib/functions.js';
+import { parseConfig } from '../lib/do-router.js';
+import { resolveRootServiceKey } from '../lib/service-key.js';
+import type { AuthContext } from '../lib/functions.js';
+import { captchaMiddleware } from '../middleware/captcha-verify.js';
+import { FunctionError } from '@edge-base/shared';
+
+function isFunctionErrorLike(
+  value: unknown,
+): value is {
+  code: string;
+  message: string;
+  httpStatus?: number;
+  status?: number;
+  details?: Record<string, unknown>;
+  toJSON?: () => unknown;
+} {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate.code === 'string' &&
+    typeof candidate.message === 'string' &&
+    (typeof candidate.httpStatus === 'number' || typeof candidate.status === 'number')
+  );
+}
+
+export const functionsRoute = new OpenAPIHono<HonoEnv>();
+
+/**
+ * Dynamic HTTP trigger handler with pattern matching.
+ */
+functionsRoute.all('/:functionName{.+}', async (c) => {
+  const functionName = c.req.param('functionName');
+  const method = c.req.method.toUpperCase();
+
+  // Match route with pattern matching (handles [param], [...slug], static routes)
+  const matched = matchRoute(functionName, method);
+
+  if (!matched) {
+    // Check if route exists but method is wrong → 405
+    if (routeExistsForPath(functionName)) {
+      return c.json(
+        { code: 405, message: `Method ${method} not allowed for '${functionName}'.` },
+        405,
+      );
+    }
+    return c.json(
+      { code: 404, message: `Function '${functionName}' not found.` },
+      404,
+    );
+  }
+
+  const config = parseConfig(c.env);
+  const serviceKey = resolveRootServiceKey(config, c.env);
+
+  // Auth context from middleware (set by authMiddleware earlier in chain)
+  const auth = (c.get('auth' as never) || null) as AuthContext | null;
+
+  const workerUrl = getWorkerUrl(c.req.url, c.env) ?? 'http://localhost';
+
+  const ctx = buildFunctionContext({
+    request: c.req.raw,
+    auth,
+    databaseNamespace: c.env.DATABASE,
+    authNamespace: c.env.AUTH,
+    d1Database: c.env.AUTH_DB,
+    kvNamespace: c.env.KV,
+    env: c.env as never,
+    executionCtx: c.executionCtx as never,
+    config,
+    serviceKey,
+    workerUrl,
+    params: matched.params,
+  });
+
+  // Captcha check for functions with captcha: true
+  if (matched.route.definition.captcha) {
+    const captchaMw = captchaMiddleware(`function:${matched.route.name}`);
+    await captchaMw(c, async () => {});
+    if (c.res && c.res.status === 403) {
+      return c.res;
+    }
+  }
+
+  try {
+    // Execute middleware chain (root → nested → handler)
+    const middlewares = getMiddlewareChain(matched.route.name);
+    for (const mw of middlewares) {
+      await mw(ctx);
+    }
+
+    // Execute handler
+    const result = await matched.route.definition.handler(ctx);
+
+    // If handler returns a Response, use it directly
+    if (result instanceof Response) {
+      return result;
+    }
+
+    // If handler returns an object, JSON-serialize it
+    if (result && typeof result === 'object') {
+      return c.json(result);
+    }
+
+    // If handler returns a string, return as text
+    if (typeof result === 'string') {
+      return c.text(result);
+    }
+
+    // Default: 204 No Content
+    return c.body(null, 204);
+  } catch (err: unknown) {
+    // Handle FunctionError specially — return structured JSON
+    if (err instanceof FunctionError) {
+      return c.json(err.toJSON(), err.httpStatus as 400);
+    }
+
+    // Cloudflare/local dev can bundle user functions with a second copy of
+    // @edge-base/shared, so instanceof is not reliable across that boundary.
+    if (isFunctionErrorLike(err)) {
+      const status = err.httpStatus ?? err.status ?? 500;
+      const body =
+        typeof err.toJSON === 'function'
+          ? err.toJSON()
+          : {
+              code: err.code,
+              message: err.message,
+              status,
+              ...(err.details ? { details: err.details } : {}),
+            };
+      return c.json(body, status as 400);
+    }
+
+    console.error(`[EdgeBase] HTTP function '${matched.route.name}' error:`, err);
+    return c.json({ code: 500, message: 'Function execution failed.' }, 500);
+  }
+});

package/src/routes/health.ts

@@ -0,0 +1,32 @@
+import { OpenAPIHono, createRoute, type HonoEnv } from '../lib/hono.js';
+import { healthResponseSchema, zodDefaultHook } from '../lib/schemas.js';
+import { SERVER_VERSION } from '../lib/version.js';
+
+
+export const healthRoute = new OpenAPIHono<HonoEnv>({ defaultHook: zodDefaultHook });
+
+/**
+ * GET /api/health — Health check endpoint.
+ * Returns server status and version information.
+ */
+const getHealth = createRoute({
+  operationId: 'getHealth',
+  method: 'get',
+  path: '/health',
+  tags: ['client'],
+  summary: 'Health check',
+  responses: {
+    200: {
+      description: 'Server is healthy',
+      content: { 'application/json': { schema: healthResponseSchema } },
+    },
+  },
+});
+
+healthRoute.openapi(getHealth, (c) => {
+  return c.json({
+    status: 'ok',
+    version: SERVER_VERSION,
+    timestamp: new Date().toISOString(),
+  }, 200);
+});