@shopify/shopify-app-remix 4.1.0 → 4.2.0

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

@@ -0,0 +1,85 @@
+import {Session} from '@shopify/shopify-api';
+
+import type {AdminApiContext} from '../../clients';
+
+export interface FlowContext {
+  /**
+   * A session with an offline token for the shop.
+   *
+   * Returned only if there is a session for the shop.
+   *
+   * @example
+   * <caption>Shopify session for the Flow request.</caption>
+   * <description>Use the session associated with this request.</description>
+   * ```ts
+   * // /app/routes/flow.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { session, admin } = await authenticate.flow(request);
+   *
+   *   console.log(session.id)
+   *
+   *   return new Response();
+   * };
+   * ```
+   */
+  session: Session;
+
+  /**
+   * The payload from the Flow request.
+   *
+   * @example
+   * <caption>Flow payload.</caption>
+   * <description>Get the request's POST payload.</description>
+   * ```ts
+   * // /app/routes/flow.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { payload } = await authenticate.flow(request);
+   *   return new Response();
+   * };
+   * ```
+   */
+  payload: any;
+
+  /**
+   * An admin context for the Flow request.
+   *
+   * Returned only if there is a session for the shop.
+   *
+   * @example
+   * <caption>Flow admin context.</caption>
+   * <description>Use the `admin` object in the context to interact with the Admin API.</description>
+   * ```ts
+   * // /app/routes/flow.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export async function action({ request }: ActionFunctionArgs) {
+   *   const { admin } = await authenticate.flow(request);
+   *
+   *   const response = await admin?.graphql(
+   *     `#graphql
+   *     mutation populateProduct($input: ProductInput!) {
+   *       productCreate(input: $input) {
+   *         product {
+   *           id
+   *         }
+   *       }
+   *     }`,
+   *     { variables: { input: { title: "Product Name" } } }
+   *   );
+   *
+   *   const productData = await response.json();
+   *   return json({ data: productData.data });
+   * }
+   * ```
+   */
+  admin: AdminApiContext;
+}
+
+export type AuthenticateFlow = (request: Request) => Promise<FlowContext>;

package/src/server/authenticate/fulfillment-service/authenticate.fulfillment-service.doc.example.ts

@@ -0,0 +1,52 @@
+import {type ActionFunctionArgs} from '@remix-run/node';
+
+import {authenticate} from '../shopify.server';
+
+export const action = async ({request}: ActionFunctionArgs) => {
+  const {admin, payload} = await authenticate.fulfillmentService(request);
+
+  const kind = payload.kind;
+
+  if (kind === 'FULFILLMENT_REQUEST') {
+    const response = await admin?.graphql(
+      `#graphql
+         query {
+           shop {
+             assignedFulfillmentOrders(first: 10, assignmentStatus: FULFILLMENT_REQUESTED) {
+               edges {
+                 node {
+                   id
+                   destination {
+                   firstName
+                   lastName
+                 }
+                 lineItems(first: 10) {
+                   edges {
+                     node {
+                     id
+                     productTitle
+                     sku
+                     remainingQuantity
+                   }
+                 }
+               }
+               merchantRequests(first: 10, kind: FULFILLMENT_REQUEST) {
+                 edges {
+                   node {
+                     message
+                   }
+                 }
+               }
+             }
+           }
+         }
+       }
+      }`,
+    );
+
+    const fulfillments = await response.json();
+    console.log(fulfillments);
+  }
+
+  return new Response();
+};

package/src/server/authenticate/fulfillment-service/authenticate.fulfillment-service.doc.ts

@@ -0,0 +1,48 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Fulfillment Service',
+  description:
+    'Contains functions for verifying fulfillment service requests.' +
+    '\n\nSee the [fulfillment service documentation](https://shopify.dev/docs/apps/fulfillment/fulfillment-service-apps) for more information.',
+  category: 'Authenticate',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'authenticate.fulfillmentService',
+      description:
+        'Verifies requests coming from Shopify to fulfillment service apps',
+      type: 'AuthenticateFulfillmentService',
+    },
+  ],
+  defaultExample: {
+    description: 'Handle a fulfillment service notification call',
+    codeblock: {
+      title: 'Consume a fulfillment service notification request',
+      tabs: [
+        {
+          title: '/app/routes/**.ts',
+          language: 'typescript',
+          code: './authenticate.fulfillment-service.doc.example.ts',
+        },
+      ],
+    },
+  },
+  jsDocTypeExamples: ['FulfillmentServiceContext'],
+  related: [
+    {
+      name: 'Admin API context',
+      subtitle: 'Interact with the Admin API.',
+      url: '/docs/api/shopify-app-remix/apis/admin-api',
+    },
+    {
+      name: 'Manage Fulfillments',
+      subtitle: 'Receive fulfillment requests and cancellations.',
+      url: '/docs/apps/fulfillment/fulfillment-service-apps/manage-fulfillments',
+      type: 'shopify',
+    },
+  ],
+};
+
+export default data;

package/src/server/authenticate/fulfillment-service/authenticate.ts

@@ -0,0 +1,82 @@
+import {ShopifyHeader} from '@shopify/shopify-api';
+
+import {adminClientFactory} from '../../clients/admin';
+import {BasicParams} from '../../types';
+import {ensureValidOfflineSession} from '../../helpers';
+
+import type {
+  AuthenticateFulfillmentService,
+  FulfillmentServiceContext,
+} from './types';
+
+export function authenticateFulfillmentServiceFactory(
+  params: BasicParams,
+): AuthenticateFulfillmentService {
+  const {api, logger} = params;
+
+  return async function authenticate(
+    request: Request,
+  ): Promise<FulfillmentServiceContext> {
+    logger.info('Authenticating fulfillment service request');
+
+    if (request.method !== 'POST') {
+      logger.debug(
+        'Received a non-POST request for fulfillment service. 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.fulfillmentService.validate({
+      rawBody,
+      rawRequest: request,
+    });
+
+    if (!result.valid) {
+      logger.error('Received an invalid fulfillment service request', {
+        reason: result.reason,
+      });
+
+      throw new Response(undefined, {
+        status: 400,
+        statusText: 'Bad Request',
+      });
+    }
+
+    const payload = JSON.parse(rawBody);
+    const shop = request.headers.get(ShopifyHeader.Domain) || '';
+
+    logger.debug(
+      'Fulfillment service request is valid, looking for an offline session',
+      {
+        shop,
+      },
+    );
+
+    const session = await ensureValidOfflineSession(params, shop);
+
+    if (!session) {
+      logger.info('Fulfillment service request could not find session', {
+        shop,
+      });
+      throw new Response(undefined, {
+        status: 400,
+        statusText: 'Bad Request',
+      });
+    }
+
+    logger.debug('Found a session for the fulfillment service request', {
+      shop,
+    });
+
+    return {
+      session,
+      payload,
+      admin: adminClientFactory({params, session}),
+    };
+  };
+}

package/src/server/authenticate/fulfillment-service/types.ts

@@ -0,0 +1,82 @@
+import {Session} from '@shopify/shopify-api';
+
+import type {AdminApiContext} from '../../clients';
+
+export type FulfillmentServicePayload = Record<string, any> & {
+  kind: string;
+};
+
+export interface FulfillmentServiceContext {
+  /**
+   * A session with an offline token for the shop.
+   *
+   * Returned only if there is a session for the shop.
+   * @example
+   * <caption>Shopify session for the fulfillment service notification request.</caption>
+   * <description>Use the session associated with this request.</description>
+   * ```ts
+   * // /app/routes/fulfillment_service_notification.tsx
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { session, admin } = await authenticate.fulfillmentService(request);
+   *
+   *   console.log(session.id)
+   *
+   *   return new Response();
+   * };
+   * ```
+   * */
+  session: Session;
+  /**
+   *
+   * An admin context for the fulfillment service request.
+   *
+   * Returned only if there is a session for the shop.
+   * @example
+   * <caption>Shopify session for the fulfillment service request.</caption>
+   * <description>Use the session associated with this request to use the Admin GraphQL API </description>
+   * ```ts
+   * // /app/routes/fulfillment_order_notification.ts
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export async function action({ request }: ActionFunctionArgs) {
+   *   const { admin, session } = await authenticate.fulfillmentService(request);
+   *
+   *   console.log(session.id)
+   *
+   *   return new Response();
+   * }
+   * ```
+   */
+  admin: AdminApiContext;
+
+  /**
+   * The payload from the fulfillment service request.
+   *
+   * @example
+   * <caption>Fulfillment service request payload.</caption>
+   * <description>Get the request's POST payload.</description>
+   * ```ts
+   * /app/routes/fulfillment_order_notification.ts
+   * import { ActionFunction } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   *
+   * export const action: ActionFunction = async ({ request }) => {
+   *   const { payload } = await authenticate.fulfillmentService(request);
+   *   if(payload.kind === 'FULFILLMENT_REQUEST') {
+   *    // handle fulfillment request
+   *   } else if (payload.kind === 'CANCELLATION_REQUEST') {
+   *    // handle cancellation request
+   *   };
+   * return new Response();
+   * ```
+   */
+  payload: FulfillmentServicePayload;
+}
+
+export type AuthenticateFulfillmentService = (
+  request: Request,
+) => Promise<FulfillmentServiceContext>;

package/src/server/authenticate/helpers/add-response-headers.ts

@@ -0,0 +1,43 @@
+import type {BasicParams} from '../../types';
+
+export type AddDocumentResponseHeadersFunction = (
+  request: Request,
+  headers: Headers,
+) => void;
+
+export function addDocumentResponseHeadersFactory(
+  params: BasicParams,
+): AddDocumentResponseHeadersFunction {
+  const {api, config} = params;
+
+  return function (request: Request, headers: Headers) {
+    const {searchParams} = new URL(request.url);
+    const shop = api.utils.sanitizeShop(searchParams.get('shop')!);
+
+    addDocumentResponseHeaders(headers, config.isEmbeddedApp, shop);
+  };
+}
+
+export function addDocumentResponseHeaders(
+  headers: Headers,
+  isEmbeddedApp: boolean,
+  shop: string | null | undefined,
+) {
+  if (shop) {
+    headers.set(
+      'Link',
+      '<https://cdn.shopify.com/shopifycloud/app-bridge.js>; rel="preload"; as="script";',
+    );
+  }
+
+  if (isEmbeddedApp) {
+    if (shop) {
+      headers.set(
+        'Content-Security-Policy',
+        `frame-ancestors https://${shop} https://admin.shopify.com https://*.spin.dev https://admin.myshopify.io https://admin.shop.dev;`,
+      );
+    }
+  } else {
+    headers.set('Content-Security-Policy', `frame-ancestors 'none';`);
+  }
+}

package/src/server/authenticate/helpers/app-bridge-url.ts

@@ -0,0 +1,10 @@
+import {APP_BRIDGE_URL} from '../const';
+
+let appBridgeUrlOverride: string | undefined;
+export function setAppBridgeUrlOverride(url: string) {
+  appBridgeUrlOverride = url;
+}
+
+export function appBridgeUrl() {
+  return appBridgeUrlOverride || APP_BRIDGE_URL;
+}

package/src/server/authenticate/helpers/ensure-cors-headers.ts

@@ -0,0 +1,38 @@
+import {BasicParams} from '../../types';
+import {REAUTH_URL_HEADER} from '../const';
+
+export interface EnsureCORSFunction {
+  (response: Response): Response;
+}
+
+export function ensureCORSHeadersFactory(
+  params: BasicParams,
+  request: Request,
+  corsHeaders: string[] = [],
+): EnsureCORSFunction {
+  const {logger, config} = params;
+
+  return function ensureCORSHeaders(response) {
+    const origin = request.headers.get('Origin');
+    if (origin && origin !== config.appUrl) {
+      logger.debug(
+        'Request comes from a different origin, adding CORS headers',
+      );
+
+      const corsHeadersSet = new Set([
+        'Authorization',
+        'Content-Type',
+        ...corsHeaders,
+      ]);
+
+      response.headers.set('Access-Control-Allow-Origin', '*');
+      response.headers.set(
+        'Access-Control-Allow-Headers',
+        [...corsHeadersSet].join(', '),
+      );
+      response.headers.set('Access-Control-Expose-Headers', REAUTH_URL_HEADER);
+    }
+
+    return response;
+  };
+}

package/src/server/authenticate/helpers/get-session-token-header.ts

@@ -0,0 +1,11 @@
+const SESSION_TOKEN_PARAM = 'id_token';
+
+export function getSessionTokenHeader(request: Request): string | undefined {
+  return request.headers.get('authorization')?.replace('Bearer ', '');
+}
+
+export function getSessionTokenFromUrlParam(request: Request): string | null {
+  const url = new URL(request.url);
+
+  return url.searchParams.get(SESSION_TOKEN_PARAM);
+}

package/src/server/authenticate/helpers/get-shop-from-request.ts

@@ -0,0 +1,4 @@
+export function getShopFromRequest(request: Request) {
+  const url = new URL(request.url);
+  return url.searchParams.get('shop')!;
+}

package/src/server/authenticate/helpers/idempotent-promise-handler.ts

@@ -0,0 +1,45 @@
+export interface IdempotentHandlePromiseParams {
+  promiseFunction: () => Promise<any>;
+  identifier: string;
+}
+
+const IDENTIFIER_TTL_MS = 60000;
+
+export class IdempotentPromiseHandler {
+  protected identifiers: Map<string, number>;
+
+  constructor() {
+    this.identifiers = new Map<string, number>();
+  }
+
+  async handlePromise({
+    promiseFunction,
+    identifier,
+  }: IdempotentHandlePromiseParams): Promise<any> {
+    try {
+      if (this.isPromiseRunnable(identifier)) {
+        await promiseFunction();
+      }
+    } finally {
+      this.clearStaleIdentifiers();
+    }
+
+    return Promise.resolve();
+  }
+
+  private isPromiseRunnable(identifier: string) {
+    if (!this.identifiers.has(identifier)) {
+      this.identifiers.set(identifier, Date.now());
+      return true;
+    }
+    return false;
+  }
+
+  private async clearStaleIdentifiers() {
+    this.identifiers.forEach((date, identifier, map) => {
+      if (Date.now() - date > IDENTIFIER_TTL_MS) {
+        map.delete(identifier);
+      }
+    });
+  }
+}

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

@@ -0,0 +1,10 @@
+export * from './app-bridge-url';
+export * from './add-response-headers';
+export * from './ensure-cors-headers';
+export * from './validate-session-token';
+export * from './get-session-token-header';
+export * from './invalidate-access-token';
+export * from './reject-bot-request';
+export * from './respond-to-options-request';
+export * from './respond-to-invalid-session-token';
+export * from './get-shop-from-request';

package/src/server/authenticate/helpers/invalidate-access-token.ts

@@ -0,0 +1,17 @@
+import {Session} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../types';
+
+export async function invalidateAccessToken(
+  params: BasicParams,
+  session: Session,
+): Promise<void> {
+  const {logger, config} = params;
+
+  logger.debug(`Invalidating access token for session - ${session.id}`, {
+    shop: session.shop,
+  });
+
+  session.accessToken = undefined;
+  await config.sessionStorage!.storeSession(session);
+}

package/src/server/authenticate/helpers/reject-bot-request.ts

@@ -0,0 +1,27 @@
+import {isbot} from 'isbot';
+
+import type {BasicParams} from '../../types';
+
+const SHOPIFY_POS_USER_AGENT = /Shopify POS\//;
+const SHOPIFY_MOBILE_USER_AGENT = /Shopify Mobile\//;
+
+const SHOPIFY_USER_AGENTS = [SHOPIFY_POS_USER_AGENT, SHOPIFY_MOBILE_USER_AGENT];
+
+export function respondToBotRequest(
+  {logger}: BasicParams,
+  request: Request,
+): void | never {
+  const userAgent = request.headers.get('User-Agent') ?? '';
+
+  // We call isbot below to prevent good (self-identifying) bots from triggering auth requests, but there are some
+  // Shopify-specific cases we want to allow that are identified as bots by isbot.
+  if (SHOPIFY_USER_AGENTS.some((agent) => agent.test(userAgent))) {
+    logger.debug('Request is from a Shopify agent, allow');
+    return;
+  }
+
+  if (isbot(userAgent)) {
+    logger.debug('Request is from a bot, skipping auth');
+    throw new Response(undefined, {status: 410, statusText: 'Gone'});
+  }
+}

package/src/server/authenticate/helpers/respond-to-invalid-session-token.ts

@@ -0,0 +1,28 @@
+import {redirectToBouncePage} from '../admin/helpers/redirect-to-bounce-page';
+import {RETRY_INVALID_SESSION_HEADER} from '../const';
+import {BasicParams} from '../../types';
+
+interface RespondToInvalidSessionTokenParams {
+  params: BasicParams;
+  request: Request;
+  retryRequest?: boolean;
+}
+
+export function respondToInvalidSessionToken({
+  params,
+  request,
+  retryRequest = false,
+}: RespondToInvalidSessionTokenParams) {
+  const {api, logger, config} = params;
+
+  const isDocumentRequest = !request.headers.get('authorization');
+  if (isDocumentRequest) {
+    return redirectToBouncePage({api, logger, config}, new URL(request.url));
+  }
+
+  throw new Response(undefined, {
+    status: 401,
+    statusText: 'Unauthorized',
+    headers: retryRequest ? RETRY_INVALID_SESSION_HEADER : {},
+  });
+}

package/src/server/authenticate/helpers/respond-to-options-request.ts

@@ -0,0 +1,26 @@
+import {BasicParams} from '../../types';
+
+import {ensureCORSHeadersFactory} from './ensure-cors-headers';
+
+export function respondToOptionsRequest(
+  params: BasicParams,
+  request: Request,
+  corsHeaders?: string[],
+) {
+  if (request.method === 'OPTIONS') {
+    const ensureCORSHeaders = ensureCORSHeadersFactory(
+      params,
+      request,
+      corsHeaders,
+    );
+
+    throw ensureCORSHeaders(
+      new Response(null, {
+        status: 204,
+        headers: {
+          'Access-Control-Max-Age': '7200',
+        },
+      }),
+    );
+  }
+}

package/src/server/authenticate/helpers/validate-session-token.ts

@@ -0,0 +1,40 @@
+import {JwtPayload} from '@shopify/shopify-api';
+
+import type {BasicParams} from '../../types';
+
+import {respondToInvalidSessionToken} from './respond-to-invalid-session-token';
+import {getShopFromRequest} from './get-shop-from-request';
+
+interface ValidateSessionTokenOptions {
+  checkAudience?: boolean;
+  retryRequest?: boolean;
+}
+
+export async function validateSessionToken(
+  params: BasicParams,
+  request: Request,
+  token: string,
+  {checkAudience = true, retryRequest = true}: ValidateSessionTokenOptions = {},
+): Promise<JwtPayload> {
+  const {api, logger} = params;
+  const shop = getShopFromRequest(request);
+  logger.debug('Validating session token', {shop});
+
+  try {
+    const payload = await api.session.decodeSessionToken(token, {
+      checkAudience,
+    });
+    logger.debug('Session token is valid - validated', {
+      shop,
+      payload: JSON.stringify(payload),
+    });
+
+    return payload;
+  } catch (error) {
+    logger.debug(`Failed to validate session token: ${error.message}`, {
+      shop,
+    });
+
+    throw respondToInvalidSessionToken({params, request, retryRequest});
+  }
+}