@starci/hfs 5.1.0 → 5.3.0

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,95 @@
+// 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("signs the caller out of every other device, keeping the session of the token", async () => {
+        const { subject, sessions } = await build()
+        sessions.endOthers.mockResolvedValue()
+
+        await subject.endOthers({ id: "u-1", role: "authenticated", sessionId: "s-1" })
+
+        expect(sessions.endOthers).toHaveBeenCalledWith("u-1", "s-1")
+    })
+
+    it("refuses to sign out the other devices of a token that names no session", async () => {
+        const { subject, sessions } = await build()
+        sessions.endOthers.mockRejectedValue(new AuthError("IDENTITY_UNAUTHENTICATED"))
+
+        await expect(subject.endOthers({ id: "u-1", role: "authenticated" })).rejects.toMatchObject({ code: IdentityErrorCode.Unauthenticated })
+        expect(sessions.endOthers).toHaveBeenCalledWith("u-1", undefined)
+    })
+
+    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,93 @@
+// 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 type { Principal } from "@modules/platform/cqrs"
+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))
+    }
+
+    /** Signs the person out of every other device; the session of the caller stays. */
+    endOthers(principal: Principal): Promise<void> {
+        return this.refusing(() => this.sessions.endOthers(principal.id, principal.sessionId))
+    }
+
+    /** 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
+        }
+    }
+}

package/templates/be/auth-lite/src/tests/fixtures/builders/identity.builder.ts

@@ -0,0 +1,40 @@
+// Managed by starci app sync (slot be.identity.sign-in); do not edit: run "npx starci app sync --execute".
+const BEFORE = new Date("2026-02-03T04:00:00.000Z")
+
+/** The kinds of account the sign-in reads by address. */
+export type AccountByEmailVariant = "live" | "disabled" | "unconfirmed" | "passwordless" | "invited"
+
+/** The kinds of account the sign-in reads by id. */
+export type AccountByIdVariant = "live" | "disabled" | "addressless"
+
+/** A row of the by-address door: `disabled` is what the database decided at its own now(). */
+export interface AccountByEmailRow {
+    id: string
+    email: string
+    encrypted_password: string | null
+    email_confirmed_at: Date | null
+    disabled: boolean
+}
+
+/** A row of the by-id door. */
+export interface AccountByIdRow {
+    id: string
+    email: string | null
+    disabled: boolean
+}
+
+/** The row the by-address door answers for a confirmed password account of the given variant. */
+export const accountByEmailRow = (variant: AccountByEmailVariant = "live"): AccountByEmailRow => ({
+    id: "u-1",
+    email: "a@example.test",
+    encrypted_password: variant === "passwordless" || variant === "invited" ? null : "hash",
+    email_confirmed_at: variant === "unconfirmed" || variant === "invited" ? null : BEFORE,
+    disabled: variant === "disabled",
+})
+
+/** The row the by-id door answers for the account of the given variant; `id` is the account the spec stands for. */
+export const accountByIdRow = (variant: AccountByIdVariant = "live", id = "u-1"): AccountByIdRow => ({
+    id,
+    email: variant === "addressless" ? null : "a@example.test",
+    disabled: variant === "disabled",
+})

package/templates/be/inbox/module-definition.ts.tpl

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { @@Provider@@InboxOptions } from "./@@provider@@-inbox.options"
 
-const built = new ConfigurableModuleBuilder<@@Provider@@InboxOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<@@Provider@@InboxOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module class the module extends. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<@@Provider@@InboxOptions>()

package/templates/be/inbox/platform/event-bus/event-bus.module-definition.ts.tpl

@@ -1,14 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { EventBusOptions } from "./event-bus.options"
 
-const built = new ConfigurableModuleBuilder<EventBusOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<EventBusOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module class the module extends. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The injection token of the registered options. */
-export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = defineCapabilityModule<EventBusOptions>()

package/templates/be/inbox/platform/inbox/inbox.module-definition.ts.tpl

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineCapabilityModule } from "@starci/nest-kit"
 import type { InboxOptions } from "./inbox.options"
 
-const built = new ConfigurableModuleBuilder<InboxOptions>()
-    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
-    .build()
-type Host = ConfigurableModuleHost<InboxOptions, "register", "create", { isGlobal: boolean }>
-
 /** The configurable-module class the module extends. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<InboxOptions>()

package/templates/be/patterns/api/feature.module-definition.ts.tpl

@@ -1,12 +1,6 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineConfigurableModule } from "@starci/nest-kit"
 import type { @@Feature@@ApiOptions } from "./@@feature@@.options"
 
-const built = new ConfigurableModuleBuilder<@@Feature@@ApiOptions>().setClassMethodName("register").build()
-type Host = ConfigurableModuleHost<@@Feature@@ApiOptions, "register", "create", {}>
-
 /** The configurable-module base of the @@feature@@ module. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The injection token of the registered options. */
-export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    defineConfigurableModule<@@Feature@@ApiOptions>()

package/templates/be/patterns/api/graphql.module-definition.ts.tpl

@@ -1,12 +1,6 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineConfigurableModule } from "@starci/nest-kit"
 import type { @@Feature@@GraphqlOptions } from "./@@feature@@-graphql.options"
 
-const built = new ConfigurableModuleBuilder<@@Feature@@GraphqlOptions>().setClassMethodName("register").build()
-type Host = ConfigurableModuleHost<@@Feature@@GraphqlOptions, "register", "create", {}>
-
 /** The configurable-module base of the @@feature@@-graphql module. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The injection token of the registered options. */
-export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    defineConfigurableModule<@@Feature@@GraphqlOptions>()

package/templates/be/patterns/cli/group.module-definition.ts.tpl

@@ -1,12 +1,5 @@
-import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import { defineConfigurableModule } from "@starci/nest-kit"
 import type { @@Group@@Options } from "./@@group@@.options"
 
-const built = new ConfigurableModuleBuilder<@@Group@@Options>().setClassMethodName("register").build()
-type Host = ConfigurableModuleHost<@@Group@@Options, "register", "create", {}>
-
 /** The configurable-module base of the @@group@@ module. */
-export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
-/** The injection token of the registered options. */
-export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
-/** The options of a synchronous registration, for the register signature. */
-export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = defineConfigurableModule<@@Group@@Options>()