@starci/hfs 4.9.8 → 4.9.9

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.9.9 - 2026-10-29
+
+- Fixed: the back-end skeleton's `RateLimitGuard` counts in a store every replica shares (BE-AUTH-4), not a process-local map. Each hit is one upsert of the caller's window (tier and address) in the primary database, answering its hits; a hit that opens a fresh window prunes up to 100 ended windows (`FOR UPDATE SKIP LOCKED`). `platform/http-security` owns the table `http_security_rate_windows`: in full through its `persistence/` entity and migration (`httpSecurityEntities`, `httpSecurityMigrations`, registered on the primary connection by the api and cli apps), in lite in the Supabase baseline with forced RLS and `app_be` policies. The lite starter now ships `platform/database/database.sql.ts` (with `DATABASE_IDENTIFIER_REJECTED`) and exports `sql`, `InjectPrimaryEntityManager` and `PRIMARY_ENTITY_MANAGER`, which the guard and its spec consume; a lite starter leaves out a platform capability's TypeORM schema files. Needs `@starci/eslint-canon-be` 3.6.5, which admits `http-security` as a persistence capability.
+- Unchanged on purpose: `platform/http` and `platform/http-security` still export only what the skeleton consumes (R25 HFS_UNUSED_EXPORT); code that first consumes `InjectHttpClient` or `RateLimit`/`RateTier` adds the export line to the owner entry in the same change, as the webhook generators already do.
+- Changed: the bundled canon pins name hfs 4.9.9 and eslint-canon-be 3.6.5.
+- Changed: the bundled canon pins name the Grammar family 0.15.7 (grammar, eslint-grammar-core, eslint-grammar-offset-pop) and eslint-canon-fe 9.4.6.
+- Changed: the bundled canon pins name the Grammar family 0.15.8 (grammar, eslint-grammar-core, eslint-grammar-offset-pop), eslint-canon-fe 9.4.7 and eslint-canon-be 3.6.6.
+
 ## 4.9.8 - 2026-10-28
 
 - Added: `starci app add page <route> --tabs a,b` puts the page tabs in the `Page` header as link tabs (Grammar 0.15.6): the first tab is the route itself, every other one its sub-route `<route>/<tab>`; the server owner resolves the labels (`<page>.tabs.label` and `<page>.tabs.items.<tab>` in every catalog) and passes no state or handler, and the stories carry the tabs. Fewer than two or repeated tab ids are refused (`HFS_ADD_TABS_INVALID`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.9.8",
+  "version": "4.9.9",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.15.6
+    version: 0.15.8
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.6.4
+    version: 3.6.6
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.4.5
+    version: 9.4.7
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.15.6
+    version: 0.15.8
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.15.6
+    version: 0.15.8
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.9.8
+    version: 4.9.9
     group: starci
     install: registry
     side: both

package/scaffold/app.mjs

@@ -407,11 +407,12 @@ const declaresCliApp = app => app.sides.be.apps.some(entry => entry.kind === 'cl
 
 const LITE_APP_REUSED = new Set(['.editorconfig', '.gitattributes', '.nvmrc']);
 const LITE_DEFERRED_GENERATOR_FILES = new Set([
-  'src/modules/platform/database/database.sql.ts',
   'src/modules/platform/database/migration-runner.service.ts',
   'src/modules/platform/database/seed-runner.service.ts',
   'src/modules/platform/primitives/sequence.policy.ts',
 ]);
+/** The TypeORM schema files of a platform capability: lite's schema authority is supabase/migrations (be.persistence lite overlay). */
+const LITE_TYPEORM_SCHEMA = /^src\/modules\/platform\/[^/]+\/persistence\/(?:connection\.ts$|entities\/|migrations\/)/;
 const liteBaseSource = (rel) => !rel.startsWith('apps/cli/')
     && !rel.startsWith('src/features/cli/')
     && !rel.startsWith('src/modules/domain/note/')
@@ -419,6 +420,7 @@ const liteBaseSource = (rel) => !rel.startsWith('apps/cli/')
     && rel !== 'src/modules/platform/database/migrate-connections.client.ts'
     && rel !== 'src/modules/platform/database/seed-connections.client.ts'
     && !LITE_DEFERRED_GENERATOR_FILES.has(rel)
+    && !LITE_TYPEORM_SCHEMA.test(rel)
     && !rel.startsWith('src/tests/');
 /** The be files the lite overlay replaces: a base unit spec of such a file tests the full variant, so lite carries its own. */
 const liteOverlaid = (() => {

package/templates/app/skeleton-lite/supabase/migrations/__timestamp___baseline.sql

@@ -62,3 +62,44 @@ grant usage on schema public to app_be;
 revoke all on table public.profiles from public, anon, authenticated;
 grant select, insert on table public.profiles to app_be;
 grant update (display_name) on table public.profiles to app_be;
+
+-- The rate limit windows of platform/http-security: every api replica counts a caller's hits in the same row, and a hit
+-- that opens a fresh window prunes a bounded batch of the ended ones.
+create table public.http_security_rate_windows (
+    key varchar(128) primary key,
+    hits integer not null check (hits > 0),
+    reset_at timestamptz not null
+);
+
+create index http_security_rate_windows_reset_at_idx on public.http_security_rate_windows (reset_at);
+
+alter table public.http_security_rate_windows enable row level security;
+alter table public.http_security_rate_windows force row level security;
+
+create policy http_security_rate_windows_app_be_select
+on public.http_security_rate_windows
+for select
+to app_be
+using (current_user = 'app_be');
+
+create policy http_security_rate_windows_app_be_insert
+on public.http_security_rate_windows
+for insert
+to app_be
+with check (current_user = 'app_be');
+
+create policy http_security_rate_windows_app_be_update
+on public.http_security_rate_windows
+for update
+to app_be
+using (current_user = 'app_be')
+with check (current_user = 'app_be');
+
+create policy http_security_rate_windows_app_be_delete
+on public.http_security_rate_windows
+for delete
+to app_be
+using (current_user = 'app_be');
+
+revoke all on table public.http_security_rate_windows from public, anon, authenticated;
+grant select, insert, update, delete on table public.http_security_rate_windows to app_be;

package/templates/be/skeleton/apps/__app__/src/compose/platform.ts

@@ -6,7 +6,13 @@ import { CONFIG_ERROR_KINDS } from "@modules/platform/config"
 import { CqrsModule } from "@modules/platform/cqrs"
 import { DATABASE_ERROR_KINDS, DatabaseModule } from "@modules/platform/database"
 import { ERRORS_MESSAGES, ErrorsModule } from "@modules/platform/errors"
-import { HTTP_SECURITY_ERROR_KINDS, HTTP_SECURITY_MESSAGES, HttpSecurityModule } from "@modules/platform/http-security"
+import {
+    HTTP_SECURITY_ERROR_KINDS,
+    HTTP_SECURITY_MESSAGES,
+    HttpSecurityModule,
+    httpSecurityEntities,
+    httpSecurityMigrations,
+} from "@modules/platform/http-security"
 import { I18nModule } from "@modules/platform/i18n"
 import { IdsModule } from "@modules/platform/ids"
 import { HTTP_ERROR_KINDS, HTTP_MESSAGES, HttpModule } from "@modules/platform/http"
@@ -44,6 +50,12 @@ export const platformModules = (options: {{appPascal}}Options): Array<DynamicMod
     HttpSecurityModule.register({ isGlobal: true, ...options.httpSecurity }),
     DatabaseModule.register({
         isGlobal: true,
-        connections: [{ ...options.database, entities: noteEntities, migrations: noteMigrations }],
+        connections: [
+            {
+                ...options.database,
+                entities: [...httpSecurityEntities, ...noteEntities],
+                migrations: [...httpSecurityMigrations, ...noteMigrations],
+            },
+        ],
     }),
 ]

package/templates/be/skeleton/apps/cli/src/compose/platform.ts

@@ -5,14 +5,15 @@ import { DatabaseModule } from "@modules/platform/database"
 import type { DatabaseConnectionConfig, DatabaseConnectionOptions } from "@modules/platform/database"
 import { IdsModule } from "@modules/platform/ids"
 import { HttpModule } from "@modules/platform/http"
+import { httpSecurityEntities, httpSecurityMigrations } from "@modules/platform/http-security"
 import { LoggingModule } from "@modules/platform/logging"
 import type { CliAppOptions } from "../cli.options"
 
 /** Binds the primary connection to its owners' entities and migrations during composition. */
 const primaryConnectionOf = (primary: DatabaseConnectionConfig): DatabaseConnectionOptions => ({
     ...primary,
-    entities: noteEntities,
-    migrations: noteMigrations,
+    entities: [...httpSecurityEntities, ...noteEntities],
+    migrations: [...httpSecurityMigrations, ...noteMigrations],
 })
 
 /** The clock, logger and declared database connections shared by CLI commands. */

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

@@ -4,6 +4,7 @@ export { HttpSecurityModule } from "./http-security.module"
 export type { HttpSecurityOptions } from "./http-security.options"
 export { HTTP_SECURITY_MESSAGES } from "./messages/http-security.messages"
 export { OriginGuard } from "./origin.guard"
+export { httpSecurityEntities, httpSecurityMigrations } from "./persistence/connection"
 export { requestOf } from "./execution-request.mapper"
 export { RateLimitGuard } from "./rate-limit.guard"
 export { applyHttpSecurity } from "./edge-security.service"

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

@@ -0,0 +1,8 @@
+import { RateWindowEntity } from "./entities/rate-window.entity"
+import { CreateRateWindows1789900000000 } from "./migrations/1789900000000-create-rate-windows"
+
+/** The entities of the http-security capability, for the primary connection its rate limit counts in. */
+export const httpSecurityEntities = [RateWindowEntity]
+
+/** The migrations of the http-security capability, in the order they run. */
+export const httpSecurityMigrations = [CreateRateWindows1789900000000]

package/templates/be/skeleton/src/modules/platform/http-security/persistence/entities/rate-window.entity.ts

@@ -0,0 +1,17 @@
+import { Column, Entity, PrimaryColumn } from "typeorm"
+
+@Entity("http_security_rate_windows")
+/** One rate limit window of one caller and tier: the hits it counted and when it ends. */
+export class RateWindowEntity {
+    /** The tier and caller address the window counts. */
+    @PrimaryColumn({ name: "key", type: "varchar", length: 128 })
+    key!: string
+
+    /** The hits counted in the window. */
+    @Column({ name: "hits", type: "integer" })
+    hits!: number
+
+    /** When the window ends; a hit after it opens a fresh one. */
+    @Column({ name: "reset_at", type: "timestamptz" })
+    resetAt!: Date
+}

package/templates/be/skeleton/src/modules/platform/http-security/persistence/migrations/1789900000000-create-rate-windows.ts

@@ -0,0 +1,24 @@
+import type { MigrationInterface, QueryRunner } from "typeorm"
+
+/** Creates the rate limit windows every api replica counts in. */
+export class CreateRateWindows1789900000000 implements MigrationInterface {
+    name = "CreateRateWindows1789900000000"
+
+    /** Creates the windows table and the index the prune reads. */
+    async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE TABLE http_security_rate_windows (
+    key varchar(128) PRIMARY KEY,
+    hits integer NOT NULL CHECK (hits > 0),
+    reset_at timestamptz NOT NULL
+)`)
+        await queryRunner.query(
+            `CREATE INDEX ix_http_security_rate_windows_reset_at ON http_security_rate_windows (reset_at)`,
+        )
+    }
+
+    /** Drops the index and the table. */
+    async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX ix_http_security_rate_windows_reset_at`)
+        await queryRunner.query(`DROP TABLE http_security_rate_windows`)
+    }
+}

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

@@ -0,0 +1,5 @@
+/** The row HIT_RATE_WINDOW answers. */
+export interface RateWindowRow {
+    /** The hits of the caller's current window, this one included. */
+    readonly hits: number
+}

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

@@ -0,0 +1,20 @@
+import { sql } from "@modules/platform/database"
+
+/**
+ * Counts one hit in the caller's window and answers the hits of that window: a missing or expired window opens afresh at one
+ * hit and ends at $3 ($1 tier and address key, $2 instant, $3 end of a fresh window).
+ */
+export const HIT_RATE_WINDOW = sql`INSERT INTO http_security_rate_windows (key, hits, reset_at)
+    VALUES ($1::varchar, 1, $3::timestamptz)
+    ON CONFLICT (key) DO UPDATE SET
+        hits = CASE WHEN http_security_rate_windows.reset_at <= $2::timestamptz THEN 1
+            ELSE http_security_rate_windows.hits + 1 END,
+        reset_at = CASE WHEN http_security_rate_windows.reset_at <= $2::timestamptz THEN EXCLUDED.reset_at
+            ELSE http_security_rate_windows.reset_at END
+    RETURNING hits`
+
+/** Deletes a bounded batch of the windows that ended by $1; a second replica skips the rows this one holds. */
+export const PRUNE_RATE_WINDOWS = sql`DELETE FROM http_security_rate_windows WHERE key IN (
+    SELECT key FROM http_security_rate_windows WHERE reset_at <= $1::timestamptz
+    LIMIT 100 FOR UPDATE SKIP LOCKED
+)`

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

@@ -3,29 +3,34 @@ import type { ExecutionContext, Type } from "@nestjs/common"
 import type { Request } from "express"
 import { Reflector } from "@nestjs/core"
 import { Test } from "@nestjs/testing"
-import { FakeClock, mock } from "@starci/jest-preset"
+import { FakeClock, mock, mockEntityManager } 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 { HIT_RATE_WINDOW, PRUNE_RATE_WINDOWS } from "./persistence/rate-limit.sql"
 import { RateLimit, RateLimitGuard, RateTier } 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: {},
 }
 
-const build = async (clock: FakeClock, tier?: RateTier) => {
+const build = async (entityManager: MockEntityManager, tier?: RateTier) => {
     const reflector = mock<Reflector>()
     reflector.getAllAndOverride.mockReturnValue(tier)
     const moduleRef = await Test.createTestingModule({
         providers: [
             RateLimitGuard,
             { provide: Reflector, useValue: reflector },
-            { provide: CLOCK, useValue: clock },
+            { 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 }
@@ -33,79 +38,100 @@ const build = async (clock: FakeClock, tier?: RateTier) => {
 
 /** 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 {}) => {
-    let address = ip
     const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
-    http.getRequest.mockImplementation(() => mock<Request>({ headers: {}, method: "POST", ip: address }))
+    http.getRequest.mockImplementation(() => mock<Request>({ headers: {}, method: "POST", ip }))
     const context = mock<ExecutionContext>()
     context.switchToHttp.mockReturnValue(http)
     context.getHandler.mockReturnValue(handler)
     context.getClass.mockReturnValue(door)
-    return { context, setIp: (value: string | undefined) => (address = value) }
+    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 { guard, reflector } = await build(new FakeClock(AT), RateTier.Strict)
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard, reflector } = await build(entityManager, RateTier.Strict)
         const handler = () => undefined
-        const { context } = contextOf("127.0.0.1", handler, Door)
 
         expect(Reflect.getMetadata("platform.http-security.rate-tier", Door)).toBe(RateTier.Strict)
-        expect(guard.canActivate(context)).toBe(true)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+        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.query).toHaveBeenCalledWith(HIT_RATE_WINDOW, [
+            "strict:127.0.0.1",
+            new Date(AT),
+            new Date(RESET_AT),
+        ])
     })
 })
 
 describe("RateLimitGuard", () => {
-    it("counts an unmarked door under the default limit", async () => {
-        const { guard } = await build(new FakeClock(AT))
-        const { context } = contextOf("127.0.0.1")
-
-        expect(guard.canActivate(context)).toBe(true)
-        expect(guard.canActivate(context)).toBe(true)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+    it("admits a caller under the default limit of an unmarked door, counting in the shared window", async () => {
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
+        expect(entityManager.query).toHaveBeenCalledWith(HIT_RATE_WINDOW, [
+            "default:127.0.0.1",
+            new Date(AT),
+            new Date(RESET_AT),
+        ])
     })
 
-    it("opens a fresh window for a caller whose bucket expired", async () => {
-        const clock = new FakeClock(AT)
-        const { guard } = await build(clock)
-        const { context } = contextOf("127.0.0.1")
-
-        guard.canActivate(context)
-        guard.canActivate(context)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+    it("refuses a caller whose shared window is over the default limit", async () => {
+        const { guard } = await build(mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 3 }]] }))
 
-        clock.advance(60_001)
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RateLimited,
+        })
+    })
 
-        expect(guard.canActivate(context)).toBe(true)
+    it("prunes the expired windows when a hit opens a fresh one", async () => {
+        const entityManager = mockEntityManager({
+            query: [
+                [HIT_RATE_WINDOW, [{ hits: 1 }]],
+                [PRUNE_RATE_WINDOWS, []],
+            ],
+        })
+        const { guard } = await build(entityManager)
+
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).resolves.toBe(true)
+        expect(entityManager.query).toHaveBeenCalledWith(PRUNE_RATE_WINDOWS, [new Date(AT)])
     })
 
-    it("counts a request without an address under the unknown bucket", async () => {
-        const { guard } = await build(new FakeClock(AT))
-        const { context } = contextOf(undefined)
+    it("counts a request without an address under the unknown key", async () => {
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard } = await build(entityManager)
 
-        guard.canActivate(context)
-        guard.canActivate(context)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+        await expect(guard.canActivate(contextOf(undefined))).resolves.toBe(true)
+        expect(entityManager.query).toHaveBeenCalledWith(HIT_RATE_WINDOW, [
+            "default:unknown",
+            new Date(AT),
+            new Date(RESET_AT),
+        ])
     })
 
-    it("prunes the expired buckets when the map outgrows the bucket cap", async () => {
-        const clock = new FakeClock(AT)
-        const { guard } = await build(clock)
-        const { context, setIp } = contextOf("0.0.0.0")
+    it("bounds the window key to the length the table stores", async () => {
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard } = await build(entityManager)
 
-        for (let index = 0; index <= 10_000; index += 1) {
-            setIp(`10.${(index >> 16) % 256}.${(index >> 8) % 256}.${index % 256}`)
-            guard.canActivate(context)
-        }
+        await guard.canActivate(contextOf("f".repeat(300)))
+
+        expect(entityManager.query).toHaveBeenCalledWith(HIT_RATE_WINDOW, [
+            `default:${"f".repeat(120)}`,
+            new Date(AT),
+            new Date(RESET_AT),
+        ])
+    })
 
-        clock.advance(60_001)
-        setIp("127.0.0.1")
+    it("refuses the request when the store answers no window", async () => {
+        const { guard } = await build(mockEntityManager({ query: [HIT_RATE_WINDOW, []] }))
 
-        expect(guard.canActivate(context)).toBe(true)
-        expect(guard.canActivate(context)).toBe(true)
-        expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.RateLimited)
+        await expect(guard.canActivate(contextOf("127.0.0.1"))).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RateLimited,
+        })
     })
 })

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

@@ -1,13 +1,17 @@
 import { Injectable, SetMetadata } from "@nestjs/common"
 import type { CanActivate, ExecutionContext } from "@nestjs/common"
 import type { Reflector } from "@nestjs/core"
+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 { 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 type { RateWindowRow } from "./persistence/rate-limit.rows"
+import { HIT_RATE_WINDOW, PRUNE_RATE_WINDOWS } from "./persistence/rate-limit.sql"
 
 /** The rate limit tiers of a door. */
 export enum RateTier {
@@ -18,29 +22,28 @@ export enum RateTier {
 }
 
 const RATE_TIER_KEY = "platform.http-security.rate-tier"
-const BUCKETS_MAX = 10_000
-
-interface Bucket {
-    count: number
-    resetAt: number
-}
+/** The longest window key the table stores: the tier, a colon and the caller address. */
+const KEY_MAX = 128
 
 /** Marks a door with a rate limit tier other than the default. */
 export const RateLimit = (tier: RateTier): ReturnType<typeof SetMetadata> => SetMetadata(RATE_TIER_KEY, tier)
 
 @Injectable()
-/** The first app guard: a fixed-window counter per caller address and tier, kept in process memory and stamped by the Clock. */
+/**
+ * The first app guard: a fixed-window counter per caller address and tier, stamped by the Clock and kept in the primary
+ * database, 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 {
-    private readonly buckets = new Map<string, Bucket>()
-
     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. */
-    canActivate(context: ExecutionContext): boolean {
+    async canActivate(context: ExecutionContext): Promise<boolean> {
         const tier =
             this.reflector.getAllAndOverride<RateTier | undefined>(RATE_TIER_KEY, [
                 context.getHandler(),
@@ -48,21 +51,13 @@ export class RateLimitGuard implements CanActivate {
             ]) ?? RateTier.Default
         const limit =
             tier === RateTier.Strict ? this.options.rateLimit.strictLimit : this.options.rateLimit.defaultLimit
-        const now = this.clock.now().getTime()
-        const key = `${tier}:${requestOf(context).ip ?? "unknown"}`
-        const current = this.buckets.get(key)
-        const bucket =
-            current && current.resetAt > now ? current : { count: 0, resetAt: now + this.options.rateLimit.windowMs }
-        bucket.count += 1
-        this.buckets.set(key, bucket)
-        if (this.buckets.size > BUCKETS_MAX) this.prune(now)
-        if (bucket.count > limit) throw new HttpSecurityError({ code: HttpSecurityErrorCode.RateLimited })
+        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 hits = rows[0]?.hits ?? Number.POSITIVE_INFINITY
+        if (hits === 1) await this.entityManager.query(PRUNE_RATE_WINDOWS, [now])
+        if (hits > limit) throw new HttpSecurityError({ code: HttpSecurityErrorCode.RateLimited })
         return true
     }
-
-    private prune(now: number): void {
-        for (const [key, bucket] of this.buckets) {
-            if (bucket.resetAt <= now) this.buckets.delete(key)
-        }
-    }
 }

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

@@ -5,11 +5,14 @@ import type { ErrorKind } from "@modules/platform/errors"
 export enum DatabaseErrorCode {
     /** A configured connection has no declared EntityManager injection token. */
     ConnectionUndeclared = "DATABASE_CONNECTION_UNDECLARED",
+    /** A dynamic SQL identifier was not on the names its caller allows. */
+    IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",
 }
 
 /** How each database code travels. */
 export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {
     [DatabaseErrorCode.ConnectionUndeclared]: "internal",
+    [DatabaseErrorCode.IdentifierRejected]: "internal",
 }
 
 /** The one error class of the database capability. */

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

@@ -1,7 +1,8 @@
 export { DatabaseModule } from "./database.module"
-export { DATABASE_PROBE, InjectDatabaseProbe } from "./primary.decorators"
+export { DATABASE_PROBE, InjectDatabaseProbe, InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"
 export { PRIMARY_DATA_SOURCE } from "./database.port"
+export { sql } from "./database.sql"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
 export { parsePrimaryDatabaseConfig } from "./primary.config"