Secure API design

{ schema: { body: CreateUserSchema }, preValidation: [app.jwt.verify], handler: async (req, reply) => { const { email, role, metadata } = CreateUserSchema.parse(req.body); // Business logic with validated data return { status: 'created', id: crypto.randomUUID() }; } });

### 4. Transport & Data Security
Enforce TLS 1.3 at the load balancer or reverse proxy. Encrypt sensitive fields at rest using envelope encryption. Strip stack traces and internal headers from responses.

```typescript
app.addHook('onSend', async (req, reply, payload) => {
  reply.headers['x-content-type-options'] = 'nosniff';
  reply.headers['x-frame-options'] = 'DENY';
  reply.headers['cache-control'] = 'no-store';
  return payload;
});

5. Rate Limiting & Abuse Prevention

Implement tiered limits: global, per-IP, per-user, and per-endpoint. Use token bucket algorithms for burst tolerance. Block abusive patterns, not just raw requests.

6. Logging, Monitoring & Incident Response

Structure logs with correlation IDs. Log authentication attempts, authorization failures, and schema violations. Forward to SIEM. Alert on anomaly spikes, not absolute thresholds.

Architecture Rationale

• Centralized Gateway vs Per-Service Auth: A gateway handles TLS termination, rate limiting, and token validation. Services receive pre-validated identities. This reduces cryptographic overhead and standardizes policy enforcement.
• Strict Validation Over Sanitization: Sanitization is error-prone and context-dependent. Strict schema rejection eliminates injection vectors at the boundary.
• Short-Lived Tokens + Refresh Rotation: Limits blast radius of token theft. Refresh tokens are rotated and bound to client fingerprints.

Pitfall Guide

1. Relying on Client-Side Validation Only Client validation improves UX but provides zero security. Attackers bypass UI constraints using raw HTTP clients. Always validate server-side with strict schemas. Production practice: treat client payloads as untrusted binary streams until parsed and validated.

2. Hardcoded or Weak Secret Management Embedding secrets in code or environment files exposes them to version control and container inspection. Use hashicorp vault, AWS Secrets Manager, or cloud KMS. Production practice: rotate secrets automatically, enforce least-privilege IAM roles, and never log secret material.

3. Overly Permissive CORS & Preflight Handling Wildcard origins (*) with credentials enabled allow cross-site request forgery and data exfiltration. Validate origins against a allowlist. Production practice: implement dynamic origin validation, restrict methods/headers, and cache preflight responses with short TTLs.

4. Ignoring JWT Lifecycle Management Long-lived tokens, missing expiry, or algorithm confusion (alg: none) create persistent access vectors. Production practice: enforce RS256/ES256, validate exp, iss, aud, implement token revocation lists or short TTLs with refresh rotation, and bind tokens to client fingerprints.

5. Exposing Internal Error Details & Stack Traces Verbose errors leak framework versions, file paths, and database schemas. Production practice: return generic error codes to clients, log full traces internally with correlation IDs, and implement custom error handlers that strip stack information.

6. Neglecting Idempotency & Replay Attacks Non-idempotent write operations allow duplicate charges or state corruption when clients retry. Production practice: require Idempotency-Key headers for POST/PUT, store keys with TTLs, and return cached responses for duplicate requests.

7. Inadequate Audit Logging & Traceability Missing logs prevent forensic analysis and compliance reporting. Production practice: log authentication events, authorization decisions, data access patterns, and configuration changes. Use structured JSON with trace_id, user_id, resource, action, and outcome.

Production Bundle

Action Checklist

• Threat model attack surfaces before route implementation
• Enforce strict server-side validation with schema rejection
• Implement short-lived JWT/OIDC tokens with refresh rotation
• Configure tiered rate limiting (global, IP, user, endpoint)
• Manage secrets via centralized vault with automatic rotation
• Strip internal error details and enforce security headers
• Implement idempotency keys for all state-mutating operations
• Structure audit logs with correlation IDs and forward to SIEM

Decision Matrix

Configuration Template

// security.config.ts
import { FastifyInstance } from 'fastify';
import fastifyJwt from '@fastify/jwt';
import fastifyHelmet from '@fastify/helmet';
import fastifyRateLimit from '@fastify/rate-limit';
import fastifyCors from '@fastify/cors';

export async function secureApiSetup(app: FastifyInstance) {
  await app.register(fastifyJwt, {
    secret: process.env.JWT_SECRET!,
    sign: { expiresIn: '15m', algorithm: 'RS256' },
    verify: { algorithms: ['RS256'], maxAge: '15m' }
  });

  await app.register(fastifyHelmet, {
    contentSecurityPolicy: {
      directives: { defaultSrc: ["'self'"], imgSrc: ["'self'"], styleSrc: ["'self'"] }
    },
    hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
    noSniff: true,
    referrerPolicy: { policy: 'strict-origin-when-cross-origin' }
  });

  await app.register(fastifyCors, {
    origin: (origin, cb) => {
      const allowed = process.env.ALLOWED_ORIGINS?.split(',') || [];
      if (!origin || allowed.includes(origin)) cb(null, true);
      else cb(new Error('Not allowed by CORS'));
    },
    credentials: true,
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
  });

  await app.register(fastifyRateLimit, {
    max: 100,
    timeWindow: '1 minute',
    keyGenerator: (req) => req.ip || req.headers['x-forwarded-for'] as string,
    errorResponseBuilder: () => ({ error: 'Rate limit exceeded', retryAfter: 60 })
  });

  app.addHook('onSend', async (req, reply) => {
    reply.headers['x-content-type-options'] = 'nosniff';
    reply.headers['x-frame-options'] = 'DENY';
    reply.headers['cache-control'] = 'no-store, no-cache, must-revalidate';
    reply.headers['permissions-policy'] = 'geolocation=(), microphone=(), camera=()';
  });

  app.setErrorHandler((error, req, reply) => {
    req.log.error({ err: error, trace_id: req.id });
    reply.status(error.statusCode || 500).send({
      error: 'Request failed',
      code: error.statusCode || 500,
      trace_id: req.id
    });
  });
}

Quick Start Guide

1. Initialize project: npm init -y && npm i fastify @fastify/jwt @fastify/helmet @fastify/rate-limit @fastify/cors zod
2. Create server.ts, paste the Configuration Template, and register secureApiSetup(app) before routes.
3. Set environment variables: JWT_SECRET, ALLOWED_ORIGINS, and configure TLS termination at your reverse proxy.
4. Run npx tsx server.ts and test with curl -H "Authorization: Bearer <token>" http://localhost:3000/api/health.
5. Verify security headers with curl -I http://localhost:3000 and confirm rate limiting by sending 101 requests in 60 seconds.