Proxy and sessions

The browser never talks to the Causeloop product API directly. Every request the console or staff portal makes goes to its own Next.js origin, at a path under /api/backend/*, and a single server-side route handler forwards it to the real backend. This page documents that handler in full — src/app/api/backend/[...path]/route.ts — plus the one sibling route that intentionally bypasses it, src/app/api/workspaces/route.ts.

Why a proxy at all

Three constraints shape this design, all verifiable in the route file itself:

No CORS surface. Because the browser’s fetch() calls always land on the same origin serving the page (/api/backend/...), the product API never needs a CORS policy, and there is no second origin an attacker’s page could point a credentialed request at.
No exposed API origin. BACKEND_URL (src/lib/backendUrl.ts) is read from process.env.CAUSELOOP_API_URL on the server only. It is never sent to the browser, never appears in a bundle, and never appears in a URL bar. A tenant admin inspecting network traffic sees only /api/backend/* paths against the frontend’s own domain.
Server-held session, httpOnly cookies. The two session cookies — cl_admin_session and cl_tenant_session (src/lib/authCookies.ts) — are httponly, samesite=lax (set by the backend; see Authentication). Client-side JavaScript cannot read them. The only thing the browser can read is a third, deliberately non-httpOnly cookie, cl_csrf, which exists solely so same-origin JS can echo it back as a header (the CSRF double-submit pattern — see below).

Because the proxy runs as a Next.js Route Handler on the server, it has access to the incoming request’s cookies without any extra plumbing — fetch() on the server forwards headers exactly like any other outbound request. This is what makes “forward the browser’s own cookies to the same-origin proxy” a non-issue rather than a vulnerability: the proxy is not a third party relaying credentials across origins, it’s the same origin the browser already trusts.

The catch-all route

src/app/api/backend/[...path]/route.ts exports GET, POST, PATCH, PUT, and DELETE, all of which call the same internal proxy() function. There is no OPTIONS handler — because every call is same-origin, the browser never issues a CORS preflight.

Path construction

The dynamic segment [...path] captures everything after /api/backend/. buildTargetUrl re-joins it with encodeURIComponent per segment and appends the original query string:

function buildTargetUrl(path: string[], search: string): string {
  const joinedPath = path.map(encodeURIComponent).join("/");
  return `${BACKEND_URL}/${joinedPath}${search}`;
}

So a browser call to /api/backend/remediation/caps?target_type=cluster becomes ${BACKEND_URL}/remediation/caps?target_type=cluster — a 1:1 mapping onto the product API’s own route names (see API reference overview).

The session gate

Before any forwarding happens, the handler checks for a real session cookie:

const hasRealSession =
  Boolean(request.cookies.get(ADMIN_SESSION_COOKIE)?.value) ||
  Boolean(request.cookies.get(TENANT_SESSION_COOKIE)?.value);

if (!hasRealSession && !PUBLIC_PATHS.has(path.join("/"))) {
  return unauthorized(); // 401 { detail: "no session" }
}

PUBLIC_PATHS is a small, explicit allowlist of operations that must work before any session exists:

admin/login, admin/password-reset/request, admin/password-reset/confirm,
health, health/live, health/ready,
login, accept-invite, password-reset/request, password-reset/confirm

The comment in the route file is precise about why: auth-bootstrapping routes establish a session and the three health operations expose only process/dependency readiness, so both categories need to be reachable before a session exists — an external deployment smoke check only needs the public frontend URL, not a backend session. Every other path this proxy sees requires one of the two session cookies to already be set. This check happens in the proxy, in addition to (not instead of) the backend’s own per-route auth dependencies (get_current_employee / get_current_tenant_user) — a request that slips past a bug in this gate still hits a real 401/403 at the backend.

This gate only checks that a session cookie of the right shape is present — it does not validate the token. Validation is the backend’s job on every request (session lookup, expiry, tenant/employee scoping). The proxy’s check exists purely to fail fast and return a stable JSON 401 instead of forwarding an unauthenticated request that the backend would reject anyway.

Header handling

The proxy rebuilds the outbound header set from scratch rather than passing request.headers through unmodified, for one specific reason: it must guarantee the backend never sees a client-supplied X-CauseLoop-* header.

const forwardHeaders = new Headers();
request.headers.forEach((value, key) => {
  const lower = key.toLowerCase();
  if (
    !HOP_BY_HOP_REQUEST_HEADERS.has(lower) &&
    !FORWARDING_REQUEST_HEADERS.has(lower) &&
    !lower.startsWith("x-causeloop-")
  ) {
    forwardHeaders.set(key, value);
  }
});

Three header sets are stripped from the inbound request before forwarding:

Set	Headers	Why
`HOP_BY_HOP_REQUEST_HEADERS`	`host`, `connection`, `content-length`	Meaningless or wrong once re-sent to a different host/body
`FORWARDING_REQUEST_HEADERS`	`forwarded`, `x-forwarded-for`, `x-forwarded-host`, `x-forwarded-port`, `x-forwarded-proto`, `x-real-ip`	The proxy computes its own trusted client-IP header instead of trusting whatever the browser sent
any `x-causeloop-*`	e.g. `X-CauseLoop-Role`, `X-CauseLoop-Tenant-Id`	Spoofing prevention. If the backend ever trusts an `X-CauseLoop-*` header for role or tenant scoping, a client that could set it directly could impersonate a different role or tenant. Stripping the entire prefix (not just the two names the proxy might inject) closes that off even for headers the proxy doesn’t currently use.

After stripping, the proxy injects exactly one header of its own, computed server-side from the trusted ingress chain:

const clientIp = clientIpFromTrustedIngress(request);
if (clientIp) {
  forwardHeaders.set("x-causeloop-client-ip", clientIp);
}

clientIpFromTrustedIngress reads the last (right-most) entry of the incoming x-forwarded-for chain — the hop closest to the frontend’s own edge, i.e. the one the frontend’s own hosting platform appended and can be trusted — and validates it’s a real IP (with node:net’s isIP, including the bracketed-IPv6-with-port case) before forwarding it. This is what lets the backend’s login rate limiter (services/api/auth/rate_limit.py) key on a real client IP without ever trusting a client-supplied header directly.

Body streaming

For any method other than GET/HEAD, the request body is streamed straight through rather than buffered:

backendResponse = await fetch(targetUrl, {
  method,
  headers: forwardHeaders,
  body: hasBody ? request.body : undefined,
  ...(hasBody ? { duplex: "half" } : {}),
  redirect: "manual",
});

duplex: "half" is required by undici (Node’s fetch implementation) whenever the request body is a ReadableStream rather than a buffered value — without it, streaming a multipart file upload (see Admin portal wiring and Tenant console wiring for the upload call sites) would throw. redirect: "manual" stops fetch from silently following a redirect the backend might send — any redirect response is passed straight back to the browser as-is instead of being resolved server-side.

Response handling

Two things happen on the way back:

Backend-unreachable → stable 502. If fetch() itself throws (connection refused, DNS failure, TLS error), the handler catches it and returns NextResponse.json({ detail: "backend unavailable" }, { status: 502 }) instead of letting Next.js turn an unhandled exception into an opaque 500.
Header filtering, with one deliberate exception. HOP_BY_HOP_RESPONSE_HEADERS (connection, content-length, content-encoding, transfer-encoding) are dropped — fetch() transparently decompresses a gzip/br body while leaving the stale content-encoding header in place, and forwarding it verbatim would make the browser try to re-decompress an already-decoded body. Every other header is appended, not set:

backendResponse.headers.forEach((value, key) => {
  if (!HOP_BY_HOP_RESPONSE_HEADERS.has(key.toLowerCase())) {
    responseHeaders.append(key, value);
  }
});

.append matters specifically for set-cookie: a login response carries two separate Set-Cookie headers (the session cookie and the CSRF cookie — see Authentication), and the Fetch API’s Headers.forEach iterates each one as its own entry rather than comma-joining them the way it does for every other header name. Using .set here would silently keep only the last cookie and drop the other — exactly the kind of bug that would show up as “CSRF token missing” errors on every mutating request right after login.

Error passthrough

The proxy does not reshape error bodies. A 409, 422, or 401 from the backend passes through with its original status code and JSON body untouched — { "detail": ... } in every case, since every product router raises HTTPException(status_code=..., detail=...). The frontend’s own API client layer (src/lib/api/client.ts) is what turns that into a typed ApiError:

async function handleResponse<T>(response: Response): Promise<T> {
  if (!response.ok) {
    const body = await parseJsonSafe(response);
    throw new ApiError(response.status, extractDetail(body));
  }
  return (await parseJsonSafe(response)) as T;
}

See Errors and conventions for the full status-code contract this depends on.

CSRF: the one thing that doesn’t route through here

The proxy forwards whatever x-csrf-token header the caller already set — it does not add one itself. Every mutating call site is responsible for reading the cookie and attaching the header, via one of two small helpers that both do the same thing:

adminSend() in src/lib/api/adminAuth.ts (staff portal mutations)
tenantSend() in src/lib/api/tenantAuth.ts (tenant console mutations)

export async function adminSend<T>(method, path, body): Promise<T> {
  const csrf = readCsrfToken();
  return apiSend<T>(method, path, body, {
    headers: csrf ? { "x-csrf-token": csrf } : {},
  });
}

readCsrfToken() (src/lib/authCookies.ts) reads document.cookie directly — this is the one cookie in the whole system a browser script is allowed to read, by design (see Authentication for the backend’s double-submit verification).

`/api/workspaces`: the one route that isn’t proxied

src/app/api/workspaces/route.ts is a second, unrelated Next.js route — not a case inside the catch-all. The login page (src/app/login/page.tsx) fetches it before any session exists at all, so it can’t go through the session-gated proxy; instead this route calls the backend directly and reshapes the response defensively. (The fetched list is currently stored in the login page’s workspaces state and not rendered anywhere — the Organization field is a plain text input defaulting to "yc-demo", not a picker.)

export async function GET(): Promise<Response> {
  try {
    const response = await fetch(`${BACKEND_URL}/workspaces`, { cache: "no-store" });
    if (!response.ok) {
      return NextResponse.json({ workspaces: [], degraded: true });
    }
    const payload = (await response.json()) as BackendWorkspace[];
    const workspaces = (Array.isArray(payload) ? payload : [])
      .filter((workspace) => typeof workspace.client_id === "string")
      .map((workspace) => ({ /* ...defaulted fields... */ }));
    return NextResponse.json({ workspaces });
  } catch {
    return NextResponse.json({ workspaces: [], degraded: true });
  }
}

Every failure mode — a non-2xx response, a malformed payload, a thrown network error — degrades to { workspaces: [], degraded: true } rather than surfacing an error to a not-yet-authenticated visitor. The backend endpoint it calls, GET /workspaces, is itself unauthenticated and deliberately minimal: it serializes each live tenant as a WorkspaceSummary (client_id, company, industry, status — populated from the tenant’s slug/name/industry with status hardcoded to "live"), nothing an anonymous visitor shouldn’t see. This is a different route from the staff-authenticated tenant registry (GET /admin/tenants, see Admin portal wiring), which returns full tenant detail behind a session.

Sequence: one authenticated request end to end

The following traces a single call — RemediationView fetching the tenant’s CAP list — from render to response. Every hop after the browser’s own request is server-to-server: the frontend’s Node process talking to the backend’s origin directly, over whatever private network the two share in the deployed environment (see Environments). Nothing about the backend’s real hostname, port, or TLS configuration is ever visible to the browser.

Using the API

Frontend Integration

Endpoints

Legacy Surfaces

Proxy and sessions

Why a proxy at all

The catch-all route

Path construction

The session gate

Header handling

Body streaming

Response handling

Error passthrough

CSRF: the one thing that doesn’t route through here

`/api/workspaces`: the one route that isn’t proxied

Sequence: one authenticated request end to end

​Why a proxy at all

​The catch-all route

​Path construction

​The session gate

​Header handling

​Body streaming

​Response handling

​Error passthrough

​CSRF: the one thing that doesn’t route through here

​/api/workspaces: the one route that isn’t proxied

​Sequence: one authenticated request end to end

​Related

Why a proxy at all

The catch-all route

Path construction

The session gate

Header handling

Body streaming

Response handling

Error passthrough

CSRF: the one thing that doesn’t route through here

`/api/workspaces`: the one route that isn’t proxied

Sequence: one authenticated request end to end

Related