@starci/hfs 4.11.11 → 4.11.13

package/templates/be/skeleton-lite/src/modules/platform/http-security/rate-limit.guard.spec.ts

@@ -0,0 +1,260 @@
+import "reflect-metadata"
+import type { ExecutionContext, Type } from "@nestjs/common"
+import type { Request, Response } from "express"
+import { Reflector } from "@nestjs/core"
+import { Test } from "@nestjs/testing"
+import { In, LessThanOrEqual, MoreThan } from "typeorm"
+import { FakeClock, mock, mockEntityManager, queueQueryBuilders } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { HttpSecurityErrorCode } from "./errors/http-security.error"
+import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
+import type { HttpSecurityOptions } from "./http-security.options"
+import { RateWindowEntity } from "./persistence/entities/rate-window.entity"
+import { RateLimit, RateLimitGuard, RateTier } from "./rate-limit.guard"
+import type { RateLimitExceeded } from "./rate-limit.guard"
+
+const AT = "2026-02-03T04:05:06.000Z"
+const RESET_AT = "2026-02-03T04:06:06.000Z"
+const options: HttpSecurityOptions = {
+    allowedOrigins: [],
+    rateLimit: { windowMs: 60_000, defaultLimit: 2, strictLimit: 1 },
+    webhooks: {},
+}
+
+/** The caller's live window holding `hits`. */
+const windowOf = (hits: number): RateWindowEntity => ({ key: "default:127.0.0.1", hits, resetAt: new Date(RESET_AT) })
+
+/** The answers of a store whose live window of the caller holds `hits` after this hit's increment. */
+const liveWindow = (hits: number) =>
+    ({ increment: [RateWindowEntity, { affected: 1 }], findOneBy: [RateWindowEntity, windowOf(hits)] }) as const
+
+/** The answers of a store where this hit opens the caller's window (no live or ended one) and the prune finds none ended. */
+const OPENING_WINDOW = {
+    increment: [RateWindowEntity, { affected: 0 }],
+    update: [RateWindowEntity, { affected: 0 }],
+    find: [RateWindowEntity, []],
+} as const
+
+const build = async (entityManager: MockEntityManager, tier?: RateTier, exceeded?: RateLimitExceeded) => {
+    const reflector = mock<Reflector>()
+    reflector.getAllAndOverride.mockImplementation((key: unknown) =>
+        key === "platform.http-security.rate-exceeded" ? exceeded : tier,
+    )
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            RateLimitGuard,
+            { provide: Reflector, useValue: reflector },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: HTTP_SECURITY_OPTIONS, useValue: options },
+            { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
+        ],
+    }).compile()
+    return { guard: moduleRef.get(RateLimitGuard), reflector }
+}
+
+/** An execution context of one POST from `ip` on the door; the handler and the class carry the tier metadata. */
+const contextOf = (
+    ip: string | undefined,
+    handler = () => undefined,
+    door: Type<unknown> = class Door {},
+    response = mock<Response>(),
+) => {
+    const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
+    http.getRequest.mockImplementation(() => mock<Request>({ headers: {}, method: "POST", ip }))
+    http.getResponse.mockReturnValue(response)
+    const context = mock<ExecutionContext>()
+    context.getType.mockReturnValue("http")
+    context.switchToHttp.mockReturnValue(http)
+    context.getHandler.mockReturnValue(handler)
+    context.getClass.mockReturnValue(door)
+    return context
+}
+
+describe("RateLimit", () => {
+    it("marks a door with the tier it declares, and the guard counts it under that tier's limit", async () => {
+        class Door {}
+        RateLimit(RateTier.Strict)(Door)
+        const entityManager = mockEntityManager(liveWindow(2))
+        const { guard, reflector } = await build(entityManager, RateTier.Strict)
+        const handler = () => undefined
+
+        expect(Reflect.getMetadata("platform.http-security.rate-tier", Door)).toBe(RateTier.Strict)
+        await expect(guard.canActivate(contextOf("127.0.0.1", handler, Door))).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RateLimited,
+        })
+        expect(reflector.getAllAndOverride).toHaveBeenCalledWith("platform.http-security.rate-tier", [handler, Door])
+        expect(entityManager.increment).toHaveBeenCalledWith(
+            RateWindowEntity,
+            { key: "strict:127.0.0.1", resetAt: MoreThan(new Date(AT)) },
+            "hits",
+            1,
+        )
+    })
+
+    it("marks a redirect-only door with its exceeded redirect beside the tier", () => {
+        class Door {}
+        RateLimit(RateTier.Strict, { redirect: "/sign-in?auth=error" })(Door)
+
+        expect(Reflect.getMetadata("platform.http-security.rate-tier", Door)).toBe(RateTier.Strict)
+        expect(Reflect.getMetadata("platform.http-security.rate-exceeded", Door)).toEqual({
+            redirect: "/sign-in?auth=error",
+        })
+    })
+
+    it.each(["https://foreign.test/sign-in", "//foreign.test/sign-in", "/\\foreign.test", "sign-in"])(
+        "refuses an exceeded redirect %s that is not a same-site path",
+        (redirect) => {
+            expect(() => RateLimit(RateTier.Strict, { redirect })).toThrow(HttpSecurityErrorCode.RequestInvalid)
+        },
+    )
+})
+
+describe("RateLimitGuard", () => {
+    it("admits a caller under the default limit of an unmarked door, counting in the shared live window", async () => {
+        const entityManager = mockEntityManager(liveWindow(2))
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
+        expect(entityManager.findOneBy).toHaveBeenCalledWith(RateWindowEntity, { key: "default:127.0.0.1" })
+    })
+
+    it("refuses a caller whose shared window is over the default limit", async () => {
+        const { guard } = await build(mockEntityManager(liveWindow(3)))
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RateLimited,
+        })
+    })
+
+    it("refuses the request when the counted window vanished before it was read", async () => {
+        const entityManager = mockEntityManager({
+            increment: [RateWindowEntity, { affected: 1 }],
+            findOneBy: [RateWindowEntity, null],
+        })
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RateLimited,
+        })
+    })
+})
+
+describe("RateLimitGuard opening a window", () => {
+    it("restarts an ended window at one hit and prunes the ended windows", async () => {
+        const ended = windowOf(5)
+        const entityManager = mockEntityManager({
+            increment: [RateWindowEntity, {}],
+            update: [RateWindowEntity, { affected: 1 }],
+            find: [RateWindowEntity, [ended]],
+            delete: [RateWindowEntity, { affected: 1 }],
+        })
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
+        expect(entityManager.update).toHaveBeenCalledWith(
+            RateWindowEntity,
+            { key: "default:127.0.0.1", resetAt: LessThanOrEqual(new Date(AT)) },
+            { hits: 1, resetAt: new Date(RESET_AT) },
+        )
+        expect(entityManager.find).toHaveBeenCalledWith(RateWindowEntity, {
+            select: { key: true },
+            where: { resetAt: LessThanOrEqual(new Date(AT)) },
+            order: { resetAt: "ASC" },
+            take: 100,
+        })
+        expect(entityManager.delete).toHaveBeenCalledWith(RateWindowEntity, {
+            key: In([ended.key]),
+            resetAt: LessThanOrEqual(new Date(AT)),
+        })
+    })
+
+    it("opens a missing window at one hit, ignoring a concurrent opener, and deletes nothing when no window ended", async () => {
+        const entityManager = mockEntityManager(OPENING_WINDOW)
+        const [opened] = queueQueryBuilders(entityManager, [{ execute: {} }])
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
+        expect(opened?.callsOf("values")).toEqual([
+            [{ key: "default:127.0.0.1", hits: 1, resetAt: new Date(RESET_AT) }],
+        ])
+        expect(opened?.callsOf("orIgnore")).toEqual([[]])
+        expect(entityManager.delete).not.toHaveBeenCalled()
+    })
+
+    it("opens a window when the restart answers no affected count", async () => {
+        const entityManager = mockEntityManager({
+            increment: [RateWindowEntity, { affected: 0 }],
+            update: [RateWindowEntity, {}],
+            find: [RateWindowEntity, []],
+        })
+        const [opened] = queueQueryBuilders(entityManager, [{ execute: {} }])
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
+        expect(opened?.callsOf("insert")).toEqual([[]])
+    })
+})
+
+describe("RateLimitGuard keys", () => {
+    it("counts a request without an address under the unknown key", async () => {
+        const entityManager = mockEntityManager(liveWindow(2))
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf(undefined))).resolves.toBe(true)
+        expect(entityManager.findOneBy).toHaveBeenCalledWith(RateWindowEntity, { key: "default:unknown" })
+    })
+
+    it("bounds the window key to the length the table stores", async () => {
+        const entityManager = mockEntityManager(liveWindow(2))
+        const { guard } = await build(entityManager)
+
+        await guard.canActivate(contextOf("f".repeat(300)))
+
+        expect(entityManager.findOneBy).toHaveBeenCalledWith(RateWindowEntity, { key: `default:${"f".repeat(120)}` })
+    })
+})
+
+describe("RateLimitGuard on a redirect-only door", () => {
+    const EXCEEDED: RateLimitExceeded = { redirect: "/sign-in?auth=error" }
+
+    /** A response whose redirect is a plain double, so the spec reads the call without the deprecated overload. */
+    const responseOf = () => {
+        const redirect = jest.fn()
+        return { response: mock<Response>({ redirect }), redirect }
+    }
+
+    it("answers the door's own 303 when the caller is over the limit, and still refuses", async () => {
+        const { guard } = await build(mockEntityManager(liveWindow(2)), RateTier.Strict, EXCEEDED)
+        const { response, redirect } = responseOf()
+
+        await expect(
+            guard.canActivate(contextOf("127.0.0.1", () => undefined, class Door {}, response)),
+        ).rejects.toMatchObject({ code: HttpSecurityErrorCode.RateLimited })
+        expect(redirect).toHaveBeenCalledWith(303, "/sign-in?auth=error")
+    })
+
+    it("writes no redirect while the caller is under the limit", async () => {
+        const entityManager = mockEntityManager(OPENING_WINDOW)
+        queueQueryBuilders(entityManager, [{ execute: {} }])
+        const { guard } = await build(entityManager, RateTier.Strict, EXCEEDED)
+        const { response, redirect } = responseOf()
+
+        await expect(guard.canActivate(contextOf("127.0.0.1", () => undefined, class Door {}, response))).resolves.toBe(
+            true,
+        )
+        expect(redirect).not.toHaveBeenCalled()
+    })
+
+    it("refuses a GraphQL operation over the limit without writing a redirect", async () => {
+        const { guard } = await build(mockEntityManager(liveWindow(2)), RateTier.Strict, EXCEEDED)
+        const { response, redirect } = responseOf()
+        const context = contextOf("127.0.0.1", () => undefined, class Door {}, response)
+        context.getType.mockReturnValue("graphql")
+        context.getArgs.mockReturnValue([{}, {}, { req: mock<Request>({ headers: {}, ip: "127.0.0.1" }) }, {}])
+
+        await expect(guard.canActivate(context)).rejects.toMatchObject({ code: HttpSecurityErrorCode.RateLimited })
+        expect(redirect).not.toHaveBeenCalled()
+    })
+})

package/templates/be/skeleton-lite/src/modules/platform/http-security/rate-limit.guard.ts

@@ -0,0 +1,133 @@
+import { Injectable, SetMetadata, applyDecorators } from "@nestjs/common"
+import type { CanActivate, ExecutionContext } from "@nestjs/common"
+import type { Reflector } from "@nestjs/core"
+import type { Response } from "express"
+import { In, LessThanOrEqual, MoreThan } from "typeorm"
+import type { EntityManager } from "typeorm"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { InjectReflector } from "@modules/platform/composition"
+import type { DoorDecorator } from "@modules/platform/composition"
+import { InjectPrimaryEntityManager } from "@modules/platform/database"
+import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
+import { requestOf } from "./execution-request.mapper"
+import { InjectHttpSecurityOptions } from "./http-security.decorators"
+import type { HttpSecurityOptions } from "./http-security.options"
+import { RateWindowEntity } from "./persistence/entities/rate-window.entity"
+
+/** The rate limit tiers of a door. */
+export enum RateTier {
+    /** The global default tier. */
+    Default = "default",
+    /** The tight tier every authentication handshake and signed webhook carries. */
+    Strict = "strict",
+}
+
+/** What a door answers when its caller is over the limit, when that is not the 429 error body. */
+export interface RateLimitExceeded {
+    /** A same-site path the door's own contract answers with a 303 (an OAuth callback's error redirect). */
+    readonly redirect: string
+}
+
+const RATE_TIER_KEY = "platform.http-security.rate-tier"
+const RATE_EXCEEDED_KEY = "platform.http-security.rate-exceeded"
+/** The longest window key the table stores: the tier, a colon and the caller address. */
+const KEY_MAX = 128
+/** The most ended windows one fresh window prunes. */
+const PRUNE_BATCH = 100
+
+/** A same-site path: one leading slash, never a protocol-relative `//` or `/\` that leaves the site. */
+const isSameSitePath = (location: string): boolean =>
+    location.startsWith("/") && !location.startsWith("//") && !location.startsWith("/\\")
+
+/**
+ * Marks a door with a rate limit tier other than the default. A door whose contract answers only redirects (an OAuth
+ * callback) names its error redirect in `exceeded`, and a caller over the limit gets that 303 instead of a 429 body.
+ */
+export const RateLimit = (tier: RateTier, exceeded?: RateLimitExceeded): DoorDecorator => {
+    if (exceeded === undefined) return applyDecorators(SetMetadata(RATE_TIER_KEY, tier))
+    if (!isSameSitePath(exceeded.redirect))
+        throw new HttpSecurityError({
+            code: HttpSecurityErrorCode.RequestInvalid,
+            params: { fields: "RATE_LIMIT_REDIRECT" },
+        })
+    return applyDecorators(SetMetadata(RATE_TIER_KEY, tier), SetMetadata(RATE_EXCEEDED_KEY, exceeded))
+}
+
+@Injectable()
+/**
+ * The first app guard: a fixed-window counter per caller address and tier, stamped by the Clock and kept in the primary
+ * database through its entity, so every replica counts against the same window. A hit that opens a fresh window also prunes
+ * a bounded batch of expired windows.
+ */
+export class RateLimitGuard implements CanActivate {
+    constructor(
+        @InjectReflector() private readonly reflector: Reflector,
+        @InjectClock() private readonly clock: Clock,
+        @InjectHttpSecurityOptions() private readonly options: HttpSecurityOptions,
+        @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
+    ) {}
+
+    /**
+     * Counts the request and refuses it when the caller is over the limit of the door tier. A door that declares its
+     * exceeded redirect has the 303 written here; the refusal still travels, and the errors filter leaves the sent
+     * response as it is.
+     */
+    async canActivate(context: ExecutionContext): Promise<boolean> {
+        const targets = [context.getHandler(), context.getClass()]
+        const tier = this.reflector.getAllAndOverride<RateTier | undefined>(RATE_TIER_KEY, targets) ?? RateTier.Default
+        const limit =
+            tier === RateTier.Strict ? this.options.rateLimit.strictLimit : this.options.rateLimit.defaultLimit
+        const now = this.clock.now()
+        const key = `${tier}:${requestOf(context).ip ?? "unknown"}`.slice(0, KEY_MAX)
+        const resetAt = new Date(now.getTime() + this.options.rateLimit.windowMs)
+        const hits = await this.hit(key, now, resetAt)
+        if (hits === 1) await this.prune(now)
+        if (hits <= limit) return true
+        const exceeded = this.reflector.getAllAndOverride<RateLimitExceeded | undefined>(RATE_EXCEEDED_KEY, targets)
+        if (exceeded !== undefined && context.getType() === "http")
+            context.switchToHttp().getResponse<Response>().redirect(303, exceeded.redirect)
+        throw new HttpSecurityError({ code: HttpSecurityErrorCode.RateLimited })
+    }
+
+    /**
+     * Counts one hit in the caller's window and answers the hits it holds: a live window grows by one in one atomic increment,
+     * an ended window restarts at one hit ending at `resetAt`, and a missing one opens at one hit (a concurrent opener's row
+     * wins and this hit is its first). A window that vanished between the writes counts as over every limit.
+     */
+    private async hit(key: string, now: Date, resetAt: Date): Promise<number> {
+        const counted = await this.entityManager.increment(RateWindowEntity, { key, resetAt: MoreThan(now) }, "hits", 1)
+        if ((counted.affected ?? 0) > 0) {
+            const window = await this.entityManager.findOneBy(RateWindowEntity, { key })
+            return window?.hits ?? Number.POSITIVE_INFINITY
+        }
+        const restarted = await this.entityManager.update(
+            RateWindowEntity,
+            { key, resetAt: LessThanOrEqual(now) },
+            { hits: 1, resetAt },
+        )
+        if ((restarted.affected ?? 0) > 0) return 1
+        await this.entityManager
+            .createQueryBuilder(RateWindowEntity, "window")
+            .insert()
+            .values({ key, hits: 1, resetAt })
+            .orIgnore()
+            .execute()
+        return 1
+    }
+
+    /** Deletes a bounded batch of the windows that ended by `now`; a window a hit restarted meanwhile is kept. */
+    private async prune(now: Date): Promise<void> {
+        const ended = await this.entityManager.find(RateWindowEntity, {
+            select: { key: true },
+            where: { resetAt: LessThanOrEqual(now) },
+            order: { resetAt: "ASC" },
+            take: PRUNE_BATCH,
+        })
+        if (ended.length === 0) return
+        await this.entityManager.delete(RateWindowEntity, {
+            key: In(ended.map((window) => window.key)),
+            resetAt: LessThanOrEqual(now),
+        })
+    }
+}