@starci/hfs 5.1.0 → 5.3.0

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, digestOf, isAcceptablePassword, 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"])
+    })
+})

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

@@ -0,0 +1,26 @@
+import { AuthPrincipalVerifier, AuthTokens } from "@starci/auth/server"
+import { ok, refused } from "@modules/platform/primitives"
+import { PassportErrorCode } from "./errors/passport.error"
+import type { PassportOptions, VerifyAccessToken } from "./passport.options"
+
+/** The signer of the app's own access tokens (it also serves the JWKS) and the verifier `domain/identity` turns into a principal. */
+export interface PassportKit {
+    /** Signs access tokens and publishes every key of the set. */
+    readonly tokens: AuthTokens
+    /** Verifies one bearer token against the app's own key set. */
+    readonly verify: VerifyAccessToken
+}
+
+/**
+ * Builds the kit from the typed options. The key set is imported on the first use, so a bad key fails the first verification
+ * instead of hiding behind a default; the package verifies against its own key set only, never a remote one.
+ */
+export const passportKit = (options: PassportOptions): PassportKit => {
+    const tokens = new AuthTokens(options)
+    const verifier = new AuthPrincipalVerifier(tokens)
+    const verify: VerifyAccessToken = async (token) => {
+        const verified = await verifier.verify(token)
+        return verified.kind === "ok" ? ok(verified.value) : refused(PassportErrorCode.AccessTokenInvalid)
+    }
+    return { tokens, verify }
+}

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

@@ -1,68 +1,39 @@
-import type { Secret } from "@modules/platform/config"
+import type { AuthOptions } from "@starci/auth/server"
 import type { Outcome } from "@modules/platform/primitives"
 import type { PassportErrorCode } from "./errors/passport.error"
 
+/**
+ * The typed settings of the sign-in, parsed once at boot by `passport.config.ts` and handed to @starci/auth: the signing keys
+ * (the first with a private key signs; every key verifies and is published as the JWKS), the access and refresh lifetimes, the
+ * Google client, the refresh cookie and the sign-in budget. The stores the package needs (sessions, accounts, rate counter)
+ * are not settings: `domain/identity` provides them.
+ */
+export type PassportOptions = Pick<
+    AuthOptions,
+    | "issuer"
+    | "audience"
+    | "keys"
+    | "accessTtlSeconds"
+    | "refreshTtlSeconds"
+    | "reuseGraceMs"
+    | "bcryptCost"
+    | "returnOrigin"
+    | "google"
+    | "cookie"
+    | "budget"
+>
+
 /** The claims admitted from one of the app's own access tokens after every cryptographic and semantic check. */
 export interface OwnPrincipal {
     /** The user identifier from the verified `sub` claim (a row of auth.users). */
     readonly id: string
     /** The verified email claim when the user has one. */
     readonly email?: string
+    /** The device session the token belongs to, when the token names one. */
+    readonly sessionId?: string
     /** The role every access token the app issues carries; any other role is refused. */
     readonly role: "authenticated"
 }
 
 /** Verifies one bearer token against the app's own key set and returns only claims that passed every check. */
 export type VerifyAccessToken = (token: string) => Promise<Outcome<OwnPrincipal, PassportErrorCode>>
-
-/** Issues one short-lived access token for a signed-in user. */
-export type IssueAccessToken = (user: { readonly id: string; readonly email?: string }) => Promise<string>
-
-/** Google OAuth 2.0 client configuration (authorization code with state and PKCE). */
-export interface GoogleOptions {
-    /** The OAuth client id. */
-    readonly clientId: string
-    /** The OAuth client secret. */
-    readonly clientSecret: Secret
-    /** The absolute callback URL of the back end's Google callback door. */
-    readonly callbackUrl: string
-}
-
-/** The app's own asymmetric access tokens and the JWKS that publishes their public key. */
-export interface TokenOptions {
-    /** The issuer (`iss`), the app's public API origin. */
-    readonly issuer: string
-    /** The audience (`aud`) every token names. */
-    readonly audience: string
-    /** The ES256 private key in PKCS#8 PEM; its public half is served as the JWKS. */
-    readonly privateKey: Secret
-    /** The key id (`kid`) of the signing key. */
-    readonly keyId: string
-    /** The access-token lifetime in seconds. */
-    readonly accessTtlSeconds: number
-}
-
-/** The rotating refresh token: an opaque value held only in an httpOnly, Secure, SameSite=Strict cookie. */
-export interface RefreshCookieOptions {
-    /** The cookie name. */
-    readonly name: string
-    /** The path the browser sends the cookie to: the refresh door only. */
-    readonly path: string
-    /** The refresh-token lifetime in seconds. */
-    readonly ttlSeconds: number
-    /**
-     * The bare registrable domain every cookie passport sets and clears carries as `Domain` (`example.com`, no scheme,
-     * no port), so a web app on another subdomain can forward the cookie to this API. Unset keeps the cookies host-only.
-     */
-    readonly cookieDomain?: string | undefined
-}
-
-/** The passport integration configuration parsed once at API boot. */
-export interface PassportOptions {
-    /** Google OAuth 2.0. */
-    readonly google: GoogleOptions
-    /** The app's own access tokens. */
-    readonly tokens: TokenOptions
-    /** The refresh cookie. */
-    readonly refresh: RefreshCookieOptions
-}

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

@@ -0,0 +1,31 @@
+import { AuthModule } from "@starci/auth/server"
+import type { AccountDirectory, RateCounter, SessionStore } from "@starci/auth/server"
+import type { DynamicModule } from "@nestjs/common"
+import { CLOCK } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { IDS } from "@modules/platform/ids"
+import type { Ids } from "@modules/platform/ids"
+import { PASSPORT_ACCOUNTS, PASSPORT_AUTHENTICATOR, PASSPORT_RATE_COUNTER, PASSPORT_SESSION_STORE } from "./passport.decorators"
+import type { PassportOptions } from "./passport.options"
+
+/** Whether the app root registers the sign-in package globally: the root decides, never the module. */
+export interface PassportRegistration {
+    /** True when every module of the app may inject what the package provides, without importing it. */
+    readonly isGlobal: boolean
+}
+
+/** The sign-in package as a Nest module: the typed options, the clock and ids of the app, and the stores the identity domain provides. */
+export const passportModule = (options: PassportOptions, registration: PassportRegistration): DynamicModule =>
+    AuthModule.registerAsync({
+        isGlobal: registration.isGlobal,
+        authenticator: PASSPORT_AUTHENTICATOR,
+        inject: [PASSPORT_SESSION_STORE, PASSPORT_ACCOUNTS, PASSPORT_RATE_COUNTER, CLOCK, IDS],
+        useFactory: (sessions: SessionStore, accounts: AccountDirectory, rate: RateCounter, clock: Clock, ids: Ids) => ({
+            ...options,
+            sessions,
+            accounts,
+            rate,
+            clock,
+            ids,
+        }),
+    })

package/templates/be/skeleton-lite/src/modules/platform/cqrs/index.ts

@@ -1,4 +1,4 @@
 export type { Principal, PublicExecuteParams } from "./cqrs.contracts"
-export { InjectQueryBus } from "./cqrs.decorators"
+export { InjectCommandBus, InjectQueryBus } from "./cqrs.decorators"
 export { ICQRSHandler } from "./cqrs.handler"
 export { CqrsModule } from "./cqrs.module"

package/templates/be/skeleton-lite/src/modules/platform/database/entities.ts

@@ -1,3 +1,4 @@
+import { identityEntities } from "@modules/domain/identity"
 import { httpSecurityEntities } from "@modules/platform/http-security"
 import type { EntityClass } from "./database.options"
 
@@ -7,4 +8,4 @@ import type { EntityClass } from "./database.options"
  * file, from the deep path `@modules/platform/database/entities`; DatabaseModule and the database barrel never do, since the
  * capability barrels import the database capability back.
  */
-export const PRIMARY_ENTITIES: ReadonlyArray<EntityClass> = [...httpSecurityEntities]
+export const PRIMARY_ENTITIES: ReadonlyArray<EntityClass> = [...httpSecurityEntities, ...identityEntities]

package/templates/be/skeleton-lite/src/modules/platform/database/index.ts

@@ -1,4 +1,5 @@
 export { DatabaseModule } from "./database.module"
+export { callDbFunction } from "./database.client"
 export { DATABASE_PROBE, InjectDatabaseProbe, InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"

package/templates/be/skeleton-lite/src/modules/platform/http-security/index.ts

@@ -6,7 +6,7 @@ export type { HttpSecurityOptions } from "./http-security.options"
 export { HTTP_SECURITY_MESSAGES } from "./messages/http-security.messages"
 export { OriginGuard, ServerToServer } from "./origin.guard"
 export { httpSecurityEntities } from "./persistence/entities"
-export { RateLimitGuard } from "./rate-limit.guard"
+export { RateLimit, RateLimitGuard, RateTier } from "./rate-limit.guard"
 export { applyHttpSecurity } from "./edge-security.service"
 export { ReadinessService } from "./readiness.service"
 export { InjectReadiness } from "./readiness.decorators"

package/templates/be/skeleton-lite/src/modules/platform/http-security/rate-limit.guard.spec.ts

@@ -129,6 +129,17 @@ describe("RateLimitGuard", () => {
         expect(entityManager.update).not.toHaveBeenCalled()
     })
 
+    it("counts with an increment the database evaluates, so concurrent hits never overwrite each other", async () => {
+        const { entityManager, counting } = liveWindow(2)
+        const { guard } = await build(entityManager)
+
+        await guard.canActivate(contextOf("127.0.0.1"))
+
+        const assignment: unknown = counting?.callsOf("set")[0]?.[0]
+        const increment: unknown = typeof assignment === "object" && assignment !== null && "hits" in assignment && typeof assignment.hits === "function" ? Reflect.apply(assignment.hits, undefined, []) : undefined
+        expect(increment).toBe("hits + 1")
+    })
+
     it("refuses a caller whose shared window is over the default limit", async () => {
         const { guard } = await build(liveWindow(3).entityManager)
 

package/templates/be/skeleton-lite/src/tests/fixtures/builders/api.builder.ts

@@ -27,9 +27,16 @@ export const buildWiringProof = (): WiringProof => ({
             schema: "public",
         },
         passport: {
-            google: { clientId: "fixture", clientSecret: new Secret("fixture-only"), callbackUrl: "https://api.fixture.example/auth/google/callback" },
-            tokens: { issuer: "https://api.fixture.example", audience: "fixture", privateKey: new Secret("fixture-only"), keyId: "k1", accessTtlSeconds: 900 },
-            refresh: { name: "refresh_token", path: "/auth/refresh", ttlSeconds: 2592000 },
+            issuer: "https://api.fixture.example",
+            audience: "fixture",
+            keys: [{ privateKey: new Secret("fixture-only"), keyId: "k1" }],
+            accessTtlSeconds: 900,
+            refreshTtlSeconds: 2592000,
+            bcryptCost: 4,
+            returnOrigin: "https://app.fixture.example",
+            google: null,
+            cookie: { name: "refresh_token" },
+            budget: { loginAttempts: 10, resetAttempts: 5, windowMs: 900000 },
         },
         objectStorage: {
             endpoint: "https://storage.fixture.example",
@@ -37,7 +44,18 @@ export const buildWiringProof = (): WiringProof => ({
             bucket: "fixture",
             accessKeyId: new Secret("fixture-only"),
             secretAccessKey: new Secret("fixture-only"),
-            presignTtlSeconds: 300,
+            defaultExpiresIn: 300,
+        },
+        mail: {
+            host: "127.0.0.1",
+            port: 2525,
+            security: "none",
+            from: { name: "Fixture", address: "no-reply@fixture.example" },
+            webOrigin: "https://app.fixture.example",
+            brandName: "Fixture",
+            defaultLanguage: "en",
+            confirmTtlSeconds: 86400,
+            resetTtlSeconds: 3600,
         },
     },
     overrides: [