@nathapp/nestjs-csrf 3.3.0 → 4.0.1

package/.turbo/turbo-build.log

@@ -1,4 +0,0 @@
-
-> @nathapp/nestjs-csrf@3.3.0 build
-> rimraf dist && tsc -p tsconfig.json
-

package/CHANGELOG.md

@@ -1,15 +0,0 @@
-# @nathapp/nestjs-csrf
-
-## 3.3.0
-
-### Minor Changes
-
-- a27440f: 3.3.0 milestone release. The `@nathapp/nestjs-*` packages now version and publish in lockstep at a unified version.
-
-  - **nestjs-csrf**: first public release — stateless double-submit-cookie CSRF guard (zero-dep HMAC, Express + Fastify, Bearer coexist skip, `@SkipCsrf()`, auto-binds `APP_GUARD`).
-  - **nestjs-health**: first public release — terminus aggregator over cache/prisma/queue with k8s liveness/readiness probes via a dynamic controller factory.
-  - **nestjs-idempotency**: first public release — `@Idempotent()` interceptor (zero-dep sha256 fingerprint, Express + Fastify, 409-in-flight, 2xx replay, fingerprint mismatch 422, fail-closed on store error).
-  - **nestjs-observability**: first public release — Prometheus RED metrics + OpenTelemetry tracing joined to the logging ALS; `initTracing()` pre-bootstrap hook.
-  - **nestjs-outbox**: first public release — transactional outbox relay (at-least-once via `ITransactionManager`, lease-claim + backoff, dead-letter).
-  - **nestjs-storage**: migrated from aws-sdk v2 to v3 (zero runtime dep via `import type` + lazy `loadPackage`); NFSStorage stub replaced with an S3-style HTTP file-service client.
-  - **nestjs-cache**: `delByPattern` now routes through Redis SCAN instead of an O(n) key sweep, with glob-detection and multi-tier iterator support.

package/lib/constant/csrf.constants.ts

@@ -1,3 +0,0 @@
-export const CSRF_MODULE_OPTIONS = Symbol.for('@nathapp/nestjs-csrf/options');
-
-export const SKIP_CSRF_METADATA_KEY = Symbol.for('@nathapp/nestjs-csrf/skip');

package/lib/constant/index.ts

@@ -1 +0,0 @@
-export { CSRF_MODULE_OPTIONS, SKIP_CSRF_METADATA_KEY } from './csrf.constants';

package/lib/decorator/index.ts

@@ -1 +0,0 @@
-export { SkipCsrf } from './skip-csrf.decorator';

package/lib/decorator/skip-csrf.decorator.ts

@@ -1,6 +0,0 @@
-import { SetMetadata } from '@nestjs/common';
-import { SKIP_CSRF_METADATA_KEY } from '../constant/csrf.constants';
-
-export function SkipCsrf(): MethodDecorator & ClassDecorator {
-  return SetMetadata(SKIP_CSRF_METADATA_KEY, true);
-}

package/lib/guard/csrf.guard.ts

@@ -1,98 +0,0 @@
-import {
-  CanActivate,
-  ExecutionContext,
-  Inject,
-  Injectable,
-  Logger,
-} from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
-import { ForbiddenAppException } from '@nathapp/nestjs-common';
-import { CSRF_MODULE_OPTIONS, SKIP_CSRF_METADATA_KEY } from '../constant/csrf.constants';
-import { CsrfOptions, ResolvedCsrfOptions } from '../interface/csrf-options.interface';
-import { CsrfTokenService } from '../service/csrf-token.service';
-import { resolveCsrfOptions } from '../service/resolve-options';
-
-@Injectable()
-export class DefaultCsrfGuard implements CanActivate {
-  private readonly logger = new Logger(DefaultCsrfGuard.name);
-  private readonly options: ResolvedCsrfOptions;
-
-  constructor(
-    @Inject(CSRF_MODULE_OPTIONS) rawOptions: CsrfOptions,
-    private readonly tokens: CsrfTokenService,
-    private readonly reflector: Reflector,
-  ) {
-    this.options = resolveCsrfOptions(rawOptions);
-  }
-
-  canActivate(context: ExecutionContext): boolean {
-    if (this.options.enabled === false) return true;
-
-    const http = context.switchToHttp();
-    const req = http.getRequest<{
-      method?: string;
-      cookies?: Record<string, string>;
-      headers?: Record<string, string | string[] | undefined>;
-      raw?: unknown;
-    }>();
-    const res = http.getResponse<{
-      cookie?: (name: string, value: string, opts?: unknown) => void;
-      setCookie?: (name: string, value: string, opts?: unknown) => void;
-    }>();
-
-    if (this.options.ignoreMethods.includes((req.method ?? '').toUpperCase())) {
-      const existingCookie = req.cookies?.[this.options.cookie.name];
-      if (!existingCookie) {
-        this.issue(res);
-      }
-      return true;
-    }
-
-    const reflectionTargets: Function[] = [context.getHandler(), context.getClass()];
-    const validTargets = reflectionTargets.filter(
-      (t): t is Function => t != null,
-    );
-    if (
-      validTargets.length > 0 &&
-      this.reflector.getAllAndOverride(SKIP_CSRF_METADATA_KEY, validTargets)
-    ) {
-      return true;
-    }
-
-    if (
-      this.options.skipWhenBearer &&
-      typeof req.headers?.['authorization'] === 'string' &&
-      /^Bearer\s/i.test(req.headers['authorization'] as string)
-    ) {
-      return true;
-    }
-
-    const cookie = req.cookies?.[this.options.cookie.name];
-    const headerValue = req.headers?.[this.options.headerName];
-    const header = Array.isArray(headerValue) ? headerValue[0] : headerValue;
-
-    if (!this.tokens.verify(this.options.secret, cookie, header)) {
-      throw new ForbiddenAppException({ reason: 'csrf_token_invalid' });
-    }
-
-    return true;
-  }
-
-  private issue(res: {
-    cookie?: (name: string, value: string, opts?: unknown) => void;
-    setCookie?: (name: string, value: string, opts?: unknown) => void;
-  }): void {
-    const token = this.tokens.mint(this.options.secret);
-    const { name, ...opts } = this.options.cookie;
-    if (typeof res.setCookie === 'function') {
-      res.setCookie(name, token, opts);
-    } else if (typeof res.cookie === 'function') {
-      res.cookie(name, token, opts);
-    } else {
-      this.logger.warn(
-        'Unable to issue CSRF cookie: response object exposes neither setCookie nor cookie. ' +
-          'Ensure cookie-parser (Express) or @fastify/cookie (Fastify) is registered.',
-      );
-    }
-  }
-}

package/lib/guard/index.ts

@@ -1 +0,0 @@
-export { DefaultCsrfGuard } from './csrf.guard';

package/lib/index.ts

@@ -1,12 +0,0 @@
-export { CSRF_MODULE_OPTIONS, SKIP_CSRF_METADATA_KEY } from './constant';
-export { CsrfAsyncModuleOptions, CsrfModule } from './module';
-export { CsrfTokenService, resolveCsrfOptions } from './service';
-export { DefaultCsrfGuard } from './guard';
-export { SkipCsrf } from './decorator';
-export {
-  CsrfCookieOptions,
-  CsrfModuleOptionsFactory,
-  CsrfOptions,
-  CsrfSameSite,
-  ResolvedCsrfOptions,
-} from './interface';

package/lib/interface/csrf-options.interface.ts

@@ -1,31 +0,0 @@
-export type CsrfSameSite = 'lax' | 'strict' | 'none';
-
-export interface CsrfCookieOptions {
-  name: string;
-  path: string;
-  httpOnly: boolean;
-  secure: boolean;
-  sameSite: CsrfSameSite;
-}
-
-export interface CsrfOptions {
-  secret: string;
-  enabled?: boolean;
-  headerName?: string;
-  ignoreMethods?: string[];
-  skipWhenBearer?: boolean;
-  cookie?: Partial<CsrfCookieOptions>;
-}
-
-export interface ResolvedCsrfOptions {
-  secret: string;
-  enabled: boolean;
-  headerName: string;
-  ignoreMethods: string[];
-  skipWhenBearer: boolean;
-  cookie: CsrfCookieOptions;
-}
-
-export interface CsrfModuleOptionsFactory {
-  createOptions(): Promise<CsrfOptions> | CsrfOptions;
-}

package/lib/interface/index.ts

@@ -1,7 +0,0 @@
-export {
-  CsrfCookieOptions,
-  CsrfModuleOptionsFactory,
-  CsrfOptions,
-  CsrfSameSite,
-  ResolvedCsrfOptions,
-} from './csrf-options.interface';

package/lib/module/csrf.module.ts

@@ -1,74 +0,0 @@
-import {
-  DynamicModule,
-  Module,
-  ModuleMetadata,
-  Provider,
-  Type,
-} from '@nestjs/common';
-import { APP_GUARD, Reflector } from '@nestjs/core';
-import { ConfigurableModuleClass } from '@nathapp/nestjs-common';
-import { CSRF_MODULE_OPTIONS } from '../constant/csrf.constants';
-import { CsrfModuleOptionsFactory, CsrfOptions } from '../interface/csrf-options.interface';
-import { CsrfTokenService } from '../service/csrf-token.service';
-import { resolveCsrfOptions } from '../service/resolve-options';
-import { DefaultCsrfGuard } from '../guard/csrf.guard';
-
-export type CsrfAsyncModuleOptions = Pick<ModuleMetadata, 'imports'> & {
-  useExisting?: Type<CsrfModuleOptionsFactory>;
-  useClass?: Type<CsrfModuleOptionsFactory>;
-  useFactory?: (...args: any[]) => Promise<CsrfOptions> | CsrfOptions;
-  inject?: any[];
-};
-
-@Module({})
-export class CsrfModule extends ConfigurableModuleClass<CsrfOptions>(
-  CSRF_MODULE_OPTIONS,
-) {
-  static register(options: CsrfOptions): DynamicModule {
-    resolveCsrfOptions(options);
-
-    const base = super.register(options);
-    return CsrfModule.withCsrfProviders(base);
-  }
-
-  static registerAsync(options: CsrfAsyncModuleOptions): DynamicModule {
-    const wrappedAsyncOptions: CsrfAsyncModuleOptions =
-      typeof options.useFactory === 'function'
-        ? {
-            ...options,
-            useFactory: async (...args: any[]) => {
-              const resolved = await options.useFactory!(...args);
-              resolveCsrfOptions(resolved);
-              return resolved;
-            },
-          }
-        : options;
-
-    const base = super.registerAsync(wrappedAsyncOptions);
-    return CsrfModule.withCsrfProviders(base, {
-      imports: options.imports ?? (base.imports ?? []),
-    });
-  }
-
-  private static withCsrfProviders(
-    base: DynamicModule,
-    overrides: Partial<DynamicModule> = {},
-  ): DynamicModule {
-    const baseProviders = (base.providers ?? []) as Provider[];
-
-    return {
-      ...base,
-      module: CsrfModule,
-      global: true,
-      ...overrides,
-      providers: [
-        ...baseProviders,
-        CsrfTokenService,
-        Reflector,
-        DefaultCsrfGuard,
-        { provide: APP_GUARD, useExisting: DefaultCsrfGuard },
-      ],
-      exports: [CsrfTokenService],
-    };
-  }
-}

package/lib/module/index.ts

@@ -1 +0,0 @@
-export { CsrfAsyncModuleOptions, CsrfModule } from './csrf.module';

package/lib/service/csrf-token.service.ts

@@ -1,34 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { createHmac, randomBytes, timingSafeEqual } from 'crypto';
-
-function timingSafeStrEqual(a: string, b: string): boolean {
-  if (typeof a !== 'string' || typeof b !== 'string') return false;
-  const aBuf = Buffer.from(a, 'utf8');
-  const bBuf = Buffer.from(b, 'utf8');
-  if (aBuf.length !== bBuf.length) return false;
-  return timingSafeEqual(aBuf, bBuf);
-}
-
-@Injectable()
-export class CsrfTokenService {
-  mint(secret: string): string {
-    const value = randomBytes(32).toString('hex');
-    const sig = createHmac('sha256', secret).update(value).digest('hex');
-    return `${value}.${sig}`;
-  }
-
-  verify(secret: string, cookieValue?: string, headerValue?: string): boolean {
-    if (!cookieValue || !headerValue) return false;
-    if (!timingSafeStrEqual(cookieValue, headerValue)) return false;
-
-    const dotIndex = cookieValue.indexOf('.');
-    if (dotIndex < 0) return false;
-
-    const value = cookieValue.slice(0, dotIndex);
-    const sig = cookieValue.slice(dotIndex + 1);
-    if (!value || !sig) return false;
-
-    const expected = createHmac('sha256', secret).update(value).digest('hex');
-    return timingSafeStrEqual(sig, expected);
-  }
-}

package/lib/service/index.ts

@@ -1,2 +0,0 @@
-export { CsrfTokenService } from './csrf-token.service';
-export { resolveCsrfOptions } from './resolve-options';

package/lib/service/resolve-options.ts

@@ -1,47 +0,0 @@
-import { CsrfCookieOptions, CsrfOptions, ResolvedCsrfOptions } from '../interface/csrf-options.interface';
-
-const DEFAULT_COOKIE_NAME = 'csrf-token';
-const DEFAULT_HEADER_NAME = 'x-csrf-token';
-const DEFAULT_IGNORE_METHODS = ['GET', 'HEAD', 'OPTIONS'];
-const DEFAULT_COOKIE_PATH = '/';
-const DEFAULT_COOKIE_HTTP_ONLY = false;
-const DEFAULT_COOKIE_SECURE = true;
-const DEFAULT_COOKIE_SAME_SITE: CsrfCookieOptions['sameSite'] = 'lax';
-
-export function resolveCsrfOptions(options: CsrfOptions): ResolvedCsrfOptions {
-  const {
-    secret,
-    enabled = true,
-    headerName: headerNameOverride = DEFAULT_HEADER_NAME,
-    ignoreMethods: ignoreMethodsOverride,
-    skipWhenBearer = true,
-    cookie: cookieOverrides,
-  } = options;
-
-  if (typeof secret !== 'string' || secret.length === 0) {
-    throw new Error('CsrfOptions.secret must be a non-empty string');
-  }
-
-  const headerName = headerNameOverride.toLowerCase();
-
-  const ignoreMethods = ignoreMethodsOverride
-    ? [...ignoreMethodsOverride]
-    : [...DEFAULT_IGNORE_METHODS];
-
-  const cookie: CsrfCookieOptions = {
-    name: cookieOverrides?.name ?? DEFAULT_COOKIE_NAME,
-    path: cookieOverrides?.path ?? DEFAULT_COOKIE_PATH,
-    httpOnly: cookieOverrides?.httpOnly ?? DEFAULT_COOKIE_HTTP_ONLY,
-    secure: cookieOverrides?.secure ?? DEFAULT_COOKIE_SECURE,
-    sameSite: cookieOverrides?.sameSite ?? DEFAULT_COOKIE_SAME_SITE,
-  };
-
-  return {
-    secret,
-    enabled,
-    headerName,
-    ignoreMethods,
-    skipWhenBearer,
-    cookie,
-  };
-}

package/test/csrf-token.service.behavior.spec.ts

@@ -1,110 +0,0 @@
-/* eslint-disable @typescript-eslint/no-var-requires */
-describe('CsrfTokenService.mint / verify', () => {
-  const loadService = () => {
-    const mod = require('../lib');
-    expect(typeof mod.CsrfTokenService).toBe('function');
-    return new mod.CsrfTokenService();
-  };
-
-  it('AC2: verify(secret, token, token) returns true when token was minted with the same secret', () => {
-    const svc = loadService();
-    const token = svc.mint('super-secret');
-    expect(svc.verify('super-secret', token, token)).toBe(true);
-  });
-
-  it('AC2 (boundary): verifies across multiple different secrets', () => {
-    const svc = loadService();
-    const secrets = ['', 'a', 'long-secret-with-various-chars-!@#$%^&*()'];
-    for (const secret of secrets) {
-      const token = svc.mint(secret);
-      expect(svc.verify(secret, token, token)).toBe(true);
-    }
-  });
-
-  it('AC3: verify(secret, token, otherToken) returns false when otherToken !== token', () => {
-    const svc = loadService();
-    const token = svc.mint('super-secret');
-    const otherToken = svc.mint('super-secret');
-    expect(token).not.toBe(otherToken);
-    expect(svc.verify('super-secret', token, otherToken)).toBe(false);
-  });
-
-  it('AC3 (boundary): any byte difference between cookie and header makes verify false', () => {
-    const svc = loadService();
-    const token = svc.mint('super-secret');
-    expect(svc.verify('super-secret', token, token + 'x')).toBe(false);
-    expect(svc.verify('super-secret', 'x' + token, token)).toBe(false);
-  });
-
-  it('AC4: tampered signature makes verify return false', () => {
-    const svc = loadService();
-    const token = svc.mint('super-secret');
-    const [value, sig] = token.split('.');
-    const tamperedSig = sig.startsWith('a') ? `b${sig.slice(1)}` : `a${sig.slice(1)}`;
-    const tampered = `${value}.${tamperedSig}`;
-    expect(tampered).not.toBe(token);
-    expect(svc.verify('super-secret', tampered, tampered)).toBe(false);
-  });
-
-  it('AC4 (boundary): tampered value with bogus signature is rejected', () => {
-    const svc = loadService();
-    const token = svc.mint('super-secret');
-    const [value] = token.split('.');
-    const tampered = `${value}.${'0'.repeat(64)}`;
-    expect(svc.verify('super-secret', tampered, tampered)).toBe(false);
-  });
-
-  it('AC5: verify with a different secret returns false', () => {
-    const svc = loadService();
-    const token = svc.mint('secret-A');
-    expect(svc.verify('secret-B', token, token)).toBe(false);
-  });
-
-  it('AC5 (boundary): verify with an empty string secret against a real token returns false', () => {
-    const svc = loadService();
-    const token = svc.mint('secret-A');
-    expect(svc.verify('', token, token)).toBe(false);
-  });
-
-  it('AC6: verify(secret, "", "") returns false without throwing', () => {
-    const svc = loadService();
-    let result: unknown;
-    expect(() => {
-      result = svc.verify('super-secret', '', '');
-    }).not.toThrow();
-    expect(result).toBe(false);
-  });
-
-  it('AC6 (boundary): undefined cookie / header values return false without throwing', () => {
-    const svc = loadService();
-    let result: unknown;
-    expect(() => {
-      result = svc.verify('super-secret', undefined, undefined);
-    }).not.toThrow();
-    expect(result).toBe(false);
-  });
-
-  it('AC7: verify(secret, "no-separator", "no-separator") returns false without throwing', () => {
-    const svc = loadService();
-    let result: unknown;
-    expect(() => {
-      result = svc.verify('super-secret', 'no-separator', 'no-separator');
-    }).not.toThrow();
-    expect(result).toBe(false);
-  });
-
-  it('AC7 (boundary): token with empty value or empty signature returns false without throwing', () => {
-    const svc = loadService();
-    let result1: unknown;
-    expect(() => {
-      result1 = svc.verify('super-secret', '.sig', '.sig');
-    }).not.toThrow();
-    expect(result1).toBe(false);
-
-    let result2: unknown;
-    expect(() => {
-      result2 = svc.verify('super-secret', 'value.', 'value.');
-    }).not.toThrow();
-    expect(result2).toBe(false);
-  });
-});

package/test/csrf-token.service.spec.ts

@@ -1,18 +0,0 @@
-/* eslint-disable @typescript-eslint/no-var-requires */
-describe('AC1: CsrfTokenService provider', () => {
-  it('AC1: resolves from a compiled Nest testing module', async () => {
-    const { Test } = require('@nestjs/testing');
-    const { CsrfTokenService } = require('../lib');
-
-    expect(typeof CsrfTokenService).toBe('function');
-
-    const moduleRef = await Test.createTestingModule({
-      providers: [CsrfTokenService],
-    }).compile();
-
-    const service = moduleRef.get(CsrfTokenService);
-    expect(service).toBeDefined();
-    expect(typeof service.mint).toBe('function');
-    expect(typeof service.verify).toBe('function');
-  });
-});

package/test/csrf.constants.spec.ts

@@ -1,11 +0,0 @@
-/* eslint-disable @typescript-eslint/no-var-requires */
-describe('CSRF constants', () => {
-  it('AC14: CSRF_MODULE_OPTIONS and SKIP_CSRF_METADATA_KEY are distinct values', () => {
-    const mod = require('../lib');
-    const { CSRF_MODULE_OPTIONS, SKIP_CSRF_METADATA_KEY } = mod;
-
-    expect(CSRF_MODULE_OPTIONS).toBeDefined();
-    expect(SKIP_CSRF_METADATA_KEY).toBeDefined();
-    expect(CSRF_MODULE_OPTIONS).not.toBe(SKIP_CSRF_METADATA_KEY);
-  });
-});