@starci/hfs 3.0.0 → 4.0.0

package/templates/app/skeleton/README.md

@@ -0,0 +1,36 @@
+# {{project}}
+
+One StarCi app: its back end in be/, its front end in fe/, one install at the root.
+
+## Overview
+
+The app starts with one api app (be/apps/api), one Next app (fe/apps/web) and the liveness probe both serve.
+
+## Stack
+
+TypeScript everywhere; NestJS in be/, Next.js with next-intl in fe/; npm with one package.json and one lockfile at the root.
+
+## Repository layout
+
+- `be/`: the back end, `apps/<app>/src` composes `src/features` and `src/modules`; its tests live under `src/tests`.
+- `fe/`: the front end, one Next app per `apps/<app>`.
+- `scripts/`: the app's operational scripts; `hfs.json` declares both sides.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm run lint
+npm test
+npm run build:be
+npm run build:fe
+```
+
+The api app reads `PORT` and `HTTP_SECURITY_ALLOWED_ORIGINS` (comma-separated origins allowed to send state-changing browser
+requests) at boot; every door is closed until it is marked public or sign-in is designed. The web app reads
+`NEXT_PUBLIC_SITE_URL`. A missing key stops the process with an error that names it.
+
+## Work
+
+The product's Work records live in `.starciwork`.

package/templates/app/skeleton/scripts/codegen.mjs

@@ -0,0 +1,4 @@
+// codegen.mjs - the app's generated code, the one step behind `npm run codegen` (lint, typecheck, dev and build run it first).
+// The front end reads the back end's committed contracts in place (be/contracts/, hfs.json sides.fe.reads) and generates its
+// client from them into a gitignored __generated__/ folder. A new app has no contract yet, so there is nothing to generate.
+process.stdout.write("codegen: no contract under be/contracts yet\n")

package/templates/{fe → app}/tool-config/prettierignore

@@ -1,10 +1,13 @@
 {{header}}
 node_modules/
-.next/
 dist/
 coverage/
 reports/
+.next/
 .starci/
 package-lock.json
+contracts/
+.starcistacks/
+.starciwork/
 **/__generated__/
 **/messages/**

package/templates/be/skeleton/.sops.yaml

@@ -0,0 +1,2 @@
+# Set a project-owned age recipient before encrypting the first secret.
+creation_rules: []

package/templates/be/skeleton/.starcistacks/application-stacks.yaml

@@ -0,0 +1,10 @@
+schema: starci/application-stacks@1
+services:
+  sonar:
+    provider: sonarqube
+    mode: local
+    qualityGate: {{sonarGate}}
+    stack:
+      owner: host
+      root: .claude/ext/sonar
+      environment: dev

package/templates/be/skeleton/apps/__app__/src/__app__.options.ts

@@ -1,7 +1,10 @@
+import type { HttpSecurityOptions } from "@modules/platform/http-security"
 import type { ServerOptions } from "@modules/platform/config"
 
 /** Everything the {{app}} app needs from its environment, parsed once by `main.ts` and handed to `AppModule.register`. */
 export interface {{appPascal}}Options {
     /** The HTTP listener. */
     readonly server: ServerOptions
+    /** The origin allowlist and rate limits. */
+    readonly httpSecurity: HttpSecurityOptions
 }

package/templates/be/skeleton/apps/__app__/src/app.module.ts

@@ -1,17 +1,26 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
-import { APP_FILTER } from "@nestjs/core"
+import { APP_FILTER, APP_GUARD } from "@nestjs/core"
 import { SystemHealthHttpModule } from "@features/system-health"
+import { AuthGuard, IDENTITY_ERROR_KINDS, IDENTITY_MESSAGES, IdentityModule } from "@modules/domain/identity"
 import { LivenessModule } from "@modules/domain/liveness"
 import { ClockModule } from "@modules/platform/clock"
-import { SERVER_OPTIONS } from "@modules/platform/config"
+import { CONFIG_ERROR_KINDS } from "@modules/platform/config"
 import { CqrsModule } from "@modules/platform/cqrs"
-import { ErrorFilter } from "@modules/platform/errors"
+import { ERRORS_MESSAGES, ErrorsFilter, ErrorsModule } from "@modules/platform/errors"
+import {
+    HTTP_SECURITY_ERROR_KINDS,
+    HTTP_SECURITY_MESSAGES,
+    HttpSecurityModule,
+    OriginGuard,
+    RateLimitGuard,
+} from "@modules/platform/http-security"
+import { I18nModule } from "@modules/platform/i18n"
 import { LoggingModule } from "@modules/platform/logging"
 import type { {{appPascal}}Options } from "./{{app}}.options"
 
 @Module({})
-/** Composition root of the {{app}} app: every capability is registered once, app-wide, the features it runs and its one error filter. */
+/** Composition root of the {{app}} app: every capability is registered once, app-wide, and the three guards run in a fixed order. */
 export class AppModule {
     /** Builds the module from options parsed once at boot; nothing here reads the environment. */
     static register(options: {{appPascal}}Options): DynamicModule {
@@ -20,13 +29,25 @@ export class AppModule {
             imports: [
                 ClockModule.register({ isGlobal: true }),
                 LoggingModule.register({ isGlobal: true }),
+                I18nModule.register({
+                    isGlobal: true,
+                    bundles: [ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
+                }),
+                ErrorsModule.register({
+                    isGlobal: true,
+                    kinds: [CONFIG_ERROR_KINDS, HTTP_SECURITY_ERROR_KINDS, IDENTITY_ERROR_KINDS],
+                }),
                 CqrsModule.register({ isGlobal: true }),
+                HttpSecurityModule.register({ isGlobal: true, ...options.httpSecurity }),
+                IdentityModule.register({ isGlobal: true }),
                 LivenessModule.register({ isGlobal: true }),
                 SystemHealthHttpModule,
             ],
             providers: [
-                { provide: SERVER_OPTIONS, useValue: options.server },
-                { provide: APP_FILTER, useClass: ErrorFilter },
+                { provide: APP_FILTER, useClass: ErrorsFilter },
+                { provide: APP_GUARD, useClass: RateLimitGuard },
+                { provide: APP_GUARD, useClass: OriginGuard },
+                { provide: APP_GUARD, useClass: AuthGuard },
             ],
         }
     }

package/templates/be/skeleton/apps/__app__/src/main.ts

@@ -1,14 +1,17 @@
 import { NestFactory } from "@nestjs/core"
 import { SystemClockService } from "@modules/platform/clock"
 import { EnvSource, parseServerConfig } from "@modules/platform/config"
+import { parseHttpSecurityConfig } from "@modules/platform/http-security"
 import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
 import { AppModule } from "./app.module"
 import type { {{appPascal}}Options } from "./{{app}}.options"
 
 /** Reads the environment once, composes the app from the parsed options and serves until a shutdown signal. */
 const bootstrap = async (): Promise<void> => {
-    const options: {{appPascal}}Options = { server: parseServerConfig(EnvSource.fromProcess()) }
+    const env = EnvSource.fromProcess()
+    const options: {{appPascal}}Options = { server: parseServerConfig(env), httpSecurity: parseHttpSecurityConfig(env) }
     const app = await NestFactory.create(AppModule.register(options))
+    app.enableCors({ origin: [...options.httpSecurity.allowedOrigins] })
     app.enableShutdownHooks()
     await app.listen(options.server.port)
     createJsonLogger(new SystemClockService()).info(LoggingLogEvent.ServerStarted, {

package/templates/be/skeleton/src/features/system-health/transport/http/live.controller.ts

@@ -1,5 +1,6 @@
 import { Controller, Get } from "@nestjs/common"
 import type { QueryBus } from "@nestjs/cqrs"
+import { Public, PublicReason } from "@modules/domain/identity"
 import type { LivenessReport } from "@modules/domain/liveness"
 import { InjectQueryBus } from "@modules/platform/cqrs"
 import { CheckLivenessQuery } from "../../application/check-liveness.query"
@@ -11,6 +12,7 @@ export class LiveController {
 
     /** Reports the process alive while its event loop still answers requests. */
     @Get("live")
+    @Public({ reason: PublicReason.Health })
     live(): Promise<LivenessReport> {
         return this.queryBus.execute(new CheckLivenessQuery({ request: {} }))
     }

package/templates/be/skeleton/src/modules/domain/identity/admission.policy.ts

@@ -0,0 +1,11 @@
+import { ok, refused } from "@modules/platform/primitives"
+import type { Outcome } from "@modules/platform/primitives"
+import { IdentityErrorCode } from "./errors/identity.error"
+import type { PublicMetadata, PublicReason } from "./identity.contracts"
+
+/**
+ * The default-deny decision of one door: a door that states why it is public is admitted; every other door is refused
+ * until the design that adds sign-in establishes a caller here.
+ */
+export const admit = (metadata: PublicMetadata | undefined): Outcome<PublicReason, IdentityErrorCode> =>
+    metadata === undefined ? refused(IdentityErrorCode.Unauthenticated) : ok(metadata.reason)

package/templates/be/skeleton/src/modules/domain/identity/auth.guard.ts

@@ -0,0 +1,25 @@
+import { Injectable } from "@nestjs/common"
+import type { CanActivate, ExecutionContext } from "@nestjs/common"
+import type { Reflector } from "@nestjs/core"
+import { InjectReflector } from "@modules/platform/composition"
+import { unwrapOutcome } from "@modules/platform/primitives"
+import { admit } from "./admission.policy"
+import { IdentityError } from "./errors/identity.error"
+import type { PublicMetadata } from "./identity.contracts"
+import { PUBLIC_KEY } from "./identity.decorators"
+
+@Injectable()
+/** The third app guard and the default-deny gate: a door is open only when it says `@Public({ reason })`. */
+export class AuthGuard implements CanActivate {
+    constructor(@InjectReflector() private readonly reflector: Reflector) {}
+
+    /** Lets public doors through and refuses every other door. */
+    canActivate(context: ExecutionContext): boolean {
+        const metadata = this.reflector.getAllAndOverride<PublicMetadata | undefined>(PUBLIC_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ])
+        unwrapOutcome(admit(metadata), IdentityError)
+        return true
+    }
+}

package/templates/be/skeleton/src/modules/domain/identity/errors/identity.error.ts

@@ -0,0 +1,16 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the identity capability. */
+export enum IdentityErrorCode {
+    /** The door needs a signed-in caller and the request establishes none. */
+    Unauthenticated = "IDENTITY_UNAUTHENTICATED",
+}
+
+/** How each identity code travels. */
+export const IDENTITY_ERROR_KINDS: Record<IdentityErrorCode, ErrorKind> = {
+    [IdentityErrorCode.Unauthenticated]: "unauthenticated",
+}
+
+/** The one error class of the identity capability. */
+export class IdentityError extends DomainError<IdentityErrorCode> {}

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

@@ -0,0 +1,11 @@
+/** Why a door is open to anonymous callers; the vocabulary is closed. */
+export enum PublicReason {
+    /** Liveness and readiness probes. */
+    Health = "health",
+}
+
+/** The metadata `@Public` attaches to a door. */
+export interface PublicMetadata {
+    /** Why the door is anonymous. */
+    readonly reason: PublicReason
+}

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

@@ -0,0 +1,8 @@
+import { SetMetadata } from "@nestjs/common"
+import type { PublicMetadata } from "./identity.contracts"
+
+/** Metadata key of `@Public`. */
+export const PUBLIC_KEY = "domain.identity.public"
+
+/** Opens a door to anonymous callers, stating why; every other door needs a signed-in caller. */
+export const Public = (metadata: PublicMetadata): ReturnType<typeof SetMetadata> => SetMetadata(PUBLIC_KEY, metadata)

package/templates/be/skeleton/src/modules/domain/identity/identity.module-definition.ts

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

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

@@ -0,0 +1,14 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { AuthGuard } from "./auth.guard"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./identity.module-definition"
+
+@Module({})
+/** The identity capability: the guard that closes every door by default. The app registers AuthGuard itself after the throttler and the origin guard. */
+export class IdentityModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return { ...base, providers: [...(base.providers ?? []), AuthGuard], exports: [AuthGuard] }
+    }
+}

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

@@ -0,0 +1,2 @@
+/** The identity capability takes no options yet; the empty record keeps `isGlobal` assignable through the configurable module. */
+export type IdentityOptions = Record<never, never>

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

@@ -0,0 +1,6 @@
+export { AuthGuard } from "./auth.guard"
+export { IDENTITY_ERROR_KINDS } from "./errors/identity.error"
+export { IDENTITY_MESSAGES } from "./messages/identity.messages"
+export { PublicReason } from "./identity.contracts"
+export { Public } from "./identity.decorators"
+export { IdentityModule } from "./identity.module"

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

@@ -0,0 +1,11 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the identity codes, Vietnamese and English. */
+export const IDENTITY_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.IDENTITY_UNAUTHENTICATED": "Bạn cần đăng nhập để thực hiện thao tác này.",
+    },
+    en: {
+        "errors.IDENTITY_UNAUTHENTICATED": "You need to sign in to do this.",
+    },
+}

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

@@ -1,8 +1,15 @@
 import { Inject } from "@nestjs/common"
 import type { InjectionToken } from "@nestjs/common"
+import { Reflector } from "@nestjs/core"
 
 /** A parameter decorator that remembers the type `T` it injects, so a lint rule can compare it with the parameter annotation. */
-export type TypedParameterDecorator<T> = ParameterDecorator & { readonly __injects?: T }
+export type TypedParameterDecorator<T> = ParameterDecorator & {
+    /** Never set at run time: it carries `T` so the lint rule can compare it with the parameter annotation. */
+    readonly __injects?: T
+}
 
 /** Builds the parameter decorator that injects `token`, typed with the value it injects. Every `Inject<Thing>()` is built with it. */
 export const injector = <T>(token: InjectionToken): TypedParameterDecorator<T> => Inject(token)
+
+/** Injects the framework Reflector that guards read handler metadata with. Parameter type: Reflector. */
+export const InjectReflector = (): TypedParameterDecorator<Reflector> => injector<Reflector>(Reflector)

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

@@ -1,2 +1,2 @@
-export { injector } from "./composition.decorators"
+export { InjectReflector, injector } from "./composition.decorators"
 export type { TypedParameterDecorator } from "./composition.decorators"

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

@@ -1,40 +1,88 @@
 import { readFileSync } from "node:fs"
-import { ConfigError } from "./errors/config.error"
+import { ConfigError, ConfigErrorCode } from "./errors/config.error"
 
-type Values = Readonly<Record<string, string | undefined>>
+const FILE_SUFFIX = "_FILE"
+const DURATION_UNITS: Readonly<Record<string, number>> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }
+const DURATION_PATTERN = /^(\d+)(ms|s|m|h)?$/
 
-/** The only reader of the process environment. Every key may instead be supplied as `<KEY>_FILE`, a path to its value. */
+/**
+ * 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.
+ */
 export class EnvSource {
-    private constructor(private readonly values: Values) {}
+    constructor(private readonly values: Readonly<Record<string, string | undefined>>) {}
 
-    /** The live process environment; called once, from `main.ts`. */
+    /** Reads the process environment once, resolving every `<KEY>_FILE` into `<KEY>`. */
     static fromProcess(): EnvSource {
-        return new EnvSource(process.env)
+        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()
+        }
+        return new EnvSource(values)
     }
 
-    /** A fixed snapshot, for specs and tools. */
-    static of(values: Values): EnvSource {
-        return new EnvSource(values)
+    /** True when the key is declared and not empty. */
+    has(key: string): boolean {
+        return Boolean(this.values[key])
+    }
+
+    /** True when at least one of the keys is declared: the switch of an all-or-nothing optional integration. */
+    anyDeclared(keys: ReadonlyArray<string>): boolean {
+        return keys.some((key) => this.has(key))
     }
 
-    /** The value of `key`, or `undefined` when it is unset or empty. */
+    /** The declared value of an optional key, or undefined. */
     optional(key: string): string | undefined {
-        const path = this.values[`${key}_FILE`]
-        if (path !== undefined && path !== "") {
-            try {
-                return readFileSync(path, "utf8").trim()
-            } catch (cause) {
-                throw new ConfigError("CONFIG_FILE_UNREADABLE", `${key}_FILE`, { cause })
-            }
-        }
+        return this.values[key] || undefined
+    }
+
+    /** A required string. */
+    string(key: string): string {
         const value = this.values[key]
-        return value === undefined || value === "" ? undefined : value
+        if (!value) throw new ConfigError({ code: ConfigErrorCode.KeyMissing, params: { key } })
+        return value
     }
 
-    /** The value of `key`; a missing key stops the boot with an error that names it. */
-    required(key: string): string {
-        const value = this.optional(key)
-        if (value === undefined) throw new ConfigError("CONFIG_KEY_MISSING", key)
+    /** A required integer, or the literal `fallback` when the key is not declared (tunables only). */
+    int(key: string, fallback?: number): number {
+        if (!this.has(key) && fallback !== undefined) return fallback
+        const value = Number(this.string(key))
+        if (!Number.isInteger(value)) throw new ConfigError({ code: ConfigErrorCode.KeyInvalid, params: { key } })
         return value
     }
+
+    /** A required boolean (`true` or `false`), or the literal `fallback` when not declared (tunables only). */
+    bool(key: string, fallback?: boolean): boolean {
+        if (!this.has(key) && fallback !== undefined) return fallback
+        const value = this.string(key)
+        if (value !== "true" && value !== "false")
+            throw new ConfigError({ code: ConfigErrorCode.KeyInvalid, params: { key } })
+        return value === "true"
+    }
+
+    /** A required absolute URL, returned as written. */
+    url(key: string): string {
+        const value = this.string(key)
+        if (!URL.canParse(value)) throw new ConfigError({ code: ConfigErrorCode.KeyInvalid, params: { key } })
+        return value
+    }
+
+    /** A required value that must be one of `allowed`. */
+    enum<T extends string>(key: string, allowed: ReadonlyArray<T>): T {
+        const value = this.string(key)
+        const found = allowed.find((candidate) => candidate === value)
+        if (found === undefined) throw new ConfigError({ code: ConfigErrorCode.KeyInvalid, params: { key } })
+        return found
+    }
+
+    /** A duration in milliseconds: `250`, `250ms`, `30s`, `5m` or `2h`; the literal `fallback` applies when not declared (tunables only). */
+    duration(key: string, fallback?: number): number {
+        if (!this.has(key) && fallback !== undefined) return fallback
+        const match = DURATION_PATTERN.exec(this.string(key))
+        const unit = DURATION_UNITS[match?.[2] ?? "ms"]
+        if (!match?.[1] || unit === undefined)
+            throw new ConfigError({ code: ConfigErrorCode.KeyInvalid, params: { key } })
+        return Number(match[1]) * unit
+    }
 }

package/templates/be/skeleton/src/modules/platform/config/errors/config.error.ts

@@ -1,21 +1,19 @@
 import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
 
-/** Why a configuration key was refused. */
-export type ConfigErrorCode = "CONFIG_KEY_MISSING" | "CONFIG_KEY_INVALID" | "CONFIG_FILE_UNREADABLE"
-
-const REASONS: Readonly<Record<ConfigErrorCode, string>> = {
-    CONFIG_KEY_MISSING: "is required and has no default",
-    CONFIG_KEY_INVALID: "does not hold a valid value",
-    CONFIG_FILE_UNREADABLE: "points at a file that cannot be read",
+/** Codes of the config capability; both are boot failures that name the offending key in the params. */
+export enum ConfigErrorCode {
+    /** A required key is not declared in the environment. */
+    KeyMissing = "CONFIG_KEY_MISSING",
+    /** A declared key does not parse as the type its reader expects. */
+    KeyInvalid = "CONFIG_KEY_INVALID",
 }
 
-/** Startup configuration refusal: names the key and the rule it broke, never the value it was given. */
-export class ConfigError extends DomainError {
-    /** The environment key that was refused. */
-    readonly key: string
-
-    constructor(code: ConfigErrorCode, key: string, options?: { readonly cause?: unknown }) {
-        super(code, `Configuration key ${key} ${REASONS[code]}.`, options)
-        this.key = key
-    }
+/** How each config code travels. */
+export const CONFIG_ERROR_KINDS: Record<ConfigErrorCode, ErrorKind> = {
+    [ConfigErrorCode.KeyMissing]: "internal",
+    [ConfigErrorCode.KeyInvalid]: "internal",
 }
+
+/** The one error class of the config capability. */
+export class ConfigError extends DomainError<ConfigErrorCode> {}

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

@@ -1,4 +1,4 @@
-export { SERVER_OPTIONS } from "./config.decorators"
 export { EnvSource } from "./env-source.config"
+export { CONFIG_ERROR_KINDS } from "./errors/config.error"
 export { parseServerConfig } from "./server.config"
 export type { ServerOptions } from "./server.options"

package/templates/be/skeleton/src/modules/platform/config/server.config.ts

@@ -1,15 +1,5 @@
 import type { EnvSource } from "./env-source.config"
-import { ConfigError } from "./errors/config.error"
 import type { ServerOptions } from "./server.options"
 
-const DEFAULT_PORT = 3000
-const MAX_PORT = 65535
-
-/** Parses the server keys of an environment; a malformed PORT stops the boot. */
-export const parseServerConfig = (env: EnvSource): ServerOptions => {
-    const raw = env.optional("PORT")
-    if (raw === undefined) return { port: DEFAULT_PORT }
-    const port = Number(raw)
-    if (!Number.isInteger(port) || port < 1 || port > MAX_PORT) throw new ConfigError("CONFIG_KEY_INVALID", "PORT")
-    return { port }
-}
+/** Parses the server keys of an environment; a missing or malformed PORT stops the boot. */
+export const parseServerConfig = (env: EnvSource): ServerOptions => ({ port: env.int("PORT") })

package/templates/be/skeleton/src/modules/platform/errors/domain.error.ts

@@ -1,11 +1,20 @@
-/** The base of every error a capability declares: a stable machine code, a sentence for people, and the cause. */
-export abstract class DomainError extends Error {
-    /** Stable machine code that transports map to a status and logs group by. */
-    readonly code: string
+import type { DomainErrorInit, ErrorParams } from "./errors.contracts"
 
-    constructor(code: string, message: string, options?: { readonly cause?: unknown }) {
-        super(message, options)
+/**
+ * The base of every capability error family: a stable code, text parameters and the cause. The message is the code
+ * itself; display text is resolved from the message catalog by code, so an error never carries prose.
+ */
+export abstract class DomainError<C extends string> extends Error {
+    /** The stable machine code, `<CAPABILITY>_<WHAT>`. */
+    readonly code: C
+
+    /** Values for the placeholders of the display text. */
+    readonly params: ErrorParams
+
+    constructor(init: DomainErrorInit<C>) {
+        super(init.code, init.cause === undefined ? undefined : { cause: init.cause })
         this.name = new.target.name
-        this.code = code
+        this.code = init.code
+        this.params = init.params ?? {}
     }
 }

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

@@ -0,0 +1,16 @@
+import { DomainError } from "../domain.error"
+import type { ErrorKind } from "../errors.contracts"
+
+/** Codes of the errors capability: the answer it gives for a failure no capability declared. */
+export enum ErrorsErrorCode {
+    /** A failure no capability declared; the transport masks its details. */
+    Internal = "ERRORS_INTERNAL",
+}
+
+/** How each errors code travels. */
+export const ERRORS_ERROR_KINDS: Record<ErrorsErrorCode, ErrorKind> = {
+    [ErrorsErrorCode.Internal]: "internal",
+}
+
+/** The one error class of the errors capability. */
+export class ErrorsError extends DomainError<ErrorsErrorCode> {}

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

@@ -0,0 +1,33 @@
+/** How a failure travels: the transport maps each kind to one HTTP status. */
+export type ErrorKind =
+    "invalid" | "unauthenticated" | "forbidden" | "not-found" | "conflict" | "rate-limited" | "unavailable" | "internal"
+
+/** Values that fill the named placeholders of an error text and travel next to the code; never prose. */
+export interface ErrorParams {
+    readonly [name: string]: string | number
+}
+
+/** What a capability error is built from: its code, optional text parameters and the failure that caused it. */
+export interface DomainErrorInit<C extends string> {
+    /** The capability code, `<CAPABILITY>_<WHAT>`. */
+    readonly code: C
+    /** Values for the placeholders of the display text. */
+    readonly params?: ErrorParams
+    /** The failure that caused this one, kept for the log. */
+    readonly cause?: unknown
+}
+
+/** One capability's exhaustive code to kind table, as its `<C>_ERROR_KINDS` constant declares it. */
+export type ErrorKindTable = Readonly<Record<string, ErrorKind>>
+
+/** Everything a transport needs to answer one failure: the stable code, the kind, the HTTP status and the parameters. */
+export interface ErrorDescription {
+    /** The stable machine code. */
+    readonly code: string
+    /** How the failure travels. */
+    readonly kind: ErrorKind
+    /** The HTTP status of the kind. */
+    readonly status: number
+    /** Values for the placeholders of the display text. */
+    readonly params: ErrorParams
+}

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

@@ -0,0 +1,16 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { ErrorsOptions } from "./errors.options"
+import type { ErrorsService } from "./errors.service"
+
+/** Token of the errors options, exported so a spec can provide it. */
+export const ERRORS_OPTIONS: unique symbol = Symbol("platform.errors.options")
+
+/** Token of the service that describes failures for the transports. */
+export const ERRORS_SERVICE: unique symbol = Symbol("platform.errors.service")
+
+/** Injects the options of the errors capability. Parameter type: ErrorsOptions. */
+export const InjectErrorsOptions = (): TypedParameterDecorator<ErrorsOptions> => injector<ErrorsOptions>(ERRORS_OPTIONS)
+
+/** Injects the service that describes failures for the transports. Parameter type: ErrorsService. */
+export const InjectErrorsService = (): TypedParameterDecorator<ErrorsService> => injector<ErrorsService>(ERRORS_SERVICE)