@starci/hfs 4.9.9 → 4.9.11

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/src/modules/domain/identity/identity.decorators.ts

@@ -1,12 +1,13 @@
-import { SetMetadata, createParamDecorator } from "@nestjs/common"
+import { SetMetadata, applyDecorators, createParamDecorator } from "@nestjs/common"
 import type { ExecutionContext } 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 type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
-import { requestOf } from "@modules/platform/http-security"
+import { ServerToServer, requestOf } from "@modules/platform/http-security"
 import type { Principal } from "@modules/platform/cqrs"
 import type { CredentialAuthenticator, CredentialMetadata } from "./credential.contracts"
 import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { PublicReason } from "./identity.contracts"
 import type { PublicMetadata } from "./identity.contracts"
 
 /** Token of the access-token verifier the composition root hands to identity. */
@@ -19,8 +20,14 @@ export const InjectAccessTokenVerifier = (): TypedParameterDecorator<VerifySupab
 /** 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 verified Supabase session. */
-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 verified Supabase session.
+ * 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")
@@ -32,9 +39,12 @@ 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())
 
 /** The authenticated Supabase caller established by the default-deny guard. */
 export const CurrentPrincipal = createParamDecorator((_data: unknown, context: ExecutionContext): Principal => {

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

@@ -4,7 +4,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 { RateLimitGuard } from "./rate-limit.guard"
 export { applyHttpSecurity } from "./edge-security.service"
 export { ReadinessService } from "./readiness.service"