@starci/hfs 4.11.8 → 4.11.12

package/templates/app/ci-workflows/github/workflows/stack-key-restore.yml

@@ -0,0 +1,58 @@
+{{header}}
+# Restores the deploy server's age identity from its GitHub Environment backup (starci app secret server-key <env> --backup github
+# stored it; --restore github dispatches this file). It runs by hand only and writes {{serverAgeIdentity}} on the server when no
+# identity is there and the secret's public key is the recipient input (deploy.remote.serverRecipient), with umask 077 and mode 600,
+# owned by root; it never echoes the identity and never overwrites one.
+# The environment input names the protected GitHub environment of the deploy (required reviewers or main only), which holds:
+#   vars    VPS_HOST, VPS_USER (the swarm manager)
+#   secrets SOPS_AGE_KEY (that environment's server identity, the one its deploy jobs read), VPS_SSH_KEY (CI-only deploy key),
+#           VPS_KNOWN_HOSTS (pinned host keys)
+name: restore stack key
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Protected environment holding the deploy transport and the server identity backup
+        required: true
+        type: environment
+      recipient:
+        description: The public age recipient of the server identity, deploy.remote.serverRecipient of that environment
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: stack-${{ inputs.environment }}
+  cancel-in-progress: false
+
+jobs:
+  restore:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    timeout-minutes: 10
+    steps:
+      - name: write the identity on the server
+        env:
+          RECIPIENT: ${{ inputs.recipient }}
+          AGE_IDENTITY: ${{ secrets.SOPS_AGE_KEY }}
+          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
+          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
+          VPS_HOST: ${{ vars.VPS_HOST }}
+          VPS_USER: ${{ vars.VPS_USER }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ "$RECIPIENT" =~ ^age1[a-z0-9]+$ ]] || { echo "recipient must be one public age recipient (age1...)" >&2; exit 1; }
+          [ -n "$AGE_IDENTITY" ] || { echo "SOPS_AGE_KEY is not set in this environment" >&2; exit 1; }
+          umask 077
+          dir="$(mktemp -d)"
+          trap 'rm -rf "$dir"' EXIT
+          printf '%s\n' "$VPS_SSH_KEY" > "$dir/id"
+          printf '%s\n' "$VPS_KNOWN_HOSTS" > "$dir/known_hosts"
+          # The server writes the identity beside its target, keeps it only when its public key is the recipient, then moves it in.
+          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
+          printf '%s\n' "$AGE_IDENTITY" | ssh -T -i "$dir/id" -o IdentitiesOnly=yes -o UserKnownHostsFile="$dir/known_hosts" \
+            -o StrictHostKeyChecking=yes -o BatchMode=yes -o ConnectTimeout=20 "$VPS_USER@$VPS_HOST" "$remote"

package/templates/app/ci-workflows-lite/github/workflows/images.yml

@@ -1,6 +1,8 @@
 {{header}}
 # Builds each image declared by the lite app. The API image is required; a front-end image is emitted only when declared.
 # It runs on the release tag, so every image is built there, and never pushes.
+# When an environment declares images, the job is bound to that protected GitHub environment and opens its sealed build
+# arguments with that environment's SOPS_AGE_KEY (its server identity, starci app secret server-key <env> --backup github).
 name: images
 
 on:

package/templates/app/ci-workflows-lite/github/workflows/stack-deploy.yml

@@ -7,7 +7,9 @@
 # operation rollback  redeploys a stored release; "release" is 16 lowercase hex characters, empty means the previous accepted release
 # The environment input names a protected GitHub environment (required reviewers) that holds:
 #   vars    VPS_HOST, VPS_USER (the swarm manager); a variable named in deploy.passEnv, when the stack interpolates one
-#   secrets SOPS_AGE_KEY (the age identity of .sops.yaml), VPS_SSH_KEY (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
+#   secrets SOPS_AGE_KEY (that environment's server identity, stored there by starci app secret server-key <env> --backup github;
+#           both jobs are bound to the environment, so they read it and never a repository secret of that name), VPS_SSH_KEY
+#           (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
 # Nothing else is a secret: images are pushed with the workflow token, which also reads the CI verdict of the tag's commit a production deploy
 # waits for (requireCi deploy.prod). Dispatch inputs reach scripts only through env.
 name: deploy stack

package/templates/app/ci-workflows-lite/github/workflows/stack-key-restore.yml

@@ -0,0 +1,58 @@
+{{header}}
+# Restores the deploy server's age identity from its GitHub Environment backup (starci app secret server-key <env> --backup github
+# stored it; --restore github dispatches this file). It runs by hand only and writes {{serverAgeIdentity}} on the server when no
+# identity is there and the secret's public key is the recipient input (deploy.remote.serverRecipient), with umask 077 and mode 600,
+# owned by root; it never echoes the identity and never overwrites one.
+# The environment input names the protected GitHub environment of the deploy (required reviewers or main only), which holds:
+#   vars    VPS_HOST, VPS_USER (the swarm manager)
+#   secrets SOPS_AGE_KEY (that environment's server identity, the one its deploy jobs read), VPS_SSH_KEY (CI-only deploy key),
+#           VPS_KNOWN_HOSTS (pinned host keys)
+name: restore stack key
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Protected environment holding the deploy transport and the server identity backup
+        required: true
+        type: environment
+      recipient:
+        description: The public age recipient of the server identity, deploy.remote.serverRecipient of that environment
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: stack-${{ inputs.environment }}
+  cancel-in-progress: false
+
+jobs:
+  restore:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    timeout-minutes: 10
+    steps:
+      - name: write the identity on the server
+        env:
+          RECIPIENT: ${{ inputs.recipient }}
+          AGE_IDENTITY: ${{ secrets.SOPS_AGE_KEY }}
+          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
+          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
+          VPS_HOST: ${{ vars.VPS_HOST }}
+          VPS_USER: ${{ vars.VPS_USER }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ "$RECIPIENT" =~ ^age1[a-z0-9]+$ ]] || { echo "recipient must be one public age recipient (age1...)" >&2; exit 1; }
+          [ -n "$AGE_IDENTITY" ] || { echo "SOPS_AGE_KEY is not set in this environment" >&2; exit 1; }
+          umask 077
+          dir="$(mktemp -d)"
+          trap 'rm -rf "$dir"' EXIT
+          printf '%s\n' "$VPS_SSH_KEY" > "$dir/id"
+          printf '%s\n' "$VPS_KNOWN_HOSTS" > "$dir/known_hosts"
+          # The server writes the identity beside its target, keeps it only when its public key is the recipient, then moves it in.
+          remote="f={{serverAgeIdentity}}; r=$RECIPIENT; "'if [ "$(id -u)" -eq 0 ]; then S=; else S="sudo -n"; fi; if $S test -e "$f"; then cat >/dev/null; echo "the server already holds $f; move it aside first" >&2; exit 3; fi; $S sh -c '"'"'umask 077; f="$1"; r="$2"; d="$(dirname "$f")"; mkdir -p "$d"; t="$(mktemp "$d/.restore.XXXXXX")"; cat > "$t"; if [ "$(age-keygen -y "$t" 2>/dev/null)" != "$r" ]; then rm -f "$t"; echo "the secret is not the identity of $r (or age-keygen is missing); nothing was written" >&2; exit 6; fi; chown root:root "$t"; chmod 600 "$t"; mv "$t" "$f"; age-keygen -y "$f"'"'"' sh "$f" "$r"'
+          printf '%s\n' "$AGE_IDENTITY" | ssh -T -i "$dir/id" -o IdentitiesOnly=yes -o UserKnownHostsFile="$dir/known_hosts" \
+            -o StrictHostKeyChecking=yes -o BatchMode=yes -o ConnectTimeout=20 "$VPS_USER@$VPS_HOST" "$remote"

package/templates/be/skeleton/src/modules/platform/http/fetch-http-client.client.spec.ts

@@ -1,5 +1,5 @@
 import { Test } from "@nestjs/testing"
-import { mock } from "@starci/jest-preset"
+import { builder, mock } from "@starci/jest-preset"
 import { Agent } from "undici"
 import { HttpErrorCode } from "./errors/http.error"
 import { FetchHttpClient } from "./fetch-http-client.client"
@@ -10,9 +10,9 @@ import type { HttpOptions } from "./http.options"
 const anyOf = (type: unknown): unknown => expect.any(type)
 const objectLike = (shape: Record<string, unknown>): unknown => expect.objectContaining(shape)
 
-const build = async (options: HttpOptions = {}): Promise<FetchHttpClient> => {
+const build = async (overrides?: Partial<HttpOptions>): Promise<FetchHttpClient> => {
     const moduleRef = await Test.createTestingModule({
-        providers: [FetchHttpClient, { provide: HTTP_OPTIONS, useValue: options }],
+        providers: [FetchHttpClient, { provide: HTTP_OPTIONS, useValue: builder<HttpOptions>({})(overrides) }],
     }).compile()
     return moduleRef.get(FetchHttpClient)
 }

package/templates/be/skeleton/src/modules/platform/http/fetch-http-client.client.ts

@@ -65,9 +65,8 @@ export class FetchHttpClient implements HttpClient, OnModuleDestroy {
                 method: request.method,
                 headers: this.headersOf(request),
                 ...(body === undefined ? {} : { body }),
-                signal,
             }
-            return await fetch(request.url, this.routed(init))
+            return await fetch(request.url, { ...this.routed(init), signal })
         } catch (cause) {
             throw this.failure(cause)
         }

package/templates/be/skeleton-lite/apps/api/src/api.env.ts

@@ -1,6 +1,7 @@
 import type { EnvSource } from "@modules/platform/config"
 import { parseServerConfig } from "@modules/platform/config"
 import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
+import { parseHttpConfig } from "@modules/platform/http"
 import { parseHttpSecurityConfig } from "@modules/platform/http-security"
 import { parsePassportConfig } from "@modules/integrations/passport"
 import { parseObjectStorageConfig } from "@modules/integrations/object-storage"
@@ -11,6 +12,8 @@ export interface ApiEnv {
     readonly server: ReturnType<typeof parseServerConfig>
     /** The origin allowlist and rate limits. */
     readonly httpSecurity: ReturnType<typeof parseHttpSecurityConfig>
+    /** What the outbound HTTP client trusts beyond Node's bundled certificate authorities. */
+    readonly http: ReturnType<typeof parseHttpConfig>
     /** The least-privilege PostgreSQL connection to the app's own database. */
     readonly database: ReturnType<typeof parsePrimaryDatabaseConfig>
     /** Google OAuth, the app's own access tokens and the refresh cookie. */
@@ -23,6 +26,7 @@ export interface ApiEnv {
 export const readApiEnv = (env: EnvSource): ApiEnv => ({
     server: parseServerConfig(env),
     httpSecurity: parseHttpSecurityConfig(env),
+    http: parseHttpConfig(env),
     database: parsePrimaryDatabaseConfig(env),
     passport: parsePassportConfig(env),
     objectStorage: parseObjectStorageConfig(env),

package/templates/be/skeleton-lite/apps/api/src/api.options.ts

@@ -2,6 +2,7 @@ import type { PassportOptions } from "@modules/integrations/passport"
 import type { ObjectStorageOptions } from "@modules/integrations/object-storage"
 import type { ServerOptions } from "@modules/platform/config"
 import type { DatabaseConnectionOptions } from "@modules/platform/database"
+import type { HttpOptions } from "@modules/platform/http"
 import type { HttpSecurityOptions } from "@modules/platform/http-security"
 
 /** Everything the API needs from its environment, parsed by `api.env.ts` and handed to `AppModule.register`. */
@@ -10,6 +11,8 @@ export interface ApiOptions {
     readonly server: ServerOptions
     /** The origin allowlist and rate limits. */
     readonly httpSecurity: HttpSecurityOptions
+    /** What the outbound HTTP client trusts beyond Node's bundled certificate authorities. */
+    readonly http: HttpOptions
     /** The least-privilege PostgreSQL connection to the app's own database. */
     readonly database: DatabaseConnectionOptions
     /** Google OAuth, the app's own access tokens and the refresh cookie. */

package/templates/be/skeleton-lite/apps/api/src/compose/platform.ts

@@ -25,7 +25,7 @@ export const platformModules = (options: ApiOptions): Array<DynamicModule> => [
     RetryModule.register({ isGlobal: true }),
     IdsModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
-    HttpModule.register({ isGlobal: true }),
+    HttpModule.register({ isGlobal: true, ...options.http }),
     I18nModule.register({
         isGlobal: true,
         bundles: [HTTP_MESSAGES, ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],

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()
+    })
+})