@starci/hfs 4.2.17 → 4.4.0

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

@@ -1,34 +1,20 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { APP_FILTER, APP_GUARD } from "@nestjs/core"
-import { SystemHealthHttpModule } from "@features/api/system-health"
-import { AuthGuard, IDENTITY_ERROR_KINDS, IDENTITY_MESSAGES, IdentityModule } from "@modules/domain/identity"
-import {
-    SUPABASE_ACCESS_TOKEN_VERIFIER,
-    SUPABASE_ADMIN_CLIENT,
-    SUPABASE_ERROR_KINDS,
-    createSupabaseAccessTokenVerifier,
-    createSupabaseAdminClient,
-} from "@modules/integrations/supabase"
-import { LivenessModule } from "@modules/domain/liveness"
-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 { ERRORS_MESSAGES, ErrorsFilter, ErrorsModule } from "@modules/platform/errors"
-import {
-    HTTP_SECURITY_ERROR_KINDS,
-    HTTP_SECURITY_MESSAGES,
-    HttpSecurityModule,
-    OriginGuard,
-    RateLimitGuard,
-} from "@modules/platform/http-security"
-import { I18nModule } from "@modules/platform/i18n"
-import { LoggingModule } from "@modules/platform/logging"
+import { AuthGuard, CredentialGuard } from "@modules/domain/identity"
+import { createSupabaseAccessTokenVerifier } from "@modules/integrations/supabase"
+import { ErrorsFilter } from "@modules/platform/errors"
+import { OriginGuard, RateLimitGuard } from "@modules/platform/http-security"
+import { platformModules } from "./compose/platform"
+import { domainModules } from "./compose/domain"
+import { systemModules } from "./compose/system"
+import { apiModules } from "./compose/api"
+import { webhooksModules } from "./compose/webhooks"
+import { integrationProviders } from "./compose/integrations"
 import type { ApiOptions } from "./api.options"
 
 @Module({})
-/** Composition root of the API: every capability is registered once and the three guards run in a fixed order. */
+/** Composition root of the API: it spreads the composition groups of `compose/`, and the four guards run in a fixed order. */
 export class AppModule {
     /** Builds the module from options parsed once at boot; nothing here reads the environment. */
     static register(options: ApiOptions): DynamicModule {
@@ -36,44 +22,18 @@ export class AppModule {
         return {
             module: AppModule,
             imports: [
-                ClockModule.register({ isGlobal: true }),
-                LoggingModule.register({ isGlobal: true }),
-                I18nModule.register({
-                    isGlobal: true,
-                    bundles: [ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
-                }),
-                ErrorsModule.register({
-                    isGlobal: true,
-                    kinds: [
-                        CONFIG_ERROR_KINDS,
-                        DATABASE_ERROR_KINDS,
-                        HTTP_SECURITY_ERROR_KINDS,
-                        IDENTITY_ERROR_KINDS,
-                        SUPABASE_ERROR_KINDS,
-                    ],
-                }),
-                CqrsModule.register({ isGlobal: true }),
-                HttpSecurityModule.register({
-                    isGlobal: true,
-                    ...options.httpSecurity,
-                }),
-                DatabaseModule.register({
-                    isGlobal: true,
-                    connections: [options.database],
-                }),
-                IdentityModule.register({ isGlobal: true, verifyAccessToken }),
-                LivenessModule.register({ isGlobal: true }),
-                SystemHealthHttpModule,
+                ...platformModules(options),
+                ...domainModules(verifyAccessToken),
+                ...systemModules(),
+                ...apiModules(),
+                ...webhooksModules(),
             ],
             providers: [
-                {
-                    provide: SUPABASE_ADMIN_CLIENT,
-                    useValue: createSupabaseAdminClient(options.supabase),
-                },
-                { provide: SUPABASE_ACCESS_TOKEN_VERIFIER, useValue: verifyAccessToken },
+                ...integrationProviders(options.supabase, verifyAccessToken),
                 { provide: APP_FILTER, useClass: ErrorsFilter },
                 { provide: APP_GUARD, useClass: RateLimitGuard },
                 { provide: APP_GUARD, useClass: OriginGuard },
+                { provide: APP_GUARD, useClass: CredentialGuard },
                 { provide: APP_GUARD, useClass: AuthGuard },
             ],
         }

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

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

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

@@ -0,0 +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"
+
+/** The domain capabilities of the API, with the app's verified Supabase identity adapter. */
+export const domainModules = (verifyAccessToken: VerifySupabaseAccessToken): Array<Type<unknown> | DynamicModule> => [
+    IdentityModule.register({ isGlobal: true, verifyAccessToken }),
+    LivenessModule.register({ isGlobal: true }),
+]

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

@@ -0,0 +1,16 @@
+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"
+
+/** 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 },
+]

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

@@ -0,0 +1,47 @@
+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 { 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 { 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"
+import { LoggingModule } from "@modules/platform/logging"
+import { RetryModule } from "@modules/platform/retry"
+import type { ApiOptions } from "../api.options"
+
+/**
+ * The platform area of the API: every platform capability, registered once and app-wide. A composition group holds
+ * one area's module list and nothing else (no logic, no environment read); `app.module.ts` spreads it into its
+ * imports.
+ */
+export const platformModules = (options: ApiOptions): Array<DynamicModule> => [
+    ClockModule.register({ isGlobal: true }),
+    RetryModule.register({ isGlobal: true }),
+    LoggingModule.register({ isGlobal: true }),
+    I18nModule.register({
+        isGlobal: true,
+        bundles: [ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
+    }),
+    ErrorsModule.register({
+        isGlobal: true,
+        kinds: [
+            CONFIG_ERROR_KINDS,
+            DATABASE_ERROR_KINDS,
+            HTTP_SECURITY_ERROR_KINDS,
+            IDENTITY_ERROR_KINDS,
+            SUPABASE_ERROR_KINDS,
+        ],
+    }),
+    CqrsModule.register({ isGlobal: true }),
+    HttpSecurityModule.register({
+        isGlobal: true,
+        ...options.httpSecurity,
+    }),
+    DatabaseModule.register({
+        isGlobal: true,
+        connections: [options.database],
+    }),
+]

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

@@ -0,0 +1,5 @@
+import type { DynamicModule, Type } from "@nestjs/common"
+import { SystemHealthHttpModule } from "@features/api/system-health"
+
+/** The system probes of the app, registered independently of product API doors. */
+export const systemModules = (): Array<Type<unknown> | DynamicModule> => [SystemHealthHttpModule.register({})]

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

@@ -0,0 +1,4 @@
+import type { DynamicModule, Type } from "@nestjs/common"
+
+/** The signed webhook transports and durable inbox capabilities of the API app. */
+export const webhooksModules = (): Array<Type<unknown> | DynamicModule> => []

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

@@ -1,26 +1,18 @@
 import { NestFactory } from "@nestjs/core"
 import { SystemClockService } from "@modules/platform/clock"
-import { EnvSource, parseServerConfig } from "@modules/platform/config"
-import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
-import { parseHttpSecurityConfig, RequestValidationService } from "@modules/platform/http-security"
+import { EnvSource } from "@modules/platform/config"
+import { applyHttpSecurity } from "@modules/platform/http-security"
 import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
-import { parseSupabaseConfig } from "@modules/integrations/supabase"
+import { readApiEnv } from "./api.env"
 import { AppModule } from "./app.module"
-import type { ApiOptions } from "./api.options"
 
 /** Reads the environment once, composes the API from parsed options and serves until a shutdown signal. */
 const bootstrap = async (): Promise<void> => {
     const env = EnvSource.fromProcess()
-    const options: ApiOptions = {
-        server: parseServerConfig(env),
-        httpSecurity: parseHttpSecurityConfig(env),
-        database: parsePrimaryDatabaseConfig(env),
-        supabase: parseSupabaseConfig(env),
-    }
+    const options = readApiEnv(env)
     const app = await NestFactory.create(AppModule.register(options), { rawBody: true })
-    app.enableCors({ origin: [...options.httpSecurity.allowedOrigins] })
+    applyHttpSecurity(app, options.httpSecurity, { trustProxy: 1 })
     app.enableShutdownHooks()
-    app.useGlobalPipes(app.get(RequestValidationService))
     await app.listen(options.server.port)
     createJsonLogger(new SystemClockService()).info(LoggingLogEvent.ServerStarted, {
         service: "api",

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

@@ -0,0 +1,17 @@
+import type { EnvSource, Secret } from "@modules/platform/config"
+import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
+
+/** The cli's primary database configuration before command composition. */
+export interface CliEnv {
+    /** The logical connection name declared in `hfs.json`. */
+    readonly name: string
+    /** The Supabase PostgreSQL provider. */
+    readonly provider: "supabase"
+    /** The least-privilege database connection URL, read through the secret source. */
+    readonly url: Secret
+    /** The isolated PostgreSQL schema. */
+    readonly schema?: string
+}
+
+/** Reads the cli environment with no defaults; database secret readers prefer mounted files. */
+export const readCliEnv = (env: EnvSource): CliEnv => parsePrimaryDatabaseConfig(env)

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

@@ -0,0 +1,12 @@
+import type { DynamicModule } from "@nestjs/common"
+import { ClockModule } from "@modules/platform/clock"
+import { DatabaseModule } from "@modules/platform/database"
+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. */
+export const platformModules = (options: CliAppOptions): Array<DynamicModule> => [
+    ClockModule.register({ isGlobal: true }),
+    LoggingModule.register({ isGlobal: true }),
+    DatabaseModule.register({ isGlobal: true, connections: options.connections }),
+]

package/templates/be/skeleton-lite/src/modules/domain/identity/admission.policy.spec.ts

@@ -1,21 +1,87 @@
+import { Test } from "@nestjs/testing"
 import type { Principal } from "@modules/platform/cqrs"
 import { admit } from "./admission.policy"
-import { IdentityErrorCode } from "./errors/identity.error"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import type { PublicMetadata } from "./identity.contracts"
 import { PublicReason } from "./identity.contracts"
 
 const principal: Principal = { id: "user-1", role: "authenticated" }
 
+const ADMISSION: unique symbol = Symbol("identity.admission")
+
+const runtimeMetadata = (source: string): PublicMetadata => {
+    try {
+        const metadata: PublicMetadata = JSON.parse(source)
+        return metadata
+    } catch (cause) {
+        throw new IdentityError({ code: IdentityErrorCode.Unauthenticated, cause })
+    }
+}
+
 describe("admit", () => {
+    let subject: typeof admit
+
+    beforeEach(async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [{ provide: ADMISSION, useFactory: () => admit }],
+        }).compile()
+        subject = moduleRef.get<typeof admit>(ADMISSION)
+    })
+
     it("admits a door that states why it is public, with or without a caller", () => {
-        expect(admit({ reason: PublicReason.Health }, undefined)).toSucceedWith(PublicReason.Health)
-        expect(admit({ reason: PublicReason.SignedWebhook }, principal)).toSucceedWith(PublicReason.SignedWebhook)
+        expect(subject({ reason: PublicReason.Health }, undefined)).toSucceedWith(PublicReason.Health)
+        expect(subject({ reason: PublicReason.SignedWebhook }, principal)).toSucceedWith(PublicReason.SignedWebhook)
+        expect(subject({ reason: PublicReason.AuthHandshake }, undefined)).toSucceedWith(PublicReason.AuthHandshake)
+        expect(subject({ reason: PublicReason.CatalogRead }, undefined)).toSucceedWith(PublicReason.CatalogRead)
+    })
+
+    it("does not trust a reason outside the closed vocabulary", () => {
+        const outside = runtimeMetadata('{"reason":"anything"}')
+        expect(subject(outside, undefined)).toBeRefused(IdentityErrorCode.Unauthenticated)
+        expect(subject(outside, principal)).toSucceedWith(principal)
+    })
+
+    it("does not treat runtime metadata without a public reason as public", () => {
+        const metadata = runtimeMetadata("{}")
+        expect(subject(metadata, undefined)).toBeRefused(IdentityErrorCode.Unauthenticated)
+        expect(subject(metadata, principal)).toSucceedWith(principal)
     })
 
     it("admits the verified principal of a door that is not public", () => {
-        expect(admit(undefined, principal)).toSucceedWith(principal)
+        expect(subject(undefined, principal)).toSucceedWith(principal)
+    })
+
+    it("admits a credential door whose principal has the required kind", () => {
+        const credentialPrincipal = { kind: "api-key", subject: "key-1", workspaceId: "ws-1" } as const
+        const credential = { required: { kind: "api-key" }, principal: credentialPrincipal } as const
+
+        expect(subject(undefined, undefined, credential)).toSucceedWith(credentialPrincipal)
+        expect(subject(undefined, principal, credential)).toSucceedWith(credentialPrincipal)
+        expect(subject({ reason: PublicReason.Health }, principal, credential)).toSucceedWith(credentialPrincipal)
+    })
+
+    it("refuses a credential door without a credential principal, even with a session or public metadata", () => {
+        const credential = { required: { kind: "api-key" }, principal: undefined } as const
+
+        expect(subject(undefined, undefined, credential)).toBeRefused(IdentityErrorCode.Unauthenticated)
+        expect(subject(undefined, principal, credential)).toBeRefused(IdentityErrorCode.Unauthenticated)
+        expect(subject({ reason: PublicReason.Health }, principal, credential)).toBeRefused(
+            IdentityErrorCode.Unauthenticated,
+        )
+    })
+
+    it("refuses a credential principal of another kind, even with a session or public metadata", () => {
+        const credentialPrincipal = { kind: "tool-token", subject: "tool-1", workspaceId: "ws-1" } as const
+        const credential = { required: { kind: "api-key" }, principal: credentialPrincipal } as const
+
+        expect(subject(undefined, undefined, credential)).toBeRefused(IdentityErrorCode.Unauthenticated)
+        expect(subject(undefined, principal, credential)).toBeRefused(IdentityErrorCode.Unauthenticated)
+        expect(subject({ reason: PublicReason.Health }, principal, credential)).toBeRefused(
+            IdentityErrorCode.Unauthenticated,
+        )
     })
 
     it("refuses a door that is not public when no principal was verified", () => {
-        expect(admit(undefined, undefined)).toBeRefused(IdentityErrorCode.Unauthenticated)
+        expect(subject(undefined, undefined)).toBeRefused(IdentityErrorCode.Unauthenticated)
     })
 })

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

@@ -1,14 +1,41 @@
 import { ok, refused } from "@modules/platform/primitives"
 import type { Outcome } from "@modules/platform/primitives"
+import type { CredentialMetadata, CredentialPrincipal } from "./credential.contracts"
 import { IdentityErrorCode } from "./errors/identity.error"
 import type { Principal } from "@modules/platform/cqrs"
 import type { IdentityAdmission, PublicMetadata } from "./identity.contracts"
+import { PublicReason } from "./identity.contracts"
 
-/** Admits an explicitly public door or a verified principal; everything else is refused. */
+/** What a credential-marked door requires and what `CredentialGuard` established for it. */
+export interface CredentialAdmission {
+    /** The `@Credential` metadata of the door. */
+    readonly required: CredentialMetadata
+    /** The principal `CredentialGuard` set on the request, when the credential authenticated. */
+    readonly principal: CredentialPrincipal | undefined
+}
+
+const admitCredential = ({
+    required,
+    principal,
+}: CredentialAdmission): Outcome<CredentialPrincipal, IdentityErrorCode> =>
+    principal?.kind === required.kind ? ok(principal) : refused(IdentityErrorCode.Unauthenticated)
+
+/** Admits a matching credential principal, an explicitly public door or a verified session; everything else is refused. */
 export const admit = (
     metadata: PublicMetadata | undefined,
     principal: Principal | undefined,
+    credential?: CredentialAdmission,
 ): Outcome<IdentityAdmission, IdentityErrorCode> => {
-    if (metadata !== undefined) return ok(metadata.reason)
+    if (credential !== undefined) return admitCredential(credential)
+    switch (metadata?.reason) {
+        case PublicReason.Health:
+        case PublicReason.AuthHandshake:
+        case PublicReason.SignedWebhook:
+        case PublicReason.CatalogRead:
+            return ok(metadata.reason)
+        case undefined:
+        default:
+            break
+    }
     return principal === undefined ? refused(IdentityErrorCode.Unauthenticated) : ok(principal)
 }

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