@commercetools/checkout-payments-processor-sdk 0.0.6

package/src/payment-processor.ts

@@ -0,0 +1,317 @@
+import {
+  AuthorityAuthorizationHook,
+  JWTAuthenticationHook,
+  Oauth2AuthenticationHook,
+  RequestContextProvider,
+  SessionHeaderAuthenticationHook,
+  SessionQueryParamAuthenticationHook,
+} from '@api';
+import type { RequestContextData } from '@api-types';
+import { CommercetoolsLogger } from '@logger';
+import type { Logger } from '@logger-types';
+import {
+  AuthorityAuthorizationManager,
+  DefaultAuthorizationService,
+  DefaultJWTService,
+  DefaultOauth2Service,
+  DefaultSessionService,
+  JWTAuthenticationManager,
+  Oauth2AuthenticationManager,
+  SessionHeaderAuthenticationManager,
+  SessionQueryParamAuthenticationManager,
+} from '@security';
+import type {
+  AuthorizationService,
+  JWTService,
+  Oauth2Service,
+  SessionService,
+} from '@security-types';
+import { DefaultOrderService } from '@/commercetools/services/ct-order.service.js';
+import { DefaultPaymentService } from '@/commercetools/services/ct-payment.service.js';
+import { DefaultPaymentMethodService } from '@/commercetools/services/ct-payment-method.service.js';
+import type { CartService } from '@/commercetools/types/cart.type.js';
+import type { OrderService } from '@/commercetools/types/order.type.js';
+import type { PaymentService } from '@/commercetools/types/payment.type.js';
+import type { PaymentMethodService } from '@/commercetools/types/payment-method.type.js';
+import type { CommercetoolsAPI } from '@/commercetools/types.js';
+import { DefaultCommercetoolsAPI } from './commercetools/api/root-api.js';
+import { DefaultCartService } from './commercetools/services/ct-cart.service.js';
+import { DefaultCustomTypeService } from './commercetools/services/ct-custom-type.service.js';
+import type { CustomTypeService } from './commercetools/types/custom-type.type.js';
+import { BasicFetcher } from './fetch/decorators/base.decorator.js';
+import { MonitoringFetcherDecorator } from './fetch/decorators/monitoring.decorator.js';
+
+/**
+ * Checkout Payments Processor SDK
+ * @description This class is used to process payments for checkout.
+ * @param opts - The options for the processor.
+ * @param opts.authUrl - The URL for the authentication service.
+ * @param opts.apiUrl - The URL for the API service.
+ * @param opts.sessionUrl - The URL for the session service.
+ * @param opts.jwksUrl - The URL for the JWT service.
+ * @param opts.clientId - The client ID for the authentication service.
+ * @param opts.clientSecret - The client secret for the authentication service.
+ * @param opts.projectKey - The project key for the API service.
+ * @param opts.jwtIssuer - The issuer for the JWT service.
+ * @param opts.getContextFn - The function to get the context.
+ * @param opts.updateContextFn - The function to update the context.
+ * @param opts.logger - The logger for the processor.
+ * @returns The CheckoutPaymentsProcessor instance.
+ */
+export class CheckoutPaymentsProcessor {
+  private readonly authUrl: string;
+  private readonly apiUrl: string;
+  private readonly sessionUrl: string;
+  private readonly jwksUrl: string;
+  private readonly clientId: string;
+  private readonly clientSecret: string;
+  private readonly projectKey: string;
+  private readonly jwtIssuer: string;
+  private readonly getContextFn: () => RequestContextData;
+  private readonly updateContextFn: (ctx: Partial<RequestContextData>) => void;
+  private readonly logger: Logger;
+  private readonly ctAPI: CommercetoolsAPI;
+  private readonly authorizationService: AuthorizationService;
+  private readonly sessionService: SessionService;
+  private readonly cartService: CartService;
+  private readonly orderService: OrderService;
+  private readonly paymentService: PaymentService;
+  private readonly paymentMethodService: PaymentMethodService;
+  private readonly customTypeService: CustomTypeService;
+  private readonly oauth2Service: Oauth2Service;
+  private readonly jwtService: JWTService;
+  private readonly sessionHeaderAuthenticationManager: SessionHeaderAuthenticationManager;
+  private readonly sessionQueryParamAuthenticationManager: SessionQueryParamAuthenticationManager;
+  private readonly jwtAuthenticationManager: JWTAuthenticationManager;
+  private readonly oauth2AuthenticationManager: Oauth2AuthenticationManager;
+  private readonly authorityAuthorizationManager: AuthorityAuthorizationManager;
+  private readonly sessionHeaderAuthHookFn: SessionHeaderAuthenticationHook;
+  private readonly sessionQueryParamAuthHookFn: SessionQueryParamAuthenticationHook;
+  private readonly jwtAuthHookFn: JWTAuthenticationHook;
+  private readonly oauth2AuthHookFn: Oauth2AuthenticationHook;
+  private readonly authorityAuthorizationHookFn: AuthorityAuthorizationHook;
+
+  constructor(opts: {
+    authUrl: string;
+    apiUrl: string;
+    sessionUrl: string;
+    jwksUrl: string;
+    clientId: string;
+    clientSecret: string;
+    projectKey: string;
+    jwtIssuer: string;
+    getContextFn: () => RequestContextData;
+    updateContextFn: (ctx: Partial<RequestContextData>) => void;
+    logger?: Logger;
+  }) {
+    this.authUrl = opts.authUrl;
+    this.apiUrl = opts.apiUrl;
+    this.sessionUrl = opts.sessionUrl;
+    this.jwksUrl = opts.jwksUrl;
+    this.clientId = opts.clientId;
+    this.clientSecret = opts.clientSecret;
+    this.projectKey = opts.projectKey;
+    this.jwtIssuer = opts.jwtIssuer;
+    this.getContextFn = opts.getContextFn;
+    this.updateContextFn = opts.updateContextFn;
+
+    const contextProvider = new RequestContextProvider({
+      getContextFn: this.getContextFn,
+      updateContextFn: this.updateContextFn,
+    });
+
+    this.logger =
+      opts.logger ||
+      new CommercetoolsLogger({ contextProvider, projectKey: opts.projectKey });
+
+    const fetcher = new MonitoringFetcherDecorator(
+      new BasicFetcher(),
+      contextProvider,
+    );
+    const decoratedFetch = fetcher.run.bind(fetcher);
+
+    this.ctAPI = new DefaultCommercetoolsAPI({
+      apiUrl: this.apiUrl,
+      authUrl: this.authUrl,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      projectKey: this.projectKey,
+      contextProvider,
+      logger: this.logger,
+    });
+
+    this.authorizationService = new DefaultAuthorizationService({
+      authUrl: this.authUrl,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      fetch: decoratedFetch,
+      logger: this.logger,
+    });
+
+    this.sessionService = new DefaultSessionService({
+      authorizationService: this.authorizationService,
+      sessionUrl: this.sessionUrl,
+      projectKey: this.projectKey,
+      logger: this.logger,
+    });
+
+    this.cartService = new DefaultCartService({
+      ctAPI: this.ctAPI,
+      logger: this.logger,
+      contextProvider,
+    });
+    this.orderService = new DefaultOrderService({
+      ctAPI: this.ctAPI,
+      logger: this.logger,
+    });
+    this.paymentService = new DefaultPaymentService({
+      ctAPI: this.ctAPI,
+      logger: this.logger,
+    });
+    this.paymentMethodService = new DefaultPaymentMethodService({
+      ctAPI: this.ctAPI,
+      logger: this.logger,
+    });
+    this.customTypeService = new DefaultCustomTypeService({
+      ctAPI: this.ctAPI,
+      logger: this.logger,
+    });
+
+    this.oauth2Service = new DefaultOauth2Service({ logger: this.logger });
+
+    this.jwtService = new DefaultJWTService({
+      jwksUrl: this.jwksUrl,
+      logger: this.logger,
+    });
+
+    this.sessionHeaderAuthenticationManager =
+      new SessionHeaderAuthenticationManager({
+        sessionService: this.sessionService,
+        logger: this.logger,
+      });
+
+    this.sessionQueryParamAuthenticationManager =
+      new SessionQueryParamAuthenticationManager({
+        sessionService: this.sessionService,
+        logger: this.logger,
+      });
+
+    this.oauth2AuthenticationManager = new Oauth2AuthenticationManager({
+      oauth2Service: this.oauth2Service,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      authUrl: this.authUrl,
+      logger: this.logger,
+    });
+
+    this.authorityAuthorizationManager = new AuthorityAuthorizationManager({
+      logger: this.logger,
+    });
+
+    this.jwtAuthenticationManager = new JWTAuthenticationManager({
+      jwtService: this.jwtService,
+      iss: this.jwtIssuer,
+      projectKey: this.projectKey,
+      logger: this.logger,
+    });
+
+    this.sessionHeaderAuthHookFn = new SessionHeaderAuthenticationHook({
+      authenticationManager: this.sessionHeaderAuthenticationManager,
+      contextProvider,
+      logger: this.logger,
+    });
+
+    this.sessionQueryParamAuthHookFn = new SessionQueryParamAuthenticationHook({
+      authenticationManager: this.sessionQueryParamAuthenticationManager,
+      contextProvider,
+      logger: this.logger,
+    });
+
+    this.jwtAuthHookFn = new JWTAuthenticationHook({
+      authenticationManager: this.jwtAuthenticationManager,
+      contextProvider,
+      logger: this.logger,
+    });
+
+    this.oauth2AuthHookFn = new Oauth2AuthenticationHook({
+      authenticationManager: this.oauth2AuthenticationManager,
+      contextProvider,
+      logger: this.logger,
+    });
+
+    this.authorityAuthorizationHookFn = new AuthorityAuthorizationHook({
+      authorizationManager: this.authorityAuthorizationManager,
+      contextProvider,
+      logger: this.logger,
+    });
+
+    this.customTypeService = new DefaultCustomTypeService({
+      ctAPI: this.ctAPI,
+      logger: this.logger,
+    });
+  }
+
+  public getLogger(): Logger {
+    return this.logger;
+  }
+
+  public getCtApi(): CommercetoolsAPI {
+    return this.ctAPI;
+  }
+
+  public getAuthorizationService(): AuthorizationService {
+    return this.authorizationService;
+  }
+
+  public getSessionService(): SessionService {
+    return this.sessionService;
+  }
+
+  public getCartService(): CartService {
+    return this.cartService;
+  }
+
+  public getOrderService(): OrderService {
+    return this.orderService;
+  }
+
+  public getPaymentService(): PaymentService {
+    return this.paymentService;
+  }
+
+  public getPaymentMethodService(): PaymentMethodService {
+    return this.paymentMethodService;
+  }
+
+  public getOauth2Service(): Oauth2Service {
+    return this.oauth2Service;
+  }
+
+  public getJwtService(): JWTService {
+    return this.jwtService;
+  }
+
+  public getSessionHeaderAuthHookFn(): SessionHeaderAuthenticationHook {
+    return this.sessionHeaderAuthHookFn;
+  }
+
+  public getSessionQueryParamAuthHookFn(): SessionQueryParamAuthenticationHook {
+    return this.sessionQueryParamAuthHookFn;
+  }
+
+  public getJwtAuthHookFn(): JWTAuthenticationHook {
+    return this.jwtAuthHookFn;
+  }
+
+  public getOauth2AuthHookFn(): Oauth2AuthenticationHook {
+    return this.oauth2AuthHookFn;
+  }
+
+  public getAuthorityAuthorizationHookFn(): AuthorityAuthorizationHook {
+    return this.authorityAuthorizationHookFn;
+  }
+
+  public getCustomTypeService(): CustomTypeService {
+    return this.customTypeService;
+  }
+}

package/src/security/authn/authns.ts

@@ -0,0 +1,219 @@
+import type {
+  Authentication,
+  HeaderPrincipal,
+  JWTPrincipal,
+  Oauth2Principal,
+  QueryParamPrincipal,
+  SessionPrincipal,
+} from '@security-types';
+
+/**
+ * SessionAuthentication is an authentication class that implements the Authentication interface.
+ * It is used to authenticate via a session id.
+ * @param sessionId - The session id to authenticate via.
+ * @param principal - The principal to authenticate via.
+ * @returns A SessionAuthentication instance.
+ */
+export class SessionAuthentication
+  implements Authentication<SessionPrincipal, string>
+{
+  private principal: SessionPrincipal;
+  private authorities: string[] = [];
+  private sessionId: string;
+  private authenticated: boolean;
+
+  constructor(sessionId: string, principal: SessionPrincipal) {
+    this.principal = principal;
+    this.sessionId = sessionId;
+    this.authenticated = true;
+  }
+
+  hasPrincipal(): boolean {
+    return this.getPrincipal() !== undefined;
+  }
+  getAuthorities(): string[] {
+    return this.authorities;
+  }
+  hasCredentials(): boolean {
+    return this.getCredentials() !== undefined;
+  }
+  getPrincipal() {
+    return this.principal;
+  }
+  getCredentials() {
+    return this.sessionId;
+  }
+  isAuthenticated(): boolean {
+    return this.authenticated;
+  }
+}
+
+/**
+ * HeaderBasedAuthentication is an authentication class that implements the Authentication interface.
+ * It is used to authenticate via a specific header.
+ * @param authHeader - The header name that is used to authenticate.
+ * @returns A HeaderBasedAuthentication instance.
+ */
+export class HeaderBasedAuthentication
+  implements Authentication<HeaderPrincipal, string>
+{
+  private authHeader: string;
+
+  constructor(authHeader: string) {
+    this.authHeader = authHeader;
+  }
+
+  hasPrincipal(): boolean {
+    return this.getPrincipal() !== undefined;
+  }
+
+  getAuthorities(): string[] {
+    return [];
+  }
+
+  hasCredentials(): boolean {
+    return this.getCredentials() !== undefined;
+  }
+
+  getCredentials(): string {
+    return this.authHeader;
+  }
+
+  getPrincipal(): HeaderPrincipal {
+    return {
+      authHeader: this.authHeader,
+    };
+  }
+
+  isAuthenticated(): boolean {
+    return false;
+  }
+}
+
+/**
+ * QueryParamBasedAuthentication is an authentication class that implements the Authentication interface.
+ * It is used to authenticate via a query param.
+ * @param authQueryParam - The query param name that is used to authenticate. It is usually called 'ctsid'.
+ * @returns A QueryParamBasedAuthentication instance.
+ */
+export class QueryParamBasedAuthentication
+  implements Authentication<QueryParamPrincipal, string>
+{
+  private authQueryParam: string;
+
+  constructor(authQueryParam: string) {
+    this.authQueryParam = authQueryParam;
+  }
+
+  hasPrincipal(): boolean {
+    return this.getPrincipal() !== undefined;
+  }
+
+  getAuthorities(): string[] {
+    return [];
+  }
+
+  hasCredentials(): boolean {
+    return this.getCredentials() !== undefined;
+  }
+
+  getCredentials(): string {
+    return this.authQueryParam;
+  }
+
+  getPrincipal(): QueryParamPrincipal {
+    return {
+      authQueryParam: this.authQueryParam,
+    };
+  }
+
+  isAuthenticated(): boolean {
+    return false;
+  }
+}
+
+/**
+ * Oauth2Authentication is an authentication class that implements the Authentication interface.
+ * It is used to authenticate via a specific OAuth2 token.
+ * @param accessToken - The OAuth2 token to authenticate via.
+ * @param principal - The principal to authenticate via.
+ * @returns A Oauth2Authentication instance.
+ */
+export class Oauth2Authentication
+  implements Authentication<Oauth2Principal, string>
+{
+  private principal: Oauth2Principal;
+  private authorities: string[];
+
+  private authenticated: boolean;
+  private accessToken: string;
+
+  constructor(accessToken: string, principal: Oauth2Principal) {
+    this.principal = principal;
+    this.authorities = principal.scope
+      .split(' ')
+      .map((scope) => scope.split(':')[0])
+      .filter((scope) => scope !== '');
+    this.authenticated = true;
+    this.accessToken = accessToken;
+  }
+
+  hasPrincipal(): boolean {
+    return this.getPrincipal() !== undefined;
+  }
+  getAuthorities(): string[] {
+    return this.authorities;
+  }
+  hasCredentials(): boolean {
+    return this.getCredentials() !== undefined;
+  }
+  getPrincipal() {
+    return this.principal;
+  }
+  getCredentials() {
+    return this.accessToken;
+  }
+  isAuthenticated(): boolean {
+    return this.authenticated;
+  }
+}
+
+/**
+ * JWTAuthentication is an authentication class that implements the Authentication interface.
+ * It is used to authenticate via a specific JWT token.
+ * @param jwt - The JWT token to authenticate via.
+ * @param principal - The principal to authenticate via.
+ * @returns A JWTAuthentication instance.
+ */
+export class JWTAuthentication implements Authentication<JWTPrincipal, string> {
+  private principal: JWTPrincipal;
+
+  private authenticated: boolean;
+  private jwt: string;
+
+  constructor(jwt: string, principal: JWTPrincipal) {
+    this.principal = principal;
+
+    this.authenticated = true;
+    this.jwt = jwt;
+  }
+
+  hasPrincipal(): boolean {
+    return this.getPrincipal() !== undefined;
+  }
+  getAuthorities(): string[] {
+    return ['manage_project', 'manage_checkout_application'];
+  }
+  hasCredentials(): boolean {
+    return this.getCredentials() !== undefined;
+  }
+  getPrincipal() {
+    return this.principal;
+  }
+  getCredentials() {
+    return this.jwt;
+  }
+  isAuthenticated(): boolean {
+    return this.authenticated;
+  }
+}

package/src/security/authn/bearer-utils.test.ts

@@ -0,0 +1,35 @@
+import { ErrorAuthErrorResponse } from '@errorx';
+import { validateBearerAuthorization } from '@/security/authn/bearer-utils.js';
+
+describe('validateBearerAuthorization', () => {
+  test('should return the token when authorization header is valid', () => {
+    // Arrange
+    const authorization = 'Bearer token';
+
+    // Act
+    const result = validateBearerAuthorization(authorization);
+
+    // Assert
+    expect(result).toBe('token');
+  });
+
+  test('should throw an error when authorization header is missing', () => {
+    // Arrange
+    const authorization = undefined;
+
+    // Act & Assert
+    expect(() => validateBearerAuthorization(authorization)).toThrow(
+      ErrorAuthErrorResponse,
+    );
+  });
+
+  test('should throw an error when authorization header format is invalid', () => {
+    // Arrange
+    const authorization = 'InvalidFormat';
+
+    // Act & Assert
+    expect(() => validateBearerAuthorization(authorization)).toThrow(
+      ErrorAuthErrorResponse,
+    );
+  });
+});

package/src/security/authn/bearer-utils.ts

@@ -0,0 +1,28 @@
+import { ErrorAuthErrorResponse } from '@errorx';
+
+export const validateBearerAuthorization = (
+  authorization: string | undefined,
+): string => {
+  if (!authorization) {
+    throw new ErrorAuthErrorResponse(
+      'This endpoint requires the authorization header.',
+      {
+        skipLog: true,
+      },
+      'access_denied',
+    );
+  }
+
+  const authorizationParts = authorization.split(' ');
+  if (authorizationParts.length !== 2 || authorizationParts[0] !== 'Bearer') {
+    throw new ErrorAuthErrorResponse(
+      `Authorization header must have the format 'Bearer <token>'`,
+      {
+        skipLog: true,
+      },
+      'invalid_request',
+    );
+  }
+
+  return authorizationParts[1];
+};

package/src/security/authn/jwt-authn-manager.ts

@@ -0,0 +1,69 @@
+import { ErrorAuthErrorResponse } from '@errorx';
+import type { Logger } from '@logger-types';
+import type { AuthenticationManager, JWTService } from '@security-types';
+import {
+  type HeaderBasedAuthentication,
+  JWTAuthentication,
+} from '@/security/authn/authns.js';
+import { validateBearerAuthorization } from '@/security/authn/bearer-utils.js';
+
+export class JWTAuthenticationManager implements AuthenticationManager {
+  private jwtService: JWTService;
+  private iss: string;
+  private projectKey: string;
+  private logger: Logger;
+
+  constructor(opts: {
+    jwtService: JWTService;
+    iss: string;
+    projectKey: string;
+    logger: Logger;
+  }) {
+    this.jwtService = opts.jwtService;
+    this.iss = opts.iss;
+    this.projectKey = opts.projectKey;
+    this.logger = opts.logger;
+  }
+
+  async authenticate(
+    authentication: HeaderBasedAuthentication,
+  ): Promise<JWTAuthentication> {
+    const principal = authentication.getPrincipal();
+
+    const token = validateBearerAuthorization(principal.authHeader);
+
+    const decodedToken = (await this.jwtService.verify({
+      token,
+    })) as {
+      iss: string;
+      [key: string]: string;
+    };
+
+    if (decodedToken.iss !== this.iss) {
+      throw new ErrorAuthErrorResponse(
+        'Issuer in the token does not match the expected issuer.',
+        {
+          privateFields: {
+            expectedIssuer: this.iss,
+            actualIssuer: decodedToken.iss,
+          },
+        },
+      );
+    }
+
+    const projectKey = decodedToken[`${this.iss}/claims/project_key`];
+    if (projectKey !== this.projectKey) {
+      throw new ErrorAuthErrorResponse('Project key does not match.', {
+        privateFields: {
+          expectedIssuer: this.iss,
+          actualIssuer: decodedToken.iss,
+          projectKey,
+        },
+      });
+    }
+
+    return new JWTAuthentication(token, {
+      mcCustomerId: decodedToken.sub,
+    });
+  }
+}