fix(#278): Implement CSRF protection using double-submit cookie pattern

Implemented comprehensive CSRF protection for all state-changing endpoints
(POST, PATCH, DELETE) using the double-submit cookie pattern.

Security Implementation:
- Created CsrfGuard using double-submit cookie validation
- Token set in httpOnly cookie and validated against X-CSRF-Token header
- Applied guard to FederationController (vulnerable endpoints)
- Safe HTTP methods (GET, HEAD, OPTIONS) automatically exempted
- Signature-based endpoints (@SkipCsrf decorator) exempted

Components Added:
- CsrfGuard: Validates cookie and header token match
- CsrfController: GET /api/v1/csrf/token endpoint for token generation
- @SkipCsrf(): Decorator to exempt endpoints with alternative auth
- Comprehensive tests (20 tests, all passing)

Protected Endpoints:
- POST /api/v1/federation/connections/initiate
- POST /api/v1/federation/connections/:id/accept
- POST /api/v1/federation/connections/:id/reject
- POST /api/v1/federation/connections/:id/disconnect
- POST /api/v1/federation/instance/regenerate-keys

Exempted Endpoints:
- POST /api/v1/federation/incoming/connect (signature-verified)
- GET requests (safe methods)

Security Features:
- httpOnly cookies prevent XSS attacks
- SameSite=strict prevents subdomain attacks
- Cryptographically secure random tokens (32 bytes)
- 24-hour token expiry
- Structured logging for security events

Testing:
- 14 guard tests covering all scenarios
- 6 controller tests for token generation
- Quality gates: lint, typecheck, build all passing

Note: Frontend integration required to use tokens. Clients must:
1. GET /api/v1/csrf/token to receive token
2. Include token in X-CSRF-Token header for state-changing requests

Fixes #278

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

apps/api/src/common/guards/csrf.guard.spec.ts

@@ -0,0 +1,140 @@
+/**
+ * CSRF Guard Tests
+ *
+ * Tests CSRF protection using double-submit cookie pattern.
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { ExecutionContext, ForbiddenException } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { CsrfGuard } from "./csrf.guard";
+
+describe("CsrfGuard", () => {
+  let guard: CsrfGuard;
+  let reflector: Reflector;
+
+  beforeEach(() => {
+    reflector = new Reflector();
+    guard = new CsrfGuard(reflector);
+  });
+
+  const createContext = (
+    method: string,
+    cookies: Record<string, string> = {},
+    headers: Record<string, string> = {},
+    skipCsrf = false
+  ): ExecutionContext => {
+    const request = {
+      method,
+      cookies,
+      headers,
+      path: "/api/test",
+    };
+
+    return {
+      switchToHttp: () => ({
+        getRequest: () => request,
+      }),
+      getHandler: () => ({}),
+      getClass: () => ({}),
+      getAllAndOverride: vi.fn().mockReturnValue(skipCsrf),
+    } as unknown as ExecutionContext;
+  };
+
+  describe("Safe HTTP methods", () => {
+    it("should allow GET requests without CSRF token", () => {
+      const context = createContext("GET");
+      expect(guard.canActivate(context)).toBe(true);
+    });
+
+    it("should allow HEAD requests without CSRF token", () => {
+      const context = createContext("HEAD");
+      expect(guard.canActivate(context)).toBe(true);
+    });
+
+    it("should allow OPTIONS requests without CSRF token", () => {
+      const context = createContext("OPTIONS");
+      expect(guard.canActivate(context)).toBe(true);
+    });
+  });
+
+  describe("Endpoints marked to skip CSRF", () => {
+    it("should allow POST requests when @SkipCsrf() is applied", () => {
+      vi.spyOn(reflector, "getAllAndOverride").mockReturnValue(true);
+      const context = createContext("POST");
+      expect(guard.canActivate(context)).toBe(true);
+    });
+  });
+
+  describe("State-changing methods requiring CSRF", () => {
+    it("should reject POST without CSRF token", () => {
+      const context = createContext("POST");
+      expect(() => guard.canActivate(context)).toThrow(ForbiddenException);
+      expect(() => guard.canActivate(context)).toThrow("CSRF token missing");
+    });
+
+    it("should reject PUT without CSRF token", () => {
+      const context = createContext("PUT");
+      expect(() => guard.canActivate(context)).toThrow(ForbiddenException);
+    });
+
+    it("should reject PATCH without CSRF token", () => {
+      const context = createContext("PATCH");
+      expect(() => guard.canActivate(context)).toThrow(ForbiddenException);
+    });
+
+    it("should reject DELETE without CSRF token", () => {
+      const context = createContext("DELETE");
+      expect(() => guard.canActivate(context)).toThrow(ForbiddenException);
+    });
+
+    it("should reject when only cookie token is present", () => {
+      const context = createContext("POST", { "csrf-token": "abc123" });
+      expect(() => guard.canActivate(context)).toThrow(ForbiddenException);
+      expect(() => guard.canActivate(context)).toThrow("CSRF token missing");
+    });
+
+    it("should reject when only header token is present", () => {
+      const context = createContext("POST", {}, { "x-csrf-token": "abc123" });
+      expect(() => guard.canActivate(context)).toThrow(ForbiddenException);
+      expect(() => guard.canActivate(context)).toThrow("CSRF token missing");
+    });
+
+    it("should reject when tokens do not match", () => {
+      const context = createContext(
+        "POST",
+        { "csrf-token": "abc123" },
+        { "x-csrf-token": "xyz789" }
+      );
+      expect(() => guard.canActivate(context)).toThrow(ForbiddenException);
+      expect(() => guard.canActivate(context)).toThrow("CSRF token mismatch");
+    });
+
+    it("should allow when tokens match", () => {
+      const context = createContext(
+        "POST",
+        { "csrf-token": "abc123" },
+        { "x-csrf-token": "abc123" }
+      );
+      expect(guard.canActivate(context)).toBe(true);
+    });
+
+    it("should allow PATCH when tokens match", () => {
+      const context = createContext(
+        "PATCH",
+        { "csrf-token": "token123" },
+        { "x-csrf-token": "token123" }
+      );
+      expect(guard.canActivate(context)).toBe(true);
+    });
+
+    it("should allow DELETE when tokens match", () => {
+      const context = createContext(
+        "DELETE",
+        { "csrf-token": "delete-token" },
+        { "x-csrf-token": "delete-token" }
+      );
+      expect(guard.canActivate(context)).toBe(true);
+    });
+  });
+});

apps/api/src/common/guards/csrf.guard.ts

@@ -0,0 +1,83 @@
+/**
+ * CSRF Guard
+ *
+ * Implements CSRF protection using double-submit cookie pattern.
+ * Validates that CSRF token in cookie matches token in header.
+ *
+ * Usage:
+ * - Apply to controllers handling state-changing operations
+ * - Use @SkipCsrf() decorator to exempt specific endpoints
+ * - Safe methods (GET, HEAD, OPTIONS) are automatically exempted
+ */
+
+import {
+  Injectable,
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Logger,
+} from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { Request } from "express";
+
+export const SKIP_CSRF_KEY = "skipCsrf";
+
+@Injectable()
+export class CsrfGuard implements CanActivate {
+  private readonly logger = new Logger(CsrfGuard.name);
+
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    // Check if endpoint is marked to skip CSRF
+    const skipCsrf = this.reflector.getAllAndOverride<boolean>(SKIP_CSRF_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (skipCsrf) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<Request>();
+
+    // Exempt safe HTTP methods (GET, HEAD, OPTIONS)
+    if (["GET", "HEAD", "OPTIONS"].includes(request.method)) {
+      return true;
+    }
+
+    // Get CSRF token from cookie and header
+    const cookies = request.cookies as Record<string, string> | undefined;
+    const cookieToken = cookies?.["csrf-token"];
+    const headerToken = request.headers["x-csrf-token"] as string | undefined;
+
+    // Validate tokens exist and match
+    if (!cookieToken || !headerToken) {
+      this.logger.warn({
+        event: "CSRF_TOKEN_MISSING",
+        method: request.method,
+        path: request.path,
+        hasCookie: !!cookieToken,
+        hasHeader: !!headerToken,
+        securityEvent: true,
+        timestamp: new Date().toISOString(),
+      });
+
+      throw new ForbiddenException("CSRF token missing");
+    }
+
+    if (cookieToken !== headerToken) {
+      this.logger.warn({
+        event: "CSRF_TOKEN_MISMATCH",
+        method: request.method,
+        path: request.path,
+        securityEvent: true,
+        timestamp: new Date().toISOString(),
+      });
+
+      throw new ForbiddenException("CSRF token mismatch");
+    }
+
+    return true;
+  }
+}