@shopify/shopify-api 12.3.0 → 13.0.0

package/lib/auth/oauth/oauth.ts

@@ -0,0 +1,260 @@
+import {isbot} from 'isbot';
+
+import {throwFailedRequest} from '../../clients/common';
+import ProcessedQuery from '../../utils/processed-query';
+import {ConfigInterface} from '../../base-types';
+import * as ShopifyErrors from '../../error';
+import {validateHmac} from '../../utils/hmac-validator';
+import {sanitizeShop} from '../../utils/shop-validator';
+import {Session} from '../../session/session';
+import {
+  abstractConvertRequest,
+  abstractConvertIncomingResponse,
+  abstractConvertResponse,
+  abstractConvertHeaders,
+  AdapterResponse,
+  AdapterHeaders,
+  Cookies,
+  NormalizedResponse,
+  NormalizedRequest,
+} from '../../../runtime/http';
+import {logger, ShopifyLogger} from '../../logger';
+import {DataType} from '../../clients/types';
+import {fetchRequestFactory} from '../../utils/fetch-request';
+
+import {
+  SESSION_COOKIE_NAME,
+  STATE_COOKIE_NAME,
+  BeginParams,
+  CallbackParams,
+  AuthQuery,
+  AccessTokenResponse,
+} from './types';
+import {nonce} from './nonce';
+import {safeCompare} from './safe-compare';
+import {createSession} from './create-session';
+
+export type OAuthBegin = (beginParams: BeginParams) => Promise<AdapterResponse>;
+
+export interface CallbackResponse<T = AdapterHeaders> {
+  headers: T;
+  session: Session;
+}
+
+export type OAuthCallback = <T = AdapterHeaders>(
+  callbackParams: CallbackParams,
+) => Promise<CallbackResponse<T>>;
+
+interface BotLog {
+  request: NormalizedRequest;
+  log: ShopifyLogger;
+  func: string;
+}
+
+const logForBot = ({request, log, func}: BotLog) => {
+  log.debug(`Possible bot request to auth ${func}: `, {
+    userAgent: request.headers['User-Agent'],
+  });
+};
+
+export function begin(config: ConfigInterface): OAuthBegin {
+  return async ({
+    shop,
+    callbackPath,
+    isOnline,
+    ...adapterArgs
+  }: BeginParams): Promise<AdapterResponse> => {
+    throwIfCustomStoreApp(
+      config.isCustomStoreApp,
+      'Cannot perform OAuth for private apps',
+    );
+
+    const log = logger(config);
+    log.info('Beginning OAuth', {shop, isOnline, callbackPath});
+
+    const request = await abstractConvertRequest(adapterArgs);
+    const response = await abstractConvertIncomingResponse(adapterArgs);
+
+    let userAgent = request.headers['User-Agent'];
+    if (Array.isArray(userAgent)) {
+      userAgent = userAgent[0];
+    }
+    if (isbot(userAgent)) {
+      logForBot({request, log, func: 'begin'});
+      response.statusCode = 410;
+      return abstractConvertResponse(response, adapterArgs);
+    }
+
+    const cookies = new Cookies(request, response, {
+      keys: [config.apiSecretKey],
+      secure: true,
+    });
+
+    const state = nonce();
+
+    await cookies.setAndSign(STATE_COOKIE_NAME, state, {
+      expires: new Date(Date.now() + 60000),
+      sameSite: 'lax',
+      secure: true,
+      path: callbackPath,
+    });
+
+    const scopes = config.scopes ? config.scopes.toString() : '';
+    const query = {
+      client_id: config.apiKey,
+      scope: scopes,
+      redirect_uri: `${config.hostScheme}://${config.hostName}${callbackPath}`,
+      state,
+      'grant_options[]': isOnline ? 'per-user' : '',
+    };
+    const processedQuery = new ProcessedQuery();
+    processedQuery.putAll(query);
+
+    const cleanShop = sanitizeShop(config)(shop, true)!;
+    const redirectUrl = `https://${cleanShop}/admin/oauth/authorize${processedQuery.stringify()}`;
+    response.statusCode = 302;
+    response.statusText = 'Found';
+    response.headers = {
+      ...response.headers,
+      ...cookies.response.headers!,
+      Location: redirectUrl,
+    };
+
+    log.debug(`OAuth started, redirecting to ${redirectUrl}`, {shop, isOnline});
+
+    return abstractConvertResponse(response, adapterArgs);
+  };
+}
+
+export function callback(config: ConfigInterface): OAuthCallback {
+  return async function callback<T = AdapterHeaders>({
+    expiring,
+    ...adapterArgs
+  }: CallbackParams): Promise<CallbackResponse<T>> {
+    throwIfCustomStoreApp(
+      config.isCustomStoreApp,
+      'Cannot perform OAuth for private apps',
+    );
+
+    const log = logger(config);
+
+    const request = await abstractConvertRequest(adapterArgs);
+
+    const query = new URL(
+      request.url,
+      `${config.hostScheme}://${config.hostName}`,
+    ).searchParams;
+    const shop = query.get('shop')!;
+
+    const response = {} as NormalizedResponse;
+    let userAgent = request.headers['User-Agent'];
+    if (Array.isArray(userAgent)) {
+      userAgent = userAgent[0];
+    }
+    if (isbot(userAgent)) {
+      logForBot({request, log, func: 'callback'});
+      throw new ShopifyErrors.BotActivityDetected(
+        'Invalid OAuth callback initiated by bot',
+      );
+    }
+
+    log.info('Completing OAuth', {shop});
+
+    const cookies = new Cookies(request, response, {
+      keys: [config.apiSecretKey],
+      secure: true,
+    });
+
+    const stateFromCookie = await cookies.getAndVerify(STATE_COOKIE_NAME);
+    cookies.deleteCookie(STATE_COOKIE_NAME);
+    if (!stateFromCookie) {
+      log.error('Could not find OAuth cookie', {shop});
+
+      throw new ShopifyErrors.CookieNotFound(
+        `Cannot complete OAuth process. Could not find an OAuth cookie for shop url: ${shop}`,
+      );
+    }
+
+    const authQuery: AuthQuery = Object.fromEntries(query.entries());
+    if (!(await validQuery({config, query: authQuery, stateFromCookie}))) {
+      log.error('Invalid OAuth callback', {shop, stateFromCookie});
+
+      throw new ShopifyErrors.InvalidOAuthError('Invalid OAuth callback.');
+    }
+
+    log.debug('OAuth request is valid, requesting access token', {shop});
+
+    const body = {
+      client_id: config.apiKey,
+      client_secret: config.apiSecretKey,
+      code: query.get('code'),
+      expiring: expiring ? '1' : '0',
+    };
+
+    const cleanShop = sanitizeShop(config)(query.get('shop')!, true)!;
+
+    const postResponse = await fetchRequestFactory(config)(
+      `https://${cleanShop}/admin/oauth/access_token`,
+      {
+        method: 'POST',
+        body: JSON.stringify(body),
+        headers: {
+          'Content-Type': DataType.JSON,
+          Accept: DataType.JSON,
+        },
+      },
+    );
+
+    if (!postResponse.ok) {
+      throwFailedRequest(await postResponse.json(), false, postResponse);
+    }
+
+    const session: Session = createSession({
+      accessTokenResponse: await postResponse.json<AccessTokenResponse>(),
+      shop: cleanShop,
+      state: stateFromCookie,
+      config,
+    });
+
+    if (!config.isEmbeddedApp) {
+      await cookies.setAndSign(SESSION_COOKIE_NAME, session.id, {
+        expires: session.expires,
+        sameSite: 'lax',
+        secure: true,
+        path: '/',
+      });
+    }
+
+    return {
+      headers: (await abstractConvertHeaders(
+        cookies.response.headers!,
+        adapterArgs,
+      )) as T,
+      session,
+    };
+  };
+}
+
+async function validQuery({
+  config,
+  query,
+  stateFromCookie,
+}: {
+  config: ConfigInterface;
+  query: AuthQuery;
+  stateFromCookie: string;
+}): Promise<boolean> {
+  return (
+    (await validateHmac(config)(query)) &&
+    safeCompare(query.state!, stateFromCookie)
+  );
+}
+
+function throwIfCustomStoreApp(
+  isCustomStoreApp: boolean,
+  message: string,
+): void {
+  if (isCustomStoreApp) {
+    throw new ShopifyErrors.PrivateAppError(message);
+  }
+}

package/lib/auth/oauth/refresh-token.ts

@@ -0,0 +1,59 @@
+import {ConfigInterface} from '../../base-types';
+import {throwFailedRequest} from '../../clients/common';
+import {DataType} from '../../clients/types';
+import {Session} from '../../session/session';
+import {fetchRequestFactory} from '../../utils/fetch-request';
+import {sanitizeShop} from '../../utils/shop-validator';
+
+import {createSession} from './create-session';
+import {AccessTokenResponse} from './types';
+
+export interface RefreshTokenParams {
+  shop: string;
+  refreshToken: string;
+}
+
+export type RefreshToken = (
+  params: RefreshTokenParams,
+) => Promise<{session: Session}>;
+
+const RefreshTokenGrantType = 'refresh_token';
+
+export function refreshToken(config: ConfigInterface): RefreshToken {
+  return async ({shop, refreshToken}: RefreshTokenParams) => {
+    const body = {
+      client_id: config.apiKey,
+      client_secret: config.apiSecretKey,
+      refresh_token: refreshToken,
+      grant_type: RefreshTokenGrantType,
+    };
+
+    const cleanShop = sanitizeShop(config)(shop, true)!;
+
+    const postResponse = await fetchRequestFactory(config)(
+      `https://${cleanShop}/admin/oauth/access_token`,
+      {
+        method: 'POST',
+        body: JSON.stringify(body),
+        headers: {
+          'Content-Type': DataType.JSON,
+          Accept: DataType.JSON,
+        },
+      },
+    );
+
+    if (!postResponse.ok) {
+      throwFailedRequest(await postResponse.json(), false, postResponse);
+    }
+
+    return {
+      session: createSession({
+        accessTokenResponse: await postResponse.json<AccessTokenResponse>(),
+        shop: cleanShop,
+        // We need to keep this as an empty string as our template DB schemas have this required
+        state: '',
+        config,
+      }),
+    };
+  };
+}

package/lib/auth/oauth/safe-compare.ts

@@ -0,0 +1,34 @@
+import * as ShopifyErrors from '../../error';
+
+export type SafeCompare = (
+  strA: string | Record<string, string> | string[] | number[],
+  strB: string | Record<string, string> | string[] | number[],
+) => boolean;
+
+export const safeCompare: SafeCompare = (strA, strB) => {
+  if (typeof strA === typeof strB) {
+    const enc = new TextEncoder();
+    const buffA = enc.encode(JSON.stringify(strA));
+    const buffB = enc.encode(JSON.stringify(strB));
+
+    if (buffA.length === buffB.length) {
+      return timingSafeEqual(buffA, buffB);
+    }
+  } else {
+    throw new ShopifyErrors.SafeCompareError(
+      `Mismatched data types provided: ${typeof strA} and ${typeof strB}`,
+    );
+  }
+  return false;
+};
+
+// Buffer must be same length for this function to be secure.
+function timingSafeEqual(bufA: ArrayBuffer, bufB: ArrayBuffer): boolean {
+  const viewA = new Uint8Array(bufA);
+  const viewB = new Uint8Array(bufB);
+  let out = 0;
+  for (let i = 0; i < viewA.length; i++) {
+    out |= viewA[i] ^ viewB[i];
+  }
+  return out === 0;
+}

package/lib/auth/oauth/token-exchange.ts

@@ -0,0 +1,79 @@
+import {throwFailedRequest} from '../../clients/common';
+import {decodeSessionToken} from '../../session/decode-session-token';
+import {sanitizeShop} from '../../utils/shop-validator';
+import {ConfigInterface} from '../../base-types';
+import {Session} from '../../session/session';
+import {DataType} from '../../clients/types';
+import {fetchRequestFactory} from '../../utils/fetch-request';
+
+import {createSession} from './create-session';
+import {AccessTokenResponse} from './types';
+
+export enum RequestedTokenType {
+  OnlineAccessToken = 'urn:shopify:params:oauth:token-type:online-access-token',
+  OfflineAccessToken = 'urn:shopify:params:oauth:token-type:offline-access-token',
+}
+
+const TokenExchangeGrantType =
+  'urn:ietf:params:oauth:grant-type:token-exchange';
+const IdTokenType = 'urn:ietf:params:oauth:token-type:id_token';
+
+export interface TokenExchangeParams {
+  shop: string;
+  sessionToken: string;
+  requestedTokenType: RequestedTokenType;
+  expiring?: boolean;
+}
+
+export type TokenExchange = (
+  params: TokenExchangeParams,
+) => Promise<{session: Session}>;
+
+export function tokenExchange(config: ConfigInterface): TokenExchange {
+  return async ({
+    shop,
+    sessionToken,
+    requestedTokenType,
+    expiring,
+  }: TokenExchangeParams) => {
+    await decodeSessionToken(config)(sessionToken);
+
+    const body = {
+      client_id: config.apiKey,
+      client_secret: config.apiSecretKey,
+      grant_type: TokenExchangeGrantType,
+      subject_token: sessionToken,
+      subject_token_type: IdTokenType,
+      requested_token_type: requestedTokenType,
+      expiring: expiring ? '1' : '0',
+    };
+
+    const cleanShop = sanitizeShop(config)(shop, true)!;
+
+    const postResponse = await fetchRequestFactory(config)(
+      `https://${cleanShop}/admin/oauth/access_token`,
+      {
+        method: 'POST',
+        body: JSON.stringify(body),
+        headers: {
+          'Content-Type': DataType.JSON,
+          Accept: DataType.JSON,
+        },
+      },
+    );
+
+    if (!postResponse.ok) {
+      throwFailedRequest(await postResponse.json(), false, postResponse);
+    }
+
+    return {
+      session: createSession({
+        accessTokenResponse: await postResponse.json<AccessTokenResponse>(),
+        shop: cleanShop,
+        // We need to keep this as an empty string as our template DB schemas have this required
+        state: '',
+        config,
+      }),
+    };
+  };
+}

package/lib/auth/oauth/types.ts

@@ -0,0 +1,111 @@
+import {AdapterArgs} from '../../../runtime/http/types';
+
+export const SESSION_COOKIE_NAME = 'shopify_app_session';
+export const STATE_COOKIE_NAME = 'shopify_app_state';
+
+export interface AuthQuery {
+  [key: string]: string | undefined;
+  hmac?: string;
+  signature?: string;
+}
+
+export interface BeginParams extends AdapterArgs {
+  /**
+   * The shop domain. For example: `{exampleshop}.myshopify.com`.
+   */
+  shop: string;
+  /**
+   * The path to the callback endpoint, with a leading `/`.
+   * This URL must be allowed in the Partners dashboard, or using the CLI to run your app.
+   */
+  callbackPath: string;
+  /**
+   * Defines if the session is online or offline.
+   * Learn more about [OAuth access modes](https://shopify.dev/docs/apps/auth/oauth/access-modes).
+   */
+  isOnline: boolean;
+}
+
+export interface CallbackParams extends AdapterArgs {
+  /**
+   * Whether the access token should be expiring. Defaults to false.
+   * Learn more about [Expiring Access Tokens](https://shopify.dev/docs/apps/auth/oauth/access-modes#expiring-access-tokens).
+   */
+  expiring?: boolean;
+}
+
+export interface AccessTokenResponse {
+  access_token: string;
+  scope: string;
+}
+
+export interface OnlineAccessInfo {
+  /**
+   * How long the access token is valid for, in seconds.
+   */
+  expires_in: number;
+  /**
+   * The effective set of scopes for the session.
+   */
+  associated_user_scope: string;
+  /**
+   * The user associated with the access token.
+   */
+  associated_user: OnlineAccessUser;
+}
+
+export interface OfflineAccessInfo {
+  /**
+   * How long the access token is valid for, in seconds.
+   */
+  expires_in?: number;
+  /**
+   * The refresh token for the session.
+   */
+  refresh_token?: string;
+  /**
+   * How long the refresh token is valid for, in seconds.
+   */
+  refresh_token_expires_in?: number;
+}
+
+export interface OnlineAccessUser {
+  /**
+   * The user's ID.
+   */
+  id: number;
+  /**
+   * The user's first name.
+   */
+  first_name: string;
+  /**
+   * The user's last name.
+   */
+  last_name: string;
+  /**
+   * The user's email address.
+   */
+  email: string;
+  /**
+   * Whether the user has verified their email address.
+   */
+  email_verified: boolean;
+  /**
+   * Whether the user is the account owner.
+   */
+  account_owner: boolean;
+  /**
+   * The user's locale.
+   */
+  locale: string;
+  /**
+   * Whether the user is a collaborator.
+   */
+  collaborator: boolean;
+}
+
+export interface OnlineAccessResponse
+  extends AccessTokenResponse, OnlineAccessInfo {}
+
+export interface OfflineAccessResponse
+  extends AccessTokenResponse, OfflineAccessInfo {}

package/lib/auth/scopes/index.ts

@@ -0,0 +1,102 @@
+/**
+ * A class that represents a set of access token scopes.
+ */
+class AuthScopes {
+  public static SCOPE_DELIMITER = ',';
+
+  private compressedScopes: Set<string>;
+  private expandedScopes: Set<string>;
+  private originalScopes: Set<string>;
+
+  constructor(scopes: string | string[] | AuthScopes | undefined) {
+    let scopesArray: string[] = [];
+    if (typeof scopes === 'string') {
+      scopesArray = scopes.split(
+        new RegExp(`${AuthScopes.SCOPE_DELIMITER}\\s*`),
+      );
+    } else if (Array.isArray(scopes)) {
+      scopesArray = scopes;
+    } else if (scopes) {
+      scopesArray = Array.from(scopes.expandedScopes);
+    }
+
+    scopesArray = scopesArray
+      .map((scope) => scope.trim())
+      .filter((scope) => scope.length);
+
+    const impliedScopes = this.getImpliedScopes(scopesArray);
+
+    const scopeSet = new Set(scopesArray);
+    const impliedSet = new Set(impliedScopes);
+
+    this.compressedScopes = new Set(
+      [...scopeSet].filter((x) => !impliedSet.has(x)),
+    );
+    this.expandedScopes = new Set([...scopeSet, ...impliedSet]);
+    this.originalScopes = scopeSet;
+  }
+
+  /**
+   * Checks whether the current set of scopes includes the given one.
+   */
+  public has(scope: string | string[] | AuthScopes | undefined) {
+    let other: AuthScopes;
+
+    if (scope instanceof AuthScopes) {
+      other = scope;
+    } else {
+      other = new AuthScopes(scope);
+    }
+
+    return (
+      other.toArray().filter((x) => !this.expandedScopes.has(x)).length === 0
+    );
+  }
+
+  /**
+   * Checks whether the current set of scopes equals the given one.
+   */
+  public equals(otherScopes: string | string[] | AuthScopes | undefined) {
+    let other: AuthScopes;
+
+    if (otherScopes instanceof AuthScopes) {
+      other = otherScopes;
+    } else {
+      other = new AuthScopes(otherScopes);
+    }
+
+    return (
+      this.compressedScopes.size === other.compressedScopes.size &&
+      this.toArray().filter((x) => !other.has(x)).length === 0
+    );
+  }
+
+  /**
+   * Returns a comma-separated string with the current set of scopes.
+   */
+  public toString() {
+    return this.toArray().join(AuthScopes.SCOPE_DELIMITER);
+  }
+
+  /**
+   * Returns an array with the current set of scopes.
+   */
+  public toArray(returnOriginalScopes = false) {
+    return returnOriginalScopes
+      ? [...this.originalScopes]
+      : [...this.compressedScopes];
+  }
+
+  private getImpliedScopes(scopesArray: string[]): string[] {
+    return scopesArray.reduce((array: string[], current: string) => {
+      const matches = current.match(/^(unauthenticated_)?write_(.*)$/);
+      if (matches) {
+        array.push(`${matches[1] ? matches[1] : ''}read_${matches[2]}`);
+      }
+
+      return array;
+    }, []);
+  }
+}
+
+export {AuthScopes};

package/lib/auth/types.ts

@@ -0,0 +1,7 @@
+import {AdapterArgs} from '../../runtime/http';
+
+export * from './oauth/types';
+export * from './scopes/index';
+export {RequestedTokenType} from './oauth/token-exchange';
+
+export interface GetEmbeddedAppUrlParams extends AdapterArgs {}