@starci/hfs 5.2.0 → 5.4.0

package/templates/be/auth-lite/src/modules/domain/identity/identity-email.service.spec.ts

@@ -0,0 +1,233 @@
+// Managed by starci app sync (slot be.identity.sign-in); do not edit: run "npx starci app sync --execute".
+import "reflect-metadata"
+import { Test } from "@nestjs/testing"
+import { FakeClock, fakeIds, fakeTransaction, mock, mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { MAILER } from "@modules/integrations/mail"
+import type { Mailer, MailOptions } from "@modules/integrations/mail"
+import { AuthError, digestOf } from "@modules/integrations/passport"
+import type { AuthPasswords, SignInBudget } from "@modules/integrations/passport"
+import { CLOCK } from "@modules/platform/clock"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { IDS } from "@modules/platform/ids"
+import { LOGGER } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { MAIL_SETTINGS } from "@modules/integrations/mail"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { IDENTITY_AUTH_PASSWORDS, IDENTITY_SIGN_IN_BUDGET } from "./identity.decorators"
+import { IdentityEmailService } from "./identity-email.service"
+import { IdentityEmailTokenEntity } from "./persistence/entities"
+import { IdentitySessionStoreService } from "./session-store.service"
+import { accountByEmailRow as account } from "@tests/fixtures/builders/identity.builder"
+
+/** The statements callDbFunction sends for the account doors the email doors use. */
+const USER_BY_EMAIL = 'SELECT * FROM "public"."be_auth_user_by_email"($1)'
+const CREATE_USER = 'SELECT * FROM "public"."be_auth_create_user"($1, $2, $3, $4, $5, $6)'
+const CONFIRM_USER = 'SELECT * FROM "public"."be_auth_confirm_user"($1, $2)'
+const SET_PASSWORD = 'SELECT * FROM "public"."be_auth_set_password"($1, $2, $3, $4)'
+
+const NEW_ID = "00000000-0000-4000-8000-000000000001"
+const AT = "2026-02-03T04:05:06.000Z"
+const NOW = new Date(AT)
+const SETTINGS = {
+    webOrigin: "https://app.example.test",
+    brandName: "Acme",
+    defaultLanguage: "en",
+    confirmTtlSeconds: 86_400,
+    resetTtlSeconds: 3_600,
+} as unknown as MailOptions
+
+const refusal = (code: string): unknown => expect.objectContaining({ code })
+const tokenRow = (purpose: string): IdentityEmailTokenEntity => ({ id: "t-1", userId: "u-1", purpose, tokenHash: "h", expiresAt: new Date("2026-02-04T00:00:00.000Z"), usedAt: null, createdAt: NOW })
+
+const build = async (entityManager: MockEntityManager) => {
+    const passwords = mock<AuthPasswords>()
+    passwords.hash.mockResolvedValue("new-hash")
+    const budget = mock<SignInBudget>()
+    budget.admit.mockResolvedValue(undefined)
+    const mailer = mock<Mailer>()
+    mailer.send.mockResolvedValue({ messageId: "<m>", accepted: ["a@example.test"] })
+    const sessions = mock<IdentitySessionStoreService>()
+    const logger = mock<Logger>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            IdentityEmailService,
+            { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
+            { provide: IDENTITY_AUTH_PASSWORDS, useValue: passwords },
+            { provide: IDENTITY_SIGN_IN_BUDGET, useValue: budget },
+            { provide: MAILER, useValue: mailer },
+            { provide: MAIL_SETTINGS, useValue: mock<MailOptions>(SETTINGS) },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: IDS, useValue: fakeIds() },
+            { provide: LOGGER, useValue: logger },
+            { provide: IdentitySessionStoreService, useValue: sessions },
+        ],
+    }).compile()
+    return { subject: moduleRef.get(IdentityEmailService), passwords, budget, mailer, sessions, logger }
+}
+
+describe("IdentityEmailService.signup", () => {
+    it("creates an unconfirmed account through the door, stores only the digest of the link token and mails the link", async () => {
+        const entityManager = mockEntityManager({ query: [[USER_BY_EMAIL, []], [CREATE_USER, [{ be_auth_create_user: NEW_ID }]]], insert: [IdentityEmailTokenEntity, {}], update: [IdentityEmailTokenEntity, {}] })
+        fakeTransaction(entityManager)
+        const { subject, budget, mailer } = await build(entityManager)
+
+        await subject.signup(" New@Example.test ", "correct horse")
+
+        expect(budget.admit).toHaveBeenCalledWith("signup", "new@example.test")
+        expect(entityManager.query).toHaveBeenCalledWith(CREATE_USER, [NEW_ID, "new@example.test", "new-hash", false, "{}", NOW])
+        const sent = mailer.send.mock.calls[0]?.[0]
+        const url = /https:\/\/[^\s"<]+/u.exec(sent?.message.text ?? "")?.[0] ?? ""
+        const token = new URL(url).searchParams.get("token") ?? ""
+        expect(new URL(url).pathname).toBe("/auth/confirm")
+        expect(token).toHaveLength(64)
+        expect(entityManager.insert).toHaveBeenCalledWith(IdentityEmailTokenEntity, expect.objectContaining({ userId: NEW_ID, purpose: "confirm", tokenHash: digestOf(token), usedAt: null }))
+        expect(sent?.to).toBe("new@example.test")
+    })
+
+    it("keeps the generated id when the create door answers no row", async () => {
+        const entityManager = mockEntityManager({ query: [[USER_BY_EMAIL, []], [CREATE_USER, []]], insert: [IdentityEmailTokenEntity, {}], update: [IdentityEmailTokenEntity, {}] })
+        fakeTransaction(entityManager)
+        const { subject } = await build(entityManager)
+
+        await subject.signup("new@example.test", "correct horse")
+
+        expect(entityManager.insert).toHaveBeenCalledWith(IdentityEmailTokenEntity, expect.objectContaining({ userId: NEW_ID }))
+    })
+
+    it("refuses a password the policy rejects before it touches an account", async () => {
+        const { subject, mailer } = await build(mockEntityManager())
+
+        await expect(subject.signup("a@example.test", "short")).rejects.toEqual(refusal(IdentityErrorCode.PasswordInvalid))
+        expect(mailer.send).not.toHaveBeenCalled()
+    })
+
+    it("mails a new link to an unconfirmed account and says nothing about a confirmed one", async () => {
+        const unconfirmed = mockEntityManager({ query: [USER_BY_EMAIL, [account("unconfirmed")]], insert: [IdentityEmailTokenEntity, {}], update: [IdentityEmailTokenEntity, {}] })
+        fakeTransaction(unconfirmed)
+        const confirmed = mockEntityManager({ query: [USER_BY_EMAIL, [account()]] })
+        const first = await build(unconfirmed)
+        const second = await build(confirmed)
+
+        await first.subject.signup("a@example.test", "correct horse")
+        await second.subject.signup("a@example.test", "correct horse")
+
+        expect(first.mailer.send).toHaveBeenCalledTimes(1)
+        expect(second.mailer.send).not.toHaveBeenCalled()
+        expect(confirmed.query).not.toHaveBeenCalledWith(CREATE_USER, expect.anything())
+    })
+
+    it("answers as if the mail was sent when the mail server fails, and logs the failure", async () => {
+        const entityManager = mockEntityManager({ query: [[USER_BY_EMAIL, []], [CREATE_USER, [{ be_auth_create_user: NEW_ID }]]], insert: [IdentityEmailTokenEntity, {}], update: [IdentityEmailTokenEntity, {}] })
+        fakeTransaction(entityManager)
+        const { subject, mailer, logger } = await build(entityManager)
+        mailer.send.mockRejectedValue(new Error("down"))
+
+        await expect(subject.signup("a@example.test", "correct horse", "vi")).resolves.toBeUndefined()
+        expect(logger.error).toHaveBeenCalledWith("identity.email.mail_failed", expect.any(Error), { kind: "confirm" })
+    })
+
+    it("turns a spent budget into the too-many-attempts refusal", async () => {
+        const { subject, budget } = await build(mockEntityManager())
+        budget.admit.mockRejectedValue(new AuthError(IdentityErrorCode.TooManyAttempts))
+
+        await expect(subject.signup("a@example.test", "correct horse")).rejects.toEqual(refusal(IdentityErrorCode.TooManyAttempts))
+        budget.admit.mockRejectedValue(new Error("store down"))
+        await expect(subject.resend("a@example.test")).rejects.toThrow("store down")
+    })
+})
+
+describe("IdentityEmailService.resend", () => {
+    it("mails only an unconfirmed password account", async () => {
+        const entityManager = mockEntityManager({ query: [USER_BY_EMAIL, [account("unconfirmed")]], insert: [IdentityEmailTokenEntity, {}], update: [IdentityEmailTokenEntity, {}] })
+        fakeTransaction(entityManager)
+        const { subject, mailer } = await build(entityManager)
+        await subject.resend("a@example.test")
+        expect(mailer.send).toHaveBeenCalledTimes(1)
+
+        for (const rows of [[], [account()], [account("invited")]]) {
+            const other = await build(mockEntityManager({ query: [USER_BY_EMAIL, rows] }))
+            await other.subject.resend("a@example.test")
+            expect(other.mailer.send).not.toHaveBeenCalled()
+        }
+    })
+})
+
+describe("IdentityEmailService.confirm", () => {
+    it("spends a live link and stamps the confirmation through the door", async () => {
+        const entityManager = mockEntityManager({ findOne: [IdentityEmailTokenEntity, tokenRow("confirm")], update: [IdentityEmailTokenEntity, {}], query: [CONFIRM_USER, []] })
+        fakeTransaction(entityManager)
+        const { subject } = await build(entityManager)
+
+        await subject.confirm("the-token-of-the-link")
+
+        expect(entityManager.findOne).toHaveBeenCalledWith(IdentityEmailTokenEntity, expect.objectContaining({ lock: { mode: "pessimistic_write" } }))
+        expect(entityManager.query).toHaveBeenCalledWith(CONFIRM_USER, ["u-1", NOW])
+    })
+
+    it("refuses an unknown, spent or expired link with the reset-token code", async () => {
+        const entityManager = mockEntityManager({ findOne: [IdentityEmailTokenEntity, null] })
+        fakeTransaction(entityManager)
+        const { subject } = await build(entityManager)
+
+        await expect(subject.confirm("nothing")).rejects.toEqual(refusal(IdentityErrorCode.ResetTokenInvalid))
+    })
+})
+
+describe("IdentityEmailService.forgot", () => {
+    it("mails a reset link to a live account and to nobody else, with the same answer", async () => {
+        const entityManager = mockEntityManager({ query: [USER_BY_EMAIL, [account()]], insert: [IdentityEmailTokenEntity, {}], update: [IdentityEmailTokenEntity, {}] })
+        fakeTransaction(entityManager)
+        const known = await build(entityManager)
+        await known.subject.forgot("a@example.test", "vi")
+        expect(known.budget.admit).toHaveBeenCalledWith("reset", "a@example.test")
+        expect(known.mailer.send.mock.calls[0]?.[0].message.text).toContain("https://app.example.test/auth/reset?token=")
+        await known.subject.forgot("a@example.test")
+        expect(known.mailer.send).toHaveBeenCalledTimes(2)
+
+        for (const rows of [[], [account("disabled")]]) {
+            const other = await build(mockEntityManager({ query: [USER_BY_EMAIL, rows] }))
+            await expect(other.subject.forgot("a@example.test")).resolves.toBeUndefined()
+            expect(other.mailer.send).not.toHaveBeenCalled()
+        }
+    })
+})
+
+describe("IdentityEmailService.reset", () => {
+    it("sets the new password and confirms the mailbox its link proved through the door, then ends every session of the person", async () => {
+        const entityManager = mockEntityManager({ findOne: [IdentityEmailTokenEntity, tokenRow("reset")], update: [IdentityEmailTokenEntity, {}], query: [SET_PASSWORD, []] })
+        fakeTransaction(entityManager)
+        const { subject, sessions } = await build(entityManager)
+
+        await subject.reset("the-token-of-the-link", "a better password")
+
+        expect(entityManager.query).toHaveBeenCalledWith(SET_PASSWORD, ["u-1", "new-hash", true, NOW])
+        expect(sessions.closeOtherSessions).toHaveBeenCalledWith("u-1", "00000000-0000-0000-0000-000000000000")
+    })
+
+    it("refuses a weak password and a link that is not live", async () => {
+        const weak = await build(mockEntityManager())
+        await expect(weak.subject.reset("t", "short")).rejects.toEqual(refusal(IdentityErrorCode.PasswordInvalid))
+
+        const entityManager = mockEntityManager({ findOne: [IdentityEmailTokenEntity, null] })
+        fakeTransaction(entityManager)
+        const dead = await build(entityManager)
+        await expect(dead.subject.reset("t", "a better password")).rejects.toBeInstanceOf(IdentityError)
+    })
+})
+
+describe("IdentityEmailService language", () => {
+    it("writes the mail in the language the request names, and in the default one when it names none the mails are written in", async () => {
+        const subjectFor = async (language?: string): Promise<string | undefined> => {
+            const entityManager = mockEntityManager({ query: [[USER_BY_EMAIL, []], [CREATE_USER, [{ be_auth_create_user: NEW_ID }]]], insert: [IdentityEmailTokenEntity, {}], update: [IdentityEmailTokenEntity, {}] })
+            fakeTransaction(entityManager)
+            const { subject, mailer } = await build(entityManager)
+            await subject.signup("a@example.test", "correct horse", language)
+            return mailer.send.mock.calls[0]?.[0].message.subject
+        }
+        const english = await subjectFor("en")
+        expect(await subjectFor("vi")).not.toBe(english)
+        expect(await subjectFor("xx")).toBe(english)
+        expect(await subjectFor()).toBe(english)
+    })
+})

package/templates/be/auth-lite/src/modules/domain/identity/identity-email.service.ts

@@ -0,0 +1,176 @@
+// Managed by starci app sync (slot be.identity.sign-in); do not edit: run "npx starci app sync --execute".
+import { Injectable } from "@nestjs/common"
+import { IsNull, MoreThan } from "typeorm"
+import type { EntityManager } from "typeorm"
+import { AuthError, digestOf, isAcceptablePassword, normalizeEmail } from "@modules/integrations/passport"
+import type { AuthPasswords, SignInBudget } from "@modules/integrations/passport"
+import { InjectMailSettings, InjectMailer } from "@modules/integrations/mail"
+import type { MailLanguage, MailOptions, Mailer } from "@modules/integrations/mail"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { InjectPrimaryEntityManager } from "@modules/platform/database"
+import { InjectIds } from "@modules/platform/ids"
+import type { Ids } from "@modules/platform/ids"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { InjectAuthPasswords, InjectSignInBudget } from "./identity.decorators"
+import { IdentityEmailLogEvent } from "./identity-email.log-events"
+import { confirmEmailMail, resetPasswordMail } from "./messages/identity-mail.messages"
+import { accountDoors } from "./persistence/account-doors.port"
+import { IdentityEmailTokenEntity } from "./persistence/entities"
+import { IdentitySessionStoreService } from "./session-store.service"
+
+const CONFIRM = "confirm"
+const RESET = "reset"
+const SECONDS_PER_HOUR = 3600
+/** The session id no session has: closing every session "but" it closes them all. */
+const NO_SESSION = "00000000-0000-0000-0000-000000000000"
+
+type Purpose = typeof CONFIRM | typeof RESET
+
+/** The languages the mails are written in. */
+const LANGUAGES: readonly MailLanguage[] = ["vi", "en"]
+
+@Injectable()
+/**
+ * The email doors of sign-in: sign up, confirm the mailbox, resend the confirmation, forget and reset the password. A link is a
+ * random single-use token that expires and is kept only as its digest; every request counts against the address's budget and a
+ * request never says whether an address has an account.
+ */
+export class IdentityEmailService {
+    constructor(
+        @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
+        @InjectAuthPasswords() private readonly passwords: AuthPasswords,
+        @InjectSignInBudget() private readonly budget: SignInBudget,
+        @InjectMailer() private readonly mailer: Mailer,
+        @InjectMailSettings() private readonly options: MailOptions,
+        @InjectClock() private readonly clock: Clock,
+        @InjectIds() private readonly ids: Ids,
+        @InjectLogger() private readonly logger: Logger,
+        private readonly sessions: IdentitySessionStoreService,
+    ) {}
+
+    /** Creates an unconfirmed password account and mails the confirmation link; an address that already has an account is answered the same way. */
+    async signup(email: string, password: string, language?: string): Promise<void> {
+        const address = normalizeEmail(email)
+        await this.admit("signup", address)
+        if (!isAcceptablePassword(password)) throw new IdentityError({ code: IdentityErrorCode.PasswordInvalid })
+        const known = await accountDoors.userByEmail(this.entityManager, address)
+        if (known !== undefined) {
+            if (known.email_confirmed_at === null) await this.sendConfirmation(known.id, address, language)
+            return
+        }
+        const now = this.clock.now()
+        const id = this.ids.next()
+        const hash = await this.passwords.hash(password)
+        const created = await accountDoors.createUser(this.entityManager, { id, email: address, hash, confirmed: false, meta: "{}", now })
+        await this.sendConfirmation(created ?? id, address, language)
+    }
+
+    /** Mails a new confirmation link to an unconfirmed account; any other address is answered the same way. */
+    async resend(email: string, language?: string): Promise<void> {
+        const address = normalizeEmail(email)
+        await this.admit("signup", address)
+        const user = await accountDoors.userByEmail(this.entityManager, address)
+        if (user === undefined || user.email_confirmed_at !== null || user.encrypted_password === null) return
+        await this.sendConfirmation(user.id, address, language)
+    }
+
+    /** Spends a confirmation link: the mailbox becomes confirmed. */
+    async confirm(token: string): Promise<void> {
+        const now = this.clock.now()
+        await this.entityManager.transaction(async (scoped) => {
+            const row = await this.spendable(scoped, token, CONFIRM, now)
+            await scoped.update(IdentityEmailTokenEntity, { userId: row.userId, purpose: CONFIRM, usedAt: IsNull() }, { usedAt: now })
+            await accountDoors.confirmUser(scoped, row.userId, now)
+        })
+    }
+
+    /** Mails a reset link when the address has a live password account; the answer never says whether it does. */
+    async forgot(email: string, language?: string): Promise<void> {
+        const address = normalizeEmail(email)
+        await this.admit("reset", address)
+        const user = await accountDoors.userByEmail(this.entityManager, address)
+        if (user === undefined || user.disabled) return
+        const token = await this.mint(user.id, RESET, this.options.resetTtlSeconds)
+        const url = `${this.options.webOrigin}/auth/reset?token=${encodeURIComponent(token)}`
+        const mail = resetPasswordMail(this.languageOf(language), { brand: this.options.brandName, url, hours: this.hoursOf(this.options.resetTtlSeconds) })
+        await this.deliver(address, mail, RESET)
+    }
+
+    /** Spends a reset link: sets the new password, confirms the mailbox (the link proved it) and ends every session of the person. */
+    async reset(token: string, password: string): Promise<void> {
+        if (!isAcceptablePassword(password)) throw new IdentityError({ code: IdentityErrorCode.PasswordInvalid })
+        const now = this.clock.now()
+        const hash = await this.passwords.hash(password)
+        const userId = await this.entityManager.transaction(async (scoped) => {
+            const row = await this.spendable(scoped, token, RESET, now)
+            await scoped.update(IdentityEmailTokenEntity, { userId: row.userId, usedAt: IsNull() }, { usedAt: now })
+            await accountDoors.setPassword(scoped, row.userId, hash, true, now)
+            return row.userId
+        })
+        await this.sessions.closeOtherSessions(userId, NO_SESSION)
+    }
+
+    private async admit(kind: "signup" | "reset", address: string): Promise<void> {
+        try {
+            await this.budget.admit(kind, address)
+        } catch (cause) {
+            if (cause instanceof AuthError) throw new IdentityError({ code: IdentityErrorCode.TooManyAttempts, cause })
+            throw cause
+        }
+    }
+
+    private async spendable(scoped: EntityManager, token: string, purpose: Purpose, now: Date): Promise<IdentityEmailTokenEntity> {
+        const row = await scoped.findOne(IdentityEmailTokenEntity, {
+            where: { tokenHash: digestOf(token), purpose, usedAt: IsNull(), expiresAt: MoreThan(now) },
+            lock: { mode: "pessimistic_write" },
+        })
+        if (row === null) throw new IdentityError({ code: IdentityErrorCode.ResetTokenInvalid })
+        return row
+    }
+
+    /** The language a request named when it is one the mails are written in, else the default of the settings. */
+    private languageOf(language: string | undefined): MailLanguage {
+        return LANGUAGES.find((candidate) => candidate === language) ?? this.options.defaultLanguage
+    }
+
+    private async sendConfirmation(userId: string, address: string, language: string | undefined): Promise<void> {
+        const token = await this.mint(userId, CONFIRM, this.options.confirmTtlSeconds)
+        const url = `${this.options.webOrigin}/auth/confirm?token=${encodeURIComponent(token)}`
+        const mail = confirmEmailMail(this.languageOf(language), { brand: this.options.brandName, url, hours: this.hoursOf(this.options.confirmTtlSeconds) })
+        await this.deliver(address, mail, CONFIRM)
+    }
+
+    /** Stores a fresh token (older live ones of the same purpose stop working) and answers the plain token for the one link that carries it. */
+    private async mint(userId: string, purpose: Purpose, ttlSeconds: number): Promise<string> {
+        const now = this.clock.now()
+        const token = `${this.ids.next()}${this.ids.next()}`.replaceAll("-", "")
+        await this.entityManager.transaction(async (scoped) => {
+            await scoped.update(IdentityEmailTokenEntity, { userId, purpose, usedAt: IsNull() }, { usedAt: now })
+            await scoped.insert(IdentityEmailTokenEntity, {
+                id: this.ids.next(),
+                userId,
+                purpose,
+                tokenHash: digestOf(token),
+                expiresAt: new Date(now.getTime() + ttlSeconds * 1000),
+                usedAt: null,
+                createdAt: now,
+            })
+        })
+        return token
+    }
+
+    private async deliver(to: string, message: Parameters<Mailer["send"]>[0]["message"], kind: Purpose): Promise<void> {
+        try {
+            await this.mailer.send({ to, message })
+        } catch (cause) {
+            this.logger.error(IdentityEmailLogEvent.MailFailed, cause, { kind })
+        }
+    }
+
+    private hoursOf(seconds: number): number {
+        return Math.max(1, Math.ceil(seconds / SECONDS_PER_HOUR))
+    }
+}

package/templates/be/auth-lite/src/modules/domain/identity/identity-sign-in.log-events.ts

@@ -0,0 +1,6 @@
+// Managed by starci app sync (slot be.identity.sign-in); do not edit: run "npx starci app sync --execute".
+/** Log events of the sign-in decisions of identity; a line names an account by id, never by address, password or token. */
+export enum IdentitySignInLogEvent {
+    /** A first Google sign-in created an account. */
+    AccountCreated = "identity.sign_in.account_created",
+}

package/templates/be/auth-lite/src/modules/domain/identity/persistence/account-doors.port.ts

@@ -0,0 +1,98 @@
+// Managed by starci app sync (slot be.identity.sign-in); do not edit: run "npx starci app sync --execute".
+import type { EntityManager } from "typeorm"
+import { callDbFunction, returnedRows, rowShape } from "@modules/platform/database"
+
+/** The account an address stands for, with the stored hash the password is checked against. */
+export interface AccountByEmail {
+    /** The account id. */
+    readonly id: string
+    /** The sign-in address. */
+    readonly email: string
+    /** The stored bcrypt hash, or null for an account that signs in with Google only. */
+    readonly encrypted_password: string | null
+    /** When the mailbox was confirmed, or null. */
+    readonly email_confirmed_at: Date | null
+    /** True when the account is deleted or banned at the database's now(). */
+    readonly disabled: boolean
+}
+
+/** The standing of an account found by id. */
+export interface AccountById {
+    /** The account id. */
+    readonly id: string
+    /** The sign-in address, or null. */
+    readonly email: string | null
+    /** True when the account is deleted or banned at the database's now(). */
+    readonly disabled: boolean
+}
+
+/** An account to create: the id, the address, the profile keys as JSON text and the instant. */
+export interface NewAccount {
+    /** The account id. */
+    readonly id: string
+    /** The sign-in address, lower-cased. */
+    readonly email: string
+    /** The bcrypt hash, or null for an account that signs in with Google only. */
+    readonly hash: string | null
+    /** Whether the mailbox counts as confirmed. */
+    readonly confirmed: boolean
+    /** The profile keys as JSON text. */
+    readonly meta: string
+    /** The instant of creation. */
+    readonly now: Date
+}
+
+const isAccountByEmail: (value: unknown) => value is AccountByEmail = rowShape({
+    id: "string",
+    email: "string",
+    encrypted_password: "string?",
+    email_confirmed_at: "date?",
+    disabled: "boolean",
+})
+const isAccountById: (value: unknown) => value is AccountById = rowShape({ id: "string", email: "string?", disabled: "boolean" })
+const isLinkedAccount = rowShape({ be_auth_user_by_google: "string?" })
+const isCreatedAccount = rowShape({ be_auth_create_user: "string" })
+
+/**
+ * The account doors: the SECURITY DEFINER functions of the baseline migration through which the application role reads and writes
+ * auth.users and auth.identities. It holds no grant on schema auth, so no other path reaches an account.
+ */
+export const accountDoors = {
+    /** The account of an exact address, or undefined. */
+    async userByEmail(manager: EntityManager, email: string): Promise<AccountByEmail | undefined> {
+        const [row] = returnedRows(await callDbFunction(manager, "public.be_auth_user_by_email", [email]), isAccountByEmail)
+        return row
+    },
+    /** The standing of an account by id, or undefined. */
+    async userById(manager: EntityManager, userId: string): Promise<AccountById | undefined> {
+        const [row] = returnedRows(await callDbFunction(manager, "public.be_auth_user_by_id", [userId]), isAccountById)
+        return row
+    },
+    /** The account a Google subject is linked to, or null. */
+    async userByGoogle(manager: EntityManager, subject: string): Promise<string | null> {
+        const [row] = returnedRows(await callDbFunction(manager, "public.be_auth_user_by_google", [subject]), isLinkedAccount)
+        return row?.be_auth_user_by_google ?? null
+    },
+    /** Creates an account and answers its id. */
+    async createUser(manager: EntityManager, account: NewAccount): Promise<string | undefined> {
+        const args = [account.id, account.email, account.hash, account.confirmed, account.meta, account.now]
+        const [row] = returnedRows(await callDbFunction(manager, "public.be_auth_create_user", args), isCreatedAccount)
+        return row?.be_auth_create_user
+    },
+    /** Links a Google subject to an account, or refreshes the link. */
+    async linkGoogle(manager: EntityManager, userId: string, subject: string, data: string, now: Date): Promise<void> {
+        await callDbFunction(manager, "public.be_auth_link_google", [userId, subject, data, now])
+    },
+    /** Stamps the confirmation of a mailbox (a spent confirmation link) without recording a sign-in. */
+    async confirmUser(manager: EntityManager, userId: string, now: Date): Promise<void> {
+        await callDbFunction(manager, "public.be_auth_confirm_user", [userId, now])
+    },
+    /** Sets the password hash of an account; `confirm` also confirms the mailbox, as a spent reset link proves it. */
+    async setPassword(manager: EntityManager, userId: string, hash: string, confirm: boolean, now: Date): Promise<void> {
+        await callDbFunction(manager, "public.be_auth_set_password", [userId, hash, confirm, now])
+    },
+    /** Records a sign-in, confirms the mailbox when asked, and fills the profile keys the person has not set. */
+    async touchUser(manager: EntityManager, userId: string, now: Date, confirm: boolean, meta: string): Promise<void> {
+        await callDbFunction(manager, "public.be_auth_touch_user", [userId, now, confirm, meta])
+    },
+}

package/templates/be/auth-lite/src/modules/domain/identity/persistence/entities/identity-email-token.entity.ts

@@ -0,0 +1,34 @@
+// Managed by starci app sync (slot be.identity.sign-in); do not edit: run "npx starci app sync --execute".
+import { Column, Entity, PrimaryColumn } from "typeorm"
+
+@Entity({ schema: "public", name: "identity_email_tokens" })
+/** One single-use link token that confirms a mailbox or resets a password, mapped from public.identity_email_tokens; only its digest is kept. */
+export class IdentityEmailTokenEntity {
+    /** The token row id. */
+    @PrimaryColumn({ name: "id", type: "uuid" })
+    id!: string
+
+    /** The account the link is for. */
+    @Column({ name: "user_id", type: "uuid" })
+    userId!: string
+
+    /** What the link does: `confirm` or `reset`. */
+    @Column({ name: "purpose", type: "varchar", length: 16 })
+    purpose!: string
+
+    /** The SHA-256 digest of the token in the link; the token itself is never stored. */
+    @Column({ name: "token_hash", type: "varchar", length: 64 })
+    tokenHash!: string
+
+    /** When the link stops working. */
+    @Column({ name: "expires_at", type: "timestamptz" })
+    expiresAt!: Date
+
+    /** When the link was spent, or null while it is live. */
+    @Column({ name: "used_at", type: "timestamptz", nullable: true })
+    usedAt!: Date | null
+
+    /** When the link was issued. */
+    @Column({ name: "created_at", type: "timestamptz" })
+    createdAt!: Date
+}

package/templates/be/auth-lite/src/modules/domain/identity/persistence/entities/identity-refresh-token.entity.ts

@@ -31,4 +31,8 @@ export class IdentityRefreshTokenEntity {
     /** When the token was rotated away, or null while it is the live one. */
     @Column({ name: "used_at", type: "timestamptz", nullable: true })
     usedAt!: Date | null
+
+    /** How many successors replays of this token obtained within the grace window after its rotation (bounded). */
+    @Column({ name: "raced_count", type: "integer", default: 0 })
+    racedCount!: number
 }

package/templates/be/auth-lite/src/modules/domain/identity/persistence/entities/index.ts

@@ -1,17 +1,10 @@
 // Managed by starci app sync (slot be.identity.sign-in); do not edit: run "npx starci app sync --execute".
-import { AuthIdentityEntity } from "./auth-identity.entity"
-import { AuthUserEntity } from "./auth-user.entity"
 import { IdentityAttemptEntity } from "./identity-attempt.entity"
+import { IdentityEmailTokenEntity } from "./identity-email-token.entity"
 import { IdentityRefreshTokenEntity } from "./identity-refresh-token.entity"
 import { IdentitySessionEntity } from "./identity-session.entity"
 
-export { AuthIdentityEntity, AuthUserEntity, IdentityAttemptEntity, IdentityRefreshTokenEntity, IdentitySessionEntity }
+export { IdentityAttemptEntity, IdentityEmailTokenEntity, IdentityRefreshTokenEntity, IdentitySessionEntity }
 
 /** The entities of the identity capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
-export const identityEntities: ReadonlyArray<new () => object> = [
-    AuthIdentityEntity,
-    AuthUserEntity,
-    IdentityAttemptEntity,
-    IdentityRefreshTokenEntity,
-    IdentitySessionEntity,
-]
+export const identityEntities: ReadonlyArray<new () => object> = [IdentityAttemptEntity, IdentityEmailTokenEntity, IdentityRefreshTokenEntity, IdentitySessionEntity]

package/templates/be/auth-lite/src/modules/domain/identity/session-store.service.spec.ts

@@ -19,6 +19,7 @@ const row = (usedAt: Date | null): IdentityRefreshTokenEntity => ({
     createdAt: NOW,
     expiresAt: LATER,
     usedAt,
+    racedCount: 0,
 })
 
 const build = async (entityManager: MockEntityManager = mockEntityManager()) => {
@@ -39,11 +40,11 @@ describe("IdentitySessionStoreService.transaction", () => {
         })
 
         expect(entityManager.insert).toHaveBeenCalledWith(IdentitySessionEntity, { id: "s-1", userId: "u-1", createdAt: NOW, refreshedAt: NOW, userAgent: "agent", ip: "203.0.113.9" })
-        expect(entityManager.insert).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: null })
+        expect(entityManager.insert).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: null, racedCount: 0 })
         expect(transaction.commits).toBe(1)
     })
 
-    it("reads the token for update, marks it used and drops the expired ones", async () => {
+    it("reads the token for update, marks it used or raced and drops the expired ones", async () => {
         const { subject, entityManager } = await build(
             mockEntityManager({
                 findOne: [[IdentityRefreshTokenEntity, row(NOW)], [IdentityRefreshTokenEntity, null]],
@@ -56,13 +57,15 @@ describe("IdentitySessionStoreService.transaction", () => {
         const missing = await subject.transaction((tx) => tx.findTokenForUpdate("h-2"))
         await subject.transaction(async (tx) => {
             await tx.markTokenUsed("t-1", NOW)
+            await tx.markTokenRaced("t-1", 2)
             await tx.deleteExpiredTokens("u-1", NOW)
         })
 
-        expect(found).toEqual({ id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: NOW })
+        expect(found).toEqual({ id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: NOW, racedCount: 0 })
         expect(missing).toBeNull()
         expect(entityManager.findOne).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { where: { tokenHash: "h-1" }, lock: { mode: "pessimistic_write" } })
         expect(entityManager.update).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1" }, { usedAt: NOW })
+        expect(entityManager.update).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1" }, { racedCount: 2 })
         expect(entityManager.delete).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { userId: "u-1", expiresAt: LessThan(NOW) })
     })
 

package/templates/be/auth-lite/src/modules/domain/identity/session-store.service.ts

@@ -13,6 +13,7 @@ const recordOf = (row: IdentityRefreshTokenEntity): RefreshTokenRecord => ({
     tokenHash: row.tokenHash,
     expiresAt: row.expiresAt,
     usedAt: row.usedAt,
+    racedCount: row.racedCount,
 })
 
 const transactionOf = (scoped: EntityManager): SessionTransaction => ({
@@ -34,6 +35,7 @@ const transactionOf = (scoped: EntityManager): SessionTransaction => ({
             tokenHash: token.tokenHash,
             expiresAt: token.expiresAt,
             usedAt: null,
+            racedCount: 0,
         })
     },
     findTokenForUpdate: async (tokenHash) => {
@@ -43,6 +45,9 @@ const transactionOf = (scoped: EntityManager): SessionTransaction => ({
     markTokenUsed: async (tokenId, at) => {
         await scoped.update(IdentityRefreshTokenEntity, { id: tokenId }, { usedAt: at })
     },
+    markTokenRaced: async (tokenId, racedCount) => {
+        await scoped.update(IdentityRefreshTokenEntity, { id: tokenId }, { racedCount })
+    },
     deleteExpiredTokens: async (userId, before) => {
         await scoped.delete(IdentityRefreshTokenEntity, { userId, expiresAt: LessThan(before) })
     },
@@ -69,7 +74,7 @@ export class IdentitySessionStoreService implements SessionStore {
         await this.entityManager.update(IdentitySessionEntity, { id: sessionId }, { refreshedAt: now })
     }
 
-    /** Ends one session; its tokens go with it (the foreign key cascades). */
+    /** Ends one session and revokes every token of it (the foreign key cascades). */
     async closeSession(sessionId: string): Promise<void> {
         await this.entityManager.delete(IdentitySessionEntity, { id: sessionId })
     }