@starci/hfs 4.0.8 → 4.0.9

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

@@ -0,0 +1,108 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { mock } from "@starci/jest-preset"
+import { Secret } from "@modules/platform/config"
+import type { DatabaseConnectionOptions } from "./database.options"
+import type { ConnectionOpener, ConnectionSource } from "./database.port"
+import { seedText } from "./database.sql"
+import { readSeedFiles, seedConnections, seedDirectoryOf } from "./seed-connections.client"
+import type { SeedFile } from "./seed-connections.client"
+
+const connection = (name: string): DatabaseConnectionOptions => ({
+    name,
+    url: new Secret(`postgres://localhost:5432/${name}`),
+    entities: [],
+    migrations: [],
+})
+
+const file = (name: string, text: string): SeedFile => ({
+    name,
+    text: seedText(text),
+})
+
+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"))
+    })
+})
+
+describe("seedConnections", () => {
+    it("runs the files of each connection in the given order and never opens a connection without a file", async () => {
+        const primary = mock<ConnectionSource>()
+        const archive = mock<ConnectionSource>()
+        const sources = new Map([
+            ["primary", primary],
+            ["archive", archive],
+        ])
+        const opener = mock<ConnectionOpener>()
+        opener.open.mockImplementation(
+            (target: DatabaseConnectionOptions) => sources.get(target.name) ?? mock<ConnectionSource>(),
+        )
+
+        const report = await seedConnections(
+            [connection("primary"), connection("archive")],
+            [file("primary-a.sql", "SELECT 1"), file("primary-b.sql", "SELECT 2")],
+            opener,
+        )
+
+        expect(report).toEqual({
+            applied: { primary: ["primary-a.sql", "primary-b.sql"] },
+            unmatched: [],
+        })
+        expect(primary.query.mock.calls).toEqual([["SELECT 1"], ["SELECT 2"]])
+        expect(primary.destroy).toHaveBeenCalledTimes(1)
+        expect(opener.open).toHaveBeenCalledTimes(1)
+        expect(archive.initialize).not.toHaveBeenCalled()
+    })
+
+    it("answers the files that name no connection as unmatched", async () => {
+        const opener = mock<ConnectionOpener>()
+
+        const report = await seedConnections(
+            [connection("primary")],
+            [file("legacy-users.sql", "INSERT INTO users DEFAULT VALUES")],
+            opener,
+        )
+
+        expect(report).toEqual({ applied: {}, unmatched: ["legacy-users.sql"] })
+        expect(opener.open).not.toHaveBeenCalled()
+    })
+
+    it("destroys the data source of a connection whose seed fails, and fails", async () => {
+        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),
+        ).rejects.toThrow("relation does not exist")
+        expect(failing.destroy).toHaveBeenCalledTimes(1)
+    })
+})
+
+describe("readSeedFiles", () => {
+    let directory = ""
+
+    beforeEach(async () => {
+        directory = await mkdtemp(join(tmpdir(), "seeds-"))
+    })
+
+    afterEach(async () => {
+        await rm(directory, { recursive: true, force: true })
+    })
+
+    it("answers every sql file of the directory sorted by name with its statements, and nothing else", async () => {
+        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)
+
+        expect(files).toEqual([
+            { name: "primary-a.sql", text: "SELECT 1" },
+            { name: "primary-b.sql", text: "SELECT 2" },
+        ])
+    })
+})

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

@@ -0,0 +1,75 @@
+import { readFile, readdir } from "node:fs/promises"
+import { join } from "node:path"
+import { seedText } from "./database.sql"
+import type { SqlText } from "./database.sql"
+import type { DatabaseConnectionOptions } from "./database.options"
+import type { ConnectionOpener } from "./database.port"
+
+const SEED_EXTENSION = ".sql"
+
+/** The stack environment whose seeds run when `--env` is not given. */
+export const DEFAULT_SEED_ENV = "dev"
+
+/** One seed file: its name (`<connection>-<name>.sql`, the connection it seeds first) and its statements. */
+export interface SeedFile {
+    /** The file name, without its directory. */
+    readonly name: string
+    /** The statements of the file, run as written. */
+    readonly text: SqlText
+}
+
+/** What a seed run did: the files it ran by connection, and the files that name no connection (never run). */
+export interface SeedReport {
+    /** The names of the files run, by connection, in the order they ran. */
+    readonly applied: Readonly<Record<string, ReadonlyArray<string>>>
+    /** The files whose name starts with no declared connection. */
+    readonly unmatched: ReadonlyArray<string>
+}
+
+/** The seed directory of a stack environment, relative to the working directory of the run: the app root. */
+export const seedDirectoryOf = (env: string): string => join(".starcistacks", env, "seeds")
+
+/** Reads every `*.sql` file of the seed directory, sorted by name; a missing directory fails the run. */
+export const readSeedFiles = async (directory: string): Promise<ReadonlyArray<SeedFile>> => {
+    const names = (await readdir(directory))
+        .filter((name) => name.endsWith(SEED_EXTENSION))
+        .sort((a, b) => a.localeCompare(b))
+    return Promise.all(
+        names.map(async (name) => ({
+            name,
+            text: seedText(await readFile(join(directory, name), "utf8")),
+        })),
+    )
+}
+
+/** Whether a seed file seeds the connection: its name starts with the connection name and a dash. */
+const seeds = (file: SeedFile, connection: DatabaseConnectionOptions): boolean =>
+    file.name.startsWith(`${connection.name}-`)
+
+/**
+ * Runs the seed files of every connection in turn, each through the data source of the connection it names, and answers the
+ * files it ran by connection and the files that name no connection. A connection without a seed file is never opened.
+ */
+export async function seedConnections(
+    connections: ReadonlyArray<DatabaseConnectionOptions>,
+    files: ReadonlyArray<SeedFile>,
+    opener: ConnectionOpener,
+): Promise<SeedReport> {
+    const applied: Record<string, ReadonlyArray<string>> = {}
+    for (const connection of connections) {
+        const own = files.filter((file) => seeds(file, connection))
+        if (own.length === 0) continue
+        const source = opener.open(connection)
+        await source.initialize()
+        try {
+            for (const file of own) await source.query(file.text)
+        } finally {
+            await source.destroy()
+        }
+        applied[connection.name] = own.map((file) => file.name)
+    }
+    const unmatched = files
+        .filter((file) => !connections.some((connection) => seeds(file, connection)))
+        .map((file) => file.name)
+    return { applied, unmatched }
+}

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

@@ -0,0 +1,88 @@
+import { mock } from "@starci/jest-preset"
+import { Test } from "@nestjs/testing"
+import { Secret } from "@modules/platform/config"
+import { LOGGER, LoggingLogEvent } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { CONNECTION_SOURCE, DATABASE_OPTIONS, READ_SEED_FILES } from "./database.port"
+import type { ConnectionOpener, ConnectionSource, SeedFileReader } from "./database.port"
+import type { DatabaseConnectionOptions } from "./database.options"
+import { seedText } from "./database.sql"
+import { seedDirectoryOf } from "./seed-connections.client"
+import type { SeedFile } from "./seed-connections.client"
+import { SeedRunnerService } from "./seed-runner.service"
+
+const connection = (name: string): DatabaseConnectionOptions => ({
+    name,
+    url: new Secret(`postgres://localhost:5432/${name}`),
+    entities: [],
+    migrations: [],
+})
+
+const file = (name: string, text: string): SeedFile => ({
+    name,
+    text: seedText(text),
+})
+
+const build = async (
+    openSource: (target: DatabaseConnectionOptions) => ConnectionSource,
+    readSeeds: (directory: string) => Promise<ReadonlyArray<SeedFile>>,
+) => {
+    const logger = mock<Logger>()
+    const opener = mock<ConnectionOpener>()
+    opener.open.mockImplementation((target) => openSource(target))
+    const reader = mock<SeedFileReader>()
+    reader.read.mockImplementation((directory) => readSeeds(directory))
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            SeedRunnerService,
+            {
+                provide: DATABASE_OPTIONS,
+                useValue: { connections: [connection("primary")] },
+            },
+            { provide: CONNECTION_SOURCE, useValue: opener },
+            { provide: READ_SEED_FILES, useValue: reader },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return { runner: moduleRef.get(SeedRunnerService), logger, reader }
+}
+
+describe("SeedRunnerService", () => {
+    it("reads the seeds of the named environment, runs them on their connections and logs the report", async () => {
+        const primary = mock<ConnectionSource>()
+        const { runner, logger, reader } = await build(
+            () => primary,
+            () =>
+                Promise.resolve([
+                    file("primary-notes.sql", "INSERT INTO notes (body) VALUES ('a')"),
+                    file("legacy-users.sql", "INSERT INTO users DEFAULT VALUES"),
+                ]),
+        )
+
+        await expect(runner.run("staging")).resolves.toBeUndefined()
+
+        expect(reader.read).toHaveBeenCalledWith(seedDirectoryOf("staging"))
+        expect(primary.query).toHaveBeenCalledWith("INSERT INTO notes (body) VALUES ('a')")
+        expect(logger.info).toHaveBeenCalledWith(LoggingLogEvent.SeedsApplied, {
+            env: "staging",
+            applied: { primary: ["primary-notes.sql"] },
+            unmatched: ["legacy-users.sql"],
+        })
+    })
+
+    it("reads the dev seeds when no environment is named", async () => {
+        const { runner, logger, reader } = await build(
+            () => mock<ConnectionSource>(),
+            () => Promise.resolve([]),
+        )
+
+        await expect(runner.run()).resolves.toBeUndefined()
+
+        expect(reader.read).toHaveBeenCalledWith(seedDirectoryOf("dev"))
+        expect(logger.info).toHaveBeenCalledWith(LoggingLogEvent.SeedsApplied, {
+            env: "dev",
+            applied: {},
+            unmatched: [],
+        })
+    })
+})

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

@@ -0,0 +1,29 @@
+import { Injectable } from "@nestjs/common"
+import { InjectLogger, LoggingLogEvent } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { InjectConnectionSource, InjectDatabaseOptions, InjectReadSeedFiles } from "./database.port"
+import type { DatabaseOptions } from "./database.options"
+import type { ConnectionOpener, SeedFileReader } from "./database.port"
+import { DEFAULT_SEED_ENV, seedConnections, seedDirectoryOf } from "./seed-connections.client"
+
+@Injectable()
+/** The one seed runner: reads the seed files of a stack environment, runs them on the connections they name and logs the report. */
+export class SeedRunnerService {
+    constructor(
+        @InjectDatabaseOptions() private readonly options: DatabaseOptions,
+        @InjectConnectionSource() private readonly opener: ConnectionOpener,
+        @InjectReadSeedFiles() private readonly reader: SeedFileReader,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    /** Reads the seed files of the environment (the dev seeds when none is named), runs them on their connections and logs the report. */
+    async run(env: string = DEFAULT_SEED_ENV): Promise<void> {
+        const files = await this.reader.read(seedDirectoryOf(env))
+        const report = await seedConnections(this.options.connections, files, this.opener)
+        this.logger.info(LoggingLogEvent.SeedsApplied, {
+            env,
+            applied: report.applied,
+            unmatched: report.unmatched,
+        })
+    }
+}

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

@@ -0,0 +1,48 @@
+import type { ArgumentsHost } from "@nestjs/common"
+import { mock } from "@starci/jest-preset"
+import type { Request, Response } from "express"
+import type { RequestLocale } from "@modules/platform/i18n"
+import { ErrorsFilter } from "./errors.filter"
+import type { ErrorsService } from "./errors.service"
+
+const build = () => {
+    const errors = mock<ErrorsService>()
+    const requestLocale = mock<RequestLocale>()
+    return { filter: new ErrorsFilter(errors, requestLocale), errors, requestLocale }
+}
+
+describe("ErrorsFilter", () => {
+    it("writes a localized description and its status to an HTTP response", () => {
+        const { filter, errors, requestLocale } = build()
+        const failure = new Error("note missing")
+        const request = mock<Request>({ headers: { "accept-language": "en-US,en;q=0.9" } })
+        const response = mock<Response>()
+        response.status.mockReturnValue(response)
+        const http = mock<ReturnType<ArgumentsHost["switchToHttp"]>>()
+        http.getRequest.mockReturnValue(request)
+        http.getResponse.mockReturnValue(response)
+        const host = mock<ArgumentsHost>()
+        host.switchToHttp.mockReturnValue(http)
+        errors.describe.mockReturnValue({
+            code: "NOTE_NOT_FOUND",
+            kind: "not-found",
+            status: 404,
+            params: { noteId: "note-1" },
+        })
+        requestLocale.of.mockReturnValue("en")
+        errors.text.mockReturnValue("The note was not found")
+
+        expect(filter.catch(failure, host)).toBeUndefined()
+
+        expect(errors.describe).toHaveBeenCalledWith(failure)
+        expect(requestLocale.of).toHaveBeenCalledWith("en-US,en;q=0.9")
+        expect(errors.text).toHaveBeenCalledWith("NOTE_NOT_FOUND", { noteId: "note-1" }, "en")
+        expect(response.status).toHaveBeenCalledWith(404)
+        expect(response.json).toHaveBeenCalledWith({
+            code: "NOTE_NOT_FOUND",
+            kind: "not-found",
+            message: "The note was not found",
+            params: { noteId: "note-1" },
+        })
+    })
+})

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

@@ -3,7 +3,7 @@ import type { MessageBundle } from "@modules/platform/i18n"
 /** Display text of the errors capability codes, Vietnamese and English. */
 export const ERRORS_MESSAGES: MessageBundle = {
     vi: {
-        "errors.ERRORS_INTERNAL": "Đã xảy ra lỗi không mong muốn.",
+        "errors.ERRORS_INTERNAL": "\u0110\u00e3 x\u1ea3y ra l\u1ed7i kh\u00f4ng mong mu\u1ed1n.",
     },
     en: {
         "errors.ERRORS_INTERNAL": "An unexpected error occurred.",

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

@@ -7,12 +7,24 @@ export enum HttpSecurityErrorCode {
     OriginRejected = "HTTP_SECURITY_ORIGIN_REJECTED",
     /** The caller sent more requests than its tier allows in the current window. */
     RateLimited = "HTTP_SECURITY_RATE_LIMITED",
+    /** The request body or arguments failed validation; the offending fields ride in the params. */
+    RequestInvalid = "HTTP_SECURITY_REQUEST_INVALID",
+    /** A webhook did not prove the signature of its exact raw body. */
+    WebhookSignatureInvalid = "HTTP_SECURITY_WEBHOOK_SIGNATURE_INVALID",
+    /** A webhook was signed outside its configured replay window. */
+    WebhookReplayed = "HTTP_SECURITY_WEBHOOK_REPLAYED",
+    /** A generated webhook route has no provider configuration. */
+    WebhookProviderUnknown = "HTTP_SECURITY_WEBHOOK_PROVIDER_UNKNOWN",
 }
 
 /** How each http-security code travels. */
 export const HTTP_SECURITY_ERROR_KINDS: Record<HttpSecurityErrorCode, ErrorKind> = {
     [HttpSecurityErrorCode.OriginRejected]: "forbidden",
     [HttpSecurityErrorCode.RateLimited]: "rate-limited",
+    [HttpSecurityErrorCode.RequestInvalid]: "invalid",
+    [HttpSecurityErrorCode.WebhookSignatureInvalid]: "unauthenticated",
+    [HttpSecurityErrorCode.WebhookReplayed]: "unauthenticated",
+    [HttpSecurityErrorCode.WebhookProviderUnknown]: "internal",
 }
 
 /** The one error class of the http-security capability. */

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

@@ -0,0 +1,16 @@
+import type { ExecutionContext } from "@nestjs/common"
+import type { Request } from "express"
+import { mock } from "@starci/jest-preset"
+import { requestOf } from "./execution-request.mapper"
+
+describe("requestOf", () => {
+    it("reads the HTTP request behind an execution context", () => {
+        const request = mock<Request>()
+        const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
+        http.getRequest.mockReturnValue(request)
+        const context = mock<ExecutionContext>()
+        context.switchToHttp.mockReturnValue(http)
+
+        expect(requestOf(context)).toBe(request)
+    })
+})

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

@@ -1,5 +1,11 @@
 import type { EnvSource } from "@modules/platform/config"
-import type { HttpSecurityOptions } from "./http-security.options"
+import type { HttpSecurityOptions, WebhookProviderOptions } from "./http-security.options"
+
+/** Reads one webhook provider's required signing secret and bounded replay window. */
+export const parseWebhookProviderConfig = (env: EnvSource, prefix: string): WebhookProviderOptions => ({
+    secret: env.secret(`${prefix}_WEBHOOK_SECRET`),
+    toleranceMs: env.duration(`${prefix}_WEBHOOK_TOLERANCE`, 300_000),
+})
 
 /** Reads the http-security options: the origin allowlist is required, the rate limits are tunables with literal defaults. */
 export const parseHttpSecurityConfig = (env: EnvSource): HttpSecurityOptions => ({
@@ -13,4 +19,5 @@ export const parseHttpSecurityConfig = (env: EnvSource): HttpSecurityOptions =>
         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.decorators.ts

@@ -1,10 +1,18 @@
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
 import type { HttpSecurityOptions } from "./http-security.options"
+import type { WebhookSignatureService } from "./webhook-signature.service"
 
 /** 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")
 
+/** Token of the shared signed-webhook proof. */
+export const WEBHOOK_SIGNATURE: unique symbol = Symbol("platform.http-security.webhook-signature")
+
+/** Injects the signed-webhook proof. Parameter type: WebhookSignatureService. */
+export const InjectWebhookSignature = (): TypedParameterDecorator<WebhookSignatureService> =>
+    injector<WebhookSignatureService>(WEBHOOK_SIGNATURE)
+
 /** Injects the options of the http-security capability. Parameter type: HttpSecurityOptions. */
 export const InjectHttpSecurityOptions = (): TypedParameterDecorator<HttpSecurityOptions> =>
     injector<HttpSecurityOptions>(HTTP_SECURITY_OPTIONS)

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

@@ -1,6 +1,10 @@
 import { Module } from "@nestjs/common"
 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 { RequestValidationService } from "./request-validation.service"
+import { WebhookSignatureService } from "./webhook-signature.service"
 
 @Module({})
 /** The http-security capability: the options its guards (registered by each api app) read. */
@@ -8,6 +12,15 @@ export class HttpSecurityModule extends ConfigurableModuleClass {
     /** Registers the capability once per app. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
         const base = super.register(options)
-        return { ...base, exports: [MODULE_OPTIONS_TOKEN] }
+        return {
+            ...base,
+            providers: [
+                ...(base.providers ?? []),
+                { provide: APP_PIPE, useClass: RequestValidationService },
+                WebhookSignatureService,
+                { provide: WEBHOOK_SIGNATURE, useExisting: WebhookSignatureService },
+            ],
+            exports: [MODULE_OPTIONS_TOKEN, WebhookSignatureService, WEBHOOK_SIGNATURE],
+        }
     }
 }

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

@@ -1,3 +1,5 @@
+import type { Secret } from "@modules/platform/config"
+
 /** How many requests a caller may send per window, per tier. */
 export interface RateLimitOptions {
     /** The length of one window in milliseconds. */
@@ -8,10 +10,20 @@ export interface RateLimitOptions {
     readonly strictLimit: number
 }
 
+/** The signing proof configured for one webhook provider. */
+export interface WebhookProviderOptions {
+    /** The secret the provider signs deliveries with. */
+    readonly secret: Secret
+    /** The maximum age or clock skew of one delivery, in milliseconds. */
+    readonly toleranceMs: number
+}
+
 /** Options of the http-security capability. */
 export interface HttpSecurityOptions {
     /** The origins allowed to send state-changing requests from a browser. */
     readonly allowedOrigins: ReadonlyArray<string>
     /** The rate limit tiers. */
     readonly rateLimit: RateLimitOptions
+    /** Signed-webhook providers keyed by their generated route name. */
+    readonly webhooks: Readonly<Record<string, WebhookProviderOptions>>
 }

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

@@ -3,11 +3,19 @@ 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ồn gửi yêu cầu không được phép.",
-        "errors.HTTP_SECURITY_RATE_LIMITED": "Bạn gửi quá nhiều yêu cầu, hãy thử lại sau.",
+        "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.",
     },
     en: {
         "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}}.",
+        "errors.HTTP_SECURITY_WEBHOOK_SIGNATURE_INVALID": "The webhook signature is not valid.",
+        "errors.HTTP_SECURITY_WEBHOOK_REPLAYED": "The webhook was signed outside the allowed time window.",
+        "errors.HTTP_SECURITY_WEBHOOK_PROVIDER_UNKNOWN": "The webhook provider {{provider}} is not configured.",
     },
 }

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

@@ -0,0 +1,63 @@
+import type { ExecutionContext } from "@nestjs/common"
+import type { Request } from "express"
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { HttpSecurityErrorCode } from "./errors/http-security.error"
+import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
+import type { HttpSecurityOptions } from "./http-security.options"
+import { OriginGuard } from "./origin.guard"
+
+const options: HttpSecurityOptions = {
+    allowedOrigins: ["https://app.test"],
+    rateLimit: { windowMs: 60_000, defaultLimit: 100, strictLimit: 10 },
+    webhooks: {},
+}
+
+const build = async (method: string, headers: Request["headers"]) => {
+    const request = mock<Request>({ headers, method })
+    const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
+    http.getRequest.mockReturnValue(request)
+    const context = mock<ExecutionContext>()
+    context.switchToHttp.mockReturnValue(http)
+    const moduleRef = await Test.createTestingModule({
+        providers: [OriginGuard, { provide: HTTP_SECURITY_OPTIONS, useValue: options }],
+    }).compile()
+    return { guard: moduleRef.get(OriginGuard), context }
+}
+
+describe("OriginGuard", () => {
+    it.each(["GET", "HEAD", "OPTIONS"])("allows the safe %s method regardless of origin", async (method) => {
+        const { guard, context } = await build(method, { origin: "https://foreign.test" })
+
+        expect(guard.canActivate(context)).toBe(true)
+    })
+
+    it.each([{}, { referer: "not a URL" }])(
+        "allows a state-changing non-browser request without a usable origin (%o)",
+        async (headers) => {
+            const { guard, context } = await build("POST", headers)
+
+            expect(guard.canActivate(context)).toBe(true)
+        },
+    )
+
+    it("allows a state-changing request carrying an allowed Origin header", async () => {
+        const { guard, context } = await build("POST", { origin: "https://app.test" })
+
+        expect(guard.canActivate(context)).toBe(true)
+    })
+
+    it("uses the origin of an allowed Referer URL", async () => {
+        const { guard, context } = await build("PATCH", { referer: "https://app.test/notes/one" })
+
+        expect(guard.canActivate(context)).toBe(true)
+    })
+
+    it("refuses a state-changing request from an origin outside the allowlist", async () => {
+        const { guard, context } = await build("DELETE", { origin: "https://foreign.test" })
+
+        expect(() => guard.canActivate(context)).toThrow(
+            expect.objectContaining({ code: HttpSecurityErrorCode.OriginRejected }),
+        )
+    })
+})