@doswiftly/storefront-sdk 4.0.0 → 4.2.0

package/src/__tests__/unit/bot-protection.test.ts

@@ -0,0 +1,461 @@
+/**
+ * Unit tests for bot protection: middleware, fallback manager, factory.
+ *
+ * Tests: botProtectionMiddleware, FallbackBotProtectionManager, createBotProtectionManager.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  botProtectionMiddleware,
+  BOT_PROTECTION_HEADER,
+  type BotProtectionTokenProvider,
+} from '../../core/middleware/bot-protection';
+import { FallbackBotProtectionManager } from '../../core/bot-protection/fallback-manager';
+import { StorefrontError } from '../../core/errors';
+import type { GraphQLRequest, GraphQLResponse, ExecuteFn } from '../../core/client/types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeRequest(overrides?: Partial<GraphQLRequest>): GraphQLRequest {
+  return {
+    query: '{ shop { id } }',
+    headers: {},
+    isMutation: false,
+    ...overrides,
+  };
+}
+
+function makeResponse(overrides?: Partial<GraphQLResponse>): GraphQLResponse {
+  return {
+    data: {},
+    status: 200,
+    headers: new Headers(),
+    ...overrides,
+  };
+}
+
+function makeNext(response?: GraphQLResponse): ExecuteFn {
+  return vi.fn(async () => response ?? makeResponse());
+}
+
+function makeTokenProvider(
+  token: string | null = 'test-token',
+  options?: { delay?: number; shouldThrow?: boolean },
+): BotProtectionTokenProvider {
+  return {
+    execute: vi.fn(async () => {
+      if (options?.delay) {
+        await new Promise((r) => setTimeout(r, options.delay));
+      }
+      if (options?.shouldThrow) {
+        throw new Error('Provider error');
+      }
+      return token;
+    }),
+    destroy: vi.fn(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// botProtectionMiddleware
+// ---------------------------------------------------------------------------
+
+describe('botProtectionMiddleware', () => {
+  const protectedOperations = ['CustomerCreate', 'CheckoutComplete', 'ReviewCreate'];
+
+  it('should skip queries (non-mutations)', async () => {
+    const provider = makeTokenProvider();
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+    });
+    const next = makeNext();
+    const req = makeRequest({ isMutation: false, operationName: 'Shop' });
+
+    await mw(req, next);
+
+    expect(provider.execute).not.toHaveBeenCalled();
+    expect(req.headers[BOT_PROTECTION_HEADER]).toBeUndefined();
+    expect(next).toHaveBeenCalledWith(req);
+  });
+
+  it('should skip non-protected mutations', async () => {
+    const provider = makeTokenProvider();
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+    });
+    const next = makeNext();
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CartLinesAdd',
+    });
+
+    await mw(req, next);
+
+    expect(provider.execute).not.toHaveBeenCalled();
+    expect(req.headers[BOT_PROTECTION_HEADER]).toBeUndefined();
+    expect(next).toHaveBeenCalledWith(req);
+  });
+
+  it('should skip mutations without operationName', async () => {
+    const provider = makeTokenProvider();
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+    });
+    const next = makeNext();
+    const req = makeRequest({ isMutation: true }); // no operationName
+
+    await mw(req, next);
+
+    expect(provider.execute).not.toHaveBeenCalled();
+    expect(next).toHaveBeenCalledWith(req);
+  });
+
+  it('should add token header for protected mutations', async () => {
+    const provider = makeTokenProvider('fresh-token');
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+    });
+    const next = makeNext();
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CustomerCreate',
+    });
+
+    await mw(req, next);
+
+    expect(provider.execute).toHaveBeenCalledWith({
+      action: 'CustomerCreate',
+      timeoutMs: 10000,
+    });
+    expect(req.headers[BOT_PROTECTION_HEADER]).toBe('fresh-token');
+    expect(next).toHaveBeenCalledWith(req);
+  });
+
+  it('should pass action matching operationName', async () => {
+    const provider = makeTokenProvider('token');
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+    });
+    const next = makeNext();
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CheckoutComplete',
+    });
+
+    await mw(req, next);
+
+    expect(provider.execute).toHaveBeenCalledWith(
+      expect.objectContaining({ action: 'CheckoutComplete' }),
+    );
+  });
+
+  it('should fail-open by default when token is null', async () => {
+    const provider = makeTokenProvider(null);
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+    });
+    const next = makeNext();
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CustomerCreate',
+    });
+
+    await mw(req, next);
+
+    // No header, but request passes through
+    expect(req.headers[BOT_PROTECTION_HEADER]).toBeUndefined();
+    expect(next).toHaveBeenCalledWith(req);
+  });
+
+  it('should throw on fail-closed when token is null', async () => {
+    const provider = makeTokenProvider(null);
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+      defaultFailStrategy: 'closed',
+    });
+    const next = makeNext();
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CustomerCreate',
+    });
+
+    await expect(mw(req, next)).rejects.toThrow(StorefrontError);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('should respect per-operation failStrategyOverrides', async () => {
+    const provider = makeTokenProvider(null);
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+      defaultFailStrategy: 'open',
+      failStrategyOverrides: {
+        CheckoutComplete: 'closed',
+      },
+    });
+    const next = makeNext();
+
+    // CustomerCreate: default open → should pass
+    const req1 = makeRequest({
+      isMutation: true,
+      operationName: 'CustomerCreate',
+    });
+    await mw(req1, next);
+    expect(next).toHaveBeenCalled();
+
+    // CheckoutComplete: override closed → should throw
+    const req2 = makeRequest({
+      isMutation: true,
+      operationName: 'CheckoutComplete',
+    });
+    await expect(mw(req2, next)).rejects.toThrow(StorefrontError);
+  });
+
+  it('should throw StorefrontError with BOT_PROTECTION_REQUIRED code on closed fail', async () => {
+    const provider = makeTokenProvider(null);
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+      defaultFailStrategy: 'closed',
+    });
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CustomerCreate',
+    });
+
+    try {
+      await mw(req, makeNext());
+      expect.fail('Should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(StorefrontError);
+      expect((err as StorefrontError).code).toBe('BOT_PROTECTION_REQUIRED');
+    }
+  });
+
+  it('should forward response from next() without modification', async () => {
+    const provider = makeTokenProvider('token');
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+    });
+    const expectedResponse = makeResponse({ data: { foo: 'bar' }, status: 201 });
+    const next = makeNext(expectedResponse);
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CustomerCreate',
+    });
+
+    const result = await mw(req, next);
+
+    expect(result).toBe(expectedResponse);
+  });
+
+  it('should propagate provider execute() exceptions to caller', async () => {
+    const provider = makeTokenProvider(null, { shouldThrow: true });
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+      defaultFailStrategy: 'open', // fail-open, but execute throws before we get to fail strategy
+    });
+    const next = makeNext();
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CustomerCreate',
+    });
+
+    // Provider throws → error propagates (not caught by middleware)
+    await expect(mw(req, next)).rejects.toThrow('Provider error');
+  });
+
+  it('should treat empty string token as falsy (no header added)', async () => {
+    const provider = makeTokenProvider('');
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+    });
+    const next = makeNext();
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CustomerCreate',
+    });
+
+    await mw(req, next);
+
+    // Empty string is falsy → no header, but fail-open passes through
+    expect(req.headers[BOT_PROTECTION_HEADER]).toBeUndefined();
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should do nothing when protectedOperations list is empty', async () => {
+    const provider = makeTokenProvider('token');
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations: [], // empty
+    });
+    const next = makeNext();
+    const req = makeRequest({
+      isMutation: true,
+      operationName: 'CustomerCreate',
+    });
+
+    await mw(req, next);
+
+    expect(provider.execute).not.toHaveBeenCalled();
+    expect(req.headers[BOT_PROTECTION_HEADER]).toBeUndefined();
+  });
+
+  it('should call execute fresh on every request (no caching)', async () => {
+    let callCount = 0;
+    const provider: BotProtectionTokenProvider = {
+      execute: vi.fn(async () => {
+        callCount++;
+        return `token-${callCount}`;
+      }),
+      destroy: vi.fn(),
+    };
+    const mw = botProtectionMiddleware({
+      tokenProvider: provider,
+      protectedOperations,
+    });
+
+    const req1 = makeRequest({ isMutation: true, operationName: 'CustomerCreate' });
+    await mw(req1, makeNext());
+    expect(req1.headers[BOT_PROTECTION_HEADER]).toBe('token-1');
+
+    const req2 = makeRequest({ isMutation: true, operationName: 'CustomerCreate' });
+    await mw(req2, makeNext());
+    expect(req2.headers[BOT_PROTECTION_HEADER]).toBe('token-2');
+
+    expect(provider.execute).toHaveBeenCalledTimes(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FallbackBotProtectionManager
+// ---------------------------------------------------------------------------
+
+describe('FallbackBotProtectionManager', () => {
+  it('should return token from primary on success', async () => {
+    const primary = makeTokenProvider('primary-token');
+    const fallback = makeTokenProvider('fallback-token');
+    const manager = new FallbackBotProtectionManager(primary, fallback);
+
+    const token = await manager.execute({ action: 'test' });
+
+    expect(token).toBe('primary-token');
+    expect(primary.execute).toHaveBeenCalled();
+    expect(fallback.execute).not.toHaveBeenCalled();
+  });
+
+  it('should fallback when primary returns null', async () => {
+    const primary = makeTokenProvider(null);
+    const fallback = makeTokenProvider('fallback-token');
+    const manager = new FallbackBotProtectionManager(primary, fallback);
+
+    const token = await manager.execute({ action: 'test' });
+
+    expect(token).toBe('fallback-token');
+    expect(primary.execute).toHaveBeenCalled();
+    expect(fallback.execute).toHaveBeenCalled();
+  });
+
+  it('should fallback when primary throws', async () => {
+    const primary = makeTokenProvider(null, { shouldThrow: true });
+    const fallback = makeTokenProvider('fallback-token');
+    const manager = new FallbackBotProtectionManager(primary, fallback);
+
+    const token = await manager.execute({ action: 'test' });
+
+    expect(token).toBe('fallback-token');
+  });
+
+  it('should return null when both fail (fail-open)', async () => {
+    const primary = makeTokenProvider(null, { shouldThrow: true });
+    const fallback = makeTokenProvider(null, { shouldThrow: true });
+    const manager = new FallbackBotProtectionManager(primary, fallback);
+
+    const token = await manager.execute({ action: 'test' });
+
+    expect(token).toBeNull();
+  });
+
+  it('should return null when primary fails and no fallback', async () => {
+    const primary = makeTokenProvider(null, { shouldThrow: true });
+    const manager = new FallbackBotProtectionManager(primary, null);
+
+    const token = await manager.execute({ action: 'test' });
+
+    expect(token).toBeNull();
+  });
+
+  it('should return null when primary returns null and no fallback', async () => {
+    const primary = makeTokenProvider(null);
+    const manager = new FallbackBotProtectionManager(primary, null);
+
+    const token = await manager.execute({ action: 'test' });
+
+    expect(token).toBeNull();
+  });
+
+  it('should destroy both primary and fallback', () => {
+    const primary = makeTokenProvider();
+    const fallback = makeTokenProvider();
+    const manager = new FallbackBotProtectionManager(primary, fallback);
+
+    manager.destroy();
+
+    expect(primary.destroy).toHaveBeenCalled();
+    expect(fallback.destroy).toHaveBeenCalled();
+  });
+
+  it('should handle destroy with null fallback', () => {
+    const primary = makeTokenProvider();
+    const manager = new FallbackBotProtectionManager(primary, null);
+
+    // Should not throw
+    manager.destroy();
+    expect(primary.destroy).toHaveBeenCalled();
+  });
+
+  it('should pass options through to providers', async () => {
+    const primary = makeTokenProvider('token');
+    const manager = new FallbackBotProtectionManager(primary, null);
+
+    await manager.execute({ action: 'CustomerCreate', timeoutMs: 5000 });
+
+    expect(primary.execute).toHaveBeenCalledWith({
+      action: 'CustomerCreate',
+      timeoutMs: 5000,
+    });
+  });
+
+  it('should treat empty string token from primary as falsy and fallback', async () => {
+    const primary = makeTokenProvider('');
+    const fallback = makeTokenProvider('fallback-token');
+    const manager = new FallbackBotProtectionManager(primary, fallback);
+
+    const token = await manager.execute();
+
+    // Empty string is falsy → should fallback
+    expect(token).toBe('fallback-token');
+  });
+
+  it('should work when called without options (undefined)', async () => {
+    const primary = makeTokenProvider('token');
+    const manager = new FallbackBotProtectionManager(primary, null);
+
+    const token = await manager.execute();
+
+    expect(token).toBe('token');
+    expect(primary.execute).toHaveBeenCalledWith(undefined);
+  });
+});