shopify-app-js 0.0.1-security → 1.0.1

package/packages/shopify-app-express/README.md

@@ -0,0 +1,93 @@
+# `@shopify/shopify-app-express`
+
+<!-- ![Build Status]() -->
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)
+[![npm version](https://badge.fury.io/js/%40shopify%2Fshopify-app-express.svg)](https://badge.fury.io/js/%40shopify%2Fshopify-app-express)
+
+This package makes it easy for [Express.js](https://expressjs.com/) apps to integrate with Shopify.
+It builds on the `@shopify/shopify-api` package and creates a middleware layer that allows the app to communicate with and authenticate requests from Shopify.
+
+> **Note**: this package will enable your app's backend to work with Shopify APIs, and by default it will behave as an [embedded app](https://shopify.dev/docs/apps/auth/oauth/session-tokens). You'll need to use [Shopify App Bridge](https://shopify.dev/docs/apps/tools/app-bridge) in your frontend to authenticate requests to the backend.
+
+## Requirements
+
+To follow these usage guides, you will need to:
+
+- have a Shopify Partner account and development store
+- have an app already set up on your partner account
+- have a JavaScript package manager such as [yarn](https://yarnpkg.com) installed
+
+## Getting started
+
+To install this package, you can run this on your terminal:
+
+```bash
+# Create your project folder
+mkdir /my/project/path
+# Set up a new yarn project
+yarn init .
+# You can use your preferred Node package manager
+yarn add @shopify/shopify-app-express
+```
+
+Then, you can import the package in your app by creating an `index.js` file containing:
+
+```ts
+const express = require('express');
+const {shopifyApp} = require('@shopify/shopify-app-express');
+
+const PORT = 8080;
+
+const shopify = shopifyApp({
+  api: {
+    apiKey: 'ApiKeyFromPartnersDashboard',
+    apiSecretKey: 'ApiSecretKeyFromPartnersDashboard',
+    scopes: ['your_scopes'],
+    hostScheme: 'http',
+    hostName: `localhost:${PORT}`,
+  },
+  auth: {
+    path: '/api/auth',
+    callbackPath: '/api/auth/callback',
+  },
+  webhooks: {
+    path: '/api/webhooks',
+  },
+});
+
+const app = express();
+
+app.get(shopify.config.auth.path, shopify.auth.begin());
+app.get(
+  shopify.config.auth.callbackPath,
+  shopify.auth.callback(),
+  shopify.redirectToShopifyOrAppRoot(),
+);
+app.post(
+  shopify.config.webhooks.path,
+  shopify.processWebhooks({webhookHandlers}),
+);
+
+app.get('/', shopify.ensureInstalledOnShop(), (req, res) => {
+  res.send('Hello world!');
+});
+
+app.listen(PORT, () => console.log('Server started'));
+```
+
+Once you set the appropriate configuration values, you can then run your Express app as usual, for instance using:
+
+```bash
+node ./index.js
+```
+
+To load your app within the Shopify Admin app, you need to:
+
+1. Update your app's URL in your Partners Dashboard app setup page to `http://localhost:8080`
+1. Update your app's callback URL to `http://localhost:8080/api/auth/callback` in that same page
+1. Go to **Test your app** in Partners Dashboard and select your development store
+
+## Next steps
+
+Now that your app is up and running, you can learn more about the `shopifyApp` object in [the reference docs](./docs/reference/shopifyApp.md).

package/packages/shopify-app-express/docs/reference/README.md

@@ -0,0 +1,3 @@
+# Package reference
+
+- [`shopifyApp`](./shopifyApp.md)

package/packages/shopify-app-express/docs/reference/auth.md

@@ -0,0 +1,76 @@
+# `shopify.auth`
+
+This object contains two express middleware functions: `begin` and `callback`.
+
+When setting up the OAuth routes, the app must redirect the user to the appropriate location.
+By default, we recommend using the `shopify.redirectToShopifyOrAppRoot` middleware to load your app in the correct location, but you can choose to redirect anywhere else.
+
+## Properties
+
+### `begin`
+
+`() => RequestHandler`
+
+This function returns an Express middleware that initiates an OAuth process with Shopify, by requesting the merchant to approve the selected scopes.
+It doesn't take any arguments, but the route that uses this middleware must match the configuration in `auth.path`.
+
+### `callback`
+
+`() => RequestHandler`
+
+This function returns an Express middleware that completes an OAuth process with Shopify, by validating that the call originated from Shopify and storing a `Session` in the database.
+
+The session is available to the following handlers via the `res.locals.shopify.session` object.
+
+> **Note**: this middleware **_DOES NOT_** redirect anywhere, so the request **_WILL NOT_** trigger a response by default. If you don't need to perform any actions after OAuth, we recommend using the `shopify.redirectToShopifyOrAppRoot()` middleware.
+
+## Example
+
+For example, the following callback will check for and request payment after OAuth if the merchant hasn't paid for the app yet.
+
+```ts
+const shopify = shopifyApp({
+  api: {
+    billing: {
+      'My plan': {
+        amount: 10,
+        currencyCode: 'USD',
+        interval: BillingInterval.Every30Days,
+      },
+    },
+  },
+  auth: {
+    path: '/auth',
+    callbackPath: '/auth/callback',
+  },
+});
+
+app.get(shopify.config.auth.path, shopify.auth.begin());
+app.get(
+  shopify.config.auth.callbackPath,
+  shopify.auth.callback(),
+  // Request payment if required
+  async (req, res, next) => {
+    const session = res.locals.shopify.session;
+    const hasPayment = await shopify.api.billing.check({
+      session,
+      plans: ['My plan'],
+      isTest: true,
+    });
+
+    if (hasPayment) {
+      next();
+    } else {
+      res.redirect(
+        await shopify.api.billing.request({
+          session,
+          plan: 'My plan',
+          isTest: true,
+        }),
+      );
+    }
+  },
+  // Load the app otherwise
+  shopify.redirectToShopifyOrAppRoot(),
+);
+```

package/packages/shopify-app-express/docs/reference/cspHeaders.md

@@ -0,0 +1,24 @@
+# `shopify.cspHeaders`
+
+This function creates an Express middleware that ensures any response will have the `Content-Security-Policy` header set correctly to prevent clickjacking attacks.
+
+This middleware behaves slightly differently depending on whether your app is embedded or not.
+
+- When embedded, the `Content-Security-Policy` will be set to `frame-ancestors https://admin.shopify.com/ https://[shop].myshopify.com`, where [shop] is dynamically set to the shop domain the app is embedded on.
+- When not embedded, the `Content-Security-Policy` will be set to `frame-ancestors none`.
+
+Please visit [our documentation](https://shopify.dev/docs/apps/store/security/iframe-protection) to learn more about setting up iframe protection.
+
+## Example
+
+```ts
+const app = express();
+const shopifyApp = shopifyApp({
+  //...
+});
+
+// ...
+app.use(shopifyApp.cspHeaders());
+
+// ...
+```

package/packages/shopify-app-express/docs/reference/ensureInstalledOnShop.md

@@ -0,0 +1,17 @@
+# `shopify.ensureInstalledOnShop`
+
+This function creates an Express middleware that ensures any request to that endpoint belongs to a shop that has already installed the app. You should call this middleware in any endpoint that renders HTML, if your app is embedded.
+
+You don't need to use it if your app is not embedded, because you can use `validateAuthenticatedSession` on any non-embedded request.
+If you call this middleware on a non-embedded app, it will behave like `validateAuthenticatedSession` instead.
+
+## Example
+
+```ts
+const app = express();
+
+// If the app wasn't installed in the shop, Shopify will prompt the merchant for permissions.
+app.use('/', shopify.ensureInstalledOnShop(), (req, res) => {
+  res.send('Hello world!');
+});
+```

package/packages/shopify-app-express/docs/reference/migrating-app-v6-api-lib-to-express-lib.md

@@ -0,0 +1,345 @@
+# Instructions to migrate an app based on v6 API library to use this Express library
+
+If you have an Express app that has been migrated to use version 6 of the `@shopify/shopify-api` library, this guide will show how to migrate to using this Express library.
+
+> **Note** This guide uses Shopify's node app template to demonstate the migration steps. Your app will likely have additional functionality that will need similar migration.
+
+> **Note** If you wish to practice this migration prior to applying it to your own app, create an app with one of the following commands, based on your package manager preference:
+>
+> ```shell
+> yarn create @shopify/app --template https://github.com/Shopify/shopify-app-template-node#cli_three_api_six
+> # or
+> npm init @shopify/app@latest -- --template https://github.com/Shopify/shopify-app-template-node#cli_three_api_six
+> # or
+> pnpm create @shopify/app@latest --template https://github.com/Shopify/shopify-app-template-node#cli_three_api_six
+> ```
+
+## Steps
+
+### 1. Change into the `web` directory
+
+This is root directory of where most of the changes will occur.
+
+```shell
+cd web
+```
+
+### 2. Update the project to use `v1` of the `@shopify/shopify-app-express` package
+
+```shell
+yarn remove @shopify/shopify-api cookie-parser express
+yarn add @shopify/shopify-app-express
+# or
+npm uninstall @shopify/shopify-api cookie-parser express
+npm install @shopify/shopify-app-express
+# or
+pnpm uninstall @shopify/shopify-api cookie-parser express
+pnpm install @shopify/shopify-app-express
+```
+
+### 3. Update the `gdpr.js` file
+
+This file needs to be updated to export a structure of webhook handlers that can then be passed to the Shopify Express app object. The comments have been removed from the code below for brevity.
+
+```diff
+ import { DeliveryMethod } from "@shopify/shopify-api";
+-import shopify from "./shopify.js";
+
+-export async function setupGDPRWebHooks(path) {
++export default {
+-  await shopify.webhooks.addHandlers({
+-    CUSTOMERS_DATA_REQUEST: {
+-      deliveryMethod: DeliveryMethod.Http,
+-      callbackUrl: path,
+-      callback: async (topic, shop, body, webhookId) => {
+-        const payload = JSON.parse(body);
+-      },
++  CUSTOMERS_DATA_REQUEST: {
++    deliveryMethod: DeliveryMethod.Http,
++    callbackUrl: "/api/webhooks",
++    callback: async (topic, shop, body, webhookId) => {
++      const payload = JSON.parse(body);
+     },
+-  });
++  },
+
+-  await shopify.webhooks.addHandlers({
+-    CUSTOMERS_REDACT: {
+-      deliveryMethod: DeliveryMethod.Http,
+-      callbackUrl: path,
+-      callback: async (topic, shop, body, webhookId) => {
+-        const payload = JSON.parse(body);
+-      },
++  CUSTOMERS_REDACT: {
++    deliveryMethod: DeliveryMethod.Http,
++    callbackUrl: "/api/webhooks",
++    callback: async (topic, shop, body, webhookId) => {
++      const payload = JSON.parse(body);
+     },
+-  });
++  },
+
+-  await shopify.webhooks.addHandlers({
+-    SHOP_REDACT: {
+-      deliveryMethod: DeliveryMethod.Http,
+-      callbackUrl: path,
+-      callback: async (topic, shop, body, webhookId) => {
+-        const payload = JSON.parse(body);
+-      },
++  SHOP_REDACT: {
++    deliveryMethod: DeliveryMethod.Http,
++    callbackUrl: "/api/webhooks",
++    callback: async (topic, shop, body, webhookId) => {
++      const payload = JSON.parse(body);
+     },
+-  });
+-}
++  },
++};
+```
+
+### 4. Update the `shopify.js` file
+
+When using the Express library, the Shopify API library will be available via the Shopify Express object. The Express object also requires an implementation of `SessionStorage` to manage the storage of sessions on behalf of the application.
+
+```diff
+-import "@shopify/shopify-api/adapters/node";
+-import { shopifyApi, BillingInterval, LATEST_API_VERSION } from "@shopify/shopify-api";
++import { BillingInterval, LATEST_API_VERSION } from "@shopify/shopify-api";
++import { shopifyApp } from "@shopify/shopify-app-express";
++import { SQLiteSessionStorage } from "@shopify/shopify-app-session-storage-sqlite";
+ let { restResources } = await import(
+   `@shopify/shopify-api/rest/admin/${LATEST_API_VERSION}`
+ );
+
++const DB_PATH = `${process.cwd()}/database.sqlite`;
+
+ // The transactions with Shopify will always be marked as test transactions, unless NODE_ENV is production.
+ // See the ensureBilling helper to learn more about billing in this template.
+ const billingConfig = {
+   "My Shopify One-Time Charge": {
+     // This is an example configuration that would do a one-time charge for $5 (only USD is currently supported)
+     amount: 5.0,
+     currencyCode: "USD",
+     interval: BillingInterval.OneTime,
+   },
+ };
+
+-const apiConfig = {
+-  apiKey: process.env.SHOPIFY_API_KEY,
+-  apiSecretKey: process.env.SHOPIFY_API_SECRET,
+-  scopes: process.env.SCOPES.split(","),
+-  hostName: process.env.HOST.replace(/https?:\/\//, ""),
+-  hostScheme: process.env.HOST.split("://")[0],
+-  apiVersion: LATEST_API_VERSION,
+-  isEmbeddedApp: true,
+-  ...(process.env.SHOP_CUSTOM_DOMAIN && {
+-    customShopDomains: [process.env.SHOP_CUSTOM_DOMAIN],
+-  }),
+-  billing: undefined, // or replace with billingConfig above to enable example billing
+-  restResources,
+-};
+-
+-const shopify = shopifyApi(apiConfig);
++const shopify = shopifyApp({
++  api: {
++    apiVersion: LATEST_API_VERSION,
++    billingConfig: undefined, // or replace with billingConfig above to enable example billing
++    restResources,
++  },
++  auth: {
++    path: "/api/auth",
++    callbackPath: "/api/auth/callback",
++  },
++  webhooks: {
++    path: "/api/webhooks",
++  },
++  // This should be replaced with your preferred storage strategy
++  sessionStorage: new SQLiteSessionStorage(DB_PATH),
++});
+
+ export default shopify;
+
+```
+
+> **Note** All the other API configuration values will default to
+>
+> ```ts
+> {
+>   apiKey: process.env.SHOPIFY_API_KEY,
+>   apiSecretKey: process.env.SHOPIFY_API_SECRET,
+>   scopes: process.env.SCOPES.split(","),
+>   hostName: process.env.HOST.replace(/https?:\/\//, ""),
+>   hostScheme: process.env.HOST.split("://")[0],
+>   isEmbeddedApp: true,
+> }
+> ```
+
+### 5. Move the `helpers/product-creater.js` file up one level ...
+
+Move the file from the `helpers` directory to the `web` directory. Assuming your terminal is in the `web` directory:
+
+```shell
+# Unix OS, e.g., macOS, Linux, etc.
+mv helpers/product-creator.js .
+# Windows
+move helpers\product-creator.js .
+```
+
+### 6. ... and update it to use the `shopify` Express instance
+
+Note that the `ADJECTIVES` and `NOUN` constants remain the same but have been collapsed/hidden below for brevity.
+
+```diff
+ import { GraphqlQueryError } from "@shopify/shopify-api";
+-import shopify from "../shopify.js";
++import shopify from "./shopify.js";
+
+ const ADJECTIVES = [ ...
+ ];
+
+ const NOUNS = [ ...
+ ];
+
+ export const DEFAULT_PRODUCTS_COUNT = 5;
+ const CREATE_PRODUCTS_MUTATION = `
+   mutation populateProduct($input: ProductInput!) {
+     productCreate(input: $input) {
+       product {
+         id
+       }
+     }
+   }
+ `;
+
+ export default async function productCreator(
+   session,
+   count = DEFAULT_PRODUCTS_COUNT
+ ) {
+-  const client = new shopify.clients.Graphql({ session });
++  const client = new shopify.api.clients.Graphql({ session });
+
+   try {
+     for (let i = 0; i < count; i++) {
+       await client.query({
+         data: {
+           query: CREATE_PRODUCTS_MUTATION,
+           variables: {
+             input: {
+               title: `${randomTitle()}`,
+               variants: [{ price: randomPrice() }],
+             },
+           },
+         },
+       });
+     }
+   } catch (error) {
+     if (error instanceof GraphqlQueryError) {
+       throw new Error(
+         `${error.message}\n${JSON.stringify(error.response, null, 2)}`
+       );
+     } else {
+       throw error;
+     }
+   }
+ }
+
+ function randomTitle() {
+   const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+   const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+   return `${adjective} ${noun}`;
+ }
+
+ function randomPrice() {
+   return Math.round((Math.random() * 10 + Number.EPSILON) * 100) / 100;
+ }
+```
+
+### 7. Remove unused files
+
+The following files can now be deleted, as their functionality has now been incorporated into the Express library.
+
+> **Note** These paths are relative to the `web` directory
+
+| Filename                                  | Note                                                                                                                                                                              |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sqlite-session-storage.js`               | An instance of `SQLiteSessionStorage` is passed as a configuration item to `shopifyApp` in `shopify.js`, so that the Shopify Express library can manage session storage directly. |
+| `app_installations.js`                    | The Shopify Express library uses the session storage to internally track app installations.                                                                                       |
+| `helpers/ensure-billing.js`               | :warning: maybe this needs to be retained as an example middleware?                                                                                                               |
+| `helpers/redirect-to-auth.js`             | This functionality is now incorporated into the Shopify Express library.                                                                                                          |
+| `helpers/return-top-level-redirection.js` | This functionality is now incorporated into the Shopify Express library.                                                                                                          |
+| `middleware/auth.js`                      | This functionality is now incorporated into the Shopify Express library.                                                                                                          |
+| `middleware/verify-request.js`            | This functionality is now incorporated into the Shopify Express library.                                                                                                          |
+
+### 8. Update the `index.js` file
+
+Replace the `index.js` file with the code below.
+
+```ts
+import {join} from 'path';
+import {readFileSync} from 'fs';
+import express from 'express';
+import serveStatic from 'serve-static';
+
+import shopify from './shopify.js';
+import productCreator from './product-creator.js';
+import GDPRWebhookHandlers from './gdpr.js';
+
+const PORT = parseInt(process.env.BACKEND_PORT || process.env.PORT, 10);
+
+const STATIC_PATH =
+  process.env.NODE_ENV === 'production'
+    ? `${process.cwd()}/frontend/dist`
+    : `${process.cwd()}/frontend/`;
+
+const app = express();
+
+// Set up Shopify authentication and webhook handling
+app.get(shopify.config.auth.path, shopify.auth.begin());
+app.get(
+  shopify.config.auth.callbackPath,
+  shopify.auth.callback(),
+  shopify.redirectToShopifyOrAppRoot(),
+);
+app.post(
+  shopify.config.webhooks.path,
+  shopify.processWebhooks({webhookHandlers: GDPRWebhookHandlers}),
+);
+
+// All endpoints after this point will require an active session
+app.use('/api/*', shopify.validateAuthenticatedSession());
+
+app.use(express.json());
+
+app.get('/api/products/count', async (_req, res) => {
+  const countData = await shopify.api.rest.Product.count({
+    session: res.locals.shopify.session,
+  });
+  res.status(200).send(countData);
+});
+
+app.get('/api/products/create', async (_req, res) => {
+  let status = 200;
+  let error = null;
+
+  try {
+    await productCreator(res.locals.shopify.session);
+  } catch (e) {
+    console.log(`Failed to process products/create: ${e.message}`);
+    status = 500;
+    error = e.message;
+  }
+  res.status(status).send({success: status === 200, error});
+});
+
+app.use(serveStatic(STATIC_PATH, {index: false}));
+
+app.use('/*', shopify.ensureInstalledOnShop(), async (_req, res, _next) => {
+  return res
+    .status(200)
+    .set('Content-Type', 'text/html')
+    .send(readFileSync(join(STATIC_PATH, 'index.html')));
+});
+
+app.listen(PORT);
+```

package/packages/shopify-app-express/docs/reference/processWebhooks.md

@@ -0,0 +1,67 @@
+# `shopify.processWebhooks()`
+
+This function creates an Express middleware that processes webhook requests from Shopify, based on the given handlers.
+
+It mounts the handlers onto the `shopify` object, and they're registered in `shopify.auth.callback` after we receive an access token to call the API.
+
+This middleware will always respond to Shopify, even if there was an error while handling the webhook.
+
+:exclamation: **Important**: Shopify always sends POST requests for webhooks.
+Make sure you use this middleware on a `.post()` route.
+
+## Parameters
+
+### `webhookHandlers`
+
+`{[topic: string]: WebhookHandler | WebhookHandler[]}`
+
+Defines the webhooks your app will listen to, and how to handle them. See [the `@shopify/shopify-api` documentation](https://github.com/Shopify/shopify-api-js/blob/main/packages/shopify-api/docs/guides/webhooks.md) for the allowed values.
+
+> **Note**: for HTTP webhook handlers, the `callbackUrl` value must match the route where you use this middleware.
+
+## Example
+
+The following example shows how to setup handlers for the mandatory GDPR webhooks.
+
+```ts
+const {DeliveryMethod} = require('@shopify/shopify-api');
+
+const shopify = shopifyApp({
+  webhooks: {
+    path: '/webhooks',
+  },
+});
+
+const webhookHandlers = {
+  CUSTOMERS_DATA_REQUEST: {
+    deliveryMethod: DeliveryMethod.Http,
+    callbackUrl: shopify.config.webhooks.path,
+    callback: async (topic, shop, body, webhookId, apiVersion) => {
+      const payload = JSON.parse(body);
+      // prepare customers data to send to customer
+    },
+  },
+  CUSTOMERS_REDACT: {
+    deliveryMethod: DeliveryMethod.Http,
+    callbackUrl: shopify.config.webhooks.path,
+    callback: async (topic, shop, body) => {
+      const payload = JSON.parse(body);
+      // remove customers data
+    },
+  },
+  SHOP_REDACT: {
+    deliveryMethod: DeliveryMethod.Http,
+    callbackUrl: shopify.config.webhooks.path,
+    callback: async (topic, shop, body, webhookId, apiVersion) => {
+      const payload = JSON.parse(body);
+      // remove shop data
+    },
+  },
+};
+
+// This must be a .post() endpoint
+app.post(
+  shopify.config.webhooks.path,
+  shopify.processWebhooks({webhookHandlers}),
+);
+```