@starci/hfs 4.9.9 → 4.10.0

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

@@ -1,4 +1,5 @@
-import type { SupabaseOptions } from "@modules/integrations/supabase"
+import type { PassportOptions } from "@modules/integrations/passport"
+import type { ObjectStorageOptions } from "@modules/integrations/object-storage"
 import type { ServerOptions } from "@modules/platform/config"
 import type { DatabaseConnectionOptions } from "@modules/platform/database"
 import type { HttpSecurityOptions } from "@modules/platform/http-security"
@@ -9,8 +10,10 @@ export interface ApiOptions {
     readonly server: ServerOptions
     /** The origin allowlist and rate limits. */
     readonly httpSecurity: HttpSecurityOptions
-    /** The least-privilege PostgreSQL connection to the Supabase project. */
+    /** The least-privilege PostgreSQL connection to the app's own database. */
     readonly database: DatabaseConnectionOptions
-    /** Supabase Auth, Storage and token-verification configuration. */
-    readonly supabase: SupabaseOptions
+    /** Google OAuth, the app's own access tokens and the refresh cookie. */
+    readonly passport: PassportOptions
+    /** S3-compatible object storage. */
+    readonly objectStorage: ObjectStorageOptions
 }

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 { createSupabaseAccessTokenVerifier } from "@modules/integrations/supabase"
+import { tokenKit } from "@modules/integrations/passport"
 import { ErrorsFilter } from "@modules/platform/errors"
 import { OriginGuard, RateLimitGuard } from "@modules/platform/http-security"
 import { platformModules } from "./compose/platform"
@@ -18,18 +18,18 @@ 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 verifyAccessToken = createSupabaseAccessTokenVerifier(options.supabase)
+        const tokens = tokenKit(options.passport.tokens)
         return {
             module: AppModule,
             imports: [
                 ...platformModules(options),
-                ...domainModules(verifyAccessToken),
+                ...domainModules(tokens.verify),
                 ...systemModules(),
                 ...apiModules(),
                 ...webhooksModules(),
             ],
             providers: [
-                ...integrationProviders(options.supabase, verifyAccessToken),
+                ...integrationProviders(options, tokens.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/domain.ts

@@ -1,10 +1,10 @@
 import type { DynamicModule, Type } from "@nestjs/common"
 import { IdentityModule } from "@modules/domain/identity"
 import { LivenessModule } from "@modules/domain/liveness"
-import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import type { VerifyAccessToken } from "@modules/integrations/passport"
 
-/** The domain capabilities of the API, with the app's verified Supabase identity adapter. */
-export const domainModules = (verifyAccessToken: VerifySupabaseAccessToken): Array<Type<unknown> | DynamicModule> => [
+/** The domain capabilities of the API, with the verifier of the app's own access tokens. */
+export const domainModules = (verifyAccessToken: VerifyAccessToken): Array<Type<unknown> | DynamicModule> => [
     IdentityModule.register({ isGlobal: true, verifyAccessToken }),
     LivenessModule.register({ isGlobal: true }),
 ]

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

@@ -1,16 +1,12 @@
 import type { Provider } from "@nestjs/common"
-import {
-    SUPABASE_ACCESS_TOKEN_VERIFIER,
-    SUPABASE_ADMIN_CLIENT,
-    createSupabaseAdminClient,
-} from "@modules/integrations/supabase"
-import type { SupabaseOptions, VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import { OWN_TOKEN_VERIFIER, PASSPORT_OPTIONS } from "@modules/integrations/passport"
+import type { VerifyAccessToken } from "@modules/integrations/passport"
+import { OBJECT_STORAGE, createObjectStorage } from "@modules/integrations/object-storage"
+import type { ApiOptions } from "../api.options"
 
-/** The Supabase integration ports bound once for this app. */
-export const integrationProviders = (
-    options: SupabaseOptions,
-    verifyAccessToken: VerifySupabaseAccessToken,
-): Array<Provider> => [
-    { provide: SUPABASE_ADMIN_CLIENT, useValue: createSupabaseAdminClient(options) },
-    { provide: SUPABASE_ACCESS_TOKEN_VERIFIER, useValue: verifyAccessToken },
+/** The passport and object-storage 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/apps/api/src/compose/platform.ts

@@ -1,10 +1,11 @@
 import type { DynamicModule } from "@nestjs/common"
 import { IDENTITY_ERROR_KINDS, IDENTITY_MESSAGES } from "@modules/domain/identity"
-import { SUPABASE_ERROR_KINDS } from "@modules/integrations/supabase"
+import { PASSPORT_ERROR_KINDS } from "@modules/integrations/passport"
 import { ClockModule } from "@modules/platform/clock"
 import { CONFIG_ERROR_KINDS } from "@modules/platform/config"
 import { CqrsModule } from "@modules/platform/cqrs"
 import { DATABASE_ERROR_KINDS, DatabaseModule } from "@modules/platform/database"
+import { PRIMARY_ENTITIES } from "@modules/platform/database/entities"
 import { ERRORS_MESSAGES, ErrorsModule } from "@modules/platform/errors"
 import { HTTP_SECURITY_ERROR_KINDS, HTTP_SECURITY_MESSAGES, HttpSecurityModule } from "@modules/platform/http-security"
 import { I18nModule } from "@modules/platform/i18n"
@@ -37,7 +38,7 @@ export const platformModules = (options: ApiOptions): Array<DynamicModule> => [
             DATABASE_ERROR_KINDS,
             HTTP_SECURITY_ERROR_KINDS,
             IDENTITY_ERROR_KINDS,
-            SUPABASE_ERROR_KINDS,
+            PASSPORT_ERROR_KINDS,
         ],
     }),
     CqrsModule.register({ isGlobal: true }),
@@ -48,5 +49,6 @@ export const platformModules = (options: ApiOptions): Array<DynamicModule> => [
     DatabaseModule.register({
         isGlobal: true,
         connections: [options.database],
+        entities: PRIMARY_ENTITIES,
     }),
 ]

package/templates/be/skeleton-lite/apps/cli/src/cli.env.ts

@@ -5,8 +5,8 @@ import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
 export interface CliEnv {
     /** The logical connection name declared in `hfs.json`. */
     readonly name: string
-    /** The Supabase PostgreSQL provider. */
-    readonly provider: "supabase"
+    /** The PostgreSQL provider. */
+    readonly provider: "postgres"
     /** The least-privilege database connection URL, read through the secret source. */
     readonly url: Secret
     /** The isolated PostgreSQL schema. */

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

@@ -1,16 +1,17 @@
 import type { DynamicModule } from "@nestjs/common"
 import { ClockModule } from "@modules/platform/clock"
 import { DatabaseModule } from "@modules/platform/database"
+import { PRIMARY_ENTITIES } from "@modules/platform/database/entities"
 import { IdsModule } from "@modules/platform/ids"
 import { HTTP_ERROR_KINDS, HTTP_MESSAGES, HttpModule } from "@modules/platform/http"
 import { LoggingModule } from "@modules/platform/logging"
 import type { CliAppOptions } from "../cli.options"
 
-/** The shared clock, logger and least-privilege connection used by Supabase CLI commands. */
+/** The shared clock, logger and least-privilege connection used by the operator commands. */
 export const platformModules = (options: CliAppOptions): Array<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
     IdsModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
     HttpModule.register({ isGlobal: true }),
-    DatabaseModule.register({ isGlobal: true, connections: options.connections }),
+    DatabaseModule.register({ isGlobal: true, connections: options.connections, entities: PRIMARY_ENTITIES }),
 ]

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

@@ -1,26 +1,33 @@
-import { SetMetadata, createParamDecorator } from "@nestjs/common"
+import { SetMetadata, applyDecorators, createParamDecorator } from "@nestjs/common"
 import type { ExecutionContext } from "@nestjs/common"
 import { injector } from "@modules/platform/composition"
-import type { TypedParameterDecorator } from "@modules/platform/composition"
-import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
-import { requestOf } from "@modules/platform/http-security"
+import type { DoorDecorator, TypedParameterDecorator } from "@modules/platform/composition"
+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"
 import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { PublicReason } from "./identity.contracts"
 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. */
-export const Public = (metadata: PublicMetadata): ReturnType<typeof SetMetadata> => SetMetadata(PUBLIC_KEY, metadata)
+/**
+ * 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 =>
+    metadata.reason === PublicReason.SignedWebhook
+        ? applyDecorators(SetMetadata(PUBLIC_KEY, metadata), ServerToServer())
+        : applyDecorators(SetMetadata(PUBLIC_KEY, metadata))
 
 /** Metadata key of `@Credential`. */
 export const CREDENTIAL_KEY: unique symbol = Symbol("domain.identity.credential")
@@ -32,11 +39,14 @@ export const CREDENTIAL_AUTHENTICATOR: unique symbol = Symbol("domain.identity.c
 export const InjectCredentialAuthenticator = (): TypedParameterDecorator<CredentialAuthenticator> =>
     injector<CredentialAuthenticator>(CREDENTIAL_AUTHENTICATOR)
 
-/** Marks a door authenticated by its own credential; `CredentialGuard` authenticates it and `AuthGuard` admits it. */
-export const Credential = (metadata: CredentialMetadata): ReturnType<typeof SetMetadata> =>
-    SetMetadata(CREDENTIAL_KEY, metadata)
+/**
+ * Marks a door authenticated by its own credential; `CredentialGuard` authenticates it and `AuthGuard` admits it. The
+ * credential travels in a header no browser attaches by itself, so the door owes no browser origin.
+ */
+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)