@starci/hfs 5.1.0 → 5.3.0

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
+}

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 { mockEntityManager } from "@starci/jest-preset"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { accountByIdRow } from "@tests/fixtures/builders/identity.builder"
+import { IdentityAccountDirectoryService } from "./account-directory.service"
+
+const USER_BY_ID = 'SELECT * FROM "public"."be_auth_user_by_id"($1)'
+
+const build = async (rows: unknown) => {
+    const entityManager = mockEntityManager({ query: [USER_BY_ID, rows] })
+    const moduleRef = await Test.createTestingModule({
+        providers: [IdentityAccountDirectoryService, { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager }],
+    }).compile()
+    return { directory: moduleRef.get(IdentityAccountDirectoryService), entityManager }
+}
+
+describe("IdentityAccountDirectoryService.find", () => {
+    it("answers the standing of a live account through the door", async () => {
+        const { directory, entityManager } = await build([accountByIdRow("live")])
+
+        expect(await directory.find("u-1")).toEqual({ id: "u-1", email: "a@example.test", disabled: false })
+        expect(entityManager.query).toHaveBeenCalledWith(USER_BY_ID, ["u-1"])
+    })
+
+    it("answers a disabled account as disabled, and an account without an address with none", async () => {
+        const banned = await build([accountByIdRow("disabled")])
+        const addressless = await build([accountByIdRow("addressless")])
+
+        expect((await banned.directory.find("u-1"))?.disabled).toBe(true)
+        expect(await addressless.directory.find("u-1")).toEqual({ id: "u-1", email: null, disabled: false })
+    })
+
+    it("answers undefined for an account that does not exist", async () => {
+        const { directory } = await build([])
+
+        expect(await directory.find("u-2")).toBeUndefined()
+    })
+
+    it("refuses a door answer that is not the account shape", async () => {
+        const { directory } = await build([{ id: "u-1", email: "a@example.test", disabled: "no" }])
+
+        await expect(directory.find("u-1")).rejects.toMatchObject({ code: "DATABASE_RETURNING_ROW_REJECTED" })
+    })
+})

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

@@ -0,0 +1,19 @@
+// 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 { InjectPrimaryEntityManager } from "@modules/platform/database"
+import { accountDoors } from "./persistence/account-doors.port"
+
+@Injectable()
+/** The package's account directory over the account doors: whether an account still stands, for a refresh to go on. */
+export class IdentityAccountDirectoryService implements AccountDirectory {
+    constructor(@InjectPrimaryEntityManager() private readonly entityManager: EntityManager) {}
+
+    /** The standing of one account (disabled is decided by the database clock), or undefined when it does not exist. */
+    async find(userId: string): Promise<AccountStanding | undefined> {
+        const account = await accountDoors.userById(this.entityManager, userId)
+        if (account === undefined) return undefined
+        return { id: account.id, email: account.email, disabled: account.disabled }
+    }
+}

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

@@ -0,0 +1,209 @@
+// 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 { LOGGER } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { IDENTITY_AUTH_PASSWORDS, IDENTITY_SIGN_IN_BUDGET } from "./identity.decorators"
+import { IdentitySignInLogEvent } from "./identity-sign-in.log-events"
+import { accountByEmailRow, accountByIdRow } from "@tests/fixtures/builders/identity.builder"
+import { IdentityAuthenticatorService } from "./authenticator.service"
+
+/** The statements callDbFunction sends for the account doors. */
+const USER_BY_EMAIL = 'SELECT * FROM "public"."be_auth_user_by_email"($1)'
+const USER_BY_ID = 'SELECT * FROM "public"."be_auth_user_by_id"($1)'
+const USER_BY_GOOGLE = 'SELECT * FROM "public"."be_auth_user_by_google"($1)'
+const CREATE_USER = 'SELECT * FROM "public"."be_auth_create_user"($1, $2, $3, $4, $5, $6)'
+const LINK_GOOGLE = 'SELECT * FROM "public"."be_auth_link_google"($1, $2, $3, $4)'
+const TOUCH_USER = 'SELECT * FROM "public"."be_auth_touch_user"($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 profile = (patch: Partial<GoogleProfile> = {}): GoogleProfile => ({
+    subject: "g-1",
+    email: "A@Example.test",
+    emailVerified: true,
+    name: "A",
+    picture: null,
+    ...patch,
+})
+
+type Stubs = ReadonlyArray<readonly [string, unknown]>
+
+const build = async (answers: Stubs, matches = true) => {
+    const entityManager: MockEntityManager = answers.length === 0 ? mockEntityManager() : mockEntityManager({ query: answers })
+    fakeTransaction(entityManager)
+    const passwords = mock<AuthPasswords>()
+    passwords.verify.mockResolvedValue(matches)
+    const budget = mock<SignInBudget>()
+    budget.counted.mockImplementation(async (_kind, _address, check) => (await check()).value)
+    const logger = mock<Logger>()
+    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() },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return { subject: moduleRef.get(IdentityAuthenticatorService), entityManager, passwords, budget, logger }
+}
+
+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 through the door", async () => {
+        const { subject, entityManager, passwords, budget } = await build([
+            [USER_BY_EMAIL, [accountByEmailRow()]],
+            [TOUCH_USER, []],
+        ])
+
+        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.query).toHaveBeenCalledWith(USER_BY_EMAIL, ["a@example.test"])
+        expect(entityManager.query).toHaveBeenCalledWith(TOUCH_USER, ["u-1", NOW, false, "{}"])
+    })
+
+    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([[USER_BY_EMAIL, []]])
+        const wrong = await build([[USER_BY_EMAIL, [accountByEmailRow()]]], 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", "")
+        expect(wrong.entityManager.query).not.toHaveBeenCalledWith(TOUCH_USER, expect.anything())
+    })
+
+    it("compares an empty password for one bcrypt cannot read, an account without a hash against the decoy", async () => {
+        const { subject, passwords } = await build([[USER_BY_EMAIL, [accountByEmailRow("passwordless")]]], false)
+
+        await expect(subject.verifyPassword("a@example.test", "x".repeat(100))).rejects.toBeInstanceOf(IdentityError)
+
+        expect(passwords.verify).toHaveBeenCalledWith("", "")
+    })
+
+    it("refuses a disabled account and an unconfirmed one after the password was right, recording no sign-in", async () => {
+        const disabled = await build([[USER_BY_EMAIL, [accountByEmailRow("disabled")]]])
+        const unconfirmed = await build([[USER_BY_EMAIL, [accountByEmailRow("unconfirmed")]]])
+
+        await expect(disabled.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))
+        expect(disabled.entityManager.query).not.toHaveBeenCalledWith(TOUCH_USER, expect.anything())
+        expect(unconfirmed.entityManager.query).not.toHaveBeenCalledWith(TOUCH_USER, expect.anything())
+    })
+})
+
+describe("IdentityAuthenticatorService.signInWithGoogle", () => {
+    it("refuses a profile without a verified address, and calls no door", async () => {
+        const { subject, entityManager } = await build([])
+
+        await expect(subject.signInWithGoogle(profile({ emailVerified: false }))).rejects.toEqual(refusal(PassportErrorCode.GoogleRejected))
+        await expect(subject.signInWithGoogle(profile({ email: null }))).rejects.toEqual(refusal(PassportErrorCode.GoogleRejected))
+        expect(entityManager.query).not.toHaveBeenCalled()
+    })
+
+    it("signs in the account a Google subject is already linked to, confirming its mailbox", async () => {
+        const { subject, entityManager } = await build([
+            [USER_BY_GOOGLE, [{ be_auth_user_by_google: "u-1" }]],
+            [LINK_GOOGLE, []],
+            [TOUCH_USER, []],
+            [USER_BY_ID, [accountByIdRow()]],
+        ])
+
+        expect(await subject.signInWithGoogle(profile())).toEqual({ userId: "u-1", email: "a@example.test" })
+
+        expect(entityManager.query).not.toHaveBeenCalledWith(USER_BY_EMAIL, expect.anything())
+        expect(entityManager.query).not.toHaveBeenCalledWith(CREATE_USER, expect.anything())
+        expect(entityManager.query).toHaveBeenCalledWith(TOUCH_USER, ["u-1", NOW, true, expect.stringContaining('"full_name":"A"')])
+    })
+
+    it("links an existing account by its verified address", async () => {
+        const { subject, entityManager } = await build([
+            [USER_BY_GOOGLE, [{ be_auth_user_by_google: null }]],
+            [USER_BY_EMAIL, [accountByEmailRow()]],
+            [LINK_GOOGLE, []],
+            [TOUCH_USER, []],
+            [USER_BY_ID, [accountByIdRow()]],
+        ])
+
+        expect(await subject.signInWithGoogle(profile())).toEqual({ userId: "u-1", email: "a@example.test" })
+
+        expect(entityManager.query).toHaveBeenCalledWith(USER_BY_EMAIL, ["a@example.test"])
+        expect(entityManager.query).toHaveBeenCalledWith(LINK_GOOGLE, ["u-1", "g-1", expect.stringContaining('"sub":"g-1"'), NOW])
+        expect(entityManager.query).not.toHaveBeenCalledWith(CREATE_USER, expect.anything())
+    })
+
+})
+
+describe("IdentityAuthenticatorService.signInWithGoogle (new accounts and refusals)", () => {
+    it("creates the account of a new person, links their Google identity and logs the id alone", async () => {
+        const { subject, entityManager, logger } = await build([
+            [USER_BY_GOOGLE, [{ be_auth_user_by_google: null }]],
+            [USER_BY_EMAIL, []],
+            [CREATE_USER, [{ be_auth_create_user: NEW_ID }]],
+            [LINK_GOOGLE, []],
+            [TOUCH_USER, []],
+            [USER_BY_ID, [accountByIdRow("live", NEW_ID)]],
+        ])
+
+        expect(await subject.signInWithGoogle(profile())).toEqual({ userId: NEW_ID, email: "a@example.test" })
+
+        expect(entityManager.query).toHaveBeenCalledWith(CREATE_USER, [NEW_ID, "a@example.test", null, true, expect.stringContaining('"full_name":"A"'), NOW])
+        expect(entityManager.query).toHaveBeenCalledWith(LINK_GOOGLE, [NEW_ID, "g-1", expect.stringContaining("g-1"), NOW])
+        expect(logger.info).toHaveBeenCalledWith(IdentitySignInLogEvent.AccountCreated, { userId: NEW_ID })
+    })
+
+    it("fills only the profile keys the Google profile has", async () => {
+        const { subject, entityManager } = await build([
+            [USER_BY_GOOGLE, [{ be_auth_user_by_google: "u-1" }]],
+            [LINK_GOOGLE, []],
+            [TOUCH_USER, []],
+            [USER_BY_ID, [accountByIdRow()]],
+        ])
+
+        await subject.signInWithGoogle(profile({ name: null, picture: "https://img.example.test/a.png" }))
+
+        const keys = { avatar_url: "https://img.example.test/a.png", picture: "https://img.example.test/a.png", email: "A@Example.test", email_verified: true }
+        expect(entityManager.query).toHaveBeenCalledWith(TOUCH_USER, ["u-1", NOW, true, JSON.stringify(keys)])
+    })
+
+    it("refuses when the create door answers no account", async () => {
+        const { subject, entityManager } = await build([
+            [USER_BY_GOOGLE, [{ be_auth_user_by_google: null }]],
+            [USER_BY_EMAIL, []],
+            [CREATE_USER, []],
+        ])
+
+        await expect(subject.signInWithGoogle(profile())).rejects.toEqual(refusal(PassportErrorCode.GoogleRejected))
+        expect(entityManager.query).not.toHaveBeenCalledWith(LINK_GOOGLE, expect.anything())
+    })
+
+    it("refuses a disabled account and an account that cannot be read back", async () => {
+        const linked: Stubs = [
+            [USER_BY_GOOGLE, [{ be_auth_user_by_google: "u-1" }]],
+            [LINK_GOOGLE, []],
+            [TOUCH_USER, []],
+        ]
+        const disabled = await build([...linked, [USER_BY_ID, [accountByIdRow("disabled")]]])
+        const gone = await build([...linked, [USER_BY_ID, []]])
+        const addressless = await build([...linked, [USER_BY_ID, [accountByIdRow("addressless")]]])
+
+        await expect(disabled.subject.signInWithGoogle(profile())).rejects.toEqual(refusal(IdentityErrorCode.AccountDisabled))
+        await expect(gone.subject.signInWithGoogle(profile())).rejects.toEqual(refusal(PassportErrorCode.GoogleRejected))
+        await expect(addressless.subject.signInWithGoogle(profile())).rejects.toEqual(refusal(PassportErrorCode.GoogleRejected))
+    })
+})

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

@@ -0,0 +1,84 @@
+// 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 { 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 { IdentitySignInLogEvent } from "./identity-sign-in.log-events"
+import { accountDoors } from "./persistence/account-doors.port"
+
+/** A Google profile whose email Google verified, so it has one. */
+type VerifiedProfile = GoogleProfile & { readonly email: string }
+
+/** The profile keys a Google sign-in may fill on the account; they never overwrite what the person already set. */
+const profileKeysOf = (profile: VerifiedProfile): Record<string, string | boolean> => ({
+    ...(profile.name === null ? {} : { full_name: profile.name, name: profile.name }),
+    ...(profile.picture === null ? {} : { avatar_url: profile.picture, picture: profile.picture }),
+    email: profile.email,
+    email_verified: profile.emailVerified,
+})
+
+@Injectable()
+/** The two sign-in decisions over the account doors: 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,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    /** 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 account = await this.budget.counted("login", address, async () => {
+            const found = await accountDoors.userByEmail(this.entityManager, address)
+            const matches = await this.passwords.verify(isPresentablePassword(password) ? password : "", found?.encrypted_password ?? "")
+            return { passed: found !== undefined && matches, value: found !== undefined && matches ? found : undefined }
+        })
+        if (account === undefined) throw new IdentityError({ code: IdentityErrorCode.PairRefused })
+        if (account.disabled) throw new IdentityError({ code: IdentityErrorCode.AccountDisabled })
+        if (account.email_confirmed_at === null) throw new IdentityError({ code: IdentityErrorCode.EmailNotConfirmed })
+        await accountDoors.touchUser(this.entityManager, account.id, this.clock.now(), false, "{}")
+        return { userId: account.id, email: account.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 verified: VerifiedProfile = { ...profile, email: profile.email }
+        const now = this.clock.now()
+        const userId = await this.entityManager.transaction(async (scoped) => {
+            const linked = await accountDoors.userByGoogle(scoped, profile.subject)
+            const byEmail = linked === null ? await accountDoors.userByEmail(scoped, address) : undefined
+            const id = linked ?? byEmail?.id ?? (await this.createFor(scoped, address, verified, now))
+            const identityData = { sub: profile.subject, email: address, name: profile.name, picture: profile.picture, email_verified: true }
+            await accountDoors.linkGoogle(scoped, id, profile.subject, JSON.stringify(identityData), now)
+            await accountDoors.touchUser(scoped, id, now, true, JSON.stringify(profileKeysOf(verified)))
+            return id
+        })
+        const account = await accountDoors.userById(this.entityManager, userId)
+        if (account?.email === undefined || account.email === null) throw new PassportError({ code: PassportErrorCode.GoogleRejected })
+        if (account.disabled) throw new IdentityError({ code: IdentityErrorCode.AccountDisabled })
+        return { userId: account.id, email: account.email }
+    }
+
+    private async createFor(scoped: EntityManager, address: string, profile: VerifiedProfile, now: Date): Promise<string> {
+        const id = this.ids.next()
+        const created = await accountDoors.createUser(scoped, { id, email: address, hash: null, confirmed: true, meta: JSON.stringify(profileKeysOf(profile)), now })
+        if (created === undefined) throw new PassportError({ code: PassportErrorCode.GoogleRejected })
+        this.logger.info(IdentitySignInLogEvent.AccountCreated, { userId: created })
+        return created
+    }
+}

package/templates/be/auth-lite/src/modules/domain/identity/identity-email.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 owned by the email doors of sign-in. */
+export enum IdentityEmailLogEvent {
+    /** A confirmation or reset mail could not be sent; the door still answers as if it was, so an address is never confirmed or denied. */
+    MailFailed = "identity.email.mail_failed",
+}