@agent-native/core 0.113.0 → 0.114.1

package/src/server/security-headers.ts

@@ -0,0 +1,170 @@
+/**
+ * Security response headers middleware.
+ *
+ * Sets a baseline set of "no-brainer" security headers on every framework HTTP
+ * response. These headers are layered defenses: each one mitigates a specific
+ * class of attack, and together they harden the surface against MIME-sniffing,
+ * referrer leakage, mixed-content downgrades, and cross-origin window/embed
+ * access.
+ *
+ * The headers we emit:
+ *
+ *   - `Strict-Transport-Security` — forces HTTPS for the browser's lifetime
+ *     of the cached value, preventing SSL-strip MITM. Only emitted when the
+ *     request scheme is `https` (we don't want to break local-dev HTTP, and
+ *     emitting HSTS over HTTP is a no-op per the spec but causes confusion).
+ *   - `X-Content-Type-Options: nosniff` — disables browser MIME sniffing so
+ *     a tool /render route serving user-authored HTML can't be misinterpreted
+ *     as some other content type by a clever Accept header.
+ *   - `Referrer-Policy: strict-origin-when-cross-origin` — strips path/query
+ *     from outbound Referer headers when the request crosses origin, so a
+ *     public-share viewer's outbound link clicks never leak the share token.
+ *   - `Permissions-Policy: camera=*, microphone=(self), geolocation=(),
+ *     screen-wake-lock=()` — allows microphone access for composer dictation
+ *     and camera access for media-capture UI (the Clips recorder, and the
+ *     Clips browser extension's camera bubble, which is injected as a
+ *     cross-origin iframe and is therefore blocked outright by `camera=()`).
+ *     Location and wake-lock stay disabled. The browser still gates actual
+ *     camera/mic use behind a per-origin permission prompt, so `camera=*` only
+ *     removes the policy-level block, not the user consent.
+ *   - `Cross-Origin-Opener-Policy: same-origin` — isolates window.opener so
+ *     a popup-window opener reference can't read or modify our document.
+ *   - `Cross-Origin-Embedder-Policy: require-corp` — emitted only for
+ *     validated MCP embed-session page loads and browser iframe navigations.
+ *     COEP hosts such as Claude's MCP Apps proxy require framed cross-origin
+ *     documents to opt in explicitly.
+ *   - `Cross-Origin-Resource-Policy: same-site` — prevents other origins from
+ *     embedding our endpoints as `<img>` / `<script>` / `<audio>`, blocking
+ *     the simplest data-leak chain when combined with auth cookies. Validated
+ *     MCP embed-session page loads and browser iframe navigations use
+ *     `cross-origin` so COEP hosts can frame app documents.
+ *
+ * NOTE: `Cross-Origin-Embedder-Policy` is NOT set by default because it
+ * requires every embedded subresource to opt in via CORP/CORS, which would
+ * break Builder's iframe editor and template embed use cases. COOP + CORP
+ * without COEP gives us most of the protection on normal responses; COEP is
+ * only added for validated MCP embed-session page loads and browser iframe
+ * navigations (see above).
+ *
+ * NOTE: `X-Frame-Options` is intentionally not set globally. Agent-native apps
+ * are expected to run inside iframe hosts such as Builder, Design, and MCP app
+ * shells. Routes that render especially sensitive iframe-only documents should
+ * set their own route-specific CSP / frame policy.
+ */
+
+import { createHash } from "node:crypto";
+
+import { defineEventHandler, getHeader, setResponseHeader } from "h3";
+
+import {
+  isMcpProtocolPath,
+  MCP_PUBLIC_ROUTE_PREFIX,
+} from "../mcp/route-paths.js";
+import {
+  isMcpEmbedCorsOrigin,
+  MCP_EMBED_CORS_ALLOW_HEADERS,
+} from "../shared/mcp-embed-headers.js";
+import { requestHasEmbedAuthMarker } from "./embed-session.js";
+
+/**
+ * Compute the sha256-<base64> hash token for an inline script's text content.
+ * Pass the raw script body (no surrounding <script> tags). The resulting token
+ * can be listed directly in a `script-src` CSP directive.
+ */
+export function computeInlineScriptHash(scriptContent: string): string {
+  const hash = createHash("sha256").update(scriptContent).digest("base64");
+  return `'sha256-${hash}'`;
+}
+
+const HSTS = "max-age=31536000; includeSubDomains; preload";
+const PERMISSIONS_POLICY =
+  "camera=*, microphone=(self), geolocation=(), screen-wake-lock=()";
+
+/**
+ * Returns true when the request was received over HTTPS. We trust both the
+ * underlying connection (when the server is terminating TLS itself) and the
+ * `x-forwarded-proto` header (set by Netlify, Vercel, Cloudflare, and any
+ * other reverse proxy that fronts the framework).
+ */
+function isHttpsRequest(event: any): boolean {
+  const xfp =
+    event?.node?.req?.headers?.["x-forwarded-proto"] ??
+    event?.headers?.get?.("x-forwarded-proto");
+  if (typeof xfp === "string" && xfp.split(",")[0].trim() === "https")
+    return true;
+  if (Array.isArray(xfp) && xfp[0] === "https") return true;
+  // h3 sets `event.url.protocol` to "http:" or "https:".
+  const proto = event?.url?.protocol;
+  if (proto === "https:") return true;
+  // Direct Node `req.connection.encrypted` (older runtimes).
+  if (event?.node?.req?.connection?.encrypted) return true;
+  return false;
+}
+
+function isMcpEndpointRequest(event: any): boolean {
+  const pathname =
+    event?.url?.pathname ??
+    String(event?.node?.req?.url ?? event?.path ?? "/").split("?")[0];
+  const normalizedPathname = pathname.replace(/\/+$/, "");
+  return (
+    isMcpProtocolPath(normalizedPathname) ||
+    normalizedPathname.endsWith(MCP_PUBLIC_ROUTE_PREFIX)
+  );
+}
+
+function isIframeNavigationRequest(event: any): boolean {
+  return getHeader(event, "sec-fetch-dest") === "iframe";
+}
+
+/**
+ * Create the security-headers h3 middleware. Mount this BEFORE other route
+ * handlers so the headers are present on every response (including 4xx/5xx
+ * error pages). Route handlers that need to tighten a specific header can call
+ * `setResponseHeader` after this runs — the latest write wins.
+ */
+export function createSecurityHeadersMiddleware() {
+  return defineEventHandler((event) => {
+    const embedFrameRequest = requestHasEmbedAuthMarker(event);
+    const mcpEndpointRequest = isMcpEndpointRequest(event);
+    const iframeNavigationRequest = isIframeNavigationRequest(event);
+    const requestOrigin = getHeader(event, "origin");
+    setResponseHeader(event, "X-Content-Type-Options", "nosniff");
+    setResponseHeader(
+      event,
+      "Referrer-Policy",
+      embedFrameRequest ? "no-referrer" : "strict-origin-when-cross-origin",
+    );
+    setResponseHeader(event, "Permissions-Policy", PERMISSIONS_POLICY);
+    setResponseHeader(event, "Cross-Origin-Opener-Policy", "same-origin");
+    if (embedFrameRequest || iframeNavigationRequest) {
+      setResponseHeader(event, "Cross-Origin-Embedder-Policy", "require-corp");
+    }
+    setResponseHeader(
+      event,
+      "Cross-Origin-Resource-Policy",
+      embedFrameRequest || mcpEndpointRequest || iframeNavigationRequest
+        ? "cross-origin"
+        : "same-site",
+    );
+    if (embedFrameRequest && isMcpEmbedCorsOrigin(requestOrigin)) {
+      // requestOrigin is non-null: isMcpEmbedCorsOrigin returns true only for truthy origins
+      setResponseHeader(event, "Access-Control-Allow-Origin", requestOrigin!);
+      setResponseHeader(event, "Vary", "Origin");
+      setResponseHeader(
+        event,
+        "Access-Control-Allow-Methods",
+        "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS",
+      );
+      setResponseHeader(
+        event,
+        "Access-Control-Allow-Headers",
+        MCP_EMBED_CORS_ALLOW_HEADERS,
+      );
+    }
+    if (isHttpsRequest(event)) {
+      setResponseHeader(event, "Strict-Transport-Security", HSTS);
+    }
+    // Continue to the next handler — we only set headers, don't return a body.
+    return undefined;
+  });
+}

package/src/server/self-dispatch.ts

@@ -0,0 +1,224 @@
+import { isLocalDatabase } from "../db/client.js";
+import { signInternalToken } from "../integrations/internal-token.js";
+/**
+ * Shared self-dispatch helper for the framework's serverless background-work
+ * pattern: enqueue a unit of work to SQL, then fire a fresh HTTP POST back to
+ * this same deployment so the work runs in its own function invocation (with
+ * its own full timeout budget) instead of riding on the request that created
+ * it.
+ *
+ * This is the single mechanism that makes background work portable across every
+ * host Nitro deploys to:
+ *   - Netlify Lambda / Vercel Functions / AWS Lambda — the dispatched request
+ *     hits a fresh function with its own budget; no `waitUntil` needed.
+ *   - Cloudflare Workers — same (and `waitUntil` still works as a belt-and-
+ *     suspenders fallback where the in-process path is used).
+ *   - Self-hosted / long-lived Node — the dispatch comes back as another
+ *     request to the same process; each handler still runs to completion.
+ *
+ * Originally inlined in both `a2a/handlers.ts` (`resolveSelfBaseUrl` +
+ * `fireProcessTaskDispatch`) and `integrations/webhook-handler.ts`
+ * (`resolveBaseUrl` + the dispatch in `enqueueAndDispatch`). Extracted here so
+ * A2A, integration webhooks, and Agent Teams sub-agents share one tested
+ * implementation.
+ */
+import {
+  getConfiguredAppBasePath,
+  withConfiguredAppBasePath,
+} from "./app-base-path.js";
+
+/**
+ * On serverless, returning from the dispatching handler before the outbound
+ * TCP handshake starts can freeze the function with the dispatch request stuck
+ * in the queue. Racing the fetch against a short timer gives the request a
+ * chance to leave the box at the cost of a little added latency on the
+ * dispatching call. Mirrors the 250ms used by the A2A/webhook paths.
+ */
+export const DEFAULT_DISPATCH_SETTLE_MS = 250;
+
+function readHeader(event: any, name: string): string | undefined {
+  try {
+    const headers = event?.node?.req?.headers ?? event?.headers;
+    if (!headers) return undefined;
+    if (typeof headers.get === "function") {
+      return headers.get(name) ?? undefined;
+    }
+    const map = headers as Record<string, string | undefined>;
+    return map[name] ?? map[String(name).toLowerCase()];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the base URL to fire a self-dispatch request at. Prefers explicit env
+ * vars (most reliable on serverless, where inbound host headers can be the
+ * platform's internal hostname), falling back to the inbound request headers
+ * and finally localhost in dev.
+ *
+ * Throws in production / shared deployments when no env var is set — a silent
+ * fallback to a bad host there would drop background work invisibly.
+ */
+export function resolveSelfDispatchBaseUrl(event?: any): string {
+  const fromEnv =
+    process.env.APP_URL ||
+    process.env.URL ||
+    process.env.DEPLOY_URL ||
+    process.env.BETTER_AUTH_URL;
+  if (fromEnv) return withConfiguredAppBasePath(String(fromEnv));
+
+  if (process.env.NODE_ENV === "production" || !isLocalDatabase()) {
+    throw new Error(
+      "Self-dispatch requires APP_URL, URL, DEPLOY_URL, or BETTER_AUTH_URL in " +
+        "production/shared deployments so background work can reach this " +
+        "deployment's own URL.",
+    );
+  }
+
+  const proto = readHeader(event, "x-forwarded-proto") || "http";
+  const host =
+    readHeader(event, "host") || `localhost:${process.env.PORT || 3000}`;
+  return withConfiguredAppBasePath(`${proto}://${host}`);
+}
+
+export interface FireInternalDispatchOptions {
+  /** Base URL of this deployment. Defaults to `resolveSelfDispatchBaseUrl(event)`. */
+  baseUrl?: string;
+  /** Request event used to derive the base URL when `baseUrl` is omitted. */
+  event?: any;
+  /** Framework route path to POST to (e.g. "/_agent-native/agent-teams/_process-run"). */
+  path: string;
+  /** Task/run id the processor will claim. Used to sign the HMAC token and as the default body. */
+  taskId: string;
+  /** Extra fields merged into the JSON body alongside `{ taskId }`. */
+  body?: Record<string, unknown>;
+  /** Max ms to wait for the outbound request to leave the box. Default 250ms. */
+  settleMs?: number;
+  /**
+   * Await the dispatch response fully instead of racing the settle timer.
+   *
+   * The 250ms settle race is correct for a synchronous handler that must
+   * respond to its own caller quickly — but it is WRONG for a handoff fired
+   * from a function that is about to finish (e.g. a background worker chaining
+   * its continuation chunk): once the handler's promise resolves, the Lambda
+   * freezes and a still-in-flight dispatch fetch is killed WITHOUT rejecting,
+   * so the handoff is lost silently — the error path never fires. With
+   * `awaitResponse: true` the call resolves only after the target confirmed
+   * receipt (Netlify background functions 202 on enqueue, normally well under
+   * a second) and throws on any network error or non-2xx, bounded by
+   * `responseTimeoutMs`.
+   */
+  awaitResponse?: boolean;
+  /** Max ms to await the dispatch response when `awaitResponse` is set. Default 15s. */
+  responseTimeoutMs?: number;
+}
+
+async function dispatchResponseError(
+  path: string,
+  res: Response,
+): Promise<Error> {
+  let body = "";
+  try {
+    body = (await res.text()).trim();
+  } catch {
+    body = "";
+  }
+  const detail = body ? `: ${body.slice(0, 300)}` : "";
+  return new Error(
+    `Self-dispatch to ${path} returned HTTP ${res.status} ${res.statusText}${detail}`,
+  );
+}
+
+/**
+ * Fire a fresh, HMAC-signed POST to a processor route on this same deployment.
+ * Fire-and-forget: the dispatch is NOT awaited to completion (the processed run
+ * may take minutes); it is only raced against a short settle timer so the
+ * request reliably leaves a serverless box before it freezes.
+ *
+ * When `A2A_SECRET` is unset (local dev), the request is sent unsigned — the
+ * processor accepts unsigned dispatches in dev and relies on the SQL atomic
+ * claim for double-processing protection, mirroring the A2A/webhook flow.
+ */
+/**
+ * For host-root dispatch targets (`/.netlify/functions/*`), strip the configured
+ * app base path suffix from the resolved base url so the request reaches the
+ * function at the host root rather than under the workspace app base path. For
+ * every other (framework-route) path the base-path-prefixed base url is returned
+ * unchanged, preserving the existing self-dispatch behavior.
+ */
+function rootBaseUrlForPath(baseUrl: string, path: string): string {
+  if (!path.startsWith("/.netlify/")) return baseUrl;
+  const basePath = getConfiguredAppBasePath();
+  if (!basePath) return baseUrl;
+  const trimmed = baseUrl.replace(/\/$/, "");
+  if (trimmed.endsWith(basePath)) {
+    return trimmed.slice(0, trimmed.length - basePath.length);
+  }
+  return trimmed;
+}
+
+export async function fireInternalDispatch(
+  options: FireInternalDispatchOptions,
+): Promise<void> {
+  const baseUrl = options.baseUrl ?? resolveSelfDispatchBaseUrl(options.event);
+  // Netlify function default urls (`/.netlify/functions/<name>`) live at the
+  // HOST ROOT, not under the workspace app base path. `resolveSelfDispatchBaseUrl`
+  // appends the configured base path (e.g. `https://host/starter`) so framework
+  // routes land on the right app; for a host-root function url we must dispatch
+  // to `https://host/.netlify/functions/<name>` instead. Strip the base path
+  // suffix from the resolved base url for `/.netlify/*` dispatch targets only.
+  const url = `${rootBaseUrlForPath(baseUrl, options.path)}${options.path}`;
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  try {
+    headers["Authorization"] = `Bearer ${signInternalToken(options.taskId)}`;
+  } catch (err) {
+    // Distinguish the documented "no A2A_SECRET in dev" path from a real
+    // signing failure, so a malformed secret doesn't fail invisibly.
+    if (err instanceof Error && !/A2A_SECRET/i.test(err.message)) {
+      console.error(
+        `[self-dispatch] signInternalToken failed unexpectedly for ${options.taskId}:`,
+        err,
+      );
+    }
+  }
+
+  const awaitResponse = options.awaitResponse === true;
+  const dispatchPromise = fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ taskId: options.taskId, ...(options.body ?? {}) }),
+    ...(awaitResponse
+      ? { signal: AbortSignal.timeout(options.responseTimeoutMs ?? 15_000) }
+      : {}),
+  }).then(async (res) => {
+    if (!res.ok) {
+      throw await dispatchResponseError(options.path, res);
+    }
+  });
+  dispatchPromise.catch((err) => {
+    // Include the resolved base URL: a self-dispatch failure is almost always
+    // about *which* host we POST to (custom domain behind an edge/auth wall vs
+    // the deploy URL), and that is invisible from the error alone. Keeps prod
+    // logs diagnostic without changing the URL resolution order.
+    console.error(
+      `[self-dispatch] dispatch to ${options.path} (base ${baseUrl}) failed:`,
+      err,
+    );
+  });
+
+  if (awaitResponse) {
+    // Confirmed handoff: resolve only once the target acknowledged the
+    // dispatch (throws on network error / timeout / non-2xx). Used by callers
+    // whose own invocation is about to end — see the option doc above.
+    await dispatchPromise;
+    return;
+  }
+
+  const settleMs = options.settleMs ?? DEFAULT_DISPATCH_SETTLE_MS;
+  await Promise.race([
+    dispatchPromise,
+    new Promise<void>((resolve) => setTimeout(resolve, settleMs)),
+  ]);
+}

package/src/server/sentry-config.ts

@@ -0,0 +1,73 @@
+function firstNonEmpty(
+  ...values: Array<string | undefined>
+): string | undefined {
+  for (const value of values) {
+    const trimmed = value?.trim();
+    if (trimmed) return trimmed;
+  }
+  return undefined;
+}
+
+function resolveSentryDsnFromKeyProject(): string | undefined {
+  const key = firstNonEmpty(
+    process.env.SENTRY_CLIENT_KEY,
+    process.env.VITE_SENTRY_CLIENT_KEY,
+  );
+  const projectId = firstNonEmpty(
+    process.env.SENTRY_PROJECT_ID,
+    process.env.VITE_SENTRY_PROJECT_ID,
+  );
+  const host = firstNonEmpty(
+    process.env.SENTRY_INGEST_HOST,
+    process.env.VITE_SENTRY_INGEST_HOST,
+  );
+  if (!key || !projectId || !host) return undefined;
+  return `https://${key}@${host}/${projectId}`;
+}
+
+export function resolveSentryEnvironment(): string {
+  return (
+    firstNonEmpty(
+      process.env.SENTRY_ENVIRONMENT,
+      process.env.NETLIFY_CONTEXT,
+      process.env.VERCEL_ENV,
+      process.env.NODE_ENV,
+    ) ?? "production"
+  );
+}
+
+export function resolveServerSentryDsn(): string | undefined {
+  return (
+    firstNonEmpty(process.env.SENTRY_SERVER_DSN, process.env.SENTRY_DSN) ??
+    resolveSentryDsnFromKeyProject()
+  );
+}
+
+export function resolvePublicSentryDsn(): string | undefined {
+  return (
+    firstNonEmpty(
+      process.env.SENTRY_CLIENT_DSN,
+      process.env.VITE_SENTRY_CLIENT_DSN,
+      process.env.VITE_SENTRY_DSN,
+      process.env.SENTRY_DSN,
+    ) ?? resolveSentryDsnFromKeyProject()
+  );
+}
+
+export function getSentryClientConfigScript(): string | null {
+  const dsn = resolvePublicSentryDsn();
+  if (!dsn) return null;
+
+  const config = {
+    sentryDsn: dsn,
+    sentryEnvironment: resolveSentryEnvironment(),
+  };
+
+  return [
+    "<script data-agent-native-sentry-config>",
+    "window.__AGENT_NATIVE_CONFIG__=Object.assign({},window.__AGENT_NATIVE_CONFIG__,",
+    JSON.stringify(config),
+    ");",
+    "</script>",
+  ].join("");
+}

package/src/server/sentry-plugin.ts

@@ -0,0 +1,138 @@
+import { getHeader, getMethod, type H3Event } from "h3";
+
+import { getSession } from "./auth.js";
+import { registerErrorCaptureProvider } from "./capture-error.js";
+/**
+ * Nitro plugin that initializes server-side Sentry and attaches per-request
+ * user context.
+ *
+ * Wires three pieces:
+ *   1. On startup, `initServerSentry()` reads `SENTRY_SERVER_DSN`/`SENTRY_DSN` and arms
+ *      the SDK (no-op when the env var is unset).
+ *   2. On every request, hook into Nitro's `request` event: resolve the
+ *      session via `getSession(event)` and tag the per-request isolation
+ *      scope with the user's id/email/orgId. Wrapped in try/catch so a
+ *      session-resolution failure can never 500 the request.
+ *   3. On every Nitro `error` event, capture the exception with the route,
+ *      method, and user-agent attached as searchable tags.
+ *
+ * Mounted as a default plugin from `framework-request-handler.ts` —
+ * templates that don't define `server/plugins/sentry.ts` get this for
+ * free. Templates that need to customize (e.g. add custom tags / skip
+ * Sentry) can override by exporting their own `sentry.ts` plugin.
+ */
+import {
+  awaitBootstrap,
+  markDefaultPluginProvided,
+} from "./framework-request-handler.js";
+import { addRequestContextObserver } from "./request-context.js";
+import {
+  captureRouteError,
+  initServerSentry,
+  isServerSentryEnabled,
+  setSentryRequestContext,
+  setSentryUserForRequest,
+} from "./sentry.js";
+
+type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
+
+function readRoute(event: H3Event): string | undefined {
+  try {
+    return event.url?.pathname;
+  } catch {
+    return undefined;
+  }
+}
+
+function readUserAgent(event: H3Event): string | undefined {
+  try {
+    return getHeader(event, "user-agent");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Skip session resolution for paths that obviously don't need one. Avoids
+ * a DB round-trip on every static-asset / favicon / public-share request
+ * while keeping API + framework routes covered.
+ */
+function shouldResolveSession(path: string | undefined): boolean {
+  if (!path) return false;
+  // Vite / React Router static assets and similar.
+  if (
+    path.startsWith("/assets/") ||
+    path.startsWith("/_build/") ||
+    path === "/favicon.ico" ||
+    path.startsWith("/static/")
+  ) {
+    return false;
+  }
+  return true;
+}
+
+export function createSentryPlugin(): NitroPluginDef {
+  return async (nitroApp: any) => {
+    markDefaultPluginProvided(nitroApp, "sentry");
+    await awaitBootstrap(nitroApp);
+
+    initServerSentry();
+    if (!isServerSentryEnabled()) {
+      // No DSN — skip wiring per-request hooks. We'd just be paying the
+      // call-site overhead for every request to no effect.
+      return;
+    }
+
+    registerErrorCaptureProvider("sentry", captureRouteError);
+
+    // Per-request: resolve session and attach to Sentry isolation scope so
+    // any exception captured later in the request carries the user. Wrapped
+    // in try/catch so a session-DB hiccup or auth-broken state never turns
+    // into a 500 — the worst case is we lose user context on the event.
+    nitroApp.hooks?.hook?.("request", async (event: H3Event) => {
+      if (!shouldResolveSession(readRoute(event))) return;
+      try {
+        const session = await getSession(event);
+        setSentryUserForRequest(session);
+      } catch {
+        // best-effort — don't break the request
+      }
+    });
+
+    // Wrap-time: every `runWithRequestContext({ userEmail, orgId, ... })`
+    // call also pins user/org onto Sentry's per-async-context isolation
+    // scope. Covers paths the cookie-based `request` hook can't see —
+    // integration webhook processors, A2A calls, agent-chat tool
+    // re-entries, and any internal call chain that opens a request scope
+    // without an HTTP cookie.
+    addRequestContextObserver((ctx) => {
+      setSentryRequestContext({ userEmail: ctx.userEmail, orgId: ctx.orgId });
+    });
+
+    // Per-error: capture with route/method/UA tags. Nitro's `error` hook
+    // signature is (error, { event, tags }) — we forward what we can.
+    nitroApp.hooks?.hook?.(
+      "error",
+      (error: unknown, ctx?: { event?: H3Event }) => {
+        try {
+          const event = ctx?.event;
+          captureRouteError(error, {
+            route: event ? readRoute(event) : undefined,
+            method: event ? getMethod(event) : undefined,
+            userAgent: event ? readUserAgent(event) : undefined,
+          });
+        } catch {
+          // Sentry capture must never escape into Nitro's error path.
+        }
+      },
+    );
+  };
+}
+
+/**
+ * Default Sentry plugin — auto-mounts when a template doesn't define its
+ * own `server/plugins/sentry.ts`. Reads `SENTRY_SERVER_DSN`/`SENTRY_DSN` from env and
+ * silently no-ops when it's unset, so this is safe to default-mount in
+ * every template (including local dev with no DSN configured).
+ */
+export const defaultSentryPlugin: NitroPluginDef = createSentryPlugin();