@starci/hfs 5.1.0 → 5.2.0

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

@@ -0,0 +1,54 @@
+// 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: "users" })
+/** One person who can sign in, mapped from auth.users of db/bootstrap.sql (the GoTrue column set; only the columns sign-in reads or writes). */
+export class AuthUserEntity {
+    /** The account id. */
+    @PrimaryColumn({ name: "id", type: "uuid" })
+    id!: string
+
+    /** The audience the row carries. */
+    @Column({ name: "aud", type: "varchar", length: 255, nullable: true })
+    aud!: string | null
+
+    /** The database role the row carries. */
+    @Column({ name: "role", type: "varchar", length: 255, nullable: true })
+    role!: string | null
+
+    /** The sign-in address, lower-cased. */
+    @Column({ name: "email", type: "varchar", length: 255, nullable: true })
+    email!: string | null
+
+    /** The bcrypt hash of the password, or null for an account that signs in with Google only. */
+    @Column({ name: "encrypted_password", type: "varchar", length: 255, nullable: true })
+    encryptedPassword!: string | null
+
+    /** When the mailbox was confirmed, or null. */
+    @Column({ name: "email_confirmed_at", type: "timestamptz", nullable: true })
+    emailConfirmedAt!: Date | null
+
+    /** The last sign-in, or null. */
+    @Column({ name: "last_sign_in_at", type: "timestamptz", nullable: true })
+    lastSignInAt!: Date | null
+
+    /** Until when the account is banned, or null. */
+    @Column({ name: "banned_until", type: "timestamptz", nullable: true })
+    bannedUntil!: Date | null
+
+    /** When the account was deleted, or null. */
+    @Column({ name: "deleted_at", type: "timestamptz", nullable: true })
+    deletedAt!: Date | null
+
+    /** True for an anonymous account, which never signs in with an address. */
+    @Column({ name: "is_anonymous", type: "boolean" })
+    isAnonymous!: boolean
+
+    /** When the account was created. */
+    @Column({ name: "created_at", type: "timestamptz", nullable: true })
+    createdAt!: Date | null
+
+    /** When the account last changed. */
+    @Column({ name: "updated_at", type: "timestamptz", nullable: true })
+    updatedAt!: Date | null
+}

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

@@ -0,0 +1,18 @@
+// 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_attempts" })
+/** The attempts of one kind and address in one window, mapped from public.identity_attempts; the address is hashed in the key. */
+export class IdentityAttemptEntity {
+    /** The kind and the digest of the address. */
+    @PrimaryColumn({ name: "key", type: "varchar", length: 128 })
+    key!: string
+
+    /** The attempts counted in the window. */
+    @Column({ name: "hits", type: "integer" })
+    hits!: number
+
+    /** When the window ends; an attempt after it opens a fresh one. */
+    @Column({ name: "reset_at", type: "timestamptz" })
+    resetAt!: Date
+}

package/templates/be/auth-lite/src/modules/domain/identity/persistence/entities/identity-refresh-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_refresh_tokens" })
+/** One refresh token of a device session, mapped from public.identity_refresh_tokens; only its digest is stored, and a spent token is kept for replay detection. */
+export class IdentityRefreshTokenEntity {
+    /** The row id. */
+    @PrimaryColumn({ name: "id", type: "uuid" })
+    id!: string
+
+    /** The device session the token belongs to. */
+    @Column({ name: "session_id", type: "uuid" })
+    sessionId!: string
+
+    /** The account the session belongs to. */
+    @Column({ name: "user_id", type: "uuid" })
+    userId!: string
+
+    /** The digest of the token, unique. */
+    @Column({ name: "token_hash", type: "text" })
+    tokenHash!: string
+
+    /** When the row was written. */
+    @Column({ name: "created_at", type: "timestamptz" })
+    createdAt!: Date
+
+    /** When the token stops working. */
+    @Column({ name: "expires_at", type: "timestamptz" })
+    expiresAt!: Date
+
+    /** 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
+}

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

@@ -0,0 +1,30 @@
+// 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_sessions" })
+/** One device session, mapped from public.identity_sessions of the baseline migration (the tables of @starci/auth). */
+export class IdentitySessionEntity {
+    /** The session id. */
+    @PrimaryColumn({ name: "id", type: "uuid" })
+    id!: string
+
+    /** The account the session belongs to. */
+    @Column({ name: "user_id", type: "uuid" })
+    userId!: string
+
+    /** When the session opened. */
+    @Column({ name: "created_at", type: "timestamptz" })
+    createdAt!: Date
+
+    /** When the session last refreshed. */
+    @Column({ name: "refreshed_at", type: "timestamptz" })
+    refreshedAt!: Date
+
+    /** The bounded user agent that opened the session. */
+    @Column({ name: "user_agent", type: "text", nullable: true })
+    userAgent!: string | null
+
+    /** The caller address that opened the session. */
+    @Column({ name: "ip", type: "text", nullable: true })
+    ip!: string | null
+}

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

@@ -0,0 +1,17 @@
+// 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 { IdentityRefreshTokenEntity } from "./identity-refresh-token.entity"
+import { IdentitySessionEntity } from "./identity-session.entity"
+
+export { AuthIdentityEntity, AuthUserEntity, IdentityAttemptEntity, 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,
+]

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

@@ -0,0 +1,86 @@
+// 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 { LessThanOrEqual, MoreThan } from "typeorm"
+import { FakeClock, mockEntityManager, queueQueryBuilders } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { IdentityAttemptEntity } from "./persistence/entities"
+import { IdentityRateCounterService } from "./rate-counter.service"
+
+const AT = "2026-02-03T04:05:06.000Z"
+const NOW = new Date(AT)
+const RESET_AT = new Date("2026-02-03T04:20:06.000Z")
+const WINDOW_MS = 900_000
+
+const isIncrement = (value: unknown): value is { readonly hits: () => string } =>
+    typeof value === "object" && value !== null && "hits" in value && typeof value.hits === "function"
+
+const build = async (entityManager: MockEntityManager) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            IdentityRateCounterService,
+            { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+        ],
+    }).compile()
+    return moduleRef.get(IdentityRateCounterService)
+}
+
+describe("IdentityRateCounterService.consume", () => {
+    it("counts a hit in the live window and compares it with the limit", async () => {
+        const entityManager = mockEntityManager()
+        const [counting] = queueQueryBuilders(entityManager, [{ execute: { raw: [{ hits: 3 }] } }, { execute: { raw: [{ hits: 4 }] } }])
+        const subject = await build(entityManager)
+
+        expect(await subject.consume("login:abc", WINDOW_MS, 3)).toBe(true)
+        expect(await subject.consume("login:abc", WINDOW_MS, 3)).toBe(false)
+
+        expect(counting?.callsOf("where")[0]).toEqual([{ key: "login:abc", resetAt: MoreThan(NOW) }])
+        const [patch] = counting?.callsOf("set")[0] ?? []
+        expect(isIncrement(patch)).toBe(true)
+        if (isIncrement(patch)) expect(patch.hits()).toBe("hits + 1")
+    })
+
+    it("restarts an ended window at one hit", async () => {
+        const entityManager = mockEntityManager({ update: [IdentityAttemptEntity, { affected: 1 }] })
+        queueQueryBuilders(entityManager, [{ execute: { raw: [] } }])
+        const subject = await build(entityManager)
+
+        expect(await subject.consume("login:abc", WINDOW_MS, 3)).toBe(true)
+
+        expect(entityManager.update).toHaveBeenCalledWith(IdentityAttemptEntity, { key: "login:abc", resetAt: LessThanOrEqual(NOW) }, { hits: 1, resetAt: RESET_AT })
+    })
+
+    it("opens a window when the restart reports no affected count", async () => {
+        const entityManager = mockEntityManager({ update: [IdentityAttemptEntity, {}] })
+        const [, inserting] = queueQueryBuilders(entityManager, [{ execute: { raw: [] } }, { execute: { raw: [] } }])
+        const subject = await build(entityManager)
+
+        expect(await subject.consume("login:abc", WINDOW_MS, 3)).toBe(true)
+
+        expect(inserting?.callsOf("execute")).toHaveLength(1)
+    })
+
+    it("opens a missing window at one hit, and a limit of zero admits nobody", async () => {
+        const entityManager = mockEntityManager({ update: [IdentityAttemptEntity, { affected: 0 }] })
+        const [, inserting] = queueQueryBuilders(entityManager, [{ execute: { raw: [] } }, { execute: { raw: [] } }])
+        const subject = await build(entityManager)
+
+        expect(await subject.consume("login:abc", WINDOW_MS, 0)).toBe(false)
+
+        expect(inserting?.callsOf("values")[0]).toEqual([{ key: "login:abc", hits: 1, resetAt: RESET_AT }])
+    })
+})
+
+describe("IdentityRateCounterService.clear", () => {
+    it("forgets the window of a key", async () => {
+        const entityManager = mockEntityManager({ delete: [IdentityAttemptEntity, {}] })
+        const subject = await build(entityManager)
+
+        await subject.clear("login:abc")
+
+        expect(entityManager.delete).toHaveBeenCalledWith(IdentityAttemptEntity, { key: "login:abc" })
+    })
+})

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

@@ -0,0 +1,45 @@
+// 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 { LessThanOrEqual, MoreThan } from "typeorm"
+import type { EntityManager } from "typeorm"
+import type { RateCounter } from "@modules/integrations/passport"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { InjectPrimaryEntityManager, returnedRows, rowShape } from "@modules/platform/database"
+import { IdentityAttemptEntity } from "./persistence/entities"
+
+const isCountedWindow = rowShape({ hits: "number" })
+
+@Injectable()
+/** The package's rate counter over identity_attempts: a fixed window per key, counted in one statement so every replica agrees. */
+export class IdentityRateCounterService implements RateCounter {
+    constructor(
+        @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
+        @InjectClock() private readonly clock: Clock,
+    ) {}
+
+    /** Counts one hit in the window and says whether the key is still within the limit. */
+    async consume(key: string, windowMs: number, limit: number): Promise<boolean> {
+        const now = this.clock.now()
+        const counted = await this.entityManager
+            .createQueryBuilder(IdentityAttemptEntity, "attempt")
+            .update()
+            .set({ hits: () => "hits + 1" })
+            .where({ key, resetAt: MoreThan(now) })
+            .returning("hits")
+            .execute()
+        const [live] = returnedRows(counted.raw, isCountedWindow)
+        if (live !== undefined) return live.hits <= limit
+        const resetAt = new Date(now.getTime() + windowMs)
+        const restarted = await this.entityManager.update(IdentityAttemptEntity, { key, resetAt: LessThanOrEqual(now) }, { hits: 1, resetAt })
+        if ((restarted.affected ?? 0) === 0) {
+            await this.entityManager.createQueryBuilder(IdentityAttemptEntity, "attempt").insert().values({ key, hits: 1, resetAt }).orIgnore().execute()
+        }
+        return limit >= 1
+    }
+
+    /** Forgets the window of a key. */
+    async clear(key: string): Promise<void> {
+        await this.entityManager.delete(IdentityAttemptEntity, { key })
+    }
+}

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

@@ -0,0 +1,97 @@
+// 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 { LessThan, Not } from "typeorm"
+import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { IdentityRefreshTokenEntity, IdentitySessionEntity } from "./persistence/entities"
+import { IdentitySessionStoreService } from "./session-store.service"
+
+const NOW = new Date("2026-02-03T04:05:06.000Z")
+const LATER = new Date("2026-03-03T04:05:06.000Z")
+
+const row = (usedAt: Date | null): IdentityRefreshTokenEntity => ({
+    id: "t-1",
+    sessionId: "s-1",
+    userId: "u-1",
+    tokenHash: "h-1",
+    createdAt: NOW,
+    expiresAt: LATER,
+    usedAt,
+})
+
+const build = async (entityManager: MockEntityManager = mockEntityManager()) => {
+    const transaction = fakeTransaction(entityManager)
+    const moduleRef = await Test.createTestingModule({
+        providers: [IdentitySessionStoreService, { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager }],
+    }).compile()
+    return { subject: moduleRef.get(IdentitySessionStoreService), entityManager, transaction }
+}
+
+describe("IdentitySessionStoreService.transaction", () => {
+    it("opens a session and stores a live token in one transaction", async () => {
+        const { subject, entityManager, transaction } = await build(mockEntityManager({ insert: [[IdentitySessionEntity, {}], [IdentityRefreshTokenEntity, {}]] }))
+
+        await subject.transaction(async (tx) => {
+            await tx.openSession({ id: "s-1", userId: "u-1", now: NOW, userAgent: "agent", ip: "203.0.113.9" })
+            await tx.insertToken({ id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER })
+        })
+
+        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(transaction.commits).toBe(1)
+    })
+
+    it("reads the token for update, marks it used and drops the expired ones", async () => {
+        const { subject, entityManager } = await build(
+            mockEntityManager({
+                findOne: [[IdentityRefreshTokenEntity, row(NOW)], [IdentityRefreshTokenEntity, null]],
+                update: [IdentityRefreshTokenEntity, {}],
+                delete: [IdentityRefreshTokenEntity, {}],
+            }),
+        )
+
+        const found = await subject.transaction((tx) => tx.findTokenForUpdate("h-1"))
+        const missing = await subject.transaction((tx) => tx.findTokenForUpdate("h-2"))
+        await subject.transaction(async (tx) => {
+            await tx.markTokenUsed("t-1", NOW)
+            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(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.delete).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { userId: "u-1", expiresAt: LessThan(NOW) })
+    })
+
+    it("rolls the transaction back when the work throws", async () => {
+        const { subject, transaction } = await build()
+
+        await expect(subject.transaction(() => Promise.reject(new Error("disk full")))).rejects.toThrow("disk full")
+
+        expect(transaction.rollbacks).toBe(1)
+    })
+})
+
+describe("IdentitySessionStoreService", () => {
+    it("finds a token outside a transaction, or none", async () => {
+        const { subject } = await build(mockEntityManager({ findOne: [[IdentityRefreshTokenEntity, row(null)], [IdentityRefreshTokenEntity, null]] }))
+
+        expect(await subject.findToken("h-1")).toMatchObject({ id: "t-1", usedAt: null })
+        expect(await subject.findToken("h-2")).toBeNull()
+    })
+
+    it("touches, closes and closes the others of a session", async () => {
+        const { subject, entityManager } = await build(mockEntityManager({ update: [IdentitySessionEntity, {}], delete: [IdentitySessionEntity, {}] }))
+
+        await subject.touchSession("s-1", NOW)
+        await subject.closeSession("s-1")
+        await subject.closeOtherSessions("u-1", "s-1")
+
+        expect(entityManager.update).toHaveBeenCalledWith(IdentitySessionEntity, { id: "s-1" }, { refreshedAt: NOW })
+        expect(entityManager.delete).toHaveBeenCalledWith(IdentitySessionEntity, { id: "s-1" })
+        expect(entityManager.delete).toHaveBeenCalledWith(IdentitySessionEntity, { userId: "u-1", id: Not("s-1") })
+    })
+})

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

@@ -0,0 +1,81 @@
+// 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 { LessThan, Not } from "typeorm"
+import type { EntityManager } from "typeorm"
+import type { NewSession, RefreshTokenRecord, SessionStore, SessionTransaction } from "@modules/integrations/passport"
+import { InjectPrimaryEntityManager } from "@modules/platform/database"
+import { IdentityRefreshTokenEntity, IdentitySessionEntity } from "./persistence/entities"
+
+const recordOf = (row: IdentityRefreshTokenEntity): RefreshTokenRecord => ({
+    id: row.id,
+    sessionId: row.sessionId,
+    userId: row.userId,
+    tokenHash: row.tokenHash,
+    expiresAt: row.expiresAt,
+    usedAt: row.usedAt,
+})
+
+const transactionOf = (scoped: EntityManager): SessionTransaction => ({
+    openSession: async (session: NewSession) => {
+        await scoped.insert(IdentitySessionEntity, {
+            id: session.id,
+            userId: session.userId,
+            createdAt: session.now,
+            refreshedAt: session.now,
+            userAgent: session.userAgent,
+            ip: session.ip,
+        })
+    },
+    insertToken: async (token) => {
+        await scoped.insert(IdentityRefreshTokenEntity, {
+            id: token.id,
+            sessionId: token.sessionId,
+            userId: token.userId,
+            tokenHash: token.tokenHash,
+            expiresAt: token.expiresAt,
+            usedAt: null,
+        })
+    },
+    findTokenForUpdate: async (tokenHash) => {
+        const row = await scoped.findOne(IdentityRefreshTokenEntity, { where: { tokenHash }, lock: { mode: "pessimistic_write" } })
+        return row === null ? null : recordOf(row)
+    },
+    markTokenUsed: async (tokenId, at) => {
+        await scoped.update(IdentityRefreshTokenEntity, { id: tokenId }, { usedAt: at })
+    },
+    deleteExpiredTokens: async (userId, before) => {
+        await scoped.delete(IdentityRefreshTokenEntity, { userId, expiresAt: LessThan(before) })
+    },
+})
+
+@Injectable()
+/** The package's session store over the entities of its tables: one transaction per rotation, the token row locked for update. */
+export class IdentitySessionStoreService implements SessionStore {
+    constructor(@InjectPrimaryEntityManager() private readonly entityManager: EntityManager) {}
+
+    /** Runs the work in one database transaction. */
+    transaction<T>(work: (tx: SessionTransaction) => Promise<T>): Promise<T> {
+        return this.entityManager.transaction((scoped) => work(transactionOf(scoped)))
+    }
+
+    /** The token with this digest, or null. */
+    async findToken(tokenHash: string): Promise<RefreshTokenRecord | null> {
+        const row = await this.entityManager.findOne(IdentityRefreshTokenEntity, { where: { tokenHash } })
+        return row === null ? null : recordOf(row)
+    }
+
+    /** Marks a session refreshed. */
+    async touchSession(sessionId: string, now: Date): Promise<void> {
+        await this.entityManager.update(IdentitySessionEntity, { id: sessionId }, { refreshedAt: now })
+    }
+
+    /** Ends one session; its tokens go with it (the foreign key cascades). */
+    async closeSession(sessionId: string): Promise<void> {
+        await this.entityManager.delete(IdentitySessionEntity, { id: sessionId })
+    }
+
+    /** Ends every session of an account but one. */
+    async closeOtherSessions(userId: string, keepSessionId: string): Promise<void> {
+        await this.entityManager.delete(IdentitySessionEntity, { userId, id: Not(keepSessionId) })
+    }
+}

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

@@ -0,0 +1,78 @@
+// 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 { mock } from "@starci/jest-preset"
+import { AuthError, PassportError, PassportErrorCode } from "@modules/integrations/passport"
+import type { AccessGrant, AuthDoors, AuthSessions, GoogleRedirect, HttpExchange } from "@modules/integrations/passport"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { IDENTITY_AUTH_DOORS, IDENTITY_AUTH_SESSIONS } from "./identity.decorators"
+import { IdentitySignInService } from "./sign-in.service"
+
+const GRANT: AccessGrant = { accessToken: "token", expiresIn: 900, expiresAt: "2026-02-03T04:20:06.000Z", user: { id: "u-1", email: "a@example.test" } }
+const REDIRECT: GoogleRedirect = { url: "https://app.example.test/", statusCode: 303 }
+const EXCHANGE = mock<HttpExchange>()
+
+const build = async () => {
+    const doors = mock<AuthDoors>()
+    const sessions = mock<AuthSessions>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [IdentitySignInService, { provide: IDENTITY_AUTH_DOORS, useValue: doors }, { provide: IDENTITY_AUTH_SESSIONS, useValue: sessions }],
+    }).compile()
+    return { subject: moduleRef.get(IdentitySignInService), doors, sessions }
+}
+
+describe("IdentitySignInService", () => {
+    it("hands each cookie door the exchange and answers what the package answers", async () => {
+        const { subject, doors } = await build()
+        doors.login.mockResolvedValue(GRANT)
+        doors.refresh.mockResolvedValue(GRANT)
+        doors.session.mockResolvedValue(GRANT)
+        doors.logout.mockResolvedValue()
+        doors.beginGoogle.mockResolvedValue()
+        doors.completeGoogle.mockResolvedValue(REDIRECT)
+
+        expect(await subject.login(EXCHANGE)).toBe(GRANT)
+        expect(await subject.refresh(EXCHANGE)).toBe(GRANT)
+        expect(await subject.session(EXCHANGE)).toBe(GRANT)
+        await subject.logout(EXCHANGE)
+        await subject.beginGoogle(EXCHANGE)
+        expect(await subject.completeGoogle(EXCHANGE)).toBe(REDIRECT)
+
+        for (const door of [doors.login, doors.refresh, doors.session, doors.logout, doors.beginGoogle, doors.completeGoogle]) expect(door).toHaveBeenCalledWith(EXCHANGE)
+    })
+
+    it("serves the public keys", async () => {
+        const { subject, sessions } = await build()
+        sessions.jwks.mockResolvedValue({ keys: [] })
+
+        expect(await subject.jwks()).toEqual({ keys: [] })
+    })
+
+    it("turns a refusal of the package into the error family that owns its code", async () => {
+        const { subject, doors } = await build()
+        doors.refresh.mockRejectedValue(new AuthError("IDENTITY_REFRESH_REUSED"))
+        doors.login.mockRejectedValue(new AuthError("PASSPORT_GOOGLE_REJECTED"))
+
+        const identity: unknown = await subject.refresh(EXCHANGE).catch((error: unknown) => error)
+        const passport: unknown = await subject.login(EXCHANGE).catch((error: unknown) => error)
+
+        expect(identity).toBeInstanceOf(IdentityError)
+        expect(identity).toMatchObject({ code: IdentityErrorCode.RefreshReused })
+        expect(passport).toBeInstanceOf(PassportError)
+        expect(passport).toMatchObject({ code: PassportErrorCode.GoogleRejected })
+    })
+
+    it("reads a code neither family names as unauthenticated", async () => {
+        const { subject, doors } = await build()
+        doors.login.mockRejectedValue(Object.assign(new AuthError("IDENTITY_REFRESH_REUSED"), { code: "NOT_A_CODE" }))
+
+        await expect(subject.login(EXCHANGE)).rejects.toMatchObject({ code: IdentityErrorCode.Unauthenticated })
+    })
+
+    it("rethrows a failure that is not a sign-in refusal as it is", async () => {
+        const { subject, doors } = await build()
+        doors.login.mockRejectedValue(new Error("boom"))
+
+        await expect(subject.login(EXCHANGE)).rejects.toThrow("boom")
+    })
+})

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

@@ -0,0 +1,87 @@
+// 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 { AuthError, PassportError, PassportErrorCode } from "@modules/integrations/passport"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { InjectAuthDoors, InjectAuthSessions } from "./identity.decorators"
+import type { AccessGrant, AuthDoors, AuthSessions, GoogleRedirect, HttpExchange, JwksDocument } from "@modules/integrations/passport"
+
+/** The wire codes of the package that belong to the passport family (the token, key and Google legs). */
+const PASSPORT_CODES: ReadonlyArray<PassportErrorCode> = [
+    PassportErrorCode.AccessTokenInvalid,
+    PassportErrorCode.KeyInvalid,
+    PassportErrorCode.MissingCredentials,
+    PassportErrorCode.GoogleStateInvalid,
+    PassportErrorCode.GoogleRejected,
+    PassportErrorCode.GoogleUnavailable,
+]
+
+/** The wire codes of the package that belong to the identity family (the session and the sign-in refusals). */
+const IDENTITY_CODES: ReadonlyArray<IdentityErrorCode> = [
+    IdentityErrorCode.RefreshInvalid,
+    IdentityErrorCode.RefreshReused,
+    IdentityErrorCode.AccountDisabled,
+    IdentityErrorCode.TooManyAttempts,
+    IdentityErrorCode.PairRefused,
+    IdentityErrorCode.EmailNotConfirmed,
+]
+
+/** The error of the family that owns a wire code of the package; a code neither family names reads as unauthenticated. */
+const familyOf = (error: AuthError): IdentityError | PassportError => {
+    const passport = PASSPORT_CODES.find((each) => each === error.code)
+    if (passport !== undefined) return new PassportError({ code: passport, cause: error })
+    const identity = IDENTITY_CODES.find((each) => each === error.code) ?? IdentityErrorCode.Unauthenticated
+    return new IdentityError({ code: identity, cause: error })
+}
+
+@Injectable()
+/** The cookie doors of sign-in for the transport: the package's doors with its refusals turned into the passport error family the errors filter maps. */
+export class IdentitySignInService {
+    constructor(
+        @InjectAuthDoors() private readonly doors: AuthDoors,
+        @InjectAuthSessions() private readonly sessions: AuthSessions,
+    ) {}
+
+    /** Email and password through the local strategy; the refresh token goes into the cookie. */
+    login(exchange: HttpExchange): Promise<AccessGrant> {
+        return this.refusing(() => this.doors.login(exchange))
+    }
+
+    /** Rotates the cookie token and answers a new access token. */
+    refresh(exchange: HttpExchange): Promise<AccessGrant> {
+        return this.refusing(() => this.doors.refresh(exchange))
+    }
+
+    /** Answers a fresh access token for the cookie session without rotating the cookie. */
+    session(exchange: HttpExchange): Promise<AccessGrant> {
+        return this.refusing(() => this.doors.session(exchange))
+    }
+
+    /** Ends the session of the cookie and clears it. */
+    logout(exchange: HttpExchange): Promise<void> {
+        return this.refusing(() => this.doors.logout(exchange))
+    }
+
+    /** Sends the browser to the Google consent screen. */
+    beginGoogle(exchange: HttpExchange): Promise<void> {
+        return this.refusing(() => this.doors.beginGoogle(exchange))
+    }
+
+    /** Finishes the Google round trip; a failure redirects to the sign-in page instead of throwing. */
+    completeGoogle(exchange: HttpExchange): Promise<GoogleRedirect> {
+        return this.refusing(() => this.doors.completeGoogle(exchange))
+    }
+
+    /** The public key document access tokens verify against. */
+    jwks(): Promise<JwksDocument> {
+        return this.refusing(() => this.sessions.jwks())
+    }
+
+    private async refusing<T>(work: () => Promise<T>): Promise<T> {
+        try {
+            return await work()
+        } catch (cause) {
+            if (cause instanceof AuthError) throw familyOf(cause)
+            throw cause
+        }
+    }
+}