@nathapp/nestjs-csrf 3.3.0

package/.nax/features/nestjs-csrf/.nax-acceptance.test.ts

@@ -0,0 +1,785 @@
+import { describe, it, expect, beforeAll, afterAll, jest } from '@jest/globals';
+import { Test } from '@nestjs/testing';
+import {
+  Controller,
+  Get,
+  Post,
+  INestApplication,
+  HttpException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+
+import {
+  CsrfTokenService,
+  CsrfModule,
+  DefaultCsrfGuard,
+  CSRF_MODULE_OPTIONS,
+  SKIP_CSRF_METADATA_KEY,
+  SkipCsrf,
+  resolveCsrfOptions,
+} from '../../../lib';
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function makeContext(
+  req: Record<string, unknown>,
+  res: Record<string, unknown>,
+  handler: object = {},
+  cls: object = {},
+) {
+  return {
+    switchToHttp: () => ({
+      getRequest: () => req,
+      getResponse: () => res,
+    }),
+    getHandler: () => handler,
+    getClass: () => cls,
+  } as any;
+}
+
+function buildGuard(
+  optionOverrides: Record<string, unknown> = {},
+  tokensOverride: Record<string, unknown> | null = null,
+  reflectorResultOverride: Record<string, unknown> | null = null,
+) {
+  const rawOptions = { secret: 'test-secret', ...optionOverrides };
+  const mockTokens = tokensOverride ?? {
+    mint: jest.fn().mockReturnValue('csrf-minted-value.fakesig1234'),
+    verify: jest.fn().mockReturnValue(false),
+  };
+  const mockReflector = reflectorResultOverride ?? {
+    getAllAndOverride: jest.fn().mockReturnValue(false),
+  };
+  return {
+    guard: new (DefaultCsrfGuard as any)(rawOptions, mockTokens, mockReflector),
+    tokens: mockTokens as any,
+    reflector: mockReflector as any,
+  };
+}
+
+// Integration test controller
+@Controller()
+class AppController {
+  @Get('page')
+  getPage() { return { ok: true }; }
+
+  @Post('action')
+  postAction() { return { ok: true }; }
+
+  @Post('skip')
+  @SkipCsrf()
+  skipAction() { return { ok: true }; }
+}
+
+function extractCsrfTokenFromSetCookie(setCookieHeader: string | string[] | undefined): string {
+  const raw = Array.isArray(setCookieHeader) ? setCookieHeader[0] : setCookieHeader;
+  if (!raw) return '';
+  const part = raw.split(';')[0]; // e.g. "csrf-token=abc.xyz"
+  const eqIdx = part.indexOf('=');
+  return eqIdx >= 0 ? part.slice(eqIdx + 1) : '';
+}
+
+function thrown403(err: unknown): boolean {
+  if (!err) return false;
+  if (typeof (err as HttpException).getStatus === 'function') {
+    return (err as HttpException).getStatus() === 403;
+  }
+  return (err as any)?.status === 403 || (err as any)?.statusCode === 403;
+}
+
+// ---------------------------------------------------------------------------
+// AC-1: CsrfTokenService injectable from Test.createTestingModule
+// ---------------------------------------------------------------------------
+describe('AC-1: CsrfTokenService injectable from Test.createTestingModule', () => {
+  it('compiles module and resolves CsrfTokenService without throwing', async () => {
+    const moduleRef = await Test.createTestingModule({
+      providers: [CsrfTokenService],
+    }).compile();
+    const svc = moduleRef.get(CsrfTokenService);
+    expect(svc).toBeDefined();
+    expect(svc).toBeInstanceOf(CsrfTokenService);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-2: mint then verify(secret, token, token) returns true
+// ---------------------------------------------------------------------------
+describe('AC-2: CsrfTokenService.mint then verify(secret, token, token) returns true', () => {
+  it('verify returns true when the same token is used as both cookie and header', () => {
+    const svc = new CsrfTokenService();
+    const token = svc.mint('test-secret');
+    expect(typeof token).toBe('string');
+    expect(token.length).toBeGreaterThan(0);
+    const result = svc.verify('test-secret', token, token);
+    expect(result).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-3: verify rejects double-submit mismatch
+// ---------------------------------------------------------------------------
+describe('AC-3: verify(secret, token1, differentToken) returns false', () => {
+  it('returns false when header does not match cookie', () => {
+    const svc = new CsrfTokenService();
+    const token1 = svc.mint('test-secret');
+    const result = svc.verify('test-secret', token1, 'different-token');
+    expect(result).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-4: verify rejects tampered signature
+// ---------------------------------------------------------------------------
+describe('AC-4: verify(secret, tampered, tampered) returns false for altered signature', () => {
+  it('returns false when value is intact but signature is replaced', () => {
+    const svc = new CsrfTokenService();
+    const token = svc.mint('test-secret');
+    const [value] = token.split('.');
+    const tampered = `${value}.0000000000000000000000000000000000000000000000000000000000`;
+    const result = svc.verify('test-secret', tampered, tampered);
+    expect(result).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-5: verify rejects token minted with wrong secret
+// ---------------------------------------------------------------------------
+describe('AC-5: verify(secret-two, token-from-secret-one, same-token) returns false', () => {
+  it('returns false when the verifying secret differs from the minting secret', () => {
+    const svc = new CsrfTokenService();
+    const token = svc.mint('secret-one');
+    const result = svc.verify('secret-two', token, token);
+    expect(result).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-6: verify does not throw on empty strings
+// ---------------------------------------------------------------------------
+describe('AC-6: verify(secret, "", "") returns false without throwing', () => {
+  it('returns false for empty cookie and header values', () => {
+    const svc = new CsrfTokenService();
+    let result: boolean | undefined;
+    let threw = false;
+    try {
+      result = svc.verify('test-secret', '', '');
+    } catch {
+      threw = true;
+    }
+    expect(threw).toBe(false);
+    expect(result).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-7: verify does not throw on missing dot separator
+// ---------------------------------------------------------------------------
+describe('AC-7: verify(secret, "no-separator", "no-separator") returns false without throwing', () => {
+  it('returns false for a malformed token with no dot separator', () => {
+    const svc = new CsrfTokenService();
+    let result: boolean | undefined;
+    let threw = false;
+    try {
+      result = svc.verify('test-secret', 'no-separator', 'no-separator');
+    } catch {
+      threw = true;
+    }
+    expect(threw).toBe(false);
+    expect(result).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-8: resolveCsrfOptions default cookie.name
+// ---------------------------------------------------------------------------
+describe('AC-8: resolveCsrfOptions({ secret: "s" }).cookie.name === "csrf-token"', () => {
+  it('default cookie name is csrf-token', () => {
+    const result = resolveCsrfOptions({ secret: 's' });
+    expect(result.cookie.name).toBe('csrf-token');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-9: resolveCsrfOptions default headerName
+// ---------------------------------------------------------------------------
+describe('AC-9: resolveCsrfOptions({ secret: "s" }).headerName === "x-csrf-token"', () => {
+  it('default header name is x-csrf-token', () => {
+    const result = resolveCsrfOptions({ secret: 's' });
+    expect(result.headerName).toBe('x-csrf-token');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-10: resolveCsrfOptions default ignoreMethods
+// ---------------------------------------------------------------------------
+describe('AC-10: resolveCsrfOptions({ secret: "s" }).ignoreMethods deep-equals ["GET","HEAD","OPTIONS"]', () => {
+  it('default ignoreMethods is GET, HEAD, OPTIONS in that order', () => {
+    const result = resolveCsrfOptions({ secret: 's' });
+    expect(JSON.stringify(result.ignoreMethods)).toBe(JSON.stringify(['GET', 'HEAD', 'OPTIONS']));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-11: resolveCsrfOptions default cookie.sameSite
+// ---------------------------------------------------------------------------
+describe('AC-11: resolveCsrfOptions({ secret: "s" }).cookie.sameSite === "lax"', () => {
+  it('default sameSite is lax', () => {
+    const result = resolveCsrfOptions({ secret: 's' });
+    expect(result.cookie.sameSite).toBe('lax');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-12: resolveCsrfOptions default skipWhenBearer
+// ---------------------------------------------------------------------------
+describe('AC-12: resolveCsrfOptions({ secret: "s" }).skipWhenBearer === true', () => {
+  it('default skipWhenBearer is true', () => {
+    const result = resolveCsrfOptions({ secret: 's' });
+    expect(result.skipWhenBearer).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-13: resolveCsrfOptions default enabled
+// ---------------------------------------------------------------------------
+describe('AC-13: resolveCsrfOptions({ secret: "s" }).enabled === true', () => {
+  it('default enabled is true', () => {
+    const result = resolveCsrfOptions({ secret: 's' });
+    expect(result.enabled).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-14: CSRF_MODULE_OPTIONS and SKIP_CSRF_METADATA_KEY are distinct
+// ---------------------------------------------------------------------------
+describe('AC-14: CSRF_MODULE_OPTIONS !== SKIP_CSRF_METADATA_KEY', () => {
+  it('both tokens are truthy and not equal to each other', () => {
+    expect(CSRF_MODULE_OPTIONS).toBeTruthy();
+    expect(SKIP_CSRF_METADATA_KEY).toBeTruthy();
+    expect(CSRF_MODULE_OPTIONS).not.toBe(SKIP_CSRF_METADATA_KEY);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-15: @SkipCsrf() sets SKIP_CSRF_METADATA_KEY to true on the decorated method
+// ---------------------------------------------------------------------------
+describe('AC-15: @SkipCsrf() exposes SKIP_CSRF_METADATA_KEY === true via Reflector.get', () => {
+  it('Reflector.get returns true for the decorated handler', () => {
+    class TestService {
+      @SkipCsrf()
+      skipMethod() {}
+    }
+    const reflector = new Reflector();
+    const result = reflector.get(SKIP_CSRF_METADATA_KEY, TestService.prototype.skipMethod);
+    expect(result).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-16: DefaultCsrfGuard injectable with canActivate of arity 1
+// ---------------------------------------------------------------------------
+describe('AC-16: DefaultCsrfGuard resolvable from Test module with canActivate(context)', () => {
+  it('module compiles without throwing and guard.canActivate has length 1', async () => {
+    const moduleRef = await Test.createTestingModule({
+      providers: [
+        DefaultCsrfGuard,
+        CsrfTokenService,
+        { provide: CSRF_MODULE_OPTIONS, useValue: { secret: 'test-secret' } },
+        { provide: Reflector, useValue: new Reflector() },
+      ],
+    }).compile();
+    const guard = moduleRef.get(DefaultCsrfGuard);
+    expect(guard).toBeDefined();
+    expect(typeof guard.canActivate).toBe('function');
+    expect(guard.canActivate.length).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-17: GET with Express adapter (no req.raw) calls res.cookie with name and token
+// ---------------------------------------------------------------------------
+describe('AC-17: canActivate on safe GET (Express) calls res.cookie with cookie name and minted token', () => {
+  it('returns true and res.cookie called with csrf-token name and non-empty string value', () => {
+    const resCookie = jest.fn();
+    const req = { method: 'GET', raw: undefined, cookies: {}, headers: {} };
+    const res = { cookie: resCookie, setCookie: undefined };
+    const mintedValue = 'csrf-minted-express-token.validhmacsig';
+    const { guard } = buildGuard({}, {
+      mint: jest.fn().mockReturnValue(mintedValue),
+      verify: jest.fn().mockReturnValue(true),
+    });
+
+    const ctx = makeContext(req, res);
+    const result = guard.canActivate(ctx);
+
+    const resolvedOpts = resolveCsrfOptions({ secret: 'test-secret' });
+    expect(result).toBe(true);
+    expect((resCookie as any).mock.calls.length).toBeGreaterThanOrEqual(1);
+    expect((resCookie as any).mock.calls[0][0]).toBe(resolvedOpts.cookie.name);
+    expect(typeof (resCookie as any).mock.calls[0][1]).toBe('string');
+    expect(((resCookie as any).mock.calls[0][1] as string).length).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-18: GET with Fastify adapter (req.raw defined) calls res.setCookie with name and token
+// ---------------------------------------------------------------------------
+describe('AC-18: canActivate on safe GET (Fastify) calls res.setCookie with cookie name and minted token', () => {
+  it('returns true and res.setCookie called with csrf-token name and non-empty string value', () => {
+    const resSetCookie = jest.fn();
+    const req = { method: 'GET', raw: {}, cookies: {}, headers: {} };
+    const res = { setCookie: resSetCookie, cookie: undefined };
+    const mintedValue = 'csrf-minted-fastify-token.validhmacsig';
+    const { guard } = buildGuard({}, {
+      mint: jest.fn().mockReturnValue(mintedValue),
+      verify: jest.fn().mockReturnValue(true),
+    });
+
+    const ctx = makeContext(req, res);
+    const result = guard.canActivate(ctx);
+
+    const resolvedOpts = resolveCsrfOptions({ secret: 'test-secret' });
+    expect(result).toBe(true);
+    expect((resSetCookie as any).mock.calls.length).toBeGreaterThanOrEqual(1);
+    expect((resSetCookie as any).mock.calls[0][0]).toBe(resolvedOpts.cookie.name);
+    expect(typeof (resSetCookie as any).mock.calls[0][1]).toBe('string');
+    expect(((resSetCookie as any).mock.calls[0][1] as string).length).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-19: POST with SKIP_CSRF_METADATA_KEY=true returns true without calling verify or issuing cookie
+// ---------------------------------------------------------------------------
+describe('AC-19: canActivate returns true when reflector returns true for SKIP_CSRF_METADATA_KEY on handler', () => {
+  it('returns true without calling tokens.verify or res.cookie', () => {
+    const verifyMock = jest.fn().mockReturnValue(false);
+    const mintMock = jest.fn().mockReturnValue('any-token.sig');
+    const resCookie = jest.fn();
+    const { guard } = buildGuard(
+      {},
+      { mint: mintMock, verify: verifyMock },
+      { getAllAndOverride: jest.fn().mockReturnValue(true) },
+    );
+
+    const req = { method: 'POST', cookies: {}, headers: {}, raw: undefined };
+    const res = { cookie: resCookie };
+    const ctx = makeContext(req, res);
+    const result = guard.canActivate(ctx);
+
+    expect(result).toBe(true);
+    expect((verifyMock as any).mock.calls.length).toBe(0);
+    expect((resCookie as any).mock.calls.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-20: POST with Bearer auth and skipWhenBearer=true returns true without calling verify
+// ---------------------------------------------------------------------------
+describe('AC-20: canActivate returns true for Bearer authorization when skipWhenBearer is true', () => {
+  it('returns true and tokens.verify is not called', () => {
+    const verifyMock = jest.fn().mockReturnValue(false);
+    const { guard } = buildGuard(
+      { skipWhenBearer: true },
+      {
+        mint: jest.fn().mockReturnValue('any.token'),
+        verify: verifyMock,
+      },
+    );
+
+    const req = {
+      method: 'POST',
+      headers: { authorization: 'Bearer abc' },
+      cookies: {},
+      raw: undefined,
+    };
+    const res = { cookie: jest.fn() };
+    const ctx = makeContext(req, res);
+    const result = guard.canActivate(ctx);
+
+    expect(result).toBe(true);
+    expect((verifyMock as any).mock.calls.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-21: POST with matching cookie+header and verify returning true → canActivate returns true
+// ---------------------------------------------------------------------------
+describe('AC-21: canActivate returns true when tokens.verify returns true for POST with matching tokens', () => {
+  it('returns true when cookie and header match and verify returns true', () => {
+    const verifyMock = jest.fn().mockReturnValue(true);
+    const { guard } = buildGuard({}, {
+      mint: jest.fn().mockReturnValue('any.token'),
+      verify: verifyMock,
+    });
+
+    const req = {
+      method: 'POST',
+      cookies: { 'csrf-token': 'validToken123' },
+      headers: { 'x-csrf-token': 'validToken123' },
+      raw: undefined,
+    };
+    const res = { cookie: jest.fn() };
+    const ctx = makeContext(req, res);
+    const result = guard.canActivate(ctx);
+
+    expect(result).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-22: verify is invoked with the cookie value and header value from the request
+// ---------------------------------------------------------------------------
+describe('AC-22: tokens.verify mock is called with the cookie and header values on POST', () => {
+  it('verify.mock.calls contains both cookie value and header value', () => {
+    const verifyMock = jest.fn().mockReturnValue(true);
+    const { guard } = buildGuard({}, {
+      mint: jest.fn().mockReturnValue('any.token'),
+      verify: verifyMock,
+    });
+
+    const cookieName = resolveCsrfOptions({ secret: 'test-secret' }).cookie.name;
+    const req = {
+      method: 'POST',
+      cookies: { [cookieName]: 'validToken123' },
+      headers: { 'x-csrf-token': 'validToken123' },
+      raw: undefined,
+    };
+    const res = { cookie: jest.fn() };
+    const ctx = makeContext(req, res);
+    guard.canActivate(ctx);
+
+    expect((verifyMock as any).mock.calls.length).toBeGreaterThanOrEqual(1);
+    const callArgs = (verifyMock as any).mock.calls[0] as string[];
+    // Both the cookie value and the header value must appear in the call arguments
+    const tokenOccurrences = callArgs.filter((a) => a === 'validToken123');
+    expect(tokenOccurrences.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-23: POST with cookie present but no x-csrf-token header → throws 403
+// ---------------------------------------------------------------------------
+describe('AC-23: canActivate throws 403 when cookie is present but x-csrf-token header is absent', () => {
+  it('throws an exception with statusCode 403', () => {
+    const { guard } = buildGuard({}, {
+      mint: jest.fn().mockReturnValue('any.token'),
+      verify: jest.fn().mockReturnValue(false),
+    });
+
+    const req = {
+      method: 'POST',
+      cookies: { 'csrf-token': 'someToken' },
+      headers: {},
+      raw: undefined,
+    };
+    const res = { cookie: jest.fn() };
+    const ctx = makeContext(req, res);
+
+    let thrown: unknown;
+    try {
+      guard.canActivate(ctx);
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeDefined();
+    expect(thrown403(thrown)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-24: POST with mismatched cookie and x-csrf-token → throws 403
+// ---------------------------------------------------------------------------
+describe('AC-24: canActivate throws 403 when cookie value and x-csrf-token header value differ', () => {
+  it('throws an exception with statusCode 403', () => {
+    const { guard } = buildGuard({}, {
+      mint: jest.fn().mockReturnValue('any.token'),
+      verify: jest.fn().mockReturnValue(false),
+    });
+
+    const req = {
+      method: 'POST',
+      cookies: { 'csrf-token': 'tokenA' },
+      headers: { 'x-csrf-token': 'tokenB' },
+      raw: undefined,
+    };
+    const res = { cookie: jest.fn() };
+    const ctx = makeContext(req, res);
+
+    let thrown: unknown;
+    try {
+      guard.canActivate(ctx);
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeDefined();
+    expect(thrown403(thrown)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-25: POST with no cookie but x-csrf-token header present → throws 403
+// ---------------------------------------------------------------------------
+describe('AC-25: canActivate throws 403 when cookie is absent but x-csrf-token header is present', () => {
+  it('throws an exception with statusCode 403', () => {
+    const { guard } = buildGuard({}, {
+      mint: jest.fn().mockReturnValue('any.token'),
+      verify: jest.fn().mockReturnValue(false),
+    });
+
+    const req = {
+      method: 'POST',
+      cookies: {},
+      headers: { 'x-csrf-token': 'someToken' },
+      raw: undefined,
+    };
+    const res = { cookie: jest.fn() };
+    const ctx = makeContext(req, res);
+
+    let thrown: unknown;
+    try {
+      guard.canActivate(ctx);
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeDefined();
+    expect(thrown403(thrown)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-26: POST with neither cookie nor x-csrf-token header → throws 403
+// ---------------------------------------------------------------------------
+describe('AC-26: canActivate throws 403 when both cookie and x-csrf-token header are absent', () => {
+  it('throws an exception with statusCode 403', () => {
+    const { guard } = buildGuard({}, {
+      mint: jest.fn().mockReturnValue('any.token'),
+      verify: jest.fn().mockReturnValue(false),
+    });
+
+    const req = {
+      method: 'POST',
+      cookies: undefined,
+      headers: {},
+      raw: undefined,
+    };
+    const res = { cookie: jest.fn() };
+    const ctx = makeContext(req, res);
+
+    let thrown: unknown;
+    try {
+      guard.canActivate(ctx);
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeDefined();
+    expect(thrown403(thrown)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-27: CsrfModule.register returns global DynamicModule
+// ---------------------------------------------------------------------------
+describe('AC-27: CsrfModule.register({ secret: "s" }) returns object with global === true', () => {
+  it('returned dynamic module has global: true', () => {
+    const result = CsrfModule.register({ secret: 's' });
+    expect((result as any).global).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-28: Integration — POST without CSRF tokens returns 403
+// ---------------------------------------------------------------------------
+describe('AC-28: CsrfModule.register app returns 403 for POST without CSRF cookie or header', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [CsrfModule.register({ secret: 's' })],
+      controllers: [AppController],
+    }).compile();
+    app = moduleRef.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app?.close();
+  });
+
+  it('POST /action with no CSRF tokens returns 403', async () => {
+    const supertest = require('supertest');
+    const res = await supertest(app.getHttpServer()).post('/action');
+    expect(res.statusCode).toBe(403);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-29: Integration — GET returns 2xx and Set-Cookie with CSRF token
+// ---------------------------------------------------------------------------
+describe('AC-29: CsrfModule.register app returns 2xx and Set-Cookie on GET', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [CsrfModule.register({ secret: 's' })],
+      controllers: [AppController],
+    }).compile();
+    app = moduleRef.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app?.close();
+  });
+
+  it('GET /page returns 2xx and Set-Cookie header containing a CSRF token value', async () => {
+    const supertest = require('supertest');
+    const res = await supertest(app.getHttpServer()).get('/page');
+    expect(res.statusCode).toBeGreaterThanOrEqual(200);
+    expect(res.statusCode).toBeLessThan(300);
+    const setCookie: string | string[] | undefined = res.headers['set-cookie'];
+    const cookieStr = Array.isArray(setCookie) ? setCookie.join(', ') : (setCookie ?? '');
+    expect(cookieStr).toContain('csrf-token');
+    const tokenValue = extractCsrfTokenFromSetCookie(setCookie);
+    expect(tokenValue.length).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-30: Integration — full double-submit round-trip returns 2xx
+// ---------------------------------------------------------------------------
+describe('AC-30: CsrfModule.register app full round-trip: GET cookie, POST with cookie+header returns 2xx', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [CsrfModule.register({ secret: 's' })],
+      controllers: [AppController],
+    }).compile();
+    app = moduleRef.createNestApplication();
+    // Enable cookie parsing so the guard can read req.cookies on POST
+    const cookieParser = require('cookie-parser');
+    app.use(cookieParser());
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app?.close();
+  });
+
+  it('POST with valid CSRF cookie and matching x-csrf-token header returns 2xx', async () => {
+    const supertest = require('supertest');
+
+    // 1. GET to receive the CSRF cookie
+    const getRes = await supertest(app.getHttpServer()).get('/page');
+    expect(getRes.statusCode).toBeGreaterThanOrEqual(200);
+    const tokenValue = extractCsrfTokenFromSetCookie(getRes.headers['set-cookie']);
+    expect(tokenValue.length).toBeGreaterThan(0);
+
+    // 2. POST echoing back the same token in cookie + header
+    const postRes = await supertest(app.getHttpServer())
+      .post('/action')
+      .set('Cookie', `csrf-token=${tokenValue}`)
+      .set('x-csrf-token', tokenValue);
+    expect(postRes.statusCode).toBeGreaterThanOrEqual(200);
+    expect(postRes.statusCode).toBeLessThan(300);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-31: Integration — enabled:false allows POST without CSRF tokens
+// ---------------------------------------------------------------------------
+describe('AC-31: CsrfModule.register({ enabled: false }) allows POST without CSRF tokens', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [CsrfModule.register({ secret: 's', enabled: false })],
+      controllers: [AppController],
+    }).compile();
+    app = moduleRef.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app?.close();
+  });
+
+  it('POST /action with no CSRF tokens returns 2xx when enabled is false', async () => {
+    const supertest = require('supertest');
+    const res = await supertest(app.getHttpServer()).post('/action');
+    expect(res.statusCode).toBeGreaterThanOrEqual(200);
+    expect(res.statusCode).toBeLessThan(300);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-32: Integration — @SkipCsrf() decorated handler allows POST without CSRF
+// ---------------------------------------------------------------------------
+describe('AC-32: POST to @SkipCsrf() decorated handler returns 2xx without CSRF token', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [CsrfModule.register({ secret: 's' })],
+      controllers: [AppController],
+    }).compile();
+    app = moduleRef.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app?.close();
+  });
+
+  it('POST /skip with no CSRF tokens returns 2xx because handler is decorated with @SkipCsrf()', async () => {
+    const supertest = require('supertest');
+    const res = await supertest(app.getHttpServer()).post('/skip');
+    expect(res.statusCode).toBeGreaterThanOrEqual(200);
+    expect(res.statusCode).toBeLessThan(300);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-33: Integration — registerAsync applies guard and returns 403 for tokenless POST
+// ---------------------------------------------------------------------------
+describe('AC-33: CsrfModule.registerAsync({ useFactory }) returns 403 for POST without CSRF tokens', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [CsrfModule.registerAsync({ useFactory: () => ({ secret: 's' }) })],
+      controllers: [AppController],
+    }).compile();
+    app = moduleRef.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app?.close();
+  });
+
+  it('POST /action without CSRF tokens returns 403', async () => {
+    const supertest = require('supertest');
+    const res = await supertest(app.getHttpServer()).post('/action');
+    expect(res.statusCode).toBe(403);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC-34: CsrfModule.register without secret throws Error containing "secret"
+// ---------------------------------------------------------------------------
+describe('AC-34: CsrfModule.register({} as any) throws an Error with message containing "secret"', () => {
+  it('throws at registration time with a message containing "secret"', () => {
+    let thrownError: Error | undefined;
+    try {
+      CsrfModule.register({} as any);
+    } catch (err: any) {
+      thrownError = err;
+    }
+    expect(thrownError).toBeDefined();
+    expect(thrownError).toBeInstanceOf(Error);
+    expect(thrownError!.message).toMatch(/secret/i);
+  });
+});