@starci/hfs 4.2.17 → 4.4.0

package/templates/be/skeleton/src/features/api/system-health/transport/http/system-health-http.module.ts

@@ -1,7 +1,12 @@
 import { Module } from "@nestjs/common"
 import { SystemHealthModule } from "../../system-health.module"
 import { LiveController } from "./live.controller"
+import { ReadyController } from "./ready.controller"
+import { ConfigurableModuleClass } from "./system-health-http.module-definition"
 
-@Module({ imports: [SystemHealthModule], controllers: [LiveController] })
-/** The HTTP transport of the health feature: the liveness door. */
-export class SystemHealthHttpModule {}
+@Module({
+    imports: [SystemHealthModule.register({})],
+    controllers: [LiveController, ReadyController],
+})
+/** The HTTP transport of the health feature: independent liveness and required-dependency readiness doors. */
+export class SystemHealthHttpModule extends ConfigurableModuleClass {}

package/templates/be/skeleton/src/features/api/system-health/transport/http/system-health-http.options.ts

@@ -0,0 +1,2 @@
+/** The system-health-http module takes no options yet. */
+export type SystemHealthHttpOptions = Record<string, never>

package/templates/be/skeleton/src/features/cli/cli.module-definition.ts

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

package/templates/be/skeleton/src/features/cli/cli.module.ts

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./cli.module-definition"
 import { MigrateModule } from "./migrate/migrate.module"
 import { SeedModule } from "./seed/seed.module"
 
-@Module({ imports: [MigrateModule, SeedModule] })
+@Module({ imports: [MigrateModule.register({}), SeedModule.register({})] })
 /** The cli feature root: every command group of the back end, compiled only into apps/cli. */
-export class CliModule {}
+export class CliModule extends ConfigurableModuleClass {}

package/templates/be/skeleton/src/features/cli/cli.options.ts

@@ -0,0 +1,2 @@
+/** The cli module takes no options yet. */
+export type CliOptions = Record<string, never>

package/templates/be/skeleton/src/features/cli/migrate/migrate.module-definition.ts

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

package/templates/be/skeleton/src/features/cli/migrate/migrate.module.ts

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
 import { MigrateCli } from "./migrate.cli"
+import { ConfigurableModuleClass } from "./migrate.module-definition"
 import { RunCli } from "./subs/run.cli"
 
 @Module({ providers: [MigrateCli, RunCli] })
 /** The migrate group: its command and its sub-commands; the connections come from the database capability. */
-export class MigrateModule {}
+export class MigrateModule extends ConfigurableModuleClass {}

package/templates/be/skeleton/src/features/cli/migrate/migrate.options.ts

@@ -0,0 +1,2 @@
+/** The migrate module takes no options yet. */
+export type MigrateOptions = Record<string, never>

package/templates/be/skeleton/src/features/cli/seed/seed.module-definition.ts

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

package/templates/be/skeleton/src/features/cli/seed/seed.module.ts

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
 import { SeedCli } from "./seed.cli"
+import { ConfigurableModuleClass } from "./seed.module-definition"
 import { RunSeedsCli } from "./subs/run.cli"
 
 @Module({ providers: [SeedCli, RunSeedsCli] })
 /** The seed group: its command and its sub-commands; the connections and the seed file reader come from the database capability. */
-export class SeedModule {}
+export class SeedModule extends ConfigurableModuleClass {}

package/templates/be/skeleton/src/features/cli/seed/seed.options.ts

@@ -0,0 +1,2 @@
+/** The seed module takes no options yet. */
+export type SeedOptions = Record<string, never>

package/templates/be/skeleton/src/features/cli/seed/subs/run.cli.spec.ts

@@ -3,17 +3,17 @@ import { Test } from "@nestjs/testing"
 import { SeedRunnerService } from "@modules/platform/database"
 import { RunSeedsCli } from "./run.cli"
 
-const build = async (seeds: SeedRunnerService) => {
+const build = async () => {
+    const seeds = mock<SeedRunnerService>()
     const moduleRef = await Test.createTestingModule({
         providers: [RunSeedsCli, { provide: SeedRunnerService, useValue: seeds }],
     }).compile()
-    return moduleRef.get(RunSeedsCli)
+    return { command: moduleRef.get(RunSeedsCli), seeds }
 }
 
 describe("RunSeedsCli", () => {
     it("delegates the seed run of the named environment to the seed runner once", async () => {
-        const seeds = mock<SeedRunnerService>()
-        const command = await build(seeds)
+        const { command, seeds } = await build()
 
         await command.run([], { env: "staging" })
 
@@ -22,8 +22,7 @@ describe("RunSeedsCli", () => {
     })
 
     it("delegates with no environment when none is named, and takes --env as given", async () => {
-        const seeds = mock<SeedRunnerService>()
-        const command = await build(seeds)
+        const { command, seeds } = await build()
 
         await command.run([])
 

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

@@ -1,13 +1,65 @@
+import { Test } from "@nestjs/testing"
 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 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", () => {
-    it("admits a door that states why it is public", () => {
-        expect(admit({ reason: PublicReason.Health })).toSucceedWith(PublicReason.Health)
+    let subject: typeof admit
+
+    beforeEach(async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [{ provide: ADMISSION, useFactory: () => admit }],
+        }).compile()
+        subject = moduleRef.get<typeof admit>(ADMISSION)
+    })
+
+    it.each([PublicReason.Health, PublicReason.AuthHandshake, PublicReason.SignedWebhook, PublicReason.CatalogRead])(
+        "admits a door with the canonical public reason %s",
+        (reason) => {
+            expect(subject({ reason })).toSucceedWith(reason)
+        },
+    )
+
+    it("admits a credential door whose principal has the required kind", () => {
+        const principal = { kind: "api-key", subject: "key-1", workspaceId: "ws-1" } as const
+
+        expect(subject(undefined, { required: { kind: "api-key" }, principal })).toSucceedWith(principal)
+    })
+
+    it("refuses a credential door without a principal of the required kind", () => {
+        const principal = { kind: "tool-token", subject: "tool-1", workspaceId: "ws-1" } as const
+
+        expect(subject(undefined, { required: { kind: "api-key" }, principal })).toBeRefused(
+            IdentityErrorCode.Unauthenticated,
+        )
+        expect(subject(undefined, { required: { kind: "api-key" }, principal: undefined })).toBeRefused(
+            IdentityErrorCode.Unauthenticated,
+        )
     })
 
     it("refuses a door that is not public", () => {
-        expect(admit(undefined)).toBeRefused(IdentityErrorCode.Unauthenticated)
+        expect(subject(undefined)).toBeRefused(IdentityErrorCode.Unauthenticated)
+    })
+
+    it("refuses an unknown public reason supplied as runtime metadata", () => {
+        const metadata = runtimeMetadata('{"reason":"tool-token"}')
+        expect(subject(metadata)).toBeRefused(IdentityErrorCode.Unauthenticated)
+    })
+
+    it("refuses runtime metadata without a public reason", () => {
+        const metadata = runtimeMetadata("{}")
+        expect(subject(metadata)).toBeRefused(IdentityErrorCode.Unauthenticated)
     })
 })

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

@@ -1,11 +1,42 @@
 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 { PublicMetadata, PublicReason } from "./identity.contracts"
+import type { PublicMetadata } from "./identity.contracts"
+import { PublicReason } from "./identity.contracts"
+
+/** 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)
 
 /**
- * The default-deny decision of one door: a door that states why it is public is admitted; every other door is refused
- * until the design that adds sign-in establishes a caller here.
+ * The default-deny decision of one door: a credential-marked door is admitted only with its authenticated credential
+ * principal; a door with a canonical public reason is admitted; every other door is refused until the design that adds
+ * sign-in establishes a session principal here.
  */
-export const admit = (metadata: PublicMetadata | undefined): Outcome<PublicReason, IdentityErrorCode> =>
-    metadata === undefined ? refused(IdentityErrorCode.Unauthenticated) : ok(metadata.reason)
+export const admit = (
+    metadata: PublicMetadata | undefined,
+    credential?: CredentialAdmission,
+): Outcome<PublicReason | CredentialPrincipal, IdentityErrorCode> => {
+    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:
+            return refused(IdentityErrorCode.Unauthenticated)
+    }
+}

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

@@ -1,37 +1,68 @@
 import type { ExecutionContext } from "@nestjs/common"
+import type { HttpArgumentsHost } from "@nestjs/common/interfaces"
 import { Reflector } from "@nestjs/core"
 import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 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 { CREDENTIAL_KEY, PUBLIC_KEY } from "./identity.decorators"
 
-const build = async (metadata: PublicMetadata | undefined) => {
+interface Door {
+    readonly credential?: CredentialMetadata
+    readonly metadata?: PublicMetadata
+    readonly principal?: CredentialPrincipal
+}
+
+const build = async ({ credential, metadata }: Door) => {
     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 }],
     }).compile()
-    return { guard: moduleRef.get(AuthGuard), reflector }
+    return moduleRef.get(AuthGuard)
 }
 
-const contextOf = () => {
+const contextOf = (principal?: CredentialPrincipal) => {
     const context = mock<ExecutionContext>()
     context.getHandler.mockReturnValue(() => undefined)
-    context.getClass.mockReturnValue(class Door {})
+    context.getClass.mockReturnValue(class DoorClass {})
+    context.getType.mockReturnValue("http")
+    const host = mock<HttpArgumentsHost>()
+    host.getRequest.mockReturnValue({ credentialPrincipal: principal })
+    context.switchToHttp.mockReturnValue(host)
     return context
 }
 
+const API_KEY: CredentialPrincipal = { kind: "api-key", subject: "key-1", workspaceId: "ws-1" }
+
 describe("AuthGuard", () => {
     it("lets a door through when it states why it is public", async () => {
-        const { guard } = await build({ reason: PublicReason.Health })
+        const guard = await build({ metadata: { reason: PublicReason.Health } })
 
         expect(guard.canActivate(contextOf())).toBe(true)
     })
 
-    it("refuses every door that is not public", async () => {
-        const { guard } = await build(undefined)
+    it("refuses every door that is neither public nor credential-marked", async () => {
+        const guard = await build({})
+
+        expect(() => guard.canActivate(contextOf())).toThrow(
+            expect.objectContaining({ code: IdentityErrorCode.Unauthenticated }),
+        )
+    })
+
+    it("lets a credential door through once the credential principal is set", async () => {
+        const guard = await build({ credential: { kind: "api-key" } })
+
+        expect(guard.canActivate(contextOf(API_KEY))).toBe(true)
+    })
+
+    it("refuses a credential door without a credential principal", async () => {
+        const guard = await build({ credential: { kind: "api-key" } })
 
         expect(() => guard.canActivate(contextOf())).toThrow(
             expect.objectContaining({ code: IdentityErrorCode.Unauthenticated }),

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

@@ -2,24 +2,30 @@ import { Injectable } from "@nestjs/common"
 import type { CanActivate, ExecutionContext } from "@nestjs/common"
 import type { Reflector } from "@nestjs/core"
 import { InjectReflector } from "@modules/platform/composition"
+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 { PUBLIC_KEY } from "./identity.decorators"
+import { CREDENTIAL_KEY, PUBLIC_KEY } from "./identity.decorators"
 
 @Injectable()
-/** The third app guard and the default-deny gate: a door is open only when it says `@Public({ reason })`. */
+/**
+ * The fourth app guard and the default-deny gate: a door is open only when it says `@Public({ reason })`, or when it is
+ * marked `@Credential` and `CredentialGuard` has set the credential principal. It never calls another guard.
+ */
 export class AuthGuard implements CanActivate {
     constructor(@InjectReflector() private readonly reflector: Reflector) {}
 
-    /** Lets public doors through and refuses every other door. */
+    /** Lets public and credential-authenticated doors through and refuses every other door. */
     canActivate(context: ExecutionContext): boolean {
-        const metadata = this.reflector.getAllAndOverride<PublicMetadata | undefined>(PUBLIC_KEY, [
-            context.getHandler(),
-            context.getClass(),
-        ])
-        unwrapOutcome(admit(metadata), IdentityError)
+        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 }
+        unwrapOutcome(admit(metadata, credential), IdentityError)
         return true
     }
 }

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

@@ -0,0 +1,26 @@
+/** The closed set of alternate credential families a door can accept. */
+export type CredentialKind = "api-key" | "run-token" | "tool-token" | "link-token" | "posting"
+
+/** Alternate credentials accepted only by doors marked with `@Credential`. */
+export interface CredentialMetadata {
+    /** The credential family this door accepts. */
+    readonly kind: CredentialKind
+    /** An optional workflow constraint the authenticator may enforce for the credential. */
+    readonly workflow?: string
+}
+
+/** A credential identity is deliberately separate from a signed-in user. */
+export interface CredentialPrincipal {
+    /** The credential family that established this identity. */
+    readonly kind: CredentialKind
+    /** The key, job, run or link the credential identifies. */
+    readonly subject: string
+    /** The only workspace this credential can act for. */
+    readonly workspaceId: string
+}
+
+/** The port the app binds to the capability that owns credential verification. */
+export interface CredentialAuthenticator {
+    /** Authenticates the actual credential, throwing the owning domain's refusal on failure. */
+    authenticate(metadata: CredentialMetadata, authorization: string, resourceId?: string): Promise<CredentialPrincipal>
+}

package/templates/be/skeleton/src/modules/domain/identity/credential.guard.spec.ts

@@ -0,0 +1,119 @@
+import type { ExecutionContext } from "@nestjs/common"
+import type { HttpArgumentsHost } from "@nestjs/common/interfaces"
+import { Reflector } from "@nestjs/core"
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { CredentialGuard } from "./credential.guard"
+import type { CredentialAuthenticator, CredentialMetadata, CredentialPrincipal } from "./credential.contracts"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { CREDENTIAL_AUTHENTICATOR } from "./identity.decorators"
+
+const PRINCIPAL: CredentialPrincipal = { kind: "tool-token", subject: "tool-1", workspaceId: "ws-1" }
+
+interface FakeHeaders {
+    readonly authorization?: string
+}
+
+interface FakeParams {
+    readonly id?: unknown
+}
+
+interface FakeRequest {
+    credentialPrincipal?: CredentialPrincipal
+    readonly headers: FakeHeaders
+    readonly params?: FakeParams
+}
+
+const build = async (metadata: CredentialMetadata | undefined, principal: CredentialPrincipal = PRINCIPAL) => {
+    const reflector = mock<Reflector>()
+    reflector.getAllAndOverride.mockReturnValue(metadata)
+    const authenticator = mock<CredentialAuthenticator>()
+    authenticator.authenticate.mockResolvedValue(principal)
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            CredentialGuard,
+            { provide: Reflector, useValue: reflector },
+            { provide: CREDENTIAL_AUTHENTICATOR, useValue: authenticator },
+        ],
+    }).compile()
+    return { guard: moduleRef.get(CredentialGuard), authenticator }
+}
+
+const contextOf = (request: FakeRequest) => {
+    const context = mock<ExecutionContext>()
+    context.getHandler.mockReturnValue(() => undefined)
+    context.getClass.mockReturnValue(class DoorClass {})
+    context.getType.mockReturnValue("http")
+    const host = mock<HttpArgumentsHost>()
+    host.getRequest.mockReturnValue(request)
+    context.switchToHttp.mockReturnValue(host)
+    return context
+}
+
+const requestOf = (): FakeRequest => ({ headers: { authorization: "Bearer secret" }, params: { id: "run-1" } })
+
+describe("CredentialGuard", () => {
+    it("passes a door without credential metadata and authenticates nothing", async () => {
+        const { guard, authenticator } = await build(undefined)
+        const request = { ...requestOf(), credentialPrincipal: PRINCIPAL }
+
+        await expect(guard.canActivate(contextOf(request))).resolves.toBe(true)
+        expect(request.credentialPrincipal).toEqual(PRINCIPAL)
+        expect(authenticator.authenticate).not.toHaveBeenCalled()
+    })
+
+    it("authenticates a credential door and sets the credential principal", async () => {
+        const { guard, authenticator } = await build({ kind: "tool-token" }, PRINCIPAL)
+        const request = requestOf()
+
+        await expect(guard.canActivate(contextOf(request))).resolves.toBe(true)
+        expect(request.credentialPrincipal).toEqual(PRINCIPAL)
+        expect(authenticator.authenticate).toHaveBeenCalledWith({ kind: "tool-token" }, "Bearer secret", "run-1")
+    })
+
+    it("refuses a principal of another credential kind", async () => {
+        const { guard } = await build({ kind: "api-key" }, PRINCIPAL)
+        const request = requestOf()
+
+        await expect(guard.canActivate(contextOf(request))).rejects.toMatchObject({
+            code: IdentityErrorCode.Unauthenticated,
+        })
+        expect(request.credentialPrincipal).toBeUndefined()
+    })
+
+    it.each([
+        { ...PRINCIPAL, subject: "" },
+        { ...PRINCIPAL, workspaceId: "" },
+    ])("refuses an incomplete credential principal (%o)", async (principal) => {
+        const { guard } = await build({ kind: "tool-token" }, principal)
+        const request = requestOf()
+
+        await expect(guard.canActivate(contextOf(request))).rejects.toMatchObject({
+            code: IdentityErrorCode.Unauthenticated,
+        })
+        expect(request.credentialPrincipal).toBeUndefined()
+    })
+
+    it("clears an earlier credential principal when authentication refuses", async () => {
+        const { guard, authenticator } = await build({ kind: "tool-token" }, PRINCIPAL)
+        const refusal = new IdentityError({ code: IdentityErrorCode.Unauthenticated })
+        authenticator.authenticate.mockRejectedValue(refusal)
+        const request = { ...requestOf(), credentialPrincipal: PRINCIPAL }
+
+        await expect(guard.canActivate(contextOf(request))).rejects.toBe(refusal)
+        expect(request.credentialPrincipal).toBeUndefined()
+    })
+
+    it.each([undefined, { id: 1 }])(
+        "passes absent authorization and no string resource id to the authenticator (%o)",
+        async (params) => {
+            const metadata = { kind: "tool-token", workflow: "checkout" } as const
+            const { guard, authenticator } = await build(metadata, PRINCIPAL)
+            const request: FakeRequest = { headers: {}, params }
+
+            await expect(guard.canActivate(contextOf(request))).resolves.toBe(true)
+            expect(authenticator.authenticate).toHaveBeenCalledWith(metadata, "", undefined)
+            expect(request.credentialPrincipal).toEqual(PRINCIPAL)
+        },
+    )
+})

package/templates/be/skeleton/src/modules/domain/identity/credential.guard.ts

@@ -0,0 +1,43 @@
+import { Injectable } from "@nestjs/common"
+import type { CanActivate, ExecutionContext } from "@nestjs/common"
+import type { Reflector } from "@nestjs/core"
+import { InjectReflector } from "@modules/platform/composition"
+import { requestOf } from "@modules/platform/http-security"
+import type { CredentialAuthenticator, CredentialMetadata } from "./credential.contracts"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { CREDENTIAL_KEY, InjectCredentialAuthenticator } from "./identity.decorators"
+
+@Injectable()
+/**
+ * The third app guard: it acts only on a door marked `@Credential({ kind })`, authenticates the credential through the
+ * identity-owned port and sets the request's credential principal. Every other door passes through untouched and
+ * `AuthGuard` decides it.
+ */
+export class CredentialGuard implements CanActivate {
+    constructor(
+        @InjectReflector() private readonly reflector: Reflector,
+        @InjectCredentialAuthenticator() private readonly authenticator: CredentialAuthenticator,
+    ) {}
+
+    /** Authenticates a credential door and leaves every other door to `AuthGuard`. */
+    async canActivate(context: ExecutionContext): Promise<boolean> {
+        const metadata = this.reflector.getAllAndOverride<CredentialMetadata | undefined>(CREDENTIAL_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ])
+        if (metadata === undefined) return true
+        const request = requestOf(context)
+        request.credentialPrincipal = undefined
+        const id: unknown = request.params?.id
+        const principal = await this.authenticator.authenticate(
+            metadata,
+            request.headers.authorization ?? "",
+            typeof id === "string" ? id : undefined,
+        )
+        if (principal.kind !== metadata.kind || !principal.subject || !principal.workspaceId) {
+            throw new IdentityError({ code: IdentityErrorCode.Unauthenticated })
+        }
+        request.credentialPrincipal = principal
+        return true
+    }
+}

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

@@ -1,7 +1,23 @@
+import type { CredentialPrincipal } from "./credential.contracts"
+
+declare module "express-serve-static-core" {
+    /** The request carries what the credential guard established. */
+    interface Request {
+        /** The identity `CredentialGuard` authenticated on a door marked `@Credential`; never a session principal. */
+        credentialPrincipal?: CredentialPrincipal
+    }
+}
+
 /** Why a door is open to anonymous callers; the vocabulary is closed. */
 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. */

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

@@ -1,8 +1,25 @@
 import { SetMetadata } from "@nestjs/common"
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { CredentialAuthenticator, CredentialMetadata } from "./credential.contracts"
 import type { PublicMetadata } from "./identity.contracts"
 
 /** Metadata key of `@Public`. */
 export const PUBLIC_KEY = "domain.identity.public"
 
-/** Opens a door to anonymous callers, stating why; every other door needs a signed-in caller. */
+/** Opens a door to anonymous callers, stating why; every other door needs a credential or a signed-in caller. */
 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)

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

@@ -1,14 +1,32 @@
 import { Module } from "@nestjs/common"
-import type { DynamicModule } from "@nestjs/common"
+import type { DynamicModule, Provider } from "@nestjs/common"
 import { AuthGuard } from "./auth.guard"
+import { CredentialGuard } from "./credential.guard"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { 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: the guard that closes every door by default. The app registers AuthGuard itself after the throttler and the origin guard. */
+/** The identity capability: the credential guard and the guard that closes every door by default. The app registers them as APP_GUARDs after the throttler and the origin guard. */
 export class IdentityModule extends ConfigurableModuleClass {
-    /** Registers the capability once per app. */
+    /** Registers the capability once per app; the credential authenticator is the port the app binds. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
         const base = super.register(options)
-        return { ...base, providers: [...(base.providers ?? []), AuthGuard], exports: [AuthGuard] }
+        const authenticator: Provider =
+            options.credentialAuthenticator === undefined
+                ? refusingAuthenticator
+                : { provide: CREDENTIAL_AUTHENTICATOR, useClass: options.credentialAuthenticator }
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), authenticator, CredentialGuard, AuthGuard],
+            exports: [CredentialGuard, CREDENTIAL_AUTHENTICATOR, AuthGuard],
+        }
     }
 }