@starci/hfs 4.9.9 → 4.10.0

package/templates/be/patterns/realtime/channel.gateway.spec.ts.tpl

@@ -1,8 +1,8 @@
 import { Test } from "@nestjs/testing"
 import { MESSAGE_MAPPING_METADATA } from "@nestjs/websockets/constants"
 import { @@service@@ } from "@@serviceModule@@"
-import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
-import { SupabaseErrorCode } from "@modules/integrations/supabase"
+import type { VerifyAccessToken } from "@modules/integrations/passport"
+import { PassportErrorCode } from "@modules/integrations/passport"
 import type { Principal } from "@modules/platform/cqrs"
 import { ok, refused } from "@modules/platform/primitives"
 import { REALTIME_HUB } from "@modules/platform/realtime"
@@ -79,7 +79,7 @@ const socketOf = (id: string, auth: Readonly<Record<string, unknown>> = { access
     return { socket, pushed }
 }
 
-const build = async (hub: RealtimeHub, verify: VerifySupabaseAccessToken) => {
+const build = async (hub: RealtimeHub, verify: VerifyAccessToken) => {
     const moduleRef = await Test.createTestingModule({
         imports: [@@Channel@@WebsocketModule.register({ verifyAccessToken: verify })],
     })
@@ -96,7 +96,7 @@ const build = async (hub: RealtimeHub, verify: VerifySupabaseAccessToken) => {
 describe("@@Channel@@Gateway", () => {
     it("builds the topic only from the verified principal, ignoring handshake principal and topic claims", async () => {
         const { hub, topics } = hubAnswering()
-        const verify: VerifySupabaseAccessToken = jest.fn().mockResolvedValue(ok(principal))
+        const verify: VerifyAccessToken = jest.fn().mockResolvedValue(ok(principal))
         const { transport, adapter } = await build(hub, verify)
         const { socket } = socketOf("socket-1", { accessToken: "signed-token", principal: { id: "p-2" }, topic: "foreign" })
 
@@ -111,7 +111,7 @@ describe("@@Channel@@Gateway", () => {
 
     it("isolates another authenticated principal's topic", async () => {
         const { hub, topics } = hubAnswering()
-        const verify: VerifySupabaseAccessToken = jest.fn().mockResolvedValue(ok({ id: "p-2", role: "authenticated" }))
+        const verify: VerifyAccessToken = jest.fn().mockResolvedValue(ok({ id: "p-2", role: "authenticated" }))
         const { transport, adapter } = await build(hub, verify)
         const { socket } = socketOf("socket-2")
 
@@ -126,7 +126,7 @@ describe("@@Channel@@Gateway", () => {
     it("pushes a hub frame automatically and releases the iterator on disconnect", async () => {
         const frame = { id: "x-1" }
         const { hub, released } = hubAnswering(frame)
-        const verify: VerifySupabaseAccessToken = jest.fn().mockResolvedValue(ok(principal))
+        const verify: VerifyAccessToken = jest.fn().mockResolvedValue(ok(principal))
         const { transport, adapter } = await build(hub, verify)
         const { socket, pushed } = socketOf("socket-1")
 
@@ -142,7 +142,7 @@ describe("@@Channel@@Gateway", () => {
 
     it.each([{}, { accessToken: "" }, { accessToken: 42 }])("refuses a missing or malformed access token without invoking the verifier", async (auth) => {
         const { hub, topics } = hubAnswering()
-        const verify: VerifySupabaseAccessToken = jest.fn()
+        const verify: VerifyAccessToken = jest.fn()
         const { adapter } = await build(hub, verify)
         const { socket } = socketOf("socket-1", auth)
         socket.data.principal = principal
@@ -156,7 +156,7 @@ describe("@@Channel@@Gateway", () => {
 
     it("refuses a rejected token and clears a prior principal", async () => {
         const { hub, topics } = hubAnswering()
-        const verify: VerifySupabaseAccessToken = jest.fn().mockResolvedValue(refused(SupabaseErrorCode.AccessTokenInvalid))
+        const verify: VerifyAccessToken = jest.fn().mockResolvedValue(refused(PassportErrorCode.AccessTokenInvalid))
         const { adapter } = await build(hub, verify)
         const { socket } = socketOf("socket-1")
         socket.data.principal = principal

package/templates/be/patterns/realtime/channel.websocket.module.ts.tpl

@@ -1,7 +1,7 @@
 import { Module } from "@nestjs/common"
 import type { OnModuleDestroy, OnModuleInit } from "@nestjs/common"
 import type { @@Channel@@Frame } from "@@serviceModule@@"
-import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import type { VerifyAccessToken } from "@modules/integrations/passport"
 import { injector } from "@modules/platform/composition"
 import type { Principal } from "@modules/platform/cqrs"
 import { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } from "./@@channel@@-websocket.module-definition"
@@ -48,8 +48,8 @@ export class @@Channel@@WebsocketModule extends ConfigurableModuleClass implemen
 
     constructor(
         private readonly gateway: @@Channel@@Gateway,
-        @injector<VerifySupabaseAccessToken>(ACCESS_TOKEN_VERIFIER)
-        private readonly verifyAccessToken: VerifySupabaseAccessToken,
+        @injector<VerifyAccessToken>(ACCESS_TOKEN_VERIFIER)
+        private readonly verifyAccessToken: VerifyAccessToken,
     ) {
         super()
     }

package/templates/be/patterns/realtime/channel.websocket.options.ts.tpl

@@ -1,7 +1,7 @@
-import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import type { VerifyAccessToken } from "@modules/integrations/passport"
 
 /** The options of the @@channel@@ socket transport: the cryptographic verifier that authenticates each connection. */
 export interface @@Channel@@WebsocketOptions {
     /** Verifies the access token of a handshake with the same verifier identity uses. */
-    readonly verifyAccessToken: VerifySupabaseAccessToken
+    readonly verifyAccessToken: VerifyAccessToken
 }

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

@@ -1,14 +1,22 @@
-import { SetMetadata } from "@nestjs/common"
+import { SetMetadata, applyDecorators } from "@nestjs/common"
 import { injector } from "@modules/platform/composition"
-import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { DoorDecorator, TypedParameterDecorator } from "@modules/platform/composition"
+import { ServerToServer } from "@modules/platform/http-security"
 import type { CredentialAuthenticator, CredentialMetadata } from "./credential.contracts"
+import { PublicReason } from "./identity.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 credential or a signed-in caller. */
-export const Public = (metadata: PublicMetadata): ReturnType<typeof SetMetadata> => SetMetadata(PUBLIC_KEY, metadata)
+/**
+ * Opens a door to anonymous callers, stating why; every other door needs a credential or a signed-in caller. A
+ * signed webhook proves its caller by its signature, so it owes no browser origin.
+ */
+export const Public = (metadata: PublicMetadata): DoorDecorator =>
+    metadata.reason === PublicReason.SignedWebhook
+        ? applyDecorators(SetMetadata(PUBLIC_KEY, metadata), ServerToServer())
+        : applyDecorators(SetMetadata(PUBLIC_KEY, metadata))
 
 /** Metadata key of `@Credential`. */
 export const CREDENTIAL_KEY: unique symbol = Symbol("domain.identity.credential")
@@ -20,6 +28,9 @@ export const CREDENTIAL_AUTHENTICATOR: unique symbol = Symbol("domain.identity.c
 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)
+/**
+ * Marks a door authenticated by its own credential; `CredentialGuard` authenticates it and `AuthGuard` admits it. The
+ * credential travels in a header no browser attaches by itself, so the door owes no browser origin.
+ */
+export const Credential = (metadata: CredentialMetadata): DoorDecorator =>
+    applyDecorators(SetMetadata(CREDENTIAL_KEY, metadata), ServerToServer())

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

@@ -8,6 +8,9 @@ export type TypedParameterDecorator<T> = ParameterDecorator & {
     readonly __injects?: T
 }
 
+/** A decorator a door carries on its method or its class; one built from several metadata decorators is typed with it. */
+export type DoorDecorator = MethodDecorator & ClassDecorator
+
 /** Builds the parameter decorator that injects `token`, typed with the value it injects. Every `Inject<Thing>()` is built with it. */
 export const injector = <T>(token: InjectionToken): TypedParameterDecorator<T> => Inject(token)
 

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

@@ -1,2 +1,2 @@
 export { InjectReflector, injector } from "./composition.decorators"
-export type { TypedParameterDecorator } from "./composition.decorators"
+export type { DoorDecorator, TypedParameterDecorator } from "./composition.decorators"

package/templates/be/skeleton/src/modules/platform/errors/errors.filter.spec.ts

@@ -37,7 +37,7 @@ describe("ErrorsFilter", () => {
         const { filter, errors, requestLocale } = await build()
         const failure = new Error("note missing")
         const request = mock<Request>({ headers: { "accept-language": "en-US,en;q=0.9" } })
-        const response = mock<Response>()
+        const response = mock<Response>({ headersSent: false })
         response.status.mockReturnValue(response)
         const http = mock<ReturnType<ArgumentsHost["switchToHttp"]>>()
         http.getRequest.mockReturnValue(request)
@@ -66,4 +66,18 @@ describe("ErrorsFilter", () => {
             params: { noteId: "note-1" },
         })
     })
+
+    it("leaves a response a guard already sent as it is", async () => {
+        const { filter, errors } = await build()
+        const response = mock<Response>({ headersSent: true })
+        const http = mock<ReturnType<ArgumentsHost["switchToHttp"]>>()
+        http.getResponse.mockReturnValue(response)
+        const host = mock<ArgumentsHost>()
+        host.switchToHttp.mockReturnValue(http)
+
+        expect(filter.catch(new Error("rate limited"), host)).toBeUndefined()
+
+        expect(errors.describe).not.toHaveBeenCalled()
+        expect(response.status).not.toHaveBeenCalled()
+    })
 })

package/templates/be/skeleton/src/modules/platform/errors/errors.filter.ts

@@ -9,7 +9,8 @@ import type { ErrorsService } from "./errors.service"
 @Catch()
 /**
  * The one REST exception filter of an app: answers `{ code, kind, message, params }` with the status of the kind. In a GraphQL
- * context it hands the failure back untouched, so the GraphQL error formatter (platform/graphql) answers it.
+ * context it hands the failure back untouched, so the GraphQL error formatter (platform/graphql) answers it. A response a
+ * guard already answered (a redirect-only door over its rate limit) is left as it was sent.
  */
 export class ErrorsFilter implements ExceptionFilter {
     constructor(
@@ -21,17 +22,17 @@ export class ErrorsFilter implements ExceptionFilter {
     catch(exception: unknown, host: ArgumentsHost): unknown {
         if (host.getType<string>() === "graphql") return exception
         const http = host.switchToHttp()
+        const response = http.getResponse<Response>()
+        if (response.headersSent) return undefined
         const request = http.getRequest<Request>()
         const description = this.errors.describe(exception)
         const locale = this.requestLocale.of(request.headers["accept-language"])
-        http.getResponse<Response>()
-            .status(description.status)
-            .json({
-                code: description.code,
-                kind: description.kind,
-                message: this.errors.text(description.code, description.params, locale),
-                params: description.params,
-            })
+        response.status(description.status).json({
+            code: description.code,
+            kind: description.kind,
+            message: this.errors.text(description.code, description.params, locale),
+            params: description.params,
+        })
         return undefined
     }
 }

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

@@ -3,7 +3,7 @@ export { parseHttpSecurityConfig } from "./http-security.config"
 export { HttpSecurityModule } from "./http-security.module"
 export type { HttpSecurityOptions } from "./http-security.options"
 export { HTTP_SECURITY_MESSAGES } from "./messages/http-security.messages"
-export { OriginGuard } from "./origin.guard"
+export { OriginGuard, ServerToServer } from "./origin.guard"
 export { httpSecurityEntities, httpSecurityMigrations } from "./persistence/connection"
 export { requestOf } from "./execution-request.mapper"
 export { RateLimitGuard } from "./rate-limit.guard"

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

@@ -1,11 +1,13 @@
-import type { ExecutionContext } from "@nestjs/common"
+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 { mock } from "@starci/jest-preset"
 import { HttpSecurityErrorCode } from "./errors/http-security.error"
 import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
-import { OriginGuard } from "./origin.guard"
+import { OriginGuard, ServerToServer } from "./origin.guard"
 
 const options: HttpSecurityOptions = {
     allowedOrigins: ["https://app.test"],
@@ -13,49 +15,63 @@ const options: HttpSecurityOptions = {
     webhooks: {},
 }
 
-const build = async (method: string, headers: Request["headers"]) => {
+class OpenDoor {}
+
+class SignedDoor {}
+ServerToServer()(SignedDoor)
+
+const build = async (method: string, headers: Request["headers"], door: Type<unknown> = OpenDoor) => {
     const request = mock<Request>({ headers, method })
     const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
     http.getRequest.mockReturnValue(request)
     const context = mock<ExecutionContext>()
     context.switchToHttp.mockReturnValue(http)
+    context.getHandler.mockReturnValue(() => undefined)
+    context.getClass.mockReturnValue(door)
     const moduleRef = await Test.createTestingModule({
-        providers: [OriginGuard, { provide: HTTP_SECURITY_OPTIONS, useValue: options }],
+        providers: [OriginGuard, Reflector, { provide: HTTP_SECURITY_OPTIONS, useValue: options }],
     }).compile()
     return { guard: moduleRef.get(OriginGuard), context }
 }
 
 describe("OriginGuard", () => {
-    it.each(["GET", "HEAD", "OPTIONS"])("allows the safe %s method regardless of origin", async (method) => {
-        const { guard, context } = await build(method, { origin: "https://foreign.test" })
+    it.each(["GET", "HEAD", "OPTIONS"])("allows the safe %s method without an origin", async (method) => {
+        const { guard, context } = await build(method, {})
 
         expect(guard.canActivate(context)).toBe(true)
     })
 
-    it.each([{}, { referer: "not a URL" }])(
-        "allows a state-changing non-browser request without a usable origin (%o)",
-        async (headers) => {
-            const { guard, context } = await build("POST", headers)
-
-            expect(guard.canActivate(context)).toBe(true)
-        },
-    )
-
     it("allows a state-changing request carrying an allowed Origin header", async () => {
         const { guard, context } = await build("POST", { origin: "https://app.test" })
 
         expect(guard.canActivate(context)).toBe(true)
     })
 
-    it("uses the origin of an allowed Referer URL", async () => {
+    it("falls back to the origin of an allowed Referer when Origin is absent", async () => {
         const { guard, context } = await build("PATCH", { referer: "https://app.test/notes/one" })
 
         expect(guard.canActivate(context)).toBe(true)
     })
 
-    it("refuses a state-changing request from an origin outside the allowlist", async () => {
-        const { guard, context } = await build("DELETE", { origin: "https://foreign.test" })
+    it.each([
+        { name: "no Origin and no Referer", headers: {} },
+        { name: "a Referer that is not a URL", headers: { referer: "not a URL" } },
+        { name: "an Origin outside the allowlist", headers: { origin: "https://foreign.test" } },
+        { name: "the opaque null Origin", headers: { origin: "null" } },
+        { name: "a Referer outside the allowlist", headers: { referer: "https://foreign.test/form" } },
+        {
+            name: "a foreign Origin beside an allowed Referer",
+            headers: { origin: "https://foreign.test", referer: "https://app.test/notes/one" },
+        },
+    ])("refuses a state-changing request with $name", async ({ headers }) => {
+        const { guard, context } = await build("DELETE", headers)
 
         expect(() => guard.canActivate(context)).toThrow(HttpSecurityErrorCode.OriginRejected)
     })
+
+    it("allows a state-changing request without an origin on a door marked server-to-server", async () => {
+        const { guard, context } = await build("POST", {}, SignedDoor)
+
+        expect(guard.canActivate(context)).toBe(true)
+    })
 })

package/templates/be/skeleton/src/modules/platform/http-security/origin.guard.ts

@@ -1,5 +1,7 @@
-import { Injectable } from "@nestjs/common"
+import { Injectable, SetMetadata } from "@nestjs/common"
 import type { CanActivate, ExecutionContext } from "@nestjs/common"
+import type { Reflector } from "@nestjs/core"
+import { InjectReflector } from "@modules/platform/composition"
 import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
 import { requestOf } from "./execution-request.mapper"
 import { InjectHttpSecurityOptions } from "./http-security.decorators"
@@ -7,25 +9,44 @@ import type { HttpSecurityOptions } from "./http-security.options"
 
 const SAFE_METHODS: ReadonlySet<string> = new Set(["GET", "HEAD", "OPTIONS"])
 
+const SERVER_TO_SERVER_KEY = "platform.http-security.server-to-server"
+
+/**
+ * Marks a door whose caller is a server proving itself on every request (a signed webhook, a header credential), so no
+ * browser origin is owed. Applied only by the identity decorators that carry that proof: `@Public({ reason:
+ * PublicReason.SignedWebhook })` and `@Credential({ kind })`.
+ */
+export const ServerToServer = (): ReturnType<typeof SetMetadata> => SetMetadata(SERVER_TO_SERVER_KEY, true)
+
+/** The origin a request names: its Origin header, or the origin of its Referer only when Origin is absent. */
 const originOf = (origin: string | undefined, referer: string | undefined): string | undefined => {
-    if (origin) return origin
-    return referer && URL.canParse(referer) ? new URL(referer).origin : undefined
+    if (origin !== undefined) return origin
+    return referer !== undefined && URL.canParse(referer) ? new URL(referer).origin : undefined
 }
 
 @Injectable()
 /**
- * The second app guard, the CSRF defence: a state-changing request that names an origin (browsers always do) must name
- * an allowed one. A request without Origin and Referer is not a browser and carries no ambient credential, so it passes.
+ * The second app guard, the CSRF defence: a state-changing request must name an allowed origin, by its Origin header or,
+ * when Origin is absent, by its Referer. A request that names none is refused, since a session cookie rides on it
+ * whatever sent it. A door marked `ServerToServer` proves its caller itself and owes no origin.
  */
 export class OriginGuard implements CanActivate {
-    constructor(@InjectHttpSecurityOptions() private readonly options: HttpSecurityOptions) {}
+    constructor(
+        @InjectReflector() private readonly reflector: Reflector,
+        @InjectHttpSecurityOptions() private readonly options: HttpSecurityOptions,
+    ) {}
 
-    /** Refuses a state-changing request from an origin outside the allowlist. */
+    /** Refuses a state-changing request whose origin is missing or outside the allowlist. */
     canActivate(context: ExecutionContext): boolean {
         const request = requestOf(context)
         if (SAFE_METHODS.has(request.method)) return true
+        const exempt = this.reflector.getAllAndOverride<boolean | undefined>(SERVER_TO_SERVER_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ])
+        if (exempt === true) return true
         const origin = originOf(request.headers.origin, request.headers.referer)
-        if (origin === undefined || this.options.allowedOrigins.includes(origin)) return true
+        if (origin !== undefined && this.options.allowedOrigins.includes(origin)) return true
         throw new HttpSecurityError({ code: HttpSecurityErrorCode.OriginRejected })
     }
 }

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

@@ -1,6 +1,6 @@
 import "reflect-metadata"
 import type { ExecutionContext, Type } from "@nestjs/common"
-import type { Request } from "express"
+import type { Request, Response } from "express"
 import { Reflector } from "@nestjs/core"
 import { Test } from "@nestjs/testing"
 import { FakeClock, mock, mockEntityManager } from "@starci/jest-preset"
@@ -12,6 +12,7 @@ import { HTTP_SECURITY_OPTIONS } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
 import { HIT_RATE_WINDOW, PRUNE_RATE_WINDOWS } from "./persistence/rate-limit.sql"
 import { RateLimit, RateLimitGuard, RateTier } from "./rate-limit.guard"
+import type { RateLimitExceeded } from "./rate-limit.guard"
 
 const AT = "2026-02-03T04:05:06.000Z"
 const RESET_AT = "2026-02-03T04:06:06.000Z"
@@ -21,9 +22,11 @@ const options: HttpSecurityOptions = {
     webhooks: {},
 }
 
-const build = async (entityManager: MockEntityManager, tier?: RateTier) => {
+const build = async (entityManager: MockEntityManager, tier?: RateTier, exceeded?: RateLimitExceeded) => {
     const reflector = mock<Reflector>()
-    reflector.getAllAndOverride.mockReturnValue(tier)
+    reflector.getAllAndOverride.mockImplementation((key: unknown) =>
+        key === "platform.http-security.rate-exceeded" ? exceeded : tier,
+    )
     const moduleRef = await Test.createTestingModule({
         providers: [
             RateLimitGuard,
@@ -37,10 +40,17 @@ const build = async (entityManager: MockEntityManager, tier?: RateTier) => {
 }
 
 /** 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 {}) => {
+const contextOf = (
+    ip: string | undefined,
+    handler = () => undefined,
+    door: Type<unknown> = class Door {},
+    response = mock<Response>(),
+) => {
     const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
     http.getRequest.mockImplementation(() => mock<Request>({ headers: {}, method: "POST", ip }))
+    http.getResponse.mockReturnValue(response)
     const context = mock<ExecutionContext>()
+    context.getType.mockReturnValue("http")
     context.switchToHttp.mockReturnValue(http)
     context.getHandler.mockReturnValue(handler)
     context.getClass.mockReturnValue(door)
@@ -66,6 +76,23 @@ describe("RateLimit", () => {
             new Date(RESET_AT),
         ])
     })
+
+    it("marks a redirect-only door with its exceeded redirect beside the tier", () => {
+        class Door {}
+        RateLimit(RateTier.Strict, { redirect: "/sign-in?auth=error" })(Door)
+
+        expect(Reflect.getMetadata("platform.http-security.rate-tier", Door)).toBe(RateTier.Strict)
+        expect(Reflect.getMetadata("platform.http-security.rate-exceeded", Door)).toEqual({
+            redirect: "/sign-in?auth=error",
+        })
+    })
+
+    it.each(["https://foreign.test/sign-in", "//foreign.test/sign-in", "/\\foreign.test", "sign-in"])(
+        "refuses an exceeded redirect %s that is not a same-site path",
+        (redirect) => {
+            expect(() => RateLimit(RateTier.Strict, { redirect })).toThrow(HttpSecurityErrorCode.RequestInvalid)
+        },
+    )
 })
 
 describe("RateLimitGuard", () => {
@@ -135,3 +162,52 @@ describe("RateLimitGuard", () => {
         })
     })
 })
+
+describe("RateLimitGuard on a redirect-only door", () => {
+    const EXCEEDED: RateLimitExceeded = { redirect: "/sign-in?auth=error" }
+
+    /** A response whose redirect is a plain double, so the spec reads the call without the deprecated overload. */
+    const responseOf = () => {
+        const redirect = jest.fn()
+        return { response: mock<Response>({ redirect }), redirect }
+    }
+
+    it("answers the door's own 303 when the caller is over the limit, and still refuses", async () => {
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard } = await build(entityManager, RateTier.Strict, EXCEEDED)
+        const { response, redirect } = responseOf()
+
+        await expect(
+            guard.canActivate(contextOf("127.0.0.1", () => undefined, class Door {}, response)),
+        ).rejects.toMatchObject({ code: HttpSecurityErrorCode.RateLimited })
+        expect(redirect).toHaveBeenCalledWith(303, "/sign-in?auth=error")
+    })
+
+    it("writes no redirect while the caller is under the limit", async () => {
+        const entityManager = mockEntityManager({
+            query: [
+                [HIT_RATE_WINDOW, [{ hits: 1 }]],
+                [PRUNE_RATE_WINDOWS, []],
+            ],
+        })
+        const { guard } = await build(entityManager, RateTier.Strict, EXCEEDED)
+        const { response, redirect } = responseOf()
+
+        await expect(guard.canActivate(contextOf("127.0.0.1", () => undefined, class Door {}, response))).resolves.toBe(
+            true,
+        )
+        expect(redirect).not.toHaveBeenCalled()
+    })
+
+    it("refuses a GraphQL operation over the limit without writing a redirect", async () => {
+        const entityManager = mockEntityManager({ query: [HIT_RATE_WINDOW, [{ hits: 2 }]] })
+        const { guard } = await build(entityManager, RateTier.Strict, EXCEEDED)
+        const { response, redirect } = responseOf()
+        const context = contextOf("127.0.0.1", () => undefined, class Door {}, response)
+        context.getType.mockReturnValue("graphql")
+        context.getArgs.mockReturnValue([{}, {}, { req: mock<Request>({ headers: {}, ip: "127.0.0.1" }) }, {}])
+
+        await expect(guard.canActivate(context)).rejects.toMatchObject({ code: HttpSecurityErrorCode.RateLimited })
+        expect(redirect).not.toHaveBeenCalled()
+    })
+})

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

@@ -1,10 +1,12 @@
-import { Injectable, SetMetadata } from "@nestjs/common"
+import { Injectable, SetMetadata, applyDecorators } from "@nestjs/common"
 import type { CanActivate, ExecutionContext } from "@nestjs/common"
 import type { Reflector } from "@nestjs/core"
+import type { Response } from "express"
 import type { EntityManager } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
 import { InjectReflector } from "@modules/platform/composition"
+import type { DoorDecorator } from "@modules/platform/composition"
 import { InjectPrimaryEntityManager } from "@modules/platform/database"
 import { HttpSecurityError, HttpSecurityErrorCode } from "./errors/http-security.error"
 import { requestOf } from "./execution-request.mapper"
@@ -21,12 +23,34 @@ export enum RateTier {
     Strict = "strict",
 }
 
+/** What a door answers when its caller is over the limit, when that is not the 429 error body. */
+export interface RateLimitExceeded {
+    /** A same-site path the door's own contract answers with a 303 (an OAuth callback's error redirect). */
+    readonly redirect: string
+}
+
 const RATE_TIER_KEY = "platform.http-security.rate-tier"
+const RATE_EXCEEDED_KEY = "platform.http-security.rate-exceeded"
 /** The longest window key the table stores: the tier, a colon and the caller address. */
 const KEY_MAX = 128
 
-/** Marks a door with a rate limit tier other than the default. */
-export const RateLimit = (tier: RateTier): ReturnType<typeof SetMetadata> => SetMetadata(RATE_TIER_KEY, tier)
+/** A same-site path: one leading slash, never a protocol-relative `//` or `/\` that leaves the site. */
+const isSameSitePath = (location: string): boolean =>
+    location.startsWith("/") && !location.startsWith("//") && !location.startsWith("/\\")
+
+/**
+ * Marks a door with a rate limit tier other than the default. A door whose contract answers only redirects (an OAuth
+ * callback) names its error redirect in `exceeded`, and a caller over the limit gets that 303 instead of a 429 body.
+ */
+export const RateLimit = (tier: RateTier, exceeded?: RateLimitExceeded): DoorDecorator => {
+    if (exceeded === undefined) return applyDecorators(SetMetadata(RATE_TIER_KEY, tier))
+    if (!isSameSitePath(exceeded.redirect))
+        throw new HttpSecurityError({
+            code: HttpSecurityErrorCode.RequestInvalid,
+            params: { fields: "RATE_LIMIT_REDIRECT" },
+        })
+    return applyDecorators(SetMetadata(RATE_TIER_KEY, tier), SetMetadata(RATE_EXCEEDED_KEY, exceeded))
+}
 
 @Injectable()
 /**
@@ -42,13 +66,14 @@ export class RateLimitGuard implements CanActivate {
         @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
     ) {}
 
-    /** Counts the request and refuses it when the caller is over the limit of the door tier. */
+    /**
+     * Counts the request and refuses it when the caller is over the limit of the door tier. A door that declares its
+     * exceeded redirect has the 303 written here; the refusal still travels, and the errors filter leaves the sent
+     * response as it is.
+     */
     async canActivate(context: ExecutionContext): Promise<boolean> {
-        const tier =
-            this.reflector.getAllAndOverride<RateTier | undefined>(RATE_TIER_KEY, [
-                context.getHandler(),
-                context.getClass(),
-            ]) ?? RateTier.Default
+        const targets = [context.getHandler(), context.getClass()]
+        const tier = this.reflector.getAllAndOverride<RateTier | undefined>(RATE_TIER_KEY, targets) ?? RateTier.Default
         const limit =
             tier === RateTier.Strict ? this.options.rateLimit.strictLimit : this.options.rateLimit.defaultLimit
         const now = this.clock.now()
@@ -57,7 +82,10 @@ export class RateLimitGuard implements CanActivate {
         const rows: Array<RateWindowRow> = await this.entityManager.query(HIT_RATE_WINDOW, [key, now, resetAt])
         const hits = rows[0]?.hits ?? Number.POSITIVE_INFINITY
         if (hits === 1) await this.entityManager.query(PRUNE_RATE_WINDOWS, [now])
-        if (hits > limit) throw new HttpSecurityError({ code: HttpSecurityErrorCode.RateLimited })
-        return true
+        if (hits <= limit) return true
+        const exceeded = this.reflector.getAllAndOverride<RateLimitExceeded | undefined>(RATE_EXCEEDED_KEY, targets)
+        if (exceeded !== undefined && context.getType() === "http")
+            context.switchToHttp().getResponse<Response>().redirect(303, exceeded.redirect)
+        throw new HttpSecurityError({ code: HttpSecurityErrorCode.RateLimited })
     }
 }

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

@@ -18,7 +18,6 @@ RUN npm ci --ignore-scripts
 
 COPY be/tsconfig.json be/tsconfig.build.json be/
 COPY be/src be/src
-COPY supabase/types supabase/types
 COPY be/apps/api be/apps/api
 RUN npm run build:be
 

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

@@ -2,7 +2,8 @@ import type { EnvSource } from "@modules/platform/config"
 import { parseServerConfig } from "@modules/platform/config"
 import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
 import { parseHttpSecurityConfig } from "@modules/platform/http-security"
-import { parseSupabaseConfig } from "@modules/integrations/supabase"
+import { parsePassportConfig } from "@modules/integrations/passport"
+import { parseObjectStorageConfig } from "@modules/integrations/object-storage"
 
 /** The API environment values required before composition. */
 export interface ApiEnv {
@@ -10,10 +11,12 @@ export interface ApiEnv {
     readonly server: ReturnType<typeof parseServerConfig>
     /** The origin allowlist and rate limits. */
     readonly httpSecurity: ReturnType<typeof parseHttpSecurityConfig>
-    /** The least-privilege PostgreSQL connection to the Supabase project. */
+    /** The least-privilege PostgreSQL connection to the app's own database. */
     readonly database: ReturnType<typeof parsePrimaryDatabaseConfig>
-    /** Supabase Auth, Storage and token-verification configuration. */
-    readonly supabase: ReturnType<typeof parseSupabaseConfig>
+    /** Google OAuth, the app's own access tokens and the refresh cookie. */
+    readonly passport: ReturnType<typeof parsePassportConfig>
+    /** S3-compatible object storage. */
+    readonly objectStorage: ReturnType<typeof parseObjectStorageConfig>
 }
 
 /** Reads the API environment; missing or invalid values fail boot, and secrets use `_FILE` first. */
@@ -21,5 +24,6 @@ export const readApiEnv = (env: EnvSource): ApiEnv => ({
     server: parseServerConfig(env),
     httpSecurity: parseHttpSecurityConfig(env),
     database: parsePrimaryDatabaseConfig(env),
-    supabase: parseSupabaseConfig(env),
+    passport: parsePassportConfig(env),
+    objectStorage: parseObjectStorageConfig(env),
 })