shopify-app-js 0.0.1-security → 1.0.1

package/packages/shopify-app-remix/src/server/types.ts

@@ -0,0 +1,509 @@
+import {
+  RegisterReturn,
+  Shopify,
+  ShopifyRestResources,
+} from '@shopify/shopify-api';
+import {SessionStorage} from '@shopify/shopify-app-session-storage';
+
+import type {AppConfig, AppConfigArg} from './config-types';
+import type {
+  AuthenticateWebhook,
+  RegisterWebhooksOptions,
+} from './authenticate/webhooks/types';
+import type {AuthenticatePublic} from './authenticate/public/types';
+import type {AuthenticateAdmin} from './authenticate/admin/types';
+import type {Unauthenticated} from './unauthenticated/types';
+import type {AuthenticateFlow} from './authenticate/flow/types';
+import type {
+  ApiConfigWithFutureFlags,
+  ApiFutureFlags,
+  FutureFlagOptions,
+} from './future/flags';
+
+export interface BasicParams<
+  Future extends FutureFlagOptions = FutureFlagOptions,
+> {
+  api: Shopify<
+    ApiConfigWithFutureFlags<Future>,
+    ShopifyRestResources,
+    ApiFutureFlags<Future>
+  >;
+  config: AppConfig;
+  logger: Shopify['logger'];
+}
+
+export type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JSONObject
+  | JSONArray;
+
+// eslint-disable-next-line no-warning-comments
+// TODO: Use this enum to replace the isCustomStoreApp config option in shopify-api-js
+export enum AppDistribution {
+  AppStore = 'app_store',
+  SingleMerchant = 'single_merchant',
+  ShopifyAdmin = 'shopify_admin',
+}
+
+export type MandatoryTopics =
+  | 'CUSTOMERS_DATA_REQUEST'
+  | 'CUSTOMERS_REDACT'
+  | 'SHOP_REDACT';
+
+// This can't be a type because it would reference itself
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
+interface JSONObject {
+  [x: string]: JSONValue;
+}
+
+interface JSONArray extends Array<JSONValue> {}
+
+type RegisterWebhooks = (
+  options: RegisterWebhooksOptions,
+) => Promise<RegisterReturn | void>;
+
+export enum LoginErrorType {
+  MissingShop = 'MISSING_SHOP',
+  InvalidShop = 'INVALID_SHOP',
+}
+
+export interface LoginError {
+  shop?: LoginErrorType;
+}
+
+type Login = (request: Request) => Promise<LoginError | never>;
+
+type AddDocumentResponseHeaders = (request: Request, headers: Headers) => void;
+
+type RestResourcesType<Config extends AppConfigArg> =
+  Config['restResources'] extends ShopifyRestResources
+    ? Config['restResources']
+    : ShopifyRestResources;
+
+type SessionStorageType<Config extends AppConfigArg> =
+  Config['sessionStorage'] extends SessionStorage
+    ? Config['sessionStorage']
+    : SessionStorage;
+
+interface Authenticate<Config extends AppConfigArg> {
+  /**
+   * Authenticate an admin Request and get back an authenticated admin context.  Use the authenticated admin context to interact with Shopify.
+   *
+   * Examples of when to use this are requests from your app's UI, or requests from admin extensions.
+   *
+   * If there is no session for the Request, this will redirect the merchant to correct auth flows.
+   *
+   * @example
+   * <caption>Authenticating a request for an embedded app.</caption>
+   * ```ts
+   * // /app/routes/**\/*.jsx
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../../shopify.server";
+   *
+   * export async function loader({ request }: LoaderFunctionArgs) {
+   *   const {admin, session, sessionToken, billing} = authenticate.admin(request);
+   *
+   *   return json(await admin.rest.resources.Product.count({ session }));
+   * }
+   * ```
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { LATEST_API_VERSION, shopifyApp } from "@shopify/shopify-app-remix/server";
+   * import { restResources } from "@shopify/shopify-api/rest/admin/2023-04";
+   *
+   * const shopify = shopifyApp({
+   *   restResources,
+   *   // ...etc
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   */
+  admin: AuthenticateAdmin<Config, RestResourcesType<Config>>;
+
+  /**
+   * Authenticate a Flow extension Request and get back an authenticated context, containing an admin context to access
+   * the API, and the payload of the request.
+   *
+   * If there is no session for the Request, this will return an HTTP 400 error.
+   *
+   * Note that this will always be a POST request.
+   *
+   * @example
+   * <caption>Authenticating a Flow extension request.</caption>
+   * ```ts
+   * // /app/routes/**\/*.jsx
+   * import { ActionFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../../shopify.server";
+   *
+   * export async function action({ request }: ActionFunctionArgs) {
+   *   const {admin, session, payload} = authenticate.flow(request);
+   *
+   *   // Perform flow extension logic
+   *
+   *   // Return a 200 response
+   *   return null;
+   * }
+   * ```
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { LATEST_API_VERSION, shopifyApp } from "@shopify/shopify-app-remix/server";
+   * import { restResources } from "@shopify/shopify-api/rest/admin/2023-04";
+   *
+   * const shopify = shopifyApp({
+   *   restResources,
+   *   // ...etc
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   */
+  flow: AuthenticateFlow<RestResourcesType<Config>>;
+
+  /**
+   * Authenticate a public request and get back a session token.
+   *
+   * @example
+   * <caption>Authenticating a request from a checkout extension</caption>
+   *
+   * ```ts
+   * // /app/routes/api/checkout.jsx
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticate } from "../../shopify.server";
+   * import { getWidgets } from "~/db/widgets";
+   *
+   * export async function loader({ request }: LoaderFunctionArgs) {
+   *   const {sessionToken} = authenticate.public.checkout(request);
+   *
+   *   return json(await getWidgets(sessionToken));
+   * }
+   * ```
+   */
+  public: AuthenticatePublic<Config['future']>;
+
+  /**
+   * Authenticate a Shopify webhook request, get back an authenticated admin context and details on the webhook request
+   *
+   * @example
+   * <caption>Authenticating a webhook request</caption>
+   *
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { DeliveryMethod, shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   webhooks: {
+   *    APP_UNINSTALLED: {
+   *       deliveryMethod: DeliveryMethod.Http,
+   *       callbackUrl: "/webhooks",
+   *     },
+   *   },
+   *   hooks: {
+   *     afterAuth: async ({ session }) => {
+   *       shopify.registerWebhooks({ session });
+   *     },
+   *   },
+   *   // ...etc
+   * });
+   * export default shopify;
+   * export const authenticate = shopify.authenticate;
+   * ```
+   * ```ts
+   * // /app/routes/webhooks.ts
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { authenticate } from "../shopify.server";
+   * import db from "../db.server";
+   *
+   * export const action = async ({ request }: ActionFunctionArgs) => {
+   *   const { topic, shop, session } = await authenticate.webhook(request);
+   *
+   *   switch (topic) {
+   *     case "APP_UNINSTALLED":
+   *       if (session) {
+   *         await db.session.deleteMany({ where: { shop } });
+   *       }
+   *       break;
+   *     case "CUSTOMERS_DATA_REQUEST":
+   *     case "CUSTOMERS_REDACT":
+   *     case "SHOP_REDACT":
+   *     default:
+   *       throw new Response("Unhandled webhook topic", { status: 404 });
+   *   }
+   *
+   *   throw new Response();
+   * };
+   * ```
+   */
+  webhook: AuthenticateWebhook<
+    Config['future'],
+    RestResourcesType<Config>,
+    keyof Config['webhooks'] | MandatoryTopics
+  >;
+}
+
+export interface ShopifyAppBase<Config extends AppConfigArg> {
+  /**
+   * The `SessionStorage` instance you passed in as a config option.
+   *
+   * @example
+   * <caption>Storing sessions with Prisma.</caption>
+   * <description>Import the `@shopify/shopify-app-session-storage-prisma` package to store sessions in your Prisma database.</description>
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   * import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
+   * import prisma from "~/db.server";
+   *
+   * const shopify = shopifyApp({
+   *   sessionStorage: new PrismaSessionStorage(prisma),
+   *   // ...etc
+   * })
+   *
+   * // shopify.sessionStorage is an instance of PrismaSessionStorage
+   * ```
+   */
+  sessionStorage: SessionStorageType<Config>;
+
+  /**
+   * Adds the required Content Security Policy headers for Shopify apps to the given Headers object.
+   *
+   * {@link https://shopify.dev/docs/apps/store/security/iframe-protection}
+   *
+   * @example
+   * <caption>Return headers on all requests.</caption>
+   * <description>Add headers to all HTML requests by calling `shopify.addDocumentResponseHeaders` in `entry.server.tsx`.</description>
+   *
+   * ```
+   * // ~/shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   * });
+   * export default shopify;
+   * export const addDocumentResponseheaders = shopify.addDocumentResponseheaders;
+   * ```
+   *
+   * ```ts
+   * // entry.server.tsx
+   * import { addDocumentResponseHeaders } from "~/shopify.server";
+   *
+   * export default function handleRequest(
+   *   request: Request,
+   *   responseStatusCode: number,
+   *   responseHeaders: Headers,
+   *   remixContext: EntryContext
+   * ) {
+   *   const markup = renderToString(
+   *     <RemixServer context={remixContext} url={request.url} />
+   *   );
+   *
+   *   responseHeaders.set("Content-Type", "text/html");
+   *   addDocumentResponseHeaders(request, responseHeaders);
+   *
+   *   return new Response("<!DOCTYPE html>" + markup, {
+   *     status: responseStatusCode,
+   *     headers: responseHeaders,
+   *   });
+   * }
+   * ```
+   */
+  addDocumentResponseHeaders: AddDocumentResponseHeaders;
+
+  /**
+   * Register webhook topics for a store using the given session. Most likely you want to use this in combination with the afterAuth hook.
+   *
+   * @example
+   * <caption>Registering webhooks after install</caption>
+   * <description>Trigger the registration to create the webhook subscriptions after a merchant installs your app using the `afterAuth` hook. Learn more about [subscribing to webhooks.](/docs/api/shopify-app-remix/v1/guide-webhooks)</description>
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { DeliveryMethod, shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   hooks: {
+   *     afterAuth: async ({ session }) => {
+   *       shopify.registerWebhooks({ session });
+   *     }
+   *   },
+   *   webhooks: {
+   *     APP_UNINSTALLED: {
+   *       deliveryMethod: DeliveryMethod.Http,
+   *        callbackUrl: "/webhooks",
+   *     },
+   *   },
+   *   // ...etc
+   * });
+   * ```
+   */
+  registerWebhooks: RegisterWebhooks;
+
+  /**
+   * Ways to authenticate requests from different surfaces across Shopify.
+   *
+   * @example
+   * <caption>Authenticate Shopify requests.</caption>
+   * <description>Use the functions in `authenticate` to validate requests coming from Shopify.</description>
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { LATEST_API_VERSION, shopifyApp } from "@shopify/shopify-app-remix/server";
+   * import { restResources } from "@shopify/shopify-api/rest/admin/2023-04";
+   *
+   * const shopify = shopifyApp({
+   *   restResources,
+   *   // ...etc
+   * });
+   * export default shopify;
+   * ```
+   * ```ts
+   * // /app/routes/**\/*.jsx
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import shopify from "../../shopify.server";
+   *
+   * export async function loader({ request }: LoaderFunctionArgs) {
+   *   const {admin, session, sessionToken, billing} = shopify.authenticate.admin(request);
+   *
+   *   return json(await admin.rest.resources.Product.count({ session }));
+   * }
+   * ```
+   */
+  authenticate: Authenticate<Config>;
+
+  /**
+   * Ways to get Contexts from requests that do not originate from Shopify.
+   *
+   * @example
+   * <caption>Using unauthenticated contexts.</caption>
+   * <description>Create contexts for requests that don't come from Shopify.</description>
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { LATEST_API_VERSION, shopifyApp } from "@shopify/shopify-app-remix/server";
+   * import { restResources } from "@shopify/shopify-api/rest/admin/2023-04";
+   *
+   * const shopify = shopifyApp({
+   *   restResources,
+   *   // ...etc
+   * });
+   * export default shopify;
+   * ```
+   * ```ts
+   * // /app/routes/**\/*.jsx
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { authenticateExternal } from "~/helpers/authenticate"
+   * import shopify from "../../shopify.server";
+   *
+   * export async function loader({ request }: LoaderFunctionArgs) {
+   *   const shop = await authenticateExternal(request)
+   *   const {admin} = await shopify.unauthenticated.admin(shop);
+   *
+   *   return json(await admin.rest.resources.Product.count({ session }));
+   * }
+   * ```
+   */
+  unauthenticated: Unauthenticated<RestResourcesType<Config>>;
+}
+
+interface ShopifyAppLogin {
+  /**
+   * Log a merchant in, and redirect them to the app root. Will redirect the merchant to authentication if a shop is
+   * present in the URL search parameters or form data.
+   *
+   * This function won't be present when the `distribution` config option is set to `AppDistribution.ShopifyAdmin`,
+   * because Admin apps aren't allowed to show a login page.
+   *
+   * @example
+   * <caption>Creating a login page.</caption>
+   * <description>Use `shopify.login` to create a login form, in a route that can handle GET and POST requests.</description>
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { LATEST_API_VERSION, shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *   // ...etc
+   * });
+   * export default shopify;
+   * ```
+   * ```ts
+   * // /app/routes/auth/login.tsx
+   * import shopify from "../../shopify.server";
+   *
+   * export async function loader({ request }: LoaderFunctionArgs) {
+   *   const errors = shopify.login(request);
+   *
+   *   return json(errors);
+   * }
+   *
+   * export async function action({ request }: ActionFunctionArgs) {
+   *   const errors = shopify.login(request);
+   *
+   *   return json(errors);
+   * }
+   *
+   * export default function Auth() {
+   *   const actionData = useActionData<typeof action>();
+   *   const [shop, setShop] = useState("");
+   *
+   *   return (
+   *     <Page>
+   *       <Card>
+   *         <Form method="post">
+   *           <FormLayout>
+   *             <Text variant="headingMd" as="h2">
+   *               Login
+   *             </Text>
+   *             <TextField
+   *               type="text"
+   *               name="shop"
+   *               label="Shop domain"
+   *               helpText="e.g: my-shop-domain.myshopify.com"
+   *               value={shop}
+   *               onChange={setShop}
+   *               autoComplete="on"
+   *               error={actionData?.errors.shop}
+   *             />
+   *             <Button submit primary>
+   *               Submit
+   *             </Button>
+   *           </FormLayout>
+   *         </Form>
+   *       </Card>
+   *     </Page>
+   *   );
+   * }
+   * ```
+   */
+  login: Login;
+}
+
+export type ShopifyAppLogger = {
+  /**
+   * Shopify App Logger
+   */
+
+  logger: Shopify['logger'];
+};
+
+export type AdminApp<Config extends AppConfigArg> = ShopifyAppBase<Config> &
+  ShopifyAppLogger;
+export type SingleMerchantApp<Config extends AppConfigArg> =
+  ShopifyAppBase<Config> & ShopifyAppLogin & ShopifyAppLogger;
+export type AppStoreApp<Config extends AppConfigArg> = ShopifyAppBase<Config> &
+  ShopifyAppLogin &
+  ShopifyAppLogger;
+
+/**
+ * An object your app can use to interact with Shopify.
+ *
+ * By default, the app's distribution is `AppStore`.
+ */
+export type ShopifyApp<Config extends AppConfigArg> =
+  Config['distribution'] extends AppDistribution.ShopifyAdmin
+    ? AdminApp<Config>
+    : Config['distribution'] extends AppDistribution.SingleMerchant
+      ? SingleMerchantApp<Config>
+      : Config['distribution'] extends AppDistribution.AppStore
+        ? AppStoreApp<Config>
+        : AppStoreApp<Config>;

package/packages/shopify-app-remix/src/server/unauthenticated/admin/__tests__/factory.test.ts

@@ -0,0 +1,30 @@
+import {SessionNotFoundError, shopifyApp} from '../../../index';
+import {
+  TEST_SHOP,
+  setUpValidSession,
+  testConfig,
+  expectAdminApiClient,
+} from '../../../__test-helpers';
+
+describe('unauthenticated admin context', () => {
+  it('throws an error if there is no offline session for the shop', async () => {
+    // GIVEN
+    const shopify = shopifyApp(testConfig());
+
+    // EXPECT
+    await expect(shopify.unauthenticated.admin(TEST_SHOP)).rejects.toThrow(
+      SessionNotFoundError,
+    );
+  });
+
+  expectAdminApiClient(async () => {
+    const shopify = shopifyApp(testConfig());
+    const expectedSession = await setUpValidSession(shopify.sessionStorage, {
+      isOnline: false,
+    });
+    const {admin, session: actualSession} =
+      await shopify.unauthenticated.admin(TEST_SHOP);
+
+    return {admin, expectedSession, actualSession};
+  });
+});

package/packages/shopify-app-remix/src/server/unauthenticated/admin/factory.ts

@@ -0,0 +1,29 @@
+import {ShopifyRestResources} from '@shopify/shopify-api';
+
+import {SessionNotFoundError} from '../../errors';
+import {BasicParams} from '../../types';
+import {adminClientFactory} from '../../clients/admin';
+import {getOfflineSession} from '../helpers';
+
+import {UnauthenticatedAdminContext} from './types';
+
+export function unauthenticatedAdminContextFactory<
+  Resources extends ShopifyRestResources,
+>(params: BasicParams) {
+  return async (
+    shop: string,
+  ): Promise<UnauthenticatedAdminContext<Resources>> => {
+    const session = await getOfflineSession(shop, params);
+
+    if (!session) {
+      throw new SessionNotFoundError(
+        `Could not find a session for shop ${shop} when creating unauthenticated admin context`,
+      );
+    }
+
+    return {
+      session,
+      admin: adminClientFactory<Resources>({params, session}),
+    };
+  };
+}

package/packages/shopify-app-remix/src/server/unauthenticated/admin/index.ts

@@ -0,0 +1 @@
+export * from './factory';

package/packages/shopify-app-remix/src/server/unauthenticated/admin/types.ts

@@ -0,0 +1,117 @@
+import {Session, ShopifyRestResources} from '@shopify/shopify-api';
+
+import {AdminApiContext} from '../../clients';
+
+export interface UnauthenticatedAdminContext<
+  Resources extends ShopifyRestResources,
+> {
+  /**
+   * The session for the given shop.
+   *
+   * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.
+   *
+   * This will always be an offline session. You can use to get shop-specific data.
+   *
+   * @example
+   * <caption>Using the offline session.</caption>
+   * <description>Get your app's shop-specific data using the returned offline `session` object.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { unauthenticated } from "../shopify.server";
+   * import { getMyAppData } from "~/db/model.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *   const shop = getShopFromExternalRequest(request);
+   *   const { session } = await unauthenticated.admin(shop);
+   *   return json(await getMyAppData({shop: session.shop));
+   * };
+   * ```
+   */
+  session: Session;
+
+  /**
+   * Methods for interacting with the GraphQL / REST Admin APIs for the given store.
+   *
+   * @example
+   * <caption>Performing a GET request to the REST API.</caption>
+   * <description>Use `admin.rest.get` to make custom requests to make a request to to the `customer/count` endpoint</description>
+   *
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { LoaderFunctionArgs, json } from "@remix-run/node";
+   * import { unauthenticated } from "../shopify.server";
+   *
+   * export const loader = async ({ request }: LoaderFunctionArgs) => {
+   *  const { admin, session } = await unauthenticated.admin(request);
+   *
+   *  const response = await admin.rest.get(
+   *    {
+   *      path: "/customers/count.json"
+   *    }
+   *  );
+   *  const customers = await response.json();
+   *
+   *  return json({ customers });
+   * };
+   * ```
+   *
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   * import { restResources } from "@shopify/shopify-api/rest/admin/2023-04";
+   *
+   * const shopify = shopifyApp({
+   *  restResources,
+   *  // ...etc
+   * });
+   *
+   * export default shopify;
+   * export const unauthenticated = shopify.unauthenticated;
+   * ```
+   * @example
+   * <caption>Querying the GraphQL API.</caption>
+   * <description>Use `admin.graphql` to make query / mutation requests.</description>
+   * ```ts
+   * // /app/routes/**\/*.ts
+   * import { ActionFunctionArgs } from "@remix-run/node";
+   * import { unauthenticated } from "../shopify.server";
+   *
+   * export async function action({ request }: ActionFunctionArgs) {
+   *  const { admin } = await unauthenticated.admin(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 });
+   * }
+   * ```
+   *
+   * ```ts
+   * // /app/shopify.server.ts
+   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
+   *
+   * const shopify = shopifyApp({
+   *  restResources,
+   *  // ...etc
+   * });
+   * export default shopify;
+   * export const unauthenticated = shopify.unauthenticated;
+   * ```
+   */
+  admin: AdminApiContext<Resources>;
+}
+
+export type GetUnauthenticatedAdminContext<
+  Resources extends ShopifyRestResources,
+> = (shop: string) => Promise<UnauthenticatedAdminContext<Resources>>;