@shopify/shopify-api 12.3.0 → 13.1.0

package/lib/session/session-utils.ts

@@ -0,0 +1,95 @@
+import {ConfigInterface} from '../base-types';
+import {SESSION_COOKIE_NAME} from '../auth/oauth/types';
+import {
+  abstractConvertRequest,
+  Cookies,
+  NormalizedResponse,
+} from '../../runtime/http';
+import {sanitizeShop} from '../utils/shop-validator';
+import {logger} from '../logger';
+import * as ShopifyErrors from '../error';
+
+import {decodeSessionToken} from './decode-session-token';
+import type {GetCurrentSessionIdParams} from './types';
+import {Session} from './session';
+
+export function getJwtSessionId(config: ConfigInterface) {
+  return (shop: string, userId: string): string => {
+    return `${sanitizeShop(config)(shop, true)}_${userId}`;
+  };
+}
+
+export function getOfflineId(config: ConfigInterface) {
+  return (shop: string): string => {
+    return `offline_${sanitizeShop(config)(shop, true)}`;
+  };
+}
+
+export function getCurrentSessionId(config: ConfigInterface) {
+  return async function getCurrentSessionId({
+    isOnline,
+    ...adapterArgs
+  }: GetCurrentSessionIdParams): Promise<string | undefined> {
+    const request = await abstractConvertRequest(adapterArgs);
+
+    const log = logger(config);
+
+    if (config.isEmbeddedApp) {
+      log.debug('App is embedded, looking for session id in JWT payload', {
+        isOnline,
+      });
+
+      const authHeader = request.headers.Authorization;
+      if (authHeader) {
+        const matches = (
+          typeof authHeader === 'string' ? authHeader : authHeader[0]
+        ).match(/^Bearer (.+)$/);
+        if (!matches) {
+          log.error('Missing Bearer token in authorization header', {isOnline});
+
+          throw new ShopifyErrors.MissingJwtTokenError(
+            'Missing Bearer token in authorization header',
+          );
+        }
+
+        const jwtPayload = await decodeSessionToken(config)(matches[1]);
+        const shop = jwtPayload.dest.replace(/^https:\/\//, '');
+
+        log.debug('Found valid JWT payload', {shop, isOnline});
+
+        if (isOnline) {
+          return getJwtSessionId(config)(shop, jwtPayload.sub);
+        } else {
+          return getOfflineId(config)(shop);
+        }
+      } else {
+        log.error(
+          'Missing Authorization header review App Bridge configuration',
+          {isOnline},
+        );
+      }
+    } else {
+      log.debug('App is not embedded, looking for session id in cookies', {
+        isOnline,
+      });
+
+      const cookies = new Cookies(request, {} as NormalizedResponse, {
+        keys: [config.apiSecretKey],
+      });
+      return cookies.getAndVerify(SESSION_COOKIE_NAME);
+    }
+
+    return undefined;
+  };
+}
+
+export function customAppSession(config: ConfigInterface) {
+  return (shop: string): Session => {
+    return new Session({
+      id: '',
+      shop: `${sanitizeShop(config)(shop, true)}`,
+      state: '',
+      isOnline: false,
+    });
+  };
+}

package/lib/session/session.ts

@@ -0,0 +1,342 @@
+/* eslint-disable no-fallthrough */
+import {InvalidSession} from '../error';
+import {OnlineAccessInfo} from '../auth/oauth/types';
+import {AuthScopes} from '../auth/scopes';
+
+import {SessionParams} from './types';
+
+const propertiesToSave = [
+  'id',
+  'shop',
+  'state',
+  'isOnline',
+  'scope',
+  'accessToken',
+  'expires',
+  'refreshToken',
+  'refreshTokenExpires',
+  'onlineAccessInfo',
+];
+
+/**
+ * Stores App information from logged in merchants so they can make authenticated requests to the Admin API.
+ */
+export class Session {
+  public static fromPropertyArray(
+    entries: [string, string | number | boolean][],
+    returnUserData = false,
+  ): Session {
+    if (!Array.isArray(entries)) {
+      throw new InvalidSession(
+        'The parameter is not an array: a Session cannot be created from this object.',
+      );
+    }
+
+    const obj = Object.fromEntries(
+      entries
+        .filter(([_key, value]) => value !== null && value !== undefined)
+        // Sanitize keys
+        .map(([key, value]) => {
+          switch (key.toLowerCase()) {
+            case 'isonline':
+              return ['isOnline', value];
+            case 'accesstoken':
+              return ['accessToken', value];
+            case 'refreshtoken':
+              return ['refreshToken', value];
+            case 'refreshtokenexpires':
+              return ['refreshTokenExpires', value];
+            case 'onlineaccessinfo':
+              return ['onlineAccessInfo', value];
+            case 'userid':
+              return ['userId', value];
+            case 'firstname':
+              return ['firstName', value];
+            case 'lastname':
+              return ['lastName', value];
+            case 'accountowner':
+              return ['accountOwner', value];
+            case 'emailverified':
+              return ['emailVerified', value];
+            default:
+              return [key.toLowerCase(), value];
+          }
+        }),
+    );
+
+    const sessionData = {} as SessionParams;
+    const onlineAccessInfo = {
+      associated_user: {},
+    } as OnlineAccessInfo;
+    Object.entries(obj).forEach(([key, value]) => {
+      switch (key) {
+        case 'isOnline':
+          if (typeof value === 'string') {
+            sessionData[key] = value.toString().toLowerCase() === 'true';
+          } else if (typeof value === 'number') {
+            sessionData[key] = Boolean(value);
+          } else {
+            sessionData[key] = value;
+          }
+          break;
+        case 'scope':
+          sessionData[key] = value.toString();
+          break;
+        case 'expires':
+          sessionData[key] = value ? new Date(Number(value)) : undefined;
+          break;
+        case 'refreshToken':
+          sessionData[key] = value ? String(value) : undefined;
+          break;
+        case 'refreshTokenExpires':
+          sessionData[key] = value ? new Date(Number(value)) : undefined;
+          break;
+        case 'onlineAccessInfo':
+          onlineAccessInfo.associated_user.id = Number(value);
+          break;
+        case 'userId':
+          if (returnUserData) {
+            onlineAccessInfo.associated_user.id = Number(value);
+            break;
+          }
+        case 'firstName':
+          if (returnUserData) {
+            onlineAccessInfo.associated_user.first_name = String(value);
+            break;
+          }
+        case 'lastName':
+          if (returnUserData) {
+            onlineAccessInfo.associated_user.last_name = String(value);
+            break;
+          }
+        case 'email':
+          if (returnUserData) {
+            onlineAccessInfo.associated_user.email = String(value);
+            break;
+          }
+        case 'accountOwner':
+          if (returnUserData) {
+            onlineAccessInfo.associated_user.account_owner = Boolean(value);
+            break;
+          }
+        case 'locale':
+          if (returnUserData) {
+            onlineAccessInfo.associated_user.locale = String(value);
+            break;
+          }
+        case 'collaborator':
+          if (returnUserData) {
+            onlineAccessInfo.associated_user.collaborator = Boolean(value);
+            break;
+          }
+        case 'emailVerified':
+          if (returnUserData) {
+            onlineAccessInfo.associated_user.email_verified = Boolean(value);
+            break;
+          }
+        // Return any user keys as passed in
+        default:
+          sessionData[key] = value;
+      }
+    });
+    if (sessionData.isOnline) {
+      sessionData.onlineAccessInfo = onlineAccessInfo;
+    }
+    const session = new Session(sessionData);
+    return session;
+  }
+
+  /**
+   * The unique identifier for the session.
+   */
+  readonly id: string;
+  /**
+   * The Shopify shop domain, such as `example.myshopify.com`.
+   */
+  public shop: string;
+  /**
+   * The state of the session. Used for the OAuth authentication code flow.
+   */
+  public state: string;
+  /**
+   * Whether the access token in the session is online or offline.
+   */
+  public isOnline: boolean;
+  /**
+   * The desired scopes for the access token, at the time the session was created.
+   */
+  public scope?: string;
+  /**
+   * The date the access token expires.
+   */
+  public expires?: Date;
+  /**
+   * The access token for the session.
+   */
+  public accessToken?: string;
+  /**
+   * The refresh token for the session.
+   */
+  public refreshToken?: string;
+  /**
+   * The date the refresh token expires.
+   */
+  public refreshTokenExpires?: Date;
+  /**
+   * Information on the user for the session. Only present for online sessions.
+   */
+  public onlineAccessInfo?: OnlineAccessInfo;
+
+  constructor(params: SessionParams) {
+    Object.assign(this, params);
+  }
+
+  /**
+   * Whether the session is active. Active sessions have an access token that is not expired, and has has the given
+   * scopes if scopes is equal to a truthy value.
+   */
+  public isActive(
+    scopes: AuthScopes | string | string[] | undefined,
+    withinMillisecondsOfExpiry = 500,
+  ): boolean {
+    const hasAccessToken = Boolean(this.accessToken);
+    const isTokenNotExpired = !this.isExpired(withinMillisecondsOfExpiry);
+    const isScopeChanged = this.isScopeChanged(scopes);
+    return !isScopeChanged && hasAccessToken && isTokenNotExpired;
+  }
+
+  /**
+   * Whether the access token includes the given scopes if they are provided.
+   */
+  public isScopeChanged(
+    scopes: AuthScopes | string | string[] | undefined,
+  ): boolean {
+    if (typeof scopes === 'undefined') {
+      return false;
+    }
+
+    return !this.isScopeIncluded(scopes);
+  }
+
+  /**
+   * Whether the access token includes the given scopes.
+   */
+  public isScopeIncluded(scopes: AuthScopes | string | string[]): boolean {
+    const requiredScopes =
+      scopes instanceof AuthScopes ? scopes : new AuthScopes(scopes);
+    const sessionScopes = new AuthScopes(this.scope);
+
+    return sessionScopes.has(requiredScopes);
+  }
+
+  /**
+   * Whether the access token is expired.
+   */
+  public isExpired(withinMillisecondsOfExpiry = 0): boolean {
+    return Boolean(
+      this.expires &&
+      this.expires.getTime() - withinMillisecondsOfExpiry < Date.now(),
+    );
+  }
+
+  /**
+   * Converts an object with data into a Session.
+   */
+  public toObject(): SessionParams {
+    const object: SessionParams = {
+      id: this.id,
+      shop: this.shop,
+      state: this.state,
+      isOnline: this.isOnline,
+    };
+
+    if (this.scope) {
+      object.scope = this.scope;
+    }
+    if (this.expires) {
+      object.expires = this.expires;
+    }
+    if (this.accessToken) {
+      object.accessToken = this.accessToken;
+    }
+    if (this.refreshToken) {
+      object.refreshToken = this.refreshToken;
+    }
+    if (this.refreshTokenExpires) {
+      object.refreshTokenExpires = this.refreshTokenExpires;
+    }
+    if (this.onlineAccessInfo) {
+      object.onlineAccessInfo = this.onlineAccessInfo;
+    }
+    return object;
+  }
+
+  /**
+   * Checks whether the given session is equal to this session.
+   */
+  public equals(other: Session | undefined): boolean {
+    if (!other) return false;
+
+    const mandatoryPropsMatch =
+      this.id === other.id &&
+      this.shop === other.shop &&
+      this.state === other.state &&
+      this.isOnline === other.isOnline;
+
+    if (!mandatoryPropsMatch) return false;
+
+    const copyA = this.toPropertyArray(true);
+    copyA.sort(([k1], [k2]) => (k1 < k2 ? -1 : 1));
+
+    const copyB = other.toPropertyArray(true);
+    copyB.sort(([k1], [k2]) => (k1 < k2 ? -1 : 1));
+
+    return JSON.stringify(copyA) === JSON.stringify(copyB);
+  }
+
+  /**
+   * Converts the session into an array of key-value pairs.
+   */
+  public toPropertyArray(
+    returnUserData = false,
+  ): [string, string | number | boolean][] {
+    return (
+      Object.entries(this)
+        .filter(
+          ([key, value]) =>
+            propertiesToSave.includes(key) &&
+            value !== undefined &&
+            value !== null,
+        )
+        // Prepare values for db storage
+        .flatMap(([key, value]): [string, string | number | boolean][] => {
+          switch (key) {
+            case 'expires':
+              return [[key, value ? value.getTime() : undefined]];
+            case 'refreshTokenExpires':
+              return [[key, value ? value.getTime() : undefined]];
+            case 'onlineAccessInfo':
+              // eslint-disable-next-line no-negated-condition
+              if (!returnUserData) {
+                return [[key, value.associated_user.id]];
+              } else {
+                return [
+                  ['userId', value?.associated_user?.id],
+                  ['firstName', value?.associated_user?.first_name],
+                  ['lastName', value?.associated_user?.last_name],
+                  ['email', value?.associated_user?.email],
+                  ['locale', value?.associated_user?.locale],
+                  ['emailVerified', value?.associated_user?.email_verified],
+                  ['accountOwner', value?.associated_user?.account_owner],
+                  ['collaborator', value?.associated_user?.collaborator],
+                ];
+              }
+            default:
+              return [[key, value]];
+          }
+        })
+        // Filter out tuples with undefined values
+        .filter(([_key, value]) => value !== undefined)
+    );
+  }
+}

package/lib/session/types.ts

@@ -0,0 +1,96 @@
+import {AdapterArgs} from '../../runtime/http';
+import {OnlineAccessInfo, OnlineAccessUser} from '../auth/oauth/types';
+
+export interface SessionParams {
+  /**
+   * The unique identifier for the session.
+   */
+  readonly id: string;
+  /**
+   * The Shopify shop domain.
+   */
+  shop: string;
+  /**
+   * The state of the session. Used for the OAuth authentication code flow.
+   */
+  state: string;
+  /**
+   * Whether the access token in the session is online or offline.
+   */
+  isOnline: boolean;
+  /**
+   * The scopes for the access token.
+   */
+  scope?: string;
+  /**
+   * The date the access token expires.
+   */
+  expires?: Date;
+  /**
+   * The access token for the session.
+   */
+  accessToken?: string;
+  /**
+   * The refresh token for the session.
+   */
+  refreshToken?: string;
+  /**
+   * The date the refresh token expires.
+   */
+  refreshTokenExpires?: Date;
+  /**
+   * Information on the user for the session. Only present for online sessions.
+   */
+  onlineAccessInfo?: OnlineAccessInfo | StoredOnlineAccessInfo;
+  /**
+   * Additional properties of the session allowing for extension
+   */
+  [key: string]: any;
+}
+
+type StoredOnlineAccessInfo = Omit<OnlineAccessInfo, 'associated_user'> & {
+  associated_user: Partial<OnlineAccessUser>;
+};
+
+export interface JwtPayload {
+  /**
+   * The shop's admin domain.
+   */
+  iss: string;
+  /**
+   * The shop's domain.
+   */
+  dest: string;
+  /**
+   * The client ID of the receiving app.
+   */
+  aud: string;
+  /**
+   * The User that the session token is intended for.
+   */
+  sub: string;
+  /**
+   * When the session token expires.
+   */
+  exp: number;
+  /**
+   * When the session token activates.
+   */
+  nbf: number;
+  /**
+   * When the session token was issued.
+   */
+  iat: number;
+  /**
+   * A secure random UUID.
+   */
+  jti: string;
+  /**
+   * A unique session ID per user and app.
+   */
+  sid: string;
+}
+
+export interface GetCurrentSessionIdParams extends AdapterArgs {
+  isOnline: boolean;
+}

package/lib/setup-jest.ts

@@ -0,0 +1,43 @@
+import {compare} from 'compare-versions';
+
+import '../adapters/mock';
+
+import {SHOPIFY_API_LIBRARY_VERSION} from './version';
+import {toMatchMadeHttpRequest} from './__test-helpers__';
+
+expect.extend({
+  toMatchMadeHttpRequest,
+  /**
+   * Checks if two dates in the form of numbers are within seconds of each other
+   *
+   * @param received First date
+   * @param compareDate Second date
+   * @param seconds The number of seconds the first and second date should be within
+   */
+  toBeWithinSecondsOf(received: number, compareDate: number, seconds: number) {
+    if (
+      received &&
+      compareDate &&
+      Math.abs(received - compareDate) <= seconds * 1000
+    ) {
+      return {
+        message: () =>
+          `expected ${received} not to be within ${seconds} seconds of ${compareDate}`,
+        pass: true,
+      };
+    } else {
+      return {
+        message: () =>
+          `expected ${received} to be within ${seconds} seconds of ${compareDate}`,
+        pass: false,
+      };
+    }
+  },
+  toBeWithinDeprecationSchedule(version: string) {
+    return {
+      message: () =>
+        `Found deprecation limited to version ${version}, please update or remove it.`,
+      pass: compare(SHOPIFY_API_LIBRARY_VERSION, version, '<'),
+    };
+  },
+});