Auth and the BFF

A token in localStorage is one cross-site scripting bug away from leaking every session. @navree/bff keeps the tokens on the server: it is the backend-for-frontend of a web app on a Navree API, written on web-standard Request and Response. @navree/next mounts it as route handlers and @navree/nuxt as Nitro routes; any server that speaks web requests can mount it too.

Creating the BFF

import { createBff, bffOptionsFromEnv } from "@navree/bff";

export const bff = createBff(bffOptionsFromEnv());

// In a route that receives every /api/* and /broadcasting/auth request:
export const handle = (request: Request) => bff.handle(request);

Create one BFF per server process and share it: the refresh map that keeps refreshes single-flight lives in it. @navree/next and @navree/nuxt create theirs on the first request.

bff.handle(request) routes by path:

What the BFF guarantees

Cookies. The access token is in navree_at (Max-Age = the token's expires_in), the refresh token in navree_rt (30 days), both HttpOnly; SameSite=Lax; Path=/, and Secure in production. A pending two-factor challenge waits in navree_2fa on Path=/api/auth/2fa, so only the code step receives it. A token pair in any auth response (a password change answers one) replaces the cookies and is stripped from the body.

Refresh. When the access cookie is gone but the refresh cookie is left, the proxy refreshes before forwarding; on a 401 it refreshes once and retries. Navree rotates refresh tokens and revokes the whole family when one is spent twice, so the refresh is single-flight per refresh token: concurrent requests holding the same cookie share one refresh call, and a finished refresh is remembered for 30 seconds for requests still carrying the old cookie. A failed refresh clears both cookies and the response is the 401, so the browser goes to sign-in.

CSRF. A non-GET request must come from the app's own origin: its Origin header's host must be the host the browser addressed (X-Forwarded-Host, else Host), or be listed in allowedOrigins. Anything else gets 403 invalid_origin before the API is called.

Pass-through. Status and body stream through unchanged, so CSV exports and server-sent events arrive as the API sends them. The response headers that pass are cache-control, content-disposition, content-language, content-security-policy, content-type, etag, last-modified, location, referrer-policy, retry-after, vary, x-content-type-options, x-frame-options, x-request-id and every x-ratelimit-*; the API's own Set-Cookie never reaches the browser. Upstream requests use cache: "no-store".

Request headers. accept, accept-language, content-type, if-match, if-none-match, if-modified-since, last-event-id, user-agent and x-request-id are forwarded, plus the workspace: the request's X-Workspace header, or the navree_workspace cookie when there is none. Cookies never leave the BFF.

Client address. The browser's own X-Forwarded-For and X-Real-IP never reach the API. Behind trustedProxyHops reverse proxies that append the client to X-Forwarded-For, the BFF sends the API a single X-Forwarded-For with the address the outermost one saw. List the BFF's address in the API's http.trusted_proxies so the login throttle and per-IP rate limits apply per browser.

The BFF's own errors

The BFF answers some requests itself, in Navree's error shape:

Options

bffOptionsFromEnv(env?, defaults?) reads them from the environment at request time, so the API can move without a rebuild:

Sessions on the server

Server rendering, server routes and middleware need a usable token for the request they handle. bff.ensureSession(request) gives one:

const session = await bff.ensureSession(request);
// { status: "active" | "refreshed" | "anonymous" | "expired", accessToken?, setCookie: string[], cookieHeader? }

ensureSession reads the JWT's exp without verifying the signature, only to decide whether to refresh; the API verifies every token it receives. It shares the refresh map with the proxy, so a page and its first API call never spend the same refresh token twice. The Next.js proxy and the Nuxt session gate call it for every page.

With the token, call the API from the server:

const user = await bff.me(session.accessToken, bff.workspaceOf(request)); // null when signed out
const response = await bff.api("/api/v1/deals?page=2", { accessToken: session.accessToken, workspace: "acme" });

me() answers null for a missing or refused token and throws when the API is down, so a page can tell "signed out" from "unreachable".

Testing

@navree/bff/testing has the helpers the package's own tests use:

import { createBff } from "@navree/bff";
import { browserRequest, fakeNavree, readSetCookies, tokenPair } from "@navree/bff/testing";
import { expect, it } from "vitest";

it("signs in with httpOnly cookies", async () => {
  const navree = fakeNavree({
    "POST /api/auth/login": () => Response.json({ user: { id: "u1" }, ...tokenPair(1) }),
  });
  const bff = createBff({ apiUrl: "http://api.test", fetch: navree.fetch });

  const response = await bff.handle(
    browserRequest("http://app.test", "/api/auth/login", { method: "POST", body: { email: "[email protected]", password: "pw" } }),
  );

  expect(await response.json()).toEqual({ user: { id: "u1" } });
  expect(readSetCookies(response).navree_at.attrs).toContain("HttpOnly");
  expect(navree.calls[0].headers.get("authorization")).toBeNull();
});

Related