@starci/hfs 4.11.11 → 4.11.12

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 4.11.12 - 2026-10-29
+
+- Changed: the skeleton canon gate (`src/scaffold-template-canon-be.spec.mjs`) lints every file under `be/src/modules/platform` of both editions with the starci-be rules, no longer `platform/http` alone; both editions are green.
+- Fixed: the lite skeleton's `platform/http-security` reads and writes its rate limit windows through `RateWindowEntity` on the EntityManager (R334), no longer through full's `rate-limit.sql.ts` and `.query(`: a live window grows in one atomic `increment`, an ended one restarts with `update`, a missing one opens with an `orIgnore` insert builder, and the prune deletes a bounded `find` batch. The entity maps `public.http_security_rate_windows` of the baseline migration (`persistence/entities/rate-window.entity.ts`, `httpSecurityEntities` in its barrel, listed in `PRIMARY_ENTITIES`); a lite platform capability takes its `persistence/` from the lite overlay alone. The guard spec uses the kit's `mockEntityManager` and `queueQueryBuilders`.
+- Changed: a fresh lite app no longer carries the raw SQL helpers nothing in it calls: `platform/database/database.sql.ts` and `database.client.ts` (with its spec) are written by the first generator that needs them (`add table` the sql helpers, `add queue`, `add job` and `add webhook` both), and the barrel exports `sql`, `callDbFunction` and `advisoryXactLock` are registered by those generators (`jobs` registers `advisoryXactLock`); `notify` is no longer exported by the starter.
+- Fixed: `source-suffix` (BE_SOURCE_FORM, R89) admits the one file a file slot names by its path, read from the slot manifest: the lite entity registry `src/modules/platform/database/entities.ts` (slot `be.platform.database.entities`) was refused for having no role suffix.
+- Fixed: the lite skeleton types its entity lists with `EntityClass` (`new () => object`, declared in `platform/database/database.options.ts` as full declares it): `DatabaseOptions.entities` and `PRIMARY_ENTITIES` of `entities.ts` were `ReadonlyArray<Function>`, which `starci-be/no-function-or-eval` refuses.
+- Changed: R334 `BE_PERSISTENCE_NO_RAW_SQL` covers test code with one owner exception (ruling lite-test-sql-owner): specs, builders and fixtures seed and assert through entities on `world.db.<connection>`, and only `src/tests/world` holds raw SQL beside `platform/database`, as named world helpers for what entities cannot express. The bundled catalog law and the failure-code hint say so; the bundled canon pins name hfs 4.11.12, eslint-canon-be 3.8.11, eslint-canon-fe 9.5.13 and the Grammar family 0.15.24.
+
 ## 4.11.11 - 2026-10-29
 
 - Changed: `server-key <env> --backup github` stores the server identity as the secret `SOPS_AGE_KEY` of the GitHub Environment `<env>` (`BACKUP_SECRET`, `gh secret set SOPS_AGE_KEY --env <env>`), the name the deploy workflows read: an Environment secret overrides a repository secret of the same name for every job bound to that Environment, so the deploy of `<env>` decrypts with that environment's own server key. `backupSecretName` and the `SOPS_AGE_KEY_<ENV>` name are gone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.11.11",
+  "version": "4.11.12",
   "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.23
+    version: 0.15.24
     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.8.10
+    version: 3.8.11
     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.5.12
+    version: 9.5.13
     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.23
+    version: 0.15.24
     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.23
+    version: 0.15.24
     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.11.11
+    version: 4.11.12
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -5828,7 +5828,7 @@ rules:
         ruling: "Lite entities only map tables the migrations create, so each entity column is checked against the migrated schema by starci app db drift, which CI runs in the build job and the release gate runs as its db-drift row."
   - id: R334
     code: "BE_PERSISTENCE_NO_RAW_SQL"
-    law: "Lite domain and feature code reads and writes through TypeORM entities on the injected EntityManager (find, findOne, findBy, count, exists, insert, save, update, delete, upsert, increment, and createQueryBuilder(Entity, alias) with named parameters for joins, aggregates, FOR UPDATE / SKIP LOCKED and jsonb or vector operators; never a table-name builder, a builder with no entity or a Repository); no .query( call and no sql template outside platform/database; a database function TypeORM cannot express is called through the callDbFunction, advisoryXactLock and notify helpers of platform/database/database.client.ts, and callDbFunction names only a function ruleParams.be.dbFunctions or hfs.json sides.be.dbFunctions lists with a reason: a function of a migration schema-qualified (public.job_claim), a pg built-in bare (pg_notify, called in pg_catalog). That file alone composes the call statement, from the name parts its validator checked and double-quotes and a numbered parameter list. Entities only map tables db/migrations created (synchronize stays false); entity-versus-schema drift is BE_ENTITY_SCHEMA_DRIFT of starci app db drift."
+    law: "Lite domain, feature and test code reads and writes through TypeORM entities on an EntityManager (domain code the injected one, integration and e2e specs, builders and fixtures the world's `world.db.<connection>`) (find, findOne, findBy, count, exists, insert, save, update, delete, upsert, increment, and createQueryBuilder(Entity, alias) with named parameters for joins, aggregates, FOR UPDATE / SKIP LOCKED and jsonb or vector operators; never a table-name builder, a builder with no entity or a Repository); no .query( call and no sql template outside the two raw SQL owners, platform/database and the test world src/tests/world, which wraps only what entities cannot express (a trigger, a database function, a row-level-security probe, a pgmq queue) in a named, typed world helper specs call; a database function TypeORM cannot express is called, in domain and test code alike, through the callDbFunction, advisoryXactLock and notify helpers of platform/database/database.client.ts, and callDbFunction names only a function ruleParams.be.dbFunctions or hfs.json sides.be.dbFunctions lists with a reason: a function of a migration schema-qualified (public.job_claim), a pg built-in bare (pg_notify, called in pg_catalog). That file alone composes the call statement, from the name parts its validator checked and double-quotes and a numbered parameter list. Entities only map tables db/migrations created (synchronize stays false); entity-versus-schema drift is BE_ENTITY_SCHEMA_DRIFT of starci app db drift."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["BE_PERSISTENCE_NO_RAW_SQL"]

package/runtime/modules/kernel/failure-codes.yaml

@@ -5581,12 +5581,12 @@ LITE_DB_MIGRATION:
   kind: check-finding
 
 BE_PERSISTENCE_NO_RAW_SQL:
-  title: "Lite domain code runs raw SQL instead of TypeORM entities"
-  title_vi: "Mã domain của app lite chạy SQL thô thay vì entity TypeORM"
-  meaning_vi: "File `<path>` gọi `.query(` hoặc dùng template `sql` ngoài platform/database và ngoài danh sách hàm ruleParams.be.lite.rawSqlFunctions."
+  title: "Lite domain, feature or test code runs raw SQL instead of TypeORM entities"
+  title_vi: "Mã domain, feature hoặc test của app lite chạy SQL thô thay vì entity TypeORM"
+  meaning_vi: "File `<path>` gọi `.query(` hoặc dùng template `sql` ngoài hai chủ của SQL thô là platform/database và test world src/tests/world, hoặc gọi callDbFunction với một hàm không có trong ruleParams.be.dbFunctions hay hfs.json sides.be.dbFunctions."
   causes_vi:
-    - "Vi phạm R334: dữ liệu của app lite đi qua entity TypeORM trên EntityManager (find, save, update, upsert, createQueryBuilder)."
-  nextStep_vi: "Khai entity ở persistence/entities/<table>.entity.ts và đọc/ghi bằng EntityManager hoặc createQueryBuilder với tham số có tên; hàm pg/SECURITY DEFINER không diễn đạt được thì khai vào rawSqlFunctions kèm lý do."
+    - "Vi phạm R334: dữ liệu của app lite, kể cả spec, builder và fixture, đi qua entity TypeORM trên EntityManager (find, save, update, upsert, createQueryBuilder); spec dùng world.db.<connection>."
+  nextStep_vi: "Đọc/ghi bằng entity trên EntityManager hoặc createQueryBuilder với tham số có tên (trong test là world.db.<connection>); hàm database TypeORM không diễn đạt được thì gọi qua callDbFunction với hàm đã khai kèm lý do; điều entity không diễn đạt được trong test (trigger, thăm dò row-level security, hàng đợi pgmq) thì gọi một helper có tên của src/tests/world."
   owner: op-retry
   kind: check-finding
 

package/runtime/scripts/hfs/path-findings.mjs

@@ -29,6 +29,8 @@ function sourceFormContext(file, resolver, suffixes, bannedSuffixes) {
   const base = path.posix.basename(file);
   if (FREE_NAMES.has(base)) return null;
   const slot = resolver.slot(c.slot);
+  // A file slot declares its one file by its path (be.platform.database.entities: src/modules/platform/database/entities.ts).
+  if (slot?.path === c.path) return null;
   if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].includes(base)) return null;
   const admitted = allowsFile(resolver, file);
   // Environment parsing is an app slot role, not a source suffix admitted outside that matching app file.
@@ -57,8 +59,8 @@ function sourceFormFinding(file, { c, base, suffixes, bannedSuffixes }, boundSuf
 }
 
 /**
- * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
- * be.persistence, the matching <app>.env.ts explicitly admitted by its app slot, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
+ * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, the one file a file
+ * slot names by its path (the lite entity registry src/modules/platform/database/entities.ts), a migration of be.persistence, the matching <app>.env.ts explicitly admitted by its app slot, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
  * as order.service.spec.ts keeps its inner words kebab-case). A suffix of ruleParams.be.bannedSuffixes anywhere in the
  * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
  */

package/scaffold/add-inbox-lite.mjs

@@ -233,17 +233,13 @@ export function addLiteWebhookInbox({
   );
   if (!hasHandoffStorage)
     planned[0].text = `${template("platform/migration.sql.tpl", renderValues)}\n${template("platform/client-operation-outcomes.sql.tpl", renderValues)}\n${planned[0].text}`;
-  const databaseSql = "be/src/modules/platform/database/database.sql.ts";
-  if (!fs.existsSync(path.join(root, ...databaseSql.split("/")))) {
+  // The sql tag and the database-function call (with its spec) the inbox and the event bus use; the lite starter leaves them out.
+  for (const file of ["database.sql.ts", "database.client.ts", "database.client.spec.ts"]) {
+    const relative = `be/src/modules/platform/database/${file}`;
+    if (fs.existsSync(path.join(root, ...relative.split("/")))) continue;
     planned.push({
-      relative: databaseSql,
-      text: render(
-        fs.readFileSync(
-          path.join(TEMPLATES_DIR, "be", "skeleton-lite", "src", "modules", "platform", "database", "database.sql.ts"),
-          "utf8",
-        ),
-        {},
-      ),
+      relative,
+      text: render(fs.readFileSync(path.join(TEMPLATES_DIR, "be", "skeleton-lite", "src", "modules", "platform", "database", file), "utf8"), {}),
     });
   }
   const databaseClient = path.join(

package/scaffold/add-queue-lite.mjs

@@ -84,12 +84,14 @@ const DATABASE_ERROR = 'be/src/modules/platform/database/errors/database.error.t
 
 /** Skeleton files the lite starter leaves out and the queue capabilities use, each from its skeleton template. */
 const SKELETON_FILES = Object.freeze([
+  ['be/src/modules/platform/database/database.client.ts', 'skeleton-lite/src/modules/platform/database/database.client.ts'],
+  ['be/src/modules/platform/database/database.client.spec.ts', 'skeleton-lite/src/modules/platform/database/database.client.spec.ts'],
   ['be/src/modules/platform/database/database.sql.ts', 'skeleton-lite/src/modules/platform/database/database.sql.ts'],
   ['be/src/modules/platform/primitives/sequence.policy.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.ts'],
   ['be/src/modules/platform/primitives/sequence.policy.spec.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.spec.ts'],
 ]);
 
-/** The sql tag of the outbox and claim statements (with its identifier error) and the in-order relay the queue adapters walk their rows with. */
+/** The database-function call and the sql tag of the outbox and claim statements (with its identifier error) and the in-order relay the queue adapters walk their rows with. */
 function skeletonFiles(repoRoot) {
   const created = SKELETON_FILES.filter(([relative]) => !fs.existsSync(path.join(repoRoot, ...relative.split('/'))))
     .map(([relative, source]) => ({ relative, text: render(template(`be/${source}`), {}) }));
@@ -364,7 +366,10 @@ export function planLiteQueue({ repoRoot, repo, noun, patterns, now }) {
         fs.writeFileSync(target, entry.text);
       }
       for (const patch of patches) fs.writeFileSync(patch.file, patch.text);
-      const exported = registerLiteExports({ root: repoRoot, generator: 'queue' });
+      const exported = [
+        ...registerLiteExports({ root: repoRoot, generator: 'queue' }),
+        ...(patterns.includes('fenced-job') ? registerLiteExports({ root: repoRoot, generator: 'jobs' }) : []),
+      ];
       const sealed = sealRedisMembers(repoRoot, stack.environments);
       const changed = patches.map((patch) => path.relative(repoRoot, patch.file).split(path.sep).join('/'));
       return [...new Set([...created.map((entry) => entry.relative), ...changed, ...exported, ...sealed])];

package/scaffold/add-table.mjs

@@ -472,9 +472,14 @@ function writeTableFiles({ root, planned, edit }, created) {
 
 }
 
+/** The lite sql helpers of platform/database (requireOwnedEntity, the bounds and the sql tag). */
+const DATABASE_SQL_FILE = "be/src/modules/platform/database/database.sql.ts";
+
 function tableRegistrations({ root, repo, fe, edit }) {
   const errorFile = "be/src/modules/platform/database/errors/database.error.ts";
   if (repo.edition === "lite" && fs.existsSync(at(root, errorFile))) edit(errorFile, withSqlIdentifierError);
+  // requireOwnedEntity lives in the sql helpers the lite starter leaves out; the first table writes them.
+  if (repo.edition === "lite") edit(DATABASE_SQL_FILE, (text) => text || render(fs.readFileSync(path.join(TEMPLATES_DIR, "be", "skeleton-lite", "src", "modules", "platform", "database", "database.sql.ts"), "utf8"), {}));
     const registrations = [
       ...(repo.edition === "lite" ? ["table"] : []),
       ...(fe ? ["api", "graphql"] : []),

package/scaffold/app.mjs

@@ -353,13 +353,25 @@ const CLI_APP_DIR = 'apps/cli/';
 const declaresCliApp = app => app.sides.be.apps.some(entry => entry.kind === 'cli' && entry.name === 'cli');
 
 const LITE_APP_REUSED = new Set(['.editorconfig', '.gitattributes', '.nvmrc']);
+/**
+ * The lite be files a generator writes when it first needs them, never the starter: the cli's runners, the in-order relay, and the
+ * raw SQL helpers of platform/database (the sql tag, and the database-function call statement with its spec), which only the table,
+ * queue, jobs and webhook capabilities call; a fresh app reads and writes through entities alone (R334).
+ */
 const LITE_DEFERRED_GENERATOR_FILES = new Set([
+  'src/modules/platform/database/database.client.ts',
+  'src/modules/platform/database/database.client.spec.ts',
+  '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 db/migrations (be.persistence lite overlay). */
-const LITE_TYPEORM_SCHEMA = /^src\/modules\/platform\/[^/]+\/persistence\/(?:connection\.ts$|entities\/|migrations\/)/;
+/**
+ * The persistence folder of a full platform capability (TypeORM migrations, connection arrays, `sql`-tagged statements and rows):
+ * lite's schema authority is db/migrations and its code reads and writes through entities (be.persistence lite overlay, R334), so a
+ * lite platform capability takes its persistence/ from the lite overlay alone.
+ */
+const FULL_PLATFORM_PERSISTENCE = /^src\/modules\/platform\/[^/]+\/persistence\//;
 const liteBaseSource = (rel) => !rel.startsWith('apps/cli/')
     && !rel.startsWith('src/features/cli/')
     && !rel.startsWith('src/modules/domain/note/')
@@ -367,7 +379,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)
+    && !FULL_PLATFORM_PERSISTENCE.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/scaffold/lite-exports.mjs

@@ -51,6 +51,22 @@ const REGISTRATIONS = Object.freeze({
       names: ["sql"],
       beforeSource: "./errors/database.error",
     },
+    {
+      // The outbox write and the relay call the queue functions of their migration (R334).
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./database.client",
+      names: ["callDbFunction"],
+      beforeSource: "./primary.decorators",
+    },
+  ],
+  // The jobs capability (add job, the fenced-job pattern): its tick takes a transaction-scoped lock before it claims the minute (R335).
+  jobs: [
+    {
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./database.client",
+      names: ["advisoryXactLock", "callDbFunction"],
+      beforeSource: "./primary.decorators",
+    },
   ],
   webhook: [
     {
@@ -59,6 +75,13 @@ const REGISTRATIONS = Object.freeze({
       names: ["BATCH_ROWS", "sql"],
       beforeSource: "./errors/database.error",
     },
+    {
+      // The inbox claim and the lite event bus call the functions of their migration (R334).
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./database.client",
+      names: ["callDbFunction"],
+      beforeSource: "./primary.decorators",
+    },
     {
       // PRIMARY_ENTITY_MANAGER: the token the inbox service's unit spec provides its EntityManager double under.
       file: "be/src/modules/platform/database/index.ts",

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

@@ -1,5 +1,8 @@
 import type { Secret } from "@modules/platform/config"
 
+/** An entity class as TypeORM registers it. */
+export type EntityClass = new () => object
+
 /** What the primary connection parser reads from the environment. */
 export interface DatabaseConnectionConfig {
     /** The logical connection name declared in `hfs.json`. */
@@ -21,5 +24,5 @@ export interface DatabaseOptions {
     /** The connections this app opens; one per physical database. */
     readonly connections: ReadonlyArray<DatabaseConnectionOptions>
     /** The TypeORM entities the connections map: PRIMARY_ENTITIES of `@modules/platform/database/entities`, passed by the app's composition root only. */
-    readonly entities: ReadonlyArray<Function>
+    readonly entities: ReadonlyArray<EntityClass>
 }

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

@@ -1,7 +1,10 @@
+import { httpSecurityEntities } from "@modules/platform/http-security"
+import type { EntityClass } from "./database.options"
+
 /**
  * The entity list of the primary connection: each capability's `<c>Entities` array (its `persistence/entities/index.ts`), by
  * name, no glob (the entity registry, slot be.platform.database.entities). Only app composition and the test world import this
  * file, from the deep path `@modules/platform/database/entities`; DatabaseModule and the database barrel never do, since the
  * capability barrels import the database capability back.
  */
-export const PRIMARY_ENTITIES: ReadonlyArray<Function> = []
+export const PRIMARY_ENTITIES: ReadonlyArray<EntityClass> = [...httpSecurityEntities]

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

@@ -1,9 +1,7 @@
 export { DatabaseModule } from "./database.module"
-export { advisoryXactLock, callDbFunction, notify } from "./database.client"
 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"

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

@@ -5,6 +5,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, ServerToServer } from "./origin.guard"
+export { httpSecurityEntities } from "./persistence/entities"
 export { RateLimitGuard } from "./rate-limit.guard"
 export { applyHttpSecurity } from "./edge-security.service"
 export { ReadinessService } from "./readiness.service"

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

@@ -0,0 +1,4 @@
+import { RateWindowEntity } from "./rate-window.entity"
+
+/** The entities of the http-security capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
+export const httpSecurityEntities = [RateWindowEntity]

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

@@ -0,0 +1,17 @@
+import { Column, Entity, PrimaryColumn } from "typeorm"
+
+@Entity({ schema: "public", name: "http_security_rate_windows" })
+/** One rate limit window of one caller and tier, mapped from public.http_security_rate_windows of the baseline migration in db/migrations. */
+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-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),
+        })
+    }
+}