Backend for frontend

Introduction

A token stored in localStorage can be read by any script on the page, so one cross-site scripting bug leaks every session. A backend-for-frontend (BFF) removes the token from the browser altogether. The browser talks only to its own web server, on the same origin. That server keeps the access and refresh tokens in httpOnly cookies, which no script can read, and calls the Navree API with Authorization: Bearer.

The API doesn't change. It stays a plain bearer-token API that mobile apps, partners, other services and the BFF all call the same way. The BFF is the web app's own small backend: it signs in, forwards requests, rotates tokens and enforces the same-origin rule that protects the cookies.

The reference CRM has two front ends, each with a BFF that keeps the same contract: apps/crm-web, a Next.js app with its BFF in src/lib/bff/, and apps/crm-nuxt, a Nuxt app with its BFF in server/lib/bff.ts. navree new --ui next generates a smaller version of the Next.js one, and the SaaS starter kit ships the full one for either framework. The code on this page comes from the CRM; where the two differ, it shows both.

The shape

The browser calls same-origin paths: /api/auth/login, /api/v1/deals, /broadcasting/auth. Route handlers in the Next.js app, or server routes in the Nuxt app, forward them to the API at NAVREE_API_URL with the same path, so the browser's API client and the API's OpenAPI document agree on every path.

One BFF, two frameworks

The BFF itself is framework-free TypeScript: createBff takes the API's URL and a few options and returns functions that take a web Request and return a Response. Next.js route handlers already speak Request and Response; in Nuxt, Nitro's toWebRequest(event) turns an event into one and a handler may return a Response. So each framework adds only a thin layer: one instance of the BFF and a one-line route per path. The auth routes cover sign-in, the two-factor step, refresh and sign-out; the catch-all forwards every other /api/* call.

Either instance holds the single-flight refresh map (below), so it is shared by every request the server handles. The Nuxt app also has a server middleware, server/middleware/session-gate.ts, that sends a page request with neither token cookie to /login?next=... before the app loads; whether a cookie is still valid stays the API's call.

Signing in

The browser posts the email and password to the BFF's /api/auth/login. The BFF calls POST /api/auth/login on Navree, keeps both tokens in cookies and returns only the user:

/** `POST /api/auth/login`: keeps the tokens, returns `{user}`. */
async function login(request: Request): Promise<Response> {
  if (!originAllowed(request)) return errorResponse(403, "Invalid origin");
  let upstream: Response;
  try {
    upstream = await upstreamFetch(`${apiUrl}/api/auth/login`, {
      method: "POST",
      cache: "no-store",
      headers: upstreamHeaders(request),
      body: await request.arrayBuffer(),
    });
  } catch {
    return unreachable();
  }
  if (!upstream.ok) return passThrough(upstream);

  const data = (await upstream.json().catch(() => ({}))) as LoginBody;
  if (data.two_factor_required === true && typeof data.challenge_token === "string") {
    // Two-factor account: no session yet. The challenge token waits in a cookie only the code step receives.
    const headers = new Headers({ "content-type": "application/json" });
    setChallengeCookie(headers, data.challenge_token, data.expires_in);
    const body = { two_factor_required: true, expires_in: data.expires_in ?? 300 };
    return new Response(JSON.stringify(body), { status: 200, headers });
  }
  if (!isTokenPair(data)) return errorResponse(502, "Unexpected login response from the API");
  return signedIn(upstream, data);
}

A failed login passes Navree's answer through unchanged (a 401 "Invalid credentials", or a 429 from the login throttle), so the form shows the API's message. The route that calls it is a few lines in either framework:

import { bff } from "@/lib/bff/server";

/** Signs in at Navree, keeps the tokens in httpOnly cookies, returns `{user}`. */
export function POST(request: Request): Promise<Response> {
  return bff.login(request);
}

export const dynamic = "force-dynamic";

import { useBff } from "../../lib/instance";

/** Signs in at Navree, keeps the tokens in httpOnly cookies, returns `{user}` (or a two-factor challenge). */
export default defineEventHandler((event) => useBff().login(toWebRequest(event)));

The BFF sets three cookies, all HttpOnly; SameSite=Lax, and Secure in production:

Accounts with two-factor authentication get a challenge instead of tokens. The challenge waits in navree_2fa, which only the code step receives. The login page then posts {code} or {recovery_code} to /api/auth/2fa/verify, and the BFF adds the challenge token, calls Navree and stores the tokens like a normal login. A wrong code keeps the challenge, so the person can try again until it expires.

Forwarding requests

Every other /api/* request goes through one catch-all route. In Nuxt a file without a method suffix answers every method:

import { bff } from "@/lib/bff/server";

/** Every `/api/*` call from the browser is forwarded to Navree with the bearer token from the httpOnly cookie. */
function handle(request: Request): Promise<Response> {
  return bff.proxy(request, new URL(request.url).pathname);
}

export const dynamic = "force-dynamic";
export { handle as DELETE, handle as GET, handle as HEAD, handle as PATCH, handle as POST, handle as PUT };

import { useBff } from "../lib/instance";

/**
 * Every `/api/*` call from the browser goes to Navree with the bearer token
 * from the httpOnly cookie (refreshed once on a 401). Mutations must come from
 * this app's own origin.
 */
export default defineEventHandler((event) => {
  const request = toWebRequest(event);
  return useBff().proxy(request, new URL(request.url).pathname);
});

proxy sends the request to the same path on the API with:

• Authorization: Bearer and the access token from navree_at;
• an allow-list of request headers: accept, accept-language, content-type, if-none-match, if-modified-since, user-agent and x-request-id. Cookies never leave the BFF;
• the body, buffered so it can be replayed after a refresh.

The API's response comes back with its status, its body (streamed, so a CSV export isn't buffered) and an allow-list of headers, including etag, location, retry-after, x-request-id and the x-ratelimit-* headers. Authenticated responses are fetched with cache: "no-store", so they never land in a shared cache.

When an /api/auth/* response carries a token pair (changing the password returns a new one), the BFF moves the pair into the cookies and strips it from the body. The browser gets {user} or a 204.

Rotating refresh tokens

Navree's access tokens are short-lived JWTs, and its refresh tokens rotate: every refresh revokes the token it was given and issues the next one in the same family. A refresh token that is used twice means two parties hold it, so Navree revokes the whole family and the session ends. See Rotation and families.

That makes refreshing from a browser app subtle. A page that fires five requests the moment the access token expires gets five 401s, and five refreshes with the same token would end the session. The BFF therefore refreshes once per refresh token, and every concurrent request waits for that one call:

/** Single-flight refresh keyed by the refresh token being spent. */
function refresh(refreshToken: string, request: Request): Promise<TokenPair | null> {
  const now = Date.now();
  for (const [key, entry] of refreshes) {
    if (entry.settledAt !== undefined && now - entry.settledAt > refreshGraceMs) refreshes.delete(key);
  }
  const existing = refreshes.get(refreshToken);
  if (existing) return existing.promise;
  const entry: { promise: Promise<TokenPair | null>; settledAt?: number } = {
    promise: callNavreeRefresh(refreshToken, request).then((pair) => {
      entry.settledAt = Date.now();
      if (!pair) refreshes.delete(refreshToken);
      return pair;
    }),
  };
  refreshes.set(refreshToken, entry);
  return entry.promise;
}

The rules proxy follows:

1. If the access cookie has expired but the refresh cookie remains, refresh before sending.
2. Send the request. On a 401, refresh once and retry with the new access token.
3. When a refresh succeeds, set both cookies on the response.
4. When it fails, clear both cookies and pass the 401 on. The browser's API client sends the user to /login.

A completed refresh is remembered for 30 seconds (refreshGraceMs), so a request that was already in flight with the old cookie gets the new pair instead of spending the old token a second time.

The single-flight map lives in one server process. When you run several BFF processes behind a load balancer, route each browser to one of them (sticky sessions), or two processes could spend the same refresh token at once and end the session.

Signing out

POST /api/auth/logout revokes the refresh token at Navree, so the stolen copy of a cookie is worthless afterwards, then clears both cookies. If the access token has already expired, the BFF refreshes first to get a bearer token for the logout call. If Navree can't be reached, the browser is signed out anyway. Send {"all": true} to end every session of the user.

CSRF protection

Cookies are sent with every request to their origin, so a page on another site could submit a form to the BFF and ride on the user's session. Two layers stop it:

• SameSite=Lax keeps the cookies off cross-site POST, PUT, PATCH and DELETE requests in browsers that support it.
• An origin check on every request that can change data. A request other than GET, HEAD or OPTIONS must carry an Origin header naming the app's own host (or one listed in APP_ORIGINS). A missing or foreign origin gets a 403 and never reaches the API:

/** Non-GET requests must come from this app: `Origin` host = the host the browser addressed. */
function originAllowed(request: Request): boolean {
  if (SAFE_METHODS.has(request.method.toUpperCase())) return true;
  const origin = request.headers.get("origin");
  if (!origin || origin === "null") return false;
  if (options.allowedOrigins?.includes(origin)) return true;
  let originHost: string;
  try {
    originHost = new URL(origin).host;
  } catch {
    return false;
  }
  const host = request.headers.get("x-forwarded-host")?.split(",")[0]?.trim() || request.headers.get("host");
  const ownHost = host ?? new URL(request.url).host;
  return originHost === ownHost;
}

Login, logout and the two-factor step are guarded the same way. Keep GET requests free of side effects and the two layers cover every route.

The API itself needs no CSRF token for this setup: it only ever sees bearer tokens, and Navree's session CSRF check applies to cookie sessions, not to bearer requests. If your app also signs users in with sessions, that check covers those requests.

Client addresses and rate limits

Navree's login throttle and per-IP rate limit key on the client's address. Behind a BFF, every browser reaches the API from the BFF's address, so all users would share one limit, and one person's wrong passwords would lock everyone out of that account.

The BFF can name the browser in X-Forwarded-For, but only when it can trust the address itself:

• The browser's own X-Forwarded-For and X-Real-IP are never passed on: anyone can forge them.
• Put the Next.js server behind a reverse proxy that appends the client to X-Forwarded-For, make Next.js reachable only through it, and set NAVREE_TRUSTED_PROXY_HOPS to the number of such proxies. The BFF then sends the API one X-Forwarded-For entry: the address the outermost proxy saw.

On the API side, list the BFF's address in http.trusted_proxies, so the API believes the header only from the BFF:

[http]
addr = "127.0.0.1:8080"
api_prefix = "/api"
# crm-web's BFF calls from here for every browser and names the browser in
# X-Forwarded-For, so rate limits and the login throttle are per browser.
# (Also the CRM's built-in default; list the BFF's address in production.)
trusted_proxies = ["127.0.0.1", "::1"]

The CRM tests this from the API's side: six wrong passwords from one browser are throttled, and another browser signing in to the same account still succeeds.

#[tokio::test]
async fn the_login_throttle_is_per_browser_behind_the_bff() {
    let crm = crm().await;
    for _ in 0..5 {
        login(&crm, "203.0.113.10", "wrong password")
            .await
            .assert_status(401);
    }
    login(&crm, "203.0.113.10", "wrong password")
        .await
        .assert_status(429);
    // Another browser signs in as the same user.
    login(&crm, "203.0.113.20", DEMO_PASSWORD)
        .await
        .assert_status(200);
    crm.shutdown().await;
}

Real time through the BFF

The WebSocket goes straight from the browser to Navree's WebSocket server: it carries no token, only a socket id. Private channels need authorization, and that request needs the user's credentials, so it goes through the BFF like any other call:

import { bff } from "@/lib/bff/server";

/** Private-channel authorization: forwarded to Navree with the bearer token. */
export function POST(request: Request): Promise<Response> {
  return bff.proxy(request, "/broadcasting/auth");
}

export const dynamic = "force-dynamic";

import { useBff } from "../../lib/instance";

/** Private-channel authorization for pusher-js: forwarded to Navree with the bearer token. */
export default defineEventHandler((event) => useBff().proxy(toWebRequest(event), "/broadcasting/auth"));

The Nuxt route lives under server/routes/ rather than server/api/, so it answers at /broadcasting/auth with no /api prefix, the same path as in the Next.js app.

The browser's pusher-js client uses a custom authorizer that posts {socket_id, channel_name} to that same-origin route. Navree checks the channel against the user's access rules and signs the subscription. List the web app's origin in realtime.allowed_origins so the WebSocket handshake is accepted. If the socket can't connect, the CRM keeps working with refetch-on-focus. See Broadcasting.

Calling the API from the browser

The browser's API client is generated from the API's OpenAPI document and points at the BFF, so it needs no token handling at all: same-origin credentials, Accept: application/json, and hooks for 401 and 403. Both front ends use openapi-fetch with types from openapi-typescript; the Nuxt app's client is app/lib/api/client.ts.

const client = createClient<paths>({
  baseUrl,
  credentials: "same-origin",
  headers: { Accept: "application/json" },
  fetch: fetchApi,
});

Because the BFF keeps the API's paths, client.GET("/api/v1/deals/board") is checked against the document by the TypeScript compiler and lands on the same route at the API. See API-first.

Configuration

The BFF reads its settings from the environment when the server runs, not when it is built, so they change without a rebuild. The Nuxt app reads the same names when its BFF is first used (NUXT_NAVREE_API_URL and NUXT_COOKIE_SECURE work too):

The Nuxt app takes the browser settings as public runtime config, so they too change without a rebuild: NUXT_PUBLIC_WS_HOST, NUXT_PUBLIC_WS_PORT, NUXT_PUBLIC_PUSHER_KEY and NUXT_PUBLIC_REALTIME. In the CRM its NAVREE_API_URL and NUXT_PUBLIC_WS_PORT default to port 8092, where pnpm api runs a copy of the API for that app.

On the API, nothing is BFF-specific beyond http.trusted_proxies and realtime.allowed_origins. Two settings are worth a look:

• auth.registration = false when accounts are created by admins, as in the CRM. The BFF then has no sign-up route to forward.
• auth.jwt.audience to issue tokens for one audience ("crm-web"), so a token minted for the web app is refused by another API that checks a different audience.

Testing

The BFF is framework-free TypeScript: createBff takes the API URL and a fetch, so its unit tests run against a scripted fake API without a server. This one proves that three concurrent requests share one refresh:

it("shares one refresh between concurrent requests (refresh tokens rotate; reuse revokes the family)", async () => {
  let refreshCalls = 0;
  const navree = fakeNavree({
    "GET /api/v1/deals/board": (call) =>
      call.headers.get("authorization") === "Bearer AT2"
        ? Response.json({ ok: true })
        : Response.json({ statusCode: 401, message: "Unauthorized", error: "Unauthorized" }, { status: 401 }),
    "POST /api/auth/refresh": async () => {
      refreshCalls += 1;
      await new Promise((r) => setTimeout(r, 10));
      return Response.json(tokens(2));
    },
  });
  const bff = createBff({ apiUrl: API, fetch: navree.fetch });
  const cookies = { [ACCESS_COOKIE]: "AT1", [REFRESH_COOKIE]: "RT1" };

  const responses = await Promise.all(
    [1, 2, 3].map(() => bff.proxy(request("/api/v1/deals/board", { cookies }), "/api/v1/deals/board")),
  );

  expect(responses.map((r) => r.status)).toEqual([200, 200, 200]);
  expect(refreshCalls).toBe(1);
});

The same suite covers the origin check, login and logout, two-factor sign-in, tokens stripped from responses and the client-address rules. On top of that:

• apps/crm-nuxt runs the same kind of suite against its own BFF (tests/unit/bff.test.ts), and tests/unit/nitro-handlers.test.ts drives the real Nitro route handlers and the session gate, mounted on an h3 app the way Nitro mounts them: login keeps both tokens in httpOnly cookies, an expired session refreshes once and rotates both cookies, a cross-origin mutation gets a 403.
• apps/crm-api/tests/bff.rs checks the API's side: per-browser throttling and rate limits behind a trusted BFF.
• E2E_REAL_API=1 pnpm e2e in apps/crm-web, and pnpm e2e in apps/crm-nuxt, run the Playwright specs against the real API and a production build of the front end, end to end. The Nuxt app's bff.spec.ts checks the CSRF refusal, the refresh-cookie rotation and that signing out revokes the refresh token at the API.

Starting your own

navree new generates the pattern for you:

navree new acme --ui next                # the API plus web/, a Next.js app with a BFF
navree new acme --kit saas               # the full SaaS kit on Next.js: BFF, sign-in, workspaces, billing, settings, admin

--ui next writes web/lib/bff.ts with sign-in, sign-out, forwarding, a refresh on 401 and the origin check, and navree dev starts both servers. The SaaS starter kit builds on the CRM's complete Next.js BFF. To see both running, see the CRM showcase.

The CRM's BFF is also a package: @navree/bff has everything on this page, plus sessions for server rendering and test helpers, and @navree/next and @navree/nuxt mount it in a Next.js or Nuxt app in a few lines.