@starci/hfs 4.0.7 → 4.0.9

package/templates/be/skeleton/src/modules/platform/http-security/rate-limit.guard.spec.ts

@@ -0,0 +1,108 @@
+import "reflect-metadata"
+import type { ExecutionContext, Type } from "@nestjs/common"
+import type { Request } from "express"
+import { Reflector } from "@nestjs/core"
+import { Test } from "@nestjs/testing"
+import { FakeClock, mock } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { HttpSecurityErrorCode } from "./errors/http-security.error"
+import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
+import type { HttpSecurityOptions } from "./http-security.options"
+import { RateLimit, RateLimitGuard, RateTier } from "./rate-limit.guard"
+
+const AT = "2026-02-03T04:05:06.000Z"
+const options: HttpSecurityOptions = {
+    allowedOrigins: [],
+    rateLimit: { windowMs: 60_000, defaultLimit: 2, strictLimit: 1 },
+    webhooks: {},
+}
+
+const build = async (reflector: Reflector, clock: FakeClock) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            RateLimitGuard,
+            { provide: Reflector, useValue: reflector },
+            { provide: CLOCK, useValue: clock },
+            { provide: HTTP_SECURITY_OPTIONS, useValue: options },
+        ],
+    }).compile()
+    return moduleRef.get(RateLimitGuard)
+}
+
+/** An execution context of one POST from `ip` on the door; the handler and the class carry the tier metadata. */
+const contextOf = (ip: string | undefined, handler = () => undefined, door: Type<unknown> = class Door {}) => {
+    let address = ip
+    const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
+    http.getRequest.mockImplementation(() => mock<Request>({ headers: {}, method: "POST", ip: address }))
+    const context = mock<ExecutionContext>()
+    context.switchToHttp.mockReturnValue(http)
+    context.getHandler.mockReturnValue(handler)
+    context.getClass.mockReturnValue(door)
+    return { context, setIp: (value: string | undefined) => (address = value) }
+}
+
+const RATE_LIMITED = expect.objectContaining({ code: HttpSecurityErrorCode.RateLimited })
+
+describe("RateLimit", () => {
+    it("marks a door with the tier it declares, and the guard counts it under that tier's limit", async () => {
+        class Door {}
+        RateLimit(RateTier.Strict)(Door)
+        const guard = await build(new Reflector(), new FakeClock(AT))
+        const { context } = contextOf("127.0.0.1", () => undefined, Door)
+
+        expect(guard.canActivate(context)).toBe(true)
+        expect(() => guard.canActivate(context)).toThrow(RATE_LIMITED)
+    })
+})
+
+describe("RateLimitGuard", () => {
+    it("counts an unmarked door under the default limit", async () => {
+        const guard = await build(mock<Reflector>(), new FakeClock(AT))
+        const { context } = contextOf("127.0.0.1")
+
+        expect(guard.canActivate(context)).toBe(true)
+        expect(guard.canActivate(context)).toBe(true)
+        expect(() => guard.canActivate(context)).toThrow(RATE_LIMITED)
+    })
+
+    it("opens a fresh window for a caller whose bucket expired", async () => {
+        const clock = new FakeClock(AT)
+        const guard = await build(mock<Reflector>(), clock)
+        const { context } = contextOf("127.0.0.1")
+
+        guard.canActivate(context)
+        guard.canActivate(context)
+        expect(() => guard.canActivate(context)).toThrow(RATE_LIMITED)
+
+        clock.advance(60_001)
+
+        expect(guard.canActivate(context)).toBe(true)
+    })
+
+    it("counts a request without an address under the unknown bucket", async () => {
+        const guard = await build(mock<Reflector>(), new FakeClock(AT))
+        const { context } = contextOf(undefined)
+
+        guard.canActivate(context)
+        guard.canActivate(context)
+        expect(() => guard.canActivate(context)).toThrow(RATE_LIMITED)
+    })
+
+    it("prunes the expired buckets when the map outgrows the bucket cap", async () => {
+        const clock = new FakeClock(AT)
+        const guard = await build(mock<Reflector>(), clock)
+        const { context, setIp } = contextOf("0.0.0.0")
+
+        for (let index = 0; index <= 10_000; index += 1) {
+            setIp(`10.${(index >> 16) % 256}.${(index >> 8) % 256}.${index % 256}`)
+            guard.canActivate(context)
+        }
+
+        clock.advance(60_001)
+        setIp("127.0.0.1")
+
+        expect(guard.canActivate(context)).toBe(true)
+        expect(guard.canActivate(context)).toBe(true)
+        expect(() => guard.canActivate(context)).toThrow(RATE_LIMITED)
+    })
+})

package/templates/be/skeleton/src/modules/platform/http-security/request-validation.service.spec.ts

@@ -0,0 +1,39 @@
+import { Test } from "@nestjs/testing"
+import { IsString, MinLength } from "class-validator"
+import { HttpSecurityErrorCode } from "./errors/http-security.error"
+import { RequestValidationService } from "./request-validation.service"
+
+class SignUpBody {
+    @IsString()
+    @MinLength(3)
+    name!: string
+}
+
+describe("RequestValidationService", () => {
+    const build = async (): Promise<RequestValidationService> => {
+        const moduleRef = await Test.createTestingModule({ providers: [RequestValidationService] }).compile()
+        return moduleRef.get(RequestValidationService)
+    }
+    const metadata = { type: "body" as const, metatype: SignUpBody }
+
+    it("returns the body as an instance of its declared class", async () => {
+        const body = await (await build()).transform({ name: "An Nguyen" }, metadata)
+
+        expect(body).toBeInstanceOf(SignUpBody)
+        expect(body).toEqual({ name: "An Nguyen" })
+    })
+
+    it("refuses an unknown property, naming it", async () => {
+        await expect((await build()).transform({ name: "An Nguyen", admin: true }, metadata)).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RequestInvalid,
+            params: { fields: "admin" },
+        })
+    })
+
+    it("refuses an invalid value, naming the offending fields", async () => {
+        await expect((await build()).transform({ name: "A" }, metadata)).rejects.toMatchObject({
+            code: HttpSecurityErrorCode.RequestInvalid,
+            params: { fields: "name" },
+        })
+    })
+})

package/templates/be/skeleton/src/modules/platform/http-security/request-validation.service.ts

@@ -0,0 +1,25 @@
+import { Injectable, ValidationPipe } from "@nestjs/common"
+import type { ValidationError } from "class-validator"
+import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
+
+const fieldsOf = (errors: ReadonlyArray<ValidationError>): string => errors.map((error) => error.property).join(", ")
+
+@Injectable()
+/**
+ * The global validation pipe: unknown properties are refused, values are transformed to their declared types, and a
+ * failure is the capability error naming the offending fields (never Nest's own bad-request exception).
+ */
+export class RequestValidationService extends ValidationPipe {
+    constructor() {
+        super({
+            whitelist: true,
+            forbidNonWhitelisted: true,
+            transform: true,
+            exceptionFactory: (errors: Array<ValidationError>) =>
+                new HttpSecurityError({
+                    code: HttpSecurityErrorCode.RequestInvalid,
+                    params: { fields: fieldsOf(errors) },
+                }),
+        })
+    }
+}

package/templates/be/skeleton/src/modules/platform/http-security/webhook-signature.service.spec.ts

@@ -0,0 +1,172 @@
+import { createHmac } from "node:crypto"
+import { Test } from "@nestjs/testing"
+import { FakeClock } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { Secret } from "@modules/platform/config"
+import { HttpSecurityErrorCode } from "./errors/http-security.error"
+import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
+import type { HttpSecurityOptions } from "./http-security.options"
+import { WebhookSignatureService } from "./webhook-signature.service"
+
+const NOW = "2026-01-01T00:00:00.000Z"
+const SIGNED_AT = Date.parse(NOW)
+const SECRET = "whsec_fixture"
+const BODY = Buffer.from('{"id":"evt_1"}')
+
+const options: HttpSecurityOptions = {
+    allowedOrigins: [],
+    rateLimit: { windowMs: 60_000, defaultLimit: 100, strictLimit: 10 },
+    webhooks: { payments: { secret: new Secret(SECRET), toleranceMs: 300_000 } },
+}
+
+const sign = (timestamp: string, body: Buffer = BODY, secret = SECRET): string =>
+    createHmac("sha256", secret).update(`${timestamp}.`).update(body).digest("hex")
+
+const build = async () => {
+    const clock = new FakeClock(NOW)
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            WebhookSignatureService,
+            { provide: CLOCK, useValue: clock },
+            { provide: HTTP_SECURITY_OPTIONS, useValue: options },
+        ],
+    }).compile()
+    return { service: moduleRef.get(WebhookSignatureService), clock }
+}
+
+const refusal = (code: HttpSecurityErrorCode) => expect.objectContaining({ code })
+
+describe("WebhookSignatureService", () => {
+    describe("verify", () => {
+        it("accepts a current delivery signed with the configured secret", async () => {
+            const { service } = await build()
+            const timestamp = String(SIGNED_AT)
+
+            expect(() =>
+                service.verify({
+                    provider: "payments",
+                    rawBody: BODY,
+                    signature: `sha256=${sign(timestamp)}`,
+                    timestamp,
+                }),
+            ).not.toThrow()
+        })
+
+        it("refuses a provider that is not configured", async () => {
+            const { service } = await build()
+
+            expect(() =>
+                service.verify({
+                    provider: "unknown",
+                    rawBody: BODY,
+                    signature: "sha256=x",
+                    timestamp: "1",
+                }),
+            ).toThrow(refusal(HttpSecurityErrorCode.WebhookProviderUnknown))
+        })
+
+        it.each([
+            {
+                rawBody: undefined,
+                signature: "sha256=x",
+                timestamp: String(SIGNED_AT),
+            },
+            { rawBody: BODY, signature: undefined, timestamp: String(SIGNED_AT) },
+            { rawBody: BODY, signature: "sha256=x", timestamp: undefined },
+            { rawBody: BODY, signature: "sha256=x", timestamp: "yesterday" },
+        ])("refuses a delivery missing a signed part (%#)", async (part) => {
+            const { service } = await build()
+
+            expect(() => service.verify({ provider: "payments", ...part })).toThrow(
+                refusal(HttpSecurityErrorCode.WebhookSignatureInvalid),
+            )
+        })
+
+        it("refuses a signature without the sha256 scheme", async () => {
+            const { service } = await build()
+            const timestamp = String(SIGNED_AT)
+
+            expect(() =>
+                service.verify({
+                    provider: "payments",
+                    rawBody: BODY,
+                    signature: sign(timestamp),
+                    timestamp,
+                }),
+            ).toThrow(refusal(HttpSecurityErrorCode.WebhookSignatureInvalid))
+        })
+
+        it("refuses a signature of another length and one made with another secret", async () => {
+            const { service } = await build()
+            const timestamp = String(SIGNED_AT)
+
+            expect(() =>
+                service.verify({
+                    provider: "payments",
+                    rawBody: BODY,
+                    signature: "sha256=abc",
+                    timestamp,
+                }),
+            ).toThrow(refusal(HttpSecurityErrorCode.WebhookSignatureInvalid))
+            expect(() =>
+                service.verify({
+                    provider: "payments",
+                    rawBody: BODY,
+                    signature: `sha256=${sign(timestamp, BODY, "other")}`,
+                    timestamp,
+                }),
+            ).toThrow(refusal(HttpSecurityErrorCode.WebhookSignatureInvalid))
+        })
+
+        it("refuses a delivery whose body was changed after signing", async () => {
+            const { service } = await build()
+            const timestamp = String(SIGNED_AT)
+
+            expect(() =>
+                service.verify({
+                    provider: "payments",
+                    rawBody: Buffer.from("{}"),
+                    signature: `sha256=${sign(timestamp)}`,
+                    timestamp,
+                }),
+            ).toThrow(refusal(HttpSecurityErrorCode.WebhookSignatureInvalid))
+        })
+
+        it("refuses a correctly signed delivery outside the replay window, in either direction", async () => {
+            const { service } = await build()
+            const stale = String(SIGNED_AT - 300_001)
+            const future = String(SIGNED_AT + 300_001)
+
+            expect(() =>
+                service.verify({
+                    provider: "payments",
+                    rawBody: BODY,
+                    signature: `sha256=${sign(stale)}`,
+                    timestamp: stale,
+                }),
+            ).toThrow(refusal(HttpSecurityErrorCode.WebhookReplayed))
+            expect(() =>
+                service.verify({
+                    provider: "payments",
+                    rawBody: BODY,
+                    signature: `sha256=${sign(future)}`,
+                    timestamp: future,
+                }),
+            ).toThrow(refusal(HttpSecurityErrorCode.WebhookReplayed))
+        })
+
+        it("accepts a delivery exactly at the edge of the replay window", async () => {
+            const { service } = await build()
+            const edge = String(SIGNED_AT - 300_000)
+
+            expect(() =>
+                service.verify({
+                    provider: "payments",
+                    rawBody: BODY,
+                    signature: `sha256=${sign(edge)}`,
+                    timestamp: edge,
+                }),
+            ).not.toThrow()
+        })
+    })
+})

package/templates/be/skeleton/src/modules/platform/http-security/webhook-signature.service.ts

@@ -0,0 +1,66 @@
+import { createHmac, timingSafeEqual } from "node:crypto"
+import { Injectable } from "@nestjs/common"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
+import { InjectHttpSecurityOptions } from "./http-security.decorators"
+import type { HttpSecurityOptions } from "./http-security.options"
+
+/** The exact signed material of one webhook delivery. */
+export interface WebhookDelivery {
+    /** The configured provider whose secret signs this delivery. */
+    readonly provider: string
+    /** The unparsed request bytes covered by the signature. */
+    readonly rawBody: Buffer | undefined
+    /** The provider signature header, when supplied. */
+    readonly signature: string | undefined
+    /** The provider timestamp header used for replay protection, when supplied. */
+    readonly timestamp: string | undefined
+}
+
+const sameDigest = (given: string, expected: string): boolean => {
+    const actual = Buffer.from(given, "utf8")
+    const wanted = Buffer.from(expected, "utf8")
+    return actual.length === wanted.length && timingSafeEqual(actual, wanted)
+}
+
+@Injectable()
+/** Verifies an HMAC-SHA256 over `<timestamp>.<raw body>` and its replay window before any domain intake runs. */
+export class WebhookSignatureService {
+    constructor(
+        @InjectHttpSecurityOptions() private readonly options: HttpSecurityOptions,
+        @InjectClock() private readonly clock: Clock,
+    ) {}
+
+    /** Throws unless the delivery carries a configured provider's current, constant-time-equal signature. */
+    verify(delivery: WebhookDelivery): void {
+        const provider = this.options.webhooks[delivery.provider]
+        if (!provider) {
+            throw new HttpSecurityError({
+                code: HttpSecurityErrorCode.WebhookProviderUnknown,
+                params: { provider: delivery.provider },
+            })
+        }
+        const signedAt = Number(delivery.timestamp)
+        if (!delivery.rawBody || !delivery.signature || !delivery.timestamp || !Number.isFinite(signedAt)) {
+            throw new HttpSecurityError({
+                code: HttpSecurityErrorCode.WebhookSignatureInvalid,
+            })
+        }
+        const expected = createHmac("sha256", provider.secret.reveal())
+            .update(`${delivery.timestamp}.`)
+            .update(delivery.rawBody)
+            .digest("hex")
+        const given = delivery.signature.startsWith("sha256=") ? delivery.signature.slice("sha256=".length) : ""
+        if (!sameDigest(given, expected)) {
+            throw new HttpSecurityError({
+                code: HttpSecurityErrorCode.WebhookSignatureInvalid,
+            })
+        }
+        if (Math.abs(this.clock.now().getTime() - signedAt) > provider.toleranceMs) {
+            throw new HttpSecurityError({
+                code: HttpSecurityErrorCode.WebhookReplayed,
+            })
+        }
+    }
+}

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

@@ -6,6 +6,8 @@ export enum LoggingLogEvent {
     StartupFailed = "server.startup_failed",
     /** The worker started: its jobs are ticking and its consumers are polling. */
     WorkerStarted = "worker.started",
-    /** The migrate app finished; the names of the applied migrations ride in the fields. */
+    /** The cli app's migrate run finished; the names of the applied migrations ride in the fields. */
     MigrationsApplied = "migrations.applied",
+    /** The seed command finished; the seed files it ran ride in the fields, by connection. */
+    SeedsApplied = "seeds.applied",
 }

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

@@ -0,0 +1,52 @@
+import { DomainError } from "@modules/platform/errors"
+import { ok, refused, unwrapOutcome } from "./outcome.mapper"
+
+type CapabilityErrorCode = "CAPABILITY_REFUSED"
+
+class CapabilityError extends DomainError<CapabilityErrorCode> {}
+
+describe("outcome mappers", () => {
+    describe("ok", () => {
+        it("wraps the produced value as a success", () => {
+            const value = { id: "value-1" }
+
+            expect(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({
+                kind: "refused",
+                code: "CAPABILITY_REFUSED",
+                params: { resource: "value-1" },
+            })
+        })
+
+        it("keeps display parameters optional", () => {
+            expect(refused("CAPABILITY_REFUSED")).toEqual({
+                kind: "refused",
+                code: "CAPABILITY_REFUSED",
+                params: undefined,
+            })
+        })
+    })
+
+    describe("unwrapOutcome", () => {
+        it("returns the value of a successful outcome", () => {
+            expect(unwrapOutcome(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" })
+
+            expect(() => unwrapOutcome(outcome, CapabilityError)).toThrow(
+                expect.objectContaining({
+                    name: "CapabilityError",
+                    code: "CAPABILITY_REFUSED",
+                    params: { resource: "value-1" },
+                }),
+            )
+        })
+    })
+})

package/templates/be/skeleton-lite/apps/api/Dockerfile

@@ -0,0 +1,37 @@
+# {{project}}/api - the api app. The build context is the APP ROOT (the folder holding the one package.json and
+# package-lock.json), not this folder:
+#
+#   docker build -f be/apps/api/Dockerfile -t {{project}}/api:<tag> .
+#
+# It follows the image canon and diverges from it nowhere. Credentials are mounted at run time and never enter the image.
+
+FROM node:22.14.0-alpine3.21 AS manifests
+WORKDIR /app
+COPY package.json package-lock.json ./
+COPY fe fe
+RUN find fe -type f ! -name package.json -delete
+
+FROM node:22.14.0-alpine3.21 AS build
+WORKDIR /app
+COPY --from=manifests /app ./
+RUN npm ci --ignore-scripts
+
+COPY be/tsconfig.json be/tsconfig.build.json be/
+COPY be/src be/src
+COPY be/apps/api be/apps/api
+RUN npm run build:be
+
+FROM node:22.14.0-alpine3.21 AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+ENV PORT=3000
+
+COPY --from=manifests /app ./
+RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
+
+COPY --from=build /app/be/dist be/dist
+
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+CMD ["node", "be/dist/apps/api/src/main.js"]

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

@@ -0,0 +1,16 @@
+import type { SupabaseOptions } from "@modules/integrations/supabase"
+import type { ServerOptions } from "@modules/platform/config"
+import type { DatabaseConnectionOptions } from "@modules/platform/database"
+import type { HttpSecurityOptions } from "@modules/platform/http-security"
+
+/** Everything the API needs from its environment, parsed once by `main.ts` and handed to `AppModule.register`. */
+export interface ApiOptions {
+    /** The HTTP listener. */
+    readonly server: ServerOptions
+    /** The origin allowlist and rate limits. */
+    readonly httpSecurity: HttpSecurityOptions
+    /** The least-privilege PostgreSQL connection to the Supabase project. */
+    readonly database: DatabaseConnectionOptions
+    /** Supabase Auth, Storage and token-verification configuration. */
+    readonly supabase: SupabaseOptions
+}

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

@@ -0,0 +1,81 @@
+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 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. */
+export class AppModule {
+    /** Builds the module from options parsed once at boot; nothing here reads the environment. */
+    static register(options: ApiOptions): DynamicModule {
+        const verifyAccessToken = createSupabaseAccessTokenVerifier(options.supabase)
+        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,
+            ],
+            providers: [
+                {
+                    provide: SUPABASE_ADMIN_CLIENT,
+                    useValue: createSupabaseAdminClient(options.supabase),
+                },
+                { provide: SUPABASE_ACCESS_TOKEN_VERIFIER, useValue: verifyAccessToken },
+                { provide: APP_FILTER, useClass: ErrorsFilter },
+                { provide: APP_GUARD, useClass: RateLimitGuard },
+                { provide: APP_GUARD, useClass: OriginGuard },
+                { provide: APP_GUARD, useClass: AuthGuard },
+            ],
+        }
+    }
+}

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

@@ -0,0 +1,34 @@
+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 { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
+import { parseSupabaseConfig } from "@modules/integrations/supabase"
+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 app = await NestFactory.create(AppModule.register(options), { rawBody: true })
+    app.enableCors({ origin: [...options.httpSecurity.allowedOrigins] })
+    app.enableShutdownHooks()
+    app.useGlobalPipes(app.get(RequestValidationService))
+    await app.listen(options.server.port)
+    createJsonLogger(new SystemClockService()).info(LoggingLogEvent.ServerStarted, {
+        service: "api",
+        port: options.server.port,
+    })
+}
+
+bootstrap().catch((error: unknown) => {
+    createJsonLogger(new SystemClockService()).error(LoggingLogEvent.StartupFailed, error, { service: "api" })
+    process.exitCode = 1
+})

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

@@ -0,0 +1,14 @@
+import { ok, refused } from "@modules/platform/primitives"
+import type { Outcome } from "@modules/platform/primitives"
+import { IdentityErrorCode } from "./errors/identity.error"
+import type { Principal } from "@modules/platform/cqrs"
+import type { IdentityAdmission, PublicMetadata } from "./identity.contracts"
+
+/** Admits an explicitly public door or a verified principal; everything else is refused. */
+export const admit = (
+    metadata: PublicMetadata | undefined,
+    principal: Principal | undefined,
+): Outcome<IdentityAdmission, IdentityErrorCode> => {
+    if (metadata !== undefined) return ok(metadata.reason)
+    return principal === undefined ? refused(IdentityErrorCode.Unauthenticated) : ok(principal)
+}