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);
+    });
+  });
+});