@starci/hfs 4.11.13 → 4.11.16

package/templates/be/skeleton/src/modules/platform/database/returned-rows.policy.ts

@@ -0,0 +1,61 @@
+import { isRecord } from "@modules/platform/primitives"
+import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
+
+/** What node-postgres hands back for one returned column; a kind ending in `?` also admits SQL null. */
+interface ColumnTypes {
+    readonly string: string
+    readonly number: number
+    readonly boolean: boolean
+    readonly date: Date
+    readonly json: unknown
+    readonly "string?": string | null
+    readonly "number?": number | null
+    readonly "boolean?": boolean | null
+    readonly "date?": Date | null
+}
+
+/** The kind one returned column is checked against. */
+type ColumnKind = keyof ColumnTypes
+
+/** The returned columns of one statement, each named as the database returns it (snake_case) with its kind. */
+type ColumnShape = Readonly<Record<string, ColumnKind>>
+
+/** The row a shape describes: every named column, typed by its kind. */
+type RowOf<Shape extends ColumnShape> = { readonly [Column in keyof Shape]: ColumnTypes[Shape[Column]] }
+
+/** A guard that proves one returned row has the shape its returned columns give it. */
+type RowGuard<Row> = (value: unknown) => value is Row
+
+/** Whether `value` is of the non-null part of a kind. */
+const KIND_CHECKS: Readonly<Record<ColumnKind, (value: unknown) => boolean>> = {
+    string: (value) => typeof value === "string",
+    number: (value) => typeof value === "number",
+    boolean: (value) => typeof value === "boolean",
+    date: (value) => value instanceof Date,
+    json: (value) => value !== undefined,
+    "string?": (value) => value === null || typeof value === "string",
+    "number?": (value) => value === null || typeof value === "number",
+    "boolean?": (value) => value === null || typeof value === "boolean",
+    "date?": (value) => value === null || value instanceof Date,
+}
+
+/**
+ * The guard of the rows a RETURNING clause answers for `shape`: an object holding every named column with a value of its kind.
+ * A column the statement does not return is refused, so the shape and the RETURNING list cannot drift apart unseen.
+ */
+export const rowShape =
+    <Shape extends ColumnShape>(shape: Shape): RowGuard<RowOf<Shape>> =>
+    (value: unknown): value is RowOf<Shape> =>
+        isRecord(value) && Object.entries(shape).every(([column, kind]) => KIND_CHECKS[kind](value[column]))
+
+/**
+ * The rows a RETURNING statement answered, each proven by `isRow`: the result of `manager.query` for an INSERT or a CTE-wrapped
+ * UPDATE or DELETE, or the `raw` of a query builder's `execute()`. A result that is not a list of rows, or a row the guard
+ * refuses, throws `DATABASE_RETURNING_ROW_REJECTED`: the statement and the shape its caller expects disagree.
+ */
+export const returnedRows = <Row>(raw: unknown, isRow: RowGuard<Row>): Array<Row> => {
+    if (!Array.isArray(raw)) throw new DatabaseError({ code: DatabaseErrorCode.ReturningRowRejected })
+    const rows: ReadonlyArray<unknown> = raw
+    if (!rows.every(isRow)) throw new DatabaseError({ code: DatabaseErrorCode.ReturningRowRejected })
+    return [...rows]
+}

package/templates/be/skeleton/src/modules/platform/http-security/http-security.decorators.ts

@@ -1,8 +1,15 @@
+import { SetMetadata } from "@nestjs/common"
 import { injector } from "@modules/platform/composition"
-import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { DoorDecorator, TypedParameterDecorator } from "@modules/platform/composition"
 import type { HttpSecurityOptions } from "./http-security.options"
 import type { WebhookSignatureService } from "./webhook-signature.service"
 
+/** Metadata for doors that require an actual Origin, including the start of a cookie-authenticated flow. */
+export const REQUIRE_ORIGIN_KEY = "platform.http-security.require-origin"
+
+/** Requires an allowed Origin on mutations even before the caller has received its first cookie. */
+export const RequireOrigin = (): DoorDecorator => SetMetadata(REQUIRE_ORIGIN_KEY, true)
+
 /** Token of the http-security options, exported so a spec can provide it. */
 export const HTTP_SECURITY_OPTIONS: unique symbol = Symbol("platform.http-security.options")
 

package/templates/be/skeleton/src/modules/platform/http-security/origin.guard.spec.ts

@@ -5,7 +5,7 @@ import { Reflector } from "@nestjs/core"
 import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 import { HttpSecurityErrorCode } from "./errors/http-security.error"
-import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
+import { HTTP_SECURITY_OPTIONS, RequireOrigin } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
 import { OriginGuard, ServerToServer } from "./origin.guard"
 
@@ -17,16 +17,31 @@ const options: HttpSecurityOptions = {
 
 class OpenDoor {}
 
+@RequireOrigin()
+class CookieDoor {}
+
+class SignInDoor {
+    @RequireOrigin()
+    start(): undefined {
+        return undefined
+    }
+}
+
 class SignedDoor {}
 ServerToServer()(SignedDoor)
 
-const build = async (method: string, headers: Request["headers"], door: Type<unknown> = OpenDoor) => {
+const build = async (
+    method: string,
+    headers: Request["headers"],
+    door: Type<unknown> = OpenDoor,
+    handler: () => void = () => undefined,
+) => {
     const request = mock<Request>({ headers, method })
     const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
     http.getRequest.mockReturnValue(request)
     const context = mock<ExecutionContext>()
     context.switchToHttp.mockReturnValue(http)
-    context.getHandler.mockReturnValue(() => undefined)
+    context.getHandler.mockReturnValue(handler)
     context.getClass.mockReturnValue(door)
     const moduleRef = await Test.createTestingModule({
         providers: [OriginGuard, Reflector, { provide: HTTP_SECURITY_OPTIONS, useValue: options }],
@@ -36,19 +51,23 @@ const build = async (method: string, headers: Request["headers"], door: Type<unk
 
 describe("OriginGuard", () => {
     it.each(["GET", "HEAD", "OPTIONS"])("allows the safe %s method without an origin", async (method) => {
-        const { guard, context } = await build(method, {})
+        const { guard, context } = await build(method, { cookie: "session=opaque" }, CookieDoor)
 
         expect(guard.canActivate(context)).toBe(true)
     })
 
     it("allows a state-changing request carrying an allowed Origin header", async () => {
-        const { guard, context } = await build("POST", { origin: "https://app.test" })
+        const { guard, context } = await build("POST", {
+            origin: "https://app.test",
+        })
 
         expect(guard.canActivate(context)).toBe(true)
     })
 
     it("falls back to the origin of an allowed Referer when Origin is absent", async () => {
-        const { guard, context } = await build("PATCH", { referer: "https://app.test/notes/one" })
+        const { guard, context } = await build("PATCH", {
+            referer: "https://app.test/notes/one",
+        })
 
         expect(guard.canActivate(context)).toBe(true)
     })
@@ -56,12 +75,21 @@ describe("OriginGuard", () => {
     it.each([
         { name: "no Origin and no Referer", headers: {} },
         { name: "a Referer that is not a URL", headers: { referer: "not a URL" } },
-        { name: "an Origin outside the allowlist", headers: { origin: "https://foreign.test" } },
+        {
+            name: "an Origin outside the allowlist",
+            headers: { origin: "https://foreign.test" },
+        },
         { name: "the opaque null Origin", headers: { origin: "null" } },
-        { name: "a Referer outside the allowlist", headers: { referer: "https://foreign.test/form" } },
+        {
+            name: "a Referer outside the allowlist",
+            headers: { referer: "https://foreign.test/form" },
+        },
         {
             name: "a foreign Origin beside an allowed Referer",
-            headers: { origin: "https://foreign.test", referer: "https://app.test/notes/one" },
+            headers: {
+                origin: "https://foreign.test",
+                referer: "https://app.test/notes/one",
+            },
         },
     ])("refuses a state-changing request with $name", async ({ headers }) => {
         const { guard, context } = await build("DELETE", headers)
@@ -75,3 +103,87 @@ describe("OriginGuard", () => {
         expect(guard.canActivate(context)).toBe(true)
     })
 })
+
+describe("OriginGuard", () => {
+    it.each(["POST", "PUT", "PATCH", "DELETE"])(
+        "allows a cookie-bearing %s with an actual allowed Origin",
+        async (method) => {
+            const { guard, context } = await build(method, {
+                origin: "https://app.test",
+                cookie: "session=opaque",
+            })
+
+            expect(guard.canActivate(context)).toBe(true)
+        },
+    )
+
+    it.each([
+        { name: "no Origin", headers: {} },
+        {
+            name: "an allowed Referer alone",
+            headers: { referer: "https://app.test/form" },
+        },
+        { name: "a malformed Referer alone", headers: { referer: "not a URL" } },
+        { name: "a foreign Origin", headers: { origin: "https://foreign.test" } },
+        { name: "an opaque Origin", headers: { origin: "null" } },
+        { name: "an empty Origin", headers: { origin: "" } },
+        {
+            name: "a foreign Origin beside an allowed Referer",
+            headers: {
+                origin: "https://foreign.test",
+                referer: "https://app.test/form",
+            },
+        },
+    ])("refuses a cookie-bearing mutation with $name", async ({ headers }) => {
+        const { guard, context } = await build("POST", {
+            ...headers,
+            cookie: "session=opaque",
+        })
+
+        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.OriginRejected)
+    })
+})
+
+describe("OriginGuard", () => {
+    it.each([{}, { referer: "https://app.test/sign-in" }])(
+        "refuses a marked cookie-flow door without Origin before a cookie exists (%o)",
+        async (headers) => {
+            const { guard, context } = await build("POST", headers, CookieDoor)
+
+            expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.OriginRejected)
+        },
+    )
+
+    it("requires Origin on an individually marked handler before a cookie exists", async () => {
+        const { guard, context } = await build("POST", {}, SignInDoor, SignInDoor.prototype.start)
+
+        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.OriginRejected)
+    })
+
+    it("admits a marked cookie-flow door with an actual allowed Origin before a cookie exists", async () => {
+        const { guard, context } = await build("POST", { origin: "https://app.test" }, CookieDoor)
+
+        expect(guard.canActivate(context)).toBe(true)
+    })
+
+    it("refuses Referer-only admission when a server-to-server door receives a cookie", async () => {
+        const { guard, context } = await build(
+            "POST",
+            { cookie: "session=opaque", referer: "https://app.test/form" },
+            SignedDoor,
+        )
+
+        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.OriginRejected)
+    })
+
+    it("refuses Referer-only admission when a server-to-server handler requires Origin", async () => {
+        const { guard, context } = await build(
+            "POST",
+            { referer: "https://app.test/form" },
+            SignedDoor,
+            SignInDoor.prototype.start,
+        )
+
+        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.OriginRejected)
+    })
+})

package/templates/be/skeleton/src/modules/platform/http-security/origin.guard.ts

@@ -4,7 +4,7 @@ import type { Reflector } from "@nestjs/core"
 import { InjectReflector } from "@modules/platform/composition"
 import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
 import { requestOf } from "./execution-request.mapper"
-import { InjectHttpSecurityOptions } from "./http-security.decorators"
+import { InjectHttpSecurityOptions, REQUIRE_ORIGIN_KEY } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
 
 const SAFE_METHODS: ReadonlySet<string> = new Set(["GET", "HEAD", "OPTIONS"])
@@ -26,9 +26,8 @@ const originOf = (origin: string | undefined, referer: string | undefined): stri
 
 @Injectable()
 /**
- * The second app guard, the CSRF defence: a state-changing request must name an allowed origin, by its Origin header or,
- * when Origin is absent, by its Referer. A request that names none is refused, since a session cookie rides on it
- * whatever sent it. A door marked `ServerToServer` proves its caller itself and owes no origin.
+ * The second app guard, the CSRF defence: cookie-bearing mutations and doors marked RequireOrigin need an actual allowed
+ * Origin. Other mutations retain Referer fallback and the ServerToServer exemption for callers proving themselves.
  */
 export class OriginGuard implements CanActivate {
     constructor(
@@ -40,12 +39,19 @@ export class OriginGuard implements CanActivate {
     canActivate(context: ExecutionContext): boolean {
         const request = requestOf(context)
         if (SAFE_METHODS.has(request.method)) return true
+        const requiresOrigin =
+            this.reflector.getAllAndOverride<boolean | undefined>(REQUIRE_ORIGIN_KEY, [
+                context.getHandler(),
+                context.getClass(),
+            ]) === true || request.headers.cookie !== undefined
         const exempt = this.reflector.getAllAndOverride<boolean | undefined>(SERVER_TO_SERVER_KEY, [
             context.getHandler(),
             context.getClass(),
         ])
-        if (exempt === true) return true
-        const origin = originOf(request.headers.origin, request.headers.referer)
+        if (!requiresOrigin && exempt === true) return true
+        const origin = requiresOrigin
+            ? request.headers.origin
+            : originOf(request.headers.origin, request.headers.referer)
         if (origin !== undefined && this.options.allowedOrigins.includes(origin)) return true
         throw new HttpSecurityError({ code: HttpSecurityErrorCode.OriginRejected })
     }

package/templates/be/skeleton/src/modules/platform/http-security/persistence/rate-limit.rows.ts

@@ -1,5 +1,10 @@
+import { rowShape } from "@modules/platform/database"
+
 /** The row HIT_RATE_WINDOW answers. */
 export interface RateWindowRow {
     /** The hits of the caller's current window, this one included. */
     readonly hits: number
 }
+
+/** Proves one row HIT_RATE_WINDOW answered is a RateWindowRow. */
+export const isRateWindowRow: (value: unknown) => value is RateWindowRow = rowShape({ hits: "number" })

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

@@ -7,12 +7,12 @@ 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 { InjectPrimaryEntityManager, returnedRows } 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 type { RateWindowRow } from "./persistence/rate-limit.rows"
+import { isRateWindowRow } from "./persistence/rate-limit.rows"
 import { HIT_RATE_WINDOW, PRUNE_RATE_WINDOWS } from "./persistence/rate-limit.sql"
 
 /** The rate limit tiers of a door. */
@@ -79,7 +79,7 @@ export class RateLimitGuard implements CanActivate {
         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 rows: Array<RateWindowRow> = await this.entityManager.query(HIT_RATE_WINDOW, [key, now, resetAt])
+        const rows = returnedRows(await this.entityManager.query(HIT_RATE_WINDOW, [key, now, resetAt]), isRateWindowRow)
         const hits = rows[0]?.hits ?? Number.POSITIVE_INFINITY
         if (hits === 1) await this.entityManager.query(PRUNE_RATE_WINDOWS, [now])
         if (hits <= limit) return true

package/templates/be/skeleton-lite/src/modules/platform/database/errors/database.error.ts

@@ -7,12 +7,15 @@ export enum DatabaseErrorCode {
     ConnectionUndeclared = "DATABASE_CONNECTION_UNDECLARED",
     /** A dynamic SQL identifier was not on the names its caller allows. */
     IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",
+    /** A RETURNING statement answered something other than rows of the shape its caller expects. */
+    ReturningRowRejected = "DATABASE_RETURNING_ROW_REJECTED",
 }
 
 /** How each database code travels. */
 export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {
     [DatabaseErrorCode.ConnectionUndeclared]: "internal",
     [DatabaseErrorCode.IdentifierRejected]: "internal",
+    [DatabaseErrorCode.ReturningRowRejected]: "internal",
 }
 
 /** The one error class of the database capability. */

package/templates/be/skeleton-lite/src/modules/platform/database/index.ts

@@ -4,4 +4,5 @@ export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"
 export { PRIMARY_DATA_SOURCE } from "./database.port"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
+export { returnedRows, rowShape } from "./returned-rows.policy"
 export { parsePrimaryDatabaseConfig } from "./primary.config"

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

@@ -5,7 +5,7 @@ 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 type { FakeQueryBuilder, 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"
@@ -23,20 +23,31 @@ const options: HttpSecurityOptions = {
     webhooks: {},
 }
 
-/** The caller's live window holding `hits`. */
+/** The caller's 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
+/** A store with a live window of the caller, and the builder of the UPDATE that counted this hit in it. */
+interface LiveWindow {
+    readonly entityManager: MockEntityManager
+    readonly counting: FakeQueryBuilder | undefined
+}
+
+/** A store whose live window of the caller holds `hits` after this hit: the counting UPDATE returns them. */
+const liveWindow = (hits: number): LiveWindow => {
+    const entityManager = mockEntityManager()
+    const [counting] = queueQueryBuilders(entityManager, [{ execute: { raw: [{ hits }] } }])
+    return { entityManager, counting }
+}
 
 /** 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
 
+/** The counting UPDATE of a hit that finds no live window: it returns no row. */
+const NO_LIVE_WINDOW = { execute: { raw: [] } } as const
+
 const build = async (entityManager: MockEntityManager, tier?: RateTier, exceeded?: RateLimitExceeded) => {
     const reflector = mock<Reflector>()
     reflector.getAllAndOverride.mockImplementation((key: unknown) =>
@@ -76,7 +87,7 @@ 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 { entityManager, counting } = liveWindow(2)
         const { guard, reflector } = await build(entityManager, RateTier.Strict)
         const handler = () => undefined
 
@@ -85,12 +96,7 @@ describe("RateLimit", () => {
             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,
-        )
+        expect(counting?.callsOf("where")).toEqual([[{ key: "strict:127.0.0.1", resetAt: MoreThan(new Date(AT)) }]])
     })
 
     it("marks a redirect-only door with its exceeded redirect beside the tier", () => {
@@ -113,30 +119,31 @@ describe("RateLimit", () => {
 
 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 { entityManager, counting } = 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" })
+        expect(counting?.callsOf("update")).toEqual([[]])
+        expect(counting?.callsOf("returning")).toEqual([["hits"]])
+        expect(counting?.callsOf("where")).toEqual([[{ key: "default:127.0.0.1", resetAt: MoreThan(new Date(AT)) }]])
+        expect(entityManager.update).not.toHaveBeenCalled()
     })
 
     it("refuses a caller whose shared window is over the default limit", async () => {
-        const { guard } = await build(mockEntityManager(liveWindow(3)))
+        const { guard } = await build(liveWindow(3).entityManager)
 
         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],
-        })
+    it("refuses to count from a returned row that is not the window's hits", async () => {
+        const entityManager = mockEntityManager()
+        queueQueryBuilders(entityManager, [{ execute: { raw: [{ hits: "2" }] } }])
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).rejects.toMatchObject({
-            code: HttpSecurityErrorCode.RateLimited,
+            code: "DATABASE_RETURNING_ROW_REJECTED",
         })
     })
 })
@@ -145,11 +152,11 @@ 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 }],
         })
+        queueQueryBuilders(entityManager, [NO_LIVE_WINDOW])
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
@@ -172,7 +179,7 @@ describe("RateLimitGuard opening a window", () => {
 
     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 [, opened] = queueQueryBuilders(entityManager, [NO_LIVE_WINDOW, { execute: {} }])
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
@@ -185,11 +192,10 @@ describe("RateLimitGuard opening a window", () => {
 
     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 [, opened] = queueQueryBuilders(entityManager, [NO_LIVE_WINDOW, { execute: {} }])
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
@@ -199,20 +205,22 @@ describe("RateLimitGuard opening a window", () => {
 
 describe("RateLimitGuard keys", () => {
     it("counts a request without an address under the unknown key", async () => {
-        const entityManager = mockEntityManager(liveWindow(2))
+        const { entityManager, counting } = liveWindow(2)
         const { guard } = await build(entityManager)
 
         await expect(guard.canActivate(contextOf(undefined))).resolves.toBe(true)
-        expect(entityManager.findOneBy).toHaveBeenCalledWith(RateWindowEntity, { key: "default:unknown" })
+        expect(counting?.callsOf("where")).toEqual([[{ key: "default:unknown", resetAt: MoreThan(new Date(AT)) }]])
     })
 
     it("bounds the window key to the length the table stores", async () => {
-        const entityManager = mockEntityManager(liveWindow(2))
+        const { entityManager, counting } = liveWindow(2)
         const { guard } = await build(entityManager)
 
         await guard.canActivate(contextOf("f".repeat(300)))
 
-        expect(entityManager.findOneBy).toHaveBeenCalledWith(RateWindowEntity, { key: `default:${"f".repeat(120)}` })
+        expect(counting?.callsOf("where")).toEqual([
+            [{ key: `default:${"f".repeat(120)}`, resetAt: MoreThan(new Date(AT)) }],
+        ])
     })
 })
 
@@ -226,7 +234,7 @@ describe("RateLimitGuard on a redirect-only door", () => {
     }
 
     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 { guard } = await build(liveWindow(2).entityManager, RateTier.Strict, EXCEEDED)
         const { response, redirect } = responseOf()
 
         await expect(
@@ -237,7 +245,7 @@ describe("RateLimitGuard on a redirect-only door", () => {
 
     it("writes no redirect while the caller is under the limit", async () => {
         const entityManager = mockEntityManager(OPENING_WINDOW)
-        queueQueryBuilders(entityManager, [{ execute: {} }])
+        queueQueryBuilders(entityManager, [NO_LIVE_WINDOW, { execute: {} }])
         const { guard } = await build(entityManager, RateTier.Strict, EXCEEDED)
         const { response, redirect } = responseOf()
 
@@ -248,7 +256,7 @@ describe("RateLimitGuard on a redirect-only door", () => {
     })
 
     it("refuses a GraphQL operation over the limit without writing a redirect", async () => {
-        const { guard } = await build(mockEntityManager(liveWindow(2)), RateTier.Strict, EXCEEDED)
+        const { guard } = await build(liveWindow(2).entityManager, RateTier.Strict, EXCEEDED)
         const { response, redirect } = responseOf()
         const context = contextOf("127.0.0.1", () => undefined, class Door {}, response)
         context.getType.mockReturnValue("graphql")

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

@@ -8,7 +8,7 @@ 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 { InjectPrimaryEntityManager, returnedRows, rowShape } from "@modules/platform/database"
 import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
 import { requestOf } from "./execution-request.mapper"
 import { InjectHttpSecurityOptions } from "./http-security.decorators"
@@ -35,6 +35,8 @@ const RATE_EXCEEDED_KEY = "platform.http-security.rate-exceeded"
 const KEY_MAX = 128
 /** The most ended windows one fresh window prunes. */
 const PRUNE_BATCH = 100
+/** The row the counting update returns: the hits of the live window, this one included. */
+const isCountedWindow = rowShape({ hits: "number" })
 
 /** A same-site path: one leading slash, never a protocol-relative `//` or `/\` that leaves the site. */
 const isSameSitePath = (location: string): boolean =>
@@ -91,16 +93,20 @@ export class RateLimitGuard implements CanActivate {
     }
 
     /**
-     * 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.
+     * Counts one hit in the caller's window and answers the hits it holds: a live window grows by one in one UPDATE that
+     * returns its hits, 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).
      */
     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 counted = await this.entityManager
+            .createQueryBuilder(RateWindowEntity, "window")
+            .update()
+            .set({ hits: () => "hits + 1" })
+            .where({ key, resetAt: MoreThan(now) })
+            .returning("hits")
+            .execute()
+        const [live] = returnedRows(counted.raw, isCountedWindow)
+        if (live !== undefined) return live.hits
         const restarted = await this.entityManager.update(
             RateWindowEntity,
             { key, resetAt: LessThanOrEqual(now) },