@starci/hfs 4.3.0 → 4.4.1

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

@@ -8,35 +8,47 @@ import { ok, refused } from "@modules/platform/primitives"
 import { SupabaseErrorCode } from "@modules/integrations/supabase"
 import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
 import { AuthGuard } from "./auth.guard"
+import type { CredentialMetadata, CredentialPrincipal } from "./credential.contracts"
 import { IdentityErrorCode } from "./errors/identity.error"
 import type { PublicMetadata } from "./identity.contracts"
 import { PublicReason } from "./identity.contracts"
-import { ACCESS_TOKEN_VERIFIER } from "./identity.decorators"
+import { ACCESS_TOKEN_VERIFIER, CREDENTIAL_KEY, PUBLIC_KEY } from "./identity.decorators"
 
 const principal: Principal = { id: "user-1", role: "authenticated" }
+const API_KEY: CredentialPrincipal = { kind: "api-key", subject: "key-1", workspaceId: "ws-1" }
+const TOOL_TOKEN: CredentialPrincipal = { kind: "tool-token", subject: "tool-1", workspaceId: "ws-1" }
 
-const build = async (metadata: PublicMetadata | undefined, verify: VerifySupabaseAccessToken) => {
+const build = async (metadata: PublicMetadata | undefined, credential?: CredentialMetadata) => {
+    const verifier = mock<{ verify: VerifySupabaseAccessToken }>()
     const reflector = mock<Reflector>()
-    reflector.getAllAndOverride.mockReturnValue(metadata)
+    reflector.getAllAndOverride.mockImplementation((key: unknown) =>
+        key === CREDENTIAL_KEY ? credential : key === PUBLIC_KEY ? metadata : undefined,
+    )
     const moduleRef = await Test.createTestingModule({
         providers: [
             AuthGuard,
             { provide: Reflector, useValue: reflector },
-            { provide: ACCESS_TOKEN_VERIFIER, useValue: verify },
+            { provide: ACCESS_TOKEN_VERIFIER, useFactory: () => verifier.verify },
         ],
     }).compile()
-    return moduleRef.get(AuthGuard)
+    return { guard: moduleRef.get(AuthGuard), verify: verifier.verify }
 }
 
-const contextOf = (authorization: string | undefined) => {
+const contextOf = (
+    authorization: string | undefined,
+    credentialPrincipal?: CredentialPrincipal,
+    sessionPrincipal?: Principal,
+) => {
     const request = mock<Request>()
     request.headers = authorization === undefined ? {} : { authorization }
-    request.principal = undefined
+    request.principal = sessionPrincipal
+    request.credentialPrincipal = credentialPrincipal
     const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
     http.getRequest.mockReturnValue(request)
     const context = mock<ExecutionContext>()
     context.getHandler.mockReturnValue(() => undefined)
     context.getClass.mockReturnValue(class Door {})
+    context.getType.mockReturnValue("http")
     context.switchToHttp.mockReturnValue(http)
     return { context, request }
 }
@@ -45,8 +57,7 @@ const unauthenticated = expect.objectContaining({ code: IdentityErrorCode.Unauth
 
 describe("AuthGuard", () => {
     it("lets a public door through without reading a token", async () => {
-        const verify = jest.fn<ReturnType<VerifySupabaseAccessToken>, Parameters<VerifySupabaseAccessToken>>()
-        const guard = await build({ reason: PublicReason.Health }, verify)
+        const { guard, verify } = await build({ reason: PublicReason.Health })
         const { context } = contextOf("Bearer token")
 
         await expect(guard.canActivate(context)).resolves.toBe(true)
@@ -55,9 +66,8 @@ describe("AuthGuard", () => {
     })
 
     it("admits a door that is not public for a verified bearer token and records the principal on the request", async () => {
-        const verify = jest.fn<ReturnType<VerifySupabaseAccessToken>, Parameters<VerifySupabaseAccessToken>>()
+        const { guard, verify } = await build(undefined)
         verify.mockResolvedValue(ok(principal))
-        const guard = await build(undefined, verify)
         const { context, request } = contextOf("Bearer signed-token")
 
         await expect(guard.canActivate(context)).resolves.toBe(true)
@@ -65,11 +75,55 @@ describe("AuthGuard", () => {
         expect(verify).toHaveBeenCalledWith("signed-token")
         expect(request.principal).toEqual(principal)
     })
+})
+
+describe("AuthGuard credential doors", () => {
+    it("admits a credential door with the required principal without verifying a session token", async () => {
+        const { guard, verify } = await build(undefined, { kind: "api-key" })
+        verify.mockResolvedValue(ok(principal))
+        const { context, request } = contextOf("Bearer signed-token", API_KEY)
+
+        await expect(guard.canActivate(context)).resolves.toBe(true)
+
+        expect(verify).not.toHaveBeenCalled()
+        expect(request.credentialPrincipal).toEqual(API_KEY)
+        expect(request.principal).toBeUndefined()
+    })
+
+    it.each([
+        { label: "missing", credentialPrincipal: undefined },
+        { label: "of another kind", credentialPrincipal: TOOL_TOKEN },
+    ])(
+        "refuses a credential door when its credential principal is $label, even with a valid session",
+        async ({ credentialPrincipal }) => {
+            const { guard, verify } = await build(undefined, { kind: "api-key" })
+            verify.mockResolvedValue(ok(principal))
+            const { context } = contextOf("Bearer signed-token", credentialPrincipal, principal)
+
+            await expect(guard.canActivate(context)).rejects.toThrow(unauthenticated)
+
+            expect(verify).not.toHaveBeenCalled()
+        },
+    )
+
+    it.each([
+        { label: "missing", credentialPrincipal: undefined },
+        { label: "of another kind", credentialPrincipal: TOOL_TOKEN },
+    ])(
+        "refuses a credential door with public metadata when its credential principal is $label",
+        async ({ credentialPrincipal }) => {
+            const { guard, verify } = await build({ reason: PublicReason.Health }, { kind: "api-key" })
+            const { context } = contextOf("Bearer signed-token", credentialPrincipal, principal)
+
+            await expect(guard.canActivate(context)).rejects.toThrow(unauthenticated)
+
+            expect(verify).not.toHaveBeenCalled()
+        },
+    )
 
     it("refuses a door that is not public when the token fails verification", async () => {
-        const verify = jest.fn<ReturnType<VerifySupabaseAccessToken>, Parameters<VerifySupabaseAccessToken>>()
+        const { guard, verify } = await build(undefined)
         verify.mockResolvedValue(refused(SupabaseErrorCode.AccessTokenInvalid))
-        const guard = await build(undefined, verify)
         const { context, request } = contextOf("bearer forged-token")
 
         await expect(guard.canActivate(context)).rejects.toThrow(unauthenticated)
@@ -83,8 +137,7 @@ describe("AuthGuard", () => {
         ["a scheme without a token", "Bearer"],
         ["a token followed by more text", "Bearer one two"],
     ])("refuses a door that is not public with %s, without calling the verifier", async (_label, authorization) => {
-        const verify = jest.fn<ReturnType<VerifySupabaseAccessToken>, Parameters<VerifySupabaseAccessToken>>()
-        const guard = await build(undefined, verify)
+        const { guard, verify } = await build(undefined)
         const { context } = contextOf(authorization)
 
         await expect(guard.canActivate(context)).rejects.toThrow(unauthenticated)

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

@@ -7,9 +7,10 @@ import type { Principal } from "@modules/platform/cqrs"
 import { requestOf } from "@modules/platform/http-security"
 import { unwrapOutcome } from "@modules/platform/primitives"
 import { admit } from "./admission.policy"
+import type { CredentialMetadata } from "./credential.contracts"
 import { IdentityError } from "./errors/identity.error"
 import type { PublicMetadata } from "./identity.contracts"
-import { InjectAccessTokenVerifier, PUBLIC_KEY } from "./identity.decorators"
+import { CREDENTIAL_KEY, InjectAccessTokenVerifier, PUBLIC_KEY } from "./identity.decorators"
 
 const bearerToken = (authorization: string | undefined): string | undefined => {
     const [scheme, token, extra] = authorization?.split(" ") ?? []
@@ -17,21 +18,25 @@ const bearerToken = (authorization: string | undefined): string | undefined => {
 }
 
 @Injectable()
-/** The third app guard and default-deny gate: non-public doors require a verified Supabase principal. */
+/**
+ * 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.
+ */
 export class AuthGuard implements CanActivate {
     constructor(
         @InjectReflector() private readonly reflector: Reflector,
         @InjectAccessTokenVerifier() private readonly verifyAccessToken: VerifySupabaseAccessToken,
     ) {}
 
-    /** Verifies the bearer token when the door is not public, then applies the admission policy. */
+    /** Verifies session tokens only for doors without public or credential metadata, then applies the admission policy. */
     async canActivate(context: ExecutionContext): Promise<boolean> {
-        const metadata = this.reflector.getAllAndOverride<PublicMetadata | undefined>(PUBLIC_KEY, [
-            context.getHandler(),
-            context.getClass(),
-        ])
+        const targets = [context.getHandler(), context.getClass()]
+        const required = this.reflector.getAllAndOverride<CredentialMetadata | undefined>(CREDENTIAL_KEY, targets)
+        const metadata = this.reflector.getAllAndOverride<PublicMetadata | undefined>(PUBLIC_KEY, targets)
+        const credential =
+            required === undefined ? undefined : { required, principal: requestOf(context).credentialPrincipal }
         let principal: Principal | undefined
-        if (metadata === undefined) {
+        if (metadata === undefined && required === undefined) {
             const request = requestOf(context)
             const token = bearerToken(request.headers.authorization)
             if (token !== undefined) {
@@ -42,7 +47,7 @@ export class AuthGuard implements CanActivate {
                 }
             }
         }
-        unwrapOutcome(admit(metadata, principal), IdentityError)
+        unwrapOutcome(admit(metadata, principal, credential), IdentityError)
         return true
     }
 }

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

@@ -1,8 +1,11 @@
 import type { Principal } from "@modules/platform/cqrs"
+import type { CredentialPrincipal } from "./credential.contracts"
 
 declare module "express-serve-static-core" {
-    /** The request carries the principal established by the default-deny auth guard. */
+    /** The request carries the separate principals established by the identity guards. */
     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. */
         principal?: Principal
     }
@@ -12,8 +15,12 @@ declare module "express-serve-static-core" {
 export enum PublicReason {
     /** Liveness and readiness probes. */
     Health = "health",
+    /** The authentication protocol's anonymous handshake. */
+    AuthHandshake = "auth-handshake",
     /** A webhook whose signature is verified before its domain intake runs. */
     SignedWebhook = "signed-webhook",
+    /** A declared public catalog read. */
+    CatalogRead = "catalog-read",
 }
 
 /** The metadata `@Public` attaches to a door. */
@@ -23,4 +30,4 @@ export interface PublicMetadata {
 }
 
 /** What identity admission returns to the guard. */
-export type IdentityAdmission = Principal | PublicReason
+export type IdentityAdmission = Principal | CredentialPrincipal | PublicReason

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

@@ -5,6 +5,7 @@ import type { TypedParameterDecorator } from "@modules/platform/composition"
 import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
 import { 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 type { PublicMetadata } from "./identity.contracts"
 
@@ -18,9 +19,23 @@ export const InjectAccessTokenVerifier = (): TypedParameterDecorator<VerifySupab
 /** Metadata key of `@Public`. */
 export const PUBLIC_KEY = "domain.identity.public"
 
-/** Opens a door to anonymous callers, stating why; every other door needs a verified Supabase session. */
+/** 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)
 
+/** Metadata key of `@Credential`. */
+export const CREDENTIAL_KEY: unique symbol = Symbol("domain.identity.credential")
+
+/** Token of the identity-owned port that authenticates an API key, run token, tool token or link token. */
+export const CREDENTIAL_AUTHENTICATOR: unique symbol = Symbol("domain.identity.credential-authenticator")
+
+/** Injects the credential authenticator identity was registered with. Parameter type: CredentialAuthenticator. */
+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)
+
 /** The authenticated Supabase caller established by the default-deny guard. */
 export const CurrentPrincipal = createParamDecorator((_data: unknown, context: ExecutionContext): Principal => {
     const principal = requestOf(context).principal

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

@@ -1,15 +1,28 @@
 import { Module } from "@nestjs/common"
-import type { DynamicModule } from "@nestjs/common"
+import type { DynamicModule, Provider } from "@nestjs/common"
 import { AuthGuard } from "./auth.guard"
-import { ACCESS_TOKEN_VERIFIER } from "./identity.decorators"
+import { CredentialGuard } from "./credential.guard"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { ACCESS_TOKEN_VERIFIER, CREDENTIAL_AUTHENTICATOR } from "./identity.decorators"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./identity.module-definition"
 
+const refusingAuthenticator: Provider = {
+    provide: CREDENTIAL_AUTHENTICATOR,
+    useValue: {
+        authenticate: () => Promise.reject(new IdentityError({ code: IdentityErrorCode.Unauthenticated })),
+    },
+}
+
 @Module({})
-/** The identity capability: its default-deny guard admits only public doors or a verified Supabase principal. */
+/** The identity capability: the app registers its credential and default-deny guards after the throttler and origin guard. */
 export class IdentityModule extends ConfigurableModuleClass {
     /** Registers identity once per app with the verifier parsed at the composition root. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
         const base = super.register(options)
+        const authenticator: Provider =
+            options.credentialAuthenticator === undefined
+                ? refusingAuthenticator
+                : { provide: CREDENTIAL_AUTHENTICATOR, useClass: options.credentialAuthenticator }
         return {
             ...base,
             providers: [
@@ -18,9 +31,11 @@ export class IdentityModule extends ConfigurableModuleClass {
                     provide: ACCESS_TOKEN_VERIFIER,
                     useValue: options.verifyAccessToken,
                 },
+                authenticator,
+                CredentialGuard,
                 AuthGuard,
             ],
-            exports: [AuthGuard],
+            exports: [CredentialGuard, CREDENTIAL_AUTHENTICATOR, AuthGuard, ACCESS_TOKEN_VERIFIER],
         }
     }
 }

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

@@ -1,7 +1,11 @@
+import type { Type } from "@nestjs/common"
 import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import type { CredentialAuthenticator } from "./credential.contracts"
 
-/** The verified identity source used by the default-deny guard. */
+/** 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
 }

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

@@ -1,6 +1,7 @@
 export { AuthGuard } from "./auth.guard"
+export { CredentialGuard } from "./credential.guard"
 export { IDENTITY_ERROR_KINDS } from "./errors/identity.error"
 export { IDENTITY_MESSAGES } from "./messages/identity.messages"
 export { PublicReason } from "./identity.contracts"
-export { Public } from "./identity.decorators"
+export { ACCESS_TOKEN_VERIFIER, Public } from "./identity.decorators"
 export { IdentityModule } from "./identity.module"

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

@@ -5,14 +5,11 @@ import type { ErrorKind } from "@modules/platform/errors"
 export enum SupabaseErrorCode {
     /** The access token failed signature or required-claim verification. */
     AccessTokenInvalid = "SUPABASE_ACCESS_TOKEN_INVALID",
-    /** A privileged Auth or Storage operation could not reach Supabase. */
-    ProviderUnavailable = "SUPABASE_PROVIDER_UNAVAILABLE",
 }
 
 /** How each Supabase integration code travels. */
 export const SUPABASE_ERROR_KINDS: Record<SupabaseErrorCode, ErrorKind> = {
     [SupabaseErrorCode.AccessTokenInvalid]: "unauthenticated",
-    [SupabaseErrorCode.ProviderUnavailable]: "unavailable",
 }
 
 /** The one error class of the Supabase integration. */

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

@@ -1,12 +1,24 @@
+import { Test } from "@nestjs/testing"
 import { Secret } from "@modules/platform/config"
 import { createSupabaseAdminClient } from "./supabase.client"
+import type { SupabaseAdminClient } from "./supabase.client"
+import { SUPABASE_ADMIN_CLIENT } from "./supabase.decorators"
 
 describe("createSupabaseAdminClient", () => {
-    it("exposes only the Auth administration and Storage surfaces of a session-less service client", () => {
-        const client = createSupabaseAdminClient({
-            url: "http://127.0.0.1:54321",
-            serviceRoleKey: new Secret("service-role"),
-        })
+    it("exposes only the Auth administration and Storage surfaces of a session-less service client", async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [
+                {
+                    provide: SUPABASE_ADMIN_CLIENT,
+                    useFactory: () =>
+                        createSupabaseAdminClient({
+                            url: "http://127.0.0.1:54321",
+                            serviceRoleKey: new Secret("service-role"),
+                        }),
+                },
+            ],
+        }).compile()
+        const client = moduleRef.get<SupabaseAdminClient>(SUPABASE_ADMIN_CLIENT)
 
         expect(Object.keys(client).sort()).toEqual(["auth", "storage"])
         expect(typeof client.auth.createUser).toBe("function")

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

@@ -2,10 +2,12 @@ import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { TypeOrmModule, getDataSourceToken } from "@nestjs/typeorm"
 import type { DataSource } from "typeorm"
+import { DatabaseProbeService } from "./database-probe.service"
 import { DATABASE_OPTIONS } from "./database.port"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./database.module-definition"
+import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
 import { PRIMARY_CONNECTION } from "./primary.connection"
-import { PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
+import { DATABASE_PROBE, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 
 /** The token each declared connection provides its shared EntityManager under. */
 type EntityManagerToken = typeof PRIMARY_ENTITY_MANAGER
@@ -20,18 +22,23 @@ export class DatabaseModule extends ConfigurableModuleClass {
     /** Registers the capability once per app with the connections it opens. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
         const base = super.register(options)
-        const managers = options.connections.flatMap((connection) => {
+        const managers = options.connections.map((connection) => {
             const token = ENTITY_MANAGER_TOKENS.get(connection.name)
-            return token === undefined
-                ? []
-                : [
-                      {
-                          provide: token,
-                          inject: [getDataSourceToken(connection.name)],
-                          useFactory: (source: DataSource) => source.manager,
-                      },
-                  ]
+            if (token === undefined) {
+                throw new DatabaseError({
+                    code: DatabaseErrorCode.ConnectionUndeclared,
+                    params: { name: connection.name },
+                })
+            }
+            return {
+                provide: token,
+                inject: [getDataSourceToken(connection.name)],
+                useFactory: (source: DataSource) => source.manager,
+            }
         })
+        const probes = options.connections.some((connection) => connection.name === PRIMARY_CONNECTION)
+            ? [{ provide: DATABASE_PROBE, useClass: DatabaseProbeService }]
+            : []
         return {
             ...base,
             imports: [
@@ -47,8 +54,12 @@ export class DatabaseModule extends ConfigurableModuleClass {
                     }),
                 ),
             ],
-            providers: [...(base.providers ?? []), ...managers],
-            exports: [DATABASE_OPTIONS, ...managers.map((manager) => manager.provide)],
+            providers: [...(base.providers ?? []), ...managers, ...probes],
+            exports: [
+                DATABASE_OPTIONS,
+                ...probes.map((probe) => probe.provide),
+                ...managers.map((manager) => manager.provide),
+            ],
         }
     }
 }

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

@@ -1,6 +1,11 @@
+import { getDataSourceToken } from "@nestjs/typeorm"
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
 import type { DatabaseOptions } from "./database.options"
+import { PRIMARY_CONNECTION } from "./primary.connection"
+
+/** The primary pool's override token for infrastructure fixtures; TypeORM tokens stay owned by this capability. */
+export const PRIMARY_DATA_SOURCE = getDataSourceToken(PRIMARY_CONNECTION)
 
 /** Token of the options of the database capability. */
 export const DATABASE_OPTIONS: unique symbol = Symbol("platform.database.options")

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

@@ -0,0 +1,16 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the database capability. */
+export enum DatabaseErrorCode {
+    /** A configured connection has no declared EntityManager injection token. */
+    ConnectionUndeclared = "DATABASE_CONNECTION_UNDECLARED",
+}
+
+/** How each database code travels. */
+export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {
+    [DatabaseErrorCode.ConnectionUndeclared]: "internal",
+}
+
+/** The one error class of the database capability. */
+export class DatabaseError extends DomainError<DatabaseErrorCode> {}

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

@@ -1,4 +1,7 @@
 export { DatabaseModule } from "./database.module"
+export { DATABASE_PROBE, InjectDatabaseProbe } from "./primary.decorators"
+export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"
+export { PRIMARY_DATA_SOURCE } from "./database.port"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
 export { parsePrimaryDatabaseConfig } from "./primary.config"

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

@@ -1,7 +1,9 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
+import { APP_PIPE } from "@nestjs/core"
 import { WEBHOOK_SIGNATURE } from "./http-security.decorators"
 import { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } from "./http-security.module-definition"
+import { ReadinessService } from "./readiness.service"
 import { RequestValidationService } from "./request-validation.service"
 import { WebhookSignatureService } from "./webhook-signature.service"
 
@@ -15,11 +17,12 @@ export class HttpSecurityModule extends ConfigurableModuleClass {
             ...base,
             providers: [
                 ...(base.providers ?? []),
-                RequestValidationService,
+                { provide: APP_PIPE, useClass: RequestValidationService },
                 WebhookSignatureService,
+                ReadinessService,
                 { provide: WEBHOOK_SIGNATURE, useExisting: WebhookSignatureService },
             ],
-            exports: [MODULE_OPTIONS_TOKEN, RequestValidationService, WebhookSignatureService, WEBHOOK_SIGNATURE],
+            exports: [MODULE_OPTIONS_TOKEN, WebhookSignatureService, WEBHOOK_SIGNATURE, ReadinessService],
         }
     }
 }

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

@@ -6,4 +6,7 @@ export type { HttpSecurityOptions } from "./http-security.options"
 export { HTTP_SECURITY_MESSAGES } from "./messages/http-security.messages"
 export { OriginGuard } from "./origin.guard"
 export { RateLimitGuard } from "./rate-limit.guard"
-export { RequestValidationService } from "./request-validation.service"
+export { applyHttpSecurity } from "./edge-security.service"
+export { ReadinessService } from "./readiness.service"
+export { InjectReadiness } from "./readiness.decorators"
+export type { ReadinessReport } from "./readiness.contracts"

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

@@ -1,4 +1,4 @@
 export type { Locale, MessageBundle } from "./i18n.contracts"
-export { InjectMessageCatalog, InjectRequestLocale, MESSAGE_CATALOG } from "./i18n.decorators"
+export { InjectMessageCatalog, InjectRequestLocale, MESSAGE_CATALOG, REQUEST_LOCALE } from "./i18n.decorators"
 export { I18nModule } from "./i18n.module"
 export type { MessageCatalog, RequestLocale } from "./i18n.port"

package/templates/be/skeleton-lite/src/modules/platform/logging/logging.log-events.ts

@@ -0,0 +1,7 @@
+/** Log events of the process lifecycle: the entry points log these. */
+export enum LoggingLogEvent {
+    /** The HTTP listener is bound and the service answers requests. */
+    ServerStarted = "server.started",
+    /** The service failed before it could serve; the process exits non-zero. */
+    StartupFailed = "server.startup_failed",
+}

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

@@ -0,0 +1,29 @@
+import { Secret } from "@modules/platform/config"
+import { PRIMARY_DATA_SOURCE } from "@modules/platform/database"
+import { ACCESS_TOKEN_VERIFIER } from "@modules/domain/identity"
+import { SUPABASE_ACCESS_TOKEN_VERIFIER, SUPABASE_ADMIN_CLIENT } from "@modules/integrations/supabase"
+
+/** Compiles the real API root with public configuration and explicit infrastructure doubles. */
+export const buildWiringProof = () => ({
+    options: {
+        server: { port: 3000 },
+        httpSecurity: {
+            allowedOrigins: ["https://fixture.example"],
+            rateLimit: { windowMs: 60000, defaultLimit: 100, strictLimit: 10 },
+            webhooks: {},
+        },
+        database: {
+            name: "primary",
+            provider: "supabase",
+            url: new Secret("postgresql://app_be@127.0.0.1:5432/postgres"),
+            schema: "public",
+        },
+        supabase: { url: "https://fixture.supabase.co", serviceRoleKey: new Secret("fixture-only") },
+    },
+    overrides: [
+        { token: PRIMARY_DATA_SOURCE, value: { manager: {} } },
+        { token: SUPABASE_ADMIN_CLIENT, value: { auth: {}, storage: {} } },
+        { token: SUPABASE_ACCESS_TOKEN_VERIFIER, value: () => ({ ok: false }) },
+        { token: ACCESS_TOKEN_VERIFIER, value: () => ({ ok: false }) },
+    ],
+})

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

@@ -0,0 +1,16 @@
+import { getDataSourceToken } from "@nestjs/typeorm"
+import { Secret } from "@modules/platform/config"
+import { PRIMARY_CONNECTION } from "@modules/platform/database"
+
+/** Public fixture options and the database double for compiling the real CLI AppModule without network access. */
+export const buildWiringProof = () => ({
+    options: {
+        connections: [{
+            name: PRIMARY_CONNECTION,
+            provider: "supabase",
+            url: new Secret("postgresql://app_be@127.0.0.1:5432/postgres"),
+            schema: "public",
+        }],
+    },
+    overrides: [{ token: getDataSourceToken(PRIMARY_CONNECTION), value: { manager: {} } }],
+})

package/templates/be/table/api/feature.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { {{Name}}ApiOptions } from "./{{name}}.options"
+
+/** The configurable-module base of the {{name}} module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<{{Name}}ApiOptions>().setClassMethodName("register").build()

package/templates/be/table/api/feature.module.ts.tpl

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
 import { Create{{Singular}}Handler } from "./application/create-{{singular}}.handler"
 import { Get{{Singular}}Handler } from "./application/get-{{singular}}.handler"
+import { ConfigurableModuleClass } from "./{{name}}.module-definition"
 
 @Module({ providers: [Get{{Singular}}Handler, Create{{Singular}}Handler] })
 /** The {{name}} feature: the handlers of its application. */
-export class {{Name}}ApiModule {}
+export class {{Name}}ApiModule extends ConfigurableModuleClass {}

package/templates/be/table/api/feature.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The {{name}} module takes no options yet. */
+export type {{Name}}ApiOptions = Record<string, never>

package/templates/be/table/api/graphql.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { {{Name}}GraphqlOptions } from "./{{name}}-graphql.options"
+
+/** The configurable-module base of the {{name}}-graphql module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<{{Name}}GraphqlOptions>().setClassMethodName("register").build()

package/templates/be/table/api/graphql.module.ts.tpl

@@ -2,7 +2,8 @@ import { Module } from "@nestjs/common"
 import { {{Name}}ApiModule } from "../../{{name}}.module"
 import { Create{{Singular}}Resolver } from "./create-{{singular}}.resolver"
 import { Get{{Singular}}Resolver } from "./get-{{singular}}.resolver"
+import { ConfigurableModuleClass } from "./{{name}}-graphql.module-definition"
 
-@Module({ imports: [{{Name}}ApiModule], providers: [Get{{Singular}}Resolver, Create{{Singular}}Resolver] })
+@Module({ imports: [{{Name}}ApiModule.register({})], providers: [Get{{Singular}}Resolver, Create{{Singular}}Resolver] })
 /** The GraphQL transport of the {{name}} feature. */
-export class {{Name}}GraphqlModule {}
+export class {{Name}}GraphqlModule extends ConfigurableModuleClass {}

package/templates/be/table/api/graphql.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The {{name}}-graphql module takes no options yet. */
+export type {{Name}}GraphqlOptions = Record<string, never>