@starci/hfs 4.2.17 → 4.4.0

package/templates/be/skeleton/src/modules/domain/identity/identity.options.ts

@@ -1,2 +1,8 @@
-/** The identity capability takes no options yet; the empty record keeps `isGlobal` assignable through the configurable module. */
-export type IdentityOptions = Record<never, never>
+import type { Type } from "@nestjs/common"
+import type { CredentialAuthenticator } from "./credential.contracts"
+
+/** The identity capability's options. */
+export interface IdentityOptions {
+    /** The app-owned authenticator of alternate credentials; a credential door fails closed while it is absent. */
+    readonly credentialAuthenticator?: Type<CredentialAuthenticator>
+}

package/templates/be/skeleton/src/modules/domain/identity/index.ts

@@ -1,4 +1,5 @@
 export { AuthGuard } from "./auth.guard"
+export { CredentialGuard } from "./credential.guard"
 export { IDENTITY_ERROR_KINDS } from "./errors/identity.error"
 export { IDENTITY_MESSAGES } from "./messages/identity.messages"
 export { PublicReason } from "./identity.contracts"

package/templates/be/skeleton/src/modules/platform/config/env-source.config.ts

@@ -21,18 +21,18 @@ export class Secret {
 }
 
 /**
- * The only reader of the process environment. Typed readers name the missing or malformed key in the error; a key
- * `<KEY>_FILE` supplies `<KEY>` from a file, so secrets can be mounted instead of exported.
+ * The only reader of the process environment. Typed readers name the missing or malformed key in the error.
+ * A declared `<KEY>_FILE` takes priority over `<KEY>` and supplies its exact file contents, so secrets can be mounted.
  */
 export class EnvSource {
     constructor(private readonly values: Readonly<Record<string, string | undefined>>) {}
 
-    /** Reads the process environment once, resolving every `<KEY>_FILE` into `<KEY>`. */
+    /** Reads the process environment once; a declared `<KEY>_FILE` must be readable and never falls back to `<KEY>`. */
     static fromProcess(): EnvSource {
         const values: Record<string, string | undefined> = { ...process.env }
-        for (const [key, path] of Object.entries(process.env)) {
-            if (key.endsWith(FILE_SUFFIX) && path)
-                values[key.slice(0, -FILE_SUFFIX.length)] = readFileSync(path, "utf8").trim()
+        for (const [key, path] of Object.entries(values)) {
+            if (key.endsWith(FILE_SUFFIX) && path !== undefined)
+                values[key.slice(0, -FILE_SUFFIX.length)] = readFileSync(path, "utf8")
         }
         return new EnvSource(values)
     }

package/templates/be/skeleton/src/modules/platform/database/connection-source.client.spec.ts

@@ -1,7 +1,10 @@
+import { Test } from "@nestjs/testing"
 import type { QueryRunner } from "typeorm"
 import { Secret } from "@modules/platform/config"
 import type { DatabaseConnectionOptions } from "./database.options"
 import { openConnectionSource } from "./connection-source.client"
+import { CONNECTION_SOURCE } from "./database.port"
+import type { ConnectionOpener } from "./database.port"
 
 class NoteEntity {}
 
@@ -16,20 +19,24 @@ class CreateNotes {
 }
 
 describe("openConnectionSource", () => {
-    it("opens an isolated PostgreSQL data source with the connection's entities and migrations", () => {
+    it("opens an isolated PostgreSQL data source with the connection's entities and migrations", async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [{ provide: CONNECTION_SOURCE, useFactory: () => ({ open: openConnectionSource }) }],
+        }).compile()
+        const client = moduleRef.get<ConnectionOpener>(CONNECTION_SOURCE)
         const connection: DatabaseConnectionOptions = {
             name: "primary",
-            url: new Secret("postgres://user:password@database.test:5432/primary"),
+            url: new Secret("postgres://database.test:5432/primary"),
             entities: [NoteEntity],
             migrations: [CreateNotes],
         }
 
-        const source = openConnectionSource(connection)
+        const source = client.open(connection)
 
         expect(source).toMatchObject({
             options: {
                 type: "postgres",
-                url: "postgres://user:password@database.test:5432/primary",
+                url: "postgres://database.test:5432/primary",
                 entities: [NoteEntity],
                 migrations: [CreateNotes],
                 migrationsTableName: "primary_migrations",

package/templates/be/skeleton/src/modules/platform/database/database-probe.service.spec.ts

@@ -0,0 +1,32 @@
+import { Test } from "@nestjs/testing"
+import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { DatabaseProbeService } from "./database-probe.service"
+import { PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
+
+const build = async (entityManager: MockEntityManager) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [DatabaseProbeService, { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager }],
+    }).compile()
+    return moduleRef.get(DatabaseProbeService)
+}
+
+describe("DatabaseProbeService", () => {
+    it("opens and commits a transaction against the required database", async () => {
+        const transaction = fakeTransaction(mockEntityManager())
+        const service = await build(transaction.em)
+
+        await expect(service.probe()).resolves.toBeUndefined()
+
+        expect(transaction.em.transaction).toHaveBeenCalledTimes(1)
+        expect(transaction.commits).toBe(1)
+    })
+
+    it("propagates a failed database transaction", async () => {
+        const entityManager = mockEntityManager()
+        entityManager.transaction.mockRejectedValue(new Error("connection unavailable"))
+        const service = await build(entityManager)
+
+        await expect(service.probe()).rejects.toThrow("connection unavailable")
+    })
+})

package/templates/be/skeleton/src/modules/platform/database/database-probe.service.ts

@@ -0,0 +1,14 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { InjectPrimaryEntityManager } from "./primary.decorators"
+
+@Injectable()
+/** Checks that the required primary database accepts and commits a transaction. */
+export class DatabaseProbeService {
+    constructor(@InjectPrimaryEntityManager() private readonly entityManager: EntityManager) {}
+
+    /** Reaches the database and fails when its transaction cannot complete. */
+    async probe(): Promise<void> {
+        await this.entityManager.transaction(() => Promise.resolve(undefined))
+    }
+}

package/templates/be/skeleton/src/modules/platform/database/database.module.ts

@@ -2,6 +2,7 @@ import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { TypeOrmModule, getDataSourceToken } from "@nestjs/typeorm"
 import type { DataSource } from "typeorm"
+import { DatabaseProbeService } from "./database-probe.service"
 import { openConnectionSource } from "./connection-source.client"
 import { CONNECTION_SOURCE, DATABASE_OPTIONS, READ_SEED_FILES } from "./database.port"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./database.module-definition"
@@ -9,7 +10,7 @@ import { MigrationRunnerService } from "./migration-runner.service"
 import { readSeedFiles } from "./seed-connections.client"
 import { SeedRunnerService } from "./seed-runner.service"
 import { PRIMARY_CONNECTION } from "./primary.connection"
-import { PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
+import { DATABASE_PROBE, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 
 /** The token each declared connection provides its shared EntityManager under. */
 type EntityManagerToken = typeof PRIMARY_ENTITY_MANAGER
@@ -39,6 +40,9 @@ export class DatabaseModule extends ConfigurableModuleClass {
                       },
                   ]
         })
+        const probes = options.connections.some((connection) => connection.name === PRIMARY_CONNECTION)
+            ? [{ provide: DATABASE_PROBE, useClass: DatabaseProbeService }]
+            : []
         return {
             ...base,
             imports: [
@@ -59,6 +63,7 @@ export class DatabaseModule extends ConfigurableModuleClass {
                 ...managers,
                 MigrationRunnerService,
                 SeedRunnerService,
+                ...probes,
                 {
                     provide: CONNECTION_SOURCE,
                     useValue: { open: openConnectionSource },
@@ -70,6 +75,7 @@ export class DatabaseModule extends ConfigurableModuleClass {
                 CONNECTION_SOURCE,
                 MigrationRunnerService,
                 SeedRunnerService,
+                ...probes.map((probe) => probe.provide),
                 ...managers.map((manager) => manager.provide),
             ],
         }

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

@@ -1,4 +1,6 @@
 export { DatabaseModule } from "./database.module"
+export { DATABASE_PROBE, InjectDatabaseProbe } from "./primary.decorators"
+export { DatabaseProbeService } from "./database-probe.service"
 export { MigrationRunnerService } from "./migration-runner.service"
 export { DEFAULT_SEED_ENV } from "./seed-connections.client"
 export { SeedRunnerService } from "./seed-runner.service"

package/templates/be/skeleton/src/modules/platform/database/primary.decorators.ts

@@ -1,6 +1,7 @@
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
 import type { EntityManager } from "typeorm"
+import type { DatabaseProbeService } from "./database-probe.service"
 
 /** Token of the shared EntityManager of the `primary` database; the database module provides it for the connection it opens. */
 export const PRIMARY_ENTITY_MANAGER: unique symbol = Symbol("platform.database.primary-entity-manager")
@@ -8,3 +9,10 @@ export const PRIMARY_ENTITY_MANAGER: unique symbol = Symbol("platform.database.p
 /** Injects the shared EntityManager of the `primary` database. Parameter type: EntityManager. */
 export const InjectPrimaryEntityManager = (): TypedParameterDecorator<EntityManager> =>
     injector<EntityManager>(PRIMARY_ENTITY_MANAGER)
+
+/** The required primary database connectivity probe provided by the database capability. */
+export const DATABASE_PROBE: unique symbol = Symbol("platform.database.probe")
+
+/** Injects the primary database connectivity probe. Parameter type: DatabaseProbeService. */
+export const InjectDatabaseProbe = (): TypedParameterDecorator<DatabaseProbeService> =>
+    injector<DatabaseProbeService>(DATABASE_PROBE)

package/templates/be/skeleton/src/modules/platform/database/seed-connections.client.spec.ts

@@ -1,6 +1,7 @@
 import { mkdtemp, rm, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
+import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 import { Secret } from "@modules/platform/config"
 import type { DatabaseConnectionOptions } from "./database.options"
@@ -9,6 +10,19 @@ import { seedText } from "./database.sql"
 import { readSeedFiles, seedConnections, seedDirectoryOf } from "./seed-connections.client"
 import type { SeedFile } from "./seed-connections.client"
 
+const SEED_CLIENT = Symbol("seed-connections")
+
+const setup = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: SEED_CLIENT, useFactory: () => ({ readSeedFiles, seedConnections, seedDirectoryOf }) }],
+    }).compile()
+    return moduleRef.get<{
+        readonly readSeedFiles: typeof readSeedFiles
+        readonly seedConnections: typeof seedConnections
+        readonly seedDirectoryOf: typeof seedDirectoryOf
+    }>(SEED_CLIENT)
+}
+
 const connection = (name: string): DatabaseConnectionOptions => ({
     name,
     url: new Secret(`postgres://localhost:5432/${name}`),
@@ -22,13 +36,15 @@ const file = (name: string, text: string): SeedFile => ({
 })
 
 describe("seedDirectoryOf", () => {
-    it("is the seeds folder of the environment under .starcistacks, relative to the app root", () => {
-        expect(seedDirectoryOf("dev")).toBe(join(".starcistacks", "dev", "seeds"))
+    it("is the seeds folder of the environment under .starcistacks, relative to the app root", async () => {
+        const client = await setup()
+        expect(client.seedDirectoryOf("dev")).toBe(join(".starcistacks", "dev", "seeds"))
     })
 })
 
 describe("seedConnections", () => {
     it("runs the files of each connection in the given order and never opens a connection without a file", async () => {
+        const client = await setup()
         const primary = mock<ConnectionSource>()
         const archive = mock<ConnectionSource>()
         const sources = new Map([
@@ -40,7 +56,7 @@ describe("seedConnections", () => {
             (target: DatabaseConnectionOptions) => sources.get(target.name) ?? mock<ConnectionSource>(),
         )
 
-        const report = await seedConnections(
+        const report = await client.seedConnections(
             [connection("primary"), connection("archive")],
             [file("primary-a.sql", "SELECT 1"), file("primary-b.sql", "SELECT 2")],
             opener,
@@ -57,9 +73,10 @@ describe("seedConnections", () => {
     })
 
     it("answers the files that name no connection as unmatched", async () => {
+        const client = await setup()
         const opener = mock<ConnectionOpener>()
 
-        const report = await seedConnections(
+        const report = await client.seedConnections(
             [connection("primary")],
             [file("legacy-users.sql", "INSERT INTO users DEFAULT VALUES")],
             opener,
@@ -70,13 +87,14 @@ describe("seedConnections", () => {
     })
 
     it("destroys the data source of a connection whose seed fails, and fails", async () => {
+        const client = await setup()
         const failing = mock<ConnectionSource>()
         failing.query.mockRejectedValue(new TypeError("relation does not exist"))
         const opener = mock<ConnectionOpener>()
         opener.open.mockReturnValue(failing)
 
         await expect(
-            seedConnections([connection("primary")], [file("primary-a.sql", "SELECT 1")], opener),
+            client.seedConnections([connection("primary")], [file("primary-a.sql", "SELECT 1")], opener),
         ).rejects.toThrow("relation does not exist")
         expect(failing.destroy).toHaveBeenCalledTimes(1)
     })
@@ -94,11 +112,12 @@ describe("readSeedFiles", () => {
     })
 
     it("answers every sql file of the directory sorted by name with its statements, and nothing else", async () => {
+        const client = await setup()
         await writeFile(join(directory, "primary-b.sql"), "SELECT 2")
         await writeFile(join(directory, "primary-a.sql"), "SELECT 1")
         await writeFile(join(directory, "README.md"), "not a seed")
 
-        const files = await readSeedFiles(directory)
+        const files = await client.readSeedFiles(directory)
 
         expect(files).toEqual([
             { name: "primary-a.sql", text: "SELECT 1" },

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

@@ -1,19 +1,29 @@
 import type { ArgumentsHost } from "@nestjs/common"
+import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 import type { Request, Response } from "express"
+import { REQUEST_LOCALE } from "@modules/platform/i18n"
 import type { RequestLocale } from "@modules/platform/i18n"
+import { ERRORS_SERVICE } from "./errors.decorators"
 import { ErrorsFilter } from "./errors.filter"
 import type { ErrorsService } from "./errors.service"
 
-const build = () => {
+const build = async () => {
     const errors = mock<ErrorsService>()
     const requestLocale = mock<RequestLocale>()
-    return { filter: new ErrorsFilter(errors, requestLocale), errors, requestLocale }
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            ErrorsFilter,
+            { provide: ERRORS_SERVICE, useValue: errors },
+            { provide: REQUEST_LOCALE, useValue: requestLocale },
+        ],
+    }).compile()
+    return { filter: moduleRef.get(ErrorsFilter), errors, requestLocale }
 }
 
 describe("ErrorsFilter", () => {
-    it("hands a failure in a GraphQL context back untouched for the GraphQL error formatter", () => {
-        const { filter, errors } = build()
+    it("hands a failure in a GraphQL context back untouched for the GraphQL error formatter", async () => {
+        const { filter, errors } = await build()
         const failure = new Error("resolver failed")
         const host = mock<ArgumentsHost>()
         host.getType.mockReturnValue("graphql")
@@ -23,8 +33,8 @@ describe("ErrorsFilter", () => {
         expect(host.switchToHttp).not.toHaveBeenCalled()
     })
 
-    it("writes a localized description and its status to an HTTP response", () => {
-        const { filter, errors, requestLocale } = build()
+    it("writes a localized description and its status to an HTTP response", async () => {
+        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>()

package/templates/be/skeleton/src/modules/platform/http-security/edge-security.service.spec.ts

@@ -0,0 +1,130 @@
+import type { INestApplication } from "@nestjs/common"
+import { Test } from "@nestjs/testing"
+import type { Express, NextFunction, Request, Response } from "express"
+import { mock } from "@starci/jest-preset"
+import { applyHttpSecurity, securityHeaders, validateAllowedOrigins } from "./edge-security.service"
+import type { HttpSecurityOptions } from "./http-security.options"
+
+const HTTP_EDGE = Symbol("HTTP_EDGE")
+
+const buildEdge = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: HTTP_EDGE, useValue: { applyHttpSecurity, securityHeaders, validateAllowedOrigins } }],
+    }).compile()
+    return moduleRef.get<typeof import("./edge-security.service")>(HTTP_EDGE)
+}
+
+const options: HttpSecurityOptions = {
+    allowedOrigins: ["https://web.example"],
+    rateLimit: { windowMs: 1, defaultLimit: 1, strictLimit: 1 },
+    webhooks: {},
+}
+
+const appWithServer = () => {
+    const server = mock<Express>()
+    const adapter = mock<ReturnType<INestApplication["getHttpAdapter"]>>()
+    adapter.getInstance.mockReturnValue(server)
+    const app = mock<INestApplication>()
+    app.getHttpAdapter.mockReturnValue(adapter)
+    return { app, server }
+}
+
+describe("HTTP edge origin validation", () => {
+    it("keeps exact HTTPS origins and admits HTTP only when explicitly enabled", async () => {
+        const edge = await buildEdge()
+        expect(edge.validateAllowedOrigins(["https://web.example", "https://admin.example:8443"], false)).toEqual([
+            "https://web.example",
+            "https://admin.example:8443",
+        ])
+        expect(edge.validateAllowedOrigins(["http://localhost:3000"], true)).toEqual(["http://localhost:3000"])
+    })
+
+    it.each([
+        "*",
+        "https://*.example",
+        "https://web.example/",
+        "https://web.example/path",
+        "https://user:pass@web.example",
+        "https://web.example?query=1",
+        "https://web.example#hash",
+        "not-an-origin",
+        "",
+        "ftp://web.example",
+    ])("rejects wildcard, malformed and non-origin allowlist entry %s at boot", async (origin) => {
+        const edge = await buildEdge()
+        expect(() => edge.validateAllowedOrigins([origin], true)).toThrow(
+            expect.objectContaining({ code: "HTTP_SECURITY_REQUEST_INVALID" }),
+        )
+    })
+
+    it("rejects an empty allowlist and HTTP origins without development permission", async () => {
+        const edge = await buildEdge()
+        expect(() => edge.validateAllowedOrigins([], false)).toThrow(
+            expect.objectContaining({ code: "HTTP_SECURITY_REQUEST_INVALID" }),
+        )
+        expect(() => edge.validateAllowedOrigins(["http://web.example"], false)).toThrow(
+            expect.objectContaining({ code: "HTTP_SECURITY_REQUEST_INVALID" }),
+        )
+    })
+})
+
+describe("HTTP edge installation", () => {
+    it("sets every API security header and continues the request", async () => {
+        const edge = await buildEdge()
+        const response = mock<Response>()
+        const next: jest.MockedFunction<NextFunction> = jest.fn()
+        edge.securityHeaders(mock<Request>(), response, next)
+        expect(response.setHeader.mock.calls).toEqual([
+            ["Strict-Transport-Security", "max-age=31536000; includeSubDomains"],
+            ["X-Content-Type-Options", "nosniff"],
+            ["X-Frame-Options", "DENY"],
+            ["Referrer-Policy", "no-referrer"],
+            ["Content-Security-Policy", "default-src 'none'; base-uri 'none'; frame-ancestors 'none'"],
+        ])
+        expect(next).toHaveBeenCalledTimes(1)
+    })
+
+    it("installs headers before CORS, removes x-powered-by and trusts the declared ingress hop count", async () => {
+        const edge = await buildEdge()
+        const { app, server } = appWithServer()
+        edge.applyHttpSecurity(app, { ...options, allowHttpOrigins: false }, { trustProxy: 1 })
+        expect(server.disable).toHaveBeenCalledWith("x-powered-by")
+        expect(server.set).toHaveBeenCalledWith("trust proxy", 1)
+        expect(app.use).toHaveBeenCalledWith(edge.securityHeaders)
+        expect(app.enableCors).toHaveBeenCalledWith({ origin: ["https://web.example"] })
+        expect(app.use.mock.invocationCallOrder[0]).toBeLessThan(app.enableCors.mock.invocationCallOrder[0] ?? 0)
+    })
+
+    it("defaults manually supplied options to HTTPS and accepts explicit zero proxy hops", async () => {
+        const edge = await buildEdge()
+        const { app, server } = appWithServer()
+        edge.applyHttpSecurity(app, options, { trustProxy: 0 })
+        expect(server.set).toHaveBeenCalledWith("trust proxy", 0)
+        expect(() =>
+            edge.applyHttpSecurity(app, { ...options, allowedOrigins: ["http://web.example"] }, { trustProxy: 1 }),
+        ).toThrow()
+    })
+
+    it("admits development HTTP origins when explicitly enabled", async () => {
+        const edge = await buildEdge()
+        const { app } = appWithServer()
+        edge.applyHttpSecurity(
+            app,
+            { ...options, allowedOrigins: ["http://localhost:3000"], allowHttpOrigins: true },
+            { trustProxy: 1 },
+        )
+        expect(app.enableCors).toHaveBeenCalledWith({ origin: ["http://localhost:3000"] })
+    })
+
+    it.each([-1, 0.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1])(
+        "rejects unsafe proxy hop count %s",
+        async (trustProxy) => {
+            const edge = await buildEdge()
+            const { app } = appWithServer()
+            expect(() => edge.applyHttpSecurity(app, options, { trustProxy })).toThrow(
+                expect.objectContaining({ code: "HTTP_SECURITY_REQUEST_INVALID" }),
+            )
+            expect(app.enableCors).not.toHaveBeenCalled()
+        },
+    )
+})

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

@@ -0,0 +1,58 @@
+import type { INestApplication } from "@nestjs/common"
+import type { Express, RequestHandler } from "express"
+import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
+import type { HttpSecurityOptions } from "./http-security.options"
+
+/** The declared ingress hop count and the environment in which HTTP origins may be used. */
+export interface HttpEdgeOptions {
+    /** Exact trusted proxy hops; the standard API stack has one ingress in front of it. */
+    readonly trustProxy: number
+}
+
+/** Validates exact browser origins at boot, before CORS can admit a request. */
+export const validateAllowedOrigins = (origins: ReadonlyArray<string>, allowHttpOrigins: boolean): Array<string> => {
+    if (origins.length === 0)
+        throw new HttpSecurityError({
+            code: HttpSecurityErrorCode.RequestInvalid,
+            params: { fields: "HTTP_SECURITY_ALLOWED_ORIGINS" },
+        })
+    return origins.map((origin) => {
+        const parsed = URL.canParse(origin) ? new URL(origin) : undefined
+        if (
+            parsed === undefined ||
+            origin.includes("*") ||
+            parsed.origin !== origin ||
+            (parsed.protocol !== "https:" && !(allowHttpOrigins && parsed.protocol === "http:"))
+        )
+            throw new HttpSecurityError({
+                code: HttpSecurityErrorCode.RequestInvalid,
+                params: { fields: "HTTP_SECURITY_ALLOWED_ORIGINS" },
+            })
+        return origin
+    })
+}
+
+/** Security headers of the API's data and probe responses, including errors. */
+export const securityHeaders: RequestHandler = (_request, response, next) => {
+    response.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
+    response.setHeader("X-Content-Type-Options", "nosniff")
+    response.setHeader("X-Frame-Options", "DENY")
+    response.setHeader("Referrer-Policy", "no-referrer")
+    response.setHeader("Content-Security-Policy", "default-src 'none'; base-uri 'none'; frame-ancestors 'none'")
+    next()
+}
+
+/** Installs the API edge policy once: validated CORS, security headers and a declared numeric ingress hop count. */
+export const applyHttpSecurity = (app: INestApplication, options: HttpSecurityOptions, edge: HttpEdgeOptions): void => {
+    const origins = validateAllowedOrigins(options.allowedOrigins, options.allowHttpOrigins === true)
+    if (!Number.isSafeInteger(edge.trustProxy) || edge.trustProxy < 0)
+        throw new HttpSecurityError({
+            code: HttpSecurityErrorCode.RequestInvalid,
+            params: { fields: "HTTP_SECURITY_TRUST_PROXY" },
+        })
+    const server: Express = app.getHttpAdapter().getInstance()
+    server.disable("x-powered-by")
+    server.set("trust proxy", edge.trustProxy)
+    app.use(securityHeaders)
+    app.enableCors({ origin: origins })
+}

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

@@ -3,6 +3,8 @@ import type { ErrorKind } from "@modules/platform/errors"
 
 /** Codes of the http-security capability. */
 export enum HttpSecurityErrorCode {
+    /** The required primary database failed or did not answer before the readiness deadline. */
+    RequiredDependencyUnavailable = "HTTP_SECURITY_REQUIRED_DEPENDENCY_UNAVAILABLE",
     /** A state-changing request came from an origin that is not on the allowlist. */
     OriginRejected = "HTTP_SECURITY_ORIGIN_REJECTED",
     /** The caller sent more requests than its tier allows in the current window. */
@@ -19,6 +21,7 @@ export enum HttpSecurityErrorCode {
 
 /** How each http-security code travels. */
 export const HTTP_SECURITY_ERROR_KINDS: Record<HttpSecurityErrorCode, ErrorKind> = {
+    [HttpSecurityErrorCode.RequiredDependencyUnavailable]: "unavailable",
     [HttpSecurityErrorCode.OriginRejected]: "forbidden",
     [HttpSecurityErrorCode.RateLimited]: "rate-limited",
     [HttpSecurityErrorCode.RequestInvalid]: "invalid",

package/templates/be/skeleton/src/modules/platform/http-security/execution-request.mapper.spec.ts

@@ -1,10 +1,21 @@
 import type { ExecutionContext } from "@nestjs/common"
 import type { Request } from "express"
+import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 import { requestOf } from "./execution-request.mapper"
 
+const REQUEST_MAPPER = Symbol("REQUEST_MAPPER")
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: REQUEST_MAPPER, useValue: requestOf }],
+    }).compile()
+    return moduleRef.get<typeof requestOf>(REQUEST_MAPPER)
+}
+
 describe("requestOf", () => {
-    it("reads the HTTP request behind an HTTP execution context", () => {
+    it("reads the HTTP request behind an HTTP execution context", async () => {
+        const mapRequest = await build()
         const request = mock<Request>()
         const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
         http.getRequest.mockReturnValue(request)
@@ -12,17 +23,18 @@ describe("requestOf", () => {
         context.getType.mockReturnValue("http")
         context.switchToHttp.mockReturnValue(http)
 
-        expect(requestOf(context)).toBe(request)
+        expect(mapRequest(context)).toBe(request)
         expect(context.getArgs).not.toHaveBeenCalled()
     })
 
-    it("reads the request of the GraphQL context behind a resolver's execution context", () => {
+    it("reads the request of the GraphQL context behind a resolver's execution context", async () => {
+        const mapRequest = await build()
         const request = mock<Request>()
         const context = mock<ExecutionContext>()
         context.getType.mockReturnValue("graphql")
         context.getArgs.mockReturnValue([undefined, {}, { req: request }, undefined])
 
-        expect(requestOf(context)).toBe(request)
+        expect(mapRequest(context)).toBe(request)
         expect(context.switchToHttp).not.toHaveBeenCalled()
     })
 })

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

@@ -1,5 +1,6 @@
 import type { EnvSource } from "@modules/platform/config"
 import type { HttpSecurityOptions, WebhookProviderOptions } from "./http-security.options"
+import { validateAllowedOrigins } from "./edge-security.service"
 
 /** Reads one webhook provider's required signing secret and bounded replay window. */
 export const parseWebhookProviderConfig = (env: EnvSource, prefix: string): WebhookProviderOptions => ({
@@ -8,16 +9,21 @@ export const parseWebhookProviderConfig = (env: EnvSource, prefix: string): Webh
 })
 
 /** Reads the http-security options: the origin allowlist is required, the rate limits are tunables with literal defaults. */
-export const parseHttpSecurityConfig = (env: EnvSource): HttpSecurityOptions => ({
-    allowedOrigins: env
+export const parseHttpSecurityConfig = (env: EnvSource): HttpSecurityOptions => {
+    const mode = env.optional("NODE_ENV") ?? "development"
+    const allowHttpOrigins = mode === "development" || mode === "test"
+    const origins = env
         .string("HTTP_SECURITY_ALLOWED_ORIGINS")
         .split(",")
         .map((origin) => origin.trim())
-        .filter(Boolean),
-    rateLimit: {
-        windowMs: env.duration("HTTP_SECURITY_RATE_WINDOW", 60_000),
-        defaultLimit: env.int("HTTP_SECURITY_RATE_DEFAULT_LIMIT", 600),
-        strictLimit: env.int("HTTP_SECURITY_RATE_STRICT_LIMIT", 30),
-    },
-    webhooks: {},
-})
+    return {
+        allowedOrigins: validateAllowedOrigins(origins, allowHttpOrigins),
+        allowHttpOrigins,
+        rateLimit: {
+            windowMs: env.duration("HTTP_SECURITY_RATE_WINDOW", 60_000),
+            defaultLimit: env.int("HTTP_SECURITY_RATE_DEFAULT_LIMIT", 600),
+            strictLimit: env.int("HTTP_SECURITY_RATE_STRICT_LIMIT", 30),
+        },
+        webhooks: {},
+    }
+}