@starci/hfs 4.3.0 → 4.4.0

package/templates/be/skeleton/src/modules/platform/primitives/outcome.mapper.spec.ts

@@ -1,3 +1,4 @@
+import { Test } from "@nestjs/testing"
 import { DomainError } from "@modules/platform/errors"
 import { ok, refused, unwrapOutcome } from "./outcome.mapper"
 
@@ -5,18 +6,31 @@ type CapabilityErrorCode = "CAPABILITY_REFUSED"
 
 class CapabilityError extends DomainError<CapabilityErrorCode> {}
 
+const OUTCOME_MAPPERS: unique symbol = Symbol("primitives.outcome")
+
+type OutcomeMappers = { ok: typeof ok; refused: typeof refused; unwrapOutcome: typeof unwrapOutcome }
+
 describe("outcome mappers", () => {
+    let subject: OutcomeMappers
+
+    beforeEach(async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [{ provide: OUTCOME_MAPPERS, useFactory: () => ({ ok, refused, unwrapOutcome }) }],
+        }).compile()
+        subject = moduleRef.get<OutcomeMappers>(OUTCOME_MAPPERS)
+    })
+
     describe("ok", () => {
         it("wraps the produced value as a success", () => {
             const value = { id: "value-1" }
 
-            expect(ok(value)).toEqual({ kind: "ok", value })
+            expect(subject.ok(value)).toEqual({ kind: "ok", value })
         })
     })
 
     describe("refused", () => {
         it("wraps the capability code and display parameters as a refusal", () => {
-            expect(refused("CAPABILITY_REFUSED", { resource: "value-1" })).toEqual({
+            expect(subject.refused("CAPABILITY_REFUSED", { resource: "value-1" })).toEqual({
                 kind: "refused",
                 code: "CAPABILITY_REFUSED",
                 params: { resource: "value-1" },
@@ -24,7 +38,7 @@ describe("outcome mappers", () => {
         })
 
         it("keeps display parameters optional", () => {
-            expect(refused("CAPABILITY_REFUSED")).toEqual({
+            expect(subject.refused("CAPABILITY_REFUSED")).toEqual({
                 kind: "refused",
                 code: "CAPABILITY_REFUSED",
                 params: undefined,
@@ -34,13 +48,13 @@ describe("outcome mappers", () => {
 
     describe("unwrapOutcome", () => {
         it("returns the value of a successful outcome", () => {
-            expect(unwrapOutcome(ok("value-1"), CapabilityError)).toBe("value-1")
+            expect(subject.unwrapOutcome(subject.ok("value-1"), CapabilityError)).toBe("value-1")
         })
 
         it("turns a refusal into the capability error with its parameters", () => {
-            const outcome = refused<CapabilityErrorCode>("CAPABILITY_REFUSED", { resource: "value-1" })
+            const outcome = subject.refused<CapabilityErrorCode>("CAPABILITY_REFUSED", { resource: "value-1" })
 
-            expect(() => unwrapOutcome(outcome, CapabilityError)).toThrow(
+            expect(() => subject.unwrapOutcome(outcome, CapabilityError)).toThrow(
                 expect.objectContaining({
                     name: "CapabilityError",
                     code: "CAPABILITY_REFUSED",

package/templates/be/skeleton/src/modules/platform/primitives/sequence.policy.spec.ts

@@ -1,3 +1,4 @@
+import { Test } from "@nestjs/testing"
 import { DomainError } from "@modules/platform/errors"
 import { eachInOrder } from "./sequence.policy"
 
@@ -5,13 +6,24 @@ type SequenceErrorCode = "STEP_FAILED"
 
 class SequenceError extends DomainError<SequenceErrorCode> {}
 
+const SEQUENCE: unique symbol = Symbol("primitives.sequence")
+
 const pause = (): Promise<void> => new Promise((resolve) => setImmediate(resolve))
 
 describe("eachInOrder", () => {
+    let subject: typeof eachInOrder
+
+    beforeEach(async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [{ provide: SEQUENCE, useFactory: () => eachInOrder }],
+        }).compile()
+        subject = moduleRef.get<typeof eachInOrder>(SEQUENCE)
+    })
+
     it("starts an item only after the one before it settled, in item order", async () => {
         const events: Array<string> = []
 
-        await eachInOrder(new Set(["a", "b", "c"]), async (item, index) => {
+        await subject(new Set(["a", "b", "c"]), async (item, index) => {
             events.push(`start ${item} ${index}`)
             await pause()
             events.push(`end ${item}`)
@@ -21,13 +33,13 @@ describe("eachInOrder", () => {
     })
 
     it("answers nothing for an empty list", async () => {
-        await expect(eachInOrder([], () => Promise.resolve())).resolves.toBeUndefined()
+        await expect(subject([], () => Promise.resolve())).resolves.toBeUndefined()
     })
 
     it("rejects with the first failure and never starts the items after it", async () => {
         const started: Array<number> = []
 
-        const run = eachInOrder([1, 2, 3], async (item) => {
+        const run = subject([1, 2, 3], async (item) => {
             started.push(item)
             await pause()
             if (item === 2) throw new SequenceError({ code: "STEP_FAILED" })
@@ -38,7 +50,7 @@ describe("eachInOrder", () => {
     })
 
     it("rejects when a step throws before it returns a promise", async () => {
-        const run = eachInOrder([1], (): Promise<void> => {
+        const run = subject([1], (): Promise<void> => {
             throw new SequenceError({ code: "STEP_FAILED" })
         })
 

package/templates/be/skeleton/src/modules/platform/retry/index.ts

@@ -0,0 +1,3 @@
+export type { Timer } from "./retry.port"
+export { TIMER, InjectTimer } from "./retry.decorators"
+export { RetryModule } from "./retry.module"

package/templates/be/skeleton/src/modules/platform/retry/retry.decorators.ts

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { Timer } from "./retry.port"
+
+/** The cancellable host timer provided by the retry capability. */
+export const TIMER: unique symbol = Symbol("platform.retry.timer")
+
+/** Injects the cancellable timer. Parameter type: Timer. */
+export const InjectTimer = (): TypedParameterDecorator<Timer> => injector<Timer>(TIMER)

package/templates/be/skeleton/src/modules/platform/retry/retry.module-definition.ts

@@ -0,0 +1,7 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { RetryOptions } from "./retry.options"
+
+/** The configurable-module base of the retry capability; the app root decides its global scope. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<RetryOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/skeleton/src/modules/platform/retry/retry.module.ts

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { TIMER } from "./retry.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./retry.module-definition"
+import { SystemTimerService } from "./system-timer.service"
+
+@Module({})
+/** Provides the cancellable Timer port backed by the host timer API. */
+export class RetryModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), { provide: TIMER, useClass: SystemTimerService }],
+            exports: [TIMER],
+        }
+    }
+}

package/templates/be/skeleton/src/modules/platform/retry/retry.options.ts

@@ -0,0 +1,2 @@
+/** The retry capability takes no options; the module builder supplies the app's global-scope option. */
+export type RetryOptions = Record<never, never>

package/templates/be/skeleton/src/modules/platform/retry/retry.port.ts

@@ -0,0 +1,11 @@
+/** The work to run when a scheduled timer expires. */
+export type TimerCallback = () => void
+
+/** Cancels a callback that has not run yet. */
+export type CancelTimer = () => void
+
+/** Schedules bounded work without exposing the ambient host timers to consumers. */
+export interface Timer {
+    /** Schedules a callback and returns the function that cancels it. */
+    schedule(callback: TimerCallback, delayMs: number): CancelTimer
+}

package/templates/be/skeleton/src/modules/platform/retry/system-timer.service.spec.ts

@@ -0,0 +1,36 @@
+import { Test } from "@nestjs/testing"
+import { SystemTimerService } from "./system-timer.service"
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({ providers: [SystemTimerService] }).compile()
+    return moduleRef.get(SystemTimerService)
+}
+
+describe("SystemTimerService", () => {
+    beforeEach(() => jest.useFakeTimers())
+    afterEach(() => jest.useRealTimers())
+
+    it("runs a callback when its delay expires", async () => {
+        const service = await build()
+        const callback = jest.fn()
+
+        service.schedule(callback, 1000)
+        await jest.advanceTimersByTimeAsync(999)
+        expect(callback).not.toHaveBeenCalled()
+        await jest.advanceTimersByTimeAsync(1)
+        expect(callback).toHaveBeenCalledTimes(1)
+        expect(jest.getTimerCount()).toBe(0)
+    })
+
+    it("cancels a scheduled callback", async () => {
+        const service = await build()
+        const callback = jest.fn()
+        const cancel = service.schedule(callback, 1000)
+
+        cancel()
+        await jest.advanceTimersByTimeAsync(1000)
+
+        expect(callback).not.toHaveBeenCalled()
+        expect(jest.getTimerCount()).toBe(0)
+    })
+})

package/templates/be/skeleton/src/modules/platform/retry/system-timer.service.ts

@@ -0,0 +1,10 @@
+import type { CancelTimer, Timer, TimerCallback } from "./retry.port"
+
+/** The production timer: owns scheduling and cancellation through the host timer API. */
+export class SystemTimerService implements Timer {
+    /** Runs the callback after its delay unless the returned function cancels it. */
+    schedule(callback: TimerCallback, delayMs: number): CancelTimer {
+        const handle = setTimeout(callback, delayMs)
+        return () => clearTimeout(handle)
+    }
+}

package/templates/be/skeleton/src/tests/contract/http-security/http-security.contract-spec.ts

@@ -0,0 +1,54 @@
+import { EnvSource } from "@modules/platform/config"
+import { parseHttpSecurityConfig } from "@modules/platform/http-security"
+
+describe("HTTP security environment contract", () => {
+    it("defaults to development and permits a local HTTP origin", () => {
+        const config = parseHttpSecurityConfig(
+            new EnvSource({ HTTP_SECURITY_ALLOWED_ORIGINS: "http://localhost:3000" }),
+        )
+        expect(config.allowedOrigins).toEqual(["http://localhost:3000"])
+        expect(config.allowHttpOrigins).toBe(true)
+        expect(config.rateLimit).toEqual({ windowMs: 60_000, defaultLimit: 600, strictLimit: 30 })
+        expect(config.webhooks).toEqual({})
+    })
+
+    it.each(["development", "test"])("permits HTTP origins in %s", (mode) => {
+        const config = parseHttpSecurityConfig(
+            new EnvSource({ NODE_ENV: mode, HTTP_SECURITY_ALLOWED_ORIGINS: "http://localhost:3000" }),
+        )
+        expect(config.allowedOrigins).toEqual(["http://localhost:3000"])
+        expect(config.allowHttpOrigins).toBe(true)
+    })
+
+    it("trims production HTTPS origins and reads declared rate tunables", () => {
+        const config = parseHttpSecurityConfig(
+            new EnvSource({
+                NODE_ENV: "production",
+                HTTP_SECURITY_ALLOWED_ORIGINS: " https://web.example , https://admin.example:8443 ",
+                HTTP_SECURITY_RATE_WINDOW: "2s",
+                HTTP_SECURITY_RATE_DEFAULT_LIMIT: "100",
+                HTTP_SECURITY_RATE_STRICT_LIMIT: "10",
+            }),
+        )
+        expect(config.allowedOrigins).toEqual(["https://web.example", "https://admin.example:8443"])
+        expect(config.allowHttpOrigins).toBe(false)
+        expect(config.rateLimit).toEqual({ windowMs: 2_000, defaultLimit: 100, strictLimit: 10 })
+    })
+
+    it.each(["production", "staging"])("rejects HTTP origins in %s", (mode) => {
+        expect(() =>
+            parseHttpSecurityConfig(
+                new EnvSource({
+                    NODE_ENV: mode,
+                    HTTP_SECURITY_ALLOWED_ORIGINS: "http://web.example",
+                }),
+            ),
+        ).toThrow(expect.objectContaining({ code: "HTTP_SECURITY_REQUEST_INVALID" }))
+    })
+
+    it("rejects an empty allowlist entry after a comma", () => {
+        expect(() =>
+            parseHttpSecurityConfig(new EnvSource({ HTTP_SECURITY_ALLOWED_ORIGINS: "https://web.example," })),
+        ).toThrow(expect.objectContaining({ code: "HTTP_SECURITY_REQUEST_INVALID" }))
+    })
+})

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

@@ -1,22 +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, IdentityModule } from "@modules/domain/identity"
-import {
-    SUPABASE_ACCESS_TOKEN_VERIFIER,
-    SUPABASE_ADMIN_CLIENT,
-    createSupabaseAccessTokenVerifier,
-    createSupabaseAdminClient,
-} from "@modules/integrations/supabase"
-import { LivenessModule } from "@modules/domain/liveness"
+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: it spreads the composition groups of `compose/`, 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 {
@@ -25,19 +23,17 @@ export class AppModule {
             module: AppModule,
             imports: [
                 ...platformModules(options),
-                IdentityModule.register({ isGlobal: true, verifyAccessToken }),
-                LivenessModule.register({ isGlobal: true }),
-                SystemHealthHttpModule,
+                ...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

@@ -9,6 +9,7 @@ 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"
 
 /**
@@ -18,6 +19,7 @@ import type { ApiOptions } from "../api.options"
  */
 export const platformModules = (options: ApiOptions): Array<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
+    RetryModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
     I18nModule.register({
         isGlobal: true,

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,7 +1,7 @@
 import { NestFactory } from "@nestjs/core"
 import { SystemClockService } from "@modules/platform/clock"
 import { EnvSource } from "@modules/platform/config"
-import { RequestValidationService } from "@modules/platform/http-security"
+import { applyHttpSecurity } from "@modules/platform/http-security"
 import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
 import { readApiEnv } from "./api.env"
 import { AppModule } from "./app.module"
@@ -11,9 +11,8 @@ const bootstrap = async (): Promise<void> => {
     const env = EnvSource.fromProcess()
     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/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)
 }