@starci/hfs 5.0.8 → 5.2.0

package/templates/be/skeleton-lite/src/modules/domain/identity/identity.decorators.ts

@@ -2,7 +2,7 @@ import { SetMetadata, applyDecorators, createParamDecorator } from "@nestjs/comm
 import type { ExecutionContext } from "@nestjs/common"
 import { injector } from "@modules/platform/composition"
 import type { DoorDecorator, TypedParameterDecorator } from "@modules/platform/composition"
-import type { VerifyAccessToken } from "@modules/integrations/passport"
+import type { AuthDoors, AuthPasswords, AuthSessions, SignInBudget, VerifyAccessToken } from "@modules/integrations/passport"
 import { ServerToServer, requestOf } from "@modules/platform/http-security"
 import type { Principal } from "@modules/platform/cqrs"
 import type { CredentialAuthenticator, CredentialMetadata } from "./credential.contracts"
@@ -10,6 +10,27 @@ import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
 import { PublicReason } from "./identity.contracts"
 import type { PublicMetadata } from "./identity.contracts"
 
+/** Token of the sign-in doors of the package, provided by the identity module from the passport integration. */
+export const IDENTITY_AUTH_DOORS: unique symbol = Symbol("domain.identity.auth-doors")
+/** Token of the rotating sessions of the package. */
+export const IDENTITY_AUTH_SESSIONS: unique symbol = Symbol("domain.identity.auth-sessions")
+/** Token of the password hasher of the package. */
+export const IDENTITY_AUTH_PASSWORDS: unique symbol = Symbol("domain.identity.auth-passwords")
+/** Token of the failures-only sign-in budget of the package. */
+export const IDENTITY_SIGN_IN_BUDGET: unique symbol = Symbol("domain.identity.sign-in-budget")
+
+/** Injects the sign-in doors. Parameter type: AuthDoors. */
+export const InjectAuthDoors = (): TypedParameterDecorator<AuthDoors> => injector<AuthDoors>(IDENTITY_AUTH_DOORS)
+
+/** Injects the rotating sessions. Parameter type: AuthSessions. */
+export const InjectAuthSessions = (): TypedParameterDecorator<AuthSessions> => injector<AuthSessions>(IDENTITY_AUTH_SESSIONS)
+
+/** Injects the password hasher. Parameter type: AuthPasswords. */
+export const InjectAuthPasswords = (): TypedParameterDecorator<AuthPasswords> => injector<AuthPasswords>(IDENTITY_AUTH_PASSWORDS)
+
+/** Injects the sign-in budget. Parameter type: SignInBudget. */
+export const InjectSignInBudget = (): TypedParameterDecorator<SignInBudget> => injector<SignInBudget>(IDENTITY_SIGN_IN_BUDGET)
+
 /** Token of the access-token verifier the composition root hands to identity. */
 export const ACCESS_TOKEN_VERIFIER: unique symbol = Symbol("domain.identity.access-token-verifier")
 
@@ -47,7 +68,7 @@ export const Credential = (metadata: CredentialMetadata): DoorDecorator =>
     applyDecorators(SetMetadata(CREDENTIAL_KEY, metadata), ServerToServer())
 
 /** The authenticated caller established by the default-deny guard. */
-export const CurrentPrincipal = createParamDecorator((_data: unknown, context: ExecutionContext): Principal => {
+export const CurrentPrincipal: ReturnType<typeof createParamDecorator> = createParamDecorator((_data: unknown, context: ExecutionContext): Principal => {
     const principal = requestOf(context).principal
     if (!principal) throw new IdentityError({ code: IdentityErrorCode.Unauthenticated })
     return principal

package/templates/be/skeleton-lite/src/modules/domain/identity/identity.module.ts

@@ -1,10 +1,32 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule, Provider } from "@nestjs/common"
+import {
+    PASSPORT_ACCOUNTS,
+    PASSPORT_AUTHENTICATOR,
+    PASSPORT_DOORS,
+    PASSPORT_PASSWORDS,
+    PASSPORT_RATE_COUNTER,
+    PASSPORT_SESSIONS,
+    PASSPORT_SESSION_STORE,
+    PASSPORT_SIGN_IN_BUDGET,
+} from "@modules/integrations/passport"
+import { IdentityAccountDirectoryService } from "./account-directory.service"
 import { AuthGuard } from "./auth.guard"
+import { IdentityAuthenticatorService } from "./authenticator.service"
 import { CredentialGuard } from "./credential.guard"
 import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
-import { ACCESS_TOKEN_VERIFIER, CREDENTIAL_AUTHENTICATOR } from "./identity.decorators"
+import {
+    ACCESS_TOKEN_VERIFIER,
+    CREDENTIAL_AUTHENTICATOR,
+    IDENTITY_AUTH_DOORS,
+    IDENTITY_AUTH_PASSWORDS,
+    IDENTITY_AUTH_SESSIONS,
+    IDENTITY_SIGN_IN_BUDGET,
+} from "./identity.decorators"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./identity.module-definition"
+import { IdentityRateCounterService } from "./rate-counter.service"
+import { IdentitySessionStoreService } from "./session-store.service"
+import { IdentitySignInService } from "./sign-in.service"
 
 const refusingAuthenticator: Provider = {
     provide: CREDENTIAL_AUTHENTICATOR,
@@ -34,8 +56,31 @@ export class IdentityModule extends ConfigurableModuleClass {
                 authenticator,
                 CredentialGuard,
                 AuthGuard,
+                IdentitySessionStoreService,
+                IdentityAccountDirectoryService,
+                IdentityRateCounterService,
+                IdentityAuthenticatorService,
+                IdentitySignInService,
+                { provide: IDENTITY_AUTH_DOORS, useExisting: PASSPORT_DOORS },
+                { provide: IDENTITY_AUTH_SESSIONS, useExisting: PASSPORT_SESSIONS },
+                { provide: IDENTITY_AUTH_PASSWORDS, useExisting: PASSPORT_PASSWORDS },
+                { provide: IDENTITY_SIGN_IN_BUDGET, useExisting: PASSPORT_SIGN_IN_BUDGET },
+                { provide: PASSPORT_SESSION_STORE, useExisting: IdentitySessionStoreService },
+                { provide: PASSPORT_ACCOUNTS, useExisting: IdentityAccountDirectoryService },
+                { provide: PASSPORT_RATE_COUNTER, useExisting: IdentityRateCounterService },
+                { provide: PASSPORT_AUTHENTICATOR, useExisting: IdentityAuthenticatorService },
+            ],
+            exports: [
+                CredentialGuard,
+                CREDENTIAL_AUTHENTICATOR,
+                AuthGuard,
+                ACCESS_TOKEN_VERIFIER,
+                IdentitySignInService,
+                PASSPORT_SESSION_STORE,
+                PASSPORT_ACCOUNTS,
+                PASSPORT_RATE_COUNTER,
+                PASSPORT_AUTHENTICATOR,
             ],
-            exports: [CredentialGuard, CREDENTIAL_AUTHENTICATOR, AuthGuard, ACCESS_TOKEN_VERIFIER],
         }
     }
 }

package/templates/be/skeleton-lite/src/modules/domain/identity/index.ts

@@ -5,3 +5,5 @@ export { IDENTITY_MESSAGES } from "./messages/identity.messages"
 export { PublicReason } from "./identity.contracts"
 export { ACCESS_TOKEN_VERIFIER, Public } from "./identity.decorators"
 export { IdentityModule } from "./identity.module"
+export { identityEntities } from "./persistence/entities"
+export { IdentitySignInService } from "./sign-in.service"

package/templates/be/skeleton-lite/src/modules/domain/identity/messages/identity.messages.ts

@@ -0,0 +1,24 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the identity codes, Vietnamese and English. */
+export const IDENTITY_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.IDENTITY_UNAUTHENTICATED":
+            "Bạn cần đăng nhập để thực hiện thao tác này.",
+        "errors.IDENTITY_REFRESH_INVALID": "Phiên đăng nhập không hợp lệ hoặc đã hết hạn.",
+        "errors.IDENTITY_REFRESH_REUSED": "Phiên đăng nhập đã kết thúc vì bị dùng lại. Hãy đăng nhập lại.",
+        "errors.IDENTITY_ACCOUNT_DISABLED": "Tài khoản này đã bị khóa.",
+        "errors.IDENTITY_TOO_MANY_ATTEMPTS": "Quá nhiều lần thử. Hãy thử lại sau.",
+        "errors.IDENTITY_INVALID_CREDENTIALS": "Email hoặc mật khẩu không đúng.",
+        "errors.IDENTITY_EMAIL_NOT_CONFIRMED": "Hãy xác nhận email trước khi đăng nhập.",
+    },
+    en: {
+        "errors.IDENTITY_UNAUTHENTICATED": "You need to sign in to do this.",
+        "errors.IDENTITY_REFRESH_INVALID": "The session is invalid or has expired.",
+        "errors.IDENTITY_REFRESH_REUSED": "The session ended because it was used again. Please sign in again.",
+        "errors.IDENTITY_ACCOUNT_DISABLED": "This account is disabled.",
+        "errors.IDENTITY_TOO_MANY_ATTEMPTS": "Too many attempts. Try again later.",
+        "errors.IDENTITY_INVALID_CREDENTIALS": "The email or password is wrong.",
+        "errors.IDENTITY_EMAIL_NOT_CONFIRMED": "Confirm your email before signing in.",
+    },
+}

package/templates/be/skeleton-lite/src/modules/integrations/object-storage/index.ts

@@ -1,4 +1,4 @@
-export { createObjectStorage } from "./object-storage.client"
+export { OBJECT_STORAGE } from "@starci/object-storage"
 export { parseObjectStorageConfig } from "./object-storage.config"
-export { InjectObjectStorage, OBJECT_STORAGE } from "./object-storage.decorators"
-export type { ObjectStorage, PresignedRequest, ObjectStorageOptions } from "./object-storage.options"
+export { ObjectStorageModule } from "./object-storage.module"
+export type { ObjectStorageOptions } from "./object-storage.options"

package/templates/be/skeleton-lite/src/modules/integrations/object-storage/object-storage.config.ts

@@ -1,6 +1,8 @@
 import type { EnvSource } from "@modules/platform/config"
 import type { ObjectStorageOptions } from "./object-storage.options"
 
+const PRESIGN_TTL_SECONDS = 300
+
 /** Reads the object storage configuration with no credential or endpoint defaults; secrets read `<KEY>_FILE` first. */
 export const parseObjectStorageConfig = (env: EnvSource): ObjectStorageOptions => ({
     endpoint: env.url("STORAGE_ENDPOINT"),
@@ -8,5 +10,5 @@ export const parseObjectStorageConfig = (env: EnvSource): ObjectStorageOptions =
     bucket: env.string("STORAGE_BUCKET"),
     accessKeyId: env.secret("STORAGE_ACCESS_KEY_ID"),
     secretAccessKey: env.secret("STORAGE_SECRET_ACCESS_KEY"),
-    presignTtlSeconds: env.int("STORAGE_PRESIGN_TTL_SECONDS", 300),
+    defaultExpiresIn: env.int("STORAGE_PRESIGN_TTL_SECONDS", PRESIGN_TTL_SECONDS),
 })

package/templates/be/skeleton-lite/src/modules/integrations/object-storage/object-storage.decorators.ts

@@ -1,9 +1,13 @@
+import { OBJECT_STORAGE } from "@starci/object-storage"
+import type { ObjectStorage } from "@starci/object-storage"
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
-import type { ObjectStorage } from "./object-storage.options"
 
-/** Token of the object storage port. */
-export const OBJECT_STORAGE: unique symbol = Symbol("integrations.object-storage")
+/** Token of the bucket of the app's objects. */
+export const OBJECT_STORAGE_BUCKET: unique symbol = Symbol("integrations.object-storage.bucket")
 
-/** Injects the object storage port. Parameter type: ObjectStorage. */
+/** Injects the object storage port of `@starci/object-storage`. Parameter type: ObjectStorage. */
 export const InjectObjectStorage = (): TypedParameterDecorator<ObjectStorage> => injector<ObjectStorage>(OBJECT_STORAGE)
+
+/** Injects the bucket of the app's objects. Parameter type: string. */
+export const InjectObjectStorageBucket = (): TypedParameterDecorator<string> => injector<string>(OBJECT_STORAGE_BUCKET)

package/templates/be/skeleton-lite/src/modules/integrations/object-storage/object-storage.module-definition.ts

@@ -0,0 +1,12 @@
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
+import type { ObjectStorageOptions } from "./object-storage.options"
+
+const built = new ConfigurableModuleBuilder<ObjectStorageOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()
+type Host = ConfigurableModuleHost<ObjectStorageOptions, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module base of the object storage glue; `isGlobal` is decided by the app root. */
+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

package/templates/be/skeleton-lite/src/modules/integrations/object-storage/object-storage.module.ts

@@ -0,0 +1,29 @@
+import { ObjectStorageModule as StorageModule } from "@starci/object-storage"
+import type { ObjectStorageOptions as StorageSettings } from "@starci/object-storage"
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { CLOCK } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { OBJECT_STORAGE_BUCKET } from "./object-storage.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./object-storage.module-definition"
+
+@Module({})
+/** Composes `@starci/object-storage` with the app's typed settings and clock, and provides the bucket of the app's objects. */
+export class ObjectStorageModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const { bucket, isGlobal, ...settings } = options
+        const base = super.register(options)
+        const storage = StorageModule.registerAsync({
+            inject: [CLOCK],
+            useFactory: (clock: Clock): StorageSettings => ({ ...settings, clock }),
+        })
+        return {
+            ...base,
+            imports: [...(base.imports ?? []), storage],
+            providers: [...(base.providers ?? []), { provide: OBJECT_STORAGE_BUCKET, useValue: bucket }],
+            exports: [...(base.exports ?? []), storage, OBJECT_STORAGE_BUCKET],
+            global: isGlobal === true,
+        }
+    }
+}

package/templates/be/skeleton-lite/src/modules/integrations/object-storage/object-storage.options.ts

@@ -1,35 +1,10 @@
-import type { Secret } from "@modules/platform/config"
+import type { ObjectStorageOptions as StorageSettings } from "@starci/object-storage"
 
-/** S3-compatible object storage (MinIO in lite) parsed once at API boot. */
-export interface ObjectStorageOptions {
-    /** The S3 endpoint origin. */
-    readonly endpoint: string
-    /** The region the endpoint signs for. */
-    readonly region: string
+/**
+ * S3-compatible object storage (MinIO in lite) parsed once at API boot: the settings of `@starci/object-storage` (its clock is
+ * the app's `Clock`) and the one bucket of the app's objects. The key layout belongs to the domain that stores the object.
+ */
+export interface ObjectStorageOptions extends Omit<StorageSettings, "clock"> {
     /** The bucket of the app's objects. */
     readonly bucket: string
-    /** The access key id. */
-    readonly accessKeyId: Secret
-    /** The secret access key. */
-    readonly secretAccessKey: Secret
-    /** The lifetime of a presigned URL in seconds. */
-    readonly presignTtlSeconds: number
-}
-
-/** One presigned request: the URL the browser calls and when it stops working. */
-export interface PresignedRequest {
-    /** The presigned URL. */
-    readonly url: string
-    /** The expiry instant, ISO-8601. */
-    readonly expiresAt: string
-}
-
-/** The object storage port: presigned PUT and GET of one key and a server-side delete. */
-export interface ObjectStorage {
-    /** A presigned PUT of `key` with its content type fixed. */
-    presignPut(key: string, contentType: string): Promise<PresignedRequest>
-    /** A presigned GET of `key`. */
-    presignGet(key: string): Promise<PresignedRequest>
-    /** Deletes `key`. */
-    remove(key: string): Promise<void>
 }

package/templates/be/skeleton-lite/src/modules/integrations/passport/errors/passport.error.ts

@@ -1,21 +1,30 @@
 import { DomainError } from "@modules/platform/errors"
 import type { ErrorKind } from "@modules/platform/errors"
 
-/** Codes of the passport integration. */
+/** Codes of the passport integration: the wire codes @starci/auth names for the token, key and Google legs (the kit spec holds the parity). */
 export enum PassportErrorCode {
-    /** The access token failed signature or required-claim verification. */
+    /** The access token failed signature, issuer, audience or expiry verification. */
     AccessTokenInvalid = "PASSPORT_ACCESS_TOKEN_INVALID",
-    /** The email and password do not match an account. */
-    CredentialsRefused = "PASSPORT_CREDENTIALS_REFUSED",
-    /** The OAuth state or PKCE verifier of a callback does not match the request that started it. */
-    OAuthStateInvalid = "PASSPORT_OAUTH_STATE_INVALID",
+    /** The signing key set is unusable. */
+    KeyInvalid = "PASSPORT_KEY_INVALID",
+    /** The request carried no email or password. */
+    MissingCredentials = "PASSPORT_MISSING_CREDENTIALS",
+    /** The Google round trip could not be proven to be ours (state, PKCE or cookie). */
+    GoogleStateInvalid = "PASSPORT_GOOGLE_STATE_INVALID",
+    /** Google refused the consent or answered no usable account. */
+    GoogleRejected = "PASSPORT_GOOGLE_REJECTED",
+    /** This deployment has no Google client. */
+    GoogleUnavailable = "PASSPORT_GOOGLE_UNAVAILABLE",
 }
 
-/** How each passport integration code travels. */
+/** How each passport code travels. */
 export const PASSPORT_ERROR_KINDS: Record<PassportErrorCode, ErrorKind> = {
     [PassportErrorCode.AccessTokenInvalid]: "unauthenticated",
-    [PassportErrorCode.CredentialsRefused]: "unauthenticated",
-    [PassportErrorCode.OAuthStateInvalid]: "unauthenticated",
+    [PassportErrorCode.KeyInvalid]: "internal",
+    [PassportErrorCode.MissingCredentials]: "invalid",
+    [PassportErrorCode.GoogleStateInvalid]: "unauthenticated",
+    [PassportErrorCode.GoogleRejected]: "unauthenticated",
+    [PassportErrorCode.GoogleUnavailable]: "unavailable",
 }
 
 /** The one error class of the passport integration. */

package/templates/be/skeleton-lite/src/modules/integrations/passport/index.ts

@@ -1,12 +1,36 @@
+export { AuthError, isPresentablePassword, normalizeEmail } from "@starci/auth/server"
+export type {
+    AccountDirectory,
+    AccountStanding,
+    AuthAuthenticator,
+    AuthDoors,
+    AuthPasswords,
+    AuthSessions,
+    AuthSubject,
+    GoogleProfile,
+    HttpExchange,
+    NewSession,
+    RateCounter,
+    RefreshTokenRecord,
+    SessionStore,
+    SessionTransaction,
+    SignInBudget,
+} from "@starci/auth/server"
+export type { AccessGrant, GoogleRedirect, JwksDocument } from "@starci/auth/contracts"
 export { parsePassportConfig } from "./passport.config"
-export { OWN_TOKEN_VERIFIER, PASSPORT_OPTIONS, PASSWORD_ACCOUNTS } from "./passport.decorators"
-export { PASSPORT_ERROR_KINDS, PassportErrorCode } from "./errors/passport.error"
-export { createTokenKit, tokenKit } from "./passport.tokens"
-export type { TokenKit } from "./passport.tokens"
-export { hashPassword, verifyPassword } from "./passport.password"
-export { clearRefreshCookie, newRefreshToken, refreshTokenHash, setRefreshCookie } from "./passport.cookie"
-export { GoogleStrategy } from "./strategies/google.strategy"
-export type { GoogleIdentity } from "./strategies/google.strategy"
-export { LocalStrategy } from "./strategies/local.strategy"
-export type { FindPasswordAccount, PasswordAccount } from "./strategies/local.strategy"
-export type { OwnPrincipal, PassportOptions, VerifyAccessToken } from "./passport.options"
+export {
+    OWN_TOKEN_VERIFIER,
+    PASSPORT_ACCOUNTS,
+    PASSPORT_AUTHENTICATOR,
+    PASSPORT_DOORS,
+    PASSPORT_OPTIONS,
+    PASSPORT_PASSWORDS,
+    PASSPORT_RATE_COUNTER,
+    PASSPORT_SESSION_STORE,
+    PASSPORT_SESSIONS,
+    PASSPORT_SIGN_IN_BUDGET,
+} from "./passport.decorators"
+export { PASSPORT_ERROR_KINDS, PassportError, PassportErrorCode } from "./errors/passport.error"
+export { passportKit } from "./passport.kit"
+export { passportModule } from "./passport.registration"
+export type { PassportOptions, VerifyAccessToken } from "./passport.options"

package/templates/be/skeleton-lite/src/modules/integrations/passport/passport.config.spec.ts

@@ -5,13 +5,9 @@ import { parsePassportConfig } from "./passport.config"
 const CONFIG: unique symbol = Symbol("passport.config")
 
 const REQUIRED = {
-    GOOGLE_CLIENT_ID: "client",
-    GOOGLE_CLIENT_SECRET: "client-secret",
-    GOOGLE_CALLBACK_URL: "https://api.example.com/auth/google/callback",
     AUTH_JWT_ISSUER: "https://api.example.com",
-    AUTH_JWT_AUDIENCE: "app",
     AUTH_JWT_PRIVATE_KEY: "key",
-    AUTH_JWT_KEY_ID: "kid-1",
+    AUTH_WEB_ORIGIN: "https://app.example.com/home",
 }
 
 const build = async () => {
@@ -21,14 +17,54 @@ const build = async () => {
 
 const parse = async (extra: Record<string, string>) => (await build()).parsePassportConfig(new EnvSource({ ...REQUIRED, ...extra }))
 
+describe("the required keys", () => {
+    it("reads the issuer, the web origin and the signing key, and defaults the lifetimes and the budget", async () => {
+        const options = await parse({})
+        expect(options.issuer).toBe("https://api.example.com")
+        expect(options.returnOrigin).toBe("https://app.example.com")
+        expect(options.keys).toHaveLength(1)
+        expect(options.audience).toBeUndefined()
+        expect(options).toMatchObject({
+            accessTtlSeconds: 900,
+            refreshTtlSeconds: 2_592_000,
+            bcryptCost: 10,
+            google: null,
+            cookie: { name: "refresh_token" },
+            budget: { loginAttempts: 10, resetAttempts: 5, windowMs: 900_000 },
+        })
+    })
+
+    it("refuses a boot without the signing key", async () => {
+        const subject = await build()
+        const { AUTH_JWT_PRIVATE_KEY: _key, ...without } = REQUIRED
+        expect(() => subject.parsePassportConfig(new EnvSource(without))).toThrow()
+    })
+})
+
+describe("the Google client", () => {
+    it("is declared by its client id and then needs its secret and callback", async () => {
+        const options = await parse({ GOOGLE_CLIENT_ID: "client", GOOGLE_CLIENT_SECRET: "secret", GOOGLE_CALLBACK_URL: "https://api.example.com/auth/google/callback" })
+        expect(options.google).toMatchObject({ clientId: "client", callbackUrl: "https://api.example.com/auth/google/callback" })
+        await expect(parse({ GOOGLE_CLIENT_ID: "client" })).rejects.toBeDefined()
+    })
+})
+
+describe("the key set", () => {
+    it("keeps the previous public key beside the signing key while a rotation runs", async () => {
+        const options = await parse({ AUTH_JWT_KEY_ID: "new", AUTH_JWT_PREVIOUS_PUBLIC_KEY: "previous-pem", AUTH_JWT_PREVIOUS_KEY_ID: "old" })
+        expect(options.keys.map((key) => key.keyId)).toEqual(["new", "old"])
+        expect(options.keys[1]?.publicKey).toBe("previous-pem")
+    })
+})
+
 describe("AUTH_COOKIE_DOMAIN", () => {
     it("leaves the refresh cookie host-only when the key is not declared", async () => {
-        expect((await parse({})).refresh.cookieDomain).toBeUndefined()
+        expect((await parse({})).cookie.domain).toBeUndefined()
     })
 
     it("reads a bare registrable domain", async () => {
-        expect((await parse({ AUTH_COOKIE_DOMAIN: "example.com" })).refresh.cookieDomain).toBe("example.com")
-        expect((await parse({ AUTH_COOKIE_DOMAIN: "Sub.Example.CO.uk" })).refresh.cookieDomain).toBe("sub.example.co.uk")
+        expect((await parse({ AUTH_COOKIE_DOMAIN: "example.com" })).cookie.domain).toBe("example.com")
+        expect((await parse({ AUTH_COOKIE_DOMAIN: "Sub.Example.CO.uk" })).cookie.domain).toBe("sub.example.co.uk")
     })
 
     it.each(["https://example.com", "example.com:443", "example.com/path", ".example.com", "localhost", "127.0.0.1", "exa mple.com", "-a.example.com"])(

package/templates/be/skeleton-lite/src/modules/integrations/passport/passport.config.ts

@@ -1,24 +1,46 @@
 import type { EnvSource } from "@modules/platform/config"
 import type { PassportOptions } from "./passport.options"
 
-/** Reads the passport configuration with no credential or localhost defaults; secrets read `<KEY>_FILE` first. */
+const ACCESS_TTL_SECONDS = 900
+const REFRESH_TTL_SECONDS = 2_592_000
+const BCRYPT_COST = 10
+const LOGIN_ATTEMPTS = 10
+const RESET_ATTEMPTS = 5
+const ATTEMPT_WINDOW_MS = 900_000
+
+/** The Google client, or null when the deployment declares none (the Google door is then unavailable). */
+const readGoogle = (env: EnvSource): PassportOptions["google"] =>
+    env.has("GOOGLE_CLIENT_ID")
+        ? {
+              clientId: env.string("GOOGLE_CLIENT_ID"),
+              clientSecret: env.secret("GOOGLE_CLIENT_SECRET"),
+              callbackUrl: env.url("GOOGLE_CALLBACK_URL"),
+          }
+        : null
+
+/** The key set: the signing key, and the previous public key while its access tokens are still valid (a rotation). */
+const readKeys = (env: EnvSource): PassportOptions["keys"] => {
+    const previous = env.optional("AUTH_JWT_PREVIOUS_PUBLIC_KEY")
+    return [
+        { privateKey: env.secret("AUTH_JWT_PRIVATE_KEY"), keyId: env.optional("AUTH_JWT_KEY_ID") },
+        ...(previous === undefined ? [] : [{ publicKey: previous, keyId: env.optional("AUTH_JWT_PREVIOUS_KEY_ID") }]),
+    ]
+}
+
+/** Reads the sign-in configuration with no credential or localhost defaults; secrets read `<KEY>_FILE` first. */
 export const parsePassportConfig = (env: EnvSource): PassportOptions => ({
-    google: {
-        clientId: env.string("GOOGLE_CLIENT_ID"),
-        clientSecret: env.secret("GOOGLE_CLIENT_SECRET"),
-        callbackUrl: env.url("GOOGLE_CALLBACK_URL"),
-    },
-    tokens: {
-        issuer: env.url("AUTH_JWT_ISSUER"),
-        audience: env.string("AUTH_JWT_AUDIENCE"),
-        privateKey: env.secret("AUTH_JWT_PRIVATE_KEY"),
-        keyId: env.string("AUTH_JWT_KEY_ID"),
-        accessTtlSeconds: env.int("AUTH_ACCESS_TTL_SECONDS", 900),
-    },
-    refresh: {
-        name: "refresh_token",
-        path: "/auth/refresh",
-        ttlSeconds: env.int("AUTH_REFRESH_TTL_SECONDS", 2_592_000),
-        cookieDomain: env.optionalDomain("AUTH_COOKIE_DOMAIN"),
+    issuer: env.url("AUTH_JWT_ISSUER"),
+    audience: env.optional("AUTH_JWT_AUDIENCE"),
+    keys: readKeys(env),
+    accessTtlSeconds: env.int("AUTH_ACCESS_TTL_SECONDS", ACCESS_TTL_SECONDS),
+    refreshTtlSeconds: env.int("AUTH_REFRESH_TTL_SECONDS", REFRESH_TTL_SECONDS),
+    bcryptCost: env.int("AUTH_BCRYPT_COST", BCRYPT_COST),
+    returnOrigin: new URL(env.url("AUTH_WEB_ORIGIN")).origin,
+    google: readGoogle(env),
+    cookie: { name: "refresh_token", domain: env.optionalDomain("AUTH_COOKIE_DOMAIN") },
+    budget: {
+        loginAttempts: env.int("AUTH_LOGIN_ATTEMPTS", LOGIN_ATTEMPTS),
+        resetAttempts: env.int("AUTH_RESET_ATTEMPTS", RESET_ATTEMPTS),
+        windowMs: env.duration("AUTH_ATTEMPT_WINDOW", ATTEMPT_WINDOW_MS),
     },
 })

package/templates/be/skeleton-lite/src/modules/integrations/passport/passport.decorators.ts

@@ -1,14 +1,20 @@
+import { AUTH_DOORS_SERVICE, AUTH_PASSWORDS, AUTH_SESSIONS, AUTH_SIGN_IN_BUDGET } from "@starci/auth/server"
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
 import type { PassportOptions, VerifyAccessToken } from "./passport.options"
-import type { FindPasswordAccount } from "./strategies/local.strategy"
 
 /** Token of the passport options. */
 export const PASSPORT_OPTIONS: unique symbol = Symbol("integrations.passport.options")
 /** Token of the verifier of the app's own access tokens. */
 export const OWN_TOKEN_VERIFIER: unique symbol = Symbol("integrations.passport.own-token-verifier")
-/** Token of the password-account lookup the identity domain provides. */
-export const PASSWORD_ACCOUNTS: unique symbol = Symbol("integrations.passport.password-accounts")
+/** Token of the session store the identity domain implements over the package's tables. */
+export const PASSPORT_SESSION_STORE: unique symbol = Symbol("integrations.passport.session-store")
+/** Token of the account directory the identity domain implements over the user table. */
+export const PASSPORT_ACCOUNTS: unique symbol = Symbol("integrations.passport.accounts")
+/** Token of the rate counter the identity domain implements over its attempts table. */
+export const PASSPORT_RATE_COUNTER: unique symbol = Symbol("integrations.passport.rate-counter")
+/** Token of the sign-in decisions (password and Google) the identity domain makes. */
+export const PASSPORT_AUTHENTICATOR: unique symbol = Symbol("integrations.passport.authenticator")
 
 /** Injects the passport options. Parameter type: PassportOptions. */
 export const InjectPassportOptions = (): TypedParameterDecorator<PassportOptions> => injector<PassportOptions>(PASSPORT_OPTIONS)
@@ -17,6 +23,12 @@ export const InjectPassportOptions = (): TypedParameterDecorator<PassportOptions
 export const InjectOwnTokenVerifier = (): TypedParameterDecorator<VerifyAccessToken> =>
     injector<VerifyAccessToken>(OWN_TOKEN_VERIFIER)
 
-/** Injects the password-account lookup. Parameter type: FindPasswordAccount. */
-export const InjectPasswordAccounts = (): TypedParameterDecorator<FindPasswordAccount> =>
-    injector<FindPasswordAccount>(PASSWORD_ACCOUNTS)
+/** Token of the sign-in doors. */
+export const PASSPORT_DOORS: typeof AUTH_DOORS_SERVICE = AUTH_DOORS_SERVICE
+/** Token of the rotating sessions. */
+export const PASSPORT_SESSIONS: typeof AUTH_SESSIONS = AUTH_SESSIONS
+/** Token of the password hasher. */
+export const PASSPORT_PASSWORDS: typeof AUTH_PASSWORDS = AUTH_PASSWORDS
+/** Token of the failures-only sign-in budget. */
+export const PASSPORT_SIGN_IN_BUDGET: typeof AUTH_SIGN_IN_BUDGET = AUTH_SIGN_IN_BUDGET
+

package/templates/be/skeleton-lite/src/modules/integrations/passport/passport.kit.spec.ts

@@ -0,0 +1,73 @@
+import { Test } from "@nestjs/testing"
+import { AUTH_ERROR_CODES, AUTH_ERROR_KINDS } from "@starci/auth/contracts"
+import { generateTestKeyPair } from "@starci/auth/testing"
+import { PASSPORT_ERROR_KINDS, PassportErrorCode } from "./errors/passport.error"
+import { passportKit } from "./passport.kit"
+import type { PassportOptions } from "./passport.options"
+
+const KIT: unique symbol = Symbol("passport.kit")
+
+const FAR_FUTURE = 32_503_680_000_000
+const LONG_AGO = 0
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({ providers: [{ provide: KIT, useValue: { passportKit } }] }).compile()
+    return moduleRef.get<{ passportKit: typeof passportKit }>(KIT).passportKit
+}
+
+const optionsFor = (keys: PassportOptions["keys"]): PassportOptions => ({
+    issuer: "https://api.example.test",
+    audience: undefined,
+    keys,
+    accessTtlSeconds: 60,
+    refreshTtlSeconds: 3600,
+    reuseGraceMs: undefined,
+    bcryptCost: 4,
+    returnOrigin: "https://app.example.test",
+    google: null,
+    cookie: { name: "refresh_token" },
+    budget: { loginAttempts: 10, resetAttempts: 5, windowMs: 900_000 },
+})
+
+describe("PassportErrorCode", () => {
+    it("names every PASSPORT wire code of @starci/auth with the same kind", () => {
+        const wire = Object.values(AUTH_ERROR_CODES).filter((code) => code.startsWith("PASSPORT_"))
+
+        expect(Object.values(PassportErrorCode).sort()).toEqual(wire.sort())
+        for (const code of Object.values(PassportErrorCode)) expect(PASSPORT_ERROR_KINDS[code]).toBe(AUTH_ERROR_KINDS[code])
+    })
+})
+
+describe("passportKit", () => {
+    it("verifies a token its own signer issued and builds the principal from it", async () => {
+        const create = await build()
+        const kit = create(optionsFor([{ privateKey: generateTestKeyPair().privateKey, keyId: "k1" }]))
+        const { token } = await kit.tokens.sign({ sub: "user-1", email: "a@example.test", sessionId: "s-1" }, new Date(FAR_FUTURE))
+
+        expect(await kit.verify(token)).toEqual({ kind: "ok", value: { id: "user-1", role: "authenticated", sessionId: "s-1", email: "a@example.test" } })
+        expect((await kit.tokens.jwks()).keys).toHaveLength(1)
+    })
+
+    it("refuses an expired token, a token of another key and a token that is no token", async () => {
+        const create = await build()
+        const kit = create(optionsFor([{ privateKey: generateTestKeyPair().privateKey }]))
+        const stranger = create(optionsFor([{ privateKey: generateTestKeyPair().privateKey }]))
+        const expired = await kit.tokens.sign({ sub: "user-1", sessionId: "s-1" }, new Date(LONG_AGO))
+        const foreign = await stranger.tokens.sign({ sub: "user-1", sessionId: "s-1" }, new Date(FAR_FUTURE))
+
+        for (const token of [expired.token, foreign.token, "not-a-token"]) {
+            expect(await kit.verify(token)).toEqual({ kind: "refused", code: PassportErrorCode.AccessTokenInvalid })
+        }
+    })
+
+    it("keeps verifying the token of a retired key while its public key stays in the set", async () => {
+        const create = await build()
+        const retired = generateTestKeyPair()
+        const before = create(optionsFor([{ privateKey: retired.privateKey, keyId: "old" }]))
+        const { token } = await before.tokens.sign({ sub: "user-1", sessionId: "s-1" }, new Date(FAR_FUTURE))
+        const after = create(optionsFor([{ privateKey: generateTestKeyPair().privateKey, keyId: "new" }, { publicKey: retired.publicKey, keyId: "old" }]))
+
+        expect((await after.verify(token)).kind).toBe("ok")
+        expect((await after.tokens.jwks()).keys.map((key) => key["kid"])).toEqual(["new", "old"])
+    })
+})