@starci/hfs 5.1.0 → 5.2.0

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

@@ -0,0 +1,44 @@
+// 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")
+const AFTER = new Date("2026-02-03T05:00:00.000Z")
+
+/** The kinds of account a sign-in spec needs. */
+export type AuthUserVariant = "live" | "banned" | "ban-ended" | "deleted" | "unconfirmed" | "addressless" | "passwordless" | "created"
+
+/** A row of auth.users as the sign-in reads it (the shape of AuthUserEntity). */
+export interface AuthUserRow {
+    id: string
+    aud: string | null
+    role: string | null
+    email: string | null
+    encryptedPassword: string | null
+    emailConfirmedAt: Date | null
+    lastSignInAt: Date | null
+    bannedUntil: Date | null
+    deletedAt: Date | null
+    isAnonymous: boolean
+    createdAt: Date | null
+    updatedAt: Date | null
+}
+
+/** Until when an account of this variant is banned, or null. */
+const bannedUntilOf = (variant: AuthUserVariant): Date | null => {
+    if (variant === "banned") return AFTER
+    return variant === "ban-ended" ? BEFORE : null
+}
+
+/** A confirmed, live password account of the given variant; \`created\` is the account the first Google sign-in makes (the first id the fake ids hand out). */
+export const authUserRow = (variant: AuthUserVariant = "live"): AuthUserRow => ({
+    id: variant === "created" ? "00000000-0000-4000-8000-000000000001" : "u-1",
+    aud: "authenticated",
+    role: "authenticated",
+    email: variant === "addressless" ? null : "a@example.test",
+    encryptedPassword: variant === "passwordless" || variant === "created" ? null : "hash",
+    emailConfirmedAt: variant === "unconfirmed" ? null : BEFORE,
+    lastSignInAt: null,
+    bannedUntil: bannedUntilOf(variant),
+    deletedAt: variant === "deleted" ? BEFORE : null,
+    isAnonymous: false,
+    createdAt: BEFORE,
+    updatedAt: BEFORE,
+})

package/templates/be/skeleton-lite/apps/api/src/app.module.ts

@@ -2,7 +2,7 @@ import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { APP_FILTER, APP_GUARD } from "@nestjs/core"
 import { AuthGuard, CredentialGuard } from "@modules/domain/identity"
-import { tokenKit } from "@modules/integrations/passport"
+import { passportKit } from "@modules/integrations/passport"
 import { ErrorsFilter } from "@modules/platform/errors"
 import { OriginGuard, RateLimitGuard } from "@modules/platform/http-security"
 import { platformModules } from "./compose/platform"
@@ -10,7 +10,7 @@ import { domainModules } from "./compose/domain"
 import { systemModules } from "./compose/system"
 import { apiModules } from "./compose/api"
 import { webhooksModules } from "./compose/webhooks"
-import { integrationProviders } from "./compose/integrations"
+import { integrationModules, integrationProviders } from "./compose/integrations"
 import type { ApiOptions } from "./api.options"
 
 @Module({})
@@ -18,18 +18,19 @@ import type { ApiOptions } from "./api.options"
 export class AppModule {
     /** Builds the module from options parsed once at boot; nothing here reads the environment. */
     static register(options: ApiOptions): DynamicModule {
-        const tokens = tokenKit(options.passport.tokens)
+        const passport = passportKit(options.passport)
         return {
             module: AppModule,
             imports: [
                 ...platformModules(options),
-                ...domainModules(tokens.verify),
+                ...integrationModules(options),
+                ...domainModules(passport.verify),
                 ...systemModules(),
                 ...apiModules(),
                 ...webhooksModules(),
             ],
             providers: [
-                ...integrationProviders(options, tokens.verify),
+                ...integrationProviders(options, passport.verify),
                 { provide: APP_FILTER, useClass: ErrorsFilter },
                 { provide: APP_GUARD, useClass: RateLimitGuard },
                 { provide: APP_GUARD, useClass: OriginGuard },

package/templates/be/skeleton-lite/apps/api/src/compose/api.ts

@@ -1,4 +1,5 @@
 import type { DynamicModule, Type } from "@nestjs/common"
+import { AuthHttpModule } from "@features/api/auth"
 
-/** The API transports of the app; `starci app add api` registers each generated door here. */
-export const apiModules = (): Array<Type<unknown> | DynamicModule> => []
+/** The API transports of the app: the sign-in doors; `starci app add api` registers each generated door here. */
+export const apiModules = (): Array<Type<unknown> | DynamicModule> => [AuthHttpModule.register({})]

package/templates/be/skeleton-lite/apps/api/src/compose/integrations.ts

@@ -1,12 +1,17 @@
-import type { Provider } from "@nestjs/common"
-import { OWN_TOKEN_VERIFIER, PASSPORT_OPTIONS } from "@modules/integrations/passport"
+import type { DynamicModule, Provider } from "@nestjs/common"
+import { OWN_TOKEN_VERIFIER, PASSPORT_OPTIONS, passportModule } from "@modules/integrations/passport"
 import type { VerifyAccessToken } from "@modules/integrations/passport"
-import { OBJECT_STORAGE, createObjectStorage } from "@modules/integrations/object-storage"
+import { ObjectStorageModule } from "@modules/integrations/object-storage"
 import type { ApiOptions } from "../api.options"
 
-/** The passport and object-storage integration ports bound once for this app. */
+/** The sign-in and object storage packages of the app, each registered once with the app's typed settings. */
+export const integrationModules = (options: ApiOptions): Array<DynamicModule> => [
+    passportModule(options.passport, { isGlobal: true }),
+    ObjectStorageModule.register({ ...options.objectStorage, isGlobal: true }),
+]
+
+/** The passport integration ports bound once for this app. */
 export const integrationProviders = (options: ApiOptions, verifyAccessToken: VerifyAccessToken): Array<Provider> => [
     { provide: PASSPORT_OPTIONS, useValue: options.passport },
     { provide: OWN_TOKEN_VERIFIER, useValue: verifyAccessToken },
-    { provide: OBJECT_STORAGE, useValue: createObjectStorage(options.objectStorage) },
 ]

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

@@ -0,0 +1,34 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the identity capability: the sign-in refusals travel under these wire codes, the same on both sides of the doors. */
+export enum IdentityErrorCode {
+    /** The door needs a signed-in caller and the request establishes none. */
+    Unauthenticated = "IDENTITY_UNAUTHENTICATED",
+    /** The refresh token is unknown, expired or already spent. */
+    RefreshInvalid = "IDENTITY_REFRESH_INVALID",
+    /** A rotated refresh token was presented again: the session was ended. */
+    RefreshReused = "IDENTITY_REFRESH_REUSED",
+    /** The account is deleted or banned. */
+    AccountDisabled = "IDENTITY_ACCOUNT_DISABLED",
+    /** Too many failed attempts for this address; try again later. */
+    TooManyAttempts = "IDENTITY_TOO_MANY_ATTEMPTS",
+    /** The pair of address and password is wrong (the same answer for an unknown address). */
+    PairRefused = "IDENTITY_INVALID_CREDENTIALS",
+    /** The mailbox was never confirmed. */
+    EmailNotConfirmed = "IDENTITY_EMAIL_NOT_CONFIRMED",
+}
+
+/** How each identity code travels. */
+export const IDENTITY_ERROR_KINDS: Record<IdentityErrorCode, ErrorKind> = {
+    [IdentityErrorCode.Unauthenticated]: "unauthenticated",
+    [IdentityErrorCode.RefreshInvalid]: "unauthenticated",
+    [IdentityErrorCode.RefreshReused]: "unauthenticated",
+    [IdentityErrorCode.AccountDisabled]: "forbidden",
+    [IdentityErrorCode.TooManyAttempts]: "rate-limited",
+    [IdentityErrorCode.PairRefused]: "unauthenticated",
+    [IdentityErrorCode.EmailNotConfirmed]: "forbidden",
+}
+
+/** The one error class of the identity capability. */
+export class IdentityError extends DomainError<IdentityErrorCode> {}

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")
 

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"])(