@starci/hfs 3.0.0 → 4.0.0

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

@@ -0,0 +1,32 @@
+import { Catch } from "@nestjs/common"
+import type { ArgumentsHost, ExceptionFilter } from "@nestjs/common"
+import type { Request, Response } from "express"
+import { InjectRequestLocale } from "@modules/platform/i18n"
+import type { RequestLocale } from "@modules/platform/i18n"
+import { InjectErrorsService } from "./errors.decorators"
+import type { ErrorsService } from "./errors.service"
+
+@Catch()
+/** The one exception filter of an app: answers `{ code, kind, message, params }` with the status of the kind. */
+export class ErrorsFilter implements ExceptionFilter {
+    constructor(
+        @InjectErrorsService() private readonly errors: ErrorsService,
+        @InjectRequestLocale() private readonly requestLocale: RequestLocale,
+    ) {}
+
+    /** Writes the description of `exception` on the HTTP response. */
+    catch(exception: unknown, host: ArgumentsHost): void {
+        const http = host.switchToHttp()
+        const request = http.getRequest<Request>()
+        const description = this.errors.describe(exception)
+        const locale = this.requestLocale.of(request.headers["accept-language"])
+        http.getResponse<Response>()
+            .status(description.status)
+            .json({
+                code: description.code,
+                kind: description.kind,
+                message: this.errors.text(description.code, description.params, locale),
+                params: description.params,
+            })
+    }
+}

package/templates/be/skeleton/src/modules/platform/errors/errors.log-events.ts

@@ -1,5 +1,5 @@
 /** Log events of the errors capability. */
 export enum ErrorsLogEvent {
-    /** A request ended in a failure the app's filter answered. */
-    RequestFailed = "http.request_failed",
+    /** A failure no capability declared reached a transport and was masked; the cause rides in the line. */
+    Unhandled = "errors.unhandled",
 }

package/templates/be/skeleton/src/modules/platform/errors/errors.module-definition.ts

@@ -0,0 +1,9 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ERRORS_OPTIONS } from "./errors.decorators"
+import type { ErrorsOptions } from "./errors.options"
+
+/** The configurable-module base of the errors capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<ErrorsOptions>({ optionsInjectionToken: ERRORS_OPTIONS })
+        .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+        .build()

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

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { ERRORS_SERVICE } from "./errors.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./errors.module-definition"
+import { ErrorsService } from "./errors.service"
+
+@Module({})
+/** The errors capability: the one description service the REST filter and the GraphQL formatter answer through. */
+export class ErrorsModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app; each api app binds the ErrorsFilter through APP_FILTER itself. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), { provide: ERRORS_SERVICE, useClass: ErrorsService }],
+            exports: [ERRORS_SERVICE],
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { ErrorKindTable } from "./errors.contracts"
+
+/** Options of the errors capability: the kind tables of every capability the app composes. */
+export interface ErrorsOptions {
+    /** One `<C>_ERROR_KINDS` table per capability; a code found in none of them is internal. */
+    readonly kinds: ReadonlyArray<ErrorKindTable>
+}

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

@@ -0,0 +1,94 @@
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { MESSAGE_CATALOG } from "@modules/platform/i18n"
+import type { MessageCatalog } from "@modules/platform/i18n"
+import { LOGGER } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { DomainError } from "./domain.error"
+import { ErrorsErrorCode } from "./errors/errors.error"
+import { ErrorsLogEvent } from "./errors.log-events"
+import { ErrorsService } from "./errors.service"
+import { ERRORS_OPTIONS } from "./errors.decorators"
+
+enum DemoCode {
+    Missing = "DEMO_MISSING",
+    Undeclared = "DEMO_UNDECLARED",
+}
+
+class DemoError extends DomainError<DemoCode> {}
+
+const build = async () => {
+    const logger = mock<Logger>()
+    const catalog = mock<MessageCatalog>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            ErrorsService,
+            { provide: ERRORS_OPTIONS, useValue: { kinds: [{ [DemoCode.Missing]: "not-found" }] } },
+            { provide: MESSAGE_CATALOG, useValue: catalog },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return { service: moduleRef.get(ErrorsService), logger, catalog }
+}
+
+describe("ErrorsService", () => {
+    describe("describe", () => {
+        it("keeps the code, kind, status and params of a declared capability error", async () => {
+            const { service, logger } = await build()
+
+            const description = service.describe(new DemoError({ code: DemoCode.Missing, params: { id: "t-1" } }))
+
+            expect(description).toEqual({
+                code: DemoCode.Missing,
+                kind: "not-found",
+                status: 404,
+                params: { id: "t-1" },
+            })
+            expect(logger.error).not.toHaveBeenCalled()
+        })
+
+        it("masks a capability error no composed capability declared, and logs it", async () => {
+            const { service, logger } = await build()
+            const error = new DemoError({ code: DemoCode.Undeclared })
+
+            expect(service.describe(error)).toEqual({
+                code: ErrorsErrorCode.Internal,
+                kind: "internal",
+                status: 500,
+                params: {},
+            })
+            expect(logger.error).toHaveBeenCalledWith(ErrorsLogEvent.Unhandled, error)
+        })
+
+        it("masks any other failure as internal, and logs it", async () => {
+            const { service, logger } = await build()
+            const error = new Error("boom")
+
+            expect(service.describe(error)).toEqual({
+                code: ErrorsErrorCode.Internal,
+                kind: "internal",
+                status: 500,
+                params: {},
+            })
+            expect(logger.error).toHaveBeenCalledWith(ErrorsLogEvent.Unhandled, error)
+        })
+    })
+
+    describe("text", () => {
+        it("answers the catalog text of the code in the locale", async () => {
+            const { service, catalog } = await build()
+            catalog.get.mockReturnValue("Not found")
+
+            expect(service.text(DemoCode.Missing, { id: "t-1" }, "en")).toBe("Not found")
+            expect(catalog.get).toHaveBeenCalledWith(`errors.${DemoCode.Missing}`, { id: "t-1" }, "en")
+        })
+
+        it("answers the text of the internal error for a code without a catalog entry", async () => {
+            const { service, catalog } = await build()
+            catalog.get.mockImplementation((key) => (key === `errors.${ErrorsErrorCode.Internal}` ? "Internal" : key))
+
+            expect(service.text(DemoCode.Undeclared, {}, "en")).toBe("Internal")
+            expect(catalog.get).toHaveBeenLastCalledWith(`errors.${ErrorsErrorCode.Internal}`, {}, "en")
+        })
+    })
+})

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

@@ -0,0 +1,47 @@
+import { Injectable } from "@nestjs/common"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { InjectMessageCatalog } from "@modules/platform/i18n"
+import type { Locale, MessageCatalog } from "@modules/platform/i18n"
+import { DomainError } from "./domain.error"
+import { InjectErrorsOptions } from "./errors.decorators"
+import type { ErrorDescription, ErrorKind, ErrorParams } from "./errors.contracts"
+import { ERRORS_ERROR_KINDS, ErrorsErrorCode } from "./errors/errors.error"
+import { ErrorsLogEvent } from "./errors.log-events"
+import type { ErrorsOptions } from "./errors.options"
+import { HTTP_STATUS_BY_KIND } from "./http-status.policy"
+
+@Injectable()
+/** Turns any failure into the one description the transport answers with: declared codes keep their code and kind, everything else is masked. */
+export class ErrorsService {
+    private readonly kinds: ReadonlyMap<string, ErrorKind>
+
+    constructor(
+        @InjectErrorsOptions() options: ErrorsOptions,
+        @InjectMessageCatalog() private readonly catalog: MessageCatalog,
+        @InjectLogger() private readonly logger: Logger,
+    ) {
+        this.kinds = new Map([...options.kinds, ERRORS_ERROR_KINDS].flatMap((table) => Object.entries(table)))
+    }
+
+    /** Describes `error`: a DomainError of a composed capability keeps its code; anything else is logged and masked as internal. */
+    describe(error: unknown): ErrorDescription {
+        if (error instanceof DomainError) {
+            const kind = this.kinds.get(error.code)
+            if (kind !== undefined) return this.build(error.code, kind, error.params)
+        }
+        this.logger.error(ErrorsLogEvent.Unhandled, error)
+        return this.build(ErrorsErrorCode.Internal, "internal", {})
+    }
+
+    /** The display text of a failure code in `locale`; a code without a catalog entry answers the text of the internal error. */
+    text(code: string, params: ErrorParams, locale: Locale): string {
+        const key = `errors.${code}`
+        const text = this.catalog.get(key, params, locale)
+        return text === key ? this.catalog.get(`errors.${ErrorsErrorCode.Internal}`, {}, locale) : text
+    }
+
+    private build(code: string, kind: ErrorKind, params: ErrorParams): ErrorDescription {
+        return { code, kind, status: HTTP_STATUS_BY_KIND[kind], params }
+    }
+}

package/templates/be/skeleton/src/modules/platform/errors/http-status.policy.ts

@@ -0,0 +1,13 @@
+import type { ErrorKind } from "./errors.contracts"
+
+/** The one table from error kind to HTTP status; every transport answers a failure through it. */
+export const HTTP_STATUS_BY_KIND: Readonly<Record<ErrorKind, number>> = {
+    invalid: 400,
+    unauthenticated: 401,
+    forbidden: 403,
+    "not-found": 404,
+    conflict: 409,
+    "rate-limited": 429,
+    unavailable: 503,
+    internal: 500,
+}

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

@@ -1,2 +1,5 @@
+export type { DomainErrorInit, ErrorKind, ErrorParams } from "./errors.contracts"
 export { DomainError } from "./domain.error"
-export { ErrorFilter } from "./error.filter"
+export { ErrorsFilter } from "./errors.filter"
+export { ErrorsModule } from "./errors.module"
+export { ERRORS_MESSAGES } from "./messages/errors.messages"

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

@@ -0,0 +1,11 @@
+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.",
+    },
+    en: {
+        "errors.ERRORS_INTERNAL": "An unexpected error occurred.",
+    },
+}

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

@@ -0,0 +1,19 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the http-security capability. */
+export enum HttpSecurityErrorCode {
+    /** 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. */
+    RateLimited = "HTTP_SECURITY_RATE_LIMITED",
+}
+
+/** How each http-security code travels. */
+export const HTTP_SECURITY_ERROR_KINDS: Record<HttpSecurityErrorCode, ErrorKind> = {
+    [HttpSecurityErrorCode.OriginRejected]: "forbidden",
+    [HttpSecurityErrorCode.RateLimited]: "rate-limited",
+}
+
+/** The one error class of the http-security capability. */
+export class HttpSecurityError extends DomainError<HttpSecurityErrorCode> {}

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

@@ -0,0 +1,5 @@
+import type { ExecutionContext } from "@nestjs/common"
+import type { Request } from "express"
+
+/** The HTTP request behind an execution context. */
+export const requestOf = (context: ExecutionContext): Request => context.switchToHttp().getRequest<Request>()

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

@@ -0,0 +1,16 @@
+import type { EnvSource } from "@modules/platform/config"
+import type { HttpSecurityOptions } from "./http-security.options"
+
+/** 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
+        .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),
+    },
+})

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

@@ -0,0 +1,10 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { HttpSecurityOptions } from "./http-security.options"
+
+/** 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")
+
+/** 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-definition.ts

@@ -0,0 +1,9 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
+import type { HttpSecurityOptions } from "./http-security.options"
+
+/** The configurable-module base of the http-security capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<HttpSecurityOptions>({ optionsInjectionToken: HTTP_SECURITY_OPTIONS })
+        .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+        .build()

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

@@ -0,0 +1,13 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } from "./http-security.module-definition"
+
+@Module({})
+/** The http-security capability: the options its guards (registered by each api app) read. */
+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] }
+    }
+}

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

@@ -0,0 +1,17 @@
+/** How many requests a caller may send per window, per tier. */
+export interface RateLimitOptions {
+    /** The length of one window in milliseconds. */
+    readonly windowMs: number
+    /** Requests per window for the default tier. */
+    readonly defaultLimit: number
+    /** Requests per window for the strict tier (authentication handshakes and signed webhooks). */
+    readonly strictLimit: 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
+}

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

@@ -0,0 +1,7 @@
+export { HTTP_SECURITY_ERROR_KINDS } from "./errors/http-security.error"
+export { parseHttpSecurityConfig } from "./http-security.config"
+export { HttpSecurityModule } from "./http-security.module"
+export type { HttpSecurityOptions } from "./http-security.options"
+export { HTTP_SECURITY_MESSAGES } from "./messages/http-security.messages"
+export { OriginGuard } from "./origin.guard"
+export { RateLimitGuard } from "./rate-limit.guard"

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

@@ -0,0 +1,13 @@
+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.",
+    },
+    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.",
+    },
+}

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

@@ -0,0 +1,31 @@
+import { Injectable } from "@nestjs/common"
+import type { CanActivate, ExecutionContext } from "@nestjs/common"
+import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
+import { requestOf } from "./execution-request.mapper"
+import { InjectHttpSecurityOptions } from "./http-security.decorators"
+import type { HttpSecurityOptions } from "./http-security.options"
+
+const SAFE_METHODS: ReadonlyArray<string> = ["GET", "HEAD", "OPTIONS"]
+
+const originOf = (origin: string | undefined, referer: string | undefined): string | undefined => {
+    if (origin) return origin
+    return referer && URL.canParse(referer) ? new URL(referer).origin : undefined
+}
+
+@Injectable()
+/**
+ * The second app guard, the CSRF defence: a state-changing request that names an origin (browsers always do) must name
+ * an allowed one. A request without Origin and Referer is not a browser and carries no ambient credential, so it passes.
+ */
+export class OriginGuard implements CanActivate {
+    constructor(@InjectHttpSecurityOptions() private readonly options: HttpSecurityOptions) {}
+
+    /** Refuses a state-changing request from an origin outside the allowlist. */
+    canActivate(context: ExecutionContext): boolean {
+        const request = requestOf(context)
+        if (SAFE_METHODS.includes(request.method)) return true
+        const origin = originOf(request.headers.origin, request.headers.referer)
+        if (origin === undefined || this.options.allowedOrigins.includes(origin)) return true
+        throw new HttpSecurityError({ code: HttpSecurityErrorCode.OriginRejected })
+    }
+}

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

@@ -0,0 +1,68 @@
+import { Injectable, SetMetadata } from "@nestjs/common"
+import type { CanActivate, ExecutionContext } from "@nestjs/common"
+import type { Reflector } from "@nestjs/core"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { InjectReflector } from "@modules/platform/composition"
+import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
+import { requestOf } from "./execution-request.mapper"
+import { InjectHttpSecurityOptions } from "./http-security.decorators"
+import type { HttpSecurityOptions } from "./http-security.options"
+
+/** The rate limit tiers of a door. */
+export enum RateTier {
+    /** The global default tier. */
+    Default = "default",
+    /** The tight tier every authentication handshake and signed webhook carries. */
+    Strict = "strict",
+}
+
+const RATE_TIER_KEY = "platform.http-security.rate-tier"
+const BUCKETS_MAX = 10_000
+
+interface Bucket {
+    count: number
+    resetAt: number
+}
+
+/** Marks a door with a rate limit tier other than the default. */
+export const RateLimit = (tier: RateTier): ReturnType<typeof SetMetadata> => SetMetadata(RATE_TIER_KEY, tier)
+
+@Injectable()
+/** The first app guard: a fixed-window counter per caller address and tier, kept in process memory and stamped by the Clock. */
+export class RateLimitGuard implements CanActivate {
+    private readonly buckets = new Map<string, Bucket>()
+
+    constructor(
+        @InjectReflector() private readonly reflector: Reflector,
+        @InjectClock() private readonly clock: Clock,
+        @InjectHttpSecurityOptions() private readonly options: HttpSecurityOptions,
+    ) {}
+
+    /** Counts the request and refuses it when the caller is over the limit of the door tier. */
+    canActivate(context: ExecutionContext): boolean {
+        const tier =
+            this.reflector.getAllAndOverride<RateTier | undefined>(RATE_TIER_KEY, [
+                context.getHandler(),
+                context.getClass(),
+            ]) ?? RateTier.Default
+        const limit =
+            tier === RateTier.Strict ? this.options.rateLimit.strictLimit : this.options.rateLimit.defaultLimit
+        const now = this.clock.now().getTime()
+        const key = `${tier}:${requestOf(context).ip ?? "unknown"}`
+        const current = this.buckets.get(key)
+        const bucket =
+            current && current.resetAt > now ? current : { count: 0, resetAt: now + this.options.rateLimit.windowMs }
+        bucket.count += 1
+        this.buckets.set(key, bucket)
+        if (this.buckets.size > BUCKETS_MAX) this.prune(now)
+        if (bucket.count > limit) throw new HttpSecurityError({ code: HttpSecurityErrorCode.RateLimited })
+        return true
+    }
+
+    private prune(now: number): void {
+        for (const [key, bucket] of this.buckets) {
+            if (bucket.resetAt <= now) this.buckets.delete(key)
+        }
+    }
+}

package/templates/be/skeleton/src/modules/platform/i18n/bundle-message-catalog.service.spec.ts

@@ -0,0 +1,66 @@
+import { Test } from "@nestjs/testing"
+import { builder } from "@starci/jest-preset"
+import { BundleMessageCatalog } from "./bundle-message-catalog.service"
+import type { I18nOptions } from "./i18n.options"
+import { I18N_OPTIONS } from "./i18n.decorators"
+
+const defaults: I18nOptions = {
+    bundles: [
+        {
+            vi: { "task.title": "Cong viec {{title}}", "task.count": "{{n}} viec" },
+            en: { "task.title": "Task {{title}}", "task.count": "{{n}} tasks" },
+        },
+        { vi: { "share.ok": "Da chia se" }, en: { "share.ok": "Shared" } },
+    ],
+}
+
+const build = async (overrides?: Partial<I18nOptions>) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            BundleMessageCatalog,
+            { provide: I18N_OPTIONS, useValue: builder<I18nOptions>(defaults)(overrides) },
+        ],
+    }).compile()
+    return moduleRef.get(BundleMessageCatalog)
+}
+
+describe("BundleMessageCatalog", () => {
+    describe("get", () => {
+        it("fills the placeholders of the text in the locale", async () => {
+            const catalog = await build()
+
+            expect(catalog.get("task.title", { title: "Write" }, "en")).toBe("Task Write")
+            expect(catalog.get("task.title", { title: "Write" }, "vi")).toBe("Cong viec Write")
+        })
+
+        it("fills a numeric parameter", async () => {
+            const catalog = await build()
+
+            expect(catalog.get("task.count", { n: 3 }, "en")).toBe("3 tasks")
+        })
+
+        it("reads a key from any composed bundle", async () => {
+            const catalog = await build()
+
+            expect(catalog.get("share.ok", {}, "en")).toBe("Shared")
+        })
+
+        it("leaves a placeholder without a value as written", async () => {
+            const catalog = await build()
+
+            expect(catalog.get("task.title", {}, "en")).toBe("Task {{title}}")
+        })
+
+        it("answers the key itself for an unknown key", async () => {
+            const catalog = await build()
+
+            expect(catalog.get("no.such.key", {}, "en")).toBe("no.such.key")
+        })
+
+        it("answers the key itself when no bundle is composed", async () => {
+            const catalog = await build({ bundles: [] })
+
+            expect(catalog.get("task.title", {}, "vi")).toBe("task.title")
+        })
+    })
+})

package/templates/be/skeleton/src/modules/platform/i18n/bundle-message-catalog.service.ts

@@ -0,0 +1,30 @@
+import { Injectable } from "@nestjs/common"
+import type { Locale, MessageParams } from "./i18n.contracts"
+import { InjectI18nOptions } from "./i18n.decorators"
+import type { I18nOptions } from "./i18n.options"
+import type { MessageCatalog } from "./i18n.port"
+
+const PLACEHOLDER = /\{\{(\w+)\}\}/g
+
+@Injectable()
+/** The catalog over the bundles of I18nOptions: later bundles never override earlier ones, keys are owned by one bundle. */
+export class BundleMessageCatalog implements MessageCatalog {
+    private readonly texts: Readonly<Record<Locale, ReadonlyMap<string, string>>>
+
+    constructor(@InjectI18nOptions() options: I18nOptions) {
+        this.texts = {
+            vi: new Map(options.bundles.flatMap((bundle) => Object.entries(bundle.vi))),
+            en: new Map(options.bundles.flatMap((bundle) => Object.entries(bundle.en))),
+        }
+    }
+
+    /** The text of `key` in `locale` with placeholders filled; a placeholder without a value stays as written. */
+    get(key: string, params: MessageParams, locale: Locale): string {
+        const text = this.texts[locale].get(key)
+        if (text === undefined) return key
+        return text.replace(PLACEHOLDER, (placeholder, name: string) => {
+            const value = params[name]
+            return value === undefined ? placeholder : String(value)
+        })
+    }
+}

package/templates/be/skeleton/src/modules/platform/i18n/i18n.contracts.ts

@@ -0,0 +1,18 @@
+/** The languages a catalog carries: Vietnamese and English, both complete. */
+export type Locale = "vi" | "en"
+
+/** The value of an `Accept-Language` request header: one line, several lines, or absent. */
+export type AcceptLanguage = string | ReadonlyArray<string> | undefined
+
+/** Values that fill the `{{name}}` placeholders of a message. */
+export interface MessageParams {
+    readonly [name: string]: string | number
+}
+
+/** What an owner writes in its `messages/<owner>.messages.ts`: one flat key to text map per language, the same keys in each. */
+export interface MessageBundle {
+    /** Vietnamese texts by key. */
+    readonly vi: Readonly<Record<string, string>>
+    /** English texts by key. */
+    readonly en: Readonly<Record<string, string>>
+}

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

@@ -0,0 +1,23 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { I18nOptions } from "./i18n.options"
+import type { MessageCatalog, RequestLocale } from "./i18n.port"
+
+/** Token of the i18n options, exported so a spec can provide it. */
+export const I18N_OPTIONS: unique symbol = Symbol("platform.i18n.options")
+
+/** Token of the MessageCatalog port. */
+export const MESSAGE_CATALOG: unique symbol = Symbol("platform.i18n.message-catalog")
+
+/** Token of the RequestLocale port. */
+export const REQUEST_LOCALE: unique symbol = Symbol("platform.i18n.request-locale")
+
+/** Injects the options of the i18n capability. Parameter type: I18nOptions. */
+export const InjectI18nOptions = (): TypedParameterDecorator<I18nOptions> => injector<I18nOptions>(I18N_OPTIONS)
+
+/** Injects the MessageCatalog port. Parameter type: MessageCatalog. */
+export const InjectMessageCatalog = (): TypedParameterDecorator<MessageCatalog> =>
+    injector<MessageCatalog>(MESSAGE_CATALOG)
+
+/** Injects the RequestLocale port. Parameter type: RequestLocale. */
+export const InjectRequestLocale = (): TypedParameterDecorator<RequestLocale> => injector<RequestLocale>(REQUEST_LOCALE)

package/templates/be/skeleton/src/modules/platform/i18n/i18n.module-definition.ts

@@ -0,0 +1,9 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { I18N_OPTIONS } from "./i18n.decorators"
+import type { I18nOptions } from "./i18n.options"
+
+/** The configurable-module base of the i18n capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<I18nOptions>({ optionsInjectionToken: I18N_OPTIONS })
+        .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+        .build()