@futdevpro/nts-dynamo 1.15.151 → 1.15.154

package/src/_modules/rate-limit/rate-limit.middleware.ts

@@ -1,504 +1,504 @@
-import { Request, Response } from 'express';
-
-import { DyFM_Error } from '@futdevpro/fsm-dynamo';
-
-import { DyNTS_global_settings } from '../../_collections/global-settings.const';
-import { DyNTS_SingletonServiceBase } from '../../_services/base/singleton.service-base';
-import { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';
-import { DyNTS_RateLimit_Config } from './_models/rate-limit-config.interface';
-import { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
-import { DyNTS_RateLimit_Policy } from './_models/rate-limit-policy.interface';
-import { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
-import { DyNTS_RateLimit_InMemoryStore } from './rate-limit-in-memory.store';
-
-const DEFAULT_LIMIT: number = 100;
-const DEFAULT_WINDOW_MS: number = 60_000;
-const DEFAULT_RESPONSE_HEADERS: boolean = true;
-const MAX_LIMIT: number = 1_000_000;
-const MAX_WINDOW_MS: number = 7 * 24 * 60 * 60 * 1_000;
-const MAX_BUCKET_PART_LENGTH: number = 240;
-const SERVICE_NAME: string = 'DyNTS_RateLimit_Middleware';
-
-interface DyNTS_RateLimit_ErrorContext_Interface {
-  status: number;
-  subcode: string;
-  message: string;
-  userMessage: string;
-}
-
-interface DyNTS_RateLimit_HeaderContext_Interface {
-  policy: DyNTS_RateLimit_Policy;
-  result: DyNTS_RateLimit_ConsumeResult_Interface;
-  now: number;
-}
-
-interface DyNTS_RateLimit_ConfigSnapshot_Interface {
-  defaultLimit: number;
-  defaultWindowMs: number;
-  isResponseHeadersEnabled: boolean;
-  isSharedStoreRequired: boolean;
-  keyExtractor: (req: Request) => string;
-  endpointGrouper: (req: Request) => string;
-  costExtractor: (req: Request) => number;
-  clock: () => number;
-  store: DyNTS_RateLimit_Store_Interface;
-  isKeyExtractorExplicit: boolean;
-  isEndpointGrouperExplicit: boolean;
-  keyPolicies: Map<string, DyNTS_RateLimit_Policy>;
-  endpointPolicies: Map<string, DyNTS_RateLimit_Policy>;
-}
-
-/** Atomic HTTP rate-limit boundary with an explicit shared-store production gate. */
-export class DyNTS_RateLimit_Middleware extends DyNTS_SingletonServiceBase {
-  private defaultLimit: number = DEFAULT_LIMIT;
-  private defaultWindowMs: number = DEFAULT_WINDOW_MS;
-  private isResponseHeadersEnabled: boolean = DEFAULT_RESPONSE_HEADERS;
-  private isSharedStoreRequired: boolean = false;
-  private isKeyExtractorExplicit: boolean = false;
-  private isEndpointGrouperExplicit: boolean = false;
-  private keyExtractor: (req: Request) => string = (req: Request): string => req.ip ?? 'unknown';
-  private endpointGrouper: (req: Request) => string = (req: Request): string => req.path;
-  private costExtractor: (req: Request) => number = (req: Request): number => {
-    void req;
-
-    return 1;
-  };
-  private clock: () => number = (): number => Date.now();
-  private store: DyNTS_RateLimit_Store_Interface = new DyNTS_RateLimit_InMemoryStore();
-  private keyPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map();
-  private endpointPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map();
-
-  /** Returns the process-wide rate-limit middleware. */
-  public static getInstance(): DyNTS_RateLimit_Middleware {
-    return DyNTS_RateLimit_Middleware.getSingletonInstance();
-  }
-
-  /** Applies a validated configuration atomically; invalid settings do not partially mutate the service. */
-  public configure(config: DyNTS_RateLimit_Config): void {
-    const snapshot: DyNTS_RateLimit_ConfigSnapshot_Interface = this.buildConfigSnapshot(config);
-
-    this.defaultLimit = snapshot.defaultLimit;
-    this.defaultWindowMs = snapshot.defaultWindowMs;
-    this.isResponseHeadersEnabled = snapshot.isResponseHeadersEnabled;
-    this.isSharedStoreRequired = snapshot.isSharedStoreRequired;
-    this.keyExtractor = snapshot.keyExtractor;
-    this.endpointGrouper = snapshot.endpointGrouper;
-    this.costExtractor = snapshot.costExtractor;
-    this.clock = snapshot.clock;
-    this.store = snapshot.store;
-    this.isKeyExtractorExplicit = snapshot.isKeyExtractorExplicit;
-    this.isEndpointGrouperExplicit = snapshot.isEndpointGrouperExplicit;
-    this.keyPolicies = snapshot.keyPolicies;
-    this.endpointPolicies = snapshot.endpointPolicies;
-  }
-
-  /** Returns content-free configuration diagnostics. */
-  public getConfig(): {
-    defaultLimit: number;
-    defaultWindowMs: number;
-    responseHeaders: boolean;
-    activeKeyPolicies: number;
-    activeEndpointPolicies: number;
-    trackedStorageKeys: number;
-    storeKind: DyNTS_RateLimitStoreKind_Type;
-    requireSharedStore: boolean;
-    } {
-    return {
-      defaultLimit: this.defaultLimit,
-      defaultWindowMs: this.defaultWindowMs,
-      responseHeaders: this.isResponseHeadersEnabled,
-      activeKeyPolicies: this.keyPolicies.size,
-      activeEndpointPolicies: this.endpointPolicies.size,
-      trackedStorageKeys: this.store instanceof DyNTS_RateLimit_InMemoryStore
-        ? this.store.getTrackedBucketCount()
-        : 0,
-      storeKind: this.store.storeKind,
-      requireSharedStore: this.isSharedStoreRequired,
-    };
-  }
-
-  /** Sets one validated subject policy. */
-  public setPolicyForKey(key: string, policy: DyNTS_RateLimit_Policy): void {
-    this.assertBucketPart(key);
-    this.assertPolicy(policy);
-    this.keyPolicies.set(key, { ...policy });
-  }
-
-  /** Removes one subject policy. */
-  public clearPolicyForKey(key: string): void {
-    this.keyPolicies.delete(key);
-  }
-
-  /** Sets one validated endpoint-group policy. */
-  public setPolicyForEndpoint(endpoint: string, policy: DyNTS_RateLimit_Policy): void {
-    this.assertBucketPart(endpoint);
-    this.assertPolicy(policy);
-    this.endpointPolicies.set(endpoint, { ...policy });
-  }
-
-  /** Removes one endpoint-group policy. */
-  public clearPolicyForEndpoint(endpoint: string): void {
-    this.endpointPolicies.delete(endpoint);
-  }
-
-  /** Atomically consumes one request permit or raises a stable content-free error. */
-  public readonly check = async (req: Request, res: Response): Promise<void> => {
-    const subject: string = this.extractBucketPart(this.keyExtractor, req);
-    const endpoint: string = this.extractBucketPart(this.endpointGrouper, req);
-    const cost: number = this.extractCost(req);
-
-    const policy: DyNTS_RateLimit_Policy = this.keyPolicies.get(subject)
-      ?? this.endpointPolicies.get(endpoint)
-      ?? { limit: this.defaultLimit, windowMs: this.defaultWindowMs };
-
-    this.assertPolicy(policy);
-    this.assertCost(cost, policy);
-
-    const now: number = this.getNow();
-    let result: unknown;
-
-    try {
-      result = await this.store.consume({
-        bucketKey: this.buildBucketKey(subject, endpoint),
-        policy: policy,
-        cost: cost,
-        now: now,
-      });
-    } catch {
-      this.throwRateLimitError({
-        status: 503,
-        subcode: 'STORE_UNAVAILABLE',
-        message: 'The configured rate-limit store could not commit a permit decision.',
-        userMessage: 'Request protection is temporarily unavailable. Please try again later.',
-      });
-    }
-
-    this.assertStoreResult(result, policy, now);
-    this.setResponseHeaders(res, {
-      policy: policy,
-      result: result,
-      now: now,
-    });
-
-    if (!result.allowed) {
-      const retryAfterSeconds: number = this.getRetryAfterSeconds(result.resetAt, now);
-
-      this.throwRateLimitError({
-        status: 429,
-        subcode: 'LIMIT',
-        message: 'The rate-limit policy rejected a request.',
-        userMessage: `Too many requests. Retry after ${retryAfterSeconds} seconds.`,
-      });
-    }
-  };
-
-  /** Performs explicit opportunistic cleanup only for the local test/development store. */
-  public runGc(): void {
-    if (this.store instanceof DyNTS_RateLimit_InMemoryStore) {
-      this.store.cleanup(this.clock());
-    }
-  }
-
-  /** Backward-compatible no-op: this implementation never starts a timer. */
-  public stopGcTimer(): void {}
-
-  /** Resets all state to deterministic local defaults for tests. */
-  public _resetForTesting(): void {
-    this.defaultLimit = DEFAULT_LIMIT;
-    this.defaultWindowMs = DEFAULT_WINDOW_MS;
-    this.isResponseHeadersEnabled = DEFAULT_RESPONSE_HEADERS;
-    this.isSharedStoreRequired = false;
-    this.isKeyExtractorExplicit = false;
-    this.isEndpointGrouperExplicit = false;
-    this.keyExtractor = (req: Request): string => req.ip ?? 'unknown';
-    this.endpointGrouper = (req: Request): string => req.path;
-    this.costExtractor = (req: Request): number => {
-      void req;
-
-      return 1;
-    };
-    this.clock = (): number => Date.now();
-    this.store = new DyNTS_RateLimit_InMemoryStore();
-    this.keyPolicies.clear();
-    this.endpointPolicies.clear();
-  }
-
-  private buildConfigSnapshot(config: DyNTS_RateLimit_Config): DyNTS_RateLimit_ConfigSnapshot_Interface {
-    const defaultLimit: number = config.defaultLimit ?? this.defaultLimit;
-    const defaultWindowMs: number = config.defaultWindowMs ?? this.defaultWindowMs;
-    const store: DyNTS_RateLimit_Store_Interface = config.store ?? this.store;
-    const isSharedStoreRequired: boolean = config.requireSharedStore ?? this.isSharedStoreRequired;
-    const isKeyExtractorExplicit: boolean = config.keyExtractor !== undefined || this.isKeyExtractorExplicit;
-    const isEndpointGrouperExplicit: boolean = config.endpointGrouper !== undefined
-      || this.isEndpointGrouperExplicit;
-    const keyPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map(this.keyPolicies);
-    const endpointPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map(this.endpointPolicies);
-
-    this.assertPolicy({ limit: defaultLimit, windowMs: defaultWindowMs });
-    this.assertConfigurationFunctions(config);
-    this.assertStore(store);
-    this.addInitialPolicies(keyPolicies, config.initialKeyPolicies);
-    this.addInitialPolicies(endpointPolicies, config.initialEndpointPolicies);
-
-    if (
-      isSharedStoreRequired
-      && (
-        store.storeKind !== DyNTS_RateLimitStoreKind_Type.shared
-        || !isKeyExtractorExplicit
-        || !isEndpointGrouperExplicit
-      )
-    ) {
-      this.throwRateLimitError({
-        status: 500,
-        subcode: 'SHARED_STORE_REQUIRED',
-        message: 'Production rate limiting requires a shared store and explicit opaque bucket extractors.',
-        userMessage: 'Request protection is not configured.',
-      });
-    }
-
-    return {
-      defaultLimit: defaultLimit,
-      defaultWindowMs: defaultWindowMs,
-      isResponseHeadersEnabled: config.responseHeaders ?? this.isResponseHeadersEnabled,
-      isSharedStoreRequired: isSharedStoreRequired,
-      keyExtractor: config.keyExtractor ?? this.keyExtractor,
-      endpointGrouper: config.endpointGrouper ?? this.endpointGrouper,
-      costExtractor: config.costExtractor ?? this.costExtractor,
-      clock: config.clock ?? this.clock,
-      store: store,
-      isKeyExtractorExplicit: isKeyExtractorExplicit,
-      isEndpointGrouperExplicit: isEndpointGrouperExplicit,
-      keyPolicies: keyPolicies,
-      endpointPolicies: endpointPolicies,
-    };
-  }
-
-  private addInitialPolicies(
-    target: Map<string, DyNTS_RateLimit_Policy>,
-    policies?: Record<string, DyNTS_RateLimit_Policy>
-  ): void {
-    if (!policies) {
-      return;
-    }
-
-    for (const entry of Object.entries(policies)) {
-      const key: string = entry[0];
-      const policy: DyNTS_RateLimit_Policy = entry[1];
-
-      this.assertBucketPart(key);
-      this.assertPolicy(policy);
-      target.set(key, { ...policy });
-    }
-  }
-
-  private assertPolicy(policy: DyNTS_RateLimit_Policy): void {
-    if (
-      !Number.isSafeInteger(policy.limit)
-      || policy.limit <= 0
-      || policy.limit > MAX_LIMIT
-      || !Number.isSafeInteger(policy.windowMs)
-      || policy.windowMs <= 0
-      || policy.windowMs > MAX_WINDOW_MS
-    ) {
-      this.throwRateLimitError({
-        status: 500,
-        subcode: 'POLICY_INVALID',
-        message: 'A rate-limit policy is outside the supported safety bounds.',
-        userMessage: 'Request protection is not configured.',
-      });
-    }
-  }
-
-  private assertCost(cost: number, policy: DyNTS_RateLimit_Policy): void {
-    if (!Number.isSafeInteger(cost) || cost <= 0 || cost > policy.limit) {
-      this.throwRateLimitError({
-        status: 500,
-        subcode: 'COST_INVALID',
-        message: 'A rate-limit request cost is outside the active policy.',
-        userMessage: 'Request protection is not configured.',
-      });
-    }
-  }
-
-  private assertConfigurationFunctions(config: DyNTS_RateLimit_Config): void {
-    const hasInvalidFunction: boolean = (
-      config.keyExtractor !== undefined && typeof config.keyExtractor !== 'function'
-    ) || (
-      config.endpointGrouper !== undefined && typeof config.endpointGrouper !== 'function'
-    ) || (
-      config.costExtractor !== undefined && typeof config.costExtractor !== 'function'
-    ) || (
-      config.clock !== undefined && typeof config.clock !== 'function'
-    );
-
-    if (hasInvalidFunction) {
-      this.throwRateLimitError({
-        status: 500,
-        subcode: 'CONFIG_INVALID',
-        message: 'A rate-limit configuration callback is invalid.',
-        userMessage: 'Request protection is not configured.',
-      });
-    }
-  }
-
-  private assertStore(store: DyNTS_RateLimit_Store_Interface): void {
-    const hasKnownKind: boolean = store?.storeKind === DyNTS_RateLimitStoreKind_Type.inMemory
-      || store?.storeKind === DyNTS_RateLimitStoreKind_Type.shared;
-
-    if (!hasKnownKind || typeof store.consume !== 'function') {
-      this.throwRateLimitError({
-        status: 500,
-        subcode: 'STORE_INVALID',
-        message: 'The configured rate-limit store does not satisfy the Bedrock contract.',
-        userMessage: 'Request protection is not configured.',
-      });
-    }
-  }
-
-  private extractBucketPart(extractor: (req: Request) => string, req: Request): string {
-    let value: unknown;
-
-    try {
-      value = extractor(req);
-    } catch {
-      value = undefined;
-    }
-
-    if (typeof value !== 'string') {
-      this.throwBucketKeyInvalid();
-    }
-
-    const normalized: string = value.trim();
-
-    this.assertBucketPart(normalized);
-
-    return normalized;
-  }
-
-  private extractCost(req: Request): number {
-    try {
-      return this.costExtractor(req);
-    } catch {
-      this.throwRateLimitError({
-        status: 500,
-        subcode: 'COST_INVALID',
-        message: 'The rate-limit request cost could not be derived.',
-        userMessage: 'Request protection is not configured.',
-      });
-    }
-  }
-
-  private buildBucketKey(subject: string, endpoint: string): string {
-    return `${subject.length}:${subject}${endpoint.length}:${endpoint}`;
-  }
-
-  private getNow(): number {
-    let now: unknown;
-
-    try {
-      now = this.clock();
-    } catch {
-      now = undefined;
-    }
-
-    if (!Number.isSafeInteger(now) || typeof now !== 'number' || now < 0) {
-      this.throwRateLimitError({
-        status: 503,
-        subcode: 'CLOCK_INVALID',
-        message: 'The rate-limit clock returned an invalid timestamp.',
-        userMessage: 'Request protection is temporarily unavailable. Please try again later.',
-      });
-    }
-
-    return now;
-  }
-
-  private assertBucketPart(value: string): void {
-    if (!value || value.length > MAX_BUCKET_PART_LENGTH) {
-      this.throwBucketKeyInvalid();
-    }
-  }
-
-  private throwBucketKeyInvalid(): never {
-    this.throwRateLimitError({
-      status: 500,
-      subcode: 'BUCKET_KEY_INVALID',
-      message: 'A rate-limit bucket component is missing, invalid or too large.',
-      userMessage: 'Request protection is not configured.',
-    });
-  }
-
-  private assertStoreResult(
-    result: unknown,
-    policy: DyNTS_RateLimit_Policy,
-    now: number
-  ): asserts result is DyNTS_RateLimit_ConsumeResult_Interface {
-    const isValid: boolean = typeof result === 'object'
-      && result !== null
-      && 'allowed' in result
-      && 'remaining' in result
-      && 'resetAt' in result
-      && typeof result.allowed === 'boolean'
-      && typeof result.remaining === 'number'
-      && Number.isSafeInteger(result.remaining)
-      && result.remaining >= 0
-      && result.remaining <= policy.limit
-      && typeof result.resetAt === 'number'
-      && Number.isSafeInteger(result.resetAt)
-      && result.resetAt >= now;
-
-    if (!isValid) {
-      this.throwRateLimitError({
-        status: 503,
-        subcode: 'STORE_RESULT_INVALID',
-        message: 'The rate-limit store returned an invalid permit decision.',
-        userMessage: 'Request protection is temporarily unavailable. Please try again later.',
-      });
-    }
-  }
-
-  private setResponseHeaders(
-    res: Response,
-    context: DyNTS_RateLimit_HeaderContext_Interface
-  ): void {
-    if (!this.isResponseHeadersEnabled) {
-      return;
-    }
-
-    const resetSeconds: string = Math.ceil(context.result.resetAt / 1_000).toString();
-
-    res.setHeader('X-RateLimit-Limit', context.policy.limit.toString());
-    res.setHeader('X-RateLimit-Remaining', context.result.remaining.toString());
-    res.setHeader('X-RateLimit-Reset', resetSeconds);
-    res.setHeader('RateLimit-Limit', context.policy.limit.toString());
-    res.setHeader('RateLimit-Remaining', context.result.remaining.toString());
-    res.setHeader(
-      'RateLimit-Reset',
-      Math.max(0, Math.ceil((context.result.resetAt - context.now) / 1_000)).toString()
-    );
-
-    if (!context.result.allowed) {
-      res.setHeader(
-        'Retry-After',
-        this.getRetryAfterSeconds(context.result.resetAt, context.now).toString()
-      );
-    }
-  }
-
-  private getRetryAfterSeconds(resetAt: number, now: number): number {
-    return Math.max(1, Math.ceil((resetAt - now) / 1_000));
-  }
-
-  private throwRateLimitError(context: DyNTS_RateLimit_ErrorContext_Interface): never {
-    const systemShortCode: string = DyNTS_global_settings.systemShortCodeName ?? 'DyNTS';
-
-    throw new DyFM_Error({
-      status: context.status,
-      errorCode: `${systemShortCode}|DyNTS-RL-${context.subcode}`,
-      addECToUserMsg: true,
-      message: context.message,
-      userMessage: context.userMessage,
-      issuerService: SERVICE_NAME,
-    });
-  }
-}
+import { Request, Response } from 'express';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+import { DyNTS_SingletonServiceBase } from '../../_services/base/singleton.service-base';
+import { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';
+import { DyNTS_RateLimit_Config } from './_models/rate-limit-config.interface';
+import { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
+import { DyNTS_RateLimit_Policy } from './_models/rate-limit-policy.interface';
+import { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
+import { DyNTS_RateLimit_InMemoryStore } from './rate-limit-in-memory.store';
+
+const DEFAULT_LIMIT: number = 100;
+const DEFAULT_WINDOW_MS: number = 60_000;
+const DEFAULT_RESPONSE_HEADERS: boolean = true;
+const MAX_LIMIT: number = 1_000_000;
+const MAX_WINDOW_MS: number = 7 * 24 * 60 * 60 * 1_000;
+const MAX_BUCKET_PART_LENGTH: number = 240;
+const SERVICE_NAME: string = 'DyNTS_RateLimit_Middleware';
+
+interface DyNTS_RateLimit_ErrorContext_Interface {
+  status: number;
+  subcode: string;
+  message: string;
+  userMessage: string;
+}
+
+interface DyNTS_RateLimit_HeaderContext_Interface {
+  policy: DyNTS_RateLimit_Policy;
+  result: DyNTS_RateLimit_ConsumeResult_Interface;
+  now: number;
+}
+
+interface DyNTS_RateLimit_ConfigSnapshot_Interface {
+  defaultLimit: number;
+  defaultWindowMs: number;
+  isResponseHeadersEnabled: boolean;
+  isSharedStoreRequired: boolean;
+  keyExtractor: (req: Request) => string;
+  endpointGrouper: (req: Request) => string;
+  costExtractor: (req: Request) => number;
+  clock: () => number;
+  store: DyNTS_RateLimit_Store_Interface;
+  isKeyExtractorExplicit: boolean;
+  isEndpointGrouperExplicit: boolean;
+  keyPolicies: Map<string, DyNTS_RateLimit_Policy>;
+  endpointPolicies: Map<string, DyNTS_RateLimit_Policy>;
+}
+
+/** Atomic HTTP rate-limit boundary with an explicit shared-store production gate. */
+export class DyNTS_RateLimit_Middleware extends DyNTS_SingletonServiceBase {
+  private defaultLimit: number = DEFAULT_LIMIT;
+  private defaultWindowMs: number = DEFAULT_WINDOW_MS;
+  private isResponseHeadersEnabled: boolean = DEFAULT_RESPONSE_HEADERS;
+  private isSharedStoreRequired: boolean = false;
+  private isKeyExtractorExplicit: boolean = false;
+  private isEndpointGrouperExplicit: boolean = false;
+  private keyExtractor: (req: Request) => string = (req: Request): string => req.ip ?? 'unknown';
+  private endpointGrouper: (req: Request) => string = (req: Request): string => req.path;
+  private costExtractor: (req: Request) => number = (req: Request): number => {
+    void req;
+
+    return 1;
+  };
+  private clock: () => number = (): number => Date.now();
+  private store: DyNTS_RateLimit_Store_Interface = new DyNTS_RateLimit_InMemoryStore();
+  private keyPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map();
+  private endpointPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map();
+
+  /** Returns the process-wide rate-limit middleware. */
+  public static getInstance(): DyNTS_RateLimit_Middleware {
+    return DyNTS_RateLimit_Middleware.getSingletonInstance();
+  }
+
+  /** Applies a validated configuration atomically; invalid settings do not partially mutate the service. */
+  public configure(config: DyNTS_RateLimit_Config): void {
+    const snapshot: DyNTS_RateLimit_ConfigSnapshot_Interface = this.buildConfigSnapshot(config);
+
+    this.defaultLimit = snapshot.defaultLimit;
+    this.defaultWindowMs = snapshot.defaultWindowMs;
+    this.isResponseHeadersEnabled = snapshot.isResponseHeadersEnabled;
+    this.isSharedStoreRequired = snapshot.isSharedStoreRequired;
+    this.keyExtractor = snapshot.keyExtractor;
+    this.endpointGrouper = snapshot.endpointGrouper;
+    this.costExtractor = snapshot.costExtractor;
+    this.clock = snapshot.clock;
+    this.store = snapshot.store;
+    this.isKeyExtractorExplicit = snapshot.isKeyExtractorExplicit;
+    this.isEndpointGrouperExplicit = snapshot.isEndpointGrouperExplicit;
+    this.keyPolicies = snapshot.keyPolicies;
+    this.endpointPolicies = snapshot.endpointPolicies;
+  }
+
+  /** Returns content-free configuration diagnostics. */
+  public getConfig(): {
+    defaultLimit: number;
+    defaultWindowMs: number;
+    responseHeaders: boolean;
+    activeKeyPolicies: number;
+    activeEndpointPolicies: number;
+    trackedStorageKeys: number;
+    storeKind: DyNTS_RateLimitStoreKind_Type;
+    requireSharedStore: boolean;
+    } {
+    return {
+      defaultLimit: this.defaultLimit,
+      defaultWindowMs: this.defaultWindowMs,
+      responseHeaders: this.isResponseHeadersEnabled,
+      activeKeyPolicies: this.keyPolicies.size,
+      activeEndpointPolicies: this.endpointPolicies.size,
+      trackedStorageKeys: this.store instanceof DyNTS_RateLimit_InMemoryStore
+        ? this.store.getTrackedBucketCount()
+        : 0,
+      storeKind: this.store.storeKind,
+      requireSharedStore: this.isSharedStoreRequired,
+    };
+  }
+
+  /** Sets one validated subject policy. */
+  public setPolicyForKey(key: string, policy: DyNTS_RateLimit_Policy): void {
+    this.assertBucketPart(key);
+    this.assertPolicy(policy);
+    this.keyPolicies.set(key, { ...policy });
+  }
+
+  /** Removes one subject policy. */
+  public clearPolicyForKey(key: string): void {
+    this.keyPolicies.delete(key);
+  }
+
+  /** Sets one validated endpoint-group policy. */
+  public setPolicyForEndpoint(endpoint: string, policy: DyNTS_RateLimit_Policy): void {
+    this.assertBucketPart(endpoint);
+    this.assertPolicy(policy);
+    this.endpointPolicies.set(endpoint, { ...policy });
+  }
+
+  /** Removes one endpoint-group policy. */
+  public clearPolicyForEndpoint(endpoint: string): void {
+    this.endpointPolicies.delete(endpoint);
+  }
+
+  /** Atomically consumes one request permit or raises a stable content-free error. */
+  public readonly check = async (req: Request, res: Response): Promise<void> => {
+    const subject: string = this.extractBucketPart(this.keyExtractor, req);
+    const endpoint: string = this.extractBucketPart(this.endpointGrouper, req);
+    const cost: number = this.extractCost(req);
+
+    const policy: DyNTS_RateLimit_Policy = this.keyPolicies.get(subject)
+      ?? this.endpointPolicies.get(endpoint)
+      ?? { limit: this.defaultLimit, windowMs: this.defaultWindowMs };
+
+    this.assertPolicy(policy);
+    this.assertCost(cost, policy);
+
+    const now: number = this.getNow();
+    let result: unknown;
+
+    try {
+      result = await this.store.consume({
+        bucketKey: this.buildBucketKey(subject, endpoint),
+        policy: policy,
+        cost: cost,
+        now: now,
+      });
+    } catch {
+      this.throwRateLimitError({
+        status: 503,
+        subcode: 'STORE_UNAVAILABLE',
+        message: 'The configured rate-limit store could not commit a permit decision.',
+        userMessage: 'Request protection is temporarily unavailable. Please try again later.',
+      });
+    }
+
+    this.assertStoreResult(result, policy, now);
+    this.setResponseHeaders(res, {
+      policy: policy,
+      result: result,
+      now: now,
+    });
+
+    if (!result.allowed) {
+      const retryAfterSeconds: number = this.getRetryAfterSeconds(result.resetAt, now);
+
+      this.throwRateLimitError({
+        status: 429,
+        subcode: 'LIMIT',
+        message: 'The rate-limit policy rejected a request.',
+        userMessage: `Too many requests. Retry after ${retryAfterSeconds} seconds.`,
+      });
+    }
+  };
+
+  /** Performs explicit opportunistic cleanup only for the local test/development store. */
+  public runGc(): void {
+    if (this.store instanceof DyNTS_RateLimit_InMemoryStore) {
+      this.store.cleanup(this.clock());
+    }
+  }
+
+  /** Backward-compatible no-op: this implementation never starts a timer. */
+  public stopGcTimer(): void {}
+
+  /** Resets all state to deterministic local defaults for tests. */
+  public _resetForTesting(): void {
+    this.defaultLimit = DEFAULT_LIMIT;
+    this.defaultWindowMs = DEFAULT_WINDOW_MS;
+    this.isResponseHeadersEnabled = DEFAULT_RESPONSE_HEADERS;
+    this.isSharedStoreRequired = false;
+    this.isKeyExtractorExplicit = false;
+    this.isEndpointGrouperExplicit = false;
+    this.keyExtractor = (req: Request): string => req.ip ?? 'unknown';
+    this.endpointGrouper = (req: Request): string => req.path;
+    this.costExtractor = (req: Request): number => {
+      void req;
+
+      return 1;
+    };
+    this.clock = (): number => Date.now();
+    this.store = new DyNTS_RateLimit_InMemoryStore();
+    this.keyPolicies.clear();
+    this.endpointPolicies.clear();
+  }
+
+  private buildConfigSnapshot(config: DyNTS_RateLimit_Config): DyNTS_RateLimit_ConfigSnapshot_Interface {
+    const defaultLimit: number = config.defaultLimit ?? this.defaultLimit;
+    const defaultWindowMs: number = config.defaultWindowMs ?? this.defaultWindowMs;
+    const store: DyNTS_RateLimit_Store_Interface = config.store ?? this.store;
+    const isSharedStoreRequired: boolean = config.requireSharedStore ?? this.isSharedStoreRequired;
+    const isKeyExtractorExplicit: boolean = config.keyExtractor !== undefined || this.isKeyExtractorExplicit;
+    const isEndpointGrouperExplicit: boolean = config.endpointGrouper !== undefined
+      || this.isEndpointGrouperExplicit;
+    const keyPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map(this.keyPolicies);
+    const endpointPolicies: Map<string, DyNTS_RateLimit_Policy> = new Map(this.endpointPolicies);
+
+    this.assertPolicy({ limit: defaultLimit, windowMs: defaultWindowMs });
+    this.assertConfigurationFunctions(config);
+    this.assertStore(store);
+    this.addInitialPolicies(keyPolicies, config.initialKeyPolicies);
+    this.addInitialPolicies(endpointPolicies, config.initialEndpointPolicies);
+
+    if (
+      isSharedStoreRequired
+      && (
+        store.storeKind !== DyNTS_RateLimitStoreKind_Type.shared
+        || !isKeyExtractorExplicit
+        || !isEndpointGrouperExplicit
+      )
+    ) {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'SHARED_STORE_REQUIRED',
+        message: 'Production rate limiting requires a shared store and explicit opaque bucket extractors.',
+        userMessage: 'Request protection is not configured.',
+      });
+    }
+
+    return {
+      defaultLimit: defaultLimit,
+      defaultWindowMs: defaultWindowMs,
+      isResponseHeadersEnabled: config.responseHeaders ?? this.isResponseHeadersEnabled,
+      isSharedStoreRequired: isSharedStoreRequired,
+      keyExtractor: config.keyExtractor ?? this.keyExtractor,
+      endpointGrouper: config.endpointGrouper ?? this.endpointGrouper,
+      costExtractor: config.costExtractor ?? this.costExtractor,
+      clock: config.clock ?? this.clock,
+      store: store,
+      isKeyExtractorExplicit: isKeyExtractorExplicit,
+      isEndpointGrouperExplicit: isEndpointGrouperExplicit,
+      keyPolicies: keyPolicies,
+      endpointPolicies: endpointPolicies,
+    };
+  }
+
+  private addInitialPolicies(
+    target: Map<string, DyNTS_RateLimit_Policy>,
+    policies?: Record<string, DyNTS_RateLimit_Policy>
+  ): void {
+    if (!policies) {
+      return;
+    }
+
+    for (const entry of Object.entries(policies)) {
+      const key: string = entry[0];
+      const policy: DyNTS_RateLimit_Policy = entry[1];
+
+      this.assertBucketPart(key);
+      this.assertPolicy(policy);
+      target.set(key, { ...policy });
+    }
+  }
+
+  private assertPolicy(policy: DyNTS_RateLimit_Policy): void {
+    if (
+      !Number.isSafeInteger(policy.limit)
+      || policy.limit <= 0
+      || policy.limit > MAX_LIMIT
+      || !Number.isSafeInteger(policy.windowMs)
+      || policy.windowMs <= 0
+      || policy.windowMs > MAX_WINDOW_MS
+    ) {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'POLICY_INVALID',
+        message: 'A rate-limit policy is outside the supported safety bounds.',
+        userMessage: 'Request protection is not configured.',
+      });
+    }
+  }
+
+  private assertCost(cost: number, policy: DyNTS_RateLimit_Policy): void {
+    if (!Number.isSafeInteger(cost) || cost <= 0 || cost > policy.limit) {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'COST_INVALID',
+        message: 'A rate-limit request cost is outside the active policy.',
+        userMessage: 'Request protection is not configured.',
+      });
+    }
+  }
+
+  private assertConfigurationFunctions(config: DyNTS_RateLimit_Config): void {
+    const hasInvalidFunction: boolean = (
+      config.keyExtractor !== undefined && typeof config.keyExtractor !== 'function'
+    ) || (
+      config.endpointGrouper !== undefined && typeof config.endpointGrouper !== 'function'
+    ) || (
+      config.costExtractor !== undefined && typeof config.costExtractor !== 'function'
+    ) || (
+      config.clock !== undefined && typeof config.clock !== 'function'
+    );
+
+    if (hasInvalidFunction) {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'CONFIG_INVALID',
+        message: 'A rate-limit configuration callback is invalid.',
+        userMessage: 'Request protection is not configured.',
+      });
+    }
+  }
+
+  private assertStore(store: DyNTS_RateLimit_Store_Interface): void {
+    const hasKnownKind: boolean = store?.storeKind === DyNTS_RateLimitStoreKind_Type.inMemory
+      || store?.storeKind === DyNTS_RateLimitStoreKind_Type.shared;
+
+    if (!hasKnownKind || typeof store.consume !== 'function') {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'STORE_INVALID',
+        message: 'The configured rate-limit store does not satisfy the Bedrock contract.',
+        userMessage: 'Request protection is not configured.',
+      });
+    }
+  }
+
+  private extractBucketPart(extractor: (req: Request) => string, req: Request): string {
+    let value: unknown;
+
+    try {
+      value = extractor(req);
+    } catch {
+      value = undefined;
+    }
+
+    if (typeof value !== 'string') {
+      this.throwBucketKeyInvalid();
+    }
+
+    const normalized: string = value.trim();
+
+    this.assertBucketPart(normalized);
+
+    return normalized;
+  }
+
+  private extractCost(req: Request): number {
+    try {
+      return this.costExtractor(req);
+    } catch {
+      this.throwRateLimitError({
+        status: 500,
+        subcode: 'COST_INVALID',
+        message: 'The rate-limit request cost could not be derived.',
+        userMessage: 'Request protection is not configured.',
+      });
+    }
+  }
+
+  private buildBucketKey(subject: string, endpoint: string): string {
+    return `${subject.length}:${subject}${endpoint.length}:${endpoint}`;
+  }
+
+  private getNow(): number {
+    let now: unknown;
+
+    try {
+      now = this.clock();
+    } catch {
+      now = undefined;
+    }
+
+    if (!Number.isSafeInteger(now) || typeof now !== 'number' || now < 0) {
+      this.throwRateLimitError({
+        status: 503,
+        subcode: 'CLOCK_INVALID',
+        message: 'The rate-limit clock returned an invalid timestamp.',
+        userMessage: 'Request protection is temporarily unavailable. Please try again later.',
+      });
+    }
+
+    return now;
+  }
+
+  private assertBucketPart(value: string): void {
+    if (!value || value.length > MAX_BUCKET_PART_LENGTH) {
+      this.throwBucketKeyInvalid();
+    }
+  }
+
+  private throwBucketKeyInvalid(): never {
+    this.throwRateLimitError({
+      status: 500,
+      subcode: 'BUCKET_KEY_INVALID',
+      message: 'A rate-limit bucket component is missing, invalid or too large.',
+      userMessage: 'Request protection is not configured.',
+    });
+  }
+
+  private assertStoreResult(
+    result: unknown,
+    policy: DyNTS_RateLimit_Policy,
+    now: number
+  ): asserts result is DyNTS_RateLimit_ConsumeResult_Interface {
+    const isValid: boolean = typeof result === 'object'
+      && result !== null
+      && 'allowed' in result
+      && 'remaining' in result
+      && 'resetAt' in result
+      && typeof result.allowed === 'boolean'
+      && typeof result.remaining === 'number'
+      && Number.isSafeInteger(result.remaining)
+      && result.remaining >= 0
+      && result.remaining <= policy.limit
+      && typeof result.resetAt === 'number'
+      && Number.isSafeInteger(result.resetAt)
+      && result.resetAt >= now;
+
+    if (!isValid) {
+      this.throwRateLimitError({
+        status: 503,
+        subcode: 'STORE_RESULT_INVALID',
+        message: 'The rate-limit store returned an invalid permit decision.',
+        userMessage: 'Request protection is temporarily unavailable. Please try again later.',
+      });
+    }
+  }
+
+  private setResponseHeaders(
+    res: Response,
+    context: DyNTS_RateLimit_HeaderContext_Interface
+  ): void {
+    if (!this.isResponseHeadersEnabled) {
+      return;
+    }
+
+    const resetSeconds: string = Math.ceil(context.result.resetAt / 1_000).toString();
+
+    res.setHeader('X-RateLimit-Limit', context.policy.limit.toString());
+    res.setHeader('X-RateLimit-Remaining', context.result.remaining.toString());
+    res.setHeader('X-RateLimit-Reset', resetSeconds);
+    res.setHeader('RateLimit-Limit', context.policy.limit.toString());
+    res.setHeader('RateLimit-Remaining', context.result.remaining.toString());
+    res.setHeader(
+      'RateLimit-Reset',
+      Math.max(0, Math.ceil((context.result.resetAt - context.now) / 1_000)).toString()
+    );
+
+    if (!context.result.allowed) {
+      res.setHeader(
+        'Retry-After',
+        this.getRetryAfterSeconds(context.result.resetAt, context.now).toString()
+      );
+    }
+  }
+
+  private getRetryAfterSeconds(resetAt: number, now: number): number {
+    return Math.max(1, Math.ceil((resetAt - now) / 1_000));
+  }
+
+  private throwRateLimitError(context: DyNTS_RateLimit_ErrorContext_Interface): never {
+    const systemShortCode: string = DyNTS_global_settings.systemShortCodeName ?? 'DyNTS';
+
+    throw new DyFM_Error({
+      status: context.status,
+      errorCode: `${systemShortCode}|DyNTS-RL-${context.subcode}`,
+      addECToUserMsg: true,
+      message: context.message,
+      userMessage: context.userMessage,
+      issuerService: SERVICE_NAME,
+    });
+  }
+}