---
name: nextjs-bff-security
description: "Secure Next.js BFF proxy/auth/session boundaries when editing app/api routes, middleware, cookie/session parsing, header forwarding, API_URL handling, or trusted network assumptions."
---

# nextjs-bff-security

## When to use

- Modify Next.js API proxy routes under `apps/web/src/app/api`.
- Change session cookie parsing, login/logout/me handlers, or middleware auth gates.
- Alter forwarded headers (`X-Api-Key`, `X-User-Github-Id`) or upstream URL logic.
- Fix auth bypass, SSR leakage, redirect/CORS, or trust-boundary issues.

## When not to use

- Presentational component-only work with no API/session behavior changes.
- Backend-only authz changes that do not involve the web proxy/session layer.
- Non-security static content updates (docs/marketing pages).

## Preconditions

- Confirm authenticated session source is httpOnly cookie and validated server-side.
- Identify all proxy headers and ensure they are generated by BFF, not client-trusted.
- Verify production `API_URL` expectations and timeout/error behavior.
- Ensure middleware route matcher still covers dashboard/auth routes as intended.

## Step-by-step workflow

1. **Validate session gate**
   - Parse/verify session token server-side before proxying protected API calls.
   - Fail unauthorized requests with `401` or redirect flows per route type.
2. **Harden header trust model**
   - Set privileged headers inside BFF only; never trust client-supplied versions.
   - Keep API access keys server-only via env, never in browser-exposed bundles.
3. **Constrain upstream target**
   - Normalize production API base URLs to prevent insecure scheme/path surprises.
   - Reject invalid production targets (for example localhost in production).
4. **Preserve route protections**
   - Keep middleware checks for dashboard paths and auth route rate limiting.
   - Ensure route matcher updates include any new protected segments.
5. **Handle failures safely**
   - Return bounded, user-safe upstream error messages without leaking secrets.
   - Keep request timeouts below function max duration with headroom.
6. **Test auth and proxy behavior**
   - Verify unauthenticated proxy access is denied.
   - Verify authenticated flow sets/reads cookie and forwards correct backend identity.

## Anti-patterns

- Reading auth/session from localStorage instead of httpOnly cookies.
- Passing through client-provided `X-User-Github-Id` or `X-Api-Key` headers.
- Allowing wildcard upstream origins or insecure production localhost routing.
- Making protected dashboard routes accessible without middleware checks.
- Exposing backend tokens/keys in client-side JavaScript.

## Concrete file anchors

- `apps/web/src/app/api/v1/[...path]/route.ts`
- `apps/web/src/app/api/v1/auth/login/route.ts`
- `apps/web/src/app/api/v1/auth/callback/route.ts`
- `apps/web/src/app/api/v1/auth/me/route.ts`
- `apps/web/src/app/api/v1/auth/logout/route.ts`
- `apps/web/src/lib/auth/session.ts`
- `apps/web/src/lib/auth/constants.ts`
- `apps/web/src/lib/monorepo-env.ts`
- `apps/web/src/middleware.ts`
- `apps/api/src/app/api/users.py`

## Minimal verification checklist

- [ ] Protected proxy routes return `401` without valid session cookie.
- [ ] BFF sets backend auth headers internally and does not trust browser-provided values.
- [ ] Middleware still protects dashboard routes and auth endpoints are rate-limited.
- [ ] Production `API_URL` validation and timeout behavior work as expected.
- [ ] Web auth/proxy tests and typecheck pass.