feat: add security middleware to server plugin (CSRF, CSP, CORS, error handler)

Add secure-by-default security middleware to the AppKit server plugin,
addressing gaps identified in the Web Security Guide for Lakehouse
Internal Developers. The Databricks Apps proxy only provides
authentication — apps must implement CSRF, CSP, CORS, and error
handling themselves.

New security features:
- CSRF protection via Origin header validation (enabled by default)
- Security headers via helmet (CSP, X-Content-Type-Options, X-Frame-Options, COOP)
- CORS support via expressjs/cors (opt-in, disabled by default)
- Global error handler preventing information disclosure
- Configurable body size limit for JSON parsing

All features are configurable via `security` option in ServerConfig
and can be individually disabled. Dev mode auto-allows localhost
for CSRF and relaxes CSP for Vite HMR.

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>

Author: pkosiec

packages/appkit/package.json

@@ -73,9 +73,11 @@
     "@opentelemetry/sdk-trace-base": "2.6.0",
     "@opentelemetry/semantic-conventions": "1.38.0",
     "@types/semver": "7.7.1",
+    "cors": "^2.8.6",
     "dotenv": "16.6.1",
     "express": "4.22.0",
     "get-port": "7.2.0",
+    "helmet": "^8.1.0",
     "js-yaml": "4.1.1",
     "obug": "2.1.1",
     "pg": "8.18.0",
@@ -88,6 +90,7 @@
   },
   "devDependencies": {
     "@opentelemetry/context-async-hooks": "2.6.1",
+    "@types/cors": "^2.8.19",
     "@types/express": "4.17.25",
     "@types/js-yaml": "4.0.9",
     "@types/json-schema": "7.0.15",

packages/appkit/src/plugins/server/index.ts

@@ -14,6 +14,7 @@ import { instrumentations } from "../../telemetry";
 import { sanitizeClientConfig } from "./client-config-sanitizer";
 import manifest from "./manifest.json";
 import { RemoteTunnelController } from "./remote-tunnel/remote-tunnel-controller";
+import { registerErrorHandler, registerSecurityMiddleware } from "./security";
 import { StaticServer } from "./static-server";
 import type { ServerConfig } from "./types";
 import { getRoutes, type PluginEndpoints, printRoutes } from "./utils";
@@ -111,6 +112,10 @@ export class ServerPlugin extends Plugin {
    */
   async start(): Promise<express.Application> {
     this.serverApplication.use(requestMetricsMiddleware);
+
+    // Security middleware first — inspects headers only, no body needed
+    registerSecurityMiddleware(this.serverApplication, this.config.security);
+
     this.serverApplication.use(
       express.json({
         // Express's stock 100kb default is too tight for modern apps —
@@ -147,6 +152,9 @@ export class ServerPlugin extends Plugin {
 
     await this.setupFrontend(endpoints, pluginConfigs);
 
+    // Error handler last — catches unhandled errors from API routes
+    registerErrorHandler(this.serverApplication, this.config.security);
+
     const listenPort = await this.resolveListenPort();
 
     const server = this.serverApplication.listen(

packages/appkit/src/plugins/server/manifest.json

@@ -24,6 +24,75 @@
         "staticPath": {
           "type": "string",
           "description": "Path to static files directory (auto-detected if not provided)"
+        },
+        "bodyLimit": {
+          "type": "string",
+          "description": "JSON body size limit (e.g. '100kb', '1mb'). Default: '100kb'"
+        },
+        "security": {
+          "type": "object",
+          "description": "Security configuration. Secure defaults applied when omitted.",
+          "properties": {
+            "csrf": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "allowedOrigins": {
+                      "type": "array",
+                      "items": { "type": "string" },
+                      "description": "Additional trusted origins for CSRF validation"
+                    }
+                  }
+                },
+                { "const": false }
+              ]
+            },
+            "helmet": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "description": "HelmetOptions — fully replaces defaults"
+                },
+                { "const": false }
+              ]
+            },
+            "cors": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "allowedOrigins": {
+                      "type": "array",
+                      "items": { "type": "string" }
+                    },
+                    "credentials": { "type": "boolean" },
+                    "maxAge": { "type": "number" },
+                    "allowedMethods": {
+                      "type": "array",
+                      "items": { "type": "string" }
+                    },
+                    "allowedHeaders": {
+                      "type": "array",
+                      "items": { "type": "string" }
+                    }
+                  }
+                },
+                { "const": false }
+              ]
+            },
+            "errorHandler": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "includeErrorCode": { "type": "boolean" }
+                  }
+                },
+                { "const": false }
+              ]
+            }
+          }
         }
       }
     }

packages/appkit/src/plugins/server/security/csrf.ts

@@ -0,0 +1,191 @@
+import type { NextFunction, Request, Response } from "express";
+import { createLogger } from "../../../logging/logger";
+import type { CsrfConfig } from "./types";
+
+const logger = createLogger("server");
+
+const STATE_CHANGING_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
+
+/**
+ * Parse a comma-separated env var into trimmed, non-empty strings.
+ */
+function parseEnvOrigins(envVar: string | undefined): string[] {
+  if (!envVar) return [];
+  return envVar
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Build the set of trusted origins from all sources:
+ * 1. DATABRICKS_APP_URL env var
+ * 2. Config allowedOrigins
+ * 3. APPKIT_CSRF_ALLOWED_ORIGINS env var
+ */
+function buildTrustedOrigins(config?: CsrfConfig): Set<string> {
+  const origins = new Set<string>();
+
+  const appUrl = process.env.DATABRICKS_APP_URL;
+  if (appUrl) {
+    try {
+      origins.add(new URL(appUrl).origin.toLowerCase());
+    } catch {
+      logger.warn(
+        "DATABRICKS_APP_URL is not a valid URL: %s — skipping for CSRF",
+        appUrl,
+      );
+    }
+  }
+
+  for (const o of config?.allowedOrigins ?? []) {
+    try {
+      origins.add(new URL(o).origin.toLowerCase());
+    } catch {
+      logger.warn(
+        "CSRF allowedOrigins entry is not a valid URL: %s — skipping",
+        o,
+      );
+    }
+  }
+
+  for (const o of parseEnvOrigins(process.env.APPKIT_CSRF_ALLOWED_ORIGINS)) {
+    origins.add(o.toLowerCase().replace(/\/$/, ""));
+  }
+
+  return origins;
+}
+
+/**
+ * Check if an origin matches localhost (any port).
+ */
+function isLocalhostOrigin(origin: string): boolean {
+  try {
+    const url = new URL(origin);
+    return url.hostname === "localhost" || url.hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Same-origin heuristic: compare Origin against Host header.
+ * Used as fallback when no trusted origins are configured.
+ */
+function isSameOrigin(origin: string, req: Request): boolean {
+  const host = req.headers.host;
+  if (!host) return false;
+
+  try {
+    const originUrl = new URL(origin);
+    const originHost = originUrl.host.toLowerCase();
+    return originHost === host.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create CSRF protection middleware using Origin header validation.
+ *
+ * - Applies to state-changing methods (POST, PUT, DELETE, PATCH) only
+ * - Allows absent/empty Origin (same-origin browser or non-browser client)
+ * - Rejects `Origin: null` (sandboxed iframe attack vector)
+ * - In dev mode, auto-allows localhost origins
+ * - Falls back to Host header comparison when no trusted origins are configured
+ */
+export function createCsrfMiddleware(
+  config?: CsrfConfig | false,
+): (req: Request, res: Response, next: NextFunction) => void {
+  if (config === false) {
+    return (_req, _res, next) => next();
+  }
+
+  const isDev = process.env.NODE_ENV === "development";
+  const trustedOrigins = buildTrustedOrigins(
+    config === undefined ? undefined : config,
+  );
+
+  if (!isDev && trustedOrigins.size === 0) {
+    logger.warn(
+      "DATABRICKS_APP_URL not set and no CSRF origins configured — CSRF will use Host header fallback. Set DATABRICKS_APP_URL for full protection.",
+    );
+  }
+
+  return (req: Request, res: Response, next: NextFunction) => {
+    if (!STATE_CHANGING_METHODS.has(req.method)) {
+      return next();
+    }
+
+    const origin = req.headers.origin;
+
+    // No Origin header — allow (same-origin or non-browser client)
+    if (!origin || origin === "") {
+      return next();
+    }
+
+    // Reject Origin: null (sandboxed iframe, data: URI)
+    if (origin === "null") {
+      logger.debug("CSRF rejected: null Origin on %s %s", req.method, req.path);
+      return res.status(403).json(
+        isDev
+          ? {
+              error: "CSRF validation failed",
+              detail:
+                "Origin: null rejected — possible sandboxed iframe or data: URI",
+            }
+          : { error: "CSRF validation failed" },
+      );
+    }
+
+    const normalizedOrigin = origin.toLowerCase().replace(/\/$/, "");
+
+    // In dev mode, allow localhost origins
+    if (isDev && isLocalhostOrigin(normalizedOrigin)) {
+      return next();
+    }
+
+    // In production, reject non-HTTPS origins
+    if (!isDev && !normalizedOrigin.startsWith("https://")) {
+      logger.debug(
+        "CSRF rejected: non-HTTPS Origin %s on %s %s",
+        origin,
+        req.method,
+        req.path,
+      );
+      return res.status(403).json(
+        isDev
+          ? {
+              error: "CSRF validation failed",
+              detail: `Origin must use HTTPS in production: ${origin}`,
+            }
+          : { error: "CSRF validation failed" },
+      );
+    }
+
+    // Check against trusted origins
+    if (trustedOrigins.has(normalizedOrigin)) {
+      return next();
+    }
+
+    // Fallback: same-origin heuristic (compare Origin vs Host)
+    if (trustedOrigins.size === 0 && isSameOrigin(origin, req)) {
+      return next();
+    }
+
+    logger.debug(
+      "CSRF rejected: Origin %s not trusted on %s %s",
+      origin,
+      req.method,
+      req.path,
+    );
+    return res.status(403).json(
+      isDev
+        ? {
+            error: "CSRF validation failed",
+            detail: `Origin ${origin} not in trusted set`,
+          }
+        : { error: "CSRF validation failed" },
+    );
+  };
+}