@starci/hfs 4.9.8 → 4.9.11

package/stack/urgent-floor.mjs

@@ -0,0 +1,147 @@
+// urgent-floor.mjs - the safety floor of an urgent deploy (`starci app stack deploy --urgent`, owner ruling urgent-release 2026-10-29). An urgent
+// release skips CI and the full gate, never this floor; each step that fails is a refusal with its own code, never a warning:
+//   record     the commit carries a pushed URGENT record (release/urgent.mjs)                     STACK_URGENT_NO_RECORD, STACK_URGENT_NOT_PUSHED
+//   backup     a fresh full database backup, encrypted to the app's age recipients (db dump)       STACK_URGENT_BACKUP_FAILED
+//   verified   its receipt names this run, its size, age header and sha256 match the archive        STACK_URGENT_BACKUP_UNVERIFIED
+//   decrypt    a test decrypt with the operator's age identity (SOPS_AGE_KEY_FILE) lists every part STACK_URGENT_DECRYPT_UNAVAILABLE, STACK_URGENT_DECRYPT_FAILED
+//   render     the release renders locally (deploy.mjs inspectRendered)                           its own STACKS_/STACK_DEPLOY_ refusal
+//   rollback   an accepted previous release exists, so a red deploy has somewhere to go back to    STACK_URGENT_NO_ROLLBACK_TARGET
+//   migrate    db migrate previews the plan, then executes it                                     STACK_URGENT_MIGRATE_PREVIEW_RED, STACK_URGENT_MIGRATE_FAILED
+//   deploy     the release with its readiness verify (deploy.verify); red rolls back by itself    STACK_URGENT_RED_ROLLED_BACK, STACK_URGENT_ROLLBACK_FAILED,
+//                                                                                                 STACK_URGENT_DEPLOY_NOT_STARTED (red before the stack deploy)
+// The public-host checks are never skipped (STACK_URGENT_SKIP_PUBLIC). A rollback cannot undo the migrations: the backup above is their way back.
+// `deps` are the collaborators (backup, decrypt, migrate), each defaulting to the app's own db verbs; a spec injects stubs.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readDeclaration } from '../release/index.mjs';
+import { releaseDir } from '../release/gate.mjs';
+import { readUrgent } from '../release/records.mjs';
+import { refusal } from './errors.mjs';
+
+const AGE_HEADER = 'age-encryption.org/v1\n';
+const SHA = /^[a-f0-9]{64}$/u;
+
+/** The database a floor step reaches: the connection named by --db-url-env, else the linked project of the `database:` block. */
+const targetOf = (options) => (options.dbUrlEnv ? { urlEnv: options.dbUrlEnv } : { linked: true });
+
+/** The backups of an urgent deploy live outside every repository: --backup-out, else ~/.starci-backups/<project>. */
+const backupDir = (config, options) => options.backupOut ?? path.join(os.homedir(), '.starci-backups', config.project);
+
+async function defaultBackup(ctx, { target, out }) {
+  const { dumpDatabase } = await import('../db/dump.mjs');
+  return dumpDatabase(ctx, { ...target, out }).data;
+}
+
+async function defaultDecrypt(ctx, { archive, identity, parts }) {
+  const { backupTool } = await import('../db/backup-receipt.mjs');
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-decrypt-'));
+  try {
+    backupTool(ctx, 'age', ['-d', '-i', identity, '-o', path.join(scratch, 'backup.tar'), archive]);
+    const listed = String(backupTool(ctx, 'tar', ['-tf', 'backup.tar'], { cwd: scratch }).stdout ?? '').split(/\r?\n/u).map((line) => line.replace(/^\.\//u, '').trim());
+    const missing = parts.filter((part) => !listed.includes(part));
+    if (missing.length > 0) throw new Error(`the decrypted archive lacks ${missing.join(', ')}`);
+    return { parts: listed.filter(Boolean) };
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+async function defaultMigrate(ctx, { target, execute }) {
+  const { loadDatabase, migrateDatabase } = await import('../db/migrate.mjs');
+  // The urgent deploy's --execute is the arming of this one migration: the floor runs it, it never waits for a second switch.
+  const armed = Object.create(ctx, { env: { value: { ...ctx.env, STARCI_DB_ARMED: '1' } } });
+  return migrateDatabase(armed, loadDatabase(ctx.cwd), { ...target, execute });
+}
+
+export const FLOOR_DEPS = Object.freeze({ backup: defaultBackup, decrypt: defaultDecrypt, migrate: defaultMigrate });
+
+/** A refused floor step: the lines so far and the code; the CLI prints both and exits 2. */
+const refused = (lines, code, message, data = {}) => ({ ok: false, refused: { code, message }, lines, data: { ...data, refused: code } });
+
+/** Problems of the backup receipt against its archive: written by this run, a full backup, its size, age header and sha256 equal to the file's. */
+function receiptProblems(receipt, archive, startedMs, sha256) {
+  const problems = [];
+  if (!receipt || typeof receipt !== 'object') return ['no receipt'];
+  if (receipt.schemaOnly !== false) problems.push('the backup is not a full (data) backup');
+  if (!Number.isFinite(Date.parse(receipt.at)) || Date.parse(receipt.at) < startedMs - 1000) problems.push('the receipt is not from this run');
+  if (!fs.existsSync(archive)) return [...problems, 'the archive is missing'];
+  const size = fs.statSync(archive).size;
+  const header = Buffer.alloc(AGE_HEADER.length);
+  const fd = fs.openSync(archive, 'r');
+  try { fs.readSync(fd, header, 0, header.length, 0); } finally { fs.closeSync(fd); }
+  if (header.toString('ascii') !== AGE_HEADER) problems.push('the archive has no age header');
+  if (size !== receipt.bytes) problems.push(`the archive is ${size} bytes, the receipt says ${receipt.bytes}`);
+  if (!SHA.test(String(receipt.sha256 ?? '')) || sha256(archive) !== receipt.sha256) problems.push('the archive sha256 differs from the receipt');
+  return problems;
+}
+
+/** What the floor needs before anything runs: the pushed urgent record, a declared database, the identity of the test decrypt, the full public verify. */
+function preconditions(ctx, config, options) {
+  if (options.skipPublic) throw refusal('STACK_URGENT_SKIP_PUBLIC', 'an urgent deploy verifies the public hosts and accepts the release: drop --skip-public');
+  const record = readUrgent(releaseDir(ctx), options.sourceSha);
+  if (!record) throw refusal('STACK_URGENT_NO_RECORD', `${options.sourceSha} has no urgent record: push it with starci app release push --urgent --reason "<text>" --execute first`);
+  if (record.pushed !== true) throw refusal('STACK_URGENT_NOT_PUSHED', `the urgent release ${record.tag} of ${options.sourceSha.slice(0, 10)} was never pushed`);
+  if (!readDeclaration(config.repoRoot ?? ctx.cwd).database) throw refusal('STACK_URGENT_NO_DATABASE', 'the floor backs up and migrates the database the `database:` block declares, and this app declares none');
+  const identity = ctx.env.SOPS_AGE_KEY_FILE;
+  if (!identity || !fs.existsSync(identity)) throw refusal('STACK_URGENT_DECRYPT_UNAVAILABLE', 'the test decrypt of the backup reads the age identity named by SOPS_AGE_KEY_FILE, which is not set or not a file');
+  return { record, identity };
+}
+
+/**
+ * The floor's steps before the deploy: backup, verify and test decrypt (before anything remote), the local render, the rollback target, migrate
+ * preview and execute. Returns null when all passed, else the refused result.
+ */
+async function guard(ctx, config, options, { f, run, identity, lines }) {
+  const target = targetOf(options);
+  const started = ctx.now();
+  let backup;
+  try { backup = await f.backup(ctx, { target, out: backupDir(config, options) }); } catch (error) {
+    return refused(lines, 'STACK_URGENT_BACKUP_FAILED', `the fresh database backup failed (${String(error?.code ?? error?.message ?? error)}); nothing was migrated or deployed`);
+  }
+  const archive = path.join(path.dirname(backup.receiptPath), backup.receipt?.file ?? '');
+  const problems = receiptProblems(backup.receipt, archive, started, run.sha256);
+  if (problems.length > 0) return refused(lines, 'STACK_URGENT_BACKUP_UNVERIFIED', `${problems.join('; ')}; nothing was migrated or deployed`);
+  lines.push(`floor: backup ${path.basename(archive)} (${backup.receipt.bytes} bytes, sha256 ${backup.receipt.sha256.slice(0, 12)}) receipt ${backup.receiptPath}`);
+  try { await f.decrypt(ctx, { archive, identity, parts: backup.receipt.parts }); } catch (error) {
+    return refused(lines, 'STACK_URGENT_DECRYPT_FAILED', `the test decrypt of the backup failed (${String(error?.code ?? error?.message ?? error)}); nothing was migrated or deployed`);
+  }
+  lines.push(`floor: test decrypt listed ${backup.receipt.parts.length} part(s)`);
+  const { releaseId } = await run.render();
+  lines.push(`floor: release ${releaseId} rendered`);
+  const store = await run.openStore();
+  if (!(await store.current())) return refused(lines, 'STACK_URGENT_NO_ROLLBACK_TARGET', 'no accepted previous release is stored on the manager, so a red urgent deploy could not roll back; nothing was migrated or deployed');
+  let preview;
+  try { preview = await f.migrate(ctx, { target, execute: false }); } catch (error) { preview = { ok: false, lines: [String(error?.message ?? error)] }; }
+  lines.push(...(preview.lines ?? []).map((line) => `floor: migrate preview: ${line}`));
+  if (!preview.ok) return refused(lines, 'STACK_URGENT_MIGRATE_PREVIEW_RED', 'the migration preview is red; nothing was migrated or deployed');
+  let applied;
+  try { applied = await f.migrate(ctx, { target, execute: true }); } catch (error) { applied = { ok: false, lines: [String(error?.message ?? error)] }; }
+  lines.push(...(applied.lines ?? []).map((line) => `floor: migrate: ${line}`));
+  if (!applied.ok) return refused(lines, 'STACK_URGENT_MIGRATE_FAILED', `the migration failed; nothing was deployed (restore from ${backup.receiptPath} if the database is half migrated)`);
+  return null;
+}
+
+/**
+ * An urgent deploy: the floor's preconditions, then (with execute) its guard steps, then `deployExecute` (the release, its readiness verify and the
+ * automatic rollback). `run` = { render(), openStore(), deployExecute(), dryRun(), sha256 }. Returns { ok, lines, data } or a refused result whose
+ * data names the urgent release.
+ */
+export async function urgentDeploy(ctx, config, options, run, deps = {}) {
+  const f = { ...FLOOR_DEPS, ...deps };
+  const { record, identity } = preconditions(ctx, config, options);
+  const lines = [`urgent         ${record.tag} (${options.sourceSha.slice(0, 10)}) by ${record.role}: ${record.reason}`];
+  if (options.execute !== true) {
+    const plan = await run.dryRun();
+    return { ...plan, lines: [...lines, 'floor (never skipped): fresh encrypted database backup, receipt verify, test decrypt, rollback target, migrate preview then execute, deploy with readiness verify and automatic rollback', ...plan.lines] };
+  }
+  const stop = await guard(ctx, config, options, { f, run, identity, lines });
+  if (stop) return { ...stop, data: { ...stop.data, urgent: record.tag } };
+  const deployed = await run.deployExecute();
+  const all = [...lines, ...deployed.lines];
+  if (deployed.ok) return { ...deployed, lines: all, data: { ...deployed.data, urgent: record.tag } };
+  const data = { ...deployed.data, urgent: record.tag };
+  if (!(deployed.data?.steps ?? []).some((step) => step.step === 'deploy')) return refused(all, 'STACK_URGENT_DEPLOY_NOT_STARTED', 'the release failed before the stack deploy, so the services are untouched; the migrations stay (backup above)', data);
+  if (deployed.data?.rolledBack) return refused(all, 'STACK_URGENT_RED_ROLLED_BACK', `the release failed its deploy or readiness verify and was rolled back to ${deployed.data.previous}; the migrations stay (backup above)`, data);
+  return refused(all, 'STACK_URGENT_ROLLBACK_FAILED', 'the release is red and the automatic rollback did not converge: follow the stack runbook, Rollback', data);
+}

package/sync/ci-commands.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { refusal } from '../stack/errors.mjs';
 import { byCodeUnit } from '../report/order.mjs';
+import { ENTITY_LIST } from '../db/entity-list.mjs';
 
 // One command vocabulary for managed CI rendering and the runtime coverage gate.
 const exampleCommand = (source, command) => source?.runtimeExample
@@ -195,7 +196,8 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
     ciLintSonar: exampleCommand(source, 'npm run lint -- --sonar reports/lint.sonar.json'),
     // The coverage judgement alone over the merged report: the fast and lint jobs already ran every other rule of the app check.
     ciCoverageProof: exampleCommand(source, 'npx starci app coverage verify ' + lcovReport),
-    ciDatabaseLint: exampleCommand(source, 'npm run db:lint'),
+    // An app with an entity list also checks its entities against the schema its migrations build, in the build job (a runner with Docker).
+    ciDatabaseLint: exampleCommand(source, (source?.files ?? []).includes(ENTITY_LIST.slice('be/'.length)) ? 'npm run db:lint && npx starci app db drift' : 'npm run db:lint'),
     auditCommand: `npm audit${audit.omitDev ? ' --omit=dev' : ''} --audit-level=${audit.level}`,
     sonarTokenSecret: sonar?.token ?? 'SONAR_TOKEN',
     sonarHostVar: sonar?.hostVar ?? 'SONAR_HOST_URL',

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

@@ -8,7 +8,8 @@
 # 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)
-# Nothing else is a secret: images are pushed with the workflow token. Dispatch inputs reach scripts only through env.
+# 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
 
 on:
@@ -48,6 +49,7 @@ jobs:
     permissions:
       contents: read
       packages: write
+      actions: read
     env:
       STACK_ENVIRONMENT: ${{ inputs.environment }}
     steps:{{stackGuard}}
@@ -88,6 +90,7 @@ jobs:
       - name: deploy the release
         env:
           XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+          GH_TOKEN: ${{ github.token }}
           SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}{{stackImageEnv}}{{stackPassEnv}}
         run: |
           npx --no-install starci app stack deploy --env "$STACK_ENVIRONMENT" \{{stackImageArgs}}

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

@@ -8,7 +8,8 @@
 # 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)
-# Nothing else is a secret: images are pushed with the workflow token. Dispatch inputs reach scripts only through env.
+# 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
 
 on:
@@ -48,6 +49,7 @@ jobs:
     permissions:
       contents: read
       packages: write
+      actions: read
     env:
       STACK_ENVIRONMENT: ${{ inputs.environment }}
     steps:{{stackGuard}}
@@ -88,6 +90,7 @@ jobs:
       - name: deploy the release
         env:
           XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+          GH_TOKEN: ${{ github.token }}
           SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}{{stackImageEnv}}{{stackPassEnv}}
         run: |
           npx --no-install starci app stack deploy --env "$STACK_ENVIRONMENT" \{{stackImageArgs}}

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/domain/identity/identity.decorators.ts

@@ -1,14 +1,22 @@
-import { SetMetadata } from "@nestjs/common"
+import { SetMetadata, applyDecorators } from "@nestjs/common"
 import { injector } from "@modules/platform/composition"
-import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { DoorDecorator, TypedParameterDecorator } from "@modules/platform/composition"
+import { ServerToServer } from "@modules/platform/http-security"
 import type { CredentialAuthenticator, CredentialMetadata } from "./credential.contracts"
+import { PublicReason } from "./identity.contracts"
 import type { PublicMetadata } from "./identity.contracts"
 
 /** Metadata key of `@Public`. */
 export const PUBLIC_KEY = "domain.identity.public"
 
-/** Opens a door to anonymous callers, stating why; every other door needs a credential or a signed-in caller. */
-export const Public = (metadata: PublicMetadata): ReturnType<typeof SetMetadata> => SetMetadata(PUBLIC_KEY, metadata)
+/**
+ * Opens a door to anonymous callers, stating why; every other door needs a credential or a signed-in caller. A
+ * signed webhook proves its caller by its signature, so it owes no browser origin.
+ */
+export const Public = (metadata: PublicMetadata): DoorDecorator =>
+    metadata.reason === PublicReason.SignedWebhook
+        ? applyDecorators(SetMetadata(PUBLIC_KEY, metadata), ServerToServer())
+        : applyDecorators(SetMetadata(PUBLIC_KEY, metadata))
 
 /** Metadata key of `@Credential`. */
 export const CREDENTIAL_KEY: unique symbol = Symbol("domain.identity.credential")
@@ -20,6 +28,9 @@ export const CREDENTIAL_AUTHENTICATOR: unique symbol = Symbol("domain.identity.c
 export const InjectCredentialAuthenticator = (): TypedParameterDecorator<CredentialAuthenticator> =>
     injector<CredentialAuthenticator>(CREDENTIAL_AUTHENTICATOR)
 
-/** Marks a door authenticated by its own credential; `CredentialGuard` authenticates it and `AuthGuard` admits it. */
-export const Credential = (metadata: CredentialMetadata): ReturnType<typeof SetMetadata> =>
-    SetMetadata(CREDENTIAL_KEY, metadata)
+/**
+ * Marks a door authenticated by its own credential; `CredentialGuard` authenticates it and `AuthGuard` admits it. The
+ * credential travels in a header no browser attaches by itself, so the door owes no browser origin.
+ */
+export const Credential = (metadata: CredentialMetadata): DoorDecorator =>
+    applyDecorators(SetMetadata(CREDENTIAL_KEY, metadata), ServerToServer())

package/templates/be/skeleton/src/modules/platform/composition/composition.decorators.ts

@@ -8,6 +8,9 @@ export type TypedParameterDecorator<T> = ParameterDecorator & {
     readonly __injects?: T
 }
 
+/** A decorator a door carries on its method or its class; one built from several metadata decorators is typed with it. */
+export type DoorDecorator = MethodDecorator & ClassDecorator
+
 /** Builds the parameter decorator that injects `token`, typed with the value it injects. Every `Inject<Thing>()` is built with it. */
 export const injector = <T>(token: InjectionToken): TypedParameterDecorator<T> => Inject(token)
 

package/templates/be/skeleton/src/modules/platform/composition/index.ts

@@ -1,2 +1,2 @@
 export { InjectReflector, injector } from "./composition.decorators"
-export type { TypedParameterDecorator } from "./composition.decorators"
+export type { DoorDecorator, TypedParameterDecorator } from "./composition.decorators"

package/templates/be/skeleton/src/modules/platform/errors/errors.filter.spec.ts

@@ -37,7 +37,7 @@ describe("ErrorsFilter", () => {
         const { filter, errors, requestLocale } = await build()
         const failure = new Error("note missing")
         const request = mock<Request>({ headers: { "accept-language": "en-US,en;q=0.9" } })
-        const response = mock<Response>()
+        const response = mock<Response>({ headersSent: false })
         response.status.mockReturnValue(response)
         const http = mock<ReturnType<ArgumentsHost["switchToHttp"]>>()
         http.getRequest.mockReturnValue(request)
@@ -66,4 +66,18 @@ describe("ErrorsFilter", () => {
             params: { noteId: "note-1" },
         })
     })
+
+    it("leaves a response a guard already sent as it is", async () => {
+        const { filter, errors } = await build()
+        const response = mock<Response>({ headersSent: true })
+        const http = mock<ReturnType<ArgumentsHost["switchToHttp"]>>()
+        http.getResponse.mockReturnValue(response)
+        const host = mock<ArgumentsHost>()
+        host.switchToHttp.mockReturnValue(http)
+
+        expect(filter.catch(new Error("rate limited"), host)).toBeUndefined()
+
+        expect(errors.describe).not.toHaveBeenCalled()
+        expect(response.status).not.toHaveBeenCalled()
+    })
 })

package/templates/be/skeleton/src/modules/platform/errors/errors.filter.ts

@@ -9,7 +9,8 @@ import type { ErrorsService } from "./errors.service"
 @Catch()
 /**
  * The one REST exception filter of an app: answers `{ code, kind, message, params }` with the status of the kind. In a GraphQL
- * context it hands the failure back untouched, so the GraphQL error formatter (platform/graphql) answers it.
+ * context it hands the failure back untouched, so the GraphQL error formatter (platform/graphql) answers it. A response a
+ * guard already answered (a redirect-only door over its rate limit) is left as it was sent.
  */
 export class ErrorsFilter implements ExceptionFilter {
     constructor(
@@ -21,17 +22,17 @@ export class ErrorsFilter implements ExceptionFilter {
     catch(exception: unknown, host: ArgumentsHost): unknown {
         if (host.getType<string>() === "graphql") return exception
         const http = host.switchToHttp()
+        const response = http.getResponse<Response>()
+        if (response.headersSent) return undefined
         const request = http.getRequest<Request>()
         const description = this.errors.describe(exception)
         const locale = this.requestLocale.of(request.headers["accept-language"])
-        http.getResponse<Response>()
-            .status(description.status)
-            .json({
-                code: description.code,
-                kind: description.kind,
-                message: this.errors.text(description.code, description.params, locale),
-                params: description.params,
-            })
+        response.status(description.status).json({
+            code: description.code,
+            kind: description.kind,
+            message: this.errors.text(description.code, description.params, locale),
+            params: description.params,
+        })
         return undefined
     }
 }

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

@@ -3,7 +3,8 @@ export { parseHttpSecurityConfig } from "./http-security.config"
 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 { OriginGuard, ServerToServer } 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/origin.guard.spec.ts

@@ -1,11 +1,13 @@
-import type { ExecutionContext } from "@nestjs/common"
+import "reflect-metadata"
+import type { ExecutionContext, Type } from "@nestjs/common"
 import type { Request } from "express"
+import { Reflector } from "@nestjs/core"
 import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 import { HttpSecurityErrorCode } from "./errors/http-security.error"
 import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
-import { OriginGuard } from "./origin.guard"
+import { OriginGuard, ServerToServer } from "./origin.guard"
 
 const options: HttpSecurityOptions = {
     allowedOrigins: ["https://app.test"],
@@ -13,49 +15,63 @@ const options: HttpSecurityOptions = {
     webhooks: {},
 }
 
-const build = async (method: string, headers: Request["headers"]) => {
+class OpenDoor {}
+
+class SignedDoor {}
+ServerToServer()(SignedDoor)
+
+const build = async (method: string, headers: Request["headers"], door: Type<unknown> = OpenDoor) => {
     const request = mock<Request>({ headers, method })
     const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
     http.getRequest.mockReturnValue(request)
     const context = mock<ExecutionContext>()
     context.switchToHttp.mockReturnValue(http)
+    context.getHandler.mockReturnValue(() => undefined)
+    context.getClass.mockReturnValue(door)
     const moduleRef = await Test.createTestingModule({
-        providers: [OriginGuard, { provide: HTTP_SECURITY_OPTIONS, useValue: options }],
+        providers: [OriginGuard, Reflector, { provide: HTTP_SECURITY_OPTIONS, useValue: options }],
     }).compile()
     return { guard: moduleRef.get(OriginGuard), context }
 }
 
 describe("OriginGuard", () => {
-    it.each(["GET", "HEAD", "OPTIONS"])("allows the safe %s method regardless of origin", async (method) => {
-        const { guard, context } = await build(method, { origin: "https://foreign.test" })
+    it.each(["GET", "HEAD", "OPTIONS"])("allows the safe %s method without an origin", async (method) => {
+        const { guard, context } = await build(method, {})
 
         expect(guard.canActivate(context)).toBe(true)
     })
 
-    it.each([{}, { referer: "not a URL" }])(
-        "allows a state-changing non-browser request without a usable origin (%o)",
-        async (headers) => {
-            const { guard, context } = await build("POST", headers)
-
-            expect(guard.canActivate(context)).toBe(true)
-        },
-    )
-
     it("allows a state-changing request carrying an allowed Origin header", async () => {
         const { guard, context } = await build("POST", { origin: "https://app.test" })
 
         expect(guard.canActivate(context)).toBe(true)
     })
 
-    it("uses the origin of an allowed Referer URL", async () => {
+    it("falls back to the origin of an allowed Referer when Origin is absent", async () => {
         const { guard, context } = await build("PATCH", { referer: "https://app.test/notes/one" })
 
         expect(guard.canActivate(context)).toBe(true)
     })
 
-    it("refuses a state-changing request from an origin outside the allowlist", async () => {
-        const { guard, context } = await build("DELETE", { origin: "https://foreign.test" })
+    it.each([
+        { name: "no Origin and no Referer", headers: {} },
+        { name: "a Referer that is not a URL", headers: { referer: "not a URL" } },
+        { name: "an Origin outside the allowlist", headers: { origin: "https://foreign.test" } },
+        { name: "the opaque null Origin", headers: { origin: "null" } },
+        { name: "a Referer outside the allowlist", headers: { referer: "https://foreign.test/form" } },
+        {
+            name: "a foreign Origin beside an allowed Referer",
+            headers: { origin: "https://foreign.test", referer: "https://app.test/notes/one" },
+        },
+    ])("refuses a state-changing request with $name", async ({ headers }) => {
+        const { guard, context } = await build("DELETE", headers)
 
         expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.OriginRejected)
     })
+
+    it("allows a state-changing request without an origin on a door marked server-to-server", async () => {
+        const { guard, context } = await build("POST", {}, SignedDoor)
+
+        expect(guard.canActivate(context)).toBe(true)
+    })
 })

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

@@ -1,5 +1,7 @@
-import { Injectable } from "@nestjs/common"
+import { Injectable, SetMetadata } from "@nestjs/common"
 import type { CanActivate, ExecutionContext } from "@nestjs/common"
+import type { Reflector } from "@nestjs/core"
+import { InjectReflector } from "@modules/platform/composition"
 import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
 import { requestOf } from "./execution-request.mapper"
 import { InjectHttpSecurityOptions } from "./http-security.decorators"
@@ -7,25 +9,44 @@ import type { HttpSecurityOptions } from "./http-security.options"
 
 const SAFE_METHODS: ReadonlySet<string> = new Set(["GET", "HEAD", "OPTIONS"])
 
+const SERVER_TO_SERVER_KEY = "platform.http-security.server-to-server"
+
+/**
+ * Marks a door whose caller is a server proving itself on every request (a signed webhook, a header credential), so no
+ * browser origin is owed. Applied only by the identity decorators that carry that proof: `@Public({ reason:
+ * PublicReason.SignedWebhook })` and `@Credential({ kind })`.
+ */
+export const ServerToServer = (): ReturnType<typeof SetMetadata> => SetMetadata(SERVER_TO_SERVER_KEY, true)
+
+/** The origin a request names: its Origin header, or the origin of its Referer only when Origin is absent. */
 const originOf = (origin: string | undefined, referer: string | undefined): string | undefined => {
-    if (origin) return origin
-    return referer && URL.canParse(referer) ? new URL(referer).origin : undefined
+    if (origin !== undefined) return origin
+    return referer !== undefined && URL.canParse(referer) ? new URL(referer).origin : undefined
 }
 
 @Injectable()
 /**
- * The second app guard, the CSRF defence: a state-changing request that names an origin (browsers always do) must name
- * an allowed one. A request without Origin and Referer is not a browser and carries no ambient credential, so it passes.
+ * The second app guard, the CSRF defence: a state-changing request must name an allowed origin, by its Origin header or,
+ * when Origin is absent, by its Referer. A request that names none is refused, since a session cookie rides on it
+ * whatever sent it. A door marked `ServerToServer` proves its caller itself and owes no origin.
  */
 export class OriginGuard implements CanActivate {
-    constructor(@InjectHttpSecurityOptions() private readonly options: HttpSecurityOptions) {}
+    constructor(
+        @InjectReflector() private readonly reflector: Reflector,
+        @InjectHttpSecurityOptions() private readonly options: HttpSecurityOptions,
+    ) {}
 
-    /** Refuses a state-changing request from an origin outside the allowlist. */
+    /** Refuses a state-changing request whose origin is missing or outside the allowlist. */
     canActivate(context: ExecutionContext): boolean {
         const request = requestOf(context)
         if (SAFE_METHODS.has(request.method)) return true
+        const exempt = this.reflector.getAllAndOverride<boolean | undefined>(SERVER_TO_SERVER_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ])
+        if (exempt === true) return true
         const origin = originOf(request.headers.origin, request.headers.referer)
-        if (origin === undefined || this.options.allowedOrigins.includes(origin)) return true
+        if (origin !== undefined && this.options.allowedOrigins.includes(origin)) return true
         throw new HttpSecurityError({ code: HttpSecurityErrorCode.OriginRejected })
     }
 }

package/templates/be/skeleton/src/modules/platform/http-security/persistence/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
+}