Backend for Frontend

The IAM service supports the Backend for Frontend or "BFF" pattern natively. Instead of exposing JWT tokens to the browser, a server-side proxy sits between the client and the IAM service. The proxy holds tokens in httpOnly cookies, rotates them transparently, and relays authorization decisions back to the frontend. The browser never sees a raw token.

The service provides three endpoints dedicated to BFF communication:

• GET /secret/data answers "is this user authorized?" and returns the user's roles.
• GET /secret/accesstoken/metadata answers "how long until this token expires?" and computes a proactive rotation hint.
• GET /operational/config shares the cookie domain and access token TTL so the proxy can set cookies correctly.

Both /secret routes run behind the full middleware chain: access token extraction, refresh token validation, device fingerprinting, checkForActiveMfa, and anomaly-aware JWT verification. The metadata route adds a strict cookie-only guard. The /operational/config endpoint is gated by IP address instead, and the service can also apply HMAC globally.

auth-h3client is the companion Nuxt module that implements the proxy side of the pattern. It consumes the three IAM endpoints above and handles login, signup, logout, OAuth, MFA relay, CSRF, token rotation, and user data caching automatically. it can also be used as h3 / nitro client directly. See the auth-h3client documentation for its full API reference, configuration, and composables.

The pattern

In a traditional SPA, the browser stores access and refresh tokens in localStorage, sessionStorage, or cookies and sends them directly to resource APIs. This exposes tokens to XSS attacks, browser extensions, and third-party scripts. The BFF pattern eliminates this exposure.

IAM service routes

The IAM service exposes two BFF-specific routes under the /secret prefix and one configuration endpoint under /operational. These routes are mounted after the authentication, token rotation, and magic link route groups in the Express middleware chain.

// service.ts (simplified mounting order)
app.use(authenticationRoutes)     // /signup, /login, /auth/OAuth/*
app.use(tokenRotationRoutes)      // /auth/user/refresh-session, /auth/logout
app.use(magicLinks)               // /auth/verify-mfa/*, /auth/reset-password/*
app.use(allowBff)                 // /secret/data, /secret/accesstoken/metadata
app.use(apiProtectedRoutes())     // /api/manage/*
app.use('/operational/config', sendOperationalConfig)

Route table

Middleware chain

Every request to /secret/data and /secret/accesstoken/metadata passes through five shared middleware functions before reaching the controller. The metadata route adds a sixth guard. Each middleware either populates request context for downstream handlers or terminates the request with an error.

requireAccessToken

Extracts the JWT access token from the Authorization header. The header must use the Bearer scheme. If the header is missing, empty, or uses a different scheme, the middleware responds with HTTP 401 and { ok: false, error: "Missing Bearer token" }. On success, it stores the raw token string on req.token for the next middleware to verify.

requireRefreshToken

Reads the session cookie from the request. If the cookie is absent, the middleware responds with HTTP 401 and { error: "Refresh token missing" }. It does not validate the token's contents or hash; that responsibility belongs to rotation endpoints. Its purpose here is to confirm that the caller holds a session cookie, which proves the request comes from a context where the user has logged in.

getFingerPrint

Extracts device and network metadata from the request headers and attaches a fingerprint to the request context. This includes the raw User-Agent, the resolved IP address, geolocation data, and parsed browser and device details. The fingerprint is consumed by protectRoute for anomaly scoring. See Fingerprinting for the full list of signals collected.

checkForActiveMfa

Hashes the session cookie and checks anomaliesCache() for an unresolved MFA state. If the current session already has a resolvable MFA challenge, the middleware returns 202 { mfa: true }. If the cached anomaly is not resolvable, it returns 401 { error: 'Re-login is required', ... }. Otherwise it calls next() and lets protectRoute continue.

protectRoute

The core security layer. It performs two operations:

1. JWT verification. Calls verifyAccessToken with the token from req.token. The verification uses a cache-backed lookup: the SHA-256 hash of the token is checked against stored access token records. If the token is revoked, expired, or not found, the middleware returns HTTP 401.
2. Anomaly detection. Calls strangeThings() with the verified token data and the fingerprint from getFingerPrint. This function runs a series of checks:

   Check	Trigger	Result
   Token not found	SHA-256 hash does not match any stored record	HTTP 401, invalid token
   Token revoked	Token's valid flag is false or usage_count > 1	HTTP 401, invalid token
   Canary mismatch	canary_id cookie does not match the session record	HTTP 401 + MFA challenge
   Idle session	User's last_seen exceeds 24 hours	HTTP 401 + MFA challenge
   Session overflow	Active sessions exceed maxAllowedSessionsPerUser	HTTP 401 + MFA challenge
   Token spam	3 or more tokens issued within 10 minutes	Revoke all tokens, HTTP 401
   IP range mismatch	Client IP falls outside the known range for this session	HTTP 401 + MFA challenge
   High suspicion score	Suspicion score reaches 25% of the ban threshold	HTTP 401 + MFA challenge
   Proxy/hosting detected	IP identified as proxy or hosting and user is not allowlisted	HTTP 401 + MFA challenge
   Device fingerprint mismatch	Browser, OS, or location differs from the session baseline	HTTP 401 + MFA challenge

   
   When an anomaly triggers an MFA challenge, the IAM service responds with HTTP 202 and sends a magic link email. The BFF is expected to relay this 202 to the browser so the user can verify their identity. Anomalies that trigger within the MFA bypass window are skipped.

On success, protectRoute populates req.user with:

acceptCookieOnly (metadata route only)

The metadata route adds an extra guard after protectRoute. This middleware enforces a strict contract: the request must carry cookies and nothing else. It rejects the request under any of these conditions:

This prevents injection vectors on an endpoint whose only input should be the cookies attached by the browser. No body, query parameters, or content-type declarations are legitimate for this route.

Authorization check: GET /secret/data

The allowBffAccess controller validates that the upstream middleware successfully populated req.user, then confirms that the user and their visitor record exist in the database. If everything checks out, it returns a JSON payload with the authorization decision.

Response shape

{
  "userId": 42,
  "authorized": true,
  "ipAddress": "203.0.113.10",
  "userAgent": "Mozilla/5.0 ...",
  "date": "2025-01-15T10:30:00.000Z",
  "roles": ["admin", "editor"]
}

Error responses

Observability

Every request to this endpoint produces a structured log entry with the client IP, request ID, user agent, original URL, and canary_id cookie value. Successful authorizations log at info level. Failed attempts log at warn level with the specific reason. Database errors log at error level without exposing the error details in the response.

Token metadata: GET /secret/accesstoken/metadata

The getAccessTokenPayload controller returns the decoded JWT payload along with computed TTL information. The BFF proxy uses this data to decide whether to proactively rotate the access token before it expires.

Response shape

{
  "authorized": true,
  "ipAddress": "203.0.113.10",
  "userAgent": "Mozilla/5.0 ...",
  "date": "2025-01-15T10:30:00.000Z",
  "roles": ["admin"],
  "payload": {
    "sub": "42",
    "visitor": "v_abc123",
    "jti": "tok_xyz789",
    "roles": ["admin"],
    "iat": 1736934600,
    "exp": 1736935500,
    "aud": "example.com",
    "iss": "example.com"
  },
  "msUntilExp": 540000,
  "refreshThreshold": 225000,
  "shouldRotate": false
}

TTL computation

The controller computes timing values from the JWT's iat and exp claims combined with the configured access token TTL:

TTL_MS     = config.jwt.access_tokens.expiresInMs ?? 900000   (default: 15 minutes)
THRESHOLD  = TTL_MS * 0.25                                    (25% of TTL)
iatMs      = payload.iat * 1000                               (or Date.now() if missing)
expMs      = payload.exp * 1000                               (or iatMs + TTL_MS if missing)
msUntilExp = max(0, expMs - now)
shouldRotate = msUntilExp <= THRESHOLD

When a 15-minute access token has less than 3 minutes and 45 seconds remaining, shouldRotate becomes true. The BFF can then call POST /auth/user/refresh-session to obtain fresh tokens before the current ones expire.

Error responses

How the BFF uses this endpoint

A typical BFF proxy calls this endpoint on every authenticated request to determine whether the access token is still usable or needs rotation:

Operational configuration: GET /operational/config

The IAM service exposes a non-authenticated endpoint that returns runtime settings the BFF needs for cookie management. This endpoint does not use the middleware chain. Instead, it is gated by IP address: only requests from the configured trusted client IP receive a response.

IP validation

The controller reads the raw socket address via req.socket.remoteAddress, strips the IPv4-mapped IPv6 prefix (::ffff:) if present, and compares the result against config.service.clientIp. If that field is not set, it falls back to config.service.proxy.ipToTrust. Any mismatch returns HTTP 403 with { error: "Forbidden" }.

Response shape

{
  "domain": ".example.com",
  "accessTokenTTL": 900000
}

The BFF typically calls this endpoint once at startup and caches the result. Since these values change only when the IAM service configuration changes, a 24-hour cache TTL is reasonable.

Exports for library consumers

The BFF routes and controllers are exported individually from the @riavzon/auth package. This allows library consumers to mount them in their own Express applications, compose them with additional middleware, or use the controllers standalone.

import {
  bffAccessRoute,
  allowBffAccess,
  getAccessTokenPayload,
  sendOperationalConfig
} from '@riavzon/auth'

The supporting middleware functions are also exported for building custom pipelines:

import {
  requireAccessToken,
  requireRefreshToken,
  protectRoute
} from '@riavzon/auth'

When using the IAM service in standalone mode, all routes are automatically mounted. When using the library, you can mount them yourself with your own middleware composition. For example, you could add rate limiting or logging middleware before the controller without modifying the IAM source.

HMAC integration

When the IAM service has HMAC authentication enabled (service.Hmac), the hmacAuth middleware runs before all route groups, including the BFF routes. Every request to /secret/data, /secret/accesstoken/metadata, and /operational/config must carry valid HMAC headers in addition to the JWT and refresh token cookies.

The BFF proxy must sign each outbound request with the same clientId and sharedSecret configured on the IAM service. See HMAC Authentication for the signature format, clock-skew tolerance, and replay protection details.

Cookie lifecycle

The BFF pattern relies on cookies that flow between the browser, the BFF proxy, and the IAM service. The IAM service sets refresh token cookies directly on authentication responses (POST /login, POST /signup, POST /auth/user/refresh-session). The BFF proxy is responsible for setting the access token cookie on the browser and forwarding refresh token cookies in both directions.

The IAM service validates the session and canary_id cookies on every BFF request. The access token arrives as a Bearer header, not from a cookie, because the BFF extracts it from __Secure-a and places it in the Authorization header before calling the IAM.

What the BFF proxy expects from the IAM service

The BFF proxy needs specific response patterns from the IAM service to manage the session lifecycle. This table summarizes every IAM endpoint the BFF calls and what it expects in return.

Configuration reference (IAM side)

The following IAM service configuration fields directly affect BFF behavior. These are set in the IAM service's configuration file, not in the BFF proxy.

Trusted proxy

HMAC verification

Token settings

Using auth-h3client as the BFF proxy

auth-h3client is the companion Nuxt module that implements the BFF proxy side of the pattern for H3-based frameworks. When installed, it consumes every IAM endpoint listed above and provides:

• Automatic token rotation using GET /secret/accesstoken/metadata and POST /auth/user/refresh-session.
• Cookie management using domain and TTL values from GET /operational/config.
• HMAC signing on every outbound request to the IAM service.
• mTLS support with optional client certificate authentication between the BFF and the IAM service.
• OAuth 2.0 and OpenID Connect client with pre-configured providers (Google, GitHub, X/Twitter, LinkedIn) and support for custom providers. Includes OIDC auto-discovery, PKCE, JWKS-based ID token verification, at_hash validation, per-provider scopes, custom email extraction callbacks, and configurable redirect URLs.
• Magic link handling for password reset, email change, and MFA verification flows with configurable redirect paths and a bounce page system.
• Client composables for browser-side auth state.
• Global middleware for IP validation, bot detection, CSRF cookie generation, and visitor fingerprint validation via signed canary cookies.
• Server-side route handler that wraps token rotation, authorization, and MFA relay into a single function.
• Input sanitization with configurable HTML sanitizer iterations, filename sanitization, and image file type/size validation.
• Structured logging via Pino with automatic secret redaction, configurable log levels, and per-request ID tracking.

The module auto-imports both client-side and server-side utilities, registers global middleware, and mounts authentication routes and OAuth routes with built-in CSRF enforcement.

For installation, configuration, composables API, and handler reference, see the auth-h3client documentation.

Rate limiting on BFF routes

The IAM service enforces rate limits on the middleware that protects BFF routes. These limits target the access token and refresh token validation layers, not the BFF controllers directly.

When a rate limit is hit, the IAM service responds with HTTP 429 and a Retry-After header. The BFF proxy should forward this header and status code to the browser.

Security layers

Requests to BFF routes pass through the full IAM security stack. This is the complete order of operations for a request reaching GET /secret/data or GET /secret/accesstoken/metadata:

Summary