@shopify/shopify-app-remix 4.1.1 → 4.2.1

package/src/server/authenticate/admin/scope/client/revoke-scopes.ts

@@ -0,0 +1,38 @@
+import {AdminApiContext} from '../../../../clients';
+
+export interface RevokeScopesResponse {
+  revoked: {
+    handle: string;
+  }[];
+  userErrors: {
+    field: string;
+    message: string;
+  }[];
+}
+
+const REVOKE_SCOPE_MUTATION = `#graphql
+mutation AppRevokeAccessScopes($scopes: [String!]!) {
+  appRevokeAccessScopes(scopes: $scopes){
+    revoked {
+      handle
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}`;
+
+export async function revokeScopes(
+  admin: AdminApiContext,
+  scopes: string[],
+): Promise<RevokeScopesResponse> {
+  const revokeScopesResult = await admin.graphql(REVOKE_SCOPE_MUTATION, {
+    variables: {
+      scopes,
+    },
+  });
+
+  const resultContent = await revokeScopesResult.json();
+  return resultContent.data.appRevokeAccessScopes;
+}

package/src/server/authenticate/admin/scope/factory.ts

@@ -0,0 +1,21 @@
+import {Session} from '@shopify/shopify-api';
+
+import {BasicParams} from '../../../types';
+import {AdminApiContext} from '../../../clients';
+
+import {ScopesApiContext} from './types';
+import {requestScopesFactory} from './request';
+import {queryScopesFactory} from './query';
+import {revokeScopesFactory} from './revoke';
+
+export function scopesApiFactory(
+  params: BasicParams,
+  session: Session,
+  admin: AdminApiContext,
+): ScopesApiContext {
+  return {
+    query: queryScopesFactory(params, session, admin),
+    request: requestScopesFactory(params, session, admin),
+    revoke: revokeScopesFactory(params, session, admin),
+  };
+}

package/src/server/authenticate/admin/scope/query.ts

@@ -0,0 +1,51 @@
+import {AuthScopes, Session} from '@shopify/shopify-api';
+
+import {AdminApiContext} from '../../../clients';
+import type {BasicParams} from '../../../types';
+
+import {ScopesDetail} from './types';
+import {
+  FetchScopesDetailResponse,
+  fetchScopeDetail,
+} from './client/fetch-scopes-details';
+
+export function queryScopesFactory(
+  params: BasicParams,
+  session: Session,
+  admin: AdminApiContext,
+) {
+  return async function queryScopes() {
+    const {logger} = params;
+
+    logger.debug('Querying scopes details: ', {
+      shop: session.shop,
+    });
+
+    const scopesDetail = await fetchScopeDetail(admin);
+    return mapFetchScopeDetail(scopesDetail);
+  };
+}
+
+export function mapFetchScopeDetail(
+  scopesDetailResponse: FetchScopesDetailResponse,
+): ScopesDetail {
+  const appInformation = scopesDetailResponse.app;
+
+  const granted = new AuthScopes(
+    appInformation.installation.accessScopes.map((scope) => scope.handle),
+  ).toArray(true);
+
+  const required = new AuthScopes(
+    appInformation.requestedAccessScopes.map((scope) => scope.handle),
+  ).toArray(true);
+
+  const optional = new AuthScopes(
+    appInformation.optionalAccessScopes.map((scope) => scope.handle),
+  ).toArray(true);
+
+  return {
+    granted,
+    required,
+    optional,
+  };
+}

package/src/server/authenticate/admin/scope/request.ts

@@ -0,0 +1,32 @@
+import {AuthScopes, Session} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../../types';
+import {redirectToInstallPage} from '../helpers/redirect-to-install-page';
+import {AdminApiContext} from '../../../clients';
+
+import {fetchScopeDetail} from './client/fetch-scopes-details';
+
+export function requestScopesFactory(
+  params: BasicParams,
+  session: Session,
+  admin: AdminApiContext,
+) {
+  return async function requestScopes(scopes: string[]) {
+    const {logger} = params;
+
+    logger.debug('Requesting optional scopes: ', {shop: session.shop, scopes});
+
+    if (scopes.length === 0) return;
+    if (await alreadyGranted(scopes, admin)) return;
+
+    throw await redirectToInstallPage(params, session.shop, scopes);
+  };
+
+  async function alreadyGranted(scopes: string[], admin: AdminApiContext) {
+    const scopesDetail = await fetchScopeDetail(admin);
+    const grantedScopes = scopesDetail.app.installation.accessScopes.map(
+      (scope) => scope.handle,
+    );
+    return new AuthScopes(grantedScopes).has(scopes);
+  }
+}

package/src/server/authenticate/admin/scope/revoke.ts

@@ -0,0 +1,48 @@
+import {Session} from '@shopify/shopify-api';
+
+import {AdminApiContext} from '../../../clients';
+import type {BasicParams} from '../../../types';
+
+import {revokeScopes} from './client/revoke-scopes';
+
+export function revokeScopesFactory(
+  params: BasicParams,
+  session: Session,
+  admin: AdminApiContext,
+) {
+  return async function revoke(scopes: string[]) {
+    const {logger} = params;
+
+    await validateScopes(scopes);
+
+    logger.debug('Revoke scopes: ', {
+      shop: session.shop,
+      scopes,
+    });
+
+    const revokeScopesResult = await revokeScopes(admin, scopes);
+    if (revokeScopesResult.userErrors?.length > 0) {
+      logger.error('Failed to revoke scopes: ', {
+        shop: session.shop,
+        errors: revokeScopesResult.userErrors,
+      });
+
+      throw new Response(JSON.stringify(revokeScopesResult.userErrors), {
+        status: 422,
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+    }
+
+    return {
+      revoked: revokeScopesResult.revoked.map((scope) => scope.handle),
+    };
+  };
+}
+
+async function validateScopes(scopes: string[]) {
+  if (!scopes || scopes.length === 0) {
+    throw new Response('No scopes provided', {status: 400});
+  }
+}

package/src/server/authenticate/admin/scope/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Provides utilities that apps can use to [manage scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes) for the app using the Admin API.
+ * @publicDocs
+ */
+export interface ScopesApiContext {
+  /**
+   * Queries Shopify to see what scopes have been granted
+   *
+   * @returns {ScopesDetail} The scope details.
+   *
+   * @example
+   * <caption>Query for granted scopes.</caption>
+   * <description>Call `scopes.query` to get scope details.</description>
+   * ```ts
+   * // /app._index.tsx
+   * import { authenticate } from "../shopify.server";
+   * import { json } from "@remix-run/node";
+   *
+   * export const loader = async ({ request }) => {
+   *   const { scopes } = await authenticate.admin(request);
+   *   const { required, optional, granted } = await scopes.query();
+   *
+   *   if (granted.includes("write_products")) {
+   *     // do something
+   *   }
+   *
+   *   return null
+   * };
+   *
+   * ```
+   */
+  query: () => Promise<ScopesDetail>;
+
+  /**
+   * Requests the merchant grant the provided scopes
+   *
+   * This method performs a redirect to the grant screen.
+   *
+   * @example
+   * <caption>Ask the merchant to grant the provided scopes.</caption>
+   * <description>Call `scopes.request` to request optional scopes.</description>
+   * ```ts
+   * // /app/routes/app.request.tsx
+   * import { authenticate } from "../shopify.server";
+   *
+   * // Example of an action to request optional scopes
+   * export const action = async ({ request }) => {
+   *   const { scopes } = await authenticate.admin(request);
+   *   const { granted } = await scopes.query();
+   *
+   *   if (!granted.includes("write_products")) {
+   *     await scopes.request(["write_products"]);
+   *   }
+   *
+   *   return null
+   * };
+   * ```
+   */
+  request: (scopes: Scope[]) => Promise<void>;
+
+  /**
+   * Revokes the provided scopes
+   *
+   * Warning: This method throws an [error](https://shopify.dev/docs/api/admin-graphql/unstable/objects/AppRevokeAccessScopesAppRevokeScopeError) if the provided optional scopes contains a required scope.
+   *
+   * @example
+   * <caption>Revoke optional scopes.</caption>
+   * <description>Call `scopes.revoke` to revoke optional scopes.</description>
+   * ```ts
+   * // /app._index.tsx
+   * import { authenticate } from "../shopify.server";
+   * import { json } from "@remix-run/node";
+   *
+   * // Example of an action to POST optional scopes to revoke
+   * export const action = async ({ request }) => {
+   *   const { scopes } = await authenticate.admin(request);
+   *   const { granted } = await scopes.query();
+   *
+   *   if (granted.includes("write_products")) {
+   *     const revokedResponse = await scopes.revoke(["write_products"]);
+   *     return json(revokedResponse);
+   *   }
+   *
+   *   return null
+   * };
+   *
+   * ```
+   */
+  revoke: (scopes: Scope[]) => Promise<ScopesRevokeResponse>;
+}
+
+/**
+ * `Scope` represents an [access scope](https://shopify.dev/docs/api/usage/access-scopes) handle, like "`write_products`" or "`read_orders`"
+ */
+export type Scope = string;
+
+/**
+ * `UserResult` represents the results of a user responding to a scopes request, i.e. a merchant user’s action taken when presented with a grant modal.
+ */
+export type UserResult = 'granted-all' | 'declined-all';
+
+export interface ScopesDetail {
+  /**
+   * The scopes that have been granted on the shop for this app
+   */
+  granted: Scope[];
+  /**
+   * The required scopes that the app has declared in its configuration
+   */
+  required: Scope[];
+  /**
+   * The optional scopes that the app has declared in its configuration
+   */
+  optional: Scope[];
+}
+
+export interface ScopesRequestResponse {
+  result: UserResult;
+  detail: ScopesDetail;
+}
+
+export interface ScopesRevokeResponse {
+  /**
+   * The scopes that have been revoked on the shop for this app
+   */
+  revoked: Scope[];
+}

package/src/server/authenticate/admin/strategies/auth-code-flow.ts

@@ -0,0 +1,332 @@
+import {
+  CookieNotFound,
+  GraphqlQueryError,
+  HttpResponseError,
+  InvalidHmacError,
+  InvalidOAuthError,
+  Session,
+  Shopify,
+} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../../types';
+import {
+  beginAuth,
+  handleClientErrorFactory,
+  redirectToAuthPage,
+  redirectToShopifyOrAppRoot,
+  redirectWithExitIframe,
+  triggerAfterAuthHook,
+  validateShopAndHostParams,
+} from '../helpers';
+import {AppConfig, AppConfigArg} from '../../../config-types';
+import {getSessionTokenHeader} from '../../helpers';
+import {HandleAdminClientError} from '../../../clients';
+import type {
+  ApiConfigWithFutureFlags,
+  ApiFutureFlags,
+} from '../../../future/flags';
+
+import {AuthorizationStrategy, SessionContext, OnErrorOptions} from './types';
+
+export class AuthCodeFlowStrategy<
+  Config extends AppConfigArg,
+> implements AuthorizationStrategy {
+  protected api: Shopify<
+    ApiConfigWithFutureFlags<Config['future']>,
+    ApiFutureFlags<Config['future']>
+  >;
+
+  protected config: AppConfig;
+  protected logger: Shopify['logger'];
+
+  public constructor({api, config, logger}: BasicParams) {
+    this.api = api;
+    this.config = config;
+    this.logger = logger;
+  }
+
+  public async respondToOAuthRequests(request: Request): Promise<void | never> {
+    const {api, config} = this;
+
+    const url = new URL(request.url);
+    const isAuthRequest = url.pathname === config.auth.path;
+    const isAuthCallbackRequest = url.pathname === config.auth.callbackPath;
+
+    if (isAuthRequest || isAuthCallbackRequest) {
+      const shop = api.utils.sanitizeShop(url.searchParams.get('shop')!);
+      if (!shop) throw new Response('Shop param is invalid', {status: 400});
+
+      if (isAuthRequest) {
+        throw await this.handleAuthBeginRequest(request, shop);
+      } else {
+        throw await this.handleAuthCallbackRequest(request, shop);
+      }
+    }
+
+    if (!getSessionTokenHeader(request)) {
+      // This is a document request that doesn't contain a session token. We check if the app is installed.
+      // If the app isn't installed, we initiate the OAuth auth code flow.
+      // Requests with a header can only happen after the app is installed.
+      await this.ensureInstalledOnShop(request);
+    }
+  }
+
+  public async authenticate(
+    request: Request,
+    sessionContext: SessionContext,
+  ): Promise<Session | never> {
+    const {api, config, logger} = this;
+
+    const {shop, session} = sessionContext;
+
+    if (!session) {
+      logger.debug('No session found, redirecting to OAuth', {shop});
+      await redirectToAuthPage({config, logger, api}, request, shop);
+    } else if (!session.isActive(config.scopes)) {
+      logger.debug(
+        'Found a session, but it has expired, redirecting to OAuth',
+        {shop},
+      );
+      await redirectToAuthPage({config, logger, api}, request, shop);
+    }
+
+    logger.debug('Found a valid session', {shop});
+
+    return session!;
+  }
+
+  public handleClientError(request: Request): HandleAdminClientError {
+    const {api, config, logger} = this;
+    return handleClientErrorFactory({
+      request,
+      onError: async ({session, error}: OnErrorOptions) => {
+        if (error.response.code === 401) {
+          throw await redirectToAuthPage(
+            {api, config, logger},
+            request,
+            session.shop,
+          );
+        }
+      },
+    });
+  }
+
+  private async ensureInstalledOnShop(request: Request) {
+    const {api, config, logger} = this;
+
+    validateShopAndHostParams({api, config, logger}, request);
+
+    const url = new URL(request.url);
+    let shop = url.searchParams.get('shop');
+
+    // Ensure app is installed
+    logger.debug('Ensuring app is installed on shop', {shop});
+
+    if (!(await this.hasValidOfflineId(request))) {
+      logger.info("Could not find a shop, can't authenticate request");
+      throw new Response(undefined, {
+        status: 400,
+        statusText: 'Bad Request',
+      });
+    }
+
+    const offlineSession = await this.getOfflineSession(request);
+    const isEmbedded = url.searchParams.get('embedded') === '1';
+
+    if (!offlineSession) {
+      logger.info("Shop hasn't installed app yet, redirecting to OAuth", {
+        shop,
+      });
+      if (isEmbedded) {
+        redirectWithExitIframe({api, config, logger}, request, shop!);
+      } else {
+        throw await beginAuth({api, config, logger}, request, false, shop!);
+      }
+    }
+
+    shop = shop || offlineSession.shop;
+
+    if (config.isEmbeddedApp && !isEmbedded) {
+      try {
+        logger.debug('Ensuring offline session is valid before embedding', {
+          shop,
+        });
+        await this.testSession(offlineSession);
+
+        logger.debug('Offline session is still valid, embedding app', {shop});
+      } catch (error) {
+        await this.handleInvalidOfflineSession(error, request, shop);
+      }
+    }
+  }
+
+  private async handleAuthBeginRequest(
+    request: Request,
+    shop: string,
+  ): Promise<never> {
+    const {api, config, logger} = this;
+
+    logger.info('Handling OAuth begin request', {shop});
+
+    // If we're loading from an iframe, we need to break out of it
+    if (
+      config.isEmbeddedApp &&
+      request.headers.get('Sec-Fetch-Dest') === 'iframe'
+    ) {
+      logger.debug('Auth request in iframe detected, exiting iframe', {shop});
+      throw redirectWithExitIframe({api, config, logger}, request, shop);
+    } else {
+      throw await beginAuth({api, config, logger}, request, false, shop);
+    }
+  }
+
+  private async handleAuthCallbackRequest(
+    request: Request,
+    shop: string,
+  ): Promise<never> {
+    const {api, config, logger} = this;
+
+    logger.info('Handling OAuth callback request', {shop});
+
+    try {
+      const {session, headers: responseHeaders} = await api.auth.callback({
+        rawRequest: request,
+        expiring: config.future.expiringOfflineAccessTokens,
+      });
+
+      await config.sessionStorage!.storeSession(session);
+
+      if (config.useOnlineTokens && !session.isOnline) {
+        logger.info('Requesting online access token for offline session', {
+          shop,
+        });
+        await beginAuth({api, config, logger}, request, true, shop);
+      }
+
+      logger.debug('Request is valid, loaded session from OAuth callback', {
+        shop: session.shop,
+        isOnline: session.isOnline,
+      });
+
+      await triggerAfterAuthHook({api, config, logger}, session, request, this);
+
+      throw await redirectToShopifyOrAppRoot(
+        request,
+        {api, config, logger},
+        responseHeaders,
+      );
+    } catch (error) {
+      if (error instanceof Response) throw error;
+
+      throw await this.oauthCallbackError(error, request, shop);
+    }
+  }
+
+  private async getOfflineSession(
+    request: Request,
+  ): Promise<Session | undefined> {
+    const offlineId = await this.getOfflineSessionId(request);
+    return this.config.sessionStorage!.loadSession(offlineId!);
+  }
+
+  private async hasValidOfflineId(request: Request) {
+    return Boolean(await this.getOfflineSessionId(request));
+  }
+
+  private async getOfflineSessionId(
+    request: Request,
+  ): Promise<string | undefined> {
+    const {api} = this;
+    const url = new URL(request.url);
+    const shop = url.searchParams.get('shop');
+
+    return shop
+      ? api.session.getOfflineId(shop)
+      : api.session.getCurrentId({isOnline: false, rawRequest: request});
+  }
+
+  private async testSession(session: Session): Promise<void> {
+    const {api} = this;
+
+    const client = new api.clients.Graphql({
+      session,
+    });
+
+    await client.request(`#graphql
+      query shopifyAppShopName {
+        shop {
+          name
+        }
+      }
+    `);
+  }
+
+  private async oauthCallbackError(
+    error: Error,
+    request: Request,
+    shop: string,
+  ) {
+    const {logger} = this;
+    logger.error('Error during OAuth callback', {shop, error: error.message});
+
+    if (error instanceof CookieNotFound) {
+      return this.handleAuthBeginRequest(request, shop);
+    }
+
+    if (
+      error instanceof InvalidHmacError ||
+      error instanceof InvalidOAuthError
+    ) {
+      return new Response(undefined, {
+        status: 400,
+        statusText: 'Invalid OAuth Request',
+      });
+    }
+
+    return new Response(undefined, {
+      status: 500,
+      statusText: 'Internal Server Error',
+    });
+  }
+
+  private async handleInvalidOfflineSession(
+    error: Error,
+    request: Request,
+    shop: string,
+  ) {
+    const {api, logger, config} = this;
+    if (error instanceof HttpResponseError) {
+      if (error.response.code === 401) {
+        logger.info('Shop session is no longer valid, redirecting to OAuth', {
+          shop,
+        });
+        throw await beginAuth({api, config, logger}, request, false, shop);
+      } else {
+        const message = JSON.stringify(error.response.body, null, 2);
+        logger.error(`Unexpected error during session validation: ${message}`, {
+          shop,
+        });
+
+        throw new Response(undefined, {
+          status: error.response.code,
+          statusText: error.response.statusText,
+        });
+      }
+    } else if (error instanceof GraphqlQueryError) {
+      const context: Record<string, string> = {shop};
+      if (error.response) {
+        context.response = JSON.stringify(error.body);
+      }
+
+      logger.error(
+        `Unexpected error during session validation: ${error.message}`,
+        context,
+      );
+
+      throw new Response(undefined, {
+        status: 500,
+        statusText: 'Internal Server Error',
+      });
+    }
+  }
+}