shopify-app-js 0.0.1-security → 1.0.1

package/packages/shopify-app-remix/src/server/authenticate/webhooks/__tests__/authenticate.test.ts

@@ -0,0 +1,207 @@
+import {Session} from '@shopify/shopify-api';
+import {restResources} from '@shopify/shopify-api/rest/admin/2023-04';
+import {MemorySessionStorage} from '@shopify/shopify-app-session-storage-memory';
+
+import {shopifyApp} from '../../..';
+import {
+  APP_URL,
+  TEST_SHOP,
+  expectAdminApiClient,
+  getHmac,
+  getThrownResponse,
+  setUpValidSession,
+  testConfig,
+} from '../../../__test-helpers';
+
+interface WebhookHeaders {
+  [key: string]: string;
+  'X-Shopify-Shop-Domain': string;
+  'X-Shopify-Topic': string;
+  'X-Shopify-API-Version': string;
+  'X-Shopify-Webhook-Id': string;
+  'X-Shopify-Hmac-Sha256': string;
+}
+
+describe('Webhook validation', () => {
+  it('returns context when there is no session', async () => {
+    // GIVEN
+    const sessionStorage = new MemorySessionStorage();
+    const shopify = shopifyApp(testConfig({sessionStorage, restResources}));
+    const body = {some: 'data'};
+
+    // WHEN
+    const {
+      admin,
+      apiVersion,
+      session: actualSession,
+      shop,
+      topic,
+      webhookId,
+      payload,
+    } = await shopify.authenticate.webhook(
+      new Request(`${APP_URL}/webhooks`, {
+        method: 'POST',
+        body: JSON.stringify(body),
+        headers: webhookHeaders(JSON.stringify(body)),
+      }),
+    );
+
+    // THEN
+    expect(apiVersion).toBe('2023-01');
+    expect(shop).toBe(TEST_SHOP);
+    expect(topic).toBe('APP_UNINSTALLED');
+    expect(webhookId).toBe('1234567890');
+    expect(payload).toEqual(body);
+
+    expect(admin).toBeUndefined();
+    expect(actualSession).toBeUndefined();
+  });
+
+  describe('returns context with session when there is a session', () => {
+    expectAdminApiClient(async () => {
+      // GIVEN
+      const sessionStorage = new MemorySessionStorage();
+      const shopify = shopifyApp(testConfig({sessionStorage, restResources}));
+      const body = {some: 'data'};
+
+      const expectedSession = new Session({
+        id: `offline_${TEST_SHOP}`,
+        shop: TEST_SHOP,
+        isOnline: false,
+        state: 'test',
+        accessToken: 'totally_real_token',
+      });
+      await sessionStorage.storeSession(expectedSession);
+
+      // WHEN
+      const {
+        admin,
+        apiVersion,
+        session: actualSession,
+        shop,
+        topic,
+        webhookId,
+        payload,
+      } = await shopify.authenticate.webhook(
+        new Request(`${APP_URL}/webhooks`, {
+          method: 'POST',
+          body: JSON.stringify(body),
+          headers: webhookHeaders(JSON.stringify(body)),
+        }),
+      );
+
+      // THEN
+      expect(apiVersion).toBe('2023-01');
+      expect(shop).toBe(TEST_SHOP);
+      expect(topic).toBe('APP_UNINSTALLED');
+      expect(webhookId).toBe('1234567890');
+      expect(actualSession).toBe(expectedSession);
+      expect(payload).toEqual(body);
+
+      if (!admin) throw new Error('Expected admin to be defined');
+      if (!actualSession) throw new Error('Expected session to be defined');
+
+      return {admin, expectedSession, actualSession};
+    });
+  });
+
+  it('returns a legacy context when the future flag is disabled', async () => {
+    // GIVEN
+    const shopify = shopifyApp(
+      testConfig({restResources, future: {v3_webhookAdminContext: false}}),
+    );
+    const session = await setUpValidSession(shopify.sessionStorage);
+
+    // WHEN
+    const body = {some: 'data'};
+    const {admin} = await shopify.authenticate.webhook(
+      new Request(`${APP_URL}/webhooks`, {
+        method: 'POST',
+        body: JSON.stringify(body),
+        headers: webhookHeaders(JSON.stringify(body)),
+      }),
+    );
+
+    // THEN
+    expect(admin?.rest.apiVersion).toBe('2023-01');
+    expect(admin?.rest.session).toBe(session);
+
+    expect(admin?.graphql.apiVersion).toBe('2023-01');
+    expect(admin?.graphql.session).toBe(session);
+  });
+
+  it('throws a 401 on invalid HMAC', async () => {
+    // GIVEN
+    const shopify = shopifyApp(testConfig());
+
+    // WHEN
+    const response = await getThrownResponse(
+      shopify.authenticate.webhook,
+      new Request(`${APP_URL}/webhooks`, {
+        method: 'POST',
+        body: JSON.stringify({}),
+        headers: webhookHeaders(JSON.stringify({}), {
+          'X-Shopify-Hmac-Sha256': 'invalid_hmac',
+        }),
+      }),
+    );
+
+    // THEN
+    expect(response.status).toBe(401);
+  });
+
+  it.each([
+    'X-Shopify-Shop-Domain',
+    'X-Shopify-Topic',
+    'X-Shopify-API-Version',
+    'X-Shopify-Webhook-Id',
+    'X-Shopify-Hmac-Sha256',
+  ])('throws a 400 when header %s is missing', async (header) => {
+    // GIVEN
+    const shopify = shopifyApp(testConfig());
+
+    // WHEN
+    const response = await getThrownResponse(
+      shopify.authenticate.webhook,
+      new Request(`${APP_URL}/webhooks`, {
+        method: 'POST',
+        body: JSON.stringify({}),
+        headers: webhookHeaders(JSON.stringify({}), {[header]: ''}),
+      }),
+    );
+
+    // THEN
+    expect(response.status).toBe(400);
+  });
+
+  it('throws a 405 Method Not Allowed on non-POST requests', async () => {
+    // GIVEN
+    const shopify = shopifyApp(testConfig());
+
+    // WHEN
+    const response = await getThrownResponse(
+      shopify.authenticate.webhook,
+      new Request(`${APP_URL}/webhooks`, {
+        method: 'GET',
+        headers: webhookHeaders(JSON.stringify({})),
+      }),
+    );
+
+    // THEN
+    expect(response.status).toBe(405);
+  });
+});
+
+function webhookHeaders(
+  body: string,
+  overrides: Partial<WebhookHeaders> = {},
+): WebhookHeaders {
+  return {
+    'X-Shopify-Shop-Domain': TEST_SHOP,
+    'X-Shopify-Topic': 'app/uninstalled',
+    'X-Shopify-API-Version': '2023-01',
+    'X-Shopify-Webhook-Id': '1234567890',
+    'X-Shopify-Hmac-Sha256': getHmac(body),
+    ...overrides,
+  };
+}

package/packages/shopify-app-remix/src/server/authenticate/webhooks/__tests__/mock-responses.ts

@@ -0,0 +1,45 @@
+export const EMPTY_WEBHOOK_RESPONSE = {
+  data: {
+    webhookSubscriptions: {
+      edges: [],
+      pageInfo: {
+        endCursor: null,
+        hasNextPage: false,
+      },
+    },
+  },
+};
+
+export const HTTP_WEBHOOK_CREATE_RESPONSE = {
+  data: {
+    webhookSubscriptionCreate: {
+      webhookSubscription: {id: 'fakeId'},
+      userErrors: [],
+    },
+  },
+};
+
+export const HTTP_WEBHOOK_CREATE_ERROR_RESPONSE = {
+  data: {
+    webhookSubscriptionCreate: {
+      webhookSubscription: null,
+      userErrors: [
+        {
+          field: ['webhookSubscriptionCreate', 'webhookSubscription'],
+          message: 'Webhook topic is invalid',
+        },
+      ],
+    },
+  },
+};
+
+export const HTTP_WEBHOOK_THROTTLING_ERROR_RESPONSE = {
+  errors: [
+    {
+      message: 'Throttled',
+      extensions: {
+        code: 'THROTTLED',
+      },
+    },
+  ],
+};

package/packages/shopify-app-remix/src/server/authenticate/webhooks/__tests__/register.test.ts

@@ -0,0 +1,210 @@
+import {DeliveryMethod, GraphqlQueryError, Session} from '@shopify/shopify-api';
+
+import {shopifyApp} from '../../..';
+import {
+  GRAPHQL_URL,
+  TEST_SHOP,
+  testConfig,
+  mockExternalRequests,
+} from '../../../__test-helpers';
+
+import * as mockResponses from './mock-responses';
+
+describe('Webhook registration', () => {
+  it('registers webhooks', async () => {
+    // GIVEN
+    const shopify = shopifyApp(
+      testConfig({
+        webhooks: {
+          PRODUCTS_CREATE: {
+            deliveryMethod: DeliveryMethod.Http,
+            callbackUrl: '/webhooks',
+          },
+        },
+      }),
+    );
+    const session = new Session({
+      id: `offline_${TEST_SHOP}`,
+      shop: TEST_SHOP,
+      isOnline: false,
+      state: 'test',
+      accessToken: 'totally_real_token',
+    });
+
+    await mockExternalRequests(
+      {
+        request: new Request(GRAPHQL_URL, {
+          method: 'POST',
+          body: 'webhookSubscriptions',
+        }),
+        response: new Response(
+          JSON.stringify(mockResponses.EMPTY_WEBHOOK_RESPONSE),
+        ),
+      },
+      {
+        request: new Request(GRAPHQL_URL, {
+          method: 'POST',
+          body: 'webhookSubscriptionCreate',
+        }),
+        response: new Response(
+          JSON.stringify(mockResponses.HTTP_WEBHOOK_CREATE_RESPONSE),
+        ),
+      },
+    );
+
+    // WHEN
+    const results = await shopify.registerWebhooks({session});
+
+    // THEN
+    expect(results).toMatchObject({
+      PRODUCTS_CREATE: [expect.objectContaining({success: true})],
+    });
+  });
+
+  it('logs when registration fails', async () => {
+    // GIVEN
+    const shopify = shopifyApp(
+      testConfig({
+        webhooks: {
+          NOT_A_VALID_TOPIC: {
+            deliveryMethod: DeliveryMethod.Http,
+            callbackUrl: '/webhooks',
+          },
+        },
+      }),
+    );
+    const session = new Session({
+      id: `offline_${TEST_SHOP}`,
+      shop: TEST_SHOP,
+      isOnline: false,
+      state: 'test',
+      accessToken: 'totally_real_token',
+    });
+
+    await mockExternalRequests(
+      {
+        request: new Request(GRAPHQL_URL, {
+          method: 'POST',
+          body: 'webhookSubscriptions',
+        }),
+        response: new Response(
+          JSON.stringify(mockResponses.EMPTY_WEBHOOK_RESPONSE),
+        ),
+      },
+      {
+        request: new Request(GRAPHQL_URL, {
+          method: 'POST',
+          body: 'webhookSubscriptionCreate',
+        }),
+        response: new Response(
+          JSON.stringify(mockResponses.HTTP_WEBHOOK_CREATE_ERROR_RESPONSE),
+        ),
+      },
+    );
+
+    // WHEN
+    const results = await shopify.registerWebhooks({session});
+
+    // THEN
+    expect(results).toMatchObject({
+      NOT_A_VALID_TOPIC: [expect.objectContaining({success: false})],
+    });
+  });
+
+  // eslint-disable-next-line no-warning-comments
+  // TODO: Remove tests once we have a better solution to parallel afterAuth calls
+  it('logs throttling errors', async () => {
+    // GIVEN
+    const shopify = shopifyApp(
+      testConfig({
+        webhooks: {
+          NOT_A_VALID_TOPIC: {
+            deliveryMethod: DeliveryMethod.Http,
+            callbackUrl: '/webhooks',
+          },
+        },
+      }),
+    );
+    const session = new Session({
+      id: `offline_${TEST_SHOP}`,
+      shop: TEST_SHOP,
+      isOnline: false,
+      state: 'test',
+      accessToken: 'totally_real_token',
+    });
+
+    await mockExternalRequests(
+      {
+        request: new Request(GRAPHQL_URL, {
+          method: 'POST',
+          body: 'webhookSubscriptions',
+        }),
+        response: new Response(
+          JSON.stringify(mockResponses.EMPTY_WEBHOOK_RESPONSE),
+        ),
+      },
+      {
+        request: new Request(GRAPHQL_URL, {
+          method: 'POST',
+          body: 'webhookSubscriptionCreate',
+        }),
+        response: new Response(
+          JSON.stringify(mockResponses.HTTP_WEBHOOK_THROTTLING_ERROR_RESPONSE),
+        ),
+      },
+    );
+
+    // WHEN
+    const results = await shopify.registerWebhooks({session});
+
+    // THEN
+    expect(results).toBeUndefined();
+  });
+
+  it('throws other errors', async () => {
+    // GIVEN
+    const shopify = shopifyApp(
+      testConfig({
+        webhooks: {
+          NOT_A_VALID_TOPIC: {
+            deliveryMethod: DeliveryMethod.Http,
+            callbackUrl: '/webhooks',
+          },
+        },
+      }),
+    );
+    const session = new Session({
+      id: `offline_${TEST_SHOP}`,
+      shop: TEST_SHOP,
+      isOnline: false,
+      state: 'test',
+      accessToken: 'totally_real_token',
+    });
+
+    await mockExternalRequests(
+      {
+        request: new Request(GRAPHQL_URL, {
+          method: 'POST',
+          body: 'webhookSubscriptions',
+        }),
+        response: new Response(
+          JSON.stringify(mockResponses.EMPTY_WEBHOOK_RESPONSE),
+        ),
+      },
+      {
+        request: new Request(GRAPHQL_URL, {
+          method: 'POST',
+          body: 'webhookSubscriptionCreate',
+        }),
+        response: new Response(
+          JSON.stringify({errors: [{extensions: {code: 'FAILED_REQUEST'}}]}),
+        ),
+      },
+    );
+
+    // THEN
+    expect(shopify.registerWebhooks({session})).rejects.toThrowError(
+      GraphqlQueryError,
+    );
+  });
+});

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

@@ -0,0 +1,113 @@
+import {
+  ApiVersion,
+  ShopifyRestResources,
+  WebhookValidationErrorReason,
+} from '@shopify/shopify-api';
+
+import type {BasicParams, MandatoryTopics} from '../../types';
+import {AdminApiContext, adminClientFactory} from '../../clients';
+import {handleClientErrorFactory} from '../admin/helpers';
+import {FutureFlagOptions} from '../../future/flags';
+
+import type {
+  AuthenticateWebhook,
+  LegacyWebhookAdminApiContext,
+  WebhookAdminContext,
+  WebhookContext,
+  WebhookContextWithoutSession,
+} from './types';
+
+export function authenticateWebhookFactory<
+  Future extends FutureFlagOptions,
+  Resources extends ShopifyRestResources,
+  Topics extends string | number | symbol | MandatoryTopics,
+>(params: BasicParams): AuthenticateWebhook<Future, Resources, Topics> {
+  const {api, config, logger} = params;
+
+  return async function authenticate(
+    request: Request,
+  ): Promise<WebhookContext<Future, Resources, Topics>> {
+    if (request.method !== 'POST') {
+      logger.debug(
+        'Received a non-POST request for a webhook. 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 check = await api.webhooks.validate({
+      rawBody,
+      rawRequest: request,
+    });
+
+    if (!check.valid) {
+      if (check.reason === WebhookValidationErrorReason.InvalidHmac) {
+        logger.debug('Webhook HMAC validation failed', check);
+        throw new Response(undefined, {
+          status: 401,
+          statusText: 'Unauthorized',
+        });
+      } else {
+        logger.debug('Webhook validation failed', check);
+        throw new Response(undefined, {status: 400, statusText: 'Bad Request'});
+      }
+    }
+
+    const sessionId = api.session.getOfflineId(check.domain);
+    const session = await config.sessionStorage.loadSession(sessionId);
+    const webhookContext: WebhookContextWithoutSession<Topics> = {
+      apiVersion: check.apiVersion,
+      shop: check.domain,
+      topic: check.topic as Topics,
+      webhookId: check.webhookId,
+      payload: JSON.parse(rawBody),
+      subTopic: check.subTopic || undefined,
+      session: undefined,
+      admin: undefined,
+    };
+
+    if (!session) {
+      return webhookContext;
+    }
+
+    let admin:
+      | AdminApiContext<Resources>
+      | LegacyWebhookAdminApiContext<Resources>;
+    if (config.future.v3_webhookAdminContext) {
+      admin = adminClientFactory<Resources>({
+        params,
+        session,
+        handleClientError: handleClientErrorFactory({request}),
+      });
+    } else {
+      const restClient = new api.clients.Rest({
+        session,
+        apiVersion: check.apiVersion as ApiVersion,
+      });
+      const graphqlClient = new api.clients.Graphql({
+        session,
+        apiVersion: check.apiVersion as ApiVersion,
+      });
+
+      Object.entries(api.rest).forEach(([name, resource]) => {
+        Reflect.set(restClient, name, resource);
+      });
+
+      admin = {
+        rest: restClient as typeof restClient & Resources,
+        graphql: graphqlClient,
+      };
+    }
+
+    return {
+      ...webhookContext,
+      session,
+      admin: admin as WebhookAdminContext<Future, Resources>,
+    };
+  };
+}

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

@@ -0,0 +1,28 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Webhook',
+  description:
+    'Contains functions for verifying Shopify webhooks.' +
+    '\n\n> Note: The format of the `admin` object returned by this function changes with the `v3_webhookAdminContext` future flag. Learn more about [gradual feature adoption](/docs/api/shopify-app-remix/guide-future-flags).',
+  category: 'Authenticate',
+  type: 'object',
+  isVisualComponent: false,
+  definitions: [
+    {
+      title: 'authenticate.webhook',
+      description: 'Verifies requests coming from Shopify webhooks.',
+      type: 'AuthenticateWebhook',
+    },
+  ],
+  jsDocTypeExamples: ['WebhookContextWithSession'],
+  related: [
+    {
+      name: 'Admin API context',
+      subtitle: 'Interact with the Admin API.',
+      url: '/docs/api/shopify-app-remix/apis/admin-api',
+    },
+  ],
+};
+
+export default data;

package/packages/shopify-app-remix/src/server/authenticate/webhooks/index.ts

@@ -0,0 +1 @@
+export {registerWebhooksFactory} from './register';

package/packages/shopify-app-remix/src/server/authenticate/webhooks/register.ts

@@ -0,0 +1,48 @@
+import type {BasicParams} from '../../types';
+
+import type {RegisterWebhooksOptions} from './types';
+
+export function registerWebhooksFactory({api, logger}: BasicParams) {
+  return async function registerWebhooks({session}: RegisterWebhooksOptions) {
+    return api.webhooks
+      .register({session})
+      .then((response) => {
+        Object.entries(response).forEach(([topic, topicResults]) => {
+          topicResults.forEach(({success, ...rest}) => {
+            if (success) {
+              logger.debug('Registered webhook', {
+                topic,
+                shop: session.shop,
+                operation: rest.operation,
+              });
+            } else {
+              logger.error('Failed to register webhook', {
+                topic,
+                shop: session.shop,
+                result: JSON.stringify(rest.result),
+              });
+            }
+          });
+        });
+
+        return response;
+      })
+      .catch((error) => {
+        const graphQLErrors: {extensions: {code?: string}}[] =
+          error.body?.errors?.graphQLErrors || [];
+
+        const throttled = graphQLErrors.find(
+          ({extensions: {code}}) => code === 'THROTTLED',
+        );
+
+        if (throttled) {
+          logger.error('Failed to register webhooks', {
+            shop: session.shop,
+            error: JSON.stringify(error),
+          });
+        } else {
+          throw error;
+        }
+      });
+  };
+}