@commercetools/checkout-payments-processor-sdk 0.0.6

package/src/api/handlers/status.handler.ts

@@ -0,0 +1,216 @@
+import type {
+  AuthType,
+  BaseIncomingHttpHeaders,
+  BaseOutgoingHttpHeaders,
+  HandlerResponse,
+  RouteHandler,
+} from '@api-types';
+import type { Logger } from '@logger-types';
+import type { AuthorizationService } from '@security-types';
+
+export type HealthCheckResult = {
+  name: string;
+  status: 'UP' | 'DOWN';
+  details?: object;
+  message?: string;
+};
+
+export type HealthCheck = () => Promise<HealthCheckResult>;
+
+export type StatusConfig = {
+  timeout: number;
+  checks: HealthCheck[];
+  metadataFn?: () => Promise<object>;
+  log: Logger;
+};
+
+export type StatusRequest = undefined;
+
+export type StatusResponse = {
+  status: 'OK' | 'Partially Available' | 'Unavailable';
+  timestamp: string;
+  checks: HealthCheckResult[];
+  version: string;
+  metadata?: object;
+};
+
+export type StatusIncomingHttpHeaders = BaseIncomingHttpHeaders & {};
+export type StatusOutgoingHttpHeaders = BaseOutgoingHttpHeaders & {};
+
+/**
+ * Check if CoCo permissions are available
+ * @param opts
+ * @returns
+ */
+export const healthCheckCommercetoolsPermissions =
+  (opts: {
+    ctAuthorizationService: AuthorizationService;
+    projectKey: string;
+    requiredPermissions: string[];
+  }): HealthCheck =>
+  async (): Promise<HealthCheckResult> => {
+    try {
+      const token = await opts.ctAuthorizationService.getAccessToken();
+
+      const hasManageProjectPermission = token.scope
+        .split(' ')
+        .includes(`manage_project:${opts.projectKey}`);
+
+      const foundAll =
+        hasManageProjectPermission ||
+        opts.requiredPermissions.every((currentScope) =>
+          token.scope
+            .split(' ')
+            .some(
+              (scopeInToken: string) =>
+                scopeInToken === `${currentScope}:${opts.projectKey}`,
+            ),
+        );
+
+      if (foundAll) {
+        return {
+          name: 'commercetools permissions',
+          status: 'UP',
+          details: {
+            scope: token.scope,
+          },
+        };
+      }
+
+      return {
+        name: 'commercetools permissions',
+        status: 'DOWN',
+        message: `commercetools permissions are not correct, expected scopes: ${opts.requiredPermissions.join(
+          ' ',
+        )}, actual scopes: ${token.scope}`,
+        details: {
+          expectedScopes: opts.requiredPermissions,
+          actualScopes: token.scope,
+          reason: 'scopes not available',
+        },
+      };
+    } catch (error) {
+      return {
+        name: 'commercetools permissions',
+        status: 'DOWN',
+        message: `Not able to talk with commercetools API`,
+        details: {
+          error,
+        },
+      };
+    }
+  };
+
+export abstract class StatusHandler
+  implements
+    RouteHandler<
+      StatusRequest,
+      StatusResponse,
+      StatusIncomingHttpHeaders,
+      StatusOutgoingHttpHeaders
+    >
+{
+  public readonly logger: Logger;
+  public constructor(opts: { logger: Logger }) {
+    this.logger = opts.logger;
+  }
+
+  public method() {
+    return 'GET';
+  }
+
+  public endpoint() {
+    return '/operations/status';
+  }
+
+  public auth(): AuthType[] {
+    return [
+      {
+        type: 'jwt',
+      },
+    ];
+  }
+
+  public async handler(_opts: {
+    request: StatusRequest;
+    headers: StatusIncomingHttpHeaders;
+  }): Promise<HandlerResponse<StatusResponse, StatusOutgoingHttpHeaders>> {
+    const statusConfig = this.handleStatus();
+
+    const status: Partial<StatusResponse> = {
+      timestamp: new Date().toISOString(),
+      version: process.env.npm_package_version ?? '0.0.0',
+    };
+
+    if (statusConfig.metadataFn) {
+      status.metadata = await statusConfig.metadataFn();
+    }
+
+    const timeout = async <T>(ms: number, promise: Promise<T>): Promise<T> => {
+      let timeoutId: NodeJS.Timeout;
+
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(
+          () => reject(new Error(`Timeout after ${ms}ms`)),
+          ms,
+        );
+      });
+
+      return Promise.race([promise, timeoutPromise]).finally(() => {
+        clearTimeout(timeoutId);
+      });
+    };
+
+    try {
+      const results = await timeout(
+        statusConfig.timeout,
+        Promise.all(statusConfig.checks.map((check) => check())),
+      );
+
+      let allDown = true;
+      let atLeastOneDown = false;
+
+      results.forEach((result) => {
+        if (result.status === 'DOWN') {
+          atLeastOneDown = true;
+          statusConfig.log.error(
+            { details: result.details },
+            result.message ??
+              `Health check for ${result.name} failed, check details`,
+          );
+        }
+        if (result.status === 'UP') {
+          allDown = false;
+        }
+      });
+
+      if (allDown) {
+        status.status = 'Unavailable';
+      } else if (atLeastOneDown) {
+        status.status = 'Partially Available';
+      } else {
+        status.status = 'OK';
+      }
+
+      status.checks = results;
+
+      return {
+        status: allDown ? 503 : 200,
+        body: status as StatusResponse,
+      };
+    } catch (e) {
+      if (e instanceof Error && e.message === 'Timeout') {
+        statusConfig.log.error({ err: e }, 'Health check timed out');
+      }
+      status.status = 'Unavailable';
+      status.checks = [];
+
+      return {
+        status: 503,
+        body: status as StatusResponse,
+      };
+    }
+  }
+
+  public abstract handleStatus(): StatusConfig;
+}

package/src/api/handlers/transaction.handler.ts

@@ -0,0 +1,86 @@
+import type { UUID } from 'node:crypto';
+import type {
+  AuthType,
+  BaseIncomingHttpHeaders,
+  BaseOutgoingHttpHeaders,
+  HandlerResponse,
+  RouteHandler,
+} from '@api-types';
+import type { Logger } from '@logger-types';
+
+export type TransactionRequest = {
+  cartId: UUID;
+  paymentInterface: UUID;
+  checkoutTransactionItemId: UUID;
+  amount?: {
+    centAmount: number;
+    currencyCode: string;
+  };
+  futureOrderNumber?: string;
+  paymentMethod?: {
+    id: UUID;
+  };
+  type?: 'Recurring';
+};
+
+export type TransactionResponse = {
+  transactionStatus: {
+    state: 'Completed' | 'Failed' | 'Pending';
+    errors: {
+      code: string;
+      message: string;
+    }[];
+  };
+};
+
+export type TransactionIncomingHttpHeaders = BaseIncomingHttpHeaders & {};
+export type TransactionOutgoingHttpHeaders = BaseOutgoingHttpHeaders & {};
+
+export abstract class TransactionHandler
+  implements
+    RouteHandler<
+      TransactionRequest,
+      TransactionResponse,
+      TransactionIncomingHttpHeaders,
+      TransactionOutgoingHttpHeaders
+    >
+{
+  public readonly logger: Logger;
+  public constructor(opts: { logger: Logger }) {
+    this.logger = opts.logger;
+  }
+
+  public method() {
+    return 'POST';
+  }
+
+  public endpoint() {
+    return '/operations/transactions';
+  }
+
+  public auth(): AuthType[] {
+    return [
+      {
+        type: 'oauth2',
+        allowedScopes: ['manage_project', 'manage_checkout_transactions'],
+      },
+    ];
+  }
+
+  public async handler(opts: {
+    request: TransactionRequest;
+    headers: TransactionIncomingHttpHeaders;
+  }): Promise<
+    HandlerResponse<TransactionResponse, TransactionOutgoingHttpHeaders>
+  > {
+    return await this.handleTransaction({
+      request: opts.request,
+    });
+  }
+
+  public abstract handleTransaction(opts: {
+    request: TransactionRequest;
+  }): Promise<
+    HandlerResponse<TransactionResponse, TransactionOutgoingHttpHeaders>
+  >;
+}

package/src/api/handlers/types/handler.type.ts

@@ -0,0 +1,49 @@
+export type HandlerResponse<Response, OutgoingHttpHeaders> = {
+  status: number;
+  body: Response;
+  headers?: OutgoingHttpHeaders;
+};
+
+export type AuthType =
+  | {
+      type: 'jwt';
+    }
+  | {
+      type: 'oauth2';
+      allowedScopes: string[];
+    }
+  | {
+      type: 'session';
+    };
+
+export interface RouteHandler<
+  Request,
+  Response,
+  IncomingHttpHeaders,
+  OutgoingHttpHeaders,
+> {
+  endpoint: () => string;
+  handler: (opts: {
+    request: Request;
+    headers: IncomingHttpHeaders;
+  }) => Promise<HandlerResponse<Response, OutgoingHttpHeaders>>;
+  auth: () => AuthType[];
+}
+
+export type BaseIncomingHttpHeaders = {
+  authorization: string;
+  'content-type': string;
+  accept: string;
+  'x-request-id': string;
+  'x-correlation-id': string;
+  [key: string]: string | string[];
+};
+
+export type BaseOutgoingHttpHeaders = {
+  authorization: string;
+  'content-type': string;
+  accept: string;
+  'x-request-id': string;
+  'x-correlation-id': string;
+  [key: string]: string | string[];
+};

package/src/api/hooks/authorize.hook.test.ts

@@ -0,0 +1,62 @@
+import type { ContextProvider, RequestContextData } from '@api-types';
+import { ErrorAuthErrorResponse } from '@errorx';
+import type { Logger } from '@logger-types';
+import type { AuthorityAuthorizationManager } from '@security';
+import { AuthorityAuthorizationHook } from '@/api/hooks/authorize.hook.js';
+
+describe('AuthorityAuthorizationHook', () => {
+  const loggerMock = vi.fn() as unknown as Logger;
+  const authorizationManagerMock = {
+    verify: vi.fn(),
+  };
+  const contextProviderMock = {
+    getContextData: vi.fn(),
+  };
+
+  const hook = new AuthorityAuthorizationHook({
+    authorizationManager:
+      authorizationManagerMock as unknown as AuthorityAuthorizationManager,
+    contextProvider:
+      contextProviderMock as unknown as ContextProvider<RequestContextData>,
+    logger: loggerMock,
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test('authorize should throw an error if authentication is missing', async () => {
+    // Arrange
+    const authorities = ['admin'];
+    //authorizationManagerMock.verify.mockRejectedValue(new ErrorAuthErrorResponse('Unauthorized'));
+    contextProviderMock.getContextData.mockReturnValue({});
+
+    // Act
+    const authorizeFn = hook.authorize(...authorities);
+
+    // Assert
+    await expect(authorizeFn()).rejects.toThrow(ErrorAuthErrorResponse);
+    expect(authorizationManagerMock.verify).not.toHaveBeenCalled();
+  });
+
+  test('authorize should call authorizationManager.verify with the correct arguments', async () => {
+    // Arrange
+    const authorities = ['admin'];
+    const authn = {
+      /* mock authentication object */
+    };
+    contextProviderMock.getContextData = vi
+      .fn()
+      .mockReturnValue({ authentication: authn });
+
+    // Act
+    const authorizeFn = hook.authorize(...authorities);
+
+    // Assert
+    await authorizeFn();
+    expect(authorizationManagerMock.verify).toHaveBeenCalledWith(
+      authn,
+      authorities,
+    );
+  });
+});

package/src/api/hooks/authorize.hook.ts

@@ -0,0 +1,51 @@
+import type {
+  AuthorizationHook,
+  ContextProvider,
+  RequestContextData,
+} from '@api-types';
+import { ErrorAuthErrorResponse } from '@errorx';
+import type { Logger } from '@logger-types';
+import type { AuthorityAuthorizationManager } from '@security';
+
+/**
+ * Represents an authorization hook that verifies the authority of a request.
+ */
+export class AuthorityAuthorizationHook implements AuthorizationHook {
+  private authorizationManager: AuthorityAuthorizationManager;
+  private contextProvider: ContextProvider<RequestContextData>;
+  private logger: Logger;
+
+  /**
+   * Constructs a new instance of the AuthorityAuthorizationHook class.
+   * @param opts - The options for configuring the hook.
+   */
+  constructor(opts: {
+    authorizationManager: AuthorityAuthorizationManager;
+    contextProvider: ContextProvider<RequestContextData>;
+    logger: Logger;
+  }) {
+    this.authorizationManager = opts.authorizationManager;
+    this.contextProvider = opts.contextProvider;
+    this.logger = opts.logger;
+  }
+
+  /**
+   * Authorizes the request based on the provided authorities.
+   * @param authorities - The authorities to verify.
+   * @returns A function that performs the authorization check.
+   */
+  authorize(...authorities: string[]) {
+    return async () => {
+      const authn = this.contextProvider.getContextData().authentication;
+
+      if (!authn) {
+        throw new ErrorAuthErrorResponse('Authentication is required.', {
+          privateMessage:
+            'Not able to authenticate the request. Missing authentication information in context.',
+        });
+      }
+
+      this.authorizationManager.verify(authn, authorities);
+    };
+  }
+}

package/src/api/hooks/jwt-auth.hook.test.ts

@@ -0,0 +1,54 @@
+import type { Logger } from '@logger-types';
+import { JWTAuthentication, type JWTAuthenticationManager } from '@security';
+import type {
+  ContextProvider,
+  RequestContextData,
+} from '@/api/context/types/request-context.type.js';
+import { JWTAuthenticationHook } from '@/api/hooks/jwt-auth.hook.js';
+
+describe('JWTAuthenticationHook', () => {
+  const authenticationManager = {
+    authenticate: vi.fn(),
+  };
+  const contextProvider = {
+    updateContextData: vi.fn(),
+  };
+  const logger = vi.fn() as unknown as Logger;
+  const authenticationHook = new JWTAuthenticationHook({
+    authenticationManager:
+      authenticationManager as unknown as JWTAuthenticationManager,
+    contextProvider:
+      contextProvider as unknown as ContextProvider<RequestContextData>,
+    logger,
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test('authenticate should update the context data with authentication', async () => {
+    // Arrange
+    const header = 'Bearer <jwt-token>';
+    const request = {
+      headers: {
+        authorization: 'Bearer <jwt-token>',
+      },
+    };
+    const jwtAuthentication = new JWTAuthentication('<jwt-token>', {
+      mcCustomerId: '123',
+    });
+
+    // Act
+    authenticationManager.authenticate.mockResolvedValue(jwtAuthentication);
+    const authenticateFn = authenticationHook.authenticate();
+    await authenticateFn(request);
+
+    // Assert
+    expect(contextProvider.updateContextData).toHaveBeenCalledWith({
+      authentication: jwtAuthentication,
+    });
+    expect(authenticationManager.authenticate).toHaveBeenCalledWith({
+      authHeader: header,
+    });
+  });
+});

package/src/api/hooks/jwt-auth.hook.ts

@@ -0,0 +1,56 @@
+import type { IncomingHttpHeaders } from 'node:http';
+import type { Logger } from '@logger-types';
+import {
+  HeaderBasedAuthentication,
+  type JWTAuthenticationManager,
+} from '@security';
+import type {
+  ContextProvider,
+  RequestContextData,
+} from '@/api/context/types/request-context.type.js';
+import type { AuthenticationHook } from '@/api/hooks/types/hook.type.js';
+
+/**
+ * Represents a JWT Authentication Hook.
+ */
+export class JWTAuthenticationHook implements AuthenticationHook {
+  private authenticationManager: JWTAuthenticationManager;
+  private contextProvider: ContextProvider<RequestContextData>;
+  private logger: Logger;
+
+  /**
+   * Constructs a new instance of the JWTAuthenticationHook class.
+   * @param opts - The options for the JWTAuthenticationHook.
+   */
+  constructor(opts: {
+    authenticationManager: JWTAuthenticationManager;
+    contextProvider: ContextProvider<RequestContextData>;
+    logger: Logger;
+  }) {
+    this.authenticationManager = opts.authenticationManager;
+    this.contextProvider = opts.contextProvider;
+    this.logger = opts.logger;
+  }
+
+  /**
+   * Authenticates the request.
+   * @returns A function that performs the authentication.
+   */
+  authenticate() {
+    return async (request: {
+      headers: IncomingHttpHeaders;
+      query?: unknown;
+    }) => {
+      const authorizationHeader = new HeaderBasedAuthentication(
+        request.headers.authorization as string,
+      );
+
+      const authn =
+        await this.authenticationManager.authenticate(authorizationHeader);
+
+      this.contextProvider.updateContextData({
+        authentication: authn,
+      });
+    };
+  }
+}