@shopify/shopify-app-remix 4.1.1 → 4.2.0

package/src/server/authenticate/admin/strategies/merchant-custom-app.ts

@@ -0,0 +1,65 @@
+import {Session, Shopify, ShopifyError} from '@shopify/shopify-api';
+
+import {AppConfig, AppConfigArg} from '../../../config-types';
+import {BasicParams} from '../../../types';
+import {ApiConfigWithFutureFlags, ApiFutureFlags} from '../../../future/flags';
+import {HandleAdminClientError} from '../../../clients';
+import {handleClientErrorFactory} from '../helpers';
+import {getShopFromRequest} from '../../helpers';
+
+import {AuthorizationStrategy, OnErrorOptions, SessionContext} from './types';
+
+export class MerchantCustomAuth<
+  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<Config['future']>) {
+    this.api = api;
+    this.config = config;
+    this.logger = logger;
+  }
+
+  public async respondToOAuthRequests(request: Request): Promise<void> {
+    this.logger.debug('Skipping OAuth request for merchant custom app', {
+      shop: getShopFromRequest(request),
+    });
+  }
+
+  public async authenticate(
+    _request: Request,
+    sessionContext: SessionContext,
+  ): Promise<Session | never> {
+    const {shop} = sessionContext;
+
+    this.logger.debug(
+      'Building session from configured access token for merchant custom app',
+      {shop},
+    );
+    const session = this.api.session.customAppSession(shop);
+
+    return session;
+  }
+
+  public handleClientError(request: Request): HandleAdminClientError {
+    return handleClientErrorFactory({
+      request,
+      onError: async ({error}: OnErrorOptions) => {
+        if (error.response.code === 401) {
+          this.logger.info(
+            'Request failed with 401. Review your API credentials or generate new tokens. https://shopify.dev/docs/apps/build/authentication-authorization/access-token-types/generate-app-access-tokens-admin#rotating-api-credentials-for-admin-created-apps ',
+          );
+          throw new ShopifyError(
+            'Unauthorized: Access token has been revoked.',
+          );
+        }
+      },
+    });
+  }
+}

package/src/server/authenticate/admin/strategies/token-exchange.ts

@@ -0,0 +1,188 @@
+import {
+  HttpResponseError,
+  InvalidJwtError,
+  RequestedTokenType,
+  Session,
+  Shopify,
+} from '@shopify/shopify-api';
+
+import {AppConfig, AppConfigArg} from '../../../config-types';
+import {BasicParams} from '../../../types';
+import {
+  respondToInvalidSessionToken,
+  invalidateAccessToken,
+  getShopFromRequest,
+} from '../../helpers';
+import {handleClientErrorFactory, triggerAfterAuthHook} from '../helpers';
+import {HandleAdminClientError} from '../../../clients';
+import type {
+  ApiConfigWithFutureFlags,
+  ApiFutureFlags,
+} from '../../../future/flags';
+import {WITHIN_MILLISECONDS_OF_EXPIRY} from '../../../helpers';
+
+import {AuthorizationStrategy, SessionContext, OnErrorOptions} from './types';
+
+export class TokenExchangeStrategy<
+  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<Config['future']>) {
+    this.api = api;
+    this.config = config;
+    this.logger = logger;
+  }
+
+  public async respondToOAuthRequests(_request: Request): Promise<void> {}
+
+  public async authenticate(
+    request: Request,
+    sessionContext: SessionContext,
+  ): Promise<Session> {
+    const {api, config, logger} = this;
+    const {shop, session, sessionToken} = sessionContext;
+
+    if (!sessionToken) throw new InvalidJwtError();
+
+    if (
+      !session ||
+      !session.isActive(undefined, WITHIN_MILLISECONDS_OF_EXPIRY)
+    ) {
+      logger.info('No valid session found', {shop});
+      logger.info('Requesting offline access token', {shop});
+      const {session: offlineSession} = await this.exchangeToken({
+        request,
+        sessionToken,
+        shop,
+        requestedTokenType: RequestedTokenType.OfflineAccessToken,
+      });
+
+      await config.sessionStorage!.storeSession(offlineSession);
+
+      let newSession = offlineSession;
+
+      if (config.useOnlineTokens) {
+        logger.info('Requesting online access token', {shop});
+        const {session: onlineSession} = await this.exchangeToken({
+          request,
+          sessionToken,
+          shop,
+          requestedTokenType: RequestedTokenType.OnlineAccessToken,
+        });
+
+        await config.sessionStorage!.storeSession(onlineSession);
+        newSession = onlineSession;
+      }
+
+      logger.debug('Request is valid, loaded session from session token', {
+        shop: newSession.shop,
+        isOnline: newSession.isOnline,
+      });
+
+      try {
+        await this.handleAfterAuthHook(
+          {api, config, logger},
+          newSession,
+          request,
+          sessionToken,
+        );
+      } catch (errorOrResponse) {
+        if (errorOrResponse instanceof Response) {
+          throw errorOrResponse;
+        }
+
+        throw new Response(undefined, {
+          status: 500,
+          statusText: 'Internal Server Error',
+        });
+      }
+
+      return newSession;
+    }
+
+    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) {
+          logger.debug('Responding to invalid access token', {
+            shop: getShopFromRequest(request),
+          });
+          await invalidateAccessToken({config, api, logger}, session);
+
+          respondToInvalidSessionToken({
+            params: {config, api, logger},
+            request,
+          });
+        }
+      },
+    });
+  }
+
+  private async exchangeToken({
+    request,
+    shop,
+    sessionToken,
+    requestedTokenType,
+  }: {
+    request: Request;
+    shop: string;
+    sessionToken: string;
+    requestedTokenType: RequestedTokenType;
+  }): Promise<{session: Session}> {
+    const {api, config, logger} = this;
+
+    try {
+      return await api.auth.tokenExchange({
+        sessionToken,
+        shop,
+        requestedTokenType,
+        expiring: config.future.expiringOfflineAccessTokens,
+      });
+    } catch (error) {
+      if (
+        error instanceof InvalidJwtError ||
+        (error instanceof HttpResponseError &&
+          error.response.code === 400 &&
+          error.response.body?.error === 'invalid_subject_token')
+      ) {
+        throw respondToInvalidSessionToken({
+          params: {api, config, logger},
+          request,
+          retryRequest: true,
+        });
+      }
+
+      throw new Response(undefined, {
+        status: 500,
+        statusText: 'Internal Server Error',
+      });
+    }
+  }
+
+  private async handleAfterAuthHook(
+    params: BasicParams,
+    session: Session,
+    request: Request,
+    sessionToken: string,
+  ) {
+    const {config} = params;
+    await config.idempotentPromiseHandler.handlePromise({
+      promiseFunction: () => {
+        return triggerAfterAuthHook(params, session, request, this);
+      },
+      identifier: sessionToken,
+    });
+  }
+}

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

@@ -0,0 +1,29 @@
+import {HttpResponseError, Session} from '@shopify/shopify-api';
+
+import {HandleAdminClientError} from '../../../clients';
+
+export interface SessionContext {
+  shop: string;
+  session?: Session;
+  sessionToken?: string;
+}
+
+export interface OnErrorOptions {
+  request: Request;
+  session: Session;
+  error: HttpResponseError;
+}
+
+export interface HandleClientErrorOptions {
+  request: Request;
+  onError?: ({session, error}: OnErrorOptions) => Promise<void | never>;
+}
+
+export interface AuthorizationStrategy {
+  respondToOAuthRequests: (request: Request) => Promise<void | never>;
+  authenticate: (
+    request: Request,
+    sessionContext: SessionContext,
+  ) => Promise<Session | never>;
+  handleClientError: (request: Request) => HandleAdminClientError;
+}

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

@@ -0,0 +1,216 @@
+import {JwtPayload, Session} from '@shopify/shopify-api';
+
+import {EnsureCORSFunction} from '../helpers/ensure-cors-headers';
+import type {AppConfigArg} from '../../config-types';
+import type {AdminApiContext} from '../../clients';
+
+import type {BillingContext} from './billing/types';
+import {RedirectFunction} from './helpers/redirect';
+import {ScopesApiContext} from './scope/types';
+
+interface AdminContextInternal<Config extends AppConfigArg> {
+  /**
+   * The session for the user who made the request.
+   *
+   * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.
+   *
+   * Use this to get shop or user-specific data.
+   *
+   * @example
+   * <caption>Using offline sessions.</caption>
+   * <description>Get your app's shop-specific data using an offline session.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { session } = await authenticate.admin(request);
+   *   return json(await getMyAppData({shop: session.shop));
+   * };
+   * ```
+   * ```ts
+   * // shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   *
+   * @example
+   * <caption>Using online sessions.</caption>
+   * <description>Get your app's user-specific data using an online session.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { session } = await authenticate.admin(request);
+   *   return json(await getMyAppData({user: session.onlineAccessInfo!.id}));
+   * };
+   * ```
+   * ```ts
+   * // shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   useOnlineTokens: true,
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   */
+  session: Session;
+
+  /**
+   * Methods for interacting with the GraphQL Admin API for the store that made the request.
+   */
+  admin: AdminApiContext;
+
+  /**
+   * Billing methods for this store, based on the plans defined in the `billing` config option.
+   *
+   * {@link https://shopify.dev/docs/apps/billing}
+   */
+  billing: BillingContext<Config>;
+
+  /**
+   * A function that ensures the CORS headers are set correctly for the response.
+   *
+   * @example
+   * <caption>Setting CORS headers for a admin request.</caption>
+   * <description>Use the `cors` helper to ensure your app can respond to requests from admin extensions.</description>
+   * ```ts
+   * // /app/routes/admin/my-route.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { session, cors } = await authenticate.admin(request);
+   *   return cors(json(await getMyAppData({user: session.onlineAccessInfo!.id})));
+   * };
+   * ```
+   */
+  cors: EnsureCORSFunction;
+}
+
+export interface EmbeddedAdminContext<
+  Config extends AppConfigArg,
+> extends AdminContextInternal<Config> {
+  /**
+   * The decoded and validated session token for the request.
+   *
+   * Returned only if `isEmbeddedApp` is `true`.
+   *
+   * {@link https://shopify.dev/docs/apps/auth/oauth/session-tokens#payload}
+   *
+   * @example
+   * <caption>Using the decoded session token.</caption>
+   * <description>Get user-specific data using the `sessionToken` object.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { sessionToken } = await authenticate.admin(
+   *     request
+   *   );
+   *   return json(await getMyAppData({user: sessionToken.sub}));
+   * };
+   * ```
+   * ```ts
+   * // shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   *   useOnlineTokens: true,
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   */
+  sessionToken: JwtPayload;
+
+  /**
+   * A function that redirects the user to a new page, ensuring that the appropriate parameters are set for embedded
+   * apps.
+   *
+   * Returned only if `isEmbeddedApp` is `true`.
+   *
+   * @example
+   * <caption>Redirecting to an app route.</caption>
+   * <description>Use the `redirect` helper to safely redirect between pages.</description>
+   * ```ts
+   * // /app/routes/admin/my-route.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { session, redirect } = await authenticate.admin(request);
+   *   return redirect("/");
+   * };
+   * ```
+   *
+   * @example
+   * <caption>Redirecting to a page in the Shopify Admin.</caption>
+   * <description>Redirects to a product page in the Shopify admin. Pass in a `target` option of `_top` or `_parent` to navigate in the current window, or `_blank` to open a new tab.</description>
+   * ```ts
+   * // /app/routes/admin/my-route.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { session, redirect } = await authenticate.admin(request);
+   *   return redirect("shopify://admin/products/123456", { target: '_parent' });
+   * };
+   * ```
+   *
+   * @example
+   * <caption>Redirecting outside of the Admin embedded app page.</caption>
+   * <description>Pass in a `target` option of `_top` or `_parent` to navigate in the current window, or `_blank` to open a new tab.</description>
+   * ```ts
+   * // /app/routes/admin/my-route.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const { session, redirect } = await authenticate.admin(request);
+   *   return redirect("/", { target: '_parent' });
+   * };
+   * ```
+   */
+  redirect: RedirectFunction;
+}
+export interface NonEmbeddedAdminContext<
+  Config extends AppConfigArg,
+> extends AdminContextInternal<Config> {}
+
+type EmbeddedTypedAdminContext<Config extends AppConfigArg> =
+  Config['isEmbeddedApp'] extends false
+    ? NonEmbeddedAdminContext<Config>
+    : EmbeddedAdminContext<Config>;
+
+export interface ScopesContext {
+  /**
+   * Methods to manage scopes for the store that made the request.
+   */
+  scopes: ScopesApiContext;
+}
+
+export type AdminContext<Config extends AppConfigArg> =
+  EmbeddedTypedAdminContext<Config> & ScopesContext;
+
+export type AuthenticateAdmin<Config extends AppConfigArg> = (
+  request: Request,
+) => Promise<AdminContext<Config>>;

package/src/server/authenticate/const.ts

@@ -0,0 +1,15 @@
+export const APP_BRIDGE_URL =
+  'https://cdn.shopify.com/shopifycloud/app-bridge.js';
+
+export const REAUTH_URL_HEADER =
+  'X-Shopify-API-Request-Failure-Reauthorize-Url';
+
+export const RETRY_INVALID_SESSION_HEADER = {
+  'X-Shopify-Retry-Invalid-Session-Request': '1',
+};
+
+export const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Headers': 'Authorization',
+  'Access-Control-Expose-Headers': REAUTH_URL_HEADER,
+};

package/src/server/authenticate/flow/authenticate.flow.doc.example.ts

@@ -0,0 +1,39 @@
+import {type ActionFunctionArgs} from '@remix-run/node';
+
+import {authenticate} from '../shopify.server';
+
+export const action = async ({request}: ActionFunctionArgs) => {
+  const {admin, payload} = await authenticate.flow(request);
+
+  const customerId = payload.properties.customer_id;
+
+  const response = await admin.graphql(
+    `#graphql
+    mutation setMetafield($customerId: ID!, $time: String!) {
+      metafieldsSet(metafields: {
+        ownerId: $customerId
+        namespace: "my-app",
+        key: "last_flow_update",
+        value: $time,
+        type: "string",
+      }) {
+        metafields {
+          key
+          value
+        }
+      }
+    }
+    `,
+    {
+      variables: {
+        customerId,
+        time: new Date().toISOString(),
+      },
+    },
+  );
+  const body = await response.json();
+
+  console.log('Updated value', body.data!.metafieldsSet!.metafields![0].value);
+
+  return new Response();
+};

package/src/server/authenticate/flow/authenticate.flow.doc.ts

@@ -0,0 +1,47 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Flow',
+  description:
+    'Contains functions for verifying Shopify Flow extensions.' +
+    '\n\nSee the [Flow documentation](https://shopify.dev/docs/apps/flow/actions/endpoints) for more information.',
+  category: 'Authenticate',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'authenticate.flow',
+      description: 'Verifies requests coming from Shopify Flow extensions.',
+      type: 'AuthenticateFlow',
+    },
+  ],
+  defaultExample: {
+    description: 'Handle a flow action call',
+    codeblock: {
+      title: 'Set a metafield on a customer after a flow call',
+      tabs: [
+        {
+          title: '/app/routes/**.ts',
+          language: 'typescript',
+          code: './authenticate.flow.doc.example.ts',
+        },
+      ],
+    },
+  },
+  jsDocTypeExamples: ['FlowContext'],
+  related: [
+    {
+      name: 'Admin API context',
+      subtitle: 'Interact with the Admin API.',
+      url: '/docs/api/shopify-app-remix/apis/admin-api',
+    },
+    {
+      name: 'Flow action endpoints',
+      subtitle: 'Receive requests from Flow.',
+      url: '/docs/apps/flow/actions/endpoints',
+      type: 'shopify',
+    },
+  ],
+};
+
+export default data;

package/src/server/authenticate/flow/authenticate.ts

@@ -0,0 +1,68 @@
+import {adminClientFactory} from '../../clients/admin';
+import {ensureValidOfflineSession} from '../../helpers';
+import {BasicParams} from '../../types';
+
+import type {AuthenticateFlow, FlowContext} from './types';
+
+export function authenticateFlowFactory(params: BasicParams): AuthenticateFlow {
+  const {api, logger} = params;
+
+  return async function authenticate(request: Request): Promise<FlowContext> {
+    logger.info('Authenticating flow request');
+
+    if (request.method !== 'POST') {
+      logger.debug(
+        'Received a non-POST request for flow. Only POST requests are allowed.',
+        {url: request.url, method: request.method},
+      );
+      throw new Response(undefined, {
+        status: 405,
+        statusText: 'Method not allowed',
+      });
+    }
+
+    const rawBody = await request.text();
+    const result = await api.flow.validate({
+      rawBody,
+      rawRequest: request,
+    });
+
+    if (!result.valid) {
+      logger.error('Received an invalid flow request', {reason: result.reason});
+
+      throw new Response(undefined, {
+        status: 400,
+        statusText: 'Bad Request',
+      });
+    }
+
+    const payload = JSON.parse(rawBody);
+
+    logger.debug('Flow request is valid, looking for an offline session', {
+      shop: payload.shopify_domain,
+    });
+
+    const session = await ensureValidOfflineSession(
+      params,
+      payload.shopify_domain,
+    );
+
+    if (!session) {
+      logger.info('Flow request could not find session', {
+        shop: payload.shopify_domain,
+      });
+      throw new Response(undefined, {
+        status: 400,
+        statusText: 'Bad Request',
+      });
+    }
+
+    logger.debug('Found a session for the flow request', {shop: session.shop});
+
+    return {
+      session,
+      payload,
+      admin: adminClientFactory({params, session}),
+    };
+  };
+}