@commercetools/checkout-payments-processor-sdk 0.0.6

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

@@ -0,0 +1,105 @@
+import { ErrorAuthErrorResponse } from '@errorx';
+import type { Logger } from '@logger-types';
+import type { AuthenticationManager, Oauth2Service } from '@security-types';
+import {
+  type HeaderBasedAuthentication,
+  Oauth2Authentication,
+} from '@/security/authn/authns.js';
+import { validateBearerAuthorization } from '@/security/authn/bearer-utils.js';
+
+interface PermissionInfo {
+  permission: string;
+  principal: string;
+}
+
+/**
+ * Oauth2AuthenticationManager is a class that implements the AuthenticationManager interface.
+ * It is used to authenticate via a specific OAuth2 token.
+ * @param opts - The options for the Oauth2AuthenticationManager.
+ * @returns A Oauth2AuthenticationManager instance.
+ */
+export class Oauth2AuthenticationManager implements AuthenticationManager {
+  private oauth2Service: Oauth2Service;
+  private clientId: string;
+  private clientSecret: string;
+  private authUrl: string;
+  private logger: Logger;
+
+  constructor(opts: {
+    oauth2Service: Oauth2Service;
+    clientId: string;
+    clientSecret: string;
+    authUrl: string;
+    logger: Logger;
+  }) {
+    this.oauth2Service = opts.oauth2Service;
+    this.clientId = opts.clientId;
+    this.clientSecret = opts.clientSecret;
+    this.authUrl = opts.authUrl;
+    this.logger = opts.logger;
+  }
+
+  async authenticate(
+    authentication: HeaderBasedAuthentication,
+  ): Promise<Oauth2Authentication> {
+    const principal = authentication.getPrincipal();
+    const authorizationHeader = principal.authHeader;
+
+    const token = validateBearerAuthorization(authorizationHeader);
+
+    const tokenIntrospectionResponseData =
+      await this.oauth2Service.introspectToken({
+        url: `${this.authUrl}/oauth/introspect`,
+        clientId: this.clientId,
+        clientSecret: this.clientSecret,
+        token,
+      });
+
+    if (!tokenIntrospectionResponseData.active) {
+      throw new ErrorAuthErrorResponse('invalid_token', {
+        skipLog: true,
+      });
+    }
+
+    const scopes = tokenIntrospectionResponseData.scope?.split(' ') ?? null;
+    if (!scopes) {
+      throw new ErrorAuthErrorResponse('Token has no scopes.', {
+        skipLog: true,
+      });
+    }
+
+    // Search for customer_id:<customer> scope
+    const customerPermission = this.searchPermission(scopes, 'customer_id');
+
+    // Search for anonymous_id:<anonymous> scope
+    const anonymousPermission = this.searchPermission(scopes, 'anonymous_id');
+
+    return new Oauth2Authentication(token, {
+      scope: tokenIntrospectionResponseData.scope,
+      clientId: tokenIntrospectionResponseData.client_id,
+      customerId: customerPermission?.principal,
+      anonymousId: anonymousPermission?.principal,
+    });
+  }
+
+  private searchPermission(
+    scopes: string[],
+    ...permissions: string[]
+  ): PermissionInfo | undefined {
+    for (const permission of permissions) {
+      // Search for customer_id:<customer> scope
+      const permissionIndex = scopes.findIndex((element) =>
+        element.startsWith(`${permission}`),
+      );
+
+      if (permissionIndex >= 0) {
+        const splitPermission = scopes[permissionIndex].split(':');
+        return {
+          permission: splitPermission[0],
+          principal: splitPermission[1],
+        };
+      }
+    }
+    return undefined;
+  }
+}

package/src/security/authn/session-header-authn-manager.ts

@@ -0,0 +1,58 @@
+import { ErrorAuthErrorResponse } from '@errorx';
+import type { Logger } from '@logger-types';
+
+import {
+  type HeaderBasedAuthentication,
+  SessionAuthentication,
+} from '@/security/authn/authns.js';
+import type { AuthenticationManager } from '@/security/authn/types/authn.type.js';
+import type { SessionService } from '@/security/services/types/session.type.js';
+
+export class SessionHeaderAuthenticationManager
+  implements AuthenticationManager
+{
+  private sessionService: SessionService;
+  private logger: Logger;
+
+  constructor(opts: {
+    sessionService: SessionService;
+    logger: Logger;
+  }) {
+    this.sessionService = opts.sessionService;
+    this.logger = opts.logger;
+  }
+
+  async authenticate(
+    authentication: HeaderBasedAuthentication,
+  ): Promise<SessionAuthentication> {
+    const principal = authentication.getPrincipal();
+    try {
+      const session = await this.sessionService.verifySession(
+        principal.authHeader,
+      );
+
+      return new SessionAuthentication(principal.authHeader, {
+        cartId: this.sessionService.getCartFromSession(session),
+        allowedPaymentMethods:
+          this.sessionService.getAllowedPaymentMethodsFromSession(session),
+        processorUrl: this.sessionService.getProcessorUrlFromSession(session),
+        paymentInterface:
+          this.sessionService.getPaymentInterfaceFromSession(session),
+        checkoutTransactionItemId:
+          this.sessionService.getCheckoutTransactionItemIdFromSession(session),
+        merchantReturnUrl:
+          this.sessionService.getMerchantReturnUrlFromSession(session),
+        futureOrderNumber:
+          this.sessionService.getFutureOrderNumberFromSession(session),
+        giftCardPlannedAmount:
+          this.sessionService.getGiftCardPlannedAmountFromSession(session),
+        correlationId: this.sessionService.getCorrelationIdFromSession(session),
+      });
+    } catch (e) {
+      this.logger.error({ err: e }, 'Failed to authenticate session');
+      throw new ErrorAuthErrorResponse('Session is not active', {
+        cause: e as Error,
+      });
+    }
+  }
+}

package/src/security/authn/session-query-param-authn-manager.ts

@@ -0,0 +1,53 @@
+import { ErrorAuthErrorResponse } from '@errorx';
+import type { Logger } from '@logger-types';
+import type { AuthenticationManager, SessionService } from '@security-types';
+import {
+  type QueryParamBasedAuthentication,
+  SessionAuthentication,
+} from '@/security/authn/authns.js';
+
+export class SessionQueryParamAuthenticationManager
+  implements AuthenticationManager
+{
+  private sessionService: SessionService;
+  private logger: Logger;
+
+  constructor(opts: {
+    sessionService: SessionService;
+    logger: Logger;
+  }) {
+    this.sessionService = opts.sessionService;
+    this.logger = opts.logger;
+  }
+
+  async authenticate(
+    authentication: QueryParamBasedAuthentication,
+  ): Promise<SessionAuthentication> {
+    const principal = authentication.getPrincipal();
+    try {
+      const session = await this.sessionService.verifySession(
+        principal.authQueryParam,
+      );
+
+      return new SessionAuthentication(principal.authQueryParam, {
+        cartId: this.sessionService.getCartFromSession(session),
+        allowedPaymentMethods:
+          this.sessionService.getAllowedPaymentMethodsFromSession(session),
+        processorUrl: this.sessionService.getProcessorUrlFromSession(session),
+        paymentInterface:
+          this.sessionService.getPaymentInterfaceFromSession(session),
+        checkoutTransactionItemId:
+          this.sessionService.getCheckoutTransactionItemIdFromSession(session),
+        merchantReturnUrl:
+          this.sessionService.getMerchantReturnUrlFromSession(session),
+        futureOrderNumber:
+          this.sessionService.getFutureOrderNumberFromSession(session),
+      });
+    } catch (e) {
+      this.logger.error({ err: e }, 'Failed to authenticate session');
+      throw new ErrorAuthErrorResponse('Session is not active', {
+        cause: e as Error,
+      });
+    }
+  }
+}

package/src/security/authn/types/authn.type.ts

@@ -0,0 +1,50 @@
+import type { Money } from '@commercetools/platform-sdk';
+
+export interface AuthenticationManager {
+  authenticate(
+    authentication: Authentication,
+  ): Promise<Authentication> | Authentication;
+}
+
+export interface Authentication<Principal = unknown, Credentials = unknown> {
+  hasPrincipal(): boolean;
+  getAuthorities(): string[];
+  hasCredentials(): boolean;
+  getPrincipal(): Principal;
+  getCredentials(): Credentials;
+  isAuthenticated(): boolean;
+}
+
+export type HeaderPrincipal = {
+  authHeader: string;
+};
+
+export type QueryParamPrincipal = {
+  authQueryParam: string;
+};
+
+export type SessionPrincipal = {
+  cartId: string;
+  allowedPaymentMethods: string[];
+  processorUrl: string;
+  /**
+   * @deprecated use checkoutTransactionItemId instead
+   */
+  paymentInterface?: string;
+  checkoutTransactionItemId?: string;
+  merchantReturnUrl?: string;
+  futureOrderNumber?: string;
+  giftCardPlannedAmount?: Money;
+  correlationId?: string;
+};
+
+export type Oauth2Principal = {
+  clientId: string;
+  scope: string;
+  customerId?: string;
+  anonymousId?: string;
+};
+
+export type JWTPrincipal = {
+  mcCustomerId?: string;
+};

package/src/security/authz/authorization-manager.ts

@@ -0,0 +1,39 @@
+import { ErrorAuthErrorResponse } from '@errorx';
+import type { Logger } from '@logger-types';
+import type { Authentication, AuthorizationManager } from '@security-types';
+
+export class AuthorityAuthorizationManager
+  implements AuthorizationManager<string[]>
+{
+  private logger: Logger;
+
+  constructor(opts: { logger: Logger }) {
+    this.logger = opts.logger;
+  }
+
+  verify(authentication: Authentication, authorities: string[]) {
+    const isAuthorized = this.check(authentication, authorities);
+    if (!isAuthorized) {
+      throw new ErrorAuthErrorResponse('Not authorized', {
+        skipLog: true,
+        fields: {
+          validAuthorities: authorities,
+        },
+        privateFields: {
+          grantedAuthorities: authentication.getAuthorities(),
+          requiredAuthorities: authorities,
+        },
+      });
+    }
+  }
+
+  check(authentication: Authentication, authorities: string[]) {
+    const grantedAuthorities = authentication.getAuthorities();
+    const hasGrantedAuthorities = authorities.some((authority) => {
+      return grantedAuthorities.find(
+        (grantedAuthority: string) => grantedAuthority === authority,
+      );
+    });
+    return hasGrantedAuthorities;
+  }
+}

package/src/security/authz/types/authz.type.ts

@@ -0,0 +1,13 @@
+import type { Authentication } from '@/security/authn/types/authn.type.js';
+
+export interface AuthorizationManager<T> {
+  /**
+   * Determines if access should be granted for a specific authentication and object.
+   */
+  verify(authentication: Authentication, object: T): void;
+
+  /**
+   * Determines if access is granted for a specific object.
+   */
+  check(authentication: Authentication, object: T): boolean;
+}

package/src/security/index.ts

@@ -0,0 +1,13 @@
+// authn
+export * from '@/security/authn/authns.js';
+export * from '@/security/authn/jwt-authn-manager.js';
+export * from '@/security/authn/oauth2-authn-manager.js';
+export * from '@/security/authn/session-header-authn-manager.js';
+export * from '@/security/authn/session-query-param-authn-manager.js';
+// authz
+export * from '@/security/authz/authorization-manager.js';
+export * from '@/security/services/authorization.service.js';
+// services
+export * from '@/security/services/jwt.service.js';
+export * from '@/security/services/oauth2.service.js';
+export * from '@/security/services/session.service.js';

package/src/security/services/authorization.service.ts

@@ -0,0 +1,54 @@
+import { ErrorGeneral } from '@errorx';
+import type { Logger } from '@logger-types';
+import type { Fetch } from '@/fetch/types/fetch.type.js';
+import type {
+  AuthorizationService,
+  CommercetoolsToken,
+} from '@/security/services/types/authorization.type.js';
+
+export class DefaultAuthorizationService implements AuthorizationService {
+  private authUrl: string;
+  private clientId: string;
+  private clientSecret: string;
+  private fetch: Fetch;
+  private logger: Logger;
+
+  constructor(opts: {
+    authUrl: string;
+    clientId: string;
+    clientSecret: string;
+    fetch: Fetch;
+    logger: Logger;
+  }) {
+    this.authUrl = opts.authUrl;
+    this.clientId = opts.clientId;
+    this.clientSecret = opts.clientSecret;
+    this.fetch = opts.fetch;
+    this.logger = opts.logger;
+  }
+
+  async getAccessToken(): Promise<CommercetoolsToken> {
+    const encodedCredentials = btoa(`${this.clientId}:${this.clientSecret}`);
+    const urlencoded = new URLSearchParams();
+    urlencoded.append('grant_type', 'client_credentials');
+    const response = await this.fetch(`${this.authUrl}/oauth/token`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Authorization: `Basic ${encodedCredentials}`,
+      },
+      body: urlencoded,
+    });
+
+    if (!response.ok) {
+      throw new ErrorGeneral(undefined, {
+        privateMessage: 'Failed to get auth token',
+        privateFields: {
+          responseStatus: response.status,
+          responseText: await response.text(),
+        },
+      });
+    }
+    return (await response.json()) as CommercetoolsToken;
+  }
+}

package/src/security/services/jwt.service.test.ts

@@ -0,0 +1,27 @@
+import { CommercetoolsLogger } from '@logger';
+import { RequestContextProvider } from '@/api/index.js';
+import { DefaultJWTService } from '@/security/services/jwt.service.js';
+
+describe('jwt', () => {
+  test('wrong jwt', async () => {
+    const projectKey = 'test';
+    const contextProvider = new RequestContextProvider({
+      getContextFn: () => ({
+        correlationId: 'correlation-id',
+        requestId: 'request-id',
+      }),
+      updateContextFn: () => {},
+    });
+    const logger = new CommercetoolsLogger({ contextProvider, projectKey });
+    const jwtService = new DefaultJWTService({
+      jwksUrl: `http://localhost:9000/jwt/.well-known/jwks.json`,
+      logger,
+    });
+
+    const verifyPromise = jwtService.verify({
+      token: `some.wrong.token`,
+    });
+
+    await expect(verifyPromise).rejects.toThrow('invalid token');
+  });
+});

package/src/security/services/jwt.service.ts

@@ -0,0 +1,45 @@
+import { ErrorAuthErrorResponse } from '@errorx';
+import type { Logger } from '@logger-types';
+import type { JWTService } from '@security-types';
+import jwt, { type JwtHeader, type SigningKeyCallback } from 'jsonwebtoken';
+import jwksClient from 'jwks-rsa';
+
+export class DefaultJWTService implements JWTService {
+  private client: jwksClient.JwksClient;
+  private logger: Logger;
+
+  constructor(opts: { jwksUrl: string; logger: Logger }) {
+    this.client = jwksClient({
+      jwksUri: opts.jwksUrl,
+    });
+    this.logger = opts.logger;
+  }
+
+  async verify(opts: { token: string | undefined }) {
+    const getKey = (header: JwtHeader, callback: SigningKeyCallback) => {
+      this.client.getSigningKey(header.kid, (err, key) => {
+        if (err) {
+          return callback(err);
+        }
+        const signingKey = key?.getPublicKey();
+        callback(null, signingKey);
+      });
+    };
+    return new Promise((resolve, reject) => {
+      if (!opts.token) {
+        throw new ErrorAuthErrorResponse('Token is missing');
+      }
+      jwt.verify(opts.token, getKey, {}, (err, decoded) => {
+        if (err) {
+          return reject(
+            new ErrorAuthErrorResponse(err.message, {
+              privateMessage: err.message,
+              cause: err,
+            }),
+          );
+        }
+        return resolve(decoded);
+      });
+    });
+  }
+}

package/src/security/services/oauth2.service.ts

@@ -0,0 +1,60 @@
+import { ErrorAuthErrorResponse, ErrorGeneral } from '@errorx';
+import type { Logger } from '@logger-types';
+import type { Oauth2Service, TokenInfo } from '@security-types';
+
+export class DefaultOauth2Service implements Oauth2Service {
+  private logger: Logger;
+  constructor(opts: { logger: Logger }) {
+    this.logger = opts.logger;
+  }
+
+  async introspectToken(opts: {
+    url: string;
+    clientId: string;
+    clientSecret: string;
+    token: string;
+  }) {
+    const urlencoded = new URLSearchParams();
+    urlencoded.append('token', opts.token);
+
+    const tokenResponse = await fetch(opts.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Authorization: `Basic ${btoa(`${opts.clientId}:${opts.clientSecret}`)}`,
+      },
+      body: urlencoded,
+    });
+
+    if (tokenResponse.status > 299) {
+      if (tokenResponse.status === 401) {
+        const tokenResponseJson = (await tokenResponse.json()) as {
+          message: string;
+          error: string;
+        };
+        throw new ErrorAuthErrorResponse(
+          tokenResponseJson.message,
+          {
+            privateFields: {
+              clientId: opts.clientId,
+              status: tokenResponse.status,
+            },
+            skipLog: true,
+          },
+          tokenResponseJson.error,
+        );
+      }
+
+      throw new ErrorGeneral('Failed to authorize request.', {
+        privateMessage: 'some error happened while requesting token from coco',
+        privateFields: {
+          clientId: opts.clientId,
+          status: tokenResponse.status,
+        },
+        skipLog: true,
+      });
+    }
+
+    return (await tokenResponse.json()) as TokenInfo;
+  }
+}

package/src/security/services/session.service.ts

@@ -0,0 +1,141 @@
+import type { Money } from '@commercetools/platform-sdk';
+import { ErrorAuthErrorResponse, ErrorGeneral } from '@errorx';
+import type { Logger } from '@logger-types';
+import type {
+  AuthorizationService,
+  CommercetoolsToken,
+  Session,
+  SessionService,
+} from '@security-types';
+
+export class DefaultSessionService implements SessionService {
+  private authorizationService: AuthorizationService;
+  private sessionUrl: string;
+  private projectKey: string;
+  protected token: CommercetoolsToken | undefined;
+  private logger: Logger;
+
+  constructor(opts: {
+    authorizationService: AuthorizationService;
+    sessionUrl: string;
+    projectKey: string;
+    logger: Logger;
+  }) {
+    this.authorizationService = opts.authorizationService;
+    this.sessionUrl = opts.sessionUrl;
+    this.projectKey = opts.projectKey;
+    this.logger = opts.logger;
+  }
+
+  async verifySession(sessionId: string): Promise<Session> {
+    if (!this.token) {
+      this.token = await this.authorizationService.getAccessToken();
+    }
+
+    let res = await this.getSession(sessionId);
+    // If commercetools oauth token is expired, get a new one and retry
+    if (res.status === 401 || res.status === 403) {
+      this.token = await this.authorizationService.getAccessToken();
+      res = await this.getSession(sessionId);
+    }
+
+    if (res.status === 404) {
+      throw new ErrorAuthErrorResponse('commercetools session not found', {
+        privateFields: {
+          status: res.status,
+          statusText: res.statusText,
+        },
+      });
+    }
+
+    if (!res.ok) {
+      throw new ErrorGeneral('Could not get commercetools session', {
+        privateFields: {
+          status: res.status,
+          statusText: res.statusText,
+        },
+      });
+    }
+
+    const session = (await res.json()) as Session;
+    if (session.state !== 'ACTIVE') {
+      throw new ErrorAuthErrorResponse(
+        `commercetools session is not ACTIVE, current status: ${session.state}`,
+        {
+          privateFields: {
+            session: JSON.stringify(session),
+          },
+        },
+      );
+    }
+    return session;
+  }
+
+  getCartFromSession(session: Session): string {
+    if (!session.activeCart?.cartRef?.id) {
+      throw new ErrorAuthErrorResponse(
+        'Cart not found in commercetools session',
+        {
+          privateFields: {
+            session: JSON.stringify(session),
+          },
+        },
+      );
+    }
+    return session.activeCart.cartRef.id;
+  }
+
+  getAllowedPaymentMethodsFromSession(session: Session): string[] {
+    return (session.metadata?.allowedPaymentMethods as string[]) || [];
+  }
+
+  getProcessorUrlFromSession(session: Session): string {
+    return session.metadata?.processorUrl as string;
+  }
+
+  getPaymentInterfaceFromSession(session: Session): string | undefined {
+    return session.metadata?.paymentInterface as string | undefined;
+  }
+
+  getCheckoutTransactionItemIdFromSession(
+    session: Session,
+  ): string | undefined {
+    return session.metadata?.checkoutTransactionItemId as string | undefined;
+  }
+
+  getMerchantReturnUrlFromSession(session: Session): string | undefined {
+    return session.metadata?.merchantReturnUrl as string | undefined;
+  }
+
+  getFutureOrderNumberFromSession(session: Session): string | undefined {
+    return session.metadata?.futureOrderNumber as string | undefined;
+  }
+
+  getGiftCardPlannedAmountFromSession(session: Session): Money | undefined {
+    return session.metadata?.giftCardPlannedAmount as Money;
+  }
+
+  getCorrelationIdFromSession(session: Session): string | undefined {
+    return session.metadata?.correlationId as string | undefined;
+  }
+
+  private async getSession(sessionId: string) {
+    if (!this.token) {
+      throw new ErrorAuthErrorResponse('Token not found', {
+        privateFields: {
+          token: this.token,
+        },
+      });
+    }
+    return await fetch(
+      `${this.sessionUrl}/${this.projectKey}/sessions/${sessionId}`,
+      {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.token.access_token}`,
+        },
+      },
+    );
+  }
+}

package/src/security/services/types/authorization.type.ts

@@ -0,0 +1,10 @@
+export type CommercetoolsToken = {
+  access_token: string;
+  token_type: string;
+  scope: string;
+  expires_in: number;
+};
+
+export interface AuthorizationService {
+  getAccessToken(): Promise<CommercetoolsToken>;
+}

package/src/security/services/types/jwt.type.ts

@@ -0,0 +1,3 @@
+export interface JWTService {
+  verify(opts: { token: string | undefined }): Promise<unknown>;
+}