@tenderprompt/accounts 0.2.0

package/templates/shopify-customer-account/apps/gateway/src/platform/customer-auth/shopify-route-adapter.ts

@@ -0,0 +1,1157 @@
+import type { CustomerAuthHostnamePolicy } from "./session-store";
+import {
+  CustomerAuthFlowCapacityError,
+  PublicCustomerAuthSessionStore,
+} from "./session-store";
+
+const DEFAULT_LOGIN_PATH = "/auth/login";
+const DEFAULT_CALLBACK_PATH = "/auth/callback";
+const DEFAULT_HANDOFF_PATH = "/auth/handoff";
+const DEFAULT_SESSION_PATH = "/api/session";
+const DEFAULT_LOGOUT_PATH = "/auth/logout";
+const DEFAULT_POST_LOGOUT_PATH = "/auth/logout/callback";
+const DEFAULT_SIGNED_IN_PATH = "/account";
+const DEFAULT_SIGNED_OUT_PATH = "/";
+const FLOW_TTL_SECONDS = 5 * 60;
+const HANDOFF_TTL_SECONDS = 60;
+const MAX_REQUEST_URL_LENGTH = 8_192;
+const MAX_FORM_BODY_BYTES = 1_024;
+const MAX_COOKIE_HEADER_LENGTH = 8_192;
+const MAX_DISCOVERY_BYTES = 16_384;
+const MAX_TOKEN_BYTES = 65_536;
+const MAX_GRAPHQL_BYTES = 65_536;
+const MAX_ENDPOINT_LENGTH = 2_048;
+const MAX_ACCESS_TOKEN_LENGTH = 32_768;
+const MAX_ID_TOKEN_LENGTH = 16_384;
+const MAX_SESSION_TTL_SECONDS = 31 * 24 * 60 * 60;
+const SHOPPER_SESSION_RECORD_TTL_SECONDS = MAX_SESSION_TTL_SECONDS;
+const PROVIDER_FETCH_TIMEOUT_MS = 10_000;
+const DEFAULT_PROVIDER_USER_AGENT = "TenderAccountsCustomerAuth/0.1";
+const PROVIDER_REDIRECT_MODE = "manual" as const;
+
+export const PUBLIC_CUSTOMER_AUTH_SESSION_COOKIE = "__Host-tender_accounts_session";
+export const PUBLIC_CUSTOMER_AUTH_FLOW_COOKIE = "__Host-tender_accounts_auth_flow";
+
+export const SHOPIFY_CUSTOMER_IDENTITY_QUERY = `query CustomerIdentity {
+  customer {
+    id
+    displayName
+    emailAddress {
+      emailAddress
+    }
+  }
+}`;
+
+export interface ShopifyCustomerAccountRouteConfig {
+  projectId: string;
+  canonicalHostname: string;
+  additionalCallbackHostnames?: readonly string[];
+  storefrontDomain: string;
+  clientId: string;
+  providerUserAgent?: string;
+  additionalProviderHostnames?: readonly string[];
+  loginPath?: string;
+  callbackPath?: string;
+  handoffPath?: string;
+  sessionPath?: string;
+  logoutPath?: string;
+  postLogoutPath?: string;
+  signedInPath?: string;
+  signedOutPath?: string;
+}
+
+export type CustomerAuthProviderFetch = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export type CustomerAuthClientKey = (request: Request) => string | Promise<string>;
+
+export interface ShopifyCustomerAccountRouteAdapter {
+  /** Returns null when the request does not target one of the adapter's exact paths. */
+  handle(request: Request): Promise<Response | null>;
+}
+
+/**
+ * Reusable merchant-Worker routes for a Shopify Customer Account public client.
+ * The adapter intentionally has no client-secret option: it performs the public
+ * authorization-code flow with S256 PKCE and keeps every provider token in D1.
+ */
+export function createShopifyCustomerAccountRouteAdapter(input: {
+  config: ShopifyCustomerAccountRouteConfig;
+  sessionStore: PublicCustomerAuthSessionStore;
+  hostnamePolicy: CustomerAuthHostnamePolicy;
+  providerFetch?: CustomerAuthProviderFetch;
+  authorizationClientKey?: CustomerAuthClientKey;
+}): ShopifyCustomerAccountRouteAdapter {
+  if (!(input.sessionStore instanceof PublicCustomerAuthSessionStore)) {
+    throw new Error("A public customer authentication session store is required.");
+  }
+  if (typeof input.hostnamePolicy !== "function") {
+    throw new Error("A public customer authentication hostname policy is required.");
+  }
+  const config = validateConfig(input.config);
+  const providerFetch = input.providerFetch ?? fetch;
+  if (typeof providerFetch !== "function") {
+    throw new Error("A Shopify provider fetch implementation is required.");
+  }
+  const authorizationClientKey = input.authorizationClientKey ?? cloudflareAuthorizationClientKey;
+  if (typeof authorizationClientKey !== "function") {
+    throw new Error("A customer authentication client-key implementation is required.");
+  }
+  const routeInput = {
+    sessionStore: input.sessionStore,
+    hostnamePolicy: input.hostnamePolicy,
+    authorizationClientKey,
+  };
+
+  return {
+    async handle(request: Request): Promise<Response | null> {
+      try {
+        const routeUrl = parsedRequestUrl(request);
+        const route = routeFor(config, routeUrl.pathname);
+        if (!route) return null;
+        const requestUrl = validatedRequestUrl(routeUrl);
+        if (request.method !== route.method) return methodNotAllowed(route.method);
+
+        switch (route.name) {
+          case "login":
+            return await handleLogin({ request, requestUrl, config, input: routeInput, providerFetch });
+          case "callback":
+            return await handleCallback({ request, requestUrl, config, input: routeInput, providerFetch });
+          case "handoff":
+            return await handleHandoff({ request, requestUrl, config, input: routeInput });
+          case "session":
+            return await handleSession({ request, requestUrl, config, input: routeInput, providerFetch });
+          case "logout":
+            return await handleLogout({ request, requestUrl, config, input: routeInput });
+          case "postLogout":
+            return handlePostLogout({ requestUrl, config });
+        }
+      } catch (error) {
+        if (error instanceof SafeHttpError) return safeError(error.status, error.code);
+        if (error instanceof CustomerAuthFlowCapacityError) {
+          return safeError(429, "customer_authentication_busy");
+        }
+        if (error instanceof ProviderFailure) return safeError(502, "customer_authentication_unavailable");
+        return safeError(500, "customer_authentication_failed");
+      }
+    },
+  };
+}
+
+async function handleLogin(context: RequestRouteContext & {
+  providerFetch: CustomerAuthProviderFetch;
+}): Promise<Response> {
+  const callbackHostname = requireCallbackHostname(context.requestUrl, context.config);
+  const returnHostname = requiredSingleQueryValue(context.requestUrl, "return_host", 253);
+  const prompt = optionalSingleQueryValue(context.requestUrl, "prompt", 4, /^(?:none)$/);
+  if (!await isAllowedHostname(context.input, context.config.projectId, returnHostname)) {
+    throw new SafeHttpError(400, "invalid_return_host");
+  }
+
+  const verifier = randomBase64Url(32);
+  const challenge = await sha256Base64Url(verifier);
+  const flow = await context.input.sessionStore.createAuthorizationFlow({
+    projectId: context.config.projectId,
+    pkceVerifier: verifier,
+    returnHostname,
+    clientKey: await requiredAuthorizationClientKey(context.input.authorizationClientKey, context.request),
+    interactionMode: prompt === "none" ? "silent" : "interactive",
+    ttlSeconds: FLOW_TTL_SECONDS,
+  });
+  let discovery: Awaited<ReturnType<typeof discoverOpenId>>;
+  try {
+    discovery = await discoverOpenId(context.config, context.providerFetch);
+  } catch (error) {
+    await context.input.sessionStore.consumeAuthorizationFlow({
+      projectId: context.config.projectId,
+      state: flow.state,
+      browserBinding: flow.browserBinding,
+    });
+    throw error;
+  }
+  const authorizationUrl = new URL(discovery.authorizationEndpoint);
+  authorizationUrl.searchParams.set("scope", "openid email customer-account-api:full");
+  authorizationUrl.searchParams.set("client_id", context.config.clientId);
+  authorizationUrl.searchParams.set("response_type", "code");
+  authorizationUrl.searchParams.set("redirect_uri", callbackUrl(context.config, callbackHostname));
+  authorizationUrl.searchParams.set("state", flow.state);
+  authorizationUrl.searchParams.set("code_challenge", challenge);
+  authorizationUrl.searchParams.set("code_challenge_method", "S256");
+  if (prompt) authorizationUrl.searchParams.set("prompt", prompt);
+  return redirectResponse(authorizationUrl.toString(), 302, {
+    "Set-Cookie": authorizationFlowCookie(flow.state, flow.browserBinding),
+  });
+}
+
+async function handleCallback(context: RequestRouteContext & {
+  providerFetch: CustomerAuthProviderFetch;
+}): Promise<Response> {
+  const callbackHostname = requireCallbackHostname(context.requestUrl, context.config);
+  const state = requiredSingleQueryValue(context.requestUrl, "state", 43, /^[A-Za-z0-9_-]{43}$/);
+  const browserBinding = readOpaqueCookie(
+    context.request.headers.get("Cookie"),
+    authorizationFlowCookieName(state),
+  );
+  if (!browserBinding) throw new SafeHttpError(400, "invalid_authorization_state");
+  if (context.requestUrl.searchParams.has("error")) {
+    const providerError = requiredSingleQueryValue(
+      context.requestUrl,
+      "error",
+      256,
+      /^[A-Za-z0-9._-]+$/,
+    );
+    const deniedFlow = await context.input.sessionStore.consumeAuthorizationFlow({
+      projectId: context.config.projectId,
+      state,
+      browserBinding,
+    });
+    if (!deniedFlow) throw new SafeHttpError(400, "invalid_authorization_state");
+    if (providerError === "login_required" && deniedFlow.interactionMode === "silent") {
+      const interactiveUrl = new URL(`https://${callbackHostname}${context.config.loginPath}`);
+      interactiveUrl.searchParams.set("return_host", deniedFlow.returnHostname);
+      return handleLogin({
+        request: new Request(interactiveUrl, { headers: context.request.headers }),
+        requestUrl: interactiveUrl,
+        config: context.config,
+        input: context.input,
+        providerFetch: context.providerFetch,
+      });
+    }
+    return safeError(400, "customer_authentication_denied");
+  }
+  const code = requiredSingleQueryValue(context.requestUrl, "code", 4_096, /^[A-Za-z0-9._~-]+$/);
+  const flow = await context.input.sessionStore.consumeAuthorizationFlow({
+    projectId: context.config.projectId,
+    state,
+    browserBinding,
+  });
+  if (!flow) throw new SafeHttpError(400, "invalid_authorization_state");
+  if (!await isAllowedHostname(context.input, context.config.projectId, flow.returnHostname)) {
+    return safeError(400, "invalid_return_host");
+  }
+
+  try {
+    const openId = await discoverOpenId(context.config, context.providerFetch);
+    const token = await exchangeAuthorizationCode({
+      config: context.config,
+      providerFetch: context.providerFetch,
+      tokenEndpoint: openId.tokenEndpoint,
+      code,
+      verifier: flow.pkceVerifier,
+      callbackHostname,
+    });
+    const customerApi = await discoverCustomerApi(context.config, context.providerFetch);
+    const tokenIssuedAt = currentSeconds();
+    const handoff = await context.input.sessionStore.createShopperSessionHandoff({
+      projectId: context.config.projectId,
+      returnHostname: flow.returnHostname,
+      sessionData: JSON.stringify({
+        version: 1,
+        accessToken: token.accessToken,
+        idToken: token.idToken,
+        graphqlEndpoint: customerApi.graphqlEndpoint,
+        endSessionEndpoint: openId.endSessionEndpoint,
+        accessTokenExpiresAt: tokenIssuedAt + token.expiresIn,
+      } satisfies StoredShopifySession),
+      sessionTtlSeconds: SHOPPER_SESSION_RECORD_TTL_SECONDS,
+      handoffTtlSeconds: Math.min(HANDOFF_TTL_SECONDS, token.expiresIn),
+    });
+    if (handoff.returnHostname === callbackHostname) {
+      return finalizeHandoff(context, handoff.handoff, handoff.returnHostname);
+    }
+    return handoffPostResponse(context.config, handoff.returnHostname, handoff.handoff);
+  } catch (error) {
+    if (error instanceof ProviderFailure) {
+      return safeError(502, "customer_authentication_unavailable");
+    }
+    throw error;
+  }
+}
+
+async function handleHandoff(context: RequestRouteContext): Promise<Response> {
+  const requestHostname = normalizedHostname(context.requestUrl.hostname);
+  if (!await isAllowedHostname(context.input, context.config.projectId, requestHostname)) {
+    throw new SafeHttpError(400, "invalid_handoff");
+  }
+  requireOrigin(context.request, [
+    `https://${context.config.canonicalHostname}`,
+    ...Array.from(context.config.additionalCallbackHostnames, (hostname) => `https://${hostname}`),
+    `https://${requestHostname}`,
+  ]);
+  const form = await boundedForm(context.request);
+  const handoffValue = requiredSingleFormValue(form, "handoff", 43, /^[A-Za-z0-9_-]{43}$/);
+  if (Array.from(form.keys()).some((key) => key !== "handoff")) {
+    throw new SafeHttpError(400, "invalid_handoff");
+  }
+  return finalizeHandoff(context, handoffValue, requestHostname);
+}
+
+async function finalizeHandoff(
+  context: RequestRouteContext,
+  handoffValue: string,
+  requestHostname: string,
+): Promise<Response> {
+  const handoff = await context.input.sessionStore.consumeHandoff({
+    projectId: context.config.projectId,
+    handoff: handoffValue,
+    requestHostname,
+  });
+  if (!handoff) throw new SafeHttpError(400, "invalid_handoff");
+  const previousSessionId = readSessionCookie(context.request.headers.get("Cookie"));
+  if (previousSessionId && previousSessionId !== handoff.sessionId) {
+    try {
+      await context.input.sessionStore.deleteShopperSession({
+        projectId: context.config.projectId,
+        sessionId: previousSessionId,
+        requestHostname,
+      });
+    } catch {
+      // A stale-session cleanup failure must not strand a finalized replacement
+      // before its cookie reaches the browser. Scheduled expiry remains the
+      // backstop for the old opaque session record.
+    }
+  }
+
+  return new Response(null, {
+    status: 303,
+    headers: secureHeaders({
+      Location: context.config.signedInPath,
+      "Set-Cookie": sessionCookie(handoff.sessionId),
+    }),
+  });
+}
+
+async function handleSession(context: RequestRouteContext & {
+  providerFetch: CustomerAuthProviderFetch;
+}): Promise<Response> {
+  const requestHostname = normalizedHostname(context.requestUrl.hostname);
+  if (!await isAllowedHostname(context.input, context.config.projectId, requestHostname)) {
+    throw new SafeHttpError(404, "not_found");
+  }
+  const sessionId = readSessionCookie(context.request.headers.get("Cookie"));
+  if (!sessionId) return unauthenticatedResponse(true);
+  const stored = await context.input.sessionStore.readShopperSession({
+    projectId: context.config.projectId,
+    sessionId,
+    requestHostname,
+  });
+  if (!stored) return unauthenticatedResponse(true);
+  const session = parseStoredShopifySession(stored.sessionData, context.config);
+  const renewalUrl = customerRenewalUrl(context.config, requestHostname);
+  if (session.accessTokenExpiresAt <= currentSeconds()) {
+    return jsonResponse(200, {
+      authenticated: false,
+      renewalRequired: true,
+      renewalUrl,
+    });
+  }
+
+  const response = await fetchProvider(context.providerFetch, session.graphqlEndpoint, {
+    method: "POST",
+    headers: providerRequestHeaders(context.config, {
+      Accept: "application/json",
+      Authorization: session.accessToken,
+      "Content-Type": "application/json",
+    }, providerOrigin(context.config, requestHostname)),
+    body: JSON.stringify({
+      operationName: "CustomerIdentity",
+      query: SHOPIFY_CUSTOMER_IDENTITY_QUERY,
+      variables: {},
+    }),
+    redirect: PROVIDER_REDIRECT_MODE,
+  });
+  if (response.status === 401 || response.status === 403) {
+    return jsonResponse(200, {
+      authenticated: false,
+      renewalRequired: true,
+      renewalUrl,
+    });
+  }
+  if (!response.ok) throw new ProviderFailure();
+  const payload = await readBoundedJson(response, MAX_GRAPHQL_BYTES);
+  const customer = parseCustomerIdentity(payload);
+  return jsonResponse(200, {
+    authenticated: true,
+    customer,
+    expiresAt: session.accessTokenExpiresAt,
+    renewalUrl,
+  });
+}
+
+async function handleLogout(context: RequestRouteContext): Promise<Response> {
+  const requestHostname = normalizedHostname(context.requestUrl.hostname);
+  if (!await isAllowedHostname(context.input, context.config.projectId, requestHostname)) {
+    throw new SafeHttpError(404, "not_found");
+  }
+  requireOrigin(context.request, `https://${requestHostname}`);
+  const sessionId = readSessionCookie(context.request.headers.get("Cookie"));
+  if (!sessionId) return localLogoutResponse();
+  const stored = await context.input.sessionStore.readShopperSession({
+    projectId: context.config.projectId,
+    sessionId,
+    requestHostname,
+  });
+  await context.input.sessionStore.deleteShopperSession({
+    projectId: context.config.projectId,
+    sessionId,
+    requestHostname,
+  });
+  if (!stored) return localLogoutResponse();
+
+  let session: StoredShopifySession;
+  try {
+    session = parseStoredShopifySession(stored.sessionData, context.config);
+  } catch {
+    return localLogoutResponse();
+  }
+  const providerLogout = new URL(session.endSessionEndpoint);
+  providerLogout.searchParams.set("id_token_hint", session.idToken);
+  providerLogout.searchParams.set(
+    "post_logout_redirect_uri",
+    `https://${callbackHostname(context.config, requestHostname)}${context.config.postLogoutPath}`,
+  );
+  return redirectResponse(providerLogout.toString(), 303, {
+    "Set-Cookie": expiredSessionCookie(),
+  });
+}
+
+function handlePostLogout(context: {
+  requestUrl: URL;
+  config: ValidatedConfig;
+}): Response {
+  requireCallbackHostname(context.requestUrl, context.config);
+  return redirectResponse(context.config.signedOutPath, 303);
+}
+
+interface RouteContext {
+  requestUrl: URL;
+  config: ValidatedConfig;
+  input: {
+    sessionStore: PublicCustomerAuthSessionStore;
+    hostnamePolicy: CustomerAuthHostnamePolicy;
+    authorizationClientKey: CustomerAuthClientKey;
+  };
+  providerFetch: CustomerAuthProviderFetch;
+}
+
+interface RequestRouteContext extends Omit<RouteContext, "providerFetch"> {
+  request: Request;
+}
+
+interface StoredShopifySession {
+  version: 1;
+  accessToken: string;
+  idToken: string;
+  graphqlEndpoint: string;
+  endSessionEndpoint: string;
+  accessTokenExpiresAt: number;
+}
+
+interface ValidatedConfig {
+  projectId: string;
+  canonicalHostname: string;
+  additionalCallbackHostnames: ReadonlySet<string>;
+  storefrontDomain: string;
+  clientId: string;
+  providerUserAgent: string;
+  additionalProviderHostnames: ReadonlySet<string>;
+  loginPath: string;
+  callbackPath: string;
+  handoffPath: string;
+  sessionPath: string;
+  logoutPath: string;
+  postLogoutPath: string;
+  signedInPath: string;
+  signedOutPath: string;
+}
+
+type RouteName = "login" | "callback" | "handoff" | "session" | "logout" | "postLogout";
+
+function routeFor(config: ValidatedConfig, pathname: string): {
+  name: RouteName;
+  method: "GET" | "POST";
+} | null {
+  if (pathname === config.loginPath) return { name: "login", method: "GET" };
+  if (pathname === config.callbackPath) return { name: "callback", method: "GET" };
+  if (pathname === config.handoffPath) return { name: "handoff", method: "POST" };
+  if (pathname === config.sessionPath) return { name: "session", method: "GET" };
+  if (pathname === config.logoutPath) return { name: "logout", method: "POST" };
+  if (pathname === config.postLogoutPath) return { name: "postLogout", method: "GET" };
+  return null;
+}
+
+function validateConfig(config: ShopifyCustomerAccountRouteConfig): ValidatedConfig {
+  if (!config || typeof config !== "object") throw new Error("Customer authentication config is required.");
+  const allowedConfigKeys = new Set([
+    "projectId",
+    "canonicalHostname",
+    "additionalCallbackHostnames",
+    "storefrontDomain",
+    "clientId",
+    "providerUserAgent",
+    "additionalProviderHostnames",
+    "loginPath",
+    "callbackPath",
+    "handoffPath",
+    "sessionPath",
+    "logoutPath",
+    "postLogoutPath",
+    "signedInPath",
+    "signedOutPath",
+  ]);
+  if (Object.keys(config).some((key) => !allowedConfigKeys.has(key))) {
+    throw new Error("The customer authentication config contains an unsupported field.");
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{1,127}$/.test(config.projectId)) {
+    throw new Error("The customer authentication project is invalid.");
+  }
+  if (typeof config.clientId !== "string" || !/^[A-Za-z0-9_-]{8,256}$/.test(config.clientId)) {
+    throw new Error("The Shopify Customer Account client ID is invalid.");
+  }
+  const canonicalHostname = normalizedHostname(config.canonicalHostname);
+  const additionalCallbackHostnames = validatedHostnameSet(
+    config.additionalCallbackHostnames,
+    "Shopify callback hostname allowlist",
+  );
+  additionalCallbackHostnames.delete(canonicalHostname);
+  const storefrontDomain = normalizedHostname(config.storefrontDomain);
+  const providerUserAgent = config.providerUserAgent ?? DEFAULT_PROVIDER_USER_AGENT;
+  if (typeof providerUserAgent !== "string"
+      || providerUserAgent.length < 3
+      || providerUserAgent.length > 128
+      || /[^\u0020-\u007e]/.test(providerUserAgent)) {
+    throw new Error("The Shopify provider User-Agent is invalid.");
+  }
+  const additionalProviderHostnames = new Set<string>();
+  if (config.additionalProviderHostnames !== undefined) {
+    if (!Array.isArray(config.additionalProviderHostnames) || config.additionalProviderHostnames.length > 8) {
+      throw new Error("The Shopify provider hostname allowlist is invalid.");
+    }
+    for (const hostname of config.additionalProviderHostnames) {
+      additionalProviderHostnames.add(normalizedHostname(hostname));
+    }
+  }
+  const routePaths = {
+    loginPath: validatedPath(config.loginPath ?? DEFAULT_LOGIN_PATH, "login"),
+    callbackPath: validatedPath(config.callbackPath ?? DEFAULT_CALLBACK_PATH, "callback"),
+    handoffPath: validatedPath(config.handoffPath ?? DEFAULT_HANDOFF_PATH, "handoff"),
+    sessionPath: validatedPath(config.sessionPath ?? DEFAULT_SESSION_PATH, "session"),
+    logoutPath: validatedPath(config.logoutPath ?? DEFAULT_LOGOUT_PATH, "logout"),
+    postLogoutPath: validatedPath(config.postLogoutPath ?? DEFAULT_POST_LOGOUT_PATH, "post-logout"),
+  };
+  if (new Set(Object.values(routePaths)).size !== Object.keys(routePaths).length) {
+    throw new Error("Customer authentication route paths must be distinct.");
+  }
+  const signedInPath = validatedPath(config.signedInPath ?? DEFAULT_SIGNED_IN_PATH, "signed-in");
+  const signedOutPath = validatedPath(config.signedOutPath ?? DEFAULT_SIGNED_OUT_PATH, "signed-out");
+  if (signedOutPath === routePaths.postLogoutPath) {
+    throw new Error("The signed-out path cannot be the post-logout callback path.");
+  }
+  return {
+    projectId: config.projectId,
+    canonicalHostname,
+    additionalCallbackHostnames,
+    storefrontDomain,
+    clientId: config.clientId,
+    providerUserAgent,
+    additionalProviderHostnames,
+    ...routePaths,
+    signedInPath,
+    signedOutPath,
+  };
+}
+
+function parsedRequestUrl(request: Request): URL {
+  if (!(request instanceof Request) || request.url.length > MAX_REQUEST_URL_LENGTH) {
+    throw new SafeHttpError(400, "invalid_request");
+  }
+  try {
+    return new URL(request.url);
+  } catch {
+    throw new SafeHttpError(400, "invalid_request");
+  }
+}
+
+function validatedRequestUrl(url: URL): URL {
+  if (url.protocol !== "https:" || url.username || url.password || url.port) {
+    throw new SafeHttpError(400, "invalid_request");
+  }
+  normalizedHostname(url.hostname);
+  return url;
+}
+
+function validatedPath(value: string, label: string): string {
+  if (typeof value !== "string" || !/^\/[A-Za-z0-9/_-]{0,127}$/.test(value) || value.includes("//")) {
+    throw new Error(`The customer authentication ${label} path is invalid.`);
+  }
+  return value;
+}
+
+function callbackUrl(config: ValidatedConfig, hostname = config.canonicalHostname): string {
+  return `https://${hostname}${config.callbackPath}`;
+}
+
+function customerRenewalUrl(config: ValidatedConfig, returnHostname: string): string {
+  return `https://${callbackHostname(config, returnHostname)}${config.loginPath}`
+    + `?return_host=${encodeURIComponent(returnHostname)}&prompt=none`;
+}
+
+function currentSeconds(): number {
+  return Math.floor(Date.now() / 1_000);
+}
+
+function requireCallbackHostname(url: URL, config: ValidatedConfig): string {
+  const hostname = normalizedHostname(url.hostname);
+  if (callbackHostname(config, hostname) !== hostname) {
+    throw new SafeHttpError(404, "not_found");
+  }
+  return hostname;
+}
+
+function callbackHostname(config: ValidatedConfig, hostname: string): string {
+  return hostname === config.canonicalHostname || config.additionalCallbackHostnames.has(hostname)
+    ? hostname
+    : config.canonicalHostname;
+}
+
+async function isAllowedHostname(
+  input: { hostnamePolicy: CustomerAuthHostnamePolicy },
+  projectId: string,
+  hostnameValue: string,
+): Promise<boolean> {
+  let hostname: string;
+  try {
+    hostname = normalizedHostname(hostnameValue);
+  } catch {
+    return false;
+  }
+  try {
+    return await input.hostnamePolicy({ projectId, hostname }) === true;
+  } catch {
+    return false;
+  }
+}
+
+async function discoverOpenId(
+  config: ValidatedConfig,
+  providerFetch: CustomerAuthProviderFetch,
+): Promise<{
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  endSessionEndpoint: string;
+}> {
+  const response = await fetchProvider(
+    providerFetch,
+    `https://${config.storefrontDomain}/.well-known/openid-configuration`,
+    {
+      method: "GET",
+      headers: providerRequestHeaders(config, { Accept: "application/json" }),
+      redirect: PROVIDER_REDIRECT_MODE,
+    },
+  );
+  if (!response.ok) throw new ProviderFailure();
+  const value = objectValue(await readBoundedJson(response, MAX_DISCOVERY_BYTES));
+  return {
+    authorizationEndpoint: providerEndpoint(value.authorization_endpoint, config),
+    tokenEndpoint: providerEndpoint(value.token_endpoint, config),
+    endSessionEndpoint: providerEndpoint(value.end_session_endpoint, config),
+  };
+}
+
+async function discoverCustomerApi(
+  config: ValidatedConfig,
+  providerFetch: CustomerAuthProviderFetch,
+): Promise<{ graphqlEndpoint: string }> {
+  const response = await fetchProvider(
+    providerFetch,
+    `https://${config.storefrontDomain}/.well-known/customer-account-api`,
+    {
+      method: "GET",
+      headers: providerRequestHeaders(config, { Accept: "application/json" }),
+      redirect: PROVIDER_REDIRECT_MODE,
+    },
+  );
+  if (!response.ok) throw new ProviderFailure();
+  const value = objectValue(await readBoundedJson(response, MAX_DISCOVERY_BYTES));
+  return { graphqlEndpoint: providerEndpoint(value.graphql_api, config) };
+}
+
+async function exchangeAuthorizationCode(input: {
+  config: ValidatedConfig;
+  providerFetch: CustomerAuthProviderFetch;
+  tokenEndpoint: string;
+  code: string;
+  verifier: string;
+  callbackHostname: string;
+}): Promise<{ accessToken: string; idToken: string; expiresIn: number }> {
+  const response = await fetchProvider(input.providerFetch, input.tokenEndpoint, {
+    method: "POST",
+    headers: providerRequestHeaders(input.config, {
+      Accept: "application/json",
+      "Content-Type": "application/x-www-form-urlencoded",
+    }, `https://${input.callbackHostname}`),
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: input.config.clientId,
+      redirect_uri: callbackUrl(input.config, input.callbackHostname),
+      code: input.code,
+      code_verifier: input.verifier,
+    }),
+    redirect: PROVIDER_REDIRECT_MODE,
+  });
+  if (!response.ok) throw new ProviderFailure();
+  const value = objectValue(await readBoundedJson(response, MAX_TOKEN_BYTES));
+  if (typeof value.access_token !== "string"
+      || value.access_token.length < 1
+      || value.access_token.length > MAX_ACCESS_TOKEN_LENGTH
+      || /[\u0000-\u001f\u007f]/.test(value.access_token)) {
+    throw new ProviderFailure();
+  }
+  if (!Number.isSafeInteger(value.expires_in)
+      || (value.expires_in as number) < 1
+      || (value.expires_in as number) > MAX_SESSION_TTL_SECONDS) {
+    throw new ProviderFailure();
+  }
+  return {
+    accessToken: value.access_token,
+    idToken: requiredIdToken(value.id_token),
+    expiresIn: value.expires_in as number,
+  };
+}
+
+function providerRequestHeaders(
+  config: ValidatedConfig,
+  values: HeadersInit,
+  origin = `https://${config.canonicalHostname}`,
+): Headers {
+  const headers = new Headers(values);
+  headers.set("Origin", origin);
+  headers.set("User-Agent", config.providerUserAgent);
+  return headers;
+}
+
+function providerEndpoint(value: unknown, config: ValidatedConfig): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > MAX_ENDPOINT_LENGTH) {
+    throw new ProviderFailure();
+  }
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ProviderFailure();
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.hash || (url.port && url.port !== "443")) {
+    throw new ProviderFailure();
+  }
+  let hostname: string;
+  try {
+    hostname = normalizedHostname(url.hostname);
+  } catch {
+    throw new ProviderFailure();
+  }
+  if (!isSameOrSubdomain(hostname, config.storefrontDomain)
+      && !isSameOrSubdomain(hostname, "shopify.com")
+      && !isSameOrSubdomain(hostname, "myshopify.com")
+      && !config.additionalProviderHostnames.has(hostname)) {
+    throw new ProviderFailure();
+  }
+  return url.toString();
+}
+
+function parseStoredShopifySession(value: string, config: ValidatedConfig): StoredShopifySession {
+  if (typeof value !== "string" || value.length > 65_536) throw new ProviderFailure();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new ProviderFailure();
+  }
+  const object = objectValue(parsed);
+  if (object.version !== 1
+      || typeof object.accessToken !== "string"
+      || object.accessToken.length < 1
+      || object.accessToken.length > MAX_ACCESS_TOKEN_LENGTH
+      || /[\u0000-\u001f\u007f]/.test(object.accessToken)) {
+    throw new ProviderFailure();
+  }
+  return {
+    version: 1,
+    accessToken: object.accessToken,
+    idToken: requiredIdToken(object.idToken),
+    graphqlEndpoint: providerEndpoint(object.graphqlEndpoint, config),
+    endSessionEndpoint: providerEndpoint(object.endSessionEndpoint, config),
+    accessTokenExpiresAt: requiredStoredExpiry(object.accessTokenExpiresAt),
+  };
+}
+
+function requiredIdToken(value: unknown): string {
+  if (typeof value !== "string" || value.length < 3 || value.length > MAX_ID_TOKEN_LENGTH
+      || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value)) {
+    throw new ProviderFailure();
+  }
+  return value;
+}
+
+function requiredStoredExpiry(value: unknown): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+    throw new ProviderFailure();
+  }
+  return value;
+}
+
+function parseCustomerIdentity(value: unknown): {
+  id: string;
+  displayName: string;
+  emailAddress: { emailAddress: string } | null;
+} {
+  const root = objectValue(value);
+  if (root.errors !== undefined || !root.data) throw new ProviderFailure();
+  const data = objectValue(root.data);
+  const customer = objectValue(data.customer);
+  const id = boundedString(customer.id, 512);
+  const displayName = boundedString(customer.displayName, 1_024);
+  let emailAddress: { emailAddress: string } | null = null;
+  if (customer.emailAddress !== null && customer.emailAddress !== undefined) {
+    const email = objectValue(customer.emailAddress);
+    emailAddress = { emailAddress: boundedString(email.emailAddress, 2_048) };
+  }
+  return { id, displayName, emailAddress };
+}
+
+async function fetchProvider(
+  providerFetch: CustomerAuthProviderFetch,
+  input: RequestInfo | URL,
+  init: RequestInit,
+): Promise<Response> {
+  try {
+    return await providerFetch(input, {
+      ...init,
+      signal: AbortSignal.timeout(PROVIDER_FETCH_TIMEOUT_MS),
+    });
+  } catch {
+    throw new ProviderFailure();
+  }
+}
+
+async function readBoundedJson(response: Response, maximumBytes: number): Promise<unknown> {
+  const contentType = response.headers.get("Content-Type")?.split(";", 1)[0]?.trim().toLowerCase();
+  if (contentType !== "application/json" && !contentType?.endsWith("+json")) throw new ProviderFailure();
+  const contentLength = response.headers.get("Content-Length");
+  if (contentLength && (!/^\d+$/.test(contentLength) || Number(contentLength) > maximumBytes)) {
+    throw new ProviderFailure();
+  }
+  if (!response.body) throw new ProviderFailure();
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let bytesRead = 0;
+  let text = "";
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done) break;
+      bytesRead += result.value.byteLength;
+      if (bytesRead > maximumBytes) throw new ProviderFailure();
+      text += decoder.decode(result.value, { stream: true });
+    }
+    text += decoder.decode();
+  } catch (error) {
+    if (error instanceof ProviderFailure) throw error;
+    throw new ProviderFailure();
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new ProviderFailure();
+  }
+}
+
+async function boundedForm(request: Request): Promise<URLSearchParams> {
+  const contentType = request.headers.get("Content-Type")?.split(";", 1)[0]?.trim().toLowerCase();
+  if (contentType !== "application/x-www-form-urlencoded") {
+    throw new SafeHttpError(400, "invalid_handoff");
+  }
+  const contentLength = request.headers.get("Content-Length");
+  if (contentLength && (!/^\d+$/.test(contentLength) || Number(contentLength) > MAX_FORM_BODY_BYTES)) {
+    throw new SafeHttpError(400, "invalid_handoff");
+  }
+  if (!request.body) throw new SafeHttpError(400, "invalid_handoff");
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let byteLength = 0;
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done) break;
+      byteLength += result.value.byteLength;
+      if (byteLength > MAX_FORM_BODY_BYTES) {
+        await reader.cancel();
+        throw new SafeHttpError(400, "invalid_handoff");
+      }
+      chunks.push(result.value);
+    }
+  } catch (error) {
+    if (error instanceof SafeHttpError) throw error;
+    throw new SafeHttpError(400, "invalid_handoff");
+  }
+  const bodyBytes = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bodyBytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  let body: string;
+  try {
+    body = new TextDecoder("utf-8", { fatal: true }).decode(bodyBytes);
+  } catch {
+    throw new SafeHttpError(400, "invalid_handoff");
+  }
+  return new URLSearchParams(body);
+}
+
+function requiredSingleQueryValue(
+  url: URL,
+  name: string,
+  maximumLength: number,
+  pattern?: RegExp,
+): string {
+  const values = url.searchParams.getAll(name);
+  if (values.length !== 1 || values[0].length < 1 || values[0].length > maximumLength
+      || (pattern && !pattern.test(values[0]))) {
+    throw new SafeHttpError(400, "invalid_request");
+  }
+  return values[0];
+}
+
+function optionalSingleQueryValue(
+  url: URL,
+  name: string,
+  maximumLength: number,
+  pattern: RegExp,
+): string | null {
+  const values = url.searchParams.getAll(name);
+  if (values.length === 0) return null;
+  if (values.length !== 1 || values[0].length < 1 || values[0].length > maximumLength
+      || !pattern.test(values[0])) {
+    throw new SafeHttpError(400, "invalid_request");
+  }
+  return values[0];
+}
+
+function requiredSingleFormValue(
+  form: URLSearchParams,
+  name: string,
+  maximumLength: number,
+  pattern: RegExp,
+): string {
+  const values = form.getAll(name);
+  if (values.length !== 1 || values[0].length < 1 || values[0].length > maximumLength
+      || !pattern.test(values[0])) {
+    throw new SafeHttpError(400, "invalid_handoff");
+  }
+  return values[0];
+}
+
+function readSessionCookie(cookieHeader: string | null): string | null {
+  return readOpaqueCookie(cookieHeader, PUBLIC_CUSTOMER_AUTH_SESSION_COOKIE);
+}
+
+function readOpaqueCookie(cookieHeader: string | null, expectedName: string): string | null {
+  if (!cookieHeader || cookieHeader.length > MAX_COOKIE_HEADER_LENGTH) return null;
+  const matches: string[] = [];
+  for (const part of cookieHeader.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator < 1) continue;
+    const name = part.slice(0, separator).trim();
+    if (name === expectedName) {
+      matches.push(part.slice(separator + 1).trim());
+    }
+  }
+  if (matches.length !== 1 || !/^[A-Za-z0-9_-]{43}$/.test(matches[0])) return null;
+  return matches[0];
+}
+
+async function requiredAuthorizationClientKey(
+  resolver: CustomerAuthClientKey,
+  request: Request,
+): Promise<string> {
+  try {
+    const key = await resolver(request);
+    if (typeof key !== "string" || key.length < 1 || key.length > 512
+        || /[\u0000-\u001f\u007f]/.test(key)) {
+      throw new Error("invalid");
+    }
+    return key;
+  } catch {
+    throw new SafeHttpError(503, "customer_authentication_unavailable");
+  }
+}
+
+function cloudflareAuthorizationClientKey(request: Request): string {
+  const address = request.headers.get("CF-Connecting-IP")?.trim().toLowerCase();
+  if (!address || address.length > 64 || !/^[0-9a-f:.]+$/.test(address)) {
+    throw new Error("The Cloudflare client address is unavailable.");
+  }
+  return `cloudflare-ip:${address}`;
+}
+
+function requireOrigin(request: Request, expectedOrigin: string | readonly string[]): void {
+  const expectedOrigins = typeof expectedOrigin === "string" ? [expectedOrigin] : expectedOrigin;
+  if (!expectedOrigins.includes(request.headers.get("Origin") ?? "")) {
+    throw new SafeHttpError(403, "invalid_origin");
+  }
+}
+
+function providerOrigin(config: ValidatedConfig, requestHostname: string): string {
+  return `https://${callbackHostname(config, requestHostname)}`;
+}
+
+function validatedHostnameSet(value: readonly string[] | undefined, label: string): Set<string> {
+  if (value === undefined) return new Set();
+  if (!Array.isArray(value) || value.length > 8) throw new Error(`The ${label} is invalid.`);
+  return new Set(value.map(normalizedHostname));
+}
+
+function normalizedHostname(value: unknown): string {
+  if (typeof value !== "string") throw new Error("The customer authentication hostname is invalid.");
+  const hostname = value.toLowerCase().replace(/\.$/, "");
+  if (!/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(hostname)
+      || hostname.length > 253) {
+    throw new Error("The customer authentication hostname is invalid.");
+  }
+  return hostname;
+}
+
+function isSameOrSubdomain(hostname: string, parent: string): boolean {
+  return hostname === parent || hostname.endsWith(`.${parent}`);
+}
+
+function objectValue(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ProviderFailure();
+  return value as Record<string, unknown>;
+}
+
+function boundedString(value: unknown, maximumLength: number): string {
+  if (typeof value !== "string" || value.length > maximumLength) throw new ProviderFailure();
+  return value;
+}
+
+function randomBase64Url(bytes: number): string {
+  const value = crypto.getRandomValues(new Uint8Array(bytes));
+  return base64Url(value);
+}
+
+async function sha256Base64Url(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return base64Url(new Uint8Array(digest));
+}
+
+function base64Url(value: Uint8Array): string {
+  const binary = Array.from(value, (byte) => String.fromCharCode(byte)).join("");
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+
+function handoffPostResponse(
+  config: ValidatedConfig,
+  returnHostname: string,
+  handoff: string,
+): Response {
+  const action = `https://${returnHostname}${config.handoffPath}`;
+  const nonce = randomBase64Url(18);
+  const html = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><meta name="referrer" content="no-referrer"><title>Signing in</title></head>
+<body>
+<form id="customer-auth-handoff" method="post" action="${escapeHtml(action)}">
+<input type="hidden" name="handoff" value="${escapeHtml(handoff)}">
+<noscript><button type="submit">Continue</button></noscript>
+</form>
+<script nonce="${nonce}">document.getElementById("customer-auth-handoff").requestSubmit();</script>
+</body>
+</html>`;
+  return new Response(html, {
+    status: 200,
+    headers: secureHeaders({
+      "Content-Type": "text/html; charset=utf-8",
+      "Content-Security-Policy": `default-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action https://${returnHostname}; script-src 'nonce-${nonce}'`,
+      "Referrer-Policy": "no-referrer",
+    }),
+  });
+}
+
+function escapeHtml(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+function sessionCookie(sessionId: string): string {
+  return `${PUBLIC_CUSTOMER_AUTH_SESSION_COOKIE}=${sessionId}; Path=/; Secure; HttpOnly; SameSite=Lax`;
+}
+
+function authorizationFlowCookie(state: string, browserBinding: string): string {
+  return `${authorizationFlowCookieName(state)}=${browserBinding}; Max-Age=${FLOW_TTL_SECONDS}; Path=/; Secure; HttpOnly; SameSite=Lax`;
+}
+
+function authorizationFlowCookieName(state: string): string {
+  if (!/^[A-Za-z0-9_-]{43}$/.test(state)) {
+    throw new Error("The customer authentication state is invalid.");
+  }
+  return `${PUBLIC_CUSTOMER_AUTH_FLOW_COOKIE}_${state}`;
+}
+
+function expiredSessionCookie(): string {
+  return `${PUBLIC_CUSTOMER_AUTH_SESSION_COOKIE}=; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=0`;
+}
+
+function localLogoutResponse(): Response {
+  return new Response(null, {
+    status: 204,
+    headers: secureHeaders({ "Set-Cookie": expiredSessionCookie() }),
+  });
+}
+
+function unauthenticatedResponse(clearCookie: boolean): Response {
+  return jsonResponse(200, { authenticated: false }, clearCookie
+    ? { "Set-Cookie": expiredSessionCookie() }
+    : undefined);
+}
+
+function jsonResponse(status: number, value: unknown, headers?: HeadersInit): Response {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: secureHeaders({ "Content-Type": "application/json; charset=utf-8", ...headers }),
+  });
+}
+
+function safeError(status: number, code: string, headers?: HeadersInit): Response {
+  return jsonResponse(status, { error: code }, headers);
+}
+
+function redirectResponse(location: string, status: 302 | 303, headers?: HeadersInit): Response {
+  const responseHeaders = new Headers(headers);
+  responseHeaders.set("Location", location);
+  return new Response(null, {
+    status,
+    headers: secureHeaders(responseHeaders),
+  });
+}
+
+function methodNotAllowed(method: "GET" | "POST"): Response {
+  return jsonResponse(405, { error: "method_not_allowed" }, { Allow: method });
+}
+
+function secureHeaders(extra: HeadersInit): Headers {
+  const headers = new Headers(extra);
+  headers.set("Cache-Control", "no-store");
+  headers.set("Referrer-Policy", "no-referrer");
+  headers.set("X-Content-Type-Options", "nosniff");
+  return headers;
+}
+
+class SafeHttpError extends Error {
+  constructor(readonly status: number, readonly code: string) {
+    super(code);
+  }
+}
+
+class ProviderFailure extends Error {}