@shop-on/theme-server 0.2.0 → 0.3.0

package/dist/account-state.js

@@ -0,0 +1,55 @@
+import { derivedCookieSecret } from "./cookie-secret.js";
+import { createServerOnlyFn } from "@tanstack/react-start";
+import { createShopBoundCookieConfig } from "@shop-on/customer-runtime/session-cookie";
+import { ACCOUNT_STATE_FORMAT } from "@shop-on/customer-runtime/handoff-state";
+//#region src/account-state.ts
+const TTL_SECONDS = 1800;
+const DOMAIN_LABEL = "account-state";
+const sessionConfig = createServerOnlyFn(async () => {
+	return createShopBoundCookieConfig({
+		name: "account_state",
+		password: await derivedCookieSecret(DOMAIN_LABEL),
+		maxAge: TTL_SECONDS
+	});
+});
+const loadSession = createServerOnlyFn(async () => {
+	const { openSession } = await import("@shop-on/customer-runtime/sealed-session");
+	return openSession(await sessionConfig());
+});
+/** The state this browser holds, or a fresh one once it is past its 30
+*  minutes. Reused so a second tab bouncing to account doesn't void the state
+*  an in-flight sign-in will come back with, and rewritten on reuse: the
+*  cookie's expiry counts from its first write, so only clearing first lets
+*  it outlast the OTP round trip that reuse starts. */
+const issueAccountState = createServerOnlyFn(async () => {
+	const session = await loadSession();
+	const { state: kept, issuedAt } = session.data;
+	if (kept && issuedAt && Date.now() - issuedAt < TTL_SECONDS * 1e3) {
+		await session.clear();
+		await session.update({
+			state: kept,
+			issuedAt
+		});
+		return kept;
+	}
+	const { randomBytes } = await import("node:crypto");
+	const state = randomBytes(32).toString("base64url");
+	await session.clear();
+	await session.update({
+		state,
+		issuedAt: Date.now()
+	});
+	return state;
+});
+/** Whether `state` is the one this browser was issued. Constant-time. */
+const matchesAccountState = createServerOnlyFn(async (state) => {
+	if (!state || !ACCOUNT_STATE_FORMAT.test(state)) return false;
+	const issued = (await loadSession()).data.state;
+	if (!issued) return false;
+	const { timingSafeEqual } = await import("node:crypto");
+	const a = Buffer.from(issued);
+	const b = Buffer.from(state);
+	return a.length === b.length && timingSafeEqual(a, b);
+});
+//#endregion
+export { issueAccountState, matchesAccountState };

package/dist/account.js

@@ -22,7 +22,12 @@ async function getAccountRedirectUrl(data) {
 			xForwardedHost: true,
 			xForwardedProto: true
 		}).origin;
-		target.searchParams.set("return_to", `${origin}${safePath}`);
+		const returnTo = new URL(`${origin}${safePath}`);
+		const { issueAccountState } = await import("./account-state.js");
+		returnTo.searchParams.set("state", await issueAccountState());
+		const { markResponsePrivate } = await import("@shop-on/customer-runtime/handoff-state");
+		await markResponsePrivate();
+		target.searchParams.set("return_to", returnTo.toString());
 	}
 	return { url: target.toString() };
 }

package/dist/cart-session.js

@@ -1,25 +1,15 @@
+import { derivedCookieSecret } from "./cookie-secret.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
+import { createShopBoundCookieConfig } from "@shop-on/customer-runtime/session-cookie";
 //#region src/cart-session.ts
 const TTL_SECONDS = 2592e3;
 const DOMAIN_LABEL = "cart";
-const readSecret = createServerOnlyFn(async () => {
-	const customer = process.env.STOREFRONT_CUSTOMER_SESSION_SECRET;
-	if (!customer) throw new Error("cart-session: STOREFRONT_CUSTOMER_SESSION_SECRET missing — orchestrator did not inject it");
-	const { createHmac } = await import("node:crypto");
-	return createHmac("sha256", customer).update(DOMAIN_LABEL).digest("hex");
-});
 const sessionConfig = createServerOnlyFn(async () => {
-	return {
-		password: await readSecret(),
+	return createShopBoundCookieConfig({
 		name: "cart_session",
-		maxAge: TTL_SECONDS,
-		cookie: {
-			secure: process.env.NODE_ENV === "production",
-			sameSite: "lax",
-			httpOnly: true,
-			path: "/"
-		}
-	};
+		password: await derivedCookieSecret(DOMAIN_LABEL),
+		maxAge: TTL_SECONDS
+	});
 });
 const useCartSession = createServerOnlyFn(async () => {
 	const { openSession } = await import("@shop-on/customer-runtime/sealed-session");

package/dist/checkout.d.ts

@@ -4,21 +4,22 @@ export type CheckoutHandoffResult = {
   redirectTo: string;
 } | {
   ok: false;
-  reason: "no_cart";
+  reason: "no_cart" | "bad_state";
 };
 /**
- * Read this shop's `cart_session` cookie, call Rails `cartCheckout` (forwarding
- * the customer-session token as `X-Customer-Session` when provided so Rails
- * folds the customer into the handoff payload in one trip), and return the URL
- * on the checkout app that consumes it.
+ * The theme's `/checkout`, both passes. `state` is the URL's `checkout_state`,
+ * a REQUIRED key even when `undefined`: a caller that never passed it would
+ * bounce theme ↔ `/begin` forever, and this way that is a compile error.
  *
- * `no_cart` covers both "no cart cookie" and Rails' `NOT_FOUND` (cart digest
- * miss / cross-shop) / `CART_EMPTY` — the central app's "no cart" StatusPage is
- * the recovery surface for either. Any other userError code is unexpected and
- * throws; the calling route's error boundary handles it (matching `request`'s
- * retry-once-then-throw contract for top-level GraphQL errors).
+ * - No state: the URL of checkout's `/begin`, which binds this browser and
+ *   returns the buyer here with one. Mints nothing.
+ * - A state: mint the cart handoff with it (`mintCheckoutHandoff`).
+ *
+ * The customer-session token is injected: forwarded as `X-Customer-Session` on
+ * the mint so Rails folds the buyer into the handoff payload in one trip.
  */
-export declare function startCheckoutHandoff(opts?: {
+export declare function startCheckoutHandoff(opts: {
+  state: string | undefined;
   customerToken?: string;
 }): Promise<CheckoutHandoffResult>;
 //#endregion

package/dist/checkout.js

@@ -1,7 +1,9 @@
 import { graphql, request } from "./graphql.js";
+import { fetchShopInfo } from "./shop.js";
 import { useCartSession } from "./cart-session.js";
 import { parseMarketingCookies } from "./marketing-cookies.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
+import { CHECKOUT_STATE_FORMAT, isLoopback, markResponsePrivate } from "@shop-on/customer-runtime/handoff-state";
 //#region src/checkout.ts
 const CartCheckoutMutation = graphql(`
   mutation CartCheckout($input: CartCheckoutInput!) {
@@ -25,24 +27,73 @@ const readMarketingAttribution = createServerOnlyFn(async () => {
 		return null;
 	}
 });
+function publicCheckoutUrl(origin) {
+	const url = new URL("/checkout", origin);
+	if (!isLoopback(url.hostname)) url.protocol = "https:";
+	return url.toString();
+}
+/**
+* The theme's `/checkout`, both passes. `state` is the URL's `checkout_state`,
+* a REQUIRED key even when `undefined`: a caller that never passed it would
+* bounce theme ↔ `/begin` forever, and this way that is a compile error.
+*
+* - No state: the URL of checkout's `/begin`, which binds this browser and
+*   returns the buyer here with one. Mints nothing.
+* - A state: mint the cart handoff with it (`mintCheckoutHandoff`).
+*
+* The customer-session token is injected: forwarded as `X-Customer-Session` on
+* the mint so Rails folds the buyer into the handoff payload in one trip.
+*/
+function startCheckoutHandoff(opts) {
+	return opts.state === void 0 ? beginCheckoutUrl() : mintCheckoutHandoff({
+		state: opts.state,
+		customerToken: opts.customerToken
+	});
+}
+async function beginCheckoutUrl() {
+	if (!(await useCartSession()).data.token) return {
+		ok: false,
+		reason: "no_cart"
+	};
+	await markResponsePrivate();
+	const shop = await fetchShopInfo();
+	if (!shop) throw new Error("[checkout] shop info unavailable from Rails");
+	const { getPublicOrigin } = await import("./seo-context.js");
+	const url = new URL(`${shop.checkoutUrl}/begin`);
+	url.searchParams.set("return_to", publicCheckoutUrl(getPublicOrigin()));
+	return {
+		ok: true,
+		redirectTo: url.toString()
+	};
+}
 /**
-* Read this shop's `cart_session` cookie, call Rails `cartCheckout` (forwarding
-* the customer-session token as `X-Customer-Session` when provided so Rails
-* folds the customer into the handoff payload in one trip), and return the URL
-* on the checkout app that consumes it.
+* Read this shop's `cart_session` cookie, call Rails `cartCheckout`, and return
+* the URL on the checkout app that consumes it, `checkout_state` appended.
 *
-* `no_cart` covers both "no cart cookie" and Rails' `NOT_FOUND` (cart digest
-* miss / cross-shop) / `CART_EMPTY` — the central app's "no cart" StatusPage is
-* the recovery surface for either. Any other userError code is unexpected and
-* throws; the calling route's error boundary handles it (matching `request`'s
-* retry-once-then-throw contract for top-level GraphQL errors).
+* `no_cart` covers "no cart cookie" and Rails' `NOT_FOUND` (cart digest miss /
+* cross-shop) / `CART_EMPTY`; `bad_state` a state of the wrong shape (never
+* bounced to `/begin` again, so it can't loop). Any other userError code is
+* unexpected and throws (matching `request`'s retry-once-then-throw contract
+* for top-level GraphQL errors); the calling route sends the buyer home rather
+* than render on a URL holding a state.
 */
-async function startCheckoutHandoff(opts = {}) {
+async function mintCheckoutHandoff(opts) {
 	const cartToken = (await useCartSession()).data.token;
 	if (!cartToken) return {
 		ok: false,
 		reason: "no_cart"
 	};
+	await markResponsePrivate();
+	if (!CHECKOUT_STATE_FORMAT.test(opts.state)) {
+		console.warn(JSON.stringify({
+			event: "theme_checkout_bad_state",
+			ts: Date.now()
+		}));
+		return {
+			ok: false,
+			reason: "bad_state"
+		};
+	}
 	const attribution = await readMarketingAttribution();
 	const result = await request(CartCheckoutMutation, { input: attribution ? {
 		cartToken,
@@ -57,9 +108,11 @@ async function startCheckoutHandoff(opts = {}) {
 		};
 		throw new Error(`[checkout] cartCheckout returned no URL (code=${code ?? "UNKNOWN"})`);
 	}
+	const bound = new URL(checkoutUrl);
+	bound.searchParams.set("checkout_state", opts.state);
 	return {
 		ok: true,
-		redirectTo: checkoutUrl
+		redirectTo: bound.toString()
 	};
 }
 //#endregion

package/dist/cookie-secret.js

@@ -0,0 +1,10 @@
+import { createServerOnlyFn } from "@tanstack/react-start";
+//#region src/cookie-secret.ts
+const derivedCookieSecret = createServerOnlyFn(async (label) => {
+	const secret = process.env.STOREFRONT_CUSTOMER_SESSION_SECRET;
+	if (!secret) throw new Error(`${label} cookie: STOREFRONT_CUSTOMER_SESSION_SECRET missing — orchestrator did not inject it`);
+	const { createHmac } = await import("node:crypto");
+	return createHmac("sha256", secret).update(label).digest("hex");
+});
+//#endregion
+export { derivedCookieSecret };

package/dist/customer-handoff.d.ts

@@ -9,5 +9,5 @@ export type ConsumeCustomerHandoffResult = {
  * Plain server-only helper. Tested directly; each theme wraps it in a thin
  * `createServerFn` for its root route's `beforeLoad`.
  */
-export declare const consumeCustomerHandoff: (nonce: string) => Promise<ConsumeCustomerHandoffResult>;
+export declare const consumeCustomerHandoff: (nonce: string, state: string | undefined) => Promise<ConsumeCustomerHandoffResult>;
 //#endregion

package/dist/customer-handoff.js

@@ -1,13 +1,14 @@
 import { writeCustomerSession } from "./customer-session.js";
+import { matchesAccountState } from "./account-state.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
 //#region src/customer-handoff.ts
 /**
 * Plain server-only helper. Tested directly; each theme wraps it in a thin
 * `createServerFn` for its root route's `beforeLoad`.
 */
-const consumeCustomerHandoff = createServerOnlyFn(async (nonce) => {
+const consumeCustomerHandoff = createServerOnlyFn(async (nonce, state) => {
 	try {
-		return await consumeAndStore(nonce);
+		return await consumeAndStore(nonce, state);
 	} catch (err) {
 		console.warn(JSON.stringify({
 			event: "theme_customer_handoff_consume_error",
@@ -20,7 +21,18 @@ const consumeCustomerHandoff = createServerOnlyFn(async (nonce) => {
 		};
 	}
 });
-const consumeAndStore = createServerOnlyFn(async (nonce) => {
+const consumeAndStore = createServerOnlyFn(async (nonce, state) => {
+	if (!await matchesAccountState(state)) {
+		console.warn(JSON.stringify({
+			event: "theme_customer_handoff_unbound",
+			hasState: Boolean(state),
+			ts: Date.now()
+		}));
+		return {
+			ok: false,
+			reason: "unbound"
+		};
+	}
 	const { consumeCustomerSessionHandoff } = await import("@shop-on/customer-runtime/customer-session-handoff");
 	const result = await consumeCustomerSessionHandoff(nonce);
 	if (!result.ok) {

package/dist/customer-session.js

@@ -1,25 +1,15 @@
+import { derivedCookieSecret } from "./cookie-secret.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
+import { createShopBoundCookieConfig } from "@shop-on/customer-runtime/session-cookie";
 //#region src/customer-session.ts
 const TTL_SECONDS = 2592e3;
 const DOMAIN_LABEL = "customer";
-const readSecret = createServerOnlyFn(async () => {
-	const secret = process.env.STOREFRONT_CUSTOMER_SESSION_SECRET;
-	if (!secret) throw new Error("customer-session: STOREFRONT_CUSTOMER_SESSION_SECRET missing — orchestrator did not inject it");
-	const { createHmac } = await import("node:crypto");
-	return createHmac("sha256", secret).update(DOMAIN_LABEL).digest("hex");
-});
 const sessionConfig = createServerOnlyFn(async () => {
-	return {
-		password: await readSecret(),
+	return createShopBoundCookieConfig({
 		name: "customer_session",
-		maxAge: TTL_SECONDS,
-		cookie: {
-			secure: process.env.NODE_ENV === "production",
-			sameSite: "lax",
-			httpOnly: true,
-			path: "/"
-		}
-	};
+		password: await derivedCookieSecret(DOMAIN_LABEL),
+		maxAge: TTL_SECONDS
+	});
 });
 const loadSession = createServerOnlyFn(async () => {
 	const { openSession } = await import("@shop-on/customer-runtime/sealed-session");

package/dist/graphql-env.d.ts

@@ -2810,6 +2810,14 @@ export type introspection_types = {
         };
       };
       defaultValue: null;
+    }, {
+      name: 'retryKey';
+      type: {
+        kind: 'SCALAR';
+        name: 'String';
+        ofType: null;
+      };
+      defaultValue: null;
     }];
   };
   'CheckoutRecoverPayload': {
@@ -2854,6 +2862,10 @@ export type introspection_types = {
       };
     };
   };
+  'CheckoutRecoveryStatusEnum': {
+    name: 'CheckoutRecoveryStatusEnum';
+    enumValues: 'EXPIRED' | 'INVALID' | 'VALID';
+  };
   'CheckoutShippingAddress': {
     kind: 'OBJECT';
     name: 'CheckoutShippingAddress';
@@ -7185,6 +7197,18 @@ export type introspection_types = {
           ofType: null;
         };
       };
+      'checkoutRecoveryStatus': {
+        name: 'checkoutRecoveryStatus';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'ENUM';
+            name: 'CheckoutRecoveryStatusEnum';
+            ofType: null;
+          };
+        };
+      };
       'collection': {
         name: 'collection';
         type: {
@@ -8745,6 +8769,18 @@ export type introspection_types = {
           };
         };
       };
+      'checkoutUrl': {
+        name: 'checkoutUrl';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'SCALAR';
+            name: 'String';
+            ofType: null;
+          };
+        };
+      };
       'city': {
         name: 'city';
         type: {

package/dist/password-session.js

@@ -1,16 +1,11 @@
+import { derivedCookieSecret } from "./cookie-secret.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
 //#region src/password-session.ts
 const TTL_SECONDS = 2592e3;
 const DOMAIN_LABEL = "password";
-const readSecret = createServerOnlyFn(async () => {
-	const secret = process.env.STOREFRONT_CUSTOMER_SESSION_SECRET;
-	if (!secret) throw new Error("password-session: STOREFRONT_CUSTOMER_SESSION_SECRET missing — orchestrator did not inject it");
-	const { createHmac } = await import("node:crypto");
-	return createHmac("sha256", secret).update(DOMAIN_LABEL).digest("hex");
-});
 const sessionConfig = createServerOnlyFn(async () => {
 	return {
-		password: await readSecret(),
+		password: await derivedCookieSecret(DOMAIN_LABEL),
 		name: "storefront_unlock",
 		maxAge: TTL_SECONDS,
 		cookie: {

package/dist/schema.storefront.graphql

@@ -408,6 +408,10 @@ input CartCheckoutInput {
 Autogenerated return type of CartCheckout.
 """
 type CartCheckoutPayload {
+  """
+  Where to send the buyer. Append `checkout_state` from the
+  `shop.checkoutUrl/begin` bounce before redirecting; checkout rejects a handoff without it.
+  """
   checkoutUrl: String
 
   """
@@ -939,6 +943,12 @@ input CheckoutRecoverInput {
   """
   clientMutationId: String
   recoveryToken: String!
+
+  """
+  A random key the caller keeps for this link. If the reply to the first use is
+  lost, the same key may resume the checkout again for a few minutes.
+  """
+  retryKey: String
 }
 
 """
@@ -954,6 +964,26 @@ type CheckoutRecoverPayload {
   userErrors: [UserError!]!
 }
 
+"""
+Whether a checkout recovery link can still resume its checkout.
+"""
+enum CheckoutRecoveryStatusEnum {
+  """
+  The checkout was completed or has expired.
+  """
+  EXPIRED
+
+  """
+  The link is unknown, already used, or replaced by a newer one.
+  """
+  INVALID
+
+  """
+  The link resumes the checkout.
+  """
+  VALID
+}
+
 """
 Buyer-facing snapshot of the shipping address on a checkout.
 """
@@ -2436,6 +2466,9 @@ type Mutation {
 
   """
   Mint a checkout handoff for the given cart and return the URL to redirect to.
+  Checkout consumes the handoff only in the browser that started it: bounce the
+  buyer through `shop.checkoutUrl` + `/begin` first, and append the
+  `checkout_state` it sends back to `checkoutUrl`, or checkout rejects it.
   """
   cartCheckout(
     """
@@ -3272,6 +3305,18 @@ type Query {
   """
   checkout(checkoutToken: String!): ShopCheckout
 
+  """
+  Whether a recovery link can still resume its checkout. Read-only: it never spends the link.
+  """
+  checkoutRecoveryStatus(
+    recoveryToken: String!
+
+    """
+    The key sent with an earlier use of this link.
+    """
+    retryKey: String
+  ): CheckoutRecoveryStatusEnum!
+
   """
   Find a collection by ID or handle
   """
@@ -4426,6 +4471,14 @@ type Shop implements Node {
   due (PAYMENT_REQUIRED).
   """
   cashOnDeliveryEnabled: Boolean!
+
+  """
+  URL of this shop's section on the central checkout app
+  (`{checkoutHost}/shops/{handle}/checkout`). Theme sends the buyer to
+  `{checkoutUrl}/begin` before minting a cart handoff, so the handoff is bound
+  to the browser that started it.
+  """
+  checkoutUrl: String!
   city: String
 
   """
@@ -5095,6 +5148,10 @@ type ShopCheckout implements Node {
   availableDeliveryOptions: [ShopDeliveryOption!]!
   completedAt: ISO8601DateTime
   createdAt: ISO8601DateTime!
+
+  """
+  The checkout's customer. Storefront callers get null without that customer's session.
+  """
   customer: ShopCustomer
 
   """

package/dist/shop.d.ts

@@ -3,6 +3,7 @@ import { ResultOf } from "./graphql.js";
 declare const ShopQuery: import("gql.tada").TadaDocumentNode<{
   shop: {
     accountUrl: string;
+    checkoutUrl: string;
     currency: string;
     handle: string;
     id: string;

package/dist/shop.js

@@ -18,6 +18,7 @@ const ShopQuery = graphql(`
       }
       turnstileSitekey
       accountUrl
+      checkoutUrl
       primaryDomain {
         fqdn
         turnstileSitekey

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/theme-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "files": [
     "dist"
@@ -58,8 +58,8 @@
     "graphql": "17.0.2",
     "graphql-request": "7.4.0",
     "liquidjs": "10.30.0",
-    "@shop-on/theme-runtime": "0.2.0",
-    "@shop-on/customer-runtime": "0.2.0"
+    "@shop-on/customer-runtime": "0.3.0",
+    "@shop-on/theme-runtime": "0.3.0"
   },
   "devDependencies": {
     "@tanstack/react-start": "1.169.3",