shopify-app-js 0.0.1-security → 1.0.1

package/packages/shopify-app-remix/src/server/authenticate/admin/strategies/token-exchange.ts

@@ -0,0 +1,169 @@
+import {
+  HttpResponseError,
+  InvalidJwtError,
+  RequestedTokenType,
+  Session,
+  Shopify,
+  ShopifyRestResources,
+} from '@shopify/shopify-api';
+
+import {AppConfig, AppConfigArg} from '../../../config-types';
+import {BasicParams} from '../../../types';
+import {respondToInvalidSessionToken} from '../../helpers';
+import {handleClientErrorFactory, triggerAfterAuthHook} from '../helpers';
+import {HandleAdminClientError} from '../../../clients';
+import type {
+  ApiConfigWithFutureFlags,
+  ApiFutureFlags,
+} from '../../../future/flags';
+
+import {AuthorizationStrategy, SessionContext, OnErrorOptions} from './types';
+
+export class TokenExchangeStrategy<Config extends AppConfigArg>
+  implements AuthorizationStrategy
+{
+  protected api: Shopify<
+    ApiConfigWithFutureFlags<Config['future']>,
+    ShopifyRestResources,
+    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.isExpired()) {
+      logger.info('No valid session found');
+      logger.info('Requesting offline access token');
+      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');
+        const {session: onlineSession} = await this.exchangeToken({
+          request,
+          sessionToken,
+          shop,
+          requestedTokenType: RequestedTokenType.OnlineAccessToken,
+        });
+
+        await config.sessionStorage.storeSession(onlineSession);
+        newSession = onlineSession;
+      }
+
+      try {
+        await this.handleAfterAuthHook(
+          {api, config, logger},
+          newSession,
+          request,
+          sessionToken,
+        );
+      } catch (error) {
+        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) {
+          config.sessionStorage.deleteSession(session.id);
+
+          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,
+      });
+    } 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/packages/shopify-app-remix/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/packages/shopify-app-remix/src/server/authenticate/admin/types.ts

@@ -0,0 +1,199 @@
+import {JwtPayload, Session, ShopifyRestResources} 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';
+
+interface AdminContextInternal<
+  Config extends AppConfigArg,
+  Resources extends ShopifyRestResources = ShopifyRestResources,
+> {
+  /**
+   * 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
+   * // shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   * ```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));
+   * };
+   * ```
+   *
+   * @example
+   * <caption>Using online sessions.</caption>
+   * <description>Get your app's user-specific data using an online session.</description>
+   * ```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;
+   * ```
+   * ```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}));
+   * };
+   * ```
+   */
+  session: Session;
+
+  /**
+   * Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request.
+   */
+  admin: AdminApiContext<Resources>;
+
+  /**
+   * 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,
+  Resources extends ShopifyRestResources = ShopifyRestResources,
+> extends AdminContextInternal<Config, Resources> {
+  /**
+   * 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
+   * // 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;
+   * ```
+   * ```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.public.checkout(
+   *     request
+   *   );
+   *   return json(await getMyAppData({user: sessionToken.sub}));
+   * };
+   * ```
+   */
+  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 outside of Shopify admin.</caption>
+   * <description>Pass in a `target` option of `_top` or `_parent` to go to an external URL.</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,
+  Resources extends ShopifyRestResources = ShopifyRestResources,
+> extends AdminContextInternal<Config, Resources> {}
+
+export type AdminContext<
+  Config extends AppConfigArg,
+  Resources extends ShopifyRestResources = ShopifyRestResources,
+> = Config['isEmbeddedApp'] extends false
+  ? NonEmbeddedAdminContext<Config, Resources>
+  : EmbeddedAdminContext<Config, Resources>;
+
+export type AuthenticateAdmin<
+  Config extends AppConfigArg,
+  Resources extends ShopifyRestResources = ShopifyRestResources,
+> = (request: Request) => Promise<AdminContext<Config, Resources>>;

package/packages/shopify-app-remix/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/packages/shopify-app-remix/src/server/authenticate/flow/__tests__/authenticate.test.ts

@@ -0,0 +1,142 @@
+import {SessionStorage} from '@shopify/shopify-app-session-storage';
+import {MemorySessionStorage} from '@shopify/shopify-app-session-storage-memory';
+
+import {shopifyApp} from '../../..';
+import {
+  expectAdminApiClient,
+  getHmac,
+  getThrownResponse,
+  setUpValidSession,
+  testConfig,
+} from '../../../__test-helpers';
+
+const FLOW_URL = 'https://example.myapp.io/authenticate/flow';
+
+describe('authenticating flow requests', () => {
+  it('throws a 405 response if the request method is not POST', async () => {
+    // GIVEN
+    const shopify = shopifyApp(testConfig());
+
+    // WHEN
+    const response = await getThrownResponse(
+      shopify.authenticate.flow,
+      new Request(FLOW_URL, {method: 'GET'}),
+    );
+
+    // THEN
+    expect(response.status).toBe(405);
+    expect(response.statusText).toBe('Method not allowed');
+  });
+
+  it('throws a 400 response if the is missing the HMAC signature', async () => {
+    // GIVEN
+    const shopify = shopifyApp(testConfig());
+
+    // WHEN
+    const response = await getThrownResponse(
+      shopify.authenticate.flow,
+      new Request(FLOW_URL, {method: 'POST'}),
+    );
+
+    // THEN
+    expect(response.status).toBe(400);
+    expect(response.statusText).toBe('Bad Request');
+  });
+
+  it('throws a 400 response if the request has an invalid HMAC signature', async () => {
+    // GIVEN
+    const shopify = shopifyApp(testConfig());
+
+    // WHEN
+    const response = await getThrownResponse(
+      shopify.authenticate.flow,
+      new Request(FLOW_URL, {
+        method: 'POST',
+        headers: {
+          'X-Shopify-Hmac-Sha256': 'not-the-right-signature',
+        },
+      }),
+    );
+
+    // THEN
+    expect(response.status).toBe(400);
+    expect(response.statusText).toBe('Bad Request');
+  });
+
+  it('throws a 400 response if there is no session for the shop', async () => {
+    // GIVEN
+    const shopify = shopifyApp(testConfig());
+    const body = {shopify_domain: 'not-the-right-shop.myshopify.io'};
+
+    // WHEN
+    const response = await getThrownResponse(
+      shopify.authenticate.flow,
+      new Request(FLOW_URL, {
+        body: JSON.stringify(body),
+        method: 'POST',
+        headers: {
+          'X-Shopify-Hmac-Sha256': getHmac(JSON.stringify(body)),
+        },
+      }),
+    );
+
+    // THEN
+    expect(response.status).toBe(400);
+    expect(response.statusText).toBe('Bad Request');
+  });
+
+  it('valid requests with a session succeed', async () => {
+    // GIVEN
+    const sessionStorage = new MemorySessionStorage();
+    const shopify = shopifyApp(testConfig({sessionStorage}));
+
+    const {
+      request,
+      body,
+      session: expectedSession,
+    } = await getValidRequest(sessionStorage);
+
+    // WHEN
+    const {payload, session} = await shopify.authenticate.flow(request);
+
+    // THEN
+    expect(session).toEqual(expectedSession);
+    expect(payload).toEqual(body);
+  });
+
+  describe('valid requests include an API client object', () => {
+    expectAdminApiClient(async () => {
+      const sessionStorage = new MemorySessionStorage();
+      const shopify = shopifyApp(testConfig({sessionStorage}));
+
+      const {request, session: expectedSession} =
+        await getValidRequest(sessionStorage);
+
+      const {admin, session: actualSession} =
+        await shopify.authenticate.flow(request);
+
+      if (!admin) {
+        throw new Error('No admin client');
+      }
+
+      return {admin, expectedSession, actualSession};
+    });
+  });
+});
+
+async function getValidRequest(sessionStorage: SessionStorage) {
+  const session = await setUpValidSession(sessionStorage, {isOnline: false});
+
+  const body = {shopify_domain: session.shop};
+  const bodyString = JSON.stringify(body);
+
+  const request = new Request(FLOW_URL, {
+    body: bodyString,
+    method: 'POST',
+    headers: {
+      'X-Shopify-Hmac-Sha256': getHmac(bodyString),
+    },
+  });
+
+  return {body, request, session};
+}

package/packages/shopify-app-remix/src/server/authenticate/flow/authenticate.flow.doc.ts

@@ -0,0 +1,34 @@
+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',
+    },
+  ],
+  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/packages/shopify-app-remix/src/server/authenticate/flow/authenticate.ts

@@ -0,0 +1,71 @@
+import {ShopifyRestResources} from '@shopify/shopify-api';
+
+import {adminClientFactory} from '../../clients/admin';
+import {BasicParams} from '../../types';
+
+import type {AuthenticateFlow, FlowContext} from './types';
+
+export function authenticateFlowFactory<
+  Resources extends ShopifyRestResources = ShopifyRestResources,
+>(params: BasicParams): AuthenticateFlow<Resources> {
+  const {api, config, logger} = params;
+
+  return async function authenticate(
+    request: Request,
+  ): Promise<FlowContext<Resources>> {
+    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 sessionId = api.session.getOfflineId(payload.shopify_domain);
+    const session = await config.sessionStorage.loadSession(sessionId);
+
+    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<Resources>({params, session}),
+    };
+  };
+}