shopify-app-js 0.0.1-security → 1.0.1

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

@@ -0,0 +1,77 @@
+# `shopify.redirectOutOfApp()`
+
+This function enables apps to redirect out of the app's host, regardless of how a request reached the app.
+It covers the following scenarios:
+
+- If the request came from an `authenticatedFetch` call, it'll return the right headers for App Bridge.
+- If the request came from an app embedded in the Shopify Admin, it'll use `config.exitIframePath`.
+- Otherwise, it will trigger a normal HTTP redirect.
+
+## Parameters
+
+This function takes in an object with the following properties:
+
+### `req`
+
+`express.Request`
+
+The Express.js request object.
+
+### `res`
+
+`express.Response`
+
+The Express.js response object.
+
+### `redirectUri`
+
+`string`
+
+The URI to redirect to.
+
+### `shop`
+
+`string`
+
+The shop for this request.
+
+## Example
+
+The following example shows how to redirect out of the app for requests that render HTML or return JSON data.
+
+```ts
+const shopify = shopifyApp({});
+
+const redirectMiddleware = (req, res, next) => {
+  if (redirectRequired) {
+    shopify.redirectOutOfApp({
+      req,
+      res,
+      redirectUri: '/my-non-embedded-endpoint',
+      shop: shopify.api.utils.sanitizeShop(req.query.shop),
+    });
+  } else {
+    next();
+  }
+};
+
+app.get(
+  '/api/endpoint-that-redirects',
+  shopify.validateAuthenticatedSession(),
+  // redirectOutOfApp will cause App Bridge to trigger the redirect
+  redirectMiddleware,
+  (req, res) => {
+    // Handle request as usual
+  },
+);
+
+app.get(
+  '/html-endpoint',
+  shopify.ensureInstalledOnShop(),
+  // redirectOutOfApp will cause the app to break out of the iframe
+  redirectMiddleware,
+  (req, res) => {
+    // Handle request as usual
+  },
+);
+```

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

@@ -0,0 +1,20 @@
+# `shopify.redirectToShopifyOrAppRoot`
+
+This function creates an Express middleware that loads the app's root, and ensures that it loads in the appropriate location.
+
+For instance, if this is an embedded app, it will redirect to the Shopify Admin and embed the app within it, but if the app is not embedded, it will load it at the browser's top level.
+
+> **Note**: This middleware expects a session to be available in `res.locals.shopify.session`.
+
+## Example
+
+```ts
+const app = express();
+
+// Once OAuth completes, return to the app root in the appropriate location.
+app.get(
+  '/auth/callback',
+  shopify.auth.callback(),
+  shopify.redirectToShopifyOrAppRoot(),
+);
+```

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

@@ -0,0 +1,148 @@
+# `shopifyApp`
+
+This function creates an object that contains everything an Express app needs to interact with Shopify.
+
+## Parameters
+
+### api
+
+`ApiConfigParams` | :exclamation: required when not using the Shopify CLI
+
+All values allowed by the `@shopify/shopify-api` package [when calling `shopifyApi`](https://github.com/Shopify/shopify-api-js/blob/main/packages/shopify-api/docs/reference/shopifyApi.md).
+
+### auth
+
+Configurations for OAuth using this package.
+See below for the specific details.
+
+#### path
+
+`string` | :exclamation: required
+
+The URL path used by the app to start the OAuth process.
+This must match the path you use for the `shopify.auth.begin` route.
+
+#### callbackPath
+
+`string` | :exclamation: required
+
+The URL path used by the app to complete the OAuth process.
+It works in the same way as `path` above, and it must match the path of the route that uses `shopify.auth.callback`.
+
+### webhooks
+
+Configurations for Webhooks using this package.
+
+#### path
+
+`string` | :exclamation: required
+
+The URL path used by the app to receive HTTP webhooks from Shopify.
+This must match the path of the route that uses `shopify.processWebhooks`.
+
+### useOnlineTokens
+
+`boolean` | Defaults to `false`
+
+Whether the OAuth process should produce online access tokens as well as offline ones (created by default).
+Learn more about [access modes in Shopify APIs](https://shopify.dev/docs/apps/auth/oauth/access-modes).
+
+### exitIframePath
+
+`string` | Defaults to `"/exitiframe"`
+
+The path your app's frontend uses to trigger an App Bridge redirect to leave the Shopify Admin before starting OAuth.
+Since that page is in the app frontend, we don't include it in this package, but you can find [an example in our template](https://github.com/Shopify/shopify-frontend-template-react/blob/main/pages/ExitIframe.jsx).
+
+## Return
+
+Returns an object that contains everything an app needs to interact with Shopify:
+
+### config
+
+`{[key: string]: any}`
+
+The configuration used to set up this object.
+
+### api
+
+The object created by the `@shopify/shopify-api` package. See [the API package documentation](https://github.com/Shopify/shopify-api-js#readme) for more details.
+
+### [auth](./auth.md)
+
+```ts
+{begin: () => RequestHandler, callback: () => RequestHandler}
+```
+
+An object containing both middlewares you'll need to authenticate with Shopify.
+
+### [processWebhooks](./processWebhooks.md)
+
+`(ProcessWebhooksMiddlewareParams) => RequestHandler`
+
+A function that returns a middleware that processes Shopify webhook requests.
+This _must_ be a `post` route.
+
+### [validateAuthenticatedSession](./validateAuthenticatedSession.md)
+
+`() => RequestHandler`
+
+A function that returns an Express middleware that verifies that the request received is authenticated with a valid session for embedded apps.
+
+### [ensureInstalledOnShop](./ensureInstalledOnShop.md)
+
+`() => RequestHandler`
+
+A function that returns an Express middleware that verifies that the request received is for a shop that has installed the app when rendering HTML.
+
+### [redirectToShopifyOrAppRoot](./redirectToShopifyOrAppRoot.md)
+
+`() => RequestHandler`
+
+A function that returns an Express middleware that redirects the user to the app, embedding it into Shopify depending on `api.isEmbeddedApp`.
+
+### [redirectOutOfApp](./redirectOutOfApp.md)
+
+`(RedirectOutOfAppParams) => void`
+
+A function that redirects to any URL at the browser's top level, regardless of where the request originated from.
+
+## Example
+
+```ts
+const shopify = shopifyApp({
+  api: {
+    apiKey: 'ApiKeyFromPartnersDashboard',
+    apiSecretKey: 'ApiSecretKeyFromPartnersDashboard',
+    scopes: ['your_scopes'],
+    hostScheme: 'http',
+    hostName: `localhost:${PORT}`,
+    billing: {
+      'My plan': {
+        amount: 10,
+        currencyCode: 'USD',
+        interval: BillingInterval.Every30Days,
+      },
+    },
+  },
+  auth: {
+    path: '/auth',
+    callbackPath: '/auth/callback',
+  },
+  webhooks: {
+    path: '/webhooks',
+  },
+});
+
+// The paths to these routes must match the configured values above
+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}),
+);
+```

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

@@ -0,0 +1,30 @@
+# `shopify.validateAuthenticatedSession`
+
+This function creates an Express middleware that ensures any request to that endpoint will have a valid session (i.e., not expired, access token available, scopes match).
+
+This middleware behaves slightly differently depending on whether your app is embedded or not.
+If the verification fails in either case, it will redirect the user to complete OAuth, thereby ensuring that a valid session is available to continue processing.
+
+- When embedded, it will verify that the request received from the front-end originates from an App Bridge `authenticatedFetch`.
+- When not embedded, it will verify that the request contains a valid session cookie set up during the OAuth process.
+  - XHR requests will return a `403 Forbidden` response with the `X-Shopify-Api-Request-Failure-Reauthorize-Url` header indicating where to redirect the user for authentication.
+
+Please visit [our documentation](https://shopify.dev/docs/apps/auth/oauth/session-tokens) to learn more about session tokens and how they work.
+
+## Example
+
+```ts
+const app = express();
+
+app.get(
+  '/api/product/count',
+  shopify.validateAuthenticatedSession(),
+  async (res, req) => {
+    // because of shopify.validateAuthenticatedSession(), session is available
+    // in res.locals.shopify.session
+    const session = res.locals.shopify.session;
+
+    // Interact with the API
+  },
+);
+```

package/packages/shopify-app-express/loom.config.ts

@@ -0,0 +1,27 @@
+import {createPackage, createProjectPlugin} from '@shopify/loom';
+import {buildLibrary} from '@shopify/loom-plugin-build-library';
+
+export default createPackage((pkg) => {
+  pkg.entry({root: './src/index.ts'});
+  pkg.use(
+    buildLibrary({
+      // Required. A browserslist string for specifying your target output.
+      // Use browser targets (e.g. `'defaults'`) if your package targets the browser,
+      // node targets (e.g. `'node 12.22'`) if your package targets node
+      // or both (e.g.`'defaults, node 12.22'`) if your package targets both
+      targets: 'node 16',
+      // Optional. Defaults to false. Defines if commonjs outputs should be generated.
+      commonjs: true,
+      // Optional. Defaults to false. Defines if esmodules outputs should be generated.
+      esmodules: false,
+      // Optional. Defaults to false. Defines if esnext outputs should be generated.
+      esnext: false,
+      // Optional. Defaults to true. Defines if entrypoints should be written at
+      // the root of the repository. You can disable this if you have a single
+      // entrypoint or if your package uses the `exports` key in package.json
+      rootEntrypoints: false,
+      // Optional. Defaults to 'node'. Defines if the jest environment should be 'node' or 'jsdom'.
+      jestTestEnvironment: 'node',
+    }),
+  );
+});

package/packages/shopify-app-express/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@shopify/shopify-app-express",
+  "version": "4.1.2",
+  "description": "Shopify Express Middleware - to simplify the building of Shopify Apps with Express",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shopify/shopify-app-express.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Shopify/shopify-app-express/issues"
+  },
+  "homepage": "https://github.com/Shopify/shopify-app-express/tree/main/packages/shopify-app-express",
+  "author": "Shopify Inc.",
+  "license": "MIT",
+  "main": "./build/cjs/index.js",
+  "types": "./build/ts/index.d.ts",
+  "scripts": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "shopify",
+    "node",
+    "express",
+    "app",
+    "graphql",
+    "rest",
+    "webhook",
+    "Admin API",
+    "Storefront API"
+  ],
+  "dependencies": {
+    "@shopify/shopify-api": "^9.3.2",
+    "@shopify/shopify-app-session-storage": "^2.1.1",
+    "@shopify/shopify-app-session-storage-memory": "^3.0.1",
+    "cookie-parser": "^1.4.6",
+    "express": "^4.18.1",
+    "semver": "^7.6.0"
+  },
+  "devDependencies": {
+    "@types/compression": "^1.7.5",
+    "@types/cookie-parser": "^1.4.6",
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.5",
+    "jsonwebtoken": "^9.0.2",
+    "supertest": "^6.3.3"
+  },
+  "files": [
+    "build/*",
+    "!bundle/*",
+    "!tsconfig.tsbuildinfo",
+    "!node_modules"
+  ]
+}

package/packages/shopify-app-express/src/__tests__/index.test.ts

@@ -0,0 +1,100 @@
+import {
+  FeatureDeprecatedError,
+  LogSeverity,
+  ShopifyError,
+} from '@shopify/shopify-api';
+
+import {shopifyApp} from '../index';
+import {SHOPIFY_EXPRESS_LIBRARY_VERSION} from '../version';
+
+import {testConfig} from './test-helper';
+
+describe('shopifyApp', () => {
+  /* eslint-disable no-process-env */
+  const oldEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = {...oldEnv};
+  });
+
+  afterAll(() => {
+    process.env = oldEnv;
+  });
+  /* eslint-enable no-process-env */
+
+  it('can create an app object', () => {
+    const shopify = shopifyApp(testConfig);
+
+    expect(shopify).toBeDefined();
+    expect(shopify.api).toBeDefined();
+    expect(shopify.api.config.apiKey).toBe(testConfig.api.apiKey);
+  });
+
+  it('fails with an invalid config', () => {
+    expect(() => shopifyApp({} as any)).toThrowError(ShopifyError);
+  });
+
+  it('properly defaults missing configs based on env vars', () => {
+    /* eslint-disable no-process-env */
+    process.env.SHOPIFY_API_KEY = 'envKey';
+    process.env.SHOPIFY_API_SECRET = 'envSecret';
+    process.env.SCOPES = 'envScope1,envScope2';
+    process.env.HOST = 'https://envHost';
+    process.env.SHOP_CUSTOM_DOMAIN = '*.envCustomDomain';
+
+    const shopify = shopifyApp({
+      auth: testConfig.auth,
+      webhooks: testConfig.webhooks,
+      api: {
+        logger: testConfig.api.logger,
+      },
+    });
+
+    expect(shopify).toBeDefined();
+    expect(shopify.api.config.apiKey).toEqual('envKey');
+    expect(shopify.api.config.apiSecretKey).toEqual('envSecret');
+    expect(shopify.api.config.scopes.toString()).toEqual('envScope1,envScope2');
+    expect(shopify.api.config.hostName).toEqual('envHost');
+    expect(shopify.api.config.hostScheme).toEqual('https');
+    expect(shopify.api.config.customShopDomains).toEqual(['*.envCustomDomain']);
+    /* eslint-enable no-process-env */
+  });
+
+  it('properly sets the package in log calls', async () => {
+    const shopify = shopifyApp(testConfig);
+
+    shopify.config.logger.info('test');
+
+    expect(shopify.api.config.logger.log).toHaveBeenCalledWith(
+      LogSeverity.Info,
+      '[shopify-app/INFO] test',
+    );
+
+    shopify.config.logger.info('test', {extra: 'context'});
+
+    expect(shopify.api.config.logger.log).toHaveBeenCalledWith(
+      LogSeverity.Info,
+      '[shopify-app/INFO] test | {extra: context}',
+    );
+  });
+
+  it('properly logs deprecation messages', async () => {
+    const shopify = shopifyApp(testConfig);
+
+    shopify.config.logger.deprecated('9999.0.0', 'test');
+
+    expect(shopify.api.config.logger.log).toHaveBeenCalledWith(
+      LogSeverity.Warning,
+      '[shopify-app/WARNING] [Deprecated | 9999.0.0] test',
+    );
+  });
+
+  it('throws when deprecation version is reached', async () => {
+    const shopify = shopifyApp(testConfig);
+
+    expect(() =>
+      shopify.config.logger.deprecated(SHOPIFY_EXPRESS_LIBRARY_VERSION, 'test'),
+    ).toThrow(FeatureDeprecatedError);
+  });
+});