@starci/hfs 5.1.0 → 5.3.0

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/app.module.ts

@@ -2,7 +2,7 @@ import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { APP_FILTER, APP_GUARD } from "@nestjs/core"
 import { AuthGuard, CredentialGuard } from "@modules/domain/identity"
-import { tokenKit } from "@modules/integrations/passport"
+import { passportKit } from "@modules/integrations/passport"
 import { ErrorsFilter } from "@modules/platform/errors"
 import { OriginGuard, RateLimitGuard } from "@modules/platform/http-security"
 import { platformModules } from "./compose/platform"
@@ -10,7 +10,7 @@ import { domainModules } from "./compose/domain"
 import { systemModules } from "./compose/system"
 import { apiModules } from "./compose/api"
 import { webhooksModules } from "./compose/webhooks"
-import { integrationProviders } from "./compose/integrations"
+import { integrationModules, integrationProviders } from "./compose/integrations"
 import type { ApiOptions } from "./api.options"
 
 @Module({})
@@ -18,18 +18,19 @@ import type { ApiOptions } from "./api.options"
 export class AppModule {
     /** Builds the module from options parsed once at boot; nothing here reads the environment. */
     static register(options: ApiOptions): DynamicModule {
-        const tokens = tokenKit(options.passport.tokens)
+        const passport = passportKit(options.passport)
         return {
             module: AppModule,
             imports: [
                 ...platformModules(options),
-                ...domainModules(tokens.verify),
+                ...integrationModules(options),
+                ...domainModules(passport.verify),
                 ...systemModules(),
                 ...apiModules(),
                 ...webhooksModules(),
             ],
             providers: [
-                ...integrationProviders(options, tokens.verify),
+                ...integrationProviders(options, passport.verify),
                 { provide: APP_FILTER, useClass: ErrorsFilter },
                 { provide: APP_GUARD, useClass: RateLimitGuard },
                 { provide: APP_GUARD, useClass: OriginGuard },

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

@@ -1,4 +1,5 @@
 import type { DynamicModule, Type } from "@nestjs/common"
+import { AuthHttpModule } from "@features/api/auth"
 
-/** The API transports of the app; `starci app add api` registers each generated door here. */
-export const apiModules = (): Array<Type<unknown> | DynamicModule> => []
+/** The API transports of the app: the sign-in doors; `starci app add api` registers each generated door here. */
+export const apiModules = (): Array<Type<unknown> | DynamicModule> => [AuthHttpModule.register({})]

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

@@ -1,12 +1,19 @@
-import type { Provider } from "@nestjs/common"
-import { OWN_TOKEN_VERIFIER, PASSPORT_OPTIONS } from "@modules/integrations/passport"
+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 { OBJECT_STORAGE, createObjectStorage } from "@modules/integrations/object-storage"
+import { MailModule } from "@modules/integrations/mail"
+import { ObjectStorageModule } from "@modules/integrations/object-storage"
 import type { ApiOptions } from "../api.options"
 
-/** The passport and object-storage integration ports bound once for this app. */
+/** 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. */
 export const integrationProviders = (options: ApiOptions, verifyAccessToken: VerifyAccessToken): Array<Provider> => [
     { provide: PASSPORT_OPTIONS, useValue: options.passport },
     { provide: OWN_TOKEN_VERIFIER, useValue: verifyAccessToken },
-    { provide: OBJECT_STORAGE, useValue: createObjectStorage(options.objectStorage) },
 ]

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

@@ -0,0 +1,40 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the identity capability: the sign-in refusals travel under these wire codes, the same on both sides of the doors. */
+export enum IdentityErrorCode {
+    /** The door needs a signed-in caller and the request establishes none. */
+    Unauthenticated = "IDENTITY_UNAUTHENTICATED",
+    /** The refresh token is unknown, expired or already spent. */
+    RefreshInvalid = "IDENTITY_REFRESH_INVALID",
+    /** A rotated refresh token was presented again: the session was ended. */
+    RefreshReused = "IDENTITY_REFRESH_REUSED",
+    /** The account is deleted or banned. */
+    AccountDisabled = "IDENTITY_ACCOUNT_DISABLED",
+    /** Too many failed attempts for this address; try again later. */
+    TooManyAttempts = "IDENTITY_TOO_MANY_ATTEMPTS",
+    /** The pair of address and password is wrong (the same answer for an unknown address). */
+    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. */
+export const IDENTITY_ERROR_KINDS: Record<IdentityErrorCode, ErrorKind> = {
+    [IdentityErrorCode.Unauthenticated]: "unauthenticated",
+    [IdentityErrorCode.RefreshInvalid]: "unauthenticated",
+    [IdentityErrorCode.RefreshReused]: "unauthenticated",
+    [IdentityErrorCode.AccountDisabled]: "forbidden",
+    [IdentityErrorCode.TooManyAttempts]: "rate-limited",
+    [IdentityErrorCode.PairRefused]: "unauthenticated",
+    [IdentityErrorCode.EmailNotConfirmed]: "forbidden",
+    [IdentityErrorCode.PasswordInvalid]: "invalid",
+    [IdentityErrorCode.ResetTokenInvalid]: "invalid",
+}
+
+/** The one error class of the identity capability. */
+export class IdentityError extends DomainError<IdentityErrorCode> {}

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

@@ -2,7 +2,7 @@ import { SetMetadata, applyDecorators, createParamDecorator } from "@nestjs/comm
 import type { ExecutionContext } from "@nestjs/common"
 import { injector } from "@modules/platform/composition"
 import type { DoorDecorator, TypedParameterDecorator } from "@modules/platform/composition"
-import type { VerifyAccessToken } from "@modules/integrations/passport"
+import type { AuthDoors, AuthPasswords, AuthSessions, SignInBudget, VerifyAccessToken } from "@modules/integrations/passport"
 import { ServerToServer, requestOf } from "@modules/platform/http-security"
 import type { Principal } from "@modules/platform/cqrs"
 import type { CredentialAuthenticator, CredentialMetadata } from "./credential.contracts"
@@ -10,6 +10,27 @@ import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
 import { PublicReason } from "./identity.contracts"
 import type { PublicMetadata } from "./identity.contracts"
 
+/** Token of the sign-in doors of the package, provided by the identity module from the passport integration. */
+export const IDENTITY_AUTH_DOORS: unique symbol = Symbol("domain.identity.auth-doors")
+/** Token of the rotating sessions of the package. */
+export const IDENTITY_AUTH_SESSIONS: unique symbol = Symbol("domain.identity.auth-sessions")
+/** Token of the password hasher of the package. */
+export const IDENTITY_AUTH_PASSWORDS: unique symbol = Symbol("domain.identity.auth-passwords")
+/** Token of the failures-only sign-in budget of the package. */
+export const IDENTITY_SIGN_IN_BUDGET: unique symbol = Symbol("domain.identity.sign-in-budget")
+
+/** Injects the sign-in doors. Parameter type: AuthDoors. */
+export const InjectAuthDoors = (): TypedParameterDecorator<AuthDoors> => injector<AuthDoors>(IDENTITY_AUTH_DOORS)
+
+/** Injects the rotating sessions. Parameter type: AuthSessions. */
+export const InjectAuthSessions = (): TypedParameterDecorator<AuthSessions> => injector<AuthSessions>(IDENTITY_AUTH_SESSIONS)
+
+/** Injects the password hasher. Parameter type: AuthPasswords. */
+export const InjectAuthPasswords = (): TypedParameterDecorator<AuthPasswords> => injector<AuthPasswords>(IDENTITY_AUTH_PASSWORDS)
+
+/** Injects the sign-in budget. Parameter type: SignInBudget. */
+export const InjectSignInBudget = (): TypedParameterDecorator<SignInBudget> => injector<SignInBudget>(IDENTITY_SIGN_IN_BUDGET)
+
 /** Token of the access-token verifier the composition root hands to identity. */
 export const ACCESS_TOKEN_VERIFIER: unique symbol = Symbol("domain.identity.access-token-verifier")
 

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

@@ -1,10 +1,33 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule, Provider } from "@nestjs/common"
+import {
+    PASSPORT_ACCOUNTS,
+    PASSPORT_AUTHENTICATOR,
+    PASSPORT_DOORS,
+    PASSPORT_PASSWORDS,
+    PASSPORT_RATE_COUNTER,
+    PASSPORT_SESSIONS,
+    PASSPORT_SESSION_STORE,
+    PASSPORT_SIGN_IN_BUDGET,
+} from "@modules/integrations/passport"
+import { IdentityAccountDirectoryService } from "./account-directory.service"
 import { AuthGuard } from "./auth.guard"
+import { IdentityAuthenticatorService } from "./authenticator.service"
 import { CredentialGuard } from "./credential.guard"
 import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
-import { ACCESS_TOKEN_VERIFIER, CREDENTIAL_AUTHENTICATOR } from "./identity.decorators"
+import {
+    ACCESS_TOKEN_VERIFIER,
+    CREDENTIAL_AUTHENTICATOR,
+    IDENTITY_AUTH_DOORS,
+    IDENTITY_AUTH_PASSWORDS,
+    IDENTITY_AUTH_SESSIONS,
+    IDENTITY_SIGN_IN_BUDGET,
+} from "./identity.decorators"
 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 = {
     provide: CREDENTIAL_AUTHENTICATOR,
@@ -34,8 +57,33 @@ export class IdentityModule extends ConfigurableModuleClass {
                 authenticator,
                 CredentialGuard,
                 AuthGuard,
+                IdentitySessionStoreService,
+                IdentityAccountDirectoryService,
+                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 },
+                { provide: IDENTITY_SIGN_IN_BUDGET, useExisting: PASSPORT_SIGN_IN_BUDGET },
+                { provide: PASSPORT_SESSION_STORE, useExisting: IdentitySessionStoreService },
+                { provide: PASSPORT_ACCOUNTS, useExisting: IdentityAccountDirectoryService },
+                { provide: PASSPORT_RATE_COUNTER, useExisting: IdentityRateCounterService },
+                { provide: PASSPORT_AUTHENTICATOR, useExisting: IdentityAuthenticatorService },
+            ],
+            exports: [
+                CredentialGuard,
+                CREDENTIAL_AUTHENTICATOR,
+                AuthGuard,
+                ACCESS_TOKEN_VERIFIER,
+                IdentitySignInService,
+                IdentityEmailService,
+                PASSPORT_SESSION_STORE,
+                PASSPORT_ACCOUNTS,
+                PASSPORT_RATE_COUNTER,
+                PASSPORT_AUTHENTICATOR,
             ],
-            exports: [CredentialGuard, CREDENTIAL_AUTHENTICATOR, AuthGuard, ACCESS_TOKEN_VERIFIER],
         }
     }
 }

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

@@ -5,3 +5,6 @@ export { IDENTITY_MESSAGES } from "./messages/identity.messages"
 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

@@ -0,0 +1,28 @@
+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.",
+        "errors.IDENTITY_REFRESH_INVALID": "Phiên đăng nhập không hợp lệ hoặc đã hết hạn.",
+        "errors.IDENTITY_REFRESH_REUSED": "Phiên đăng nhập đã kết thúc vì bị dùng lại. Hãy đăng nhập lại.",
+        "errors.IDENTITY_ACCOUNT_DISABLED": "Tài khoản này đã bị khóa.",
+        "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.",
+        "errors.IDENTITY_REFRESH_INVALID": "The session is invalid or has expired.",
+        "errors.IDENTITY_REFRESH_REUSED": "The session ended because it was used again. Please sign in again.",
+        "errors.IDENTITY_ACCOUNT_DISABLED": "This account is disabled.",
+        "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/index.ts

@@ -1,4 +1,4 @@
-export { createObjectStorage } from "./object-storage.client"
+export { OBJECT_STORAGE } from "@starci/object-storage"
 export { parseObjectStorageConfig } from "./object-storage.config"
-export { InjectObjectStorage, OBJECT_STORAGE } from "./object-storage.decorators"
-export type { ObjectStorage, PresignedRequest, ObjectStorageOptions } from "./object-storage.options"
+export { ObjectStorageModule } from "./object-storage.module"
+export type { ObjectStorageOptions } from "./object-storage.options"

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

@@ -1,6 +1,8 @@
 import type { EnvSource } from "@modules/platform/config"
 import type { ObjectStorageOptions } from "./object-storage.options"
 
+const PRESIGN_TTL_SECONDS = 300
+
 /** Reads the object storage configuration with no credential or endpoint defaults; secrets read `<KEY>_FILE` first. */
 export const parseObjectStorageConfig = (env: EnvSource): ObjectStorageOptions => ({
     endpoint: env.url("STORAGE_ENDPOINT"),
@@ -8,5 +10,5 @@ export const parseObjectStorageConfig = (env: EnvSource): ObjectStorageOptions =
     bucket: env.string("STORAGE_BUCKET"),
     accessKeyId: env.secret("STORAGE_ACCESS_KEY_ID"),
     secretAccessKey: env.secret("STORAGE_SECRET_ACCESS_KEY"),
-    presignTtlSeconds: env.int("STORAGE_PRESIGN_TTL_SECONDS", 300),
+    defaultExpiresIn: env.int("STORAGE_PRESIGN_TTL_SECONDS", PRESIGN_TTL_SECONDS),
 })

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

@@ -1,9 +1,13 @@
+import { OBJECT_STORAGE } from "@starci/object-storage"
+import type { ObjectStorage } from "@starci/object-storage"
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
-import type { ObjectStorage } from "./object-storage.options"
 
-/** Token of the object storage port. */
-export const OBJECT_STORAGE: unique symbol = Symbol("integrations.object-storage")
+/** Token of the bucket of the app's objects. */
+export const OBJECT_STORAGE_BUCKET: unique symbol = Symbol("integrations.object-storage.bucket")
 
-/** Injects the object storage port. Parameter type: ObjectStorage. */
+/** Injects the object storage port of `@starci/object-storage`. Parameter type: ObjectStorage. */
 export const InjectObjectStorage = (): TypedParameterDecorator<ObjectStorage> => injector<ObjectStorage>(OBJECT_STORAGE)
+
+/** Injects the bucket of the app's objects. Parameter type: string. */
+export const InjectObjectStorageBucket = (): TypedParameterDecorator<string> => injector<string>(OBJECT_STORAGE_BUCKET)

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

@@ -0,0 +1,5 @@
+import { defineCapabilityModule } from "@starci/nest-kit"
+import type { ObjectStorageOptions } from "./object-storage.options"
+
+/** The configurable-module base of the object storage glue; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<ObjectStorageOptions>()

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

@@ -0,0 +1,29 @@
+import { ObjectStorageModule as StorageModule } from "@starci/object-storage"
+import type { ObjectStorageOptions as StorageSettings } from "@starci/object-storage"
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { CLOCK } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { OBJECT_STORAGE_BUCKET } from "./object-storage.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./object-storage.module-definition"
+
+@Module({})
+/** Composes `@starci/object-storage` with the app's typed settings and clock, and provides the bucket of the app's objects. */
+export class ObjectStorageModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const { bucket, isGlobal, ...settings } = options
+        const base = super.register(options)
+        const storage = StorageModule.registerAsync({
+            inject: [CLOCK],
+            useFactory: (clock: Clock): StorageSettings => ({ ...settings, clock }),
+        })
+        return {
+            ...base,
+            imports: [...(base.imports ?? []), storage],
+            providers: [...(base.providers ?? []), { provide: OBJECT_STORAGE_BUCKET, useValue: bucket }],
+            exports: [...(base.exports ?? []), storage, OBJECT_STORAGE_BUCKET],
+            global: isGlobal === true,
+        }
+    }
+}