@starci/hfs 5.2.0 → 5.4.0

package/templates/app/skeleton-lite/.starcistacks/dev/infra/compose/compose.yaml

@@ -1,6 +1,8 @@
 # The dev environment's dependencies, run by `starci app stack up --env dev --execute` (PROJECT-STACKS-3, PROJECT-STACKS-6).
 # Host ports come from environments.dev.local.ports through STACK_PORT_<NAME>; the superuser password is read from a file through the least
-# grant STACK_GRANT_DB (a directory holding only POSTGRES_PASSWORD), never from the environment. Every port publishes on loopback only. The api and web run natively against these containers.
+# grant STACK_GRANT_DB (a directory holding only POSTGRES_PASSWORD), never from the environment. Every port publishes on loopback only.
+# `mail` is the dev mail sink (Mailpit, an unmodified upstream image pinned by digest in contexts/stack/pins.yaml): the api sends the
+# confirmation and reset mails to its SMTP port, over a plain channel that exists on loopback only, and a person reads them in its web UI. The api and web run natively against these containers.
 name: {{project}}-dev
 services:
   db:
@@ -21,5 +23,21 @@ services:
       retries: 30
       start_period: 10s
     restart: unless-stopped
+  mail:
+    image: axllent/mailpit:v1.31.6@sha256:23fe39e81bde596a918000b3135c0f85dc8bb4c9ea6be274b051143f3e300387
+    environment:
+      MP_SMTP_BIND_ADDR: 0.0.0.0:1025
+      MP_UI_BIND_ADDR: 0.0.0.0:8025
+      MP_MAX_MESSAGES: "500"
+    ports:
+      - "127.0.0.1:${STACK_PORT_MAIL}:1025"
+      - "127.0.0.1:${STACK_PORT_MAILUI}:8025"
+    healthcheck:
+      test: ["CMD", "/mailpit", "readyz"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 5s
+    restart: unless-stopped
 volumes:
   db-data: {}

package/templates/app/skeleton-lite/.starcistacks/dev/runtime/env/KEYS.md

@@ -18,5 +18,8 @@ Names only. Dev values are generated once by the owner-armed `starci app secret
 | `AUTH_JWT_PRIVATE_KEY` | API Ed25519 (EdDSA) signing key (member `auth`) |
 | `STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET` | API storage address |
 | `STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY` | API storage credentials (member `storage`) |
+| `MAIL_HOST`, `MAIL_PORT`, `MAIL_SECURITY`, `MAIL_FROM`, `MAIL_FROM_NAME` | API outgoing mail server (the dev `mail` service, Mailpit, on its SMTP port: a plain channel on loopback only) and the sender of the confirmation and reset mails |
+| `MAIL_DEFAULT_LANGUAGE`, `MAIL_CONFIRM_TTL_SECONDS`, `MAIL_RESET_TTL_SECONDS` | API mail language (`vi` or `en`) and link lifetimes; optional |
+| `MAIL_USER`, `MAIL_PASSWORD` | API mail server login; optional, the password reads `MAIL_PASSWORD_FILE` |
 | `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_GRAPHQL_URL` | Front-end site, auth doors and GraphQL transport |
 | `DATABASE_URL` | `starci app db` verbs; the stack verb composes it in memory for the migration |

package/templates/app/skeleton-lite/.starcistacks/production/infra/swarm/stack.yaml

@@ -17,6 +17,11 @@ services:
       AUTH_JWT_KEY_ID: production-1
       AUTH_COOKIE_DOMAIN: {{project}}.example.invalid
       AUTH_JWT_PRIVATE_KEY_FILE: /run/secrets/auth-jwt-private-key
+      MAIL_HOST: smtp.{{project}}.example.invalid
+      MAIL_PORT: "587"
+      MAIL_SECURITY: starttls
+      MAIL_FROM: no-reply@{{project}}.example.invalid
+      MAIL_FROM_NAME: {{project}}
       STORAGE_ENDPOINT: https://storage.{{project}}.example.invalid
       STORAGE_REGION: us-east-1
       STORAGE_BUCKET: {{project}}-production

package/templates/app/skeleton-lite/.starcistacks/production/runtime/env/KEYS.md

@@ -23,6 +23,10 @@ This inventory declares names, consumers and mounted file paths. Scaffolding gen
 | `STORAGE_BUCKET` | API storage bucket |
 | `STORAGE_ACCESS_KEY_ID` | API storage credential; reads `STORAGE_ACCESS_KEY_ID_FILE` at `/run/secrets/storage-access-key-id` |
 | `STORAGE_SECRET_ACCESS_KEY` | API storage credential; reads `STORAGE_SECRET_ACCESS_KEY_FILE` at `/run/secrets/storage-secret-access-key` |
+| `MAIL_HOST`, `MAIL_PORT`, `MAIL_SECURITY` | API outgoing mail server and how its channel is secured (`starttls` is required to succeed, `tls` is implicit TLS) |
+| `MAIL_FROM`, `MAIL_FROM_NAME` | API sender address and name of the confirmation and reset mails |
+| `MAIL_DEFAULT_LANGUAGE`, `MAIL_CONFIRM_TTL_SECONDS`, `MAIL_RESET_TTL_SECONDS` | API mail language (`vi` or `en`) and link lifetimes; optional |
+| `MAIL_USER`, `MAIL_PASSWORD` | API mail server login; optional, the password reads `MAIL_PASSWORD_FILE` at `/run/secrets/mail-password` |
 | `DATABASE_URL` | `starci app db` verbs (migrate, dump) and `contract:emit`, from the operator's environment |
 | `NEXT_PUBLIC_SITE_URL` | Front-end site URL |
 | `NEXT_PUBLIC_API_URL` | Front-end auth doors of the API |

package/templates/app/skeleton-lite/db/migrations/__timestamp___baseline.sql

@@ -24,12 +24,9 @@ begin
 end;
 $$;
 
-grant usage on schema auth to app_be;
-grant select, insert, update on table auth.users to app_be;
-grant select, insert on table auth.identities to app_be;
-
 -- The device sessions and rotating refresh tokens of @starci/auth. A token is stored by its sha256 only; a rotated token stays,
--- marked used, so a replay is detected (a replay inside the grace window is a racing tab, an older one ends the session).
+-- marked used, so a replay is detected: a replay inside the grace window gets a successor of its own (raced_count bounds how many),
+-- an older one ends the session and every token of it.
 -- identity_attempts counts the sign-in attempts of one address in a window every replica shares (the budget of failures).
 -- The app owns auth.users (db/bootstrap.sql) and the role app_be.
 
@@ -52,6 +49,7 @@ create table public.identity_refresh_tokens (
     created_at timestamptz not null default now(),
     expires_at timestamptz not null,
     used_at timestamptz,
+    raced_count integer not null default 0,
     constraint identity_refresh_tokens_hash_key unique (token_hash)
 );
 
@@ -87,6 +85,30 @@ create policy identity_refresh_tokens_app_be_all on public.identity_refresh_toke
 create policy identity_attempts_app_be_all on public.identity_attempts
     for all to app_be using (current_user = 'app_be') with check (current_user = 'app_be');
 
+{{> app/auth-doors.sql.partial}}
+
+-- The single-use links that confirm a mailbox or reset a password (the email doors of sign-in): only the sha256 of the token is
+-- stored, a spent link stays marked used, and a new link of the same purpose ends the older ones.
+create table public.identity_email_tokens (
+    id uuid primary key,
+    user_id uuid not null references auth.users (id) on delete cascade,
+    purpose varchar(16) not null check (purpose in ('confirm', 'reset')),
+    token_hash varchar(64) not null,
+    expires_at timestamptz not null,
+    used_at timestamptz,
+    created_at timestamptz not null,
+    constraint identity_email_tokens_hash_key unique (token_hash)
+);
+
+create index identity_email_tokens_user_idx on public.identity_email_tokens (user_id, purpose);
+
+alter table public.identity_email_tokens enable row level security;
+alter table public.identity_email_tokens force row level security;
+revoke all on table public.identity_email_tokens from public;
+grant select, insert, update, delete on table public.identity_email_tokens to app_be;
+create policy identity_email_tokens_app_be_all on public.identity_email_tokens
+    for all to app_be using (current_user = 'app_be') with check (current_user = 'app_be');
+
 create table public.profiles (
     id uuid primary key references auth.users (id) on delete cascade,
     display_name text not null check (char_length(display_name) between 1 and 120),

package/templates/be/auth-lite/src/features/api/auth/application/auth.contracts.ts

@@ -1,4 +1,5 @@
 // Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import type { MailLanguage } from "@modules/integrations/mail"
 import type { HttpExchange } from "@modules/integrations/passport"
 
 /** One cookie door of sign-in: the request and response the strategy or the refresh cookie work on. */
@@ -9,3 +10,35 @@ export interface ExchangeRequest {
 
 /** A request with nothing in it. */
 export type EmptyRequest = Record<string, never>
+
+/** The posted data of the signup door. */
+export interface SignupData {
+    /** The sign-in address. */
+    readonly email: string
+    /** The chosen password. */
+    readonly password: string
+    /** The language of the confirmation mail, when the request names one. */
+    readonly language: MailLanguage | undefined
+}
+
+/** The posted data of the resend and forgot doors. */
+export interface AddressData {
+    /** The address the mail goes to. */
+    readonly email: string
+    /** The language of the mail, when the request names one. */
+    readonly language: MailLanguage | undefined
+}
+
+/** The link token of the confirm door. */
+export interface TokenData {
+    /** The token the link carries. */
+    readonly token: string
+}
+
+/** The posted data of the reset door. */
+export interface ResetData {
+    /** The token the link carries. */
+    readonly token: string
+    /** The new password. */
+    readonly password: string
+}

package/templates/be/auth-lite/src/features/api/auth/application/confirm.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { TokenData } from "./auth.contracts"
+
+/** Spends a confirmation link and confirms the mailbox. */
+export class ConfirmCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<TokenData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/confirm.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { ConfirmCommand } from "./confirm.command"
+
+@CommandHandler(ConfirmCommand)
+/** Spends a confirmation link and confirms the mailbox. */
+export class ConfirmHandler extends ICQRSHandler<ConfirmCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: ConfirmCommand): Promise<void> {
+        return this.email.confirm(command.params.request.token)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/forgot.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { AddressData } from "./auth.contracts"
+
+/** Mails a password reset link when the address has an account; the answer never says whether it does. */
+export class ForgotCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<AddressData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/forgot.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { ForgotCommand } from "./forgot.command"
+
+@CommandHandler(ForgotCommand)
+/** Mails a password reset link when the address has an account; the answer never says whether it does. */
+export class ForgotHandler extends ICQRSHandler<ForgotCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: ForgotCommand): Promise<void> {
+        return this.email.forgot(command.params.request.email, command.params.request.language)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/resend.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { AddressData } from "./auth.contracts"
+
+/** Mails a new confirmation link to an unconfirmed account; the answer never says whether the address has one. */
+export class ResendCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<AddressData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/resend.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { ResendCommand } from "./resend.command"
+
+@CommandHandler(ResendCommand)
+/** Mails a new confirmation link to an unconfirmed account; the answer never says whether the address has one. */
+export class ResendHandler extends ICQRSHandler<ResendCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: ResendCommand): Promise<void> {
+        return this.email.resend(command.params.request.email, command.params.request.language)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/reset.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { ResetData } from "./auth.contracts"
+
+/** Spends a reset link: sets the new password and ends every session of the person. */
+export class ResetCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<ResetData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/reset.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { ResetCommand } from "./reset.command"
+
+@CommandHandler(ResetCommand)
+/** Spends a reset link: sets the new password and ends every session of the person. */
+export class ResetHandler extends ICQRSHandler<ResetCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: ResetCommand): Promise<void> {
+        return this.email.reset(command.params.request.token, command.params.request.password)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/signup.command.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { SignupData } from "./auth.contracts"
+
+/** Creates an unconfirmed password account and mails the confirmation link; the answer never says whether the address already had an account. */
+export class SignupCommand extends Command<void> {
+    constructor(readonly params: PublicExecuteParams<SignupData>) {
+        super()
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/application/signup.handler.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentityEmailService } from "@modules/domain/identity"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { SignupCommand } from "./signup.command"
+
+@CommandHandler(SignupCommand)
+/** Creates an unconfirmed password account and mails the confirmation link; the answer never says whether the address already had an account. */
+export class SignupHandler extends ICQRSHandler<SignupCommand, void> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly email: IdentityEmailService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: SignupCommand): Promise<void> {
+        return this.email.signup(command.params.request.email, command.params.request.password, command.params.request.language)
+    }
+}

package/templates/be/auth-lite/src/features/api/auth/auth.module-definition.ts

@@ -1,13 +1,6 @@
-// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineConfigurableModule } from "@starci/nest-kit"
 import type { AuthApiOptions } from "./auth.options"
 
-const built = new ConfigurableModuleBuilder<AuthApiOptions>().setClassMethodName("register").build()
-type Host = ConfigurableModuleHost<AuthApiOptions, "register", "create", {}>
-
 /** The configurable-module base of the auth feature module. */
-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 } =
+    defineConfigurableModule<AuthApiOptions>()

package/templates/be/auth-lite/src/features/api/auth/auth.module.ts

@@ -7,10 +7,15 @@ import { LogoutHandler } from "./application/logout.handler"
 import { GoogleBeginHandler } from "./application/google-begin.handler"
 import { GoogleCompleteHandler } from "./application/google-complete.handler"
 import { GetJwksHandler } from "./application/get-jwks.handler"
+import { SignupHandler } from "./application/signup.handler"
+import { ResendHandler } from "./application/resend.handler"
+import { ConfirmHandler } from "./application/confirm.handler"
+import { ForgotHandler } from "./application/forgot.handler"
+import { ResetHandler } from "./application/reset.handler"
 import { ConfigurableModuleClass } from "./auth.module-definition"
 
 @Module({
-    providers: [LoginHandler, RefreshHandler, SessionHandler, LogoutHandler, GoogleBeginHandler, GoogleCompleteHandler, GetJwksHandler],
+    providers: [LoginHandler, RefreshHandler, SessionHandler, LogoutHandler, GoogleBeginHandler, GoogleCompleteHandler, GetJwksHandler, SignupHandler, ResendHandler, ConfirmHandler, ForgotHandler, ResetHandler],
 })
 /** The auth feature: the handlers behind the sign-in doors. */
 export class AuthApiModule extends ConfigurableModuleClass {}

package/templates/be/auth-lite/src/features/api/auth/transport/http/auth-http.module-definition.ts

@@ -1,13 +1,6 @@
-// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineConfigurableModule } from "@starci/nest-kit"
 import type { AuthHttpOptions } from "./auth-http.options"
 
-const built = new ConfigurableModuleBuilder<AuthHttpOptions>().setClassMethodName("register").build()
-type Host = ConfigurableModuleHost<AuthHttpOptions, "register", "create", {}>
-
 /** The configurable-module base of the auth-http module. */
-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 } =
+    defineConfigurableModule<AuthHttpOptions>()

package/templates/be/auth-lite/src/features/api/auth/transport/http/auth.controller.ts

@@ -6,6 +6,11 @@ import { Public, PublicReason } from "@modules/domain/identity"
 import type { AccessGrant, GoogleRedirect, JwksDocument } from "@modules/integrations/passport"
 import { InjectCommandBus, InjectQueryBus } from "@modules/platform/cqrs"
 import { RateLimit, RateTier } from "@modules/platform/http-security"
+import { SignupCommand } from "../../application/signup.command"
+import { ResendCommand } from "../../application/resend.command"
+import { ConfirmCommand } from "../../application/confirm.command"
+import { ForgotCommand } from "../../application/forgot.command"
+import { ResetCommand } from "../../application/reset.command"
 import { GetJwksQuery } from "../../application/get-jwks.query"
 import { GoogleBeginCommand } from "../../application/google-begin.command"
 import { GoogleCompleteCommand } from "../../application/google-complete.command"
@@ -13,11 +18,16 @@ import { LoginCommand } from "../../application/login.command"
 import { LogoutCommand } from "../../application/logout.command"
 import { RefreshCommand } from "../../application/refresh.command"
 import { SessionCommand } from "../../application/session.command"
+import { ForgotRequest } from "./dto/forgot.request"
 import { GoogleStartRequest } from "./dto/google-start.request"
 import { LoginRequest } from "./dto/login.request"
+import { ResendRequest } from "./dto/resend.request"
+import { ResetRequest } from "./dto/reset.request"
+import { SignupRequest } from "./dto/signup.request"
+import { TokenRequest } from "./dto/token.request"
 
 @Controller("auth")
-/** The cookie doors of sign-in: email and password, Google, refresh, session, sign-out and the public keys. */
+/** The cookie doors of sign-in: email and password, the email doors (sign up, confirm, resend, forgot, reset), Google, refresh, session, sign-out and the public keys. */
 export class AuthController {
     constructor(
         @InjectCommandBus() private readonly commandBus: CommandBus,
@@ -80,6 +90,51 @@ export class AuthController {
         return this.commandBus.execute(new GoogleCompleteCommand({ request: { exchange: { req, res } } }))
     }
 
+    /** Creates an unconfirmed account and mails the confirmation link; always answers 204. */
+    @Post("signup")
+    @HttpCode(204)
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    signup(@Body() body: SignupRequest): Promise<void> {
+        return this.commandBus.execute(new SignupCommand({ request: { email: body.email, password: body.password, language: body.language } }))
+    }
+
+    /** Mails a new confirmation link; always answers 204. */
+    @Post("resend")
+    @HttpCode(204)
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    resend(@Body() body: ResendRequest): Promise<void> {
+        return this.commandBus.execute(new ResendCommand({ request: { email: body.email, language: body.language } }))
+    }
+
+    /** Spends a confirmation link; a spent, expired or unknown link is refused with IDENTITY_RESET_TOKEN_INVALID. */
+    @Post("confirm")
+    @HttpCode(204)
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    confirm(@Body() body: TokenRequest): Promise<void> {
+        return this.commandBus.execute(new ConfirmCommand({ request: { token: body.token } }))
+    }
+
+    /** Mails a password reset link when the address has an account; always answers 204. */
+    @Post("forgot")
+    @HttpCode(204)
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    forgot(@Body() body: ForgotRequest): Promise<void> {
+        return this.commandBus.execute(new ForgotCommand({ request: { email: body.email, language: body.language } }))
+    }
+
+    /** Spends a reset link and sets the new password; every session of the person ends. */
+    @Post("reset")
+    @HttpCode(204)
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    reset(@Body() body: ResetRequest): Promise<void> {
+        return this.commandBus.execute(new ResetCommand({ request: { token: body.token, password: body.password } }))
+    }
+
     /** The public keys access tokens verify against. */
     @Get("jwks")
     @Public({ reason: PublicReason.AuthHandshake })

package/templates/be/auth-lite/src/features/api/auth/transport/http/dto/forgot.request.ts

@@ -0,0 +1,16 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { IsEmail, IsIn, IsOptional, MaxLength } from "class-validator"
+import type { MailLanguage } from "@modules/integrations/mail"
+
+/** The posted address of a password reset request. */
+export class ForgotRequest {
+    /** The sign-in address. */
+    @IsEmail()
+    @MaxLength(254)
+    email!: string
+
+    /** The language of the mail; the app's default when left out. */
+    @IsOptional()
+    @IsIn(["vi", "en"])
+    language?: MailLanguage
+}

package/templates/be/auth-lite/src/features/api/auth/transport/http/dto/resend.request.ts

@@ -0,0 +1,16 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { IsEmail, IsIn, IsOptional, MaxLength } from "class-validator"
+import type { MailLanguage } from "@modules/integrations/mail"
+
+/** The posted address of a resend. */
+export class ResendRequest {
+    /** The sign-in address. */
+    @IsEmail()
+    @MaxLength(254)
+    email!: string
+
+    /** The language of the mail; the app's default when left out. */
+    @IsOptional()
+    @IsIn(["vi", "en"])
+    language?: MailLanguage
+}

package/templates/be/auth-lite/src/features/api/auth/transport/http/dto/reset.request.ts

@@ -0,0 +1,18 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { IsString, MaxLength, MinLength } from "class-validator"
+
+/** The posted link token and new password. */
+export class ResetRequest {
+    /** The token the link carries. */
+    @IsString()
+    @MinLength(16)
+    @MaxLength(256)
+    token!: string
+
+    /** The new password. */
+    @IsString()
+    @MinLength(1)
+    @MaxLength(128)
+    password!: string
+
+}

package/templates/be/auth-lite/src/features/api/auth/transport/http/dto/signup.request.ts

@@ -0,0 +1,22 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { IsEmail, IsIn, IsOptional, IsString, MaxLength, MinLength } from "class-validator"
+import type { MailLanguage } from "@modules/integrations/mail"
+
+/** The posted sign-up data. */
+export class SignupRequest {
+    /** The sign-in address. */
+    @IsEmail()
+    @MaxLength(254)
+    email!: string
+
+    /** The password. */
+    @IsString()
+    @MinLength(1)
+    @MaxLength(128)
+    password!: string
+
+    /** The language of the mail; the app's default when left out. */
+    @IsOptional()
+    @IsIn(["vi", "en"])
+    language?: MailLanguage
+}

package/templates/be/auth-lite/src/features/api/auth/transport/http/dto/token.request.ts

@@ -0,0 +1,11 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { IsString, MaxLength, MinLength } from "class-validator"
+
+/** The posted link token. */
+export class TokenRequest {
+    /** The token the link carries. */
+    @IsString()
+    @MinLength(16)
+    @MaxLength(256)
+    token!: string
+}