@starci/hfs 4.9.11 → 4.10.0

package/templates/be/skeleton-lite/src/modules/domain/identity/auth.guard.spec.ts

@@ -5,8 +5,8 @@ import type { Request } from "express"
 import { mock } from "@starci/jest-preset"
 import type { Principal } from "@modules/platform/cqrs"
 import { ok, refused } from "@modules/platform/primitives"
-import { SupabaseErrorCode } from "@modules/integrations/supabase"
-import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import { PassportErrorCode } from "@modules/integrations/passport"
+import type { VerifyAccessToken } from "@modules/integrations/passport"
 import { AuthGuard } from "./auth.guard"
 import type { CredentialMetadata, CredentialPrincipal } from "./credential.contracts"
 import { IdentityErrorCode } from "./errors/identity.error"
@@ -26,7 +26,7 @@ interface GuardRequest {
 }
 
 const build = async (metadata: PublicMetadata | undefined, credential?: CredentialMetadata) => {
-    const verifier = mock<{ verify: VerifySupabaseAccessToken }>()
+    const verifier = mock<{ verify: VerifyAccessToken }>()
     const reflector = mock<Reflector>()
     reflector.getAllAndOverride.mockImplementation((key: unknown) =>
         key === CREDENTIAL_KEY ? credential : key === PUBLIC_KEY ? metadata : undefined,
@@ -129,7 +129,7 @@ describe("AuthGuard credential doors", () => {
 
     it("refuses a door that is not public when the token fails verification", async () => {
         const { guard, verify } = await build(undefined)
-        verify.mockResolvedValue(refused(SupabaseErrorCode.AccessTokenInvalid))
+        verify.mockResolvedValue(refused(PassportErrorCode.AccessTokenInvalid))
         const { context, request } = contextOf("bearer forged-token")
 
         await expect(guard.canActivate(context)).rejects.toThrow(IdentityErrorCode.Unauthenticated)

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

@@ -1,7 +1,7 @@
 import { Injectable } from "@nestjs/common"
 import type { CanActivate, ExecutionContext } from "@nestjs/common"
 import type { Reflector } from "@nestjs/core"
-import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import type { VerifyAccessToken } from "@modules/integrations/passport"
 import { InjectReflector } from "@modules/platform/composition"
 import type { Principal } from "@modules/platform/cqrs"
 import { requestOf } from "@modules/platform/http-security"
@@ -20,12 +20,12 @@ const bearerToken = (authorization: string | undefined): string | undefined => {
 @Injectable()
 /**
  * The fourth app guard and default-deny gate: a credential door requires the matching principal from `CredentialGuard`,
- * a public door states its reason, and every other door requires a verified Supabase principal. It never calls another guard.
+ * a public door states its reason, and every other door requires a principal verified from the app's own access token. It never calls another guard.
  */
 export class AuthGuard implements CanActivate {
     constructor(
         @InjectReflector() private readonly reflector: Reflector,
-        @InjectAccessTokenVerifier() private readonly verifyAccessToken: VerifySupabaseAccessToken,
+        @InjectAccessTokenVerifier() private readonly verifyAccessToken: VerifyAccessToken,
     ) {}
 
     /** Verifies session tokens only for doors without public or credential metadata, then applies the admission policy. */

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

@@ -6,7 +6,7 @@ declare module "express-serve-static-core" {
     interface Request {
         /** The identity `CredentialGuard` authenticated on a door marked `@Credential`; never a session principal. */
         credentialPrincipal?: CredentialPrincipal
-        /** The authenticated Supabase caller, when the door is not public. */
+        /** The authenticated caller, when the door is not public. */
         principal?: Principal
     }
 }

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 { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import type { 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"
@@ -13,15 +13,15 @@ import type { PublicMetadata } from "./identity.contracts"
 /** 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")
 
-/** Injects the access-token verifier identity was registered with. Parameter type: VerifySupabaseAccessToken. */
-export const InjectAccessTokenVerifier = (): TypedParameterDecorator<VerifySupabaseAccessToken> =>
-    injector<VerifySupabaseAccessToken>(ACCESS_TOKEN_VERIFIER)
+/** Injects the access-token verifier identity was registered with. Parameter type: VerifyAccessToken. */
+export const InjectAccessTokenVerifier = (): TypedParameterDecorator<VerifyAccessToken> =>
+    injector<VerifyAccessToken>(ACCESS_TOKEN_VERIFIER)
 
 /** Metadata key of `@Public`. */
 export const PUBLIC_KEY = "domain.identity.public"
 
 /**
- * Opens a door to anonymous callers, stating why; every other door needs a credential or a verified Supabase session.
+ * Opens a door to anonymous callers, stating why; every other door needs a credential or a verified session.
  * A signed webhook proves its caller by its signature, so it owes no browser origin.
  */
 export const Public = (metadata: PublicMetadata): DoorDecorator =>
@@ -46,7 +46,7 @@ export const InjectCredentialAuthenticator = (): TypedParameterDecorator<Credent
 export const Credential = (metadata: CredentialMetadata): DoorDecorator =>
     applyDecorators(SetMetadata(CREDENTIAL_KEY, metadata), ServerToServer())
 
-/** The authenticated Supabase caller established by the default-deny guard. */
+/** The authenticated caller established by the default-deny guard. */
 export const CurrentPrincipal = createParamDecorator((_data: unknown, context: ExecutionContext): Principal => {
     const principal = requestOf(context).principal
     if (!principal) throw new IdentityError({ code: IdentityErrorCode.Unauthenticated })

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

@@ -1,11 +1,11 @@
 import type { Type } from "@nestjs/common"
-import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import type { VerifyAccessToken } from "@modules/integrations/passport"
 import type { CredentialAuthenticator } from "./credential.contracts"
 
 /** The identity capability's credential and session verification options. */
 export interface IdentityOptions {
     /** The app-owned authenticator of alternate credentials; a credential door fails closed while it is absent. */
     readonly credentialAuthenticator?: Type<CredentialAuthenticator>
-    /** Cryptographically verifies a Supabase access token before it can become a principal. */
-    readonly verifyAccessToken: VerifySupabaseAccessToken
+    /** Cryptographically verifies one of the app's own access tokens before it can become a principal. */
+    readonly verifyAccessToken: VerifyAccessToken
 }

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

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

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

@@ -0,0 +1,22 @@
+import { Secret } from "@modules/platform/config"
+import { createObjectStorage } from "./object-storage.client"
+
+const options = {
+    endpoint: "http://127.0.0.1:9000",
+    region: "us-east-1",
+    bucket: "app",
+    accessKeyId: new Secret("access"),
+    secretAccessKey: new Secret("secret"),
+    presignTtlSeconds: 300,
+}
+
+describe("createObjectStorage", () => {
+    it("presigns a path-style PUT of one key in the bucket, valid for the configured lifetime", async () => {
+        const storage = createObjectStorage(options, () => new Date("2026-10-29T00:00:00.000Z"))
+        const request = await storage.presignPut("users/u1/avatar.png", "image/png")
+
+        expect(new URL(request.url).pathname).toBe("/app/users/u1/avatar.png")
+        expect(new URL(request.url).searchParams.get("X-Amz-Expires")).toBe("300")
+        expect(request.expiresAt).toBe("2026-10-29T00:05:00.000Z")
+    })
+})

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

@@ -0,0 +1,25 @@
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3"
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner"
+import type { ObjectStorage, PresignedRequest, ObjectStorageOptions } from "./object-storage.options"
+
+/** The one S3 client of the app over S3-compatible storage (path-style, as MinIO serves it). */
+export const createObjectStorage = (options: ObjectStorageOptions, now: () => Date = () => new Date()): ObjectStorage => {
+    const client = new S3Client({
+        endpoint: options.endpoint,
+        region: options.region,
+        forcePathStyle: true,
+        credentials: { accessKeyId: options.accessKeyId.reveal(), secretAccessKey: options.secretAccessKey.reveal() },
+    })
+    const expiresAt = (): string => new Date(now().getTime() + options.presignTtlSeconds * 1000).toISOString()
+    const presign = async (command: PutObjectCommand | GetObjectCommand): Promise<PresignedRequest> => ({
+        url: await getSignedUrl(client, command, { expiresIn: options.presignTtlSeconds }),
+        expiresAt: expiresAt(),
+    })
+    return {
+        presignPut: (key, contentType) => presign(new PutObjectCommand({ Bucket: options.bucket, Key: key, ContentType: contentType })),
+        presignGet: (key) => presign(new GetObjectCommand({ Bucket: options.bucket, Key: key })),
+        remove: async (key) => {
+            await client.send(new DeleteObjectCommand({ Bucket: options.bucket, Key: key }))
+        },
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { EnvSource } from "@modules/platform/config"
+import type { ObjectStorageOptions } from "./object-storage.options"
+
+/** 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"),
+    region: env.string("STORAGE_REGION"),
+    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),
+})

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

@@ -0,0 +1,9 @@
+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")
+
+/** Injects the object storage port. Parameter type: ObjectStorage. */
+export const InjectObjectStorage = (): TypedParameterDecorator<ObjectStorage> => injector<ObjectStorage>(OBJECT_STORAGE)

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

@@ -0,0 +1,35 @@
+import type { Secret } from "@modules/platform/config"
+
+/** 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
+    /** 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

@@ -0,0 +1,22 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the passport integration. */
+export enum PassportErrorCode {
+    /** The access token failed signature or required-claim 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",
+}
+
+/** How each passport integration code travels. */
+export const PASSPORT_ERROR_KINDS: Record<PassportErrorCode, ErrorKind> = {
+    [PassportErrorCode.AccessTokenInvalid]: "unauthenticated",
+    [PassportErrorCode.CredentialsRefused]: "unauthenticated",
+    [PassportErrorCode.OAuthStateInvalid]: "unauthenticated",
+}
+
+/** The one error class of the passport integration. */
+export class PassportError extends DomainError<PassportErrorCode> {}

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

@@ -0,0 +1,12 @@
+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"

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

@@ -0,0 +1,23 @@
+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. */
+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),
+    },
+})

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

@@ -0,0 +1,29 @@
+import { createHash, randomBytes } from "node:crypto"
+import type { CookieOptions, Response } from "express"
+import type { RefreshCookieOptions } from "./passport.options"
+
+/** A fresh opaque refresh token (256 bits) and the sha256 the session store keeps instead of it. */
+export const newRefreshToken = (): { readonly token: string; readonly hash: string } => {
+    const token = randomBytes(32).toString("base64url")
+    return { token, hash: refreshTokenHash(token) }
+}
+
+/** The sha256 a refresh token is stored and looked up by; the token itself is never stored. */
+export const refreshTokenHash = (token: string): string => createHash("sha256").update(token).digest("hex")
+
+const attributes = (options: RefreshCookieOptions): CookieOptions => ({
+    httpOnly: true,
+    secure: true,
+    sameSite: "strict",
+    path: options.path,
+})
+
+/** Sets the rotated refresh token: httpOnly, Secure, SameSite=Strict and sent to the refresh door only. */
+export const setRefreshCookie = (response: Response, options: RefreshCookieOptions, token: string): void => {
+    response.cookie(options.name, token, { ...attributes(options), maxAge: options.ttlSeconds * 1000 })
+}
+
+/** Clears the refresh cookie on sign-out or on a detected reuse. */
+export const clearRefreshCookie = (response: Response, options: RefreshCookieOptions): void => {
+    response.clearCookie(options.name, attributes(options))
+}

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

@@ -0,0 +1,22 @@
+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")
+
+/** Injects the passport options. Parameter type: PassportOptions. */
+export const InjectPassportOptions = (): TypedParameterDecorator<PassportOptions> => injector<PassportOptions>(PASSPORT_OPTIONS)
+
+/** Injects the own-token verifier. Parameter type: VerifyAccessToken. */
+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)

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

@@ -0,0 +1,63 @@
+import type { Secret } from "@modules/platform/config"
+import type { Outcome } from "@modules/platform/primitives"
+import type { PassportErrorCode } from "./errors/passport.error"
+
+/** 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 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 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.password.ts

@@ -0,0 +1,11 @@
+import { compare, hash } from "bcryptjs"
+
+/** The bcrypt cost of a new password hash; existing `$2a$`/`$2b$` hashes (auth.users.encrypted_password) verify at their own cost. */
+const COST = 12
+
+/** Hashes a new password with bcrypt. */
+export const hashPassword = (password: string): Promise<string> => hash(password, COST)
+
+/** True when `password` matches the stored bcrypt hash; a missing hash never matches. */
+export const verifyPassword = async (password: string, stored: string | null): Promise<boolean> =>
+    stored === null ? false : compare(password, stored)

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

@@ -0,0 +1,32 @@
+import { exportPKCS8, generateKeyPair } from "jose"
+import { Secret } from "@modules/platform/config"
+import { createTokenKit } from "./passport.tokens"
+
+const options = async () => {
+    const { privateKey } = await generateKeyPair("ES256", { extractable: true })
+    return {
+        issuer: "https://api.example.test",
+        audience: "app",
+        privateKey: new Secret(await exportPKCS8(privateKey)),
+        keyId: "k1",
+        accessTtlSeconds: 60,
+    }
+}
+
+describe("createTokenKit", () => {
+    it("verifies its own token against its own key set and publishes only the public key", async () => {
+        const kit = await createTokenKit(await options())
+        const verified = await kit.verify(await kit.issue({ id: "user-1", email: "a@example.test" }))
+
+        expect(verified).toEqual({ kind: "ok", value: { id: "user-1", role: "authenticated", email: "a@example.test" } })
+        expect(kit.jwks.keys).toHaveLength(1)
+        expect(kit.jwks.keys[0]).not.toHaveProperty("d")
+    })
+
+    it("refuses a token another key signed", async () => {
+        const kit = await createTokenKit(await options())
+        const other = await createTokenKit(await options())
+
+        expect((await kit.verify(await other.issue({ id: "user-1" }))).kind).toBe("refused")
+    })
+})

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

@@ -0,0 +1,69 @@
+import { createLocalJWKSet, exportJWK, importPKCS8, jwtVerify, SignJWT } from "jose"
+import type { JSONWebKeySet } from "jose"
+import { ok, refused } from "@modules/platform/primitives"
+import { PassportErrorCode } from "./errors/passport.error"
+import type { IssueAccessToken, OwnPrincipal, TokenOptions, VerifyAccessToken } from "./passport.options"
+
+const ALGORITHM = "ES256"
+const ROLE = "authenticated"
+
+/** The app's own token kit: the signer, the verifier over its own key set, and the public JWKS the API serves. */
+export interface TokenKit {
+    /** Signs one access token. */
+    readonly issue: IssueAccessToken
+    /** Verifies one access token against the app's own keys. */
+    readonly verify: VerifyAccessToken
+    /** The public key set served at `/.well-known/jwks.json`. */
+    readonly jwks: JSONWebKeySet
+}
+
+/** Builds the token kit from the ES256 private key; the verifier checks the app's own key set, never a remote one. */
+export const createTokenKit = async (options: TokenOptions): Promise<TokenKit> => {
+    const privateKey = await importPKCS8(options.privateKey.reveal(), ALGORITHM, { extractable: true })
+    const { d: _private, ...publicJwk } = await exportJWK(privateKey)
+    const jwks: JSONWebKeySet = { keys: [{ ...publicJwk, kid: options.keyId, alg: ALGORITHM, use: "sig" }] }
+    const keys = createLocalJWKSet(jwks)
+    const issue: IssueAccessToken = (user) =>
+        new SignJWT({ role: ROLE, ...(user.email === undefined ? {} : { email: user.email }) })
+            .setProtectedHeader({ alg: ALGORITHM, kid: options.keyId })
+            .setSubject(user.id)
+            .setIssuer(options.issuer)
+            .setAudience(options.audience)
+            .setIssuedAt()
+            .setExpirationTime(`${String(options.accessTtlSeconds)}s`)
+            .sign(privateKey)
+    const verify: VerifyAccessToken = async (token) => {
+        try {
+            const { payload } = await jwtVerify(token, keys, {
+                algorithms: ["ES256"],
+                audience: options.audience,
+                issuer: options.issuer,
+            })
+            if (typeof payload.sub !== "string" || typeof payload.exp !== "number" || payload.role !== ROLE) {
+                return refused(PassportErrorCode.AccessTokenInvalid)
+            }
+            const principal: OwnPrincipal = {
+                id: payload.sub,
+                role: ROLE,
+                ...(typeof payload.email === "string" ? { email: payload.email } : {}),
+            }
+            return ok(principal)
+        } catch (cause) {
+            return refused(PassportErrorCode.AccessTokenInvalid, { cause: String(cause) })
+        }
+    }
+    return { issue, verify, jwks }
+}
+
+/**
+ * The token kit of a composition root that registers synchronously: each call awaits the one key import started here, so a
+ * bad key fails the first verification instead of hiding behind a default.
+ */
+export const tokenKit = (options: TokenOptions): { readonly issue: IssueAccessToken; readonly verify: VerifyAccessToken; readonly jwks: () => Promise<JSONWebKeySet> } => {
+    const kit = createTokenKit(options)
+    return {
+        issue: async (user) => (await kit).issue(user),
+        verify: async (token) => (await kit).verify(token),
+        jwks: async () => (await kit).jwks,
+    }
+}

package/templates/be/skeleton-lite/src/modules/integrations/passport/strategies/google.strategy.ts

@@ -0,0 +1,37 @@
+import { Injectable } from "@nestjs/common"
+import { PassportStrategy } from "@nestjs/passport"
+import { Strategy } from "passport-google-oauth20"
+import type { Profile } from "passport-google-oauth20"
+import { InjectPassportOptions } from "../passport.decorators"
+import type { PassportOptions } from "../passport.options"
+import { CookieStateStore } from "./oauth-state.store"
+
+/** The Google identity a callback proves: the provider subject and the verified email when Google states one. */
+export interface GoogleIdentity {
+    /** Google's stable subject id (auth.identities.provider_id). */
+    readonly providerId: string
+    /** The verified email, when present. */
+    readonly email?: string
+}
+
+@Injectable()
+/** Google OAuth 2.0 (authorization code with state and PKCE): it proves the Google identity and never signs the user in itself. */
+export class GoogleStrategy extends PassportStrategy(Strategy, "google") {
+    constructor(@InjectPassportOptions() options: PassportOptions) {
+        super({
+            clientID: options.google.clientId,
+            clientSecret: options.google.clientSecret.reveal(),
+            callbackURL: options.google.callbackUrl,
+            scope: ["openid", "email"],
+            pkce: true,
+            state: true,
+            store: new CookieStateStore(new URL(options.google.callbackUrl).pathname),
+        })
+    }
+
+    /** The identity of the callback; the identity domain links it to a user and issues the session. */
+    validate(_accessToken: string, _refreshToken: string, profile: Profile): GoogleIdentity {
+        const email = profile.emails?.find((entry) => entry.verified)?.value
+        return { providerId: profile.id, ...(email === undefined ? {} : { email }) }
+    }
+}

package/templates/be/skeleton-lite/src/modules/integrations/passport/strategies/local.strategy.ts

@@ -0,0 +1,36 @@
+import { Injectable } from "@nestjs/common"
+import { PassportStrategy } from "@nestjs/passport"
+import { Strategy } from "passport-local"
+import { PassportError, PassportErrorCode } from "../errors/passport.error"
+import { InjectPasswordAccounts } from "../passport.decorators"
+import { verifyPassword } from "../passport.password"
+
+/** The account a password sign-in proves. */
+export interface PasswordAccount {
+    /** The user id (auth.users.id). */
+    readonly id: string
+    /** The account email. */
+    readonly email: string
+    /** The stored bcrypt hash (auth.users.encrypted_password), null for an account without a password. */
+    readonly passwordHash: string | null
+}
+
+/** The lookup the identity domain provides: the account of one email, or undefined. */
+export type FindPasswordAccount = (email: string) => Promise<PasswordAccount | undefined>
+
+@Injectable()
+/** Email and password sign-in: bcrypt against the stored hash; a miss and a wrong password fail alike. */
+export class LocalStrategy extends PassportStrategy(Strategy, "local") {
+    constructor(@InjectPasswordAccounts() private readonly findAccount: FindPasswordAccount) {
+        super({ usernameField: "email", passwordField: "password" })
+    }
+
+    /** The proven account; every refusal is the same error so an email's existence never leaks. */
+    async validate(email: string, password: string): Promise<{ readonly id: string; readonly email: string }> {
+        const account = await this.findAccount(email.trim().toLowerCase())
+        if (!(await verifyPassword(password, account?.passwordHash ?? null)) || account === undefined) {
+            throw new PassportError({ code: PassportErrorCode.CredentialsRefused })
+        }
+        return { id: account.id, email: account.email }
+    }
+}