feat(api): add helmet security headers and rate limiting

- Add helmet middleware for secure HTTP response headers
- Add express-rate-limit with three limiters:
  - authLimiter: per-IP, 20 req/15min on /api/auth/*
  - gameLimiter: per-user, 150 req/15min (not yet wired)
  - lobbyLimiter: per-user, 20 req/15min (not yet wired)
- Set trust proxy for correct client IP behind Caddy
- Add tests for all three limiters and helmet headers

apps/api/package.json

@@ -15,6 +15,8 @@
     "better-auth": "^1.6.2",
     "cors": "^2.8.6",
     "express": "^5.2.1",
+    "express-rate-limit": "^8.4.0",
+    "helmet": "^8.1.0",
     "ws": "^8.20.0"
   },
   "devDependencies": {

apps/api/src/app.test.ts

@@ -0,0 +1,39 @@
+import request from "supertest";
+import { describe, it, expect } from "vitest";
+import { createApp } from "./app.js";
+
+const app = createApp();
+
+describe("security headers (helmet)", () => {
+  it("sets X-Content-Type-Options to nosniff", async () => {
+    const res = await request(app).get("/api/v1/health");
+    expect(res.headers["x-content-type-options"]).toBe("nosniff");
+  });
+
+  it("sets X-Frame-Options to SAMEORIGIN", async () => {
+    const res = await request(app).get("/api/v1/health");
+    expect(res.headers["x-frame-options"]).toBe("SAMEORIGIN");
+  });
+
+  it("removes X-Powered-By header", async () => {
+    const res = await request(app).get("/api/v1/health");
+    expect(res.headers).not.toHaveProperty("x-powered-by");
+  });
+
+  it("sets Content-Security-Policy", async () => {
+    const res = await request(app).get("/api/v1/health");
+    expect(res.headers).toHaveProperty("content-security-policy");
+  });
+});
+
+describe("auth rate limiting", () => {
+  it("returns 429 after exceeding the auth limit", async () => {
+    const testApp = createApp();
+    const limit = 20;
+    for (let i = 0; i < limit; i++) {
+      await request(testApp).post("/api/auth/sign-in");
+    }
+    const res = await request(testApp).post("/api/auth/sign-in");
+    expect(res.status).toBe(429);
+  });
+});

apps/api/src/app.ts

@@ -1,20 +1,26 @@
 import express from "express";
 import type { Express } from "express";
 import { toNodeHandler } from "better-auth/node";
+import cors from "cors";
+import helmet from "helmet";
 import { auth } from "./lib/auth.js";
 import { apiRouter } from "./routes/apiRouter.js";
 import { errorHandler } from "./middleware/errorHandler.js";
-import cors from "cors";
+import { authLimiter } from "./middleware/rateLimiters.js";
 
 export function createApp() {
   const app: Express = express();
 
+  app.set("trust proxy", 1);
+  app.use(helmet());
+
   app.use(
     cors({
       origin: process.env["CORS_ORIGIN"] || "http://localhost:5173",
       credentials: true,
     }),
   );
+  app.use("/api/auth", authLimiter);
   app.all("/api/auth/*splat", toNodeHandler(auth));
   app.use(express.json());
   app.use("/api/v1", apiRouter);

apps/api/src/middleware/rateLimiters.test.ts

@@ -0,0 +1,179 @@
+import express from "express";
+import request from "supertest";
+import { describe, it, expect, beforeEach } from "vitest";
+import { authLimiter, gameLimiter, lobbyLimiter } from "./rateLimiters.js";
+
+import type { Session, User } from "better-auth";
+
+// Minimal app to test the limiter in isolation
+function createTestApp() {
+  const app = express();
+  app.set("trust proxy", 1);
+  app.use("/api/auth", authLimiter);
+  app.all("/api/auth/*splat", (_req, res) => {
+    res.status(200).json({ success: true });
+  });
+  return app;
+}
+
+describe("authLimiter", () => {
+  let app: ReturnType<typeof createTestApp>;
+
+  beforeEach(() => {
+    // Fresh app = fresh in-memory store = counters reset between tests
+    app = createTestApp();
+  });
+
+  it("allows requests under the limit through", async () => {
+    const res = await request(app).post("/api/auth/sign-in");
+    expect(res.status).toBe(200);
+  });
+
+  it("returns 429 after exceeding the limit", async () => {
+    const limit = 20;
+    for (let i = 0; i < limit; i++) {
+      await request(app).post("/api/auth/sign-in");
+    }
+    const res = await request(app).post("/api/auth/sign-in");
+    expect(res.status).toBe(429);
+    expect(res.body).toEqual({
+      success: false,
+      error: "Too many requests, please try again later.",
+    });
+  });
+
+  it("sets RateLimit headers on responses", async () => {
+    const res = await request(app).post("/api/auth/sign-in");
+    expect(res.headers).toHaveProperty("ratelimit");
+  });
+});
+
+function fakeAuth(userId: string) {
+  return (
+    req: express.Request,
+    _res: express.Response,
+    next: express.NextFunction,
+  ) => {
+    req.session = { session: {} as Session, user: { id: userId } as User };
+    next();
+  };
+}
+
+function createGameTestApp(userId = "user-1") {
+  const app = express();
+  app.set("trust proxy", 1);
+  app.use(fakeAuth(userId));
+  app.use(gameLimiter);
+  app.post("/game/start", (_req, res) =>
+    res.status(200).json({ success: true }),
+  );
+  app.post("/game/answer", (_req, res) =>
+    res.status(200).json({ success: true }),
+  );
+  return app;
+}
+
+describe("gameLimiter", () => {
+  it("allows requests under the limit through", async () => {
+    const app = createGameTestApp();
+    const res = await request(app).post("/game/start");
+    expect(res.status).toBe(200);
+  });
+
+  it("returns 429 after exceeding the limit", async () => {
+    const app = createGameTestApp();
+    const limit = 150;
+    for (let i = 0; i < limit; i++) {
+      await request(app).post("/game/answer");
+    }
+    const res = await request(app).post("/game/answer");
+    expect(res.status).toBe(429);
+    expect(res.body).toEqual({
+      success: false,
+      error: "Too many requests, please try again later.",
+    });
+  });
+
+  it("tracks limits per user, not per IP", async () => {
+    const app = express();
+    app.set("trust proxy", 1);
+
+    // Two routes, same limiter, different users
+    app.use("/user1", fakeAuth("user-1"), gameLimiter, (_req, res) =>
+      res.status(200).json({ success: true }),
+    );
+    app.use("/user2", fakeAuth("user-2"), gameLimiter, (_req, res) =>
+      res.status(200).json({ success: true }),
+    );
+
+    const limit = 150;
+    for (let i = 0; i < limit; i++) {
+      await request(app).post("/user1");
+    }
+
+    // user-1 is exhausted
+    const blocked = await request(app).post("/user1");
+    expect(blocked.status).toBe(429);
+
+    // user-2 is unaffected
+    const allowed = await request(app).post("/user2");
+    expect(allowed.status).toBe(200);
+  });
+});
+
+function createLobbyTestApp(userId = "user-1") {
+  const app = express();
+  app.set("trust proxy", 1);
+  app.use(fakeAuth(userId));
+  app.use(lobbyLimiter);
+  app.post("/lobbies", (_req, res) => res.status(200).json({ success: true }));
+  app.post("/lobbies/:code/join", (_req, res) =>
+    res.status(200).json({ success: true }),
+  );
+  return app;
+}
+
+describe("lobbyLimiter", () => {
+  it("allows requests under the limit through", async () => {
+    const app = createLobbyTestApp();
+    const res = await request(app).post("/lobbies");
+    expect(res.status).toBe(200);
+  });
+
+  it("returns 429 after exceeding the limit", async () => {
+    const app = createLobbyTestApp();
+    const limit = 20;
+    for (let i = 0; i < limit; i++) {
+      await request(app).post("/lobbies");
+    }
+    const res = await request(app).post("/lobbies");
+    expect(res.status).toBe(429);
+    expect(res.body).toEqual({
+      success: false,
+      error: "Too many requests, please try again later.",
+    });
+  });
+
+  it("tracks limits per user, not per IP", async () => {
+    const app = express();
+    app.set("trust proxy", 1);
+
+    app.use("/user1", fakeAuth("user-1"), lobbyLimiter, (_req, res) =>
+      res.status(200).json({ success: true }),
+    );
+    app.use("/user2", fakeAuth("user-2"), lobbyLimiter, (_req, res) =>
+      res.status(200).json({ success: true }),
+    );
+
+    const limit = 20;
+    for (let i = 0; i < limit; i++) {
+      await request(app).post("/user1");
+    }
+
+    const blocked = await request(app).post("/user1");
+    expect(blocked.status).toBe(429);
+
+    const allowed = await request(app).post("/user2");
+    expect(allowed.status).toBe(200);
+  });
+});

apps/api/src/middleware/rateLimiters.ts

@@ -0,0 +1,44 @@
+import rateLimit from "express-rate-limit";
+import type { Request } from "express";
+
+// TODO: When Valkey is wired up, swap the default in-memory store for
+// rate-limit-redis to persist limits across restarts:
+//
+// import { RedisStore } from "rate-limit-redis";
+// import { valkey } from "../lib/valkey.js";
+// Then add to each limiter: store: new RedisStore({ sendCommand: (...args) => valkey.call(...args) })
+
+export const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  limit: 20,
+  standardHeaders: "draft-8",
+  legacyHeaders: false,
+  message: {
+    success: false,
+    error: "Too many requests, please try again later.",
+  },
+});
+
+export const gameLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  limit: 150,
+  standardHeaders: "draft-8",
+  legacyHeaders: false,
+  keyGenerator: (req: Request) => req.session!.user.id,
+  message: {
+    success: false,
+    error: "Too many requests, please try again later.",
+  },
+});
+
+export const lobbyLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  limit: 20,
+  standardHeaders: "draft-8",
+  legacyHeaders: false,
+  keyGenerator: (req: Request) => req.session!.user.id,
+  message: {
+    success: false,
+    error: "Too many requests, please try again later.",
+  },
+});

documentation/backlog.md

@@ -32,6 +32,9 @@ Things that are actively in progress or should be picked up immediately. Mostly
 - **Security headers with helmet** `[security]`
   Add helmet middleware to set secure HTTP response headers. One-liner: app.use(helmet()). Covers headers like X-Content-Type-Options, X-Frame-Options, and Content-Security-Policy.
 
+- **Conditionally register OAuth providers** `[debt]`
+  Better Auth logs warnings when social providers are registered without credentials (`Social provider google is missing clientId or clientSecret`). Instead of registering all providers unconditionally, only add a provider to the config when its credentials are present in the environment. Keeps local dev clean for contributors who don't have OAuth apps set up.
+
 ---
 
 ## next

pnpm-lock.yaml

@@ -62,6 +62,12 @@ importers:
       express:
         specifier: ^5.2.1
         version: 5.2.1
+      express-rate-limit:
+        specifier: ^8.4.0
+        version: 8.4.0(express@5.2.1)
+      helmet:
+        specifier: ^8.1.0
+        version: 8.1.0
       ws:
         specifier: ^8.20.0
         version: 8.20.0
@@ -2045,6 +2051,12 @@ packages:
     resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==}
     engines: {node: '>=12.0.0'}
 
+  express-rate-limit@8.4.0:
+    resolution: {integrity: sha512-gDK8yiqKxrGta+3WtON59arrrw6GLmadA1qoFgYXzdcch8fmKDID2XqO8itsi3f1wufXYPT51387dN6cvVBS3Q==}
+    engines: {node: '>= 16'}
+    peerDependencies:
+      express: '>= 4.11'
+
   express@5.2.1:
     resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
     engines: {node: '>= 18'}
@@ -2185,6 +2197,10 @@ packages:
     resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
     engines: {node: '>= 0.4'}
 
+  helmet@8.1.0:
+    resolution: {integrity: sha512-jOiHyAZsmnr8LqoPGmCjYAaiuWwjAPLgY8ZX2XrmHawt99/u1y6RgrZMTeoPfpUbV96HOalYgz1qzkRbw54Pmg==}
+    engines: {node: '>=18.0.0'}
+
   hermes-estree@0.25.1:
     resolution: {integrity: sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==}
 
@@ -2227,6 +2243,10 @@ packages:
   ini@1.3.8:
     resolution: {integrity: sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==}
 
+  ip-address@10.1.0:
+    resolution: {integrity: sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==}
+    engines: {node: '>= 12'}
+
   ipaddr.js@1.9.1:
     resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
     engines: {node: '>= 0.10'}
@@ -4821,6 +4841,11 @@ snapshots:
 
   expect-type@1.3.0: {}
 
+  express-rate-limit@8.4.0(express@5.2.1):
+    dependencies:
+      express: 5.2.1
+      ip-address: 10.1.0
+
   express@5.2.1:
     dependencies:
       accepts: 2.0.0
@@ -4982,6 +5007,8 @@ snapshots:
     dependencies:
       function-bind: 1.1.2
 
+  helmet@8.1.0: {}
+
   hermes-estree@0.25.1: {}
 
   hermes-parser@0.25.1:
@@ -5020,6 +5047,8 @@ snapshots:
 
   ini@1.3.8: {}
 
+  ip-address@10.1.0: {}
+
   ipaddr.js@1.9.1: {}
 
   is-binary-path@2.1.0: