@starci/hfs 4.3.0 → 4.4.0

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: {},
+    }
+}

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

@@ -3,6 +3,7 @@ import type { DynamicModule } from "@nestjs/common"
 import { APP_PIPE } from "@nestjs/core"
 import { WEBHOOK_SIGNATURE } from "./http-security.decorators"
 import { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } from "./http-security.module-definition"
+import { ReadinessService } from "./readiness.service"
 import { RequestValidationService } from "./request-validation.service"
 import { WebhookSignatureService } from "./webhook-signature.service"
 
@@ -18,9 +19,10 @@ export class HttpSecurityModule extends ConfigurableModuleClass {
                 ...(base.providers ?? []),
                 { provide: APP_PIPE, useClass: RequestValidationService },
                 WebhookSignatureService,
+                ReadinessService,
                 { provide: WEBHOOK_SIGNATURE, useExisting: WebhookSignatureService },
             ],
-            exports: [MODULE_OPTIONS_TOKEN, WebhookSignatureService, WEBHOOK_SIGNATURE],
+            exports: [MODULE_OPTIONS_TOKEN, WebhookSignatureService, WEBHOOK_SIGNATURE, ReadinessService],
         }
     }
 }

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

@@ -22,6 +22,8 @@ export interface WebhookProviderOptions {
 export interface HttpSecurityOptions {
     /** The origins allowed to send state-changing requests from a browser. */
     readonly allowedOrigins: ReadonlyArray<string>
+    /** Plain HTTP origins are admitted only by a development or test environment reader. */
+    readonly allowHttpOrigins?: boolean
     /** The rate limit tiers. */
     readonly rateLimit: RateLimitOptions
     /** Signed-webhook providers keyed by their generated route name. */

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

@@ -4,4 +4,9 @@ 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 { requestOf } from "./execution-request.mapper"
 export { RateLimitGuard } from "./rate-limit.guard"
+export { applyHttpSecurity } from "./edge-security.service"
+export { ReadinessService } from "./readiness.service"
+export { InjectReadiness } from "./readiness.decorators"
+export type { ReadinessReport } from "./readiness.contracts"

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

@@ -3,14 +3,21 @@ import type { MessageBundle } from "@modules/platform/i18n"
 /** Display text of the http-security codes, Vietnamese and English. */
 export const HTTP_SECURITY_MESSAGES: MessageBundle = {
     vi: {
-        "errors.HTTP_SECURITY_ORIGIN_REJECTED": "Ngu\u1ed3n g\u1eedi y\u00eau c\u1ea7u kh\u00f4ng \u0111\u01b0\u1ee3c ph\u00e9p.",
-        "errors.HTTP_SECURITY_RATE_LIMITED": "B\u1ea1n g\u1eedi qu\u00e1 nhi\u1ec1u y\u00eau c\u1ea7u, h\u00e3y th\u1eed l\u1ea1i sau.",
-        "errors.HTTP_SECURITY_REQUEST_INVALID": "D\u1eef li\u1ec7u g\u1eedi l\u00ean kh\u00f4ng h\u1ee3p l\u1ec7: {{fields}}.",
+        "errors.HTTP_SECURITY_REQUIRED_DEPENDENCY_UNAVAILABLE": "C\u01a1 s\u1edf d\u1eef li\u1ec7u b\u1eaft bu\u1ed9c hi\u1ec7n kh\u00f4ng kh\u1ea3 d\u1ee5ng.",
+        "errors.HTTP_SECURITY_ORIGIN_REJECTED":
+            "Ngu\u1ed3n g\u1eedi y\u00eau c\u1ea7u kh\u00f4ng \u0111\u01b0\u1ee3c ph\u00e9p.",
+        "errors.HTTP_SECURITY_RATE_LIMITED":
+            "B\u1ea1n g\u1eedi qu\u00e1 nhi\u1ec1u y\u00eau c\u1ea7u, h\u00e3y th\u1eed l\u1ea1i sau.",
+        "errors.HTTP_SECURITY_REQUEST_INVALID":
+            "D\u1eef li\u1ec7u g\u1eedi l\u00ean kh\u00f4ng h\u1ee3p l\u1ec7: {{fields}}.",
         "errors.HTTP_SECURITY_WEBHOOK_SIGNATURE_INVALID": "Ch\u1eef k\u00fd webhook kh\u00f4ng h\u1ee3p l\u1ec7.",
-        "errors.HTTP_SECURITY_WEBHOOK_REPLAYED": "Webhook n\u1eb1m ngo\u00e0i c\u1eeda s\u1ed5 th\u1eddi gian cho ph\u00e9p.",
-        "errors.HTTP_SECURITY_WEBHOOK_PROVIDER_UNKNOWN": "Nh\u00e0 cung c\u1ea5p webhook {{provider}} ch\u01b0a \u0111\u01b0\u1ee3c c\u1ea5u h\u00ecnh.",
+        "errors.HTTP_SECURITY_WEBHOOK_REPLAYED":
+            "Webhook n\u1eb1m ngo\u00e0i c\u1eeda s\u1ed5 th\u1eddi gian cho ph\u00e9p.",
+        "errors.HTTP_SECURITY_WEBHOOK_PROVIDER_UNKNOWN":
+            "Nh\u00e0 cung c\u1ea5p webhook {{provider}} ch\u01b0a \u0111\u01b0\u1ee3c c\u1ea5u h\u00ecnh.",
     },
     en: {
+        "errors.HTTP_SECURITY_REQUIRED_DEPENDENCY_UNAVAILABLE": "The required database is unavailable.",
         "errors.HTTP_SECURITY_ORIGIN_REJECTED": "The origin of the request is not allowed.",
         "errors.HTTP_SECURITY_RATE_LIMITED": "Too many requests, try again later.",
         "errors.HTTP_SECURITY_REQUEST_INVALID": "The submitted data is invalid: {{fields}}.",

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

@@ -17,7 +17,9 @@ const options: HttpSecurityOptions = {
     webhooks: {},
 }
 
-const build = async (reflector: Reflector, clock: FakeClock) => {
+const build = async (clock: FakeClock, tier?: RateTier) => {
+    const reflector = mock<Reflector>()
+    reflector.getAllAndOverride.mockReturnValue(tier)
     const moduleRef = await Test.createTestingModule({
         providers: [
             RateLimitGuard,
@@ -26,7 +28,7 @@ const build = async (reflector: Reflector, clock: FakeClock) => {
             { provide: HTTP_SECURITY_OPTIONS, useValue: options },
         ],
     }).compile()
-    return moduleRef.get(RateLimitGuard)
+    return { guard: moduleRef.get(RateLimitGuard), reflector }
 }
 
 /** An execution context of one POST from `ip` on the door; the handler and the class carry the tier metadata. */
@@ -47,17 +49,20 @@ describe("RateLimit", () => {
     it("marks a door with the tier it declares, and the guard counts it under that tier's limit", async () => {
         class Door {}
         RateLimit(RateTier.Strict)(Door)
-        const guard = await build(new Reflector(), new FakeClock(AT))
-        const { context } = contextOf("127.0.0.1", () => undefined, Door)
+        const { guard, reflector } = await build(new FakeClock(AT), RateTier.Strict)
+        const handler = () => undefined
+        const { context } = contextOf("127.0.0.1", handler, Door)
 
+        expect(Reflect.getMetadata("platform.http-security.rate-tier", Door)).toBe(RateTier.Strict)
         expect(guard.canActivate(context)).toBe(true)
         expect(() => guard.canActivate(context)).toThrow(RATE_LIMITED)
+        expect(reflector.getAllAndOverride).toHaveBeenCalledWith("platform.http-security.rate-tier", [handler, Door])
     })
 })
 
 describe("RateLimitGuard", () => {
     it("counts an unmarked door under the default limit", async () => {
-        const guard = await build(mock<Reflector>(), new FakeClock(AT))
+        const { guard } = await build(new FakeClock(AT))
         const { context } = contextOf("127.0.0.1")
 
         expect(guard.canActivate(context)).toBe(true)
@@ -67,7 +72,7 @@ describe("RateLimitGuard", () => {
 
     it("opens a fresh window for a caller whose bucket expired", async () => {
         const clock = new FakeClock(AT)
-        const guard = await build(mock<Reflector>(), clock)
+        const { guard } = await build(clock)
         const { context } = contextOf("127.0.0.1")
 
         guard.canActivate(context)
@@ -80,7 +85,7 @@ describe("RateLimitGuard", () => {
     })
 
     it("counts a request without an address under the unknown bucket", async () => {
-        const guard = await build(mock<Reflector>(), new FakeClock(AT))
+        const { guard } = await build(new FakeClock(AT))
         const { context } = contextOf(undefined)
 
         guard.canActivate(context)
@@ -90,7 +95,7 @@ describe("RateLimitGuard", () => {
 
     it("prunes the expired buckets when the map outgrows the bucket cap", async () => {
         const clock = new FakeClock(AT)
-        const guard = await build(mock<Reflector>(), clock)
+        const { guard } = await build(clock)
         const { context, setIp } = contextOf("0.0.0.0")
 
         for (let index = 0; index <= 10_000; index += 1) {

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

@@ -0,0 +1,5 @@
+/** The required primary database answered before the readiness deadline. */
+export interface ReadinessReport {
+    /** Whether this process can serve requests requiring the database. */
+    readonly ok: true
+}