Environment Configuration for Production Auth Architecture

import { sign, verify } from 'jsonwebtoken';
import { createHash, randomUUID } from 'crypto';
import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);
const ACCESS_TTL = 15 * 60; // 15 minutes
const REFRESH_TTL = 7 * 24 * 60 * 60; // 7 days
const PRIVATE_KEY = process.env.JWT_PRIVATE_KEY!;

interface TokenPayload {
  sub: string;
  jti: string;
  iat: number;
  exp: number;
  deviceFingerprint: string;
}

export async function issueTokenPair(userId: string, deviceFingerprint: string) {
  const jti = randomUUID();
  const now = Math.floor(Date.now() / 1000);

  const accessPayload: TokenPayload = {
    sub: userId,
    jti,
    iat: now,
    exp: now + ACCESS_TTL,
    deviceFingerprint,
  };

  const refreshPayload = {
    sub: userId,
    jti: randomUUID(),
    iat: now,
    exp: now + REFRESH_TTL,
    deviceFingerprint,
  };

  const accessToken = sign(accessPayload, PRIVATE_KEY, { algorithm: 'RS256' });
  const refreshToken = sign(refreshPayload, PRIVATE_KEY, { algorithm: 'RS256' });

  // Store refresh token metadata with TTL and rotation tracking
  const sess

ionKey = auth:refresh:${userId}:${deviceFingerprint}; await redis.setex( sessionKey, REFRESH_TTL, JSON.stringify({ jti: refreshPayload.jti, iat: now, exp: now + REFRESH_TTL, rotated: false, lastUsed: now, }) );

return { accessToken, refreshToken }; }

### Step 3: Refresh Rotation & Revocation Logic
```typescript
export async function rotateRefreshToken(refreshToken: string, deviceFingerprint: string) {
  const decoded = verify(refreshToken, process.env.JWT_PUBLIC_KEY!, {
    algorithms: ['RS256'],
  }) as TokenPayload;

  const sessionKey = `auth:refresh:${decoded.sub}:${deviceFingerprint}`;
  const sessionRaw = await redis.get(sessionKey);

  if (!sessionRaw) throw new Error('SESSION_NOT_FOUND');

  const session = JSON.parse(sessionRaw);

  // Detect refresh token reuse (possible compromise)
  if (session.jti !== decoded.jti || session.rotated) {
    // Compromise detected: revoke all sessions for this user
    await redis.del(`auth:refresh:${decoded.sub}:*`);
    throw new Error('TOKEN_REUSE_DETECTED');
  }

  // Invalidate old refresh token
  session.rotated = true;
  await redis.setex(sessionKey, REFRESH_TTL, JSON.stringify(session));

  // Issue new token pair
  return issueTokenPair(decoded.sub, deviceFingerprint);
}

Step 4: Validation Middleware

import { Request, Response, NextFunction } from 'express';

export function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'MISSING_ACCESS_TOKEN' });
  }

  try {
    const token = authHeader.split(' ')[1];
    const payload = verify(token, process.env.JWT_PUBLIC_KEY!, {
      algorithms: ['RS256'],
    }) as TokenPayload;

    // Bind validation: ensure device fingerprint matches
    const requestFingerprint = createHash('sha256')
      .update(req.ip + req.headers['user-agent'])
      .digest('hex')
      .slice(0, 16);

    if (payload.deviceFingerprint !== requestFingerprint) {
      return res.status(403).json({ error: 'DEVICE_MISMATCH' });
    }

    req.user = payload;
    next();
  } catch {
    return res.status(401).json({ error: 'INVALID_ACCESS_TOKEN' });
  }
}

Architecture Decisions & Rationale

• Short-lived access tokens: Limit exposure window. Even if intercepted, validity expires before exploitation scales.
• Server-side refresh storage: Enables deterministic revocation, rotation tracking, and compromise detection without breaking stateless access validation.
• Device fingerprint binding: Mitigates token replay across environments. Hashing IP + User-Agent reduces false positives from NAT/mobile networks while blocking cross-device theft.
• HttpOnly cookies for refresh: Prevents XSS token extraction. Access tokens remain in Authorization headers to support mobile/SPA clients securely.
• RS256/ES256 over HS256: Asymmetric signing allows public key distribution to services without exposing the private key, enabling secure microservice validation.

Pitfall Guide

1. Storing access tokens in localStorage or sessionStorage JavaScript-accessible storage is trivially exploitable via XSS. Production systems must isolate tokens from the JS execution context. Use HttpOnly cookies for refresh tokens and secure memory/secure storage for mobile clients.

2. Implementing static refresh tokens without rotation A long-lived refresh token that never rotates becomes a persistent credential. If leaked, it grants indefinite access until manual revocation. Rotation enforces single-use semantics and enables compromise detection on reuse.

3. Assuming stateless JWTs solve revocation JWTs cannot be revoked until expiry without server-side state. Blacklists scale poorly. Server-side session tracking with short TTLs provides instant revocation while preserving validation speed.

4. Skipping token binding or using overly strict binding Binding to exact IP fails on mobile networks and NAT. Binding to device fingerprint + subnet hash balances security and usability. Always validate binding at refresh, not on every access token validation, to avoid latency penalties.

5. Inconsistent expiration strategies across services Mixed TTLs, clock skew, and unsynchronized time sources cause premature expirations or validation gaps. Use NTP-synchronized servers, standardize TTLs at the gateway, and validate exp claims with a 30-second leeway.

6. Exposing authentication endpoints to credential stuffing Login and refresh endpoints are high-value targets. Implement progressive rate limiting, account lockout after failed attempts, and CAPTCHA or proof-of-work challenges for suspicious traffic patterns.

7. Coupling authentication logic with business domains Embedding token validation, session management, and user provisioning into application routes creates tight coupling and testing complexity. Isolate auth into a dedicated service or middleware layer with clear contracts.

Production Bundle

Action Checklist

• Define token lifecycle: access TTL, refresh TTL, rotation policy, and revocation path
• Implement asymmetric signing (RS256/ES256) with public key distribution to validation services
• Store refresh tokens server-side with TTL, rotation tracking, and reuse detection
• Enforce HttpOnly, Secure, SameSite=Lax cookies for refresh token transport
• Bind tokens to device fingerprint + subnet hash; validate on refresh, not access
• Deploy progressive rate limiting and anomaly detection on auth endpoints
• Isolate authentication into a bounded context with explicit API contracts
• Run periodic token rotation audits and simulate breach containment drills

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
MVP / Low-risk internal tool	Stateless JWT + Redis blacklist	Fastest implementation, acceptable revocation delay	Low infrastructure cost
High-security SaaS / Fintech	Rotating refresh + server store + device binding	Instant revocation, breach isolation, compliance alignment	Moderate Redis/memory cost
Mobile-first app	Short-lived access + secure storage refresh + token binding	Mitigates device theft, supports offline validation	Higher client-side secure storage cost
Multi-tenant platform	Centralized auth service + per-tenant key rotation	Tenant isolation, auditability, scalable revocation	Higher architectural complexity

Configuration Template

# Environment Configuration for Production Auth Architecture
JWT_PRIVATE_KEY_PATH=./keys/private.pem
JWT_PUBLIC_KEY_PATH=./keys/public.pem
JWT_ALGORITHM=RS256
ACCESS_TOKEN_TTL=900
REFRESH_TOKEN_TTL=604800
REFRESH_STORAGE_TTL=604800
AUTH_COOKIE_SECURE=true
AUTH_COOKIE_SAME_SITE=Lax
AUTH_COOKIE_HTTP_ONLY=true
AUTH_RATE_LIMIT_WINDOW=300
AUTH_RATE_LIMIT_MAX=10
AUTH_DEVICE_BINDING=sha256:ip:ua
AUTH_COMPROMISE_ACTION=REVOKE_ALL
REDIS_URL=redis://auth-redis:6379/1
LOG_LEVEL=warn

Quick Start Guide

1. Generate asymmetric key pair: openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048 then extract public key
2. Configure environment variables using the template above; point REDIS_URL to a local or cloud Redis instance
3. Install dependencies: npm install jsonwebtoken ioredent express helmet cookie-parser
4. Deploy the token generation, rotation, and middleware modules; expose /auth/login, /auth/refresh, and /auth/logout endpoints
5. Run locally with node --env-file=.env server.ts; validate token flow using curl or Postman with HttpOnly cookie simulation