@starci/hfs 5.1.0 → 5.2.0

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

@@ -0,0 +1,23 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentitySignInService } from "@modules/domain/identity"
+import type { AccessGrant } from "@modules/integrations/passport"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { RefreshCommand } from "./refresh.command"
+
+@CommandHandler(RefreshCommand)
+/** Rotates the refresh cookie and answers a new access token; a bad cookie is cleared. */
+export class RefreshHandler extends ICQRSHandler<RefreshCommand, AccessGrant> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly signIn: IdentitySignInService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: RefreshCommand): Promise<AccessGrant> {
+        return this.signIn.refresh(command.params.request.exchange)
+    }
+}

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

@@ -0,0 +1,12 @@
+// 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 { AccessGrant } from "@modules/integrations/passport"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { ExchangeRequest } from "./auth.contracts"
+
+/** Answers a fresh access token for the cookie session without rotating the cookie. */
+export class SessionCommand extends Command<AccessGrant> {
+    constructor(readonly params: PublicExecuteParams<ExchangeRequest>) {
+        super()
+    }
+}

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

@@ -0,0 +1,23 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { CommandHandler } from "@nestjs/cqrs"
+import { IdentitySignInService } from "@modules/domain/identity"
+import type { AccessGrant } from "@modules/integrations/passport"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { SessionCommand } from "./session.command"
+
+@CommandHandler(SessionCommand)
+/** Answers a fresh access token for the cookie session without rotating the cookie. */
+export class SessionHandler extends ICQRSHandler<SessionCommand, AccessGrant> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly signIn: IdentitySignInService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: SessionCommand): Promise<AccessGrant> {
+        return this.signIn.session(command.params.request.exchange)
+    }
+}

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

@@ -0,0 +1,13 @@
+// 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 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

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

@@ -0,0 +1,16 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Module } from "@nestjs/common"
+import { LoginHandler } from "./application/login.handler"
+import { RefreshHandler } from "./application/refresh.handler"
+import { SessionHandler } from "./application/session.handler"
+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 { ConfigurableModuleClass } from "./auth.module-definition"
+
+@Module({
+    providers: [LoginHandler, RefreshHandler, SessionHandler, LogoutHandler, GoogleBeginHandler, GoogleCompleteHandler, GetJwksHandler],
+})
+/** The auth feature: the handlers behind the sign-in doors. */
+export class AuthApiModule extends ConfigurableModuleClass {}

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

@@ -0,0 +1,3 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+/** The auth feature module takes no options yet. */
+export type AuthApiOptions = Record<string, never>

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

@@ -0,0 +1,2 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+export { AuthHttpModule } from "./transport/http/auth-http.module"

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

@@ -0,0 +1,13 @@
+// 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 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

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

@@ -0,0 +1,9 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Module } from "@nestjs/common"
+import { AuthApiModule } from "../../auth.module"
+import { AuthController } from "./auth.controller"
+import { ConfigurableModuleClass } from "./auth-http.module-definition"
+
+@Module({ imports: [AuthApiModule.register({})], controllers: [AuthController] })
+/** The HTTP transport of the auth feature: the REST doors under /auth. */
+export class AuthHttpModule extends ConfigurableModuleClass {}

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

@@ -0,0 +1,3 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+/** The auth-http module takes no options yet. */
+export type AuthHttpOptions = Record<string, never>

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

@@ -0,0 +1,90 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { Body, Controller, Get, HttpCode, Post, Query, Redirect, Req, Res } from "@nestjs/common"
+import type { CommandBus, QueryBus } from "@nestjs/cqrs"
+import type { Request, Response } from "express"
+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 { GetJwksQuery } from "../../application/get-jwks.query"
+import { GoogleBeginCommand } from "../../application/google-begin.command"
+import { GoogleCompleteCommand } from "../../application/google-complete.command"
+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 { GoogleStartRequest } from "./dto/google-start.request"
+import { LoginRequest } from "./dto/login.request"
+
+@Controller("auth")
+/** The cookie doors of sign-in: email and password, Google, refresh, session, sign-out and the public keys. */
+export class AuthController {
+    constructor(
+        @InjectCommandBus() private readonly commandBus: CommandBus,
+        @InjectQueryBus() private readonly queryBus: QueryBus,
+    ) {}
+
+    /** Signs in with email and password; the refresh token is set as an httpOnly cookie. */
+    @Post("login")
+    @HttpCode(200)
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    login(
+        @Body() _body: LoginRequest,
+        @Req() req: Request,
+        @Res({ passthrough: true }) res: Response,
+    ): Promise<AccessGrant> {
+        return this.commandBus.execute(new LoginCommand({ request: { exchange: { req, res } } }))
+    }
+
+    /** Rotates the refresh cookie and answers a new access token; a bad cookie is cleared. */
+    @Post("refresh")
+    @HttpCode(200)
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    refresh(@Req() req: Request, @Res({ passthrough: true }) res: Response): Promise<AccessGrant> {
+        return this.commandBus.execute(new RefreshCommand({ request: { exchange: { req, res } } }))
+    }
+
+    /** Answers a fresh access token for the cookie session WITHOUT rotating the cookie, so parallel requests of one browser never race. */
+    @Get("session")
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    session(@Req() req: Request, @Res({ passthrough: true }) res: Response): Promise<AccessGrant> {
+        return this.commandBus.execute(new SessionCommand({ request: { exchange: { req, res } } }))
+    }
+
+    /** Ends the session of the refresh cookie and clears it. */
+    @Post("logout")
+    @HttpCode(204)
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    logout(@Req() req: Request, @Res({ passthrough: true }) res: Response): Promise<void> {
+        return this.commandBus.execute(new LogoutCommand({ request: { exchange: { req, res } } }))
+    }
+
+    /** Sends the browser to Google (authorization code with state and PKCE); `returnTo` is an absolute address on the web origin or a path. */
+    @Get("google")
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    google(@Query() _query: GoogleStartRequest, @Req() req: Request, @Res() res: Response): Promise<void> {
+        return this.commandBus.execute(new GoogleBeginCommand({ request: { exchange: { req, res } } }))
+    }
+
+    /** Google sends the browser back here; the session cookie is set and the browser lands on the web app (or its sign-in page on failure). */
+    @Get("google/callback")
+    @Redirect()
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    googleCallback(@Req() req: Request, @Res({ passthrough: true }) res: Response): Promise<GoogleRedirect> {
+        return this.commandBus.execute(new GoogleCompleteCommand({ request: { exchange: { req, res } } }))
+    }
+
+    /** The public keys access tokens verify against. */
+    @Get("jwks")
+    @Public({ reason: PublicReason.AuthHandshake })
+    @RateLimit(RateTier.Strict)
+    jwks(): Promise<JwksDocument> {
+        return this.queryBus.execute(new GetJwksQuery({ request: {} }))
+    }
+}

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

@@ -0,0 +1,17 @@
+// Managed by starci app sync (slot be.feature.auth); do not edit: run "npx starci app sync --execute".
+import { IsOptional, IsString, MaxLength } from "class-validator"
+
+/** The query that starts a Google sign-in. */
+export class GoogleStartRequest {
+    /** An absolute address on the web origin, or a path, to land on afterwards. */
+    @IsOptional()
+    @IsString()
+    @MaxLength(1024)
+    returnTo?: string
+
+    /** A path to land on afterwards (the older spelling of returnTo). */
+    @IsOptional()
+    @IsString()
+    @MaxLength(512)
+    next?: string
+}

package/templates/be/auth-lite/src/features/api/auth/transport/http/dto/login.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, IsString, MaxLength, MinLength } from "class-validator"
+
+/** The posted sign-in pair. */
+export class LoginRequest {
+    /** The sign-in address. */
+    @IsEmail()
+    @MaxLength(254)
+    email!: string
+
+    /** The password. */
+    @IsString()
+    @MinLength(1)
+    @MaxLength(128)
+    password!: string
+}

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

@@ -0,0 +1,46 @@
+// 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, mockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { authUserRow as user } from "@tests/fixtures/builders/identity.builder"
+import { AuthUserEntity } from "./persistence/entities"
+import { IdentityAccountDirectoryService, isDisabled } from "./account-directory.service"
+
+const AT = "2026-02-03T04:05:06.000Z"
+
+const build = async (rows: ReadonlyArray<AuthUserEntity | null>) => {
+    const entityManager = mockEntityManager({ findOne: rows.map((result) => [AuthUserEntity, result] as const) })
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            IdentityAccountDirectoryService,
+            { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+        ],
+    }).compile()
+    return moduleRef.get(IdentityAccountDirectoryService)
+}
+
+describe("IdentityAccountDirectoryService.find", () => {
+    it("answers the standing of a live account, a banned one, a deleted one and a missing one", async () => {
+        const subject = await build([user("live"), user("banned"), user("ban-ended"), user("deleted"), null])
+
+        expect(await subject.find("u-1")).toEqual({ id: "u-1", email: "a@example.test", disabled: false })
+        expect((await subject.find("u-1"))?.disabled).toBe(true)
+        expect((await subject.find("u-1"))?.disabled).toBe(false)
+        expect((await subject.find("u-1"))?.disabled).toBe(true)
+        expect(await subject.find("u-2")).toBeUndefined()
+    })
+})
+
+describe("isDisabled", () => {
+    it("is true for a deleted account and for a ban that has not ended", () => {
+        const now = new Date(AT)
+
+        expect(isDisabled(user("deleted"), now)).toBe(true)
+        expect(isDisabled(user("banned"), now)).toBe(true)
+        expect(isDisabled(user("ban-ended"), now)).toBe(false)
+        expect(isDisabled(user("live"), now)).toBe(false)
+    })
+})

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

@@ -0,0 +1,28 @@
+// 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 type { EntityManager } from "typeorm"
+import type { AccountDirectory, AccountStanding } from "@modules/integrations/passport"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { InjectPrimaryEntityManager } from "@modules/platform/database"
+import { AuthUserEntity } from "./persistence/entities"
+
+/** True when the account is deleted or banned at this instant. */
+export const isDisabled = (user: AuthUserEntity, now: Date): boolean =>
+    user.deletedAt !== null || (user.bannedUntil !== null && user.bannedUntil > now)
+
+@Injectable()
+/** The package's account directory over auth.users: whether an account still stands, for a refresh to go on. */
+export class IdentityAccountDirectoryService implements AccountDirectory {
+    constructor(
+        @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
+        @InjectClock() private readonly clock: Clock,
+    ) {}
+
+    /** The standing of one account, or undefined when it does not exist. */
+    async find(userId: string): Promise<AccountStanding | undefined> {
+        const user = await this.entityManager.findOne(AuthUserEntity, { where: { id: userId } })
+        if (user === null) return undefined
+        return { id: user.id, email: user.email, disabled: isDisabled(user, this.clock.now()) }
+    }
+}

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

@@ -0,0 +1,145 @@
+// 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 { PassportErrorCode } from "@modules/integrations/passport"
+import type { AuthPasswords, GoogleProfile, 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 { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { IDENTITY_AUTH_PASSWORDS, IDENTITY_SIGN_IN_BUDGET } from "./identity.decorators"
+import { authUserRow as user } from "@tests/fixtures/builders/identity.builder"
+import { IdentityAuthenticatorService } from "./authenticator.service"
+import { AuthIdentityEntity, AuthUserEntity } from "./persistence/entities"
+
+const NEW_ID = "00000000-0000-4000-8000-000000000001"
+const AT = "2026-02-03T04:05:06.000Z"
+const NOW = new Date(AT)
+const BEFORE = new Date("2026-02-03T04:00:00.000Z")
+
+const profile = (patch: Partial<GoogleProfile> = {}): GoogleProfile => ({
+    subject: "g-1",
+    email: "A@Example.test",
+    emailVerified: true,
+    name: "A",
+    picture: null,
+    ...patch,
+})
+
+const build = async (entityManager: MockEntityManager, matches = true) => {
+    const passwords = mock<AuthPasswords>()
+    passwords.verify.mockResolvedValue(matches)
+    const budget = mock<SignInBudget>()
+    budget.counted.mockImplementation(async (_kind, _address, check) => (await check()).value)
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            IdentityAuthenticatorService,
+            { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
+            { provide: IDENTITY_AUTH_PASSWORDS, useValue: passwords },
+            { provide: IDENTITY_SIGN_IN_BUDGET, useValue: budget },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: IDS, useValue: fakeIds() },
+        ],
+    }).compile()
+    return { subject: moduleRef.get(IdentityAuthenticatorService), passwords, budget }
+}
+
+const refusal = (code: string): unknown => expect.objectContaining({ code })
+
+describe("IdentityAuthenticatorService.verifyPassword", () => {
+    it("answers the person of a right pair, normalising the address, and records the sign-in", async () => {
+        const entityManager = mockEntityManager({ findOne: [AuthUserEntity, user()], update: [AuthUserEntity, {}] })
+        const { subject, passwords, budget } = await build(entityManager)
+
+        expect(await subject.verifyPassword("  A@Example.test ", "correct horse")).toEqual({ userId: "u-1", email: "a@example.test" })
+
+        expect(budget.counted).toHaveBeenCalledWith("login", "a@example.test", expect.any(Function))
+        expect(passwords.verify).toHaveBeenCalledWith("correct horse", "hash")
+        expect(entityManager.update).toHaveBeenCalledWith(AuthUserEntity, { id: "u-1" }, { lastSignInAt: NOW })
+    })
+
+    it("refuses an unknown address and a wrong password with the same code, and still spends the check on a decoy", async () => {
+        const unknown = await build(mockEntityManager({ findOne: [AuthUserEntity, null] }))
+        const wrong = await build(mockEntityManager({ findOne: [AuthUserEntity, user()] }), false)
+
+        await expect(unknown.subject.verifyPassword("a@example.test", "pw")).rejects.toEqual(refusal(IdentityErrorCode.PairRefused))
+        await expect(wrong.subject.verifyPassword("a@example.test", "pw")).rejects.toBeInstanceOf(IdentityError)
+        expect(unknown.passwords.verify).toHaveBeenCalledWith("pw", "")
+    })
+
+    it("compares an empty password for one bcrypt cannot read, an account without a hash against the decoy", async () => {
+        const { subject, passwords } = await build(mockEntityManager({ findOne: [AuthUserEntity, user("passwordless")] }), false)
+
+        await expect(subject.verifyPassword("a@example.test", "x".repeat(100))).rejects.toBeInstanceOf(IdentityError)
+
+        expect(passwords.verify).toHaveBeenCalledWith("", "")
+    })
+
+    it("refuses a banned or deleted account and an unconfirmed one after the password was right", async () => {
+        const banned = await build(mockEntityManager({ findOne: [AuthUserEntity, user("banned")] }))
+        const unconfirmed = await build(mockEntityManager({ findOne: [AuthUserEntity, user("unconfirmed")] }))
+        const addressless = await build(mockEntityManager({ findOne: [AuthUserEntity, user("addressless")] }))
+
+        await expect(banned.subject.verifyPassword("a@example.test", "pw")).rejects.toEqual(refusal(IdentityErrorCode.AccountDisabled))
+        await expect(unconfirmed.subject.verifyPassword("a@example.test", "pw")).rejects.toEqual(refusal(IdentityErrorCode.EmailNotConfirmed))
+        await expect(addressless.subject.verifyPassword("a@example.test", "pw")).rejects.toEqual(refusal(IdentityErrorCode.EmailNotConfirmed))
+    })
+})
+
+describe("IdentityAuthenticatorService.signInWithGoogle", () => {
+    it("refuses a profile without a verified address", async () => {
+        const { subject } = await build(mockEntityManager())
+
+        await expect(subject.signInWithGoogle(profile({ emailVerified: false }))).rejects.toEqual(refusal(PassportErrorCode.GoogleRejected))
+        await expect(subject.signInWithGoogle(profile({ email: null }))).rejects.toEqual(refusal(PassportErrorCode.GoogleRejected))
+    })
+
+    it("signs in the account a Google subject is already linked to", async () => {
+        const linked: AuthIdentityEntity = { id: "i-1", providerId: "g-1", userId: "u-1", identityData: {}, provider: "google", lastSignInAt: null, createdAt: BEFORE, updatedAt: BEFORE }
+        const entityManager = mockEntityManager({ findOne: [[AuthIdentityEntity, linked], [AuthUserEntity, user("unconfirmed")]], update: [AuthUserEntity, {}] })
+        fakeTransaction(entityManager)
+        const { subject } = await build(entityManager)
+
+        expect(await subject.signInWithGoogle(profile())).toEqual({ userId: "u-1", email: "a@example.test" })
+
+        expect(entityManager.insert).not.toHaveBeenCalled()
+        expect(entityManager.update).toHaveBeenCalledWith(AuthUserEntity, { id: "u-1" }, { lastSignInAt: NOW, emailConfirmedAt: NOW })
+    })
+
+    it("links an existing account by its verified address and keeps its confirmation date", async () => {
+        const entityManager = mockEntityManager({ findOne: [[AuthIdentityEntity, null], [AuthUserEntity, user()]], insert: [AuthIdentityEntity, {}], update: [AuthUserEntity, {}] })
+        fakeTransaction(entityManager)
+        const { subject } = await build(entityManager)
+
+        expect(await subject.signInWithGoogle(profile())).toEqual({ userId: "u-1", email: "a@example.test" })
+
+        expect(entityManager.insert).toHaveBeenCalledWith(AuthIdentityEntity, expect.objectContaining({ id: NEW_ID, providerId: "g-1", userId: "u-1", provider: "google" }))
+        expect(entityManager.update).toHaveBeenCalledWith(AuthUserEntity, { id: "u-1" }, { lastSignInAt: NOW, emailConfirmedAt: BEFORE })
+    })
+
+    it("creates the account of a new person and links their Google identity", async () => {
+        const entityManager = mockEntityManager({
+            findOne: [[AuthIdentityEntity, null], [AuthUserEntity, null], [AuthUserEntity, user("created")]],
+            insert: [[AuthUserEntity, {}], [AuthIdentityEntity, {}]],
+            update: [AuthUserEntity, {}],
+        })
+        fakeTransaction(entityManager)
+        const { subject } = await build(entityManager)
+
+        expect(await subject.signInWithGoogle(profile())).toEqual({ userId: NEW_ID, email: "a@example.test" })
+
+        expect(entityManager.insert).toHaveBeenCalledWith(AuthUserEntity, expect.objectContaining({ id: NEW_ID, email: "a@example.test", encryptedPassword: null, emailConfirmedAt: NOW }))
+    })
+
+    it("refuses a disabled account and an account that cannot be read back", async () => {
+        const disabled = mockEntityManager({ findOne: [[AuthIdentityEntity, null], [AuthUserEntity, user("deleted")]], insert: [AuthIdentityEntity, {}], update: [AuthUserEntity, {}] })
+        fakeTransaction(disabled)
+        const missing = mockEntityManager({ findOne: [[AuthIdentityEntity, null], [AuthUserEntity, null]], insert: [[AuthUserEntity, {}], [AuthIdentityEntity, {}]], update: [AuthUserEntity, {}] })
+        fakeTransaction(missing)
+
+        await expect((await build(disabled)).subject.signInWithGoogle(profile())).rejects.toEqual(refusal(IdentityErrorCode.AccountDisabled))
+        await expect((await build(missing)).subject.signInWithGoogle(profile())).rejects.toEqual(refusal(PassportErrorCode.GoogleRejected))
+    })
+})

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

@@ -0,0 +1,95 @@
+// 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 type { EntityManager } from "typeorm"
+import { PassportError, PassportErrorCode, isPresentablePassword, normalizeEmail } from "@modules/integrations/passport"
+import type { AuthAuthenticator, AuthPasswords, AuthSubject, GoogleProfile, SignInBudget } from "@modules/integrations/passport"
+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 { isDisabled } from "./account-directory.service"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { InjectAuthPasswords, InjectSignInBudget } from "./identity.decorators"
+import { AuthIdentityEntity, AuthUserEntity } from "./persistence/entities"
+
+const GOOGLE = "google"
+
+@Injectable()
+/** The two sign-in decisions: is this email and password right, and which account does this Google profile stand for. */
+export class IdentityAuthenticatorService implements AuthAuthenticator {
+    constructor(
+        @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
+        @InjectAuthPasswords() private readonly passwords: AuthPasswords,
+        @InjectSignInBudget() private readonly budget: SignInBudget,
+        @InjectClock() private readonly clock: Clock,
+        @InjectIds() private readonly ids: Ids,
+    ) {}
+
+    /** Verifies the pair. An unknown address and a wrong password answer the same refusal; only wrong passwords count against the budget. */
+    async verifyPassword(email: string, password: string): Promise<AuthSubject> {
+        const address = normalizeEmail(email)
+        const user = await this.budget.counted("login", address, async () => {
+            const found = await this.entityManager.findOne(AuthUserEntity, { where: { email: address, isAnonymous: false } })
+            const matches = await this.passwords.verify(isPresentablePassword(password) ? password : "", found?.encryptedPassword ?? "")
+            return { passed: found !== null && matches, value: found !== null && matches ? found : null }
+        })
+        if (user === null) throw new IdentityError({ code: IdentityErrorCode.PairRefused })
+        const now = this.clock.now()
+        if (isDisabled(user, now)) throw new IdentityError({ code: IdentityErrorCode.AccountDisabled })
+        if (user.emailConfirmedAt === null || user.email === null) throw new IdentityError({ code: IdentityErrorCode.EmailNotConfirmed })
+        await this.entityManager.update(AuthUserEntity, { id: user.id }, { lastSignInAt: now })
+        return { userId: user.id, email: user.email }
+    }
+
+    /** Finds the account a Google subject is linked to, else links by a verified email, else creates the account. */
+    async signInWithGoogle(profile: GoogleProfile): Promise<AuthSubject> {
+        if (profile.email === null || !profile.emailVerified) throw new PassportError({ code: PassportErrorCode.GoogleRejected })
+        const address = normalizeEmail(profile.email)
+        const now = this.clock.now()
+        const user = await this.entityManager.transaction(async (scoped) => {
+            const linked = await scoped.findOne(AuthIdentityEntity, { where: { provider: GOOGLE, providerId: profile.subject } })
+            const known =
+                (linked === null ? null : await scoped.findOne(AuthUserEntity, { where: { id: linked.userId } })) ??
+                (await scoped.findOne(AuthUserEntity, { where: { email: address, isAnonymous: false } }))
+            const person = known ?? (await this.create(scoped, address, now))
+            if (linked === null) {
+                await scoped.insert(AuthIdentityEntity, {
+                    id: this.ids.next(),
+                    providerId: profile.subject,
+                    userId: person.id,
+                    provider: GOOGLE,
+                    identityData: { sub: profile.subject, email: address, name: profile.name, picture: profile.picture, email_verified: true },
+                    lastSignInAt: now,
+                    createdAt: now,
+                    updatedAt: now,
+                })
+            }
+            await scoped.update(AuthUserEntity, { id: person.id }, { lastSignInAt: now, emailConfirmedAt: person.emailConfirmedAt ?? now })
+            return person
+        })
+        if (isDisabled(user, now)) throw new IdentityError({ code: IdentityErrorCode.AccountDisabled })
+        return { userId: user.id, email: address }
+    }
+
+    private async create(scoped: EntityManager, address: string, now: Date): Promise<AuthUserEntity> {
+        const id = this.ids.next()
+        await scoped.insert(AuthUserEntity, {
+            id,
+            aud: "authenticated",
+            role: "authenticated",
+            email: address,
+            encryptedPassword: null,
+            emailConfirmedAt: now,
+            lastSignInAt: now,
+            bannedUntil: null,
+            deletedAt: null,
+            isAnonymous: false,
+            createdAt: now,
+            updatedAt: now,
+        })
+        const created = await scoped.findOne(AuthUserEntity, { where: { id } })
+        if (created === null) throw new PassportError({ code: PassportErrorCode.GoogleRejected })
+        return created
+    }
+}

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

@@ -0,0 +1,38 @@
+// 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: "auth", name: "identities" })
+/** One external identity of an account (a Google subject), mapped from auth.identities of db/bootstrap.sql. */
+export class AuthIdentityEntity {
+    /** The row id. */
+    @PrimaryColumn({ name: "id", type: "uuid" })
+    id!: string
+
+    /** The provider's id of the person (the Google subject). */
+    @Column({ name: "provider_id", type: "text" })
+    providerId!: string
+
+    /** The account the identity belongs to. */
+    @Column({ name: "user_id", type: "uuid" })
+    userId!: string
+
+    /** What the provider told us, as JSON. */
+    @Column({ name: "identity_data", type: "jsonb" })
+    identityData!: Record<string, string | boolean | null>
+
+    /** The provider name. */
+    @Column({ name: "provider", type: "text" })
+    provider!: string
+
+    /** The last sign-in through this identity, or null. */
+    @Column({ name: "last_sign_in_at", type: "timestamptz", nullable: true })
+    lastSignInAt!: Date | null
+
+    /** When the identity was linked. */
+    @Column({ name: "created_at", type: "timestamptz", nullable: true })
+    createdAt!: Date | null
+
+    /** When the identity last changed. */
+    @Column({ name: "updated_at", type: "timestamptz", nullable: true })
+    updatedAt!: Date | null
+}