@starci/hfs 5.2.0 → 5.4.0

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

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { IdentityOptions } from "./identity.options"
 
-const built = new ConfigurableModuleBuilder<IdentityOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<IdentityOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the identity capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<IdentityOptions>()

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

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { LivenessOptions } from "./liveness.options"
 
-const built = new ConfigurableModuleBuilder<LivenessOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<LivenessOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the liveness capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<LivenessOptions>()

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

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { NoteOptions } from "./note.options"
 
-const built = new ConfigurableModuleBuilder<NoteOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<NoteOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the note capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<NoteOptions>()

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

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { ClockOptions } from "./clock.options"
 
-const built = new ConfigurableModuleBuilder<ClockOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<ClockOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the clock capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<ClockOptions>()

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

@@ -6,6 +6,8 @@ export interface Principal {
     readonly email?: string
     /** The authenticated provider role. */
     readonly role: "authenticated"
+    /** The device session the access token belongs to, when the token names one. */
+    readonly sessionId?: string
 }
 
 /** The params of an authenticated operation: its mapped request and verified caller. */

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

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { CqrsOptions } from "./cqrs.options"
 
-const built = new ConfigurableModuleBuilder<CqrsOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<CqrsOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the cqrs capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<CqrsOptions>()

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

@@ -1,18 +1,8 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import { DATABASE_OPTIONS } from "./database.port"
 import type { DatabaseOptions } from "./database.options"
 
-const built = new ConfigurableModuleBuilder<DatabaseOptions>({
+/** The configurable-module base of the database capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<DatabaseOptions>({
     optionsInjectionToken: DATABASE_OPTIONS,
 })
-    .setExtras({ isGlobal: false }, (definition, extras) => ({
-        ...definition,
-        global: extras.isGlobal,
-    }))
-    .build()
-type Host = ConfigurableModuleHost<DatabaseOptions, "register", "create", { isGlobal: boolean }>
-
-/** The configurable-module base of the database capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

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

@@ -1,15 +1,8 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import { ERRORS_OPTIONS } from "./errors.decorators"
 import type { ErrorsOptions } from "./errors.options"
 
-const built = new ConfigurableModuleBuilder<ErrorsOptions>({ optionsInjectionToken: ERRORS_OPTIONS })
-        .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-        .build()
-type Host = ConfigurableModuleHost<ErrorsOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the errors capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The injection token of the registered options. */
-export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = defineCapabilityModule<ErrorsOptions>({
+    optionsInjectionToken: ERRORS_OPTIONS,
+})

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

@@ -1,13 +1,8 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import { HTTP_OPTIONS } from "./http.decorators"
 import type { HttpOptions } from "./http.options"
 
-const built = new ConfigurableModuleBuilder<HttpOptions>({ optionsInjectionToken: HTTP_OPTIONS })
-        .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-        .build()
-type Host = ConfigurableModuleHost<HttpOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the http capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<HttpOptions>({
+    optionsInjectionToken: HTTP_OPTIONS,
+})

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

@@ -1,15 +1,9 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
 
-const built = new ConfigurableModuleBuilder<HttpSecurityOptions>({ optionsInjectionToken: HTTP_SECURITY_OPTIONS })
-        .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-        .build()
-type Host = ConfigurableModuleHost<HttpSecurityOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the http-security capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The injection token of the registered options. */
-export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    defineCapabilityModule<HttpSecurityOptions>({
+        optionsInjectionToken: HTTP_SECURITY_OPTIONS,
+    })

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

@@ -1,15 +1,8 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import { I18N_OPTIONS } from "./i18n.decorators"
 import type { I18nOptions } from "./i18n.options"
 
-const built = new ConfigurableModuleBuilder<I18nOptions>({ optionsInjectionToken: I18N_OPTIONS })
-        .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-        .build()
-type Host = ConfigurableModuleHost<I18nOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the i18n capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The injection token of the registered options. */
-export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = defineCapabilityModule<I18nOptions>({
+    optionsInjectionToken: I18N_OPTIONS,
+})

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

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { IdsOptions } from "./ids.options"
 
-const built = new ConfigurableModuleBuilder<IdsOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<IdsOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the ids capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<IdsOptions>()

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

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { LoggingOptions } from "./logging.options"
 
-const built = new ConfigurableModuleBuilder<LoggingOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<LoggingOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the logging capability; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<LoggingOptions>()

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

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { RetryOptions } from "./retry.options"
 
-const built = new ConfigurableModuleBuilder<RetryOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<RetryOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the retry capability; the app root decides its global scope. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<RetryOptions>()

package/templates/be/skeleton-lite/apps/api/src/api.env.ts

@@ -4,6 +4,7 @@ import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
 import { parseHttpConfig } from "@modules/platform/http"
 import { parseHttpSecurityConfig } from "@modules/platform/http-security"
 import { parsePassportConfig } from "@modules/integrations/passport"
+import { parseMailConfig } from "@modules/integrations/mail"
 import { parseObjectStorageConfig } from "@modules/integrations/object-storage"
 
 /** The API environment values required before composition. */
@@ -20,6 +21,8 @@ export interface ApiEnv {
     readonly passport: ReturnType<typeof parsePassportConfig>
     /** S3-compatible object storage. */
     readonly objectStorage: ReturnType<typeof parseObjectStorageConfig>
+    /** Outgoing mail: the SMTP server and the app's own mail settings. */
+    readonly mail: ReturnType<typeof parseMailConfig>
 }
 
 /** Reads the API environment; missing or invalid values fail boot, and secrets use `_FILE` first. */
@@ -30,4 +33,5 @@ export const readApiEnv = (env: EnvSource): ApiEnv => ({
     database: parsePrimaryDatabaseConfig(env),
     passport: parsePassportConfig(env),
     objectStorage: parseObjectStorageConfig(env),
+    mail: parseMailConfig(env),
 })

package/templates/be/skeleton-lite/apps/api/src/api.options.ts

@@ -1,4 +1,5 @@
 import type { PassportOptions } from "@modules/integrations/passport"
+import type { MailOptions } from "@modules/integrations/mail"
 import type { ObjectStorageOptions } from "@modules/integrations/object-storage"
 import type { ServerOptions } from "@modules/platform/config"
 import type { DatabaseConnectionOptions } from "@modules/platform/database"
@@ -19,4 +20,6 @@ export interface ApiOptions {
     readonly passport: PassportOptions
     /** S3-compatible object storage. */
     readonly objectStorage: ObjectStorageOptions
+    /** Outgoing mail: the SMTP server and the app's own mail settings. */
+    readonly mail: MailOptions
 }

package/templates/be/skeleton-lite/apps/api/src/compose/integrations.ts

@@ -1,13 +1,15 @@
 import type { DynamicModule, Provider } from "@nestjs/common"
 import { OWN_TOKEN_VERIFIER, PASSPORT_OPTIONS, passportModule } from "@modules/integrations/passport"
 import type { VerifyAccessToken } from "@modules/integrations/passport"
+import { MailModule } from "@modules/integrations/mail"
 import { ObjectStorageModule } from "@modules/integrations/object-storage"
 import type { ApiOptions } from "../api.options"
 
-/** The sign-in and object storage packages of the app, each registered once with the app's typed settings. */
+/** The sign-in, object storage and mail packages of the app, each registered once with the app's typed settings. */
 export const integrationModules = (options: ApiOptions): Array<DynamicModule> => [
     passportModule(options.passport, { isGlobal: true }),
     ObjectStorageModule.register({ ...options.objectStorage, isGlobal: true }),
+    MailModule.register({ ...options.mail, isGlobal: true }),
 ]
 
 /** The passport integration ports bound once for this app. */

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

@@ -17,6 +17,10 @@ export enum IdentityErrorCode {
     PairRefused = "IDENTITY_INVALID_CREDENTIALS",
     /** The mailbox was never confirmed. */
     EmailNotConfirmed = "IDENTITY_EMAIL_NOT_CONFIRMED",
+    /** The new password does not fit the policy (at least 8 characters, at most 72 bytes). */
+    PasswordInvalid = "IDENTITY_PASSWORD_INVALID",
+    /** The confirmation or reset link is unknown, expired or already spent. */
+    ResetTokenInvalid = "IDENTITY_RESET_TOKEN_INVALID",
 }
 
 /** How each identity code travels. */
@@ -28,6 +32,8 @@ export const IDENTITY_ERROR_KINDS: Record<IdentityErrorCode, ErrorKind> = {
     [IdentityErrorCode.TooManyAttempts]: "rate-limited",
     [IdentityErrorCode.PairRefused]: "unauthenticated",
     [IdentityErrorCode.EmailNotConfirmed]: "forbidden",
+    [IdentityErrorCode.PasswordInvalid]: "invalid",
+    [IdentityErrorCode.ResetTokenInvalid]: "invalid",
 }
 
 /** The one error class of the identity capability. */

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

@@ -26,6 +26,7 @@ import {
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./identity.module-definition"
 import { IdentityRateCounterService } from "./rate-counter.service"
 import { IdentitySessionStoreService } from "./session-store.service"
+import { IdentityEmailService } from "./identity-email.service"
 import { IdentitySignInService } from "./sign-in.service"
 
 const refusingAuthenticator: Provider = {
@@ -61,6 +62,7 @@ export class IdentityModule extends ConfigurableModuleClass {
                 IdentityRateCounterService,
                 IdentityAuthenticatorService,
                 IdentitySignInService,
+                IdentityEmailService,
                 { provide: IDENTITY_AUTH_DOORS, useExisting: PASSPORT_DOORS },
                 { provide: IDENTITY_AUTH_SESSIONS, useExisting: PASSPORT_SESSIONS },
                 { provide: IDENTITY_AUTH_PASSWORDS, useExisting: PASSPORT_PASSWORDS },
@@ -76,6 +78,7 @@ export class IdentityModule extends ConfigurableModuleClass {
                 AuthGuard,
                 ACCESS_TOKEN_VERIFIER,
                 IdentitySignInService,
+                IdentityEmailService,
                 PASSPORT_SESSION_STORE,
                 PASSPORT_ACCOUNTS,
                 PASSPORT_RATE_COUNTER,

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

@@ -6,4 +6,5 @@ export { PublicReason } from "./identity.contracts"
 export { ACCESS_TOKEN_VERIFIER, Public } from "./identity.decorators"
 export { IdentityModule } from "./identity.module"
 export { identityEntities } from "./persistence/entities"
+export { IdentityEmailService } from "./identity-email.service"
 export { IdentitySignInService } from "./sign-in.service"

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

@@ -0,0 +1,65 @@
+import { renderTransactional } from "@modules/integrations/mail"
+import type { MailLanguage, RenderedMail } from "@modules/integrations/mail"
+
+/** What a confirmation or reset mail is drawn from. */
+export interface LinkMailInput {
+    /** The product name in the header. */
+    readonly brand: string
+    /** The absolute link the button opens. */
+    readonly url: string
+    /** How many hours the link lives. */
+    readonly hours: number
+}
+
+interface LinkCopy {
+    readonly subject: string
+    readonly paragraphs: (input: LinkMailInput) => readonly string[]
+    readonly button: string
+    readonly footer: string
+}
+
+const CONFIRM: Record<MailLanguage, LinkCopy> = {
+    vi: {
+        subject: "Xác nhận email của bạn",
+        paragraphs: ({ brand, hours }) => [`Cảm ơn bạn đã đăng ký ${brand}.`, `Nhấn nút bên dưới để xác nhận email. Liên kết có hiệu lực trong ${String(hours)} giờ và chỉ dùng được một lần.`],
+        button: "Xác nhận email",
+        footer: "Nếu bạn không đăng ký, hãy bỏ qua thư này.",
+    },
+    en: {
+        subject: "Confirm your email",
+        paragraphs: ({ brand, hours }) => [`Thanks for signing up to ${brand}.`, `Press the button below to confirm your email. The link works once and lasts ${String(hours)} hours.`],
+        button: "Confirm email",
+        footer: "If you did not sign up, ignore this message.",
+    },
+}
+
+const RESET: Record<MailLanguage, LinkCopy> = {
+    vi: {
+        subject: "Đặt lại mật khẩu",
+        paragraphs: ({ hours }) => ["Chúng tôi nhận được yêu cầu đặt lại mật khẩu cho tài khoản của bạn.", `Nhấn nút bên dưới để chọn mật khẩu mới. Liên kết có hiệu lực trong ${String(hours)} giờ và chỉ dùng được một lần.`],
+        button: "Đặt lại mật khẩu",
+        footer: "Nếu bạn không yêu cầu, hãy bỏ qua thư này; mật khẩu của bạn không thay đổi.",
+    },
+    en: {
+        subject: "Reset your password",
+        paragraphs: ({ hours }) => ["We received a request to reset the password of your account.", `Press the button below to choose a new password. The link works once and lasts ${String(hours)} hours.`],
+        button: "Reset password",
+        footer: "If you did not ask for this, ignore this message; your password stays as it is.",
+    },
+}
+
+const draw = (copy: LinkCopy, lang: MailLanguage, input: LinkMailInput): RenderedMail =>
+    renderTransactional({
+        lang,
+        subject: copy.subject,
+        brand: { name: input.brand },
+        paragraphs: copy.paragraphs(input),
+        action: { label: copy.button, url: input.url },
+        footer: copy.footer,
+    })
+
+/** The mail that carries the link confirming a mailbox. */
+export const confirmEmailMail = (lang: MailLanguage, input: LinkMailInput): RenderedMail => draw(CONFIRM[lang], lang, input)
+
+/** The mail that carries the link choosing a new password. */
+export const resetPasswordMail = (lang: MailLanguage, input: LinkMailInput): RenderedMail => draw(RESET[lang], lang, input)

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

@@ -11,6 +11,8 @@ export const IDENTITY_MESSAGES: MessageBundle = {
         "errors.IDENTITY_TOO_MANY_ATTEMPTS": "Quá nhiều lần thử. Hãy thử lại sau.",
         "errors.IDENTITY_INVALID_CREDENTIALS": "Email hoặc mật khẩu không đúng.",
         "errors.IDENTITY_EMAIL_NOT_CONFIRMED": "Hãy xác nhận email trước khi đăng nhập.",
+        "errors.IDENTITY_PASSWORD_INVALID": "Mật khẩu cần ít nhất 8 ký tự và tối đa 72 byte.",
+        "errors.IDENTITY_RESET_TOKEN_INVALID": "Liên kết không hợp lệ hoặc đã hết hạn.",
     },
     en: {
         "errors.IDENTITY_UNAUTHENTICATED": "You need to sign in to do this.",
@@ -20,5 +22,7 @@ export const IDENTITY_MESSAGES: MessageBundle = {
         "errors.IDENTITY_TOO_MANY_ATTEMPTS": "Too many attempts. Try again later.",
         "errors.IDENTITY_INVALID_CREDENTIALS": "The email or password is wrong.",
         "errors.IDENTITY_EMAIL_NOT_CONFIRMED": "Confirm your email before signing in.",
+        "errors.IDENTITY_PASSWORD_INVALID": "The password needs at least 8 characters and at most 72 bytes.",
+        "errors.IDENTITY_RESET_TOKEN_INVALID": "The link is invalid or has expired.",
     },
 }

package/templates/be/skeleton-lite/src/modules/integrations/mail/index.ts

@@ -0,0 +1,6 @@
+export { MAILER, MailError, escapeHtml, html, renderTransactional } from "@starci/mail"
+export type { Mailer, MailMessage, RenderedMail, SentMail } from "@starci/mail"
+export { parseMailConfig } from "./mail.config"
+export { InjectMailSettings, InjectMailer, MAIL_SETTINGS } from "./mail.decorators"
+export { MailModule } from "./mail.module"
+export type { MailLanguage, MailOptions } from "./mail.options"

package/templates/be/skeleton-lite/src/modules/integrations/mail/mail.config.ts

@@ -0,0 +1,33 @@
+import type { MailSecurity } from "@starci/mail"
+import type { EnvSource } from "@modules/platform/config"
+import type { MailLanguage, MailOptions } from "./mail.options"
+
+const DEFAULT_PORT = 587
+const CONFIRM_TTL_SECONDS = 86_400
+const RESET_TTL_SECONDS = 3_600
+
+const readSecurity = (env: EnvSource): MailSecurity => {
+    const value = env.optional("MAIL_SECURITY") ?? "starttls"
+    if (value !== "tls" && value !== "starttls" && value !== "none") throw new Error("MAIL_SECURITY must be tls, starttls or none")
+    return value
+}
+
+const readLanguage = (env: EnvSource): MailLanguage => {
+    const value = env.optional("MAIL_DEFAULT_LANGUAGE") ?? "en"
+    if (value !== "vi" && value !== "en") throw new Error("MAIL_DEFAULT_LANGUAGE must be vi or en")
+    return value
+}
+
+/** Reads the mail configuration with no credential or server defaults; the login is optional and its password reads `<KEY>_FILE` first. */
+export const parseMailConfig = (env: EnvSource): MailOptions => ({
+    host: env.string("MAIL_HOST"),
+    port: env.int("MAIL_PORT", DEFAULT_PORT),
+    security: readSecurity(env),
+    ...(env.has("MAIL_USER") ? { auth: { user: env.string("MAIL_USER"), pass: env.secret("MAIL_PASSWORD") } } : {}),
+    from: { name: env.string("MAIL_FROM_NAME"), address: env.string("MAIL_FROM") },
+    webOrigin: new URL(env.url("AUTH_WEB_ORIGIN")).origin,
+    brandName: env.string("MAIL_FROM_NAME"),
+    defaultLanguage: readLanguage(env),
+    confirmTtlSeconds: env.int("MAIL_CONFIRM_TTL_SECONDS", CONFIRM_TTL_SECONDS),
+    resetTtlSeconds: env.int("MAIL_RESET_TTL_SECONDS", RESET_TTL_SECONDS),
+})

package/templates/be/skeleton-lite/src/modules/integrations/mail/mail.decorators.ts

@@ -0,0 +1,14 @@
+import { MAILER } from "@starci/mail"
+import type { Mailer } from "@starci/mail"
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { MailOptions } from "./mail.options"
+
+/** Token of the app's mail settings (the brand, the default language, the link lifetimes). */
+export const MAIL_SETTINGS: unique symbol = Symbol("integrations.mail.settings")
+
+/** Injects the mail port of `@starci/mail`. Parameter type: Mailer. */
+export const InjectMailer = (): TypedParameterDecorator<Mailer> => injector<Mailer>(MAILER)
+
+/** Injects the app's mail settings. Parameter type: MailOptions. */
+export const InjectMailSettings = (): TypedParameterDecorator<MailOptions> => injector<MailOptions>(MAIL_SETTINGS)

package/templates/be/skeleton-lite/src/modules/integrations/mail/mail.module-definition.ts

@@ -0,0 +1,12 @@
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import type { MailOptions } from "./mail.options"
+
+const built = new ConfigurableModuleBuilder<MailOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()
+type Host = ConfigurableModuleHost<MailOptions, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module base of the mail glue; `isGlobal` is decided by the app root. */
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/skeleton-lite/src/modules/integrations/mail/mail.module.ts

@@ -0,0 +1,27 @@
+import { MailModule as PackageMailModule } from "@starci/mail"
+import type { MailOptions as PackageMailOptions } from "@starci/mail"
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { MAIL_SETTINGS } from "./mail.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./mail.module-definition"
+
+@Module({})
+/** Composes `@starci/mail` with the app's typed settings and provides the settings of the app's own mail. */
+export class MailModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const { webOrigin, brandName, defaultLanguage, confirmTtlSeconds, resetTtlSeconds, isGlobal, ...transport } = options
+        const base = super.register(options)
+        const mail = PackageMailModule.register({ ...(transport satisfies PackageMailOptions), isGlobal: false })
+        return {
+            ...base,
+            imports: [...(base.imports ?? []), mail],
+            providers: [
+                ...(base.providers ?? []),
+                { provide: MAIL_SETTINGS, useValue: { ...transport, webOrigin, brandName, defaultLanguage, confirmTtlSeconds, resetTtlSeconds } },
+            ],
+            exports: [...(base.exports ?? []), mail, MAIL_SETTINGS],
+            global: isGlobal === true,
+        }
+    }
+}

package/templates/be/skeleton-lite/src/modules/integrations/mail/mail.options.ts

@@ -0,0 +1,22 @@
+import type { MailOptions as MailSettings } from "@starci/mail"
+
+/** The languages the app writes its mail in. */
+export type MailLanguage = "vi" | "en"
+
+/**
+ * Outgoing mail parsed once at API boot: the settings of `@starci/mail` and what the app's own mail needs (the product name in
+ * the header, the language of a mail whose request names none, how long a confirmation or reset link lives). The words and
+ * layout of each mail belong to the domain that sends it.
+ */
+export interface MailOptions extends MailSettings {
+    /** The origin of the web app: the links of a confirmation or reset mail open its pages. */
+    readonly webOrigin: string
+    /** The product name in the header of every mail. */
+    readonly brandName: string
+    /** The language of a mail whose request names none. */
+    readonly defaultLanguage: MailLanguage
+    /** How long a confirmation link lives, in seconds. */
+    readonly confirmTtlSeconds: number
+    /** How long a password reset link lives, in seconds. */
+    readonly resetTtlSeconds: number
+}

package/templates/be/skeleton-lite/src/modules/integrations/object-storage/object-storage.module-definition.ts

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { ObjectStorageOptions } from "./object-storage.options"
 
-const built = new ConfigurableModuleBuilder<ObjectStorageOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<ObjectStorageOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module base of the object storage glue; `isGlobal` is decided by the app root. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<ObjectStorageOptions>()

package/templates/be/skeleton-lite/src/modules/integrations/passport/index.ts

@@ -1,4 +1,4 @@
-export { AuthError, isPresentablePassword, normalizeEmail } from "@starci/auth/server"
+export { AuthError, digestOf, isAcceptablePassword, isPresentablePassword, normalizeEmail } from "@starci/auth/server"
 export type {
     AccountDirectory,
     AccountStanding,

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

@@ -1,4 +1,5 @@
 export { DatabaseModule } from "./database.module"
+export { callDbFunction } from "./database.client"
 export { DATABASE_PROBE, InjectDatabaseProbe, InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"

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

@@ -129,6 +129,17 @@ describe("RateLimitGuard", () => {
         expect(entityManager.update).not.toHaveBeenCalled()
     })
 
+    it("counts with an increment the database evaluates, so concurrent hits never overwrite each other", async () => {
+        const { entityManager, counting } = liveWindow(2)
+        const { guard } = await build(entityManager)
+
+        await guard.canActivate(contextOf("127.0.0.1"))
+
+        const assignment: unknown = counting?.callsOf("set")[0]?.[0]
+        const increment: unknown = typeof assignment === "object" && assignment !== null && "hits" in assignment && typeof assignment.hits === "function" ? Reflect.apply(assignment.hits, undefined, []) : undefined
+        expect(increment).toBe("hits + 1")
+    })
+
     it("refuses a caller whose shared window is over the default limit", async () => {
         const { guard } = await build(liveWindow(3).entityManager)