feat(observability): gated client-side Sentry via same-origin tunnel

docs/site-map.md

@@ -596,6 +596,7 @@ This file is generated by `npm run sitemap:update`. Run `npm run sitemap:check`
 - `/api/local-project-id` - Local project identity guard. Source: `src/app/api/local-project-id/route.ts`.
 - `/api/medications` - Route discovered from app directory Source: `src/app/api/medications/route.ts`.
 - `/api/medications/[slug]` - Route discovered from app directory Source: `src/app/api/medications/[slug]/route.ts`.
+- `/api/monitoring` - Route discovered from app directory Source: `src/app/api/monitoring/route.ts`.
 - `/api/registry/records` - Registry record collection. Source: `src/app/api/registry/records/route.ts`.
 - `/api/registry/records/[slug]` - Registry record detail. Source: `src/app/api/registry/records/[slug]/route.ts`.
 - `/api/search` - Search endpoint. Source: `src/app/api/search/route.ts`.

next.config.ts

@@ -36,12 +36,24 @@ const nextConfig: NextConfig = {
  turbopack: {
  root: projectRoot,
  },
- webpack(config) {
+ webpack(config, { webpack }) {
  // Avoid a Next/webpack WasmHash worker crash observed on Node 24 during local production builds.
  config.output = {
  ...config.output,
  hashFunction: "sha256",
  };
+ // Build-time flag so the browser Sentry SDK (@sentry/browser) is fully
+ // tree-shaken out unless a public DSN is set at build. Next does NOT fold an
+ // UNSET NEXT_PUBLIC_* var to a compile-time constant, so a plain
+ // `if (process.env.NEXT_PUBLIC_SENTRY_DSN)` gate leaves the dynamic import (and
+ // its chunk) on disk. This literal boolean lets webpack dead-code-eliminate the
+ // whole block, so an unconfigured build ships zero Sentry bytes. See
+ // src/instrumentation-client.ts.
+ config.plugins.push(
+ new webpack.DefinePlugin({
+ __SENTRY_ENABLED__: JSON.stringify(Boolean(process.env.NEXT_PUBLIC_SENTRY_DSN)),
+ }),
+ );
  return config;
  },
  async headers() {

package.json

@@ -141,6 +141,7 @@
  },
  "dependencies": {
  "@next/env": "16.2.10",
+ "@sentry/browser": "^10.65.0",
  "@sentry/node": "^10.65.0",
  "@supabase/ssr": "^0.12.0",
  "@supabase/supabase-js": "^2.108.2",

src/app/api/monitoring/route.ts

@@ -0,0 +1,144 @@
+// Same-origin Sentry tunnel. The browser SDK is configured with
+// `tunnel: "/api/monitoring"` (src/instrumentation-client.ts) so event envelopes
+// are POSTed here instead of directly to Sentry's ingest host. This keeps the
+// strict clinical CSP intact — `connect-src 'self'` already allows this route, so
+// no Sentry ingest host has to be added to the policy — and lets ad-blockers that
+// block *.sentry.io not silently drop client error reports.
+//
+// The route forwards the raw envelope to Sentry server-side (server fetches are not
+// bound by CSP). Hardening: it (1) validates the envelope's embedded DSN against the
+// project's own configured DSN so the endpoint cannot relay to arbitrary projects,
+// (2) caps the buffered body at 1 MB (Content-Length preflight + streamed byte
+// count) since this is an unauthenticated public POST under a large proxy body
+// allowance, and (3) bounds the upstream relay with a timeout. Inert (404) until
+// SENTRY_DSN / NEXT_PUBLIC_SENTRY_DSN is set.
+
+export const runtime = "nodejs";
+
+const MAX_ENVELOPE_BYTES = 1_000_000; // 1 MB — Sentry event envelopes are far smaller.
+const UPSTREAM_TIMEOUT_MS = 5_000;
+
+// Lightweight per-IP throttle. This is an unauthenticated public POST, so a
+// spammer with a valid envelope could otherwise burn the project's Sentry ingest
+// quota. A per-instance in-memory window is intentionally simple (unlike the
+// durable answer/upload limiters this is best-effort telemetry relay, not a paid
+// or state-changing path); Sentry's own ingest rate limits are the backstop.
+const RATE_LIMIT_MAX = 120;
+const RATE_LIMIT_WINDOW_MS = 60_000;
+type RateWindow = { count: number; resetAt: number };
+const rateLimitByIp = new Map<string, RateWindow>();
+
+function isRateLimited(ip: string): boolean {
+ const now = Date.now();
+ if (rateLimitByIp.size > 5_000) {
+ for (const [key, window] of rateLimitByIp) if (now >= window.resetAt) rateLimitByIp.delete(key);
+ }
+ const existing = rateLimitByIp.get(ip);
+ if (!existing || now >= existing.resetAt) {
+ rateLimitByIp.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS });
+ return false;
+ }
+ existing.count += 1;
+ return existing.count > RATE_LIMIT_MAX;
+}
+
+type ParsedDsn = { host: string; projectId: string };
+
+function parseDsn(dsn: string): ParsedDsn {
+ const url = new URL(dsn);
+ const projectId = url.pathname.replace(/^\//, "");
+ if (!url.host || !projectId) throw new Error("incomplete dsn");
+ return { host: url.host, projectId };
+}
+
+// Reads the request body as text but aborts once it exceeds `maxBytes`, returning
+// null. Streams so an oversized body is never fully buffered.
+async function readCappedText(request: Request, maxBytes: number): Promise<string | null> {
+ const reader = request.body?.getReader();
+ if (!reader) {
+ const text = await request.text();
+ return text.length > maxBytes ? null : text;
+ }
+ const decoder = new TextDecoder();
+ let total = 0;
+ let out = "";
+ for (;;) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ total += value.byteLength;
+ if (total > maxBytes) {
+ await reader.cancel();
+ return null;
+ }
+ out += decoder.decode(value, { stream: true });
+ }
+ out += decoder.decode();
+ return out;
+}
+
+export async function POST(request: Request): Promise<Response> {
+ const configuredDsn = process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN;
+ if (!configuredDsn) return new Response(null, { status: 404 });
+
+ const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || "unknown";
+ if (isRateLimited(ip)) {
+ return new Response("too many requests", { status: 429, headers: { "Retry-After": "60" } });
+ }
+
+ let expected: ParsedDsn;
+ try {
+ expected = parseDsn(configuredDsn);
+ } catch {
+ // Misconfigured server DSN — do not leak detail, just refuse.
+ return new Response(null, { status: 404 });
+ }
+
+ // Reject oversized payloads before buffering when the length is declared.
+ const declaredLength = Number(request.headers.get("content-length"));
+ if (Number.isFinite(declaredLength) && declaredLength > MAX_ENVELOPE_BYTES) {
+ return new Response("payload too large", { status: 413 });
+ }
+
+ const envelope = await readCappedText(request, MAX_ENVELOPE_BYTES);
+ if (envelope === null) return new Response("payload too large", { status: 413 });
+
+ const firstNewline = envelope.indexOf("\n");
+ if (firstNewline === -1) return new Response("invalid envelope", { status: 400 });
+
+ let header: { dsn?: unknown };
+ try {
+ header = JSON.parse(envelope.slice(0, firstNewline));
+ } catch {
+ return new Response("invalid envelope header", { status: 400 });
+ }
+
+ if (typeof header.dsn !== "string") return new Response("missing dsn", { status: 400 });
+
+ let incoming: ParsedDsn;
+ try {
+ incoming = parseDsn(header.dsn);
+ } catch {
+ return new Response("invalid dsn", { status: 400 });
+ }
+
+ // Reject anything not addressed to this project's own DSN (no open relay).
+ if (incoming.host !== expected.host || incoming.projectId !== expected.projectId) {
+ return new Response("forbidden", { status: 403 });
+ }
+
+ let upstream: Response;
+ try {
+ upstream = await fetch(`https://${expected.host}/api/${expected.projectId}/envelope/`, {
+ method: "POST",
+ body: envelope,
+ headers: { "Content-Type": "application/x-sentry-envelope" },
+ signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+ });
+ } catch {
+ // Upstream slow/unreachable — fail fast without tying up the request thread.
+ return new Response("bad gateway", { status: 502 });
+ }
+
+ const body = await upstream.text();
+ return new Response(body, { status: upstream.status });
+}

src/app/global-error.tsx

@@ -2,6 +2,8 @@
 
 import { useEffect } from "react";
 
+import { captureClientException } from "@/lib/observability/sentry-client";
+
 /**
  * Last-resort boundary for the App Router. Unlike `app/error.tsx`, this replaces
  * the root layout entirely, so it is the ONLY thing that can recover from an
@@ -13,6 +15,8 @@ import { useEffect } from "react";
 export default function GlobalError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  useEffect(() => {
  console.error("Fatal error captured by global-error boundary:", error);
+ // No-op unless the browser Sentry SDK was initialized (NEXT_PUBLIC_SENTRY_DSN set at build).
+ captureClientException(error);
  }, [error]);
 
  return (

src/components/route-error-boundary.tsx

@@ -4,6 +4,7 @@ import { useEffect } from "react";
 import { TriangleAlert, RefreshCw } from "lucide-react";
 
 import { cn, primaryControl } from "@/components/ui-primitives";
+import { captureClientException } from "@/lib/observability/sentry-client";
 
 export type RouteErrorBoundaryProps = {
  /** The error thrown by the segment, forwarded by Next.js. */
@@ -40,6 +41,8 @@ export function RouteErrorBoundary({
 }: RouteErrorBoundaryProps) {
  useEffect(() => {
  console.error(logLabel, error);
+ // No-op unless the browser Sentry SDK was initialized (NEXT_PUBLIC_SENTRY_DSN set at build).
+ captureClientException(error);
  }, [error, logLabel]);
 
  return (

src/instrumentation-client.ts

@@ -10,5 +10,43 @@
 // (validation stays correct, just interpreted rather than compiled). The server
 // has no CSP, so it keeps the faster JIT path — this is client-only by design.
 import { config } from "zod";
+import { registerSentryClient } from "@/lib/observability/sentry-client";
 
 config({ jitless: true });
+
+// Gated browser error tracking, the client counterpart to the server-side
+// @sentry/node capture in src/instrumentation.ts. `__SENTRY_ENABLED__` is a
+// build-time literal boolean injected by DefinePlugin (next.config.ts) — true only
+// when a public DSN is set at build. As a real compile-time constant it lets the
+// webpack production build dead-code-eliminate this whole block (and the entire
+// @sentry/browser chunk) when false, so an unconfigured build ships ZERO Sentry
+// bytes. The `typeof` guard keeps it safe under the Turbopack dev server, which
+// does not run the webpack DefinePlugin and so leaves the identifier undefined.
+// Events go through the same-origin tunnel (/api/monitoring) so the strict
+// clinical CSP (connect-src 'self' …) needs no Sentry ingest host.
+declare const __SENTRY_ENABLED__: boolean;
+
+if (typeof __SENTRY_ENABLED__ !== "undefined" && __SENTRY_ENABLED__) {
+ void (async () => {
+ const [Sentry, { scrubClientSentryEvent }] = await Promise.all([
+ import("@sentry/browser"),
+ import("@/lib/observability/sentry-scrub"),
+ ]);
+ Sentry.init({
+ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+ tunnel: "/api/monitoring",
+ environment: process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT || process.env.NODE_ENV,
+ // Errors only: no performance tracing (avoids shipping navigation-timing/PII).
+ tracesSampleRate: 0,
+ sendDefaultPii: false,
+ // Same privacy boundary as the server init: strip request + breadcrumbs, and
+ // never record breadcrumbs in the first place.
+ beforeSend: scrubClientSentryEvent,
+ beforeBreadcrumb: () => null,
+ });
+ registerSentryClient(Sentry);
+ })().catch(() => {
+ // Loading/initializing the SDK is best-effort observability; a failed dynamic
+ // import (e.g. blocked chunk) must never surface as an unhandled rejection.
+ });
+}

src/lib/env.ts

@@ -24,6 +24,16 @@ const envSchema = z.object({
  (value) => (typeof value === "string" && value.trim() === "" ? undefined : value),
  z.string().url().optional(),
  ),
+ // Optional client-side (browser) Sentry error capture, the counterpart to the
+ // server SENTRY_DSN above. This public DSN is safe to expose to the browser. Fully
+ // inert when unset: the @sentry/browser SDK is tree-shaken out of the client bundle
+ // (see src/instrumentation-client.ts). Blank is normalized to undefined so an empty
+ // NEXT_PUBLIC_SENTRY_DSN="" never fails envSchema.parse at startup.
+ NEXT_PUBLIC_SENTRY_DSN: z.preprocess(
+ (value) => (typeof value === "string" && value.trim() === "" ? undefined : value),
+ z.string().url().optional(),
+ ),
+ NEXT_PUBLIC_SENTRY_ENVIRONMENT: z.string().optional(),
  NEXT_PUBLIC_LOCAL_NO_AUTH: z.enum(["true", "false"]).optional().default("false"),
  LOCAL_NO_AUTH: z.enum(["true", "false"]).optional().default("false"),
  LOCAL_NO_AUTH_OWNER_EMAIL: z.string().optional(),

src/lib/observability/sentry-client.ts

@@ -0,0 +1,18 @@
+// Client-side Sentry access indirection. Error boundaries call
+// captureClientException() without ever statically importing @sentry/browser, so
+// a build WITHOUT NEXT_PUBLIC_SENTRY_DSN ships zero Sentry code: instrumentation-
+// client.ts only loads the SDK (and registers it here) when a DSN is present at
+// build time. Until then every call here is a no-op.
+type SentryClientModule = {
+ captureException: (error: unknown) => string;
+};
+
+let client: SentryClientModule | null = null;
+
+export function registerSentryClient(mod: SentryClientModule): void {
+ client = mod;
+}
+
+export function captureClientException(error: unknown): void {
+ client?.captureException(error);
+}