@futdevpro/nts-dynamo 1.15.151 → 1.15.154

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

@@ -1,488 +1,488 @@
-import { Request, Response } from 'express';
-
-import { DyFM_Error } from '@futdevpro/fsm-dynamo';
-
-import { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';
-import { DyNTS_RateLimit_ConsumeRequest_Interface } from './_models/rate-limit-consume-request.interface';
-import { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
-import { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
-import { DyNTS_RateLimit_InMemoryStore } from './rate-limit-in-memory.store';
-import { DyNTS_RateLimit_Middleware } from './rate-limit.middleware';
-
-interface DyNTS_RateLimit_TestRequestSettings_Interface {
-  ip?: string;
-  path?: string;
-  headers?: Record<string, string>;
-}
-
-interface DyNTS_RateLimit_TestResponse_Interface {
-  response: jasmine.SpyObj<Response>;
-  headers: Record<string, string>;
-}
-
-/** Public constructor only for simulating separate application processes in this spec. */
-class DyNTS_RateLimit_TestMiddleware extends DyNTS_RateLimit_Middleware {
-  /** Creates one isolated middleware instance. */
-  public constructor() {
-    super();
-  }
-}
-
-/** Shared-scope wrapper around one deterministic store instance. */
-class DyNTS_RateLimit_TestSharedStore implements DyNTS_RateLimit_Store_Interface {
-  public readonly storeKind: DyNTS_RateLimitStoreKind_Type = DyNTS_RateLimitStoreKind_Type.shared;
-
-  /** Creates a shared test store over one caller-owned atomic delegate. */
-  public constructor(private readonly delegate: DyNTS_RateLimit_InMemoryStore) {}
-
-  /** Forwards one atomic consume request. */
-  public consume(
-    request: DyNTS_RateLimit_ConsumeRequest_Interface
-  ): Promise<DyNTS_RateLimit_ConsumeResult_Interface> {
-    return this.delegate.consume(request);
-  }
-}
-
-/** Injects a failure containing the raw bucket so middleware redaction can be asserted. */
-class DyNTS_RateLimit_TestFailingStore implements DyNTS_RateLimit_Store_Interface {
-  public readonly storeKind: DyNTS_RateLimitStoreKind_Type = DyNTS_RateLimitStoreKind_Type.shared;
-
-  /** Rejects every consume operation. */
-  public async consume(request: DyNTS_RateLimit_ConsumeRequest_Interface): Promise<never> {
-    throw new Error(`Injected store detail: ${request.bucketKey}`);
-  }
-}
-
-/** Returns a structurally invalid result to verify fail-closed validation. */
-class DyNTS_RateLimit_TestInvalidStore implements DyNTS_RateLimit_Store_Interface {
-  public readonly storeKind: DyNTS_RateLimitStoreKind_Type = DyNTS_RateLimitStoreKind_Type.shared;
-
-  /** Returns an impossible remaining count. */
-  public async consume(
-    request: DyNTS_RateLimit_ConsumeRequest_Interface
-  ): Promise<DyNTS_RateLimit_ConsumeResult_Interface> {
-    return {
-      allowed: true,
-      remaining: request.policy.limit + 1,
-      resetAt: request.now,
-    };
-  }
-}
-
-describe('| DyNTS_RateLimit_Middleware', (): void => {
-  let service: DyNTS_RateLimit_Middleware;
-  let now: number;
-
-  beforeEach((): void => {
-    now = 10_000;
-    service = DyNTS_RateLimit_Middleware.getInstance();
-    service._resetForTesting();
-    service.configure({ clock: (): number => now });
-  });
-
-  afterEach((): void => {
-    service._resetForTesting();
-  });
-
-  it('| returns one process-wide singleton', (): void => {
-    expect(DyNTS_RateLimit_Middleware.getInstance()).toBe(service);
-  });
-
-  it('| uses trusted req.ip by default and ignores a caller-controlled forwarded header', async (): Promise<void> => {
-    service.configure({ defaultLimit: 1, defaultWindowMs: 1_000 });
-
-    await service.check(mockRequest({
-      ip: 'trusted-address',
-      headers: { 'x-forwarded-for': 'spoofed-one' },
-    }), mockResponse().response);
-    const error: DyFM_Error = await captureError((): Promise<void> => service.check(mockRequest({
-      ip: 'trusted-address',
-      headers: { 'x-forwarded-for': 'spoofed-two' },
-    }), mockResponse().response));
-
-    expect(DyFM_Error.getErrorStatus(error)).toBe(429);
-  });
-
-  it('| resets an exact local sliding window without waiting or starting a timer', async (): Promise<void> => {
-    const intervalSpy: jasmine.Spy = spyOn(globalThis, 'setInterval');
-
-    service.configure({ defaultLimit: 1, defaultWindowMs: 1_000 });
-    await service.check(mockRequest(), mockResponse().response);
-    now = 11_001;
-    await service.check(mockRequest(), mockResponse().response);
-
-    expect(intervalSpy).not.toHaveBeenCalled();
-  });
-
-  it('| consumes a validated weighted cost', async (): Promise<void> => {
-    service.configure({
-      defaultLimit: 3,
-      defaultWindowMs: 1_000,
-      costExtractor: costTwo,
-    });
-
-    await service.check(mockRequest(), mockResponse().response);
-    const error: DyFM_Error = await captureError(
-      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
-    );
-
-    expect(DyFM_Error.getErrorCode(error)).toContain('DyNTS-RL-LIMIT');
-  });
-
-  it('| isolates subjects and endpoint groups', async (): Promise<void> => {
-    service.configure({ defaultLimit: 1, defaultWindowMs: 1_000 });
-
-    await service.check(mockRequest({ ip: 'subject-a', path: '/one' }), mockResponse().response);
-    await service.check(mockRequest({ ip: 'subject-b', path: '/one' }), mockResponse().response);
-    await service.check(mockRequest({ ip: 'subject-a', path: '/two' }), mockResponse().response);
-
-    expect(service.getConfig().trackedStorageKeys).toBe(3);
-  });
-
-  it('| length-prefixes bucket components so separator characters cannot collide', async (): Promise<void> => {
-    service.configure({
-      defaultLimit: 1,
-      defaultWindowMs: 1_000,
-      keyExtractor: headerSubject,
-    });
-
-    await service.check(mockRequest({ path: 'c', headers: { 'x-key': 'a|b' } }), mockResponse().response);
-    await service.check(mockRequest({ path: 'b|c', headers: { 'x-key': 'a' } }), mockResponse().response);
-
-    expect(service.getConfig().trackedStorageKeys).toBe(2);
-  });
-
-  it('| emits legacy and standard limit headers from the committed decision', async (): Promise<void> => {
-    const first: DyNTS_RateLimit_TestResponse_Interface = mockResponse();
-    const denied: DyNTS_RateLimit_TestResponse_Interface = mockResponse();
-
-    service.configure({ defaultLimit: 1, defaultWindowMs: 5_000 });
-    await service.check(mockRequest(), first.response);
-    await captureError((): Promise<void> => service.check(mockRequest(), denied.response));
-
-    expect(first.headers['X-RateLimit-Remaining']).toBe('0');
-    expect(first.headers['RateLimit-Limit']).toBe('1');
-    expect(denied.headers['Retry-After']).toBe('5');
-    expect(denied.headers['RateLimit-Remaining']).toBe('0');
-  });
-
-  it('| can disable all response headers', async (): Promise<void> => {
-    const response: DyNTS_RateLimit_TestResponse_Interface = mockResponse();
-
-    service.configure({ responseHeaders: false });
-    await service.check(mockRequest(), response.response);
-
-    expect(response.response.setHeader).not.toHaveBeenCalled();
-  });
-
-  it('| applies subject policy before endpoint policy and supports clearing both', async (): Promise<void> => {
-    service.configure({
-      defaultLimit: 3,
-      defaultWindowMs: 1_000,
-      keyExtractor: (req: Request): string => req.headers['x-key']?.toString() ?? 'anonymous',
-    });
-    service.setPolicyForEndpoint('/strict', { limit: 2, windowMs: 1_000 });
-    service.setPolicyForKey('subject', { limit: 1, windowMs: 1_000 });
-    const request: Request = mockRequest({ path: '/strict', headers: { 'x-key': 'subject' } });
-
-    await service.check(request, mockResponse().response);
-    await captureError((): Promise<void> => service.check(request, mockResponse().response));
-    service.clearPolicyForKey('subject');
-    service.clearPolicyForEndpoint('/strict');
-    now = 11_001;
-    await service.check(request, mockResponse().response);
-    await service.check(request, mockResponse().response);
-    await service.check(request, mockResponse().response);
-
-    expect(service.getConfig().activeKeyPolicies).toBe(0);
-    expect(service.getConfig().activeEndpointPolicies).toBe(0);
-  });
-
-  it('| rejects invalid policy and cost without partially mutating configuration', async (): Promise<void> => {
-    service.configure({ defaultLimit: 4, defaultWindowMs: 2_000 });
-
-    const policyError: DyFM_Error = captureSyncError((): void => service.configure({ defaultLimit: 0 }));
-
-    service.configure({ costExtractor: costFive });
-    const costError: DyFM_Error = await captureError(
-      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
-    );
-
-    expect(DyFM_Error.getErrorCode(policyError)).toContain('POLICY_INVALID');
-    expect(DyFM_Error.getErrorCode(costError)).toContain('COST_INVALID');
-    expect(service.getConfig().defaultLimit).toBe(4);
-  });
-
-  it('| requires a shared store and explicit opaque extractors when production gate is enabled', (): void => {
-    const localError: DyFM_Error = captureSyncError((): void => service.configure({
-      requireSharedStore: true,
-    }));
-    const sharedStore: DyNTS_RateLimit_TestSharedStore = new DyNTS_RateLimit_TestSharedStore(
-      new DyNTS_RateLimit_InMemoryStore()
-    );
-    const extractorError: DyFM_Error = captureSyncError((): void => service.configure({
-      store: sharedStore,
-      requireSharedStore: true,
-    }));
-
-    service.configure({
-      store: sharedStore,
-      requireSharedStore: true,
-      keyExtractor: opaqueSubject,
-      endpointGrouper: loginGroup,
-    });
-
-    expect(DyFM_Error.getErrorCode(localError)).toContain('SHARED_STORE_REQUIRED');
-    expect(DyFM_Error.getErrorCode(extractorError)).toContain('SHARED_STORE_REQUIRED');
-    expect(service.getConfig().storeKind).toBe(DyNTS_RateLimitStoreKind_Type.shared);
-  });
-
-  it('| shares one exact permit budget across two middleware instances', async (): Promise<void> => {
-    const store: DyNTS_RateLimit_TestSharedStore = new DyNTS_RateLimit_TestSharedStore(
-      new DyNTS_RateLimit_InMemoryStore()
-    );
-    const first: DyNTS_RateLimit_TestMiddleware = createSharedMiddleware(store, 20_000);
-    const second: DyNTS_RateLimit_TestMiddleware = createSharedMiddleware(store, 20_000);
-
-    await first.check(mockRequest(), mockResponse().response);
-    await second.check(mockRequest(), mockResponse().response);
-    const error: DyFM_Error = await captureError(
-      (): Promise<void> => first.check(mockRequest(), mockResponse().response)
-    );
-
-    expect(DyFM_Error.getErrorStatus(error)).toBe(429);
-  });
-
-  it('| allows exactly one concurrent request for the final shared permit', async (): Promise<void> => {
-    const store: DyNTS_RateLimit_TestSharedStore = new DyNTS_RateLimit_TestSharedStore(
-      new DyNTS_RateLimit_InMemoryStore()
-    );
-    const first: DyNTS_RateLimit_TestMiddleware = createSharedMiddleware(store, 30_000);
-    const second: DyNTS_RateLimit_TestMiddleware = createSharedMiddleware(store, 30_000);
-
-    await first.check(mockRequest(), mockResponse().response);
-    const results: PromiseSettledResult<void>[] = await Promise.allSettled([
-      first.check(mockRequest(), mockResponse().response),
-      second.check(mockRequest(), mockResponse().response),
-    ]);
-
-    expect(results.filter((result: PromiseSettledResult<void>): boolean => result.status === 'fulfilled').length)
-      .toBe(1);
-    expect(results.filter((result: PromiseSettledResult<void>): boolean => result.status === 'rejected').length)
-      .toBe(1);
-  });
-
-  it('| maps store failure without reflecting the opaque bucket or store exception', async (): Promise<void> => {
-    service.configure({
-      store: new DyNTS_RateLimit_TestFailingStore(),
-      requireSharedStore: true,
-      keyExtractor: rawSensitiveBucket,
-      endpointGrouper: loginGroup,
-    });
-
-    const error: DyFM_Error = await captureError(
-      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
-    );
-    const serialized: string = JSON.stringify(error);
-
-    expect(DyFM_Error.getErrorStatus(error)).toBe(503);
-    expect(DyFM_Error.getErrorCode(error)).toContain('STORE_UNAVAILABLE');
-    expect(serialized).not.toContain('raw-sensitive-bucket');
-    expect(serialized).not.toContain('Injected store detail');
-  });
-
-  it('| rejects an invalid store result fail closed', async (): Promise<void> => {
-    service.configure({
-      store: new DyNTS_RateLimit_TestInvalidStore(),
-      requireSharedStore: true,
-      keyExtractor: opaqueSubject,
-      endpointGrouper: loginGroup,
-    });
-
-    const error: DyFM_Error = await captureError(
-      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
-    );
-
-    expect(DyFM_Error.getErrorCode(error)).toContain('STORE_RESULT_INVALID');
-  });
-
-  it('| maps throwing extractors and invalid clocks to stable content-free errors', async (): Promise<void> => {
-    service.configure({ keyExtractor: throwingBucket });
-    const bucketError: DyFM_Error = await captureError(
-      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
-    );
-
-    service.configure({ keyExtractor: opaqueSubject, clock: invalidClock });
-    const clockError: DyFM_Error = await captureError(
-      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
-    );
-
-    expect(DyFM_Error.getErrorCode(bucketError)).toContain('BUCKET_KEY_INVALID');
-    expect(JSON.stringify(bucketError)).not.toContain('sensitive extractor detail');
-    expect(DyFM_Error.getErrorCode(clockError)).toContain('CLOCK_INVALID');
-  });
-
-  it('| rejects empty or oversized bucket components before store access', async (): Promise<void> => {
-    service.configure({ keyExtractor: emptyBucket });
-    const emptyError: DyFM_Error = await captureError(
-      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
-    );
-
-    service.configure({ keyExtractor: oversizedBucket });
-    const oversizedError: DyFM_Error = await captureError(
-      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
-    );
-
-    expect(DyFM_Error.getErrorCode(emptyError)).toContain('BUCKET_KEY_INVALID');
-    expect(DyFM_Error.getErrorCode(oversizedError)).toContain('BUCKET_KEY_INVALID');
-  });
-
-  it('| performs deterministic explicit cleanup without a background task', async (): Promise<void> => {
-    service.configure({ defaultWindowMs: 100 });
-    await service.check(mockRequest(), mockResponse().response);
-    now = 10_101;
-    service.runGc();
-    service.stopGcTimer();
-
-    expect(service.getConfig().trackedStorageKeys).toBe(0);
-  });
-
-  /** Creates an isolated production-gated middleware over a shared store. */
-  function createSharedMiddleware(
-    store: DyNTS_RateLimit_Store_Interface,
-    fixedNow: number
-  ): DyNTS_RateLimit_TestMiddleware {
-    const middleware: DyNTS_RateLimit_TestMiddleware = new DyNTS_RateLimit_TestMiddleware();
-
-    middleware.configure({
-      defaultLimit: 2,
-      defaultWindowMs: 1_000,
-      store: store,
-      requireSharedStore: true,
-      keyExtractor: opaqueSubject,
-      endpointGrouper: loginGroup,
-      clock: (): number => fixedNow,
-    });
-
-    return middleware;
-  }
-
-  /** Returns a two-permit request cost. */
-  function costTwo(req: Request): number {
-    void req;
-
-    return 2;
-  }
-
-  /** Returns an intentionally invalid five-permit request cost. */
-  function costFive(req: Request): number {
-    void req;
-
-    return 5;
-  }
-
-  /** Returns one opaque subject bucket. */
-  function opaqueSubject(req: Request): string {
-    void req;
-
-    return 'opaque-subject';
-  }
-
-  /** Returns the test subject supplied by the request fixture. */
-  function headerSubject(req: Request): string {
-    return req.headers['x-key']?.toString() ?? 'anonymous';
-  }
-
-  /** Returns one stable endpoint group. */
-  function loginGroup(req: Request): string {
-    void req;
-
-    return 'login';
-  }
-
-  /** Returns a sensitive-looking test key used only for non-reflection evidence. */
-  function rawSensitiveBucket(req: Request): string {
-    void req;
-
-    return 'raw-sensitive-bucket';
-  }
-
-  /** Returns an invalid empty bucket. */
-  function emptyBucket(req: Request): string {
-    void req;
-
-    return '';
-  }
-
-  /** Returns a bucket beyond the Bedrock safety ceiling. */
-  function oversizedBucket(req: Request): string {
-    void req;
-
-    return 'a'.repeat(241);
-  }
-
-  /** Simulates a host extractor failure containing content that must not escape. */
-  function throwingBucket(req: Request): string {
-    void req;
-
-    throw new Error('sensitive extractor detail');
-  }
-
-  /** Returns a timestamp that cannot be used for an atomic store decision. */
-  function invalidClock(): number {
-    return Number.NaN;
-  }
-
-  /** Builds an Express-compatible request spy without a structural type assertion. */
-  function mockRequest(settings: DyNTS_RateLimit_TestRequestSettings_Interface = {}): Request {
-    return jasmine.createSpyObj<Request>('Request', [], {
-      ip: settings.ip ?? 'trusted-address',
-      path: settings.path ?? '/api/test',
-      headers: settings.headers ?? {},
-    });
-  }
-
-  /** Builds a response spy and captures string headers. */
-  function mockResponse(): DyNTS_RateLimit_TestResponse_Interface {
-    const headers: Record<string, string> = {};
-    const response: jasmine.SpyObj<Response> = jasmine.createSpyObj<Response>('Response', [ 'setHeader' ]);
-
-    response.setHeader.and.callFake((name: string, value: string | number | readonly string[]): Response => {
-      headers[name] = Array.isArray(value) ? value.join(',') : value.toString();
-
-      return response;
-    });
-
-    return { response: response, headers: headers };
-  }
-
-  /** Captures one asynchronous Dynamo error. */
-  async function captureError(run: () => Promise<void>): Promise<DyFM_Error> {
-    try {
-      await run();
-    } catch (error: unknown) {
-      if (error instanceof DyFM_Error) {
-        return error;
-      }
-
-      throw error;
-    }
-
-    throw new Error('Expected a DyFM_Error.');
-  }
-
-  /** Captures one synchronous Dynamo error. */
-  function captureSyncError(run: () => void): DyFM_Error {
-    try {
-      run();
-    } catch (error: unknown) {
-      if (error instanceof DyFM_Error) {
-        return error;
-      }
-
-      throw error;
-    }
-
-    throw new Error('Expected a DyFM_Error.');
-  }
-});
+import { Request, Response } from 'express';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';
+import { DyNTS_RateLimit_ConsumeRequest_Interface } from './_models/rate-limit-consume-request.interface';
+import { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
+import { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
+import { DyNTS_RateLimit_InMemoryStore } from './rate-limit-in-memory.store';
+import { DyNTS_RateLimit_Middleware } from './rate-limit.middleware';
+
+interface DyNTS_RateLimit_TestRequestSettings_Interface {
+  ip?: string;
+  path?: string;
+  headers?: Record<string, string>;
+}
+
+interface DyNTS_RateLimit_TestResponse_Interface {
+  response: jasmine.SpyObj<Response>;
+  headers: Record<string, string>;
+}
+
+/** Public constructor only for simulating separate application processes in this spec. */
+class DyNTS_RateLimit_TestMiddleware extends DyNTS_RateLimit_Middleware {
+  /** Creates one isolated middleware instance. */
+  public constructor() {
+    super();
+  }
+}
+
+/** Shared-scope wrapper around one deterministic store instance. */
+class DyNTS_RateLimit_TestSharedStore implements DyNTS_RateLimit_Store_Interface {
+  public readonly storeKind: DyNTS_RateLimitStoreKind_Type = DyNTS_RateLimitStoreKind_Type.shared;
+
+  /** Creates a shared test store over one caller-owned atomic delegate. */
+  public constructor(private readonly delegate: DyNTS_RateLimit_InMemoryStore) {}
+
+  /** Forwards one atomic consume request. */
+  public consume(
+    request: DyNTS_RateLimit_ConsumeRequest_Interface
+  ): Promise<DyNTS_RateLimit_ConsumeResult_Interface> {
+    return this.delegate.consume(request);
+  }
+}
+
+/** Injects a failure containing the raw bucket so middleware redaction can be asserted. */
+class DyNTS_RateLimit_TestFailingStore implements DyNTS_RateLimit_Store_Interface {
+  public readonly storeKind: DyNTS_RateLimitStoreKind_Type = DyNTS_RateLimitStoreKind_Type.shared;
+
+  /** Rejects every consume operation. */
+  public async consume(request: DyNTS_RateLimit_ConsumeRequest_Interface): Promise<never> {
+    throw new Error(`Injected store detail: ${request.bucketKey}`);
+  }
+}
+
+/** Returns a structurally invalid result to verify fail-closed validation. */
+class DyNTS_RateLimit_TestInvalidStore implements DyNTS_RateLimit_Store_Interface {
+  public readonly storeKind: DyNTS_RateLimitStoreKind_Type = DyNTS_RateLimitStoreKind_Type.shared;
+
+  /** Returns an impossible remaining count. */
+  public async consume(
+    request: DyNTS_RateLimit_ConsumeRequest_Interface
+  ): Promise<DyNTS_RateLimit_ConsumeResult_Interface> {
+    return {
+      allowed: true,
+      remaining: request.policy.limit + 1,
+      resetAt: request.now,
+    };
+  }
+}
+
+describe('| DyNTS_RateLimit_Middleware', (): void => {
+  let service: DyNTS_RateLimit_Middleware;
+  let now: number;
+
+  beforeEach((): void => {
+    now = 10_000;
+    service = DyNTS_RateLimit_Middleware.getInstance();
+    service._resetForTesting();
+    service.configure({ clock: (): number => now });
+  });
+
+  afterEach((): void => {
+    service._resetForTesting();
+  });
+
+  it('| returns one process-wide singleton', (): void => {
+    expect(DyNTS_RateLimit_Middleware.getInstance()).toBe(service);
+  });
+
+  it('| uses trusted req.ip by default and ignores a caller-controlled forwarded header', async (): Promise<void> => {
+    service.configure({ defaultLimit: 1, defaultWindowMs: 1_000 });
+
+    await service.check(mockRequest({
+      ip: 'trusted-address',
+      headers: { 'x-forwarded-for': 'spoofed-one' },
+    }), mockResponse().response);
+    const error: DyFM_Error = await captureError((): Promise<void> => service.check(mockRequest({
+      ip: 'trusted-address',
+      headers: { 'x-forwarded-for': 'spoofed-two' },
+    }), mockResponse().response));
+
+    expect(DyFM_Error.getErrorStatus(error)).toBe(429);
+  });
+
+  it('| resets an exact local sliding window without waiting or starting a timer', async (): Promise<void> => {
+    const intervalSpy: jasmine.Spy = spyOn(globalThis, 'setInterval');
+
+    service.configure({ defaultLimit: 1, defaultWindowMs: 1_000 });
+    await service.check(mockRequest(), mockResponse().response);
+    now = 11_001;
+    await service.check(mockRequest(), mockResponse().response);
+
+    expect(intervalSpy).not.toHaveBeenCalled();
+  });
+
+  it('| consumes a validated weighted cost', async (): Promise<void> => {
+    service.configure({
+      defaultLimit: 3,
+      defaultWindowMs: 1_000,
+      costExtractor: costTwo,
+    });
+
+    await service.check(mockRequest(), mockResponse().response);
+    const error: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
+
+    expect(DyFM_Error.getErrorCode(error)).toContain('DyNTS-RL-LIMIT');
+  });
+
+  it('| isolates subjects and endpoint groups', async (): Promise<void> => {
+    service.configure({ defaultLimit: 1, defaultWindowMs: 1_000 });
+
+    await service.check(mockRequest({ ip: 'subject-a', path: '/one' }), mockResponse().response);
+    await service.check(mockRequest({ ip: 'subject-b', path: '/one' }), mockResponse().response);
+    await service.check(mockRequest({ ip: 'subject-a', path: '/two' }), mockResponse().response);
+
+    expect(service.getConfig().trackedStorageKeys).toBe(3);
+  });
+
+  it('| length-prefixes bucket components so separator characters cannot collide', async (): Promise<void> => {
+    service.configure({
+      defaultLimit: 1,
+      defaultWindowMs: 1_000,
+      keyExtractor: headerSubject,
+    });
+
+    await service.check(mockRequest({ path: 'c', headers: { 'x-key': 'a|b' } }), mockResponse().response);
+    await service.check(mockRequest({ path: 'b|c', headers: { 'x-key': 'a' } }), mockResponse().response);
+
+    expect(service.getConfig().trackedStorageKeys).toBe(2);
+  });
+
+  it('| emits legacy and standard limit headers from the committed decision', async (): Promise<void> => {
+    const first: DyNTS_RateLimit_TestResponse_Interface = mockResponse();
+    const denied: DyNTS_RateLimit_TestResponse_Interface = mockResponse();
+
+    service.configure({ defaultLimit: 1, defaultWindowMs: 5_000 });
+    await service.check(mockRequest(), first.response);
+    await captureError((): Promise<void> => service.check(mockRequest(), denied.response));
+
+    expect(first.headers['X-RateLimit-Remaining']).toBe('0');
+    expect(first.headers['RateLimit-Limit']).toBe('1');
+    expect(denied.headers['Retry-After']).toBe('5');
+    expect(denied.headers['RateLimit-Remaining']).toBe('0');
+  });
+
+  it('| can disable all response headers', async (): Promise<void> => {
+    const response: DyNTS_RateLimit_TestResponse_Interface = mockResponse();
+
+    service.configure({ responseHeaders: false });
+    await service.check(mockRequest(), response.response);
+
+    expect(response.response.setHeader).not.toHaveBeenCalled();
+  });
+
+  it('| applies subject policy before endpoint policy and supports clearing both', async (): Promise<void> => {
+    service.configure({
+      defaultLimit: 3,
+      defaultWindowMs: 1_000,
+      keyExtractor: (req: Request): string => req.headers['x-key']?.toString() ?? 'anonymous',
+    });
+    service.setPolicyForEndpoint('/strict', { limit: 2, windowMs: 1_000 });
+    service.setPolicyForKey('subject', { limit: 1, windowMs: 1_000 });
+    const request: Request = mockRequest({ path: '/strict', headers: { 'x-key': 'subject' } });
+
+    await service.check(request, mockResponse().response);
+    await captureError((): Promise<void> => service.check(request, mockResponse().response));
+    service.clearPolicyForKey('subject');
+    service.clearPolicyForEndpoint('/strict');
+    now = 11_001;
+    await service.check(request, mockResponse().response);
+    await service.check(request, mockResponse().response);
+    await service.check(request, mockResponse().response);
+
+    expect(service.getConfig().activeKeyPolicies).toBe(0);
+    expect(service.getConfig().activeEndpointPolicies).toBe(0);
+  });
+
+  it('| rejects invalid policy and cost without partially mutating configuration', async (): Promise<void> => {
+    service.configure({ defaultLimit: 4, defaultWindowMs: 2_000 });
+
+    const policyError: DyFM_Error = captureSyncError((): void => service.configure({ defaultLimit: 0 }));
+
+    service.configure({ costExtractor: costFive });
+    const costError: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
+
+    expect(DyFM_Error.getErrorCode(policyError)).toContain('POLICY_INVALID');
+    expect(DyFM_Error.getErrorCode(costError)).toContain('COST_INVALID');
+    expect(service.getConfig().defaultLimit).toBe(4);
+  });
+
+  it('| requires a shared store and explicit opaque extractors when production gate is enabled', (): void => {
+    const localError: DyFM_Error = captureSyncError((): void => service.configure({
+      requireSharedStore: true,
+    }));
+    const sharedStore: DyNTS_RateLimit_TestSharedStore = new DyNTS_RateLimit_TestSharedStore(
+      new DyNTS_RateLimit_InMemoryStore()
+    );
+    const extractorError: DyFM_Error = captureSyncError((): void => service.configure({
+      store: sharedStore,
+      requireSharedStore: true,
+    }));
+
+    service.configure({
+      store: sharedStore,
+      requireSharedStore: true,
+      keyExtractor: opaqueSubject,
+      endpointGrouper: loginGroup,
+    });
+
+    expect(DyFM_Error.getErrorCode(localError)).toContain('SHARED_STORE_REQUIRED');
+    expect(DyFM_Error.getErrorCode(extractorError)).toContain('SHARED_STORE_REQUIRED');
+    expect(service.getConfig().storeKind).toBe(DyNTS_RateLimitStoreKind_Type.shared);
+  });
+
+  it('| shares one exact permit budget across two middleware instances', async (): Promise<void> => {
+    const store: DyNTS_RateLimit_TestSharedStore = new DyNTS_RateLimit_TestSharedStore(
+      new DyNTS_RateLimit_InMemoryStore()
+    );
+    const first: DyNTS_RateLimit_TestMiddleware = createSharedMiddleware(store, 20_000);
+    const second: DyNTS_RateLimit_TestMiddleware = createSharedMiddleware(store, 20_000);
+
+    await first.check(mockRequest(), mockResponse().response);
+    await second.check(mockRequest(), mockResponse().response);
+    const error: DyFM_Error = await captureError(
+      (): Promise<void> => first.check(mockRequest(), mockResponse().response)
+    );
+
+    expect(DyFM_Error.getErrorStatus(error)).toBe(429);
+  });
+
+  it('| allows exactly one concurrent request for the final shared permit', async (): Promise<void> => {
+    const store: DyNTS_RateLimit_TestSharedStore = new DyNTS_RateLimit_TestSharedStore(
+      new DyNTS_RateLimit_InMemoryStore()
+    );
+    const first: DyNTS_RateLimit_TestMiddleware = createSharedMiddleware(store, 30_000);
+    const second: DyNTS_RateLimit_TestMiddleware = createSharedMiddleware(store, 30_000);
+
+    await first.check(mockRequest(), mockResponse().response);
+    const results: PromiseSettledResult<void>[] = await Promise.allSettled([
+      first.check(mockRequest(), mockResponse().response),
+      second.check(mockRequest(), mockResponse().response),
+    ]);
+
+    expect(results.filter((result: PromiseSettledResult<void>): boolean => result.status === 'fulfilled').length)
+      .toBe(1);
+    expect(results.filter((result: PromiseSettledResult<void>): boolean => result.status === 'rejected').length)
+      .toBe(1);
+  });
+
+  it('| maps store failure without reflecting the opaque bucket or store exception', async (): Promise<void> => {
+    service.configure({
+      store: new DyNTS_RateLimit_TestFailingStore(),
+      requireSharedStore: true,
+      keyExtractor: rawSensitiveBucket,
+      endpointGrouper: loginGroup,
+    });
+
+    const error: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
+    const serialized: string = JSON.stringify(error);
+
+    expect(DyFM_Error.getErrorStatus(error)).toBe(503);
+    expect(DyFM_Error.getErrorCode(error)).toContain('STORE_UNAVAILABLE');
+    expect(serialized).not.toContain('raw-sensitive-bucket');
+    expect(serialized).not.toContain('Injected store detail');
+  });
+
+  it('| rejects an invalid store result fail closed', async (): Promise<void> => {
+    service.configure({
+      store: new DyNTS_RateLimit_TestInvalidStore(),
+      requireSharedStore: true,
+      keyExtractor: opaqueSubject,
+      endpointGrouper: loginGroup,
+    });
+
+    const error: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
+
+    expect(DyFM_Error.getErrorCode(error)).toContain('STORE_RESULT_INVALID');
+  });
+
+  it('| maps throwing extractors and invalid clocks to stable content-free errors', async (): Promise<void> => {
+    service.configure({ keyExtractor: throwingBucket });
+    const bucketError: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
+
+    service.configure({ keyExtractor: opaqueSubject, clock: invalidClock });
+    const clockError: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
+
+    expect(DyFM_Error.getErrorCode(bucketError)).toContain('BUCKET_KEY_INVALID');
+    expect(JSON.stringify(bucketError)).not.toContain('sensitive extractor detail');
+    expect(DyFM_Error.getErrorCode(clockError)).toContain('CLOCK_INVALID');
+  });
+
+  it('| rejects empty or oversized bucket components before store access', async (): Promise<void> => {
+    service.configure({ keyExtractor: emptyBucket });
+    const emptyError: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
+
+    service.configure({ keyExtractor: oversizedBucket });
+    const oversizedError: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
+
+    expect(DyFM_Error.getErrorCode(emptyError)).toContain('BUCKET_KEY_INVALID');
+    expect(DyFM_Error.getErrorCode(oversizedError)).toContain('BUCKET_KEY_INVALID');
+  });
+
+  it('| performs deterministic explicit cleanup without a background task', async (): Promise<void> => {
+    service.configure({ defaultWindowMs: 100 });
+    await service.check(mockRequest(), mockResponse().response);
+    now = 10_101;
+    service.runGc();
+    service.stopGcTimer();
+
+    expect(service.getConfig().trackedStorageKeys).toBe(0);
+  });
+
+  /** Creates an isolated production-gated middleware over a shared store. */
+  function createSharedMiddleware(
+    store: DyNTS_RateLimit_Store_Interface,
+    fixedNow: number
+  ): DyNTS_RateLimit_TestMiddleware {
+    const middleware: DyNTS_RateLimit_TestMiddleware = new DyNTS_RateLimit_TestMiddleware();
+
+    middleware.configure({
+      defaultLimit: 2,
+      defaultWindowMs: 1_000,
+      store: store,
+      requireSharedStore: true,
+      keyExtractor: opaqueSubject,
+      endpointGrouper: loginGroup,
+      clock: (): number => fixedNow,
+    });
+
+    return middleware;
+  }
+
+  /** Returns a two-permit request cost. */
+  function costTwo(req: Request): number {
+    void req;
+
+    return 2;
+  }
+
+  /** Returns an intentionally invalid five-permit request cost. */
+  function costFive(req: Request): number {
+    void req;
+
+    return 5;
+  }
+
+  /** Returns one opaque subject bucket. */
+  function opaqueSubject(req: Request): string {
+    void req;
+
+    return 'opaque-subject';
+  }
+
+  /** Returns the test subject supplied by the request fixture. */
+  function headerSubject(req: Request): string {
+    return req.headers['x-key']?.toString() ?? 'anonymous';
+  }
+
+  /** Returns one stable endpoint group. */
+  function loginGroup(req: Request): string {
+    void req;
+
+    return 'login';
+  }
+
+  /** Returns a sensitive-looking test key used only for non-reflection evidence. */
+  function rawSensitiveBucket(req: Request): string {
+    void req;
+
+    return 'raw-sensitive-bucket';
+  }
+
+  /** Returns an invalid empty bucket. */
+  function emptyBucket(req: Request): string {
+    void req;
+
+    return '';
+  }
+
+  /** Returns a bucket beyond the Bedrock safety ceiling. */
+  function oversizedBucket(req: Request): string {
+    void req;
+
+    return 'a'.repeat(241);
+  }
+
+  /** Simulates a host extractor failure containing content that must not escape. */
+  function throwingBucket(req: Request): string {
+    void req;
+
+    throw new Error('sensitive extractor detail');
+  }
+
+  /** Returns a timestamp that cannot be used for an atomic store decision. */
+  function invalidClock(): number {
+    return Number.NaN;
+  }
+
+  /** Builds an Express-compatible request spy without a structural type assertion. */
+  function mockRequest(settings: DyNTS_RateLimit_TestRequestSettings_Interface = {}): Request {
+    return jasmine.createSpyObj<Request>('Request', [], {
+      ip: settings.ip ?? 'trusted-address',
+      path: settings.path ?? '/api/test',
+      headers: settings.headers ?? {},
+    });
+  }
+
+  /** Builds a response spy and captures string headers. */
+  function mockResponse(): DyNTS_RateLimit_TestResponse_Interface {
+    const headers: Record<string, string> = {};
+    const response: jasmine.SpyObj<Response> = jasmine.createSpyObj<Response>('Response', [ 'setHeader' ]);
+
+    response.setHeader.and.callFake((name: string, value: string | number | readonly string[]): Response => {
+      headers[name] = Array.isArray(value) ? value.join(',') : value.toString();
+
+      return response;
+    });
+
+    return { response: response, headers: headers };
+  }
+
+  /** Captures one asynchronous Dynamo error. */
+  async function captureError(run: () => Promise<void>): Promise<DyFM_Error> {
+    try {
+      await run();
+    } catch (error: unknown) {
+      if (error instanceof DyFM_Error) {
+        return error;
+      }
+
+      throw error;
+    }
+
+    throw new Error('Expected a DyFM_Error.');
+  }
+
+  /** Captures one synchronous Dynamo error. */
+  function captureSyncError(run: () => void): DyFM_Error {
+    try {
+      run();
+    } catch (error: unknown) {
+      if (error instanceof DyFM_Error) {
+        return error;
+      }
+
+      throw error;
+    }
+
+    throw new Error('Expected a DyFM_Error.');
+  }
+});