@shopify/shopify-app-remix 4.1.0 → 4.2.0

package/src/server/authenticate/admin/helpers/ensure-app-is-embedded-if-required.ts

@@ -0,0 +1,18 @@
+import {BasicParams} from '../../../types';
+
+import {redirectToShopifyOrAppRoot} from './redirect-to-shopify-or-app-root';
+
+export const ensureAppIsEmbeddedIfRequired = async (
+  params: BasicParams,
+  request: Request,
+) => {
+  const {api, logger, config} = params;
+  const url = new URL(request.url);
+
+  const shop = url.searchParams.get('shop')!;
+
+  if (api.config.isEmbeddedApp && url.searchParams.get('embedded') !== '1') {
+    logger.debug('App is not embedded, redirecting to Shopify', {shop});
+    await redirectToShopifyOrAppRoot(request, {api, logger, config});
+  }
+};

package/src/server/authenticate/admin/helpers/ensure-session-token-search-param-if-required.ts

@@ -0,0 +1,25 @@
+import {BasicParams} from '../../../types';
+
+import {redirectToBouncePage} from './redirect-to-bounce-page';
+
+const SESSION_TOKEN_PARAM = 'id_token';
+
+export const ensureSessionTokenSearchParamIfRequired = async (
+  params: BasicParams,
+  request: Request,
+) => {
+  const {api, logger} = params;
+  const url = new URL(request.url);
+
+  const shop = url.searchParams.get('shop')!;
+  const searchParamSessionToken = url.searchParams.get(SESSION_TOKEN_PARAM);
+  const isEmbedded = url.searchParams.get('embedded') === '1';
+
+  if (api.config.isEmbeddedApp && isEmbedded && !searchParamSessionToken) {
+    logger.debug(
+      'Missing session token in search params, going to bounce page',
+      {shop},
+    );
+    redirectToBouncePage(params, url);
+  }
+};

package/src/server/authenticate/admin/helpers/handle-client-error.ts

@@ -0,0 +1,45 @@
+import {HttpResponseError} from '@shopify/shopify-api';
+
+import type {HandleAdminClientError} from '../../../clients/admin/types';
+import {HandleClientErrorOptions} from '../strategies/types';
+
+export function handleClientErrorFactory({
+  request,
+  onError,
+}: HandleClientErrorOptions): HandleAdminClientError {
+  return async function handleClientError({
+    error,
+    params,
+    session,
+  }): Promise<never> {
+    if (error instanceof HttpResponseError !== true) {
+      params.logger.debug(
+        `Got a response error from the API: ${error.message}`,
+        {shop: session.shop},
+      );
+      throw error;
+    }
+
+    params.logger.debug(
+      `Got an HTTP response error from the API: ${error.message}`,
+      {
+        shop: session.shop,
+        code: error.response.code,
+        statusText: error.response.statusText,
+        body: JSON.stringify(error.response.body),
+      },
+    );
+
+    if (onError) {
+      await onError({request, session, error});
+    }
+
+    // forward a minimal copy of the upstream HTTP response instead of an Error:
+    throw new Response(JSON.stringify(error.response.body), {
+      status: error.response.code,
+      headers: {
+        'Content-Type': error.response.headers!['Content-Type'] as string,
+      },
+    });
+  };
+}

package/src/server/authenticate/admin/helpers/index.ts

@@ -0,0 +1,14 @@
+export * from './begin-auth';
+export * from './create-admin-api-context';
+export * from './ensure-app-is-embedded-if-required';
+export * from './ensure-session-token-search-param-if-required';
+export * from './handle-client-error';
+export * from './redirect-to-auth-page';
+export * from './redirect-to-bounce-page';
+export * from './redirect-to-shopify-or-app-root';
+export * from './redirect-with-app-bridge-headers';
+export * from './redirect-with-exitiframe';
+export * from './redirect';
+export * from './render-app-bridge';
+export * from './trigger-after-auth-hook';
+export * from './validate-shop-and-host-params';

package/src/server/authenticate/admin/helpers/redirect-to-auth-page.ts

@@ -0,0 +1,28 @@
+import type {BasicParams} from '../../../types';
+
+import {beginAuth} from './begin-auth';
+import {redirectWithExitIframe} from './redirect-with-exitiframe';
+import {redirectWithAppBridgeHeaders} from './redirect-with-app-bridge-headers';
+
+export async function redirectToAuthPage(
+  params: BasicParams,
+  request: Request,
+  shop: string,
+  isOnline = false,
+): Promise<never> {
+  const {config} = params;
+
+  const url = new URL(request.url);
+  const isEmbeddedRequest = url.searchParams.get('embedded') === '1';
+  const isXhrRequest = request.headers.get('authorization');
+
+  if (isXhrRequest) {
+    const redirectUri = new URL(config.auth.path, config.appUrl);
+    redirectUri.searchParams.set('shop', shop);
+    redirectWithAppBridgeHeaders(redirectUri.toString());
+  } else if (isEmbeddedRequest) {
+    redirectWithExitIframe(params, request, shop);
+  } else {
+    throw await beginAuth(params, request, isOnline, shop);
+  }
+}

package/src/server/authenticate/admin/helpers/redirect-to-bounce-page.ts

@@ -0,0 +1,23 @@
+import {redirect} from '@remix-run/server-runtime';
+
+import {BasicParams} from '../../../types';
+
+export const redirectToBouncePage = (params: BasicParams, url: URL): never => {
+  const {config} = params;
+
+  // Make sure we always point to the configured app URL so it also works behind reverse proxies (that alter the Host
+  // header).
+  const searchParams = url.searchParams;
+  searchParams.delete('id_token');
+  searchParams.set(
+    'shopify-reload',
+    `${config.appUrl}${url.pathname}?${searchParams.toString()}`,
+  );
+
+  // eslint-disable-next-line no-warning-comments
+  // TODO Make sure this works on chrome without a tunnel (weird HTTPS redirect issue)
+  // https://github.com/orgs/Shopify/projects/6899/views/1?pane=issue&itemId=28376650
+  throw redirect(
+    `${config.auth.patchSessionTokenPath}?${searchParams.toString()}`,
+  );
+};

package/src/server/authenticate/admin/helpers/redirect-to-install-page.ts

@@ -0,0 +1,53 @@
+import {redirect as remixRedirect} from '@remix-run/server-runtime';
+
+import type {BasicParams} from '../../../types';
+
+import {redirectWithAppBridgeHeaders} from './redirect-with-app-bridge-headers';
+
+export async function redirectToInstallPage(
+  params: BasicParams,
+  shop: string,
+  optionalScopes: string[] = [],
+): Promise<never> {
+  const installUrl = buildInstallUrl(params, shop, optionalScopes);
+  if (params.config.isEmbeddedApp) {
+    throw redirectWithAppBridgeHeaders(installUrl);
+  } else {
+    throw remixRedirect(installUrl);
+  }
+}
+
+function buildInstallUrl(
+  params: BasicParams,
+  shop: string,
+  optionalScopes: string[] = [],
+) {
+  const baseInstallUrl = buildBaseInstallUrl(params, shop);
+  baseInstallUrl.search = buildParamsInstallUrl(
+    params,
+    optionalScopes,
+  ).toString();
+  return baseInstallUrl.href;
+}
+
+function buildBaseInstallUrl({api}: BasicParams, shop: string) {
+  const cleanShop = api.utils.sanitizeShop(shop, true);
+  return new URL(`https://${cleanShop}/admin/oauth/install`);
+}
+
+function buildParamsInstallUrl(
+  {config}: BasicParams,
+  optionalScopes: string[] = [],
+) {
+  const optionalScopesParam =
+    optionalScopes && optionalScopes.length > 0
+      ? {optional_scopes: optionalScopes.join(',')}
+      : undefined;
+
+  const query = {
+    client_id: config.apiKey,
+    scope: config.scopes?.toString() || '',
+    ...optionalScopesParam,
+  };
+  return new URLSearchParams(query);
+}

package/src/server/authenticate/admin/helpers/redirect-to-shopify-or-app-root.ts

@@ -0,0 +1,21 @@
+import {redirect} from '@remix-run/server-runtime';
+
+import type {BasicParams} from '../../../types';
+
+export async function redirectToShopifyOrAppRoot(
+  request: Request,
+  params: BasicParams,
+  responseHeaders?: Headers,
+): Promise<never> {
+  const {api} = params;
+  const url = new URL(request.url);
+
+  const host = api.utils.sanitizeHost(url.searchParams.get('host')!)!;
+  const shop = api.utils.sanitizeShop(url.searchParams.get('shop')!)!;
+
+  const redirectUrl = api.config.isEmbeddedApp
+    ? await api.auth.getEmbeddedAppUrl({rawRequest: request})
+    : `/?shop=${shop}&host=${encodeURIComponent(host)}`;
+
+  throw redirect(redirectUrl, {headers: responseHeaders});
+}

package/src/server/authenticate/admin/helpers/redirect-with-app-bridge-headers.ts

@@ -0,0 +1,13 @@
+import {REAUTH_URL_HEADER} from '../../const';
+
+export function redirectWithAppBridgeHeaders(redirectUri: string): never {
+  throw new Response(undefined, {
+    status: 401,
+    statusText: 'Unauthorized',
+    headers: getAppBridgeHeaders(redirectUri),
+  });
+}
+
+export function getAppBridgeHeaders(url: string) {
+  return new Headers({[REAUTH_URL_HEADER]: url});
+}

package/src/server/authenticate/admin/helpers/redirect-with-exitiframe.ts

@@ -0,0 +1,28 @@
+import {redirect} from '@remix-run/server-runtime';
+
+import type {BasicParams} from '../../../types';
+
+export function redirectWithExitIframe(
+  params: BasicParams,
+  request: Request,
+  shop: string,
+): never {
+  const {api, config} = params;
+  const url = new URL(request.url);
+
+  const queryParams = url.searchParams;
+
+  const host = api.utils.sanitizeHost(queryParams.get('host')!);
+
+  queryParams.set('shop', shop);
+
+  let destination = `${config.auth.path}?shop=${shop}`;
+
+  if (host) {
+    queryParams.set('host', host);
+    destination = `${destination}&host=${host}`;
+  }
+  queryParams.set('exitIframe', destination);
+
+  throw redirect(`${config.auth.exitIframePath}?${queryParams.toString()}`);
+}

package/src/server/authenticate/admin/helpers/redirect.ts

@@ -0,0 +1,164 @@
+import {
+  TypedResponse,
+  redirect as remixRedirect,
+} from '@remix-run/server-runtime';
+
+import {BasicParams} from '../../../types';
+import {getSessionTokenHeader} from '../../helpers/get-session-token-header';
+
+import {renderAppBridge} from './render-app-bridge';
+import {redirectWithAppBridgeHeaders} from './redirect-with-app-bridge-headers';
+
+export type RedirectTarget = '_self' | '_parent' | '_top' | '_blank';
+export type RedirectInit = number | (ResponseInit & {target?: RedirectTarget});
+export type RedirectFunction = (
+  url: string,
+  init?: RedirectInit,
+) => TypedResponse<never>;
+
+interface ParseURLOptions {
+  params: BasicParams;
+  url: string;
+  base: string;
+  shop: string;
+  init: RedirectInit;
+}
+
+interface ParsedURL {
+  url: URL;
+  target: RedirectTarget;
+}
+
+export function redirectFactory(
+  params: BasicParams,
+  request: Request,
+  shop: string,
+): RedirectFunction {
+  const {config, logger} = params;
+
+  return function redirect(url, init: RedirectInit) {
+    const {searchParams} = new URL(request.url);
+    const {url: parsedUrl, target} = parseURL({
+      params,
+      url,
+      base: config.appUrl,
+      shop,
+      init,
+    });
+
+    logger.debug('Redirecting', {shop, url: parsedUrl.toString()});
+
+    const isSameOrigin = parsedUrl.origin === config.appUrl;
+    if (isSameOrigin || url.startsWith('/')) {
+      searchParams.forEach((value, key) => {
+        if (!parsedUrl.searchParams.has(key)) {
+          parsedUrl.searchParams.set(key, value);
+        }
+      });
+    }
+
+    if (target === '_self') {
+      if (isBounceRequest(request)) {
+        throw renderAppBridge(params, request, {
+          url: parsedUrl.toString(),
+          target,
+        });
+      } else {
+        return remixRedirect(parsedUrl.toString(), init);
+      }
+    } else if (isDataRequest(request)) {
+      throw redirectWithAppBridgeHeaders(parsedUrl.toString());
+    } else if (isEmbeddedRequest(request)) {
+      throw renderAppBridge(params, request, {
+        url: parsedUrl.toString(),
+        target,
+      });
+    }
+    return remixRedirect(url, init);
+  };
+}
+
+function isBounceRequest(request: Request) {
+  return (
+    Boolean(getSessionTokenHeader(request)) &&
+    request.headers.has('X-Shopify-Bounce')
+  );
+}
+
+function isDataRequest(request: Request) {
+  const isGet = request.method === 'GET';
+  const sessionTokenHeader = Boolean(getSessionTokenHeader(request));
+
+  return (
+    sessionTokenHeader &&
+    !isBounceRequest(request) &&
+    (!isEmbeddedRequest(request) || !isGet)
+  );
+}
+
+function isEmbeddedRequest(request: Request) {
+  const {searchParams} = new URL(request.url);
+
+  return searchParams.get('embedded') === '1';
+}
+
+function parseURL({params, base, init, shop, url}: ParseURLOptions): ParsedURL {
+  let target: RedirectTarget | undefined =
+    typeof init !== 'number' && init?.target ? init.target : undefined;
+
+  if (isAdminRemotePath(url)) {
+    const {config} = params;
+
+    const adminPath = getAdminRemotePath(url);
+    const cleanShopName = shop.replace('.myshopify.com', '');
+
+    if (!target) {
+      target = config.isEmbeddedApp ? '_parent' : '_self';
+    }
+
+    return {
+      url: new URL(
+        `https://admin.shopify.com/store/${cleanShopName}${adminPath}`,
+      ),
+      target,
+    };
+  } else {
+    return {
+      url: new URL(url, base),
+      target: target ?? '_self',
+    };
+  }
+}
+
+const ADMIN_REGEX = /^shopify:\/*admin\//i;
+
+function isAdminRemotePath(url: string) {
+  return ADMIN_REGEX.test(url);
+}
+
+function getAdminRemotePath(url: string | URL) {
+  const parsedUrl = removeRestrictedParams(new URL(url)).href;
+  return parsedUrl.replace(ADMIN_REGEX, '/');
+}
+
+const embeddedFrameParamsToRemove = [
+  'hmac',
+  'locale',
+  'protocol',
+  'session',
+  'id_token',
+  'shop',
+  'timestamp',
+  'host',
+  'embedded',
+  // sent when clicking rel="home" nav item
+  'appLoadId',
+];
+
+function removeRestrictedParams(url: URL | string) {
+  const newUrl = new URL(url);
+  embeddedFrameParamsToRemove.forEach((param) =>
+    newUrl.searchParams.delete(param),
+  );
+  return newUrl;
+}

package/src/server/authenticate/admin/helpers/render-app-bridge.ts

@@ -0,0 +1,46 @@
+import {BasicParams} from '../../../types';
+import {appBridgeUrl} from '../../helpers/app-bridge-url';
+import {addDocumentResponseHeaders} from '../../helpers/add-response-headers';
+
+import {sanitizeRedirectUrl} from './validate-redirect-url';
+
+import type {RedirectTarget} from '.';
+
+export interface RedirectToOptions {
+  url: string | URL;
+  target?: RedirectTarget;
+}
+
+export function renderAppBridge(
+  {config}: BasicParams,
+  request: Request,
+  redirectTo?: RedirectToOptions,
+): never {
+  let redirectToScript = '';
+  if (redirectTo) {
+    const destination = sanitizeRedirectUrl(config.appUrl, redirectTo.url);
+
+    const target = redirectTo.target ?? '_top';
+
+    redirectToScript = `<script>window.open(${JSON.stringify(
+      destination.toString(),
+    )}, ${JSON.stringify(target)})</script>`;
+  }
+
+  const responseHeaders = new Headers({
+    'content-type': 'text/html;charset=utf-8',
+  });
+  addDocumentResponseHeaders(
+    responseHeaders,
+    config.isEmbeddedApp,
+    new URL(request.url).searchParams.get('shop'),
+  );
+
+  throw new Response(
+    `
+      <script data-api-key="${config.apiKey}" src="${appBridgeUrl()}"></script>
+      ${redirectToScript}
+    `,
+    {headers: responseHeaders},
+  );
+}

package/src/server/authenticate/admin/helpers/trigger-after-auth-hook.ts

@@ -0,0 +1,29 @@
+import {Session} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../../types';
+import {AuthorizationStrategy} from '../strategies/types';
+
+import {createAdminApiContext} from './create-admin-api-context';
+
+export async function triggerAfterAuthHook(
+  params: BasicParams,
+  session: Session,
+  request: Request,
+  authStrategy: AuthorizationStrategy,
+) {
+  const {config, logger} = params;
+  if (config.hooks.afterAuth) {
+    logger.info('Running afterAuth hook', {shop: session.shop});
+
+    const admin = createAdminApiContext(
+      session,
+      params,
+      authStrategy.handleClientError(request),
+    );
+
+    await config.hooks.afterAuth({
+      session,
+      admin,
+    });
+  }
+}

package/src/server/authenticate/admin/helpers/validate-redirect-url.ts

@@ -0,0 +1,67 @@
+import {ShopifyError} from '@shopify/shopify-api';
+
+interface Options {
+  requireSSL?: boolean;
+  throwOnInvalid?: boolean;
+}
+
+type SanitizedRedirectUrl<OptionsArg extends Options> =
+  OptionsArg['throwOnInvalid'] extends false ? URL | undefined : URL;
+
+const FILE_URI_MATCH = /\/\/\//;
+const INVALID_RELATIVE_URL = /[/\\][/\\]/;
+const WHITESPACE_CHARACTER = /\s/;
+const VALID_PROTOCOLS = ['https:', 'http:'];
+
+function isSafe(
+  domain: string,
+  redirectUrl: unknown,
+  requireSSL: boolean | undefined = true,
+): redirectUrl is string {
+  if (typeof redirectUrl !== 'string') {
+    return false;
+  }
+
+  if (
+    FILE_URI_MATCH.test(redirectUrl) ||
+    WHITESPACE_CHARACTER.test(redirectUrl)
+  ) {
+    return false;
+  }
+
+  let url: URL;
+
+  try {
+    url = new URL(redirectUrl, domain);
+  } catch (error) {
+    return false;
+  }
+
+  if (INVALID_RELATIVE_URL.test(url.pathname)) {
+    return false;
+  }
+
+  if (!VALID_PROTOCOLS.includes(url.protocol)) {
+    return false;
+  }
+
+  if (requireSSL && url.protocol !== 'https:') {
+    return false;
+  }
+
+  return true;
+}
+
+export function sanitizeRedirectUrl<OptionsArg extends Options>(
+  domain: string,
+  redirectUrl: unknown,
+  options: OptionsArg = {} as OptionsArg,
+): SanitizedRedirectUrl<OptionsArg> {
+  if (isSafe(domain, redirectUrl, options.requireSSL)) {
+    return new URL(redirectUrl, domain) as SanitizedRedirectUrl<OptionsArg>;
+  } else if (options.throwOnInvalid === false) {
+    return undefined as SanitizedRedirectUrl<OptionsArg>;
+  } else {
+    throw new ShopifyError('Invalid URL. Refusing to redirect');
+  }
+}

package/src/server/authenticate/admin/helpers/validate-shop-and-host-params.ts

@@ -0,0 +1,46 @@
+import {redirect} from '@remix-run/server-runtime';
+
+import {BasicParams} from '../../../types';
+
+export function validateShopAndHostParams(
+  params: BasicParams,
+  request: Request,
+) {
+  const {api, config, logger} = params;
+
+  if (config.isEmbeddedApp) {
+    const url = new URL(request.url);
+    const shop = api.utils.sanitizeShop(url.searchParams.get('shop')!);
+    if (!shop) {
+      logger.debug('Missing or invalid shop, redirecting to login path', {
+        shop,
+      });
+      throw redirectToLoginPath(request, params);
+    }
+
+    const host = api.utils.sanitizeHost(url.searchParams.get('host')!);
+    if (!host) {
+      logger.debug('Invalid host, redirecting to login path', {
+        shop,
+        host: url.searchParams.get('host'),
+      });
+      throw redirectToLoginPath(request, params);
+    }
+  }
+}
+
+function redirectToLoginPath(request: Request, params: BasicParams): never {
+  const {config, logger} = params;
+
+  const {pathname} = new URL(request.url);
+  if (pathname === config.auth.loginPath) {
+    const message =
+      `Detected call to shopify.authenticate.admin() from configured login path ` +
+      `('${config.auth.loginPath}'), please make sure to call shopify.login() from that route instead.`;
+
+    logger.debug(message);
+    throw new Response(message, {status: 500});
+  }
+
+  throw redirect(config.auth.loginPath);
+}

package/src/server/authenticate/admin/scope/authenticate.admin.scopes.doc.ts

@@ -0,0 +1,28 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Scopes',
+  description:
+    'Contains functions used to manage scopes for your app.\n\nThis object is returned on authenticated Admin requests.',
+  category: 'APIs',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'scopes',
+      description:
+        '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.',
+      type: 'ScopesApiContext',
+    },
+  ],
+  jsDocTypeExamples: ['ScopesApiContext'],
+  related: [
+    {
+      name: 'Admin context',
+      subtitle: 'Authenticate requests from Shopify Admin.',
+      url: '/docs/api/shopify-app-remix/authenticate/admin',
+    },
+  ],
+};
+
+export default data;