@shop-on/theme-server 0.2.0 → 0.4.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/availability.d.ts

@@ -0,0 +1,10 @@
+//#region src/availability.d.ts
+/**
+ * Request middleware: every theme registers it in `src/start.ts` after
+ * `storefrontActivityMiddleware`, which answers `/health` before it. A closed
+ * or suspended store (see docs/shop-lifecycle.md) serves one uncacheable,
+ * unindexed 503 page in place of every route; the shop record is the
+ * memoised one the root loader reads, so this costs no extra request.
+ */
+export declare const storefrontAvailabilityMiddleware: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>;
+//#endregion

package/dist/availability.js

@@ -0,0 +1,59 @@
+import { fetchShopInfo } from "./shop.js";
+import { escapeHtmlAttr } from "./html.js";
+import { createMiddleware } from "@tanstack/react-start";
+//#region src/availability.ts
+/**
+* Request middleware: every theme registers it in `src/start.ts` after
+* `storefrontActivityMiddleware`, which answers `/health` before it. A closed
+* or suspended store (see docs/shop-lifecycle.md) serves one uncacheable,
+* unindexed 503 page in place of every route; the shop record is the
+* memoised one the root loader reads, so this costs no extra request.
+*/
+const storefrontAvailabilityMiddleware = createMiddleware().server(async ({ next }) => {
+	let shop;
+	try {
+		shop = await fetchShopInfo();
+	} catch {
+		return next();
+	}
+	if (!shop || shop.status === "active") return next();
+	return unavailableResponse(shop.name);
+});
+function unavailableResponse(shopName) {
+	const name = escapeHtmlAttr(shopName);
+	const html = `<!doctype html>
+<html lang="mn">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${name}</title>
+<style>
+:root{color-scheme:light dark;--bg:#fafafa;--fg:#171717;--muted:#737373}
+@media (prefers-color-scheme:dark){:root{--bg:#0a0a0a;--fg:#fafafa;--muted:#a3a3a3}}
+body{margin:0;min-height:100svh;display:grid;place-items:center;padding:24px;box-sizing:border-box;background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;text-align:center}
+main{max-width:28rem}
+h1{margin:0 0 12px;font-size:1.25rem;font-weight:600}
+p{margin:4px 0;color:var(--muted)}
+</style>
+</head>
+<body>
+<main>
+<h1>${name}</h1>
+<p>Энэ дэлгүүр одоогоор түр хаалттай байна.</p>
+<p lang="en">This store is currently unavailable.</p>
+</main>
+</body>
+</html>
+`;
+	return new Response(html, {
+		status: 503,
+		headers: {
+			"Content-Type": "text/html; charset=utf-8",
+			"Cache-Control": "no-store",
+			"X-Robots-Tag": "noindex"
+		}
+	});
+}
+//#endregion
+export { storefrontAvailabilityMiddleware };

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/collection.d.ts

@@ -184,6 +184,7 @@ export declare const CollectionImageFragment: import("gql.tada").TadaDocumentNod
   thumbUrl: string | null;
   thumbhash: string | null;
   url: string | null;
+  url1_5x: string | null;
   url2x: string | null;
   url3x: string | null;
   width: number | null;

package/dist/collection.js

@@ -134,6 +134,7 @@ const CollectionImageFragment = graphql(`
     thumbhash
     ... on ShopMediaImage {
       url(transform: { maxWidth: 640 })
+      url1_5x: url(transform: { maxWidth: 960 })
       url2x: url(transform: { maxWidth: 640, scale: 2 })
       url3x: url(transform: { maxWidth: 640, scale: 3 })
       thumbUrl: url(transform: { maxWidth: 80 })

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/files.d.ts

@@ -36,6 +36,7 @@ type FileLikeNode = {
   preview?: {
     url?: string | null;
   } | null;
+  url1_5x?: string | null;
   url2x?: string | null;
   url3x?: string | null;
   thumbUrl?: string | null;

package/dist/files.js

@@ -6,6 +6,7 @@ const FileByIdQuery = graphql(`
   query FileById(
     $id: ID!
     $transform: ImageTransformInput
+    $transform1_5x: ImageTransformInput
     $transform2x: ImageTransformInput
     $transform3x: ImageTransformInput
   ) {
@@ -18,6 +19,7 @@ const FileByIdQuery = graphql(`
         width
         height
         url(transform: $transform)
+        url1_5x: url(transform: $transform1_5x)
         url2x: url(transform: $transform2x)
         url3x: url(transform: $transform3x)
         focalPoint {
@@ -50,23 +52,30 @@ function buildSrcset(entries) {
 	}
 	return parts.length > 1 ? parts.join(", ") : null;
 }
+function ladderSrcset(node, baseWidth) {
+	return buildSrcset([
+		{
+			url: node.url,
+			w: baseWidth
+		},
+		{
+			url: node.url1_5x,
+			w: Math.round(baseWidth * 1.5)
+		},
+		{
+			url: node.url2x,
+			w: baseWidth * 2
+		},
+		{
+			url: node.url3x,
+			w: baseWidth * 3
+		}
+	]);
+}
 function toFileInfo(node, extra = {}) {
 	if (!node) return null;
 	if (node.__typename === "ShopMediaImage") {
-		const computedSrcset = extra.baseWidth != null ? buildSrcset([
-			{
-				url: node.url,
-				w: extra.baseWidth
-			},
-			{
-				url: node.url2x,
-				w: extra.baseWidth * 2
-			},
-			{
-				url: node.url3x,
-				w: extra.baseWidth * 3
-			}
-		]) : null;
+		const computedSrcset = extra.baseWidth != null ? ladderSrcset(node, extra.baseWidth) : null;
 		return {
 			kind: "image",
 			id: node.id ?? "",
@@ -106,29 +115,31 @@ function scaled(t, scale) {
 		scale
 	};
 }
+function widened(t) {
+	if (!t?.maxWidth) return null;
+	const { scale: _, ...rest } = t;
+	return {
+		...rest,
+		maxWidth: Math.round(t.maxWidth * 1.5),
+		...t.maxHeight ? { maxHeight: Math.round(t.maxHeight * 1.5) } : {}
+	};
+}
 const fetchFileById = memoTTL(async ({ id, transform }) => {
 	const node = (await request(FileByIdQuery, {
 		id,
 		transform: transform ?? null,
+		transform1_5x: widened(transform),
 		transform2x: scaled(transform, 2),
 		transform3x: scaled(transform, 3)
 	})).node;
 	if (!node) return null;
 	const baseWidth = transform?.maxWidth;
-	return toFileInfo(node, { srcset: node.__typename === "ShopMediaImage" && baseWidth != null ? buildSrcset([
-		{
-			url: node.url,
-			w: baseWidth
-		},
-		{
-			url: node.url2x,
-			w: baseWidth * 2
-		},
-		{
-			url: node.url3x,
-			w: baseWidth * 3
-		}
-	]) : null });
+	return toFileInfo(node, { srcset: node.__typename === "ShopMediaImage" && baseWidth != null ? ladderSrcset({
+		url: node.url,
+		url1_5x: node.url1_5x,
+		url2x: node.url2x,
+		url3x: node.url3x
+	}, baseWidth) : null });
 }, {
 	key: ({ id, transform }) => `${id}|${transform ? JSON.stringify(transform) : ""}`,
 	version: getContentVersion

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;
@@ -26,6 +27,7 @@ declare const ShopQuery: import("gql.tada").TadaDocumentNode<{
       turnstileSitekey: string | null;
     } | null;
     primaryLocale: string;
+    status: string;
     taxesIncluded: boolean;
     timezone: string;
     turnstileSitekey: string | null;

package/dist/shop.js

@@ -8,6 +8,7 @@ const ShopQuery = graphql(`
       id
       name
       handle
+      status
       currency
       timezone
       primaryLocale
@@ -18,6 +19,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.4.0",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "files": [
     "dist"
@@ -11,6 +11,7 @@
     "./activity": "./dist/activity.js",
     "./analytics-proxy": "./dist/analytics-proxy.js",
     "./analytics-script-proxy": "./dist/analytics-script-proxy.js",
+    "./availability": "./dist/availability.js",
     "./blog": "./dist/blog.js",
     "./cache": "./dist/cache.js",
     "./canonical-host": "./dist/canonical-host.js",
@@ -58,8 +59,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.4.0",
+    "@shop-on/theme-runtime": "0.4.0"
   },
   "devDependencies": {
     "@tanstack/react-start": "1.169.3",