@futdevpro/nts-dynamo 1.15.145 → 1.15.150

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

@@ -2,263 +2,487 @@ 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';
 
-
-/** Test-only — minimal Request mock-ot ad vissza. */
-const mockReq = (overrides: Partial<{ ip: string; path: string; headers: Record<string, string> }> = {}): Request => {
-  return {
-    ip:      overrides.ip ?? '127.0.0.1',
-    path:    overrides.path ?? '/api/test',
-    headers: overrides.headers ?? {},
-  } as unknown as Request;
-};
-
-/** Test-only — Response stub a setHeader-rel. */
-const mockRes = (): Response & { _headers: Record<string, string> } => {
-  const headers: Record<string, string> = {};
-  return {
-    _headers: headers,
-    setHeader: function(name: string, value: string): void {
-      headers[name] = value;
-    },
-  } as unknown as Response & { _headers: Record<string, string> };
-};
-
+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 svc: DyNTS_RateLimit_Middleware;
+  let service: DyNTS_RateLimit_Middleware;
+  let now: number;
 
   beforeEach((): void => {
-    svc = DyNTS_RateLimit_Middleware.getInstance();
-    svc._resetForTesting();
+    now = 10_000;
+    service = DyNTS_RateLimit_Middleware.getInstance();
+    service._resetForTesting();
+    service.configure({ clock: (): number => now });
   });
 
   afterEach((): void => {
-    svc._resetForTesting();
+    service._resetForTesting();
   });
 
+  it('| returns one process-wide singleton', (): void => {
+    expect(DyNTS_RateLimit_Middleware.getInstance()).toBe(service);
+  });
 
-  describe('| singleton', (): void => {
-    it('| ugyanazt az instance-t adja vissza', (): void => {
-      const a: DyNTS_RateLimit_Middleware = DyNTS_RateLimit_Middleware.getInstance();
-      const b: DyNTS_RateLimit_Middleware = DyNTS_RateLimit_Middleware.getInstance();
-      expect(a).toBe(b);
-    });
+  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();
+  });
 
-  describe('| check() — default limit', (): void => {
-    it('| atengedi az elso request-et', async (): Promise<void> => {
-      let thrown: any = null;
-      try { await svc.check(mockReq(), mockRes()); } catch (e) { thrown = e; }
-      expect(thrown).toBeNull();
+  it('| consumes a validated weighted cost', async (): Promise<void> => {
+    service.configure({
+      defaultLimit: 3,
+      defaultWindowMs: 1_000,
+      costExtractor: costTwo,
     });
 
-    it('| 429 amikor a limit-et eleri', async (): Promise<void> => {
-      svc.configure({ defaultLimit: 3, defaultWindowMs: 10000 });
+    await service.check(mockRequest(), mockResponse().response);
+    const error: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
 
-      // 3 sikeres request a limit-en belul
-      await svc.check(mockReq(), mockRes());
-      await svc.check(mockReq(), mockRes());
-      await svc.check(mockReq(), mockRes());
+    expect(DyFM_Error.getErrorCode(error)).toContain('DyNTS-RL-LIMIT');
+  });
 
-      // 4. request: 429
-      let thrown: any = null;
-      try { await svc.check(mockReq(), mockRes()); } catch (e) { thrown = e; }
-      expect(thrown).not.toBeNull();
-      expect(DyFM_Error.getErrorStatus(thrown)).toBe(429);
-      expect(DyFM_Error.getErrorCode(thrown)).toContain('DyNTS-RL-LIMIT');
-    });
+  it('| isolates subjects and endpoint groups', async (): Promise<void> => {
+    service.configure({ defaultLimit: 1, defaultWindowMs: 1_000 });
 
-    it('| kulonbozo IP-k kulon vodorbe kerulnek', async (): Promise<void> => {
-      svc.configure({ defaultLimit: 2, defaultWindowMs: 10000 });
+    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);
 
-      await svc.check(mockReq({ ip: '1.1.1.1' }), mockRes());
-      await svc.check(mockReq({ ip: '1.1.1.1' }), mockRes());
-      // 1.1.1.1 most a limit-en van; 2.2.2.2 meg friss
-      let thrown: any = null;
-      try { await svc.check(mockReq({ ip: '2.2.2.2' }), mockRes()); } catch (e) { thrown = e; }
-      expect(thrown).toBeNull();
+    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,
     });
 
-    it('| kulonbozo endpoint-ok kulon vodorbe kerulnek', async (): Promise<void> => {
-      svc.configure({ defaultLimit: 2, defaultWindowMs: 10000 });
+    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);
 
-      await svc.check(mockReq({ path: '/api/a' }), mockRes());
-      await svc.check(mockReq({ path: '/api/a' }), mockRes());
-      // /api/a most a limit-en van; /api/b meg friss
-      let thrown: any = null;
-      try { await svc.check(mockReq({ path: '/api/b' }), mockRes()); } catch (e) { thrown = e; }
-      expect(thrown).toBeNull();
-    });
+    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();
 
-  describe('| response headers', (): void => {
-    it('| beallitja az X-RateLimit-* header-eket sikeres request-nel', async (): Promise<void> => {
-      svc.configure({ defaultLimit: 10, defaultWindowMs: 60000 });
-      const res = mockRes();
-      await svc.check(mockReq(), res);
-      expect(res._headers['X-RateLimit-Limit']).toBe('10');
-      expect(res._headers['X-RateLimit-Remaining']).toBe('9');
-      expect(res._headers['X-RateLimit-Reset']).toBeDefined();
-    });
+    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('| beallitja a Retry-After header-t 429-nel', async (): Promise<void> => {
-      svc.configure({ defaultLimit: 1, defaultWindowMs: 10000 });
-      await svc.check(mockReq(), mockRes());
+  it('| can disable all response headers', async (): Promise<void> => {
+    const response: DyNTS_RateLimit_TestResponse_Interface = mockResponse();
 
-      const res = mockRes();
-      let thrown: any = null;
-      try { await svc.check(mockReq(), res); } catch (e) { thrown = e; }
-      expect(thrown).not.toBeNull();
-      expect(res._headers['Retry-After']).toBeDefined();
-      expect(res._headers['X-RateLimit-Remaining']).toBe('0');
-    });
+    service.configure({ responseHeaders: false });
+    await service.check(mockRequest(), response.response);
 
-    it('| nem allit be header-t ha responseHeaders=false', async (): Promise<void> => {
-      svc.configure({ defaultLimit: 10, defaultWindowMs: 60000, responseHeaders: false });
-      const res = mockRes();
-      await svc.check(mockReq(), res);
-      expect(res._headers['X-RateLimit-Limit']).toBeUndefined();
+    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 });
 
-  describe('| setPolicyForKey() — subscription-tier-up', (): void => {
-    it('| egyedi limit a kulcsra felulhatja a default-ot', async (): Promise<void> => {
-      svc.configure({
-        defaultLimit:    2,
-        defaultWindowMs: 10000,
-        keyExtractor:    (req: Request): string => (req.headers['x-api-key'] as string) ?? req.ip ?? 'anon',
-      });
-      svc.setPolicyForKey('premium-key', { limit: 10, windowMs: 10000 });
+    const policyError: DyFM_Error = captureSyncError((): void => service.configure({ defaultLimit: 0 }));
 
-      // premium-key 10-et kap
-      for (let i: number = 0; i < 10; i++) {
-        await svc.check(mockReq({ headers: { 'x-api-key': 'premium-key' } }), mockRes());
-      }
-      let thrown: any = null;
-      try { await svc.check(mockReq({ headers: { 'x-api-key': 'premium-key' } }), mockRes()); } catch (e) { thrown = e; }
-      expect(thrown).not.toBeNull();
-      expect(DyFM_Error.getErrorStatus(thrown)).toBe(429);
-    });
+    service.configure({ costExtractor: costFive });
+    const costError: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
 
-    it('| clearPolicyForKey visszaallit a default-ra', async (): Promise<void> => {
-      svc.configure({
-        defaultLimit:    1,
-        defaultWindowMs: 10000,
-        keyExtractor:    (req: Request): string => (req.headers['x-api-key'] as string) ?? 'anon',
-      });
-      svc.setPolicyForKey('k1', { limit: 5, windowMs: 10000 });
-      svc.clearPolicyForKey('k1');
-
-      // most a default 1-es limit ervenyes
-      await svc.check(mockReq({ headers: { 'x-api-key': 'k1' } }), mockRes());
-      let thrown: any = null;
-      try { await svc.check(mockReq({ headers: { 'x-api-key': 'k1' } }), mockRes()); } catch (e) { thrown = e; }
-      expect(thrown).not.toBeNull();
+    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);
 
-  describe('| setPolicyForEndpoint() — per-endpoint limit', (): void => {
-    it('| egyedi limit az endpointra felulhatja a default-ot, mas endpoint nem erintett', async (): Promise<void> => {
-      svc.configure({ defaultLimit: 2, defaultWindowMs: 10000 });
-      svc.setPolicyForEndpoint('/webhook', { limit: 5, windowMs: 10000 });
+    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)
+    );
 
-      // /webhook 5-ot kap a default 2 helyett
-      for (let i: number = 0; i < 5; i++) {
-        await svc.check(mockReq({ path: '/webhook' }), mockRes());
-      }
-      let webhookThrown: any = null;
-      try { await svc.check(mockReq({ path: '/webhook' }), mockRes()); } catch (e) { webhookThrown = e; }
-      expect(webhookThrown).not.toBeNull();
-      expect(DyFM_Error.getErrorStatus(webhookThrown)).toBe(429);
-
-      // egy masik endpoint tovabbra is a default 2-t kapja (a per-endpoint policy izolalt)
-      await svc.check(mockReq({ path: '/admin/refund' }), mockRes());
-      await svc.check(mockReq({ path: '/admin/refund' }), mockRes());
-      let refundThrown: any = null;
-      try { await svc.check(mockReq({ path: '/admin/refund' }), mockRes()); } catch (e) { refundThrown = e; }
-      expect(refundThrown).not.toBeNull();
-    });
+    expect(DyFM_Error.getErrorStatus(error)).toBe(429);
+  });
 
-    it('| clearPolicyForEndpoint visszaallit a default-ra', async (): Promise<void> => {
-      svc.configure({ defaultLimit: 1, defaultWindowMs: 10000 });
-      svc.setPolicyForEndpoint('/webhook', { limit: 5, windowMs: 10000 });
-      svc.clearPolicyForEndpoint('/webhook');
+  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);
+  });
 
-      await svc.check(mockReq({ path: '/webhook' }), mockRes());
-      let thrown: any = null;
-      try { await svc.check(mockReq({ path: '/webhook' }), mockRes()); } catch (e) { thrown = e; }
-      expect(thrown).not.toBeNull();
+  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,
     });
 
-    it('| precedencia: per-kulcs policy felulirja a per-endpoint policy-t', async (): Promise<void> => {
-      svc.configure({
-        defaultLimit:    2,
-        defaultWindowMs: 10000,
-        keyExtractor:    (req: Request): string => (req.headers['x-api-key'] as string) ?? req.ip ?? 'anon',
-      });
-      svc.setPolicyForEndpoint('/webhook', { limit: 5, windowMs: 10000 });
-      svc.setPolicyForKey('throttled-key', { limit: 1, windowMs: 10000 });
-
-      // a kulcs-policy (1) gyoz az endpoint-policy (5) felett
-      await svc.check(mockReq({ path: '/webhook', headers: { 'x-api-key': 'throttled-key' } }), mockRes());
-      let thrown: any = null;
-      try {
-        await svc.check(mockReq({ path: '/webhook', headers: { 'x-api-key': 'throttled-key' } }), mockRes());
-      } catch (e) { thrown = e; }
-      expect(thrown).not.toBeNull();
+    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)
+    );
 
-  describe('| keyExtractor override', (): void => {
-    it('| custom keyExtractor felulhatja a default IP-alapu-t', async (): Promise<void> => {
-      svc.configure({
-        defaultLimit:    1,
-        defaultWindowMs: 10000,
-        keyExtractor:    (req: Request): string => (req.headers['x-api-key'] as string) ?? 'anon',
-      });
-      // ugyanaz a IP, kulonbozo api-key — kulon limit
-      await svc.check(mockReq({ ip: '1.1.1.1', headers: { 'x-api-key': 'k1' } }), mockRes());
-      await svc.check(mockReq({ ip: '1.1.1.1', headers: { 'x-api-key': 'k2' } }), mockRes());
-      // k1 most a limit-en, k2 meg friss; ujabb k1 → 429
-      let thrown: any = null;
-      try { await svc.check(mockReq({ ip: '1.1.1.1', headers: { 'x-api-key': 'k1' } }), mockRes()); } catch (e) { thrown = e; }
-      expect(thrown).not.toBeNull();
-    });
+    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)
+    );
 
-  describe('| GC', (): void => {
-    it('| runGc eltavolitja az ures kulcsokat', async (): Promise<void> => {
-      svc.configure({ defaultLimit: 10, defaultWindowMs: 10 }); // 10ms-os window
-      await svc.check(mockReq(), mockRes());
-      expect(svc.getConfig().trackedStorageKeys).toBe(1);
+    service.configure({ keyExtractor: oversizedBucket });
+    const oversizedError: DyFM_Error = await captureError(
+      (): Promise<void> => service.check(mockRequest(), mockResponse().response)
+    );
 
-      // varjunk meg amig a window lejar
-      await new Promise<void>((resolve: () => void): void => { setTimeout(resolve, 50); });
+    expect(DyFM_Error.getErrorCode(emptyError)).toContain('BUCKET_KEY_INVALID');
+    expect(DyFM_Error.getErrorCode(oversizedError)).toContain('BUCKET_KEY_INVALID');
+  });
 
-      svc.runGc();
-      expect(svc.getConfig().trackedStorageKeys).toBe(0);
-    });
+  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 '';
+  }
 
-  describe('| getConfig() diagnosztika', (): void => {
-    it('| visszaadja az aktualis allapotot', (): void => {
-      svc.configure({ defaultLimit: 50, defaultWindowMs: 30000 });
-      svc.setPolicyForKey('a', { limit: 100, windowMs: 60000 });
-      svc.setPolicyForKey('b', { limit: 200, windowMs: 60000 });
+  /** Returns a bucket beyond the Bedrock safety ceiling. */
+  function oversizedBucket(req: Request): string {
+    void req;
 
-      const cfg = svc.getConfig();
-      expect(cfg.defaultLimit).toBe(50);
-      expect(cfg.defaultWindowMs).toBe(30000);
-      expect(cfg.activeKeyPolicies).toBe(2);
+    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.');
+  }
 });