@starci/hfs 4.11.15 → 4.11.16

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 4.11.16 - 2026-10-30
+
+- Fixed: the back-end skeleton's `OriginGuard` (`platform/http-security`, BE-AUTH-5) requires an actual allowed `Origin` header on a cookie-bearing mutation (`POST`, `PUT`, `PATCH`, `DELETE` with a `Cookie` header) and on a door or handler marked with the new `RequireOrigin()` (`http-security.decorators.ts`, metadata `REQUIRE_ORIGIN_KEY`), which covers the start of a cookie-authenticated flow before the first cookie exists. A missing, empty, opaque (`null`) or foreign `Origin` is refused with `HTTP_SECURITY_ORIGIN_REJECTED` (403), and an allowed `Referer` no longer stands in for it there; `ServerToServer` does not exempt such a request. Safe methods, and mutations without a cookie on unmarked doors, keep their rules (Referer fallback when Origin is absent, the `ServerToServer` exemption). Spec `origin.guard.spec.ts`: class and handler markers, the first sign-in, cookie-bearing requests and the preserved admission paths, split into describe groups within the function budget.
+- Fixed: the GraphQL platform templates' specs (`templates/be/platform/graphql` `graphql-depth.policy.spec.ts` and `localize-errors.mapper.spec.ts`, `templates/be/platform/errors-graphql` `graphql-error.mapper.spec.ts`), which the first GraphQL feature copies into an app, pass the app canon: each builds its collaborators through a Nest testing module (`spec-builds-with-testing-module`: the `ERRORS_SERVICE` and `REQUEST_LOCALE` doubles, the depth limit), optional fields are typed for `exactOptionalPropertyTypes`, and the plugin describe is split under `function-line-budget`. Assertions are unchanged.
+- Changed: R260 `BE_JWT_ALG_PINNED` (machine `jwt-policy`, `runtime/scripts/hfs/architecture/jwt-ast.mjs`, the copy eslint-canon-be 3.8.15 holds) binds the principal by an audience derived from typed configuration (an OIDC verifier such as the Keycloak client of full, or the lite Passport verifier of the app's own tokens) or, for an issuer-wide literal audience (Supabase-style), by rejecting every role other than authenticated; algorithms and the configured issuer are unchanged. The bundled `rules.yaml` states the law. Spec: `src/architecture-jwt-policy.spec.mjs` (a role-free Keycloak verifier with a configured audience is admitted, one with a literal audience refused, in both editions).
+- Changed: the bundled canon pins name hfs 4.11.16, eslint-canon-be 3.8.15, eslint-canon-fe 9.5.17, the Grammar family 0.15.28 and test-world 1.3.2.
+
 ## 4.11.15 - 2026-10-29
 
 - Added: `platform/database/returned-rows.policy.ts` in the skeleton of both editions, exported from the database barrel: `rowShape({ column: kind })` builds the guard of the rows a RETURNING clause answers (kinds `string`, `number`, `boolean`, `date`, `json`, and `string?`, `number?`, `boolean?`, `date?` that also admit SQL null; a column the statement does not return is refused), and `returnedRows(raw, isRow)` narrows the result of `manager.query` or the `raw` of a query builder's `execute()` to typed rows with no cast. A result that is not a list of rows (the `[rows, count]` of a bare UPDATE included) or a row the guard refuses throws the new `DATABASE_RETURNING_ROW_REJECTED` (internal) of both editions' `DatabaseErrorCode`. The policy spec proves every kind, null, a missing column and both refusals.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.11.15",
+  "version": "4.11.16",
   "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.27
+    version: 0.15.28
     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.14
+    version: 3.8.15
     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.16
+    version: 9.5.17
     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.27
+    version: 0.15.28
     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.27
+    version: 0.15.28
     group: starci
     install: registry
     side: fe
@@ -92,7 +92,7 @@ pins:
     source: packages/jest-preset/package.json
     why: 'the Jest preset of a back end: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: it pairs exactly with @starci/test-world, and any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. The unit run writes the lcov Sonar and Codecov import (services only); the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; it ships the unit kit (mockEntityManager, fakeTransaction, fakeQueryBuilder, queueQueryBuilders, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
   '@starci/test-world':
-    version: 1.3.1
+    version: 1.3.2
     group: starci
     install: registry
     side: be
@@ -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.15
+    version: 4.11.16
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -4346,7 +4346,7 @@ rules:
       - {path: packages/hfs/src/hfs-database-config.spec.mjs, editions: [lite], codes: [DB_EXTENSION_ALLOWED, DB_MIGRATION_DESTRUCTIVE, HFS_SEED_PII, DB_VAULT_WRITE]}
   - id: R260
     code: "BE_JWT_ALG_PINNED"
-    law: "A back-end JWT verifier pins a nonempty literal subset of ES256, RS256 and EdDSA and obtains its issuer from configuration. A principal is built only after verification and rejection of every role other than authenticated, in lite and full."
+    law: "Every back-end JWT verifier pins a nonempty literal subset of ES256, RS256 and EdDSA and obtains its issuer from typed configuration. A principal is built only after verification and is bound either by an audience read from typed configuration (an OIDC verifier such as the Keycloak of full, or the app's own Passport access tokens of lite) or, where every token of the issuer shares one audience (Supabase-style), by rejecting every role other than authenticated first, in lite and full."
     kinds: [check, lint]
     gates: ["pre-commit","settle","land","ci"]
     failureCodes: ["BE_JWT_ALG_PINNED"]

package/runtime/scripts/hfs/architecture/identity.mjs

@@ -140,7 +140,7 @@ function checkOwnJwks(input) {
   return { violations, coverage: { status: 'checked', integrationFiles: integrations.length, verifyCalls: counters.verifyCalls, verifiedCalls: counters.verifiedCalls } };
 }
 
-/** R260 BE_JWT_ALG_PINNED: every jose jwtVerify call pins a literal secure algorithm list, a configured issuer and the authenticated role. */
+/** R260 BE_JWT_ALG_PINNED: every jose jwtVerify call pins a literal secure algorithm list and a configured issuer, and binds the principal by a configured audience or the authenticated role. */
 export function checkJwtPolicy(input) {
   const kit = machineKit(input);
   const violations = [];

package/runtime/scripts/hfs/architecture/jwt-ast.mjs

@@ -61,28 +61,28 @@ const configType = (checker, node) => {
     || /(?:Config|Options|Env)$/u.test(symbol.name)));
 };
 
-/** Trace issuer construction through configuration values and local URL/string transformations. */
-const issuerFromConfig = (ts, checker, expression, seen = new Set()) => {
+/** Trace an issuer or audience to typed configuration values through local URL/string transformations. */
+const fromConfig = (ts, checker, expression, seen = new Set()) => {
   const node = unwrap(ts, expression);
   if (!node || seen.has(node)) return false;
   const next = new Set(seen).add(node);
   if (ts.isIdentifier(node)) {
     return declarationsOf(ts, checker, node).some(declaration => {
-      if (ts.isVariableDeclaration(declaration) && declaration.initializer) return issuerFromConfig(ts, checker, declaration.initializer, next);
+      if (ts.isVariableDeclaration(declaration) && declaration.initializer) return fromConfig(ts, checker, declaration.initializer, next);
       if (ts.isParameter(declaration) || ts.isPropertyDeclaration(declaration)) return configType(checker, node);
       return /(?:\.config|\.env)\.ts$|\/modules\/config\//u.test(String(declaration.getSourceFile().fileName).replaceAll('\\', '/'));
     });
   }
   if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
-    return issuerFromConfig(ts, checker, node.expression, next) || declarationsOf(ts, checker, node).some(declaration =>
+    return fromConfig(ts, checker, node.expression, next) || declarationsOf(ts, checker, node).some(declaration =>
       (ts.isParameter(declaration) || ts.isPropertyDeclaration(declaration)) && !declaration.initializer && configType(checker, node));
   }
-  if (ts.isTemplateExpression(node)) return node.templateSpans.some(span => issuerFromConfig(ts, checker, span.expression, next));
+  if (ts.isTemplateExpression(node)) return node.templateSpans.some(span => fromConfig(ts, checker, span.expression, next));
   if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
-    return issuerFromConfig(ts, checker, node.left, next) || issuerFromConfig(ts, checker, node.right, next);
+    return fromConfig(ts, checker, node.left, next) || fromConfig(ts, checker, node.right, next);
   }
   if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
-    return issuerFromConfig(ts, checker, node.expression, next) || node.arguments?.some(argument => issuerFromConfig(ts, checker, argument, next));
+    return fromConfig(ts, checker, node.expression, next) || node.arguments?.some(argument => fromConfig(ts, checker, argument, next));
   }
   return false;
 };
@@ -201,7 +201,12 @@ export const jwtPolicyProblems = (ts, checker, call) => {
     || options?.properties.some(entry => ts.isSpreadAssignment(entry))) {
     problems.push('BE_JWT_ALG_PINNED: algorithms must be a non-empty literal subset of ES256, RS256 and EdDSA.');
   }
-  if (!issuerFromConfig(ts, checker, value('issuer'))) problems.push('BE_JWT_ALG_PINNED: issuer must derive from typed configuration.');
-  if (!rejectsOtherRoles(ts, checker, call)) problems.push('BE_JWT_ALG_PINNED: the verified principal must reject every role other than authenticated before returning it.');
+  if (!fromConfig(ts, checker, value('issuer'))) problems.push('BE_JWT_ALG_PINNED: issuer must derive from typed configuration.');
+  // The principal is bound either by an audience of typed configuration (an OIDC client such as Keycloak, the app's own
+  // Passport tokens) or, where the audience is shared by every token of the issuer (Supabase's literal 'authenticated'),
+  // by rejecting every role other than authenticated before the principal is returned.
+  if (!fromConfig(ts, checker, value('audience')) && !rejectsOtherRoles(ts, checker, call)) {
+    problems.push('BE_JWT_ALG_PINNED: an OIDC verifier audience must derive from typed configuration, or the verified principal must reject every role other than authenticated before returning it.');
+  }
   return problems;
 };

package/templates/be/platform/errors-graphql/graphql-error.mapper.spec.ts

@@ -1,13 +1,23 @@
+import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 import { GraphQLError } from "graphql"
+import { ERRORS_SERVICE } from "./errors.decorators"
 import type { ErrorsService } from "./errors.service"
 import { formatGraphqlError } from "./graphql-error.mapper"
 
 const formatted = { message: "raw", path: ["item"], locations: [{ line: 1, column: 3 }] }
 
+const build = async () => {
+    const double = mock<ErrorsService>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: ERRORS_SERVICE, useValue: double }],
+    }).compile()
+    return moduleRef.get<typeof double>(ERRORS_SERVICE)
+}
+
 describe("formatGraphqlError", () => {
-    it("keeps the message of a malformed operation and marks it invalid without describing it", () => {
-        const errors = mock<ErrorsService>()
+    it("keeps the message of a malformed operation and marks it invalid without describing it", async () => {
+        const errors = await build()
 
         expect(formatGraphqlError(errors, formatted, new GraphQLError("GRAPHQL_VALIDATION_FAILED"))).toEqual({
             message: "raw",
@@ -18,8 +28,8 @@ describe("formatGraphqlError", () => {
         expect(errors.describe).not.toHaveBeenCalled()
     })
 
-    it("describes the original failure of a resolver and travels its code, kind and params", () => {
-        const errors = mock<ErrorsService>()
+    it("describes the original failure of a resolver and travels its code, kind and params", async () => {
+        const errors = await build()
         const cause = new Error("not found")
         errors.describe.mockReturnValue({
             code: "ITEM_NOT_FOUND",
@@ -37,8 +47,8 @@ describe("formatGraphqlError", () => {
         expect(errors.describe).toHaveBeenCalledWith(cause)
     })
 
-    it("describes a failure that is not a GraphQL error as it is", () => {
-        const errors = mock<ErrorsService>()
+    it("describes a failure that is not a GraphQL error as it is", async () => {
+        const errors = await build()
         const cause = new Error("boom")
         errors.describe.mockReturnValue({ code: "ERRORS_INTERNAL", kind: "internal", status: 500, params: {} })
 
@@ -50,9 +60,9 @@ describe("formatGraphqlError", () => {
         expect(errors.describe).toHaveBeenCalledWith(cause)
     })
 
-    it("leaves out the locations and path a formatted error does not carry", () => {
+    it("leaves out the locations and path a formatted error does not carry", async () => {
         const subject = formatGraphqlError
-        const errors = mock<ErrorsService>()
+        const errors = await build()
         errors.describe.mockReturnValue({ code: "ERRORS_INTERNAL", kind: "internal", status: 500, params: {} })
 
         expect(subject(errors, { message: "raw" }, new GraphQLError("GRAPHQL_PARSE_FAILED"))).toEqual({

package/templates/be/platform/graphql/graphql-depth.policy.spec.ts

@@ -1,3 +1,4 @@
+import { Test } from "@nestjs/testing"
 import { buildSchema, parse, validate } from "graphql"
 import { depthLimitRule } from "./graphql-depth.policy"
 
@@ -12,10 +13,17 @@ const schema = buildSchema(`
     }
 `)
 
-const validateDepth = (source: string, maxDepth = 2) => validate(schema, parse(source), [depthLimitRule(maxDepth)])
+const DEPTH_LIMIT = Symbol("spec.depth-limit")
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({ providers: [{ provide: DEPTH_LIMIT, useValue: 2 }] }).compile()
+    const maxDepth = moduleRef.get<number>(DEPTH_LIMIT)
+    return (source: string) => validate(schema, parse(source), [depthLimitRule(maxDepth)])
+}
 
 describe("depthLimitRule", () => {
-    it("accepts an operation nested exactly to the depth limit", () => {
+    it("accepts an operation nested exactly to the depth limit", async () => {
+        const validateDepth = await build()
         const errors = validateDepth(`
             query {
                 item {
@@ -27,7 +35,8 @@ describe("depthLimitRule", () => {
         expect(errors).toEqual([])
     })
 
-    it("rejects the first selection set deeper than the limit", () => {
+    it("rejects the first selection set deeper than the limit", async () => {
+        const validateDepth = await build()
         const errors = validateDepth(`
             query {
                 item {

package/templates/be/platform/graphql/localize-errors.mapper.spec.ts

@@ -1,12 +1,36 @@
 import type { GraphQLRequestContext, GraphQLRequestContextWillSendResponse, GraphQLResponse } from "@apollo/server"
+import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 import type { Request } from "express"
 import type { GraphQLFormattedError } from "graphql"
+import { ERRORS_SERVICE } from "@modules/platform/errors"
 import type { ErrorsService } from "@modules/platform/errors"
+import { REQUEST_LOCALE } from "@modules/platform/i18n"
 import type { RequestLocale } from "@modules/platform/i18n"
 import type { GraphqlContext } from "./graphql.contracts"
 import { localizeError, localizeErrorsPlugin } from "./localize-errors.mapper"
 
+const build = async () => {
+    const errorsDouble = mock<ErrorsService>()
+    const localeDouble = mock<RequestLocale>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            { provide: ERRORS_SERVICE, useValue: errorsDouble },
+            { provide: REQUEST_LOCALE, useValue: localeDouble },
+        ],
+    }).compile()
+    return {
+        errors: moduleRef.get<typeof errorsDouble>(ERRORS_SERVICE),
+        requestLocale: moduleRef.get<typeof localeDouble>(REQUEST_LOCALE),
+    }
+}
+
+const errorWith = (extensions?: GraphQLFormattedError["extensions"]): GraphQLFormattedError =>
+    extensions === undefined ? { message: "syntax error" } : { message: "syntax error", extensions }
+
+const acceptLanguage = (language?: string): Request["headers"] =>
+    language === undefined ? {} : { "accept-language": language }
+
 const singleResponse = (errors?: ReadonlyArray<GraphQLFormattedError>): GraphQLResponse =>
     mock<GraphQLResponse>({ body: { kind: "single", singleResult: errors === undefined ? {} : { errors } } })
 
@@ -33,17 +57,17 @@ const sendResponse = async (
 describe("localizeError", () => {
     it.each([undefined, {}, { code: 400 }, { code: null }, { code: false }])(
         "returns an error without a string code unchanged (%p)",
-        (extensions) => {
-            const errors = mock<ErrorsService>()
-            const error: GraphQLFormattedError = { message: "syntax error", extensions }
+        async (extensions) => {
+            const { errors } = await build()
+            const error = errorWith(extensions)
 
             expect(localizeError(errors, "en", error)).toBe(error)
             expect(errors.text).not.toHaveBeenCalled()
         },
     )
 
-    it("replaces a coded error's message with the catalog text and keeps only string and number params", () => {
-        const errors = mock<ErrorsService>()
+    it("replaces a coded error's message with the catalog text and keeps only string and number params", async () => {
+        const { errors } = await build()
         errors.text.mockReturnValue("The item was not found")
         const error: GraphQLFormattedError = {
             message: "ITEM_NOT_FOUND",
@@ -67,8 +91,8 @@ describe("localizeError", () => {
 
     it.each([undefined, null, ["i-1"], "i-1", 42, false])(
         "interpolates no params when extensions.params is %p",
-        (params) => {
-            const errors = mock<ErrorsService>()
+        async (params) => {
+            const { errors } = await build()
             errors.text.mockReturnValue("The item was not found")
             const error: GraphQLFormattedError = {
                 message: "ITEM_NOT_FOUND",
@@ -83,8 +107,7 @@ describe("localizeError", () => {
 
 describe("localizeErrorsPlugin", () => {
     it("forwards the Accept-Language preferences and localizes every coded error in the resolved locale", async () => {
-        const errors = mock<ErrorsService>()
-        const requestLocale = mock<RequestLocale>()
+        const { errors, requestLocale } = await build()
         requestLocale.of.mockReturnValue("vi")
         errors.text.mockReturnValueOnce("localized: not found").mockReturnValueOnce("localized: denied")
         const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
@@ -115,15 +138,14 @@ describe("localizeErrorsPlugin", () => {
     it.each([undefined, ""])(
         "delegates an absent or empty Accept-Language header to the locale default (%p)",
         async (language) => {
-            const errors = mock<ErrorsService>()
-            const requestLocale = mock<RequestLocale>()
+            const { errors, requestLocale } = await build()
             requestLocale.of.mockReturnValue("vi")
             errors.text.mockReturnValue("localized: not found")
             const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
 
             const response = singleResponse([coded])
 
-            await sendResponse(errors, requestLocale, requestContext(response, { "accept-language": language }))
+            await sendResponse(errors, requestLocale, requestContext(response, acceptLanguage(language)))
 
             expect(requestLocale.of).toHaveBeenCalledWith(language)
             expect(errors.text).toHaveBeenCalledWith("ITEM_NOT_FOUND", {}, "vi")
@@ -132,10 +154,11 @@ describe("localizeErrorsPlugin", () => {
             ])
         },
     )
+})
 
+describe("localizeErrorsPlugin on a response with nothing to localize", () => {
     it("leaves a response without errors alone", async () => {
-        const errors = mock<ErrorsService>()
-        const requestLocale = mock<RequestLocale>()
+        const { errors, requestLocale } = await build()
 
         const response = singleResponse()
         const body = response.body
@@ -149,14 +172,13 @@ describe("localizeErrorsPlugin", () => {
     })
 
     it("leaves an incremental response alone", async () => {
-        const errors = mock<ErrorsService>()
-        const requestLocale = mock<RequestLocale>()
+        const { errors, requestLocale } = await build()
         const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
         const response = mock<GraphQLResponse>({
             body: {
                 kind: "incremental",
                 initialResult: { errors: [coded], hasNext: true },
-                subsequentResults: mock<AsyncGenerator>(),
+                subsequentResults: mock<AsyncIterable<never>>(),
             },
         })
         const body = response.body

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

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

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

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

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

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