Add cart customer identity sync hooks

[fredericoo]

TL;DR: Cart handlers can now associate newly created carts with the current Customer Account session, while Customer Account routes expose lifecycle hooks for application-owned synchronization of existing carts.

Before

Cart creation did not include Customer Account buyer identity, and the standard authorization, refresh, and logout routes offered no integration points for related session work.

After

const cartHandlers = createCartServerHandlers({customerSession});

const updateCartBuyerIdentity = async (context, customerAccessToken) => {
  const cartId = await getVerifiedCartId(context.sessionManager);
  if (!cartId) return;

  await context.storefrontClient.graphql(CART_BUYER_IDENTITY_UPDATE, {
    variables: {
      cartId,
      buyerIdentity: {customerAccessToken},
    },
  });
};

const attachCartBuyerIdentity = async (context, accessToken) => {
  await updateCartBuyerIdentity(context, accessToken);
};

const refreshCartBuyerIdentity = async (context, result) => {
  if (result.status === "transient") return;
  await updateCartBuyerIdentity(context, result.accessToken ?? null);
};

const customerAccountHandlers = createCustomerAccountServerHandlers({
  customerSession,
  onAuthenticated: attachCartBuyerIdentity,
  onTokenRefresh: refreshCartBuyerIdentity,
  onLogout: (context) => updateCartBuyerIdentity(context, null),
});

getVerifiedCartId must resolve a cart ID from protected server-side ownership state, not an unsigned client-controlled cookie or request value.

What this changes

• Adds the current usable customer token to new cart buyer identity.
• Marks checkout URLs in authenticated cart GET responses with logged_in=true.
• Adds Customer Account lifecycle hooks that run before session commit. Authentication receives the exact issued token; refresh receives a discriminated authenticated, transient, or unauthenticated result.
• Commits session state and returns a sanitized server error when a lifecycle hook rejects.
• Adds secure cart synchronization guidance based on protected server-side cart ownership.

Developer impact

Includes a minor changeset for @shopify/hydrogen. The new cart option, lifecycle hooks, handler types, and documentation are additive; existing handler configuration remains unchanged. Token-bearing hooks require the session returned by createCustomerSession; custom session implementations can continue using standard routes and onLogout.

Out of scope

• Hydrogen does not automatically associate existing carts during Customer Account lifecycle routes.
• Applications own cart-ID verification, synchronization mutations, and fail-safe logout cleanup.

Risk

• Customer-aware cart reads add one protected session lookup.
• Lifecycle hooks run on the authentication request path, so applications should bound downstream work and honour the request abort signal.
• Existing-cart synchronization must never trust an unsigned client-controlled cart ID.

[fredericoo]

note that we dont do it automatically as the use case is not for every customer.

in addition, we dont want to control how users store the cart id cookie and binding a non httpOnly cookie to a httpOnly session was flagged by security review from one of my subagents

this way we leave the responsibility to the implementer

this may be bad, because there is a lot more wiring up to do, im willing to discuss whether this is the most sane approach or an "auto sync" is a better idea

[graygilmore]

Not entirely sure how to 🎩 this one so I'm leaving the one critical thing that the bots found.

[graygilmore]

🔒 Security: customerSession.logout() at line 658 clears the session and destroys tokens.idToken. It then builds the Shopify end-session URL from that token. Line 663 discards that URL when onLogout rejects and returns a 500.

The result: the app session is gone, but the Shopify IdP session stays alive. A retry cannot fix this. A second logout reads an empty session, hits if (!idToken) at line 498, and redirects home. The next login silently signs the customer back in. On a shared device, the buyer pressed "Log out" but stays signed in at Shopify.

The other hook sites (authorize, refresh) are safe. A rejected hook there only skips a redirect the user can retry. Logout is the one site where "skip the redirect" destroys state first.

Suggestion: Complete the redirect even when the hook rejects. The documented cleanup pattern (cart-sync.md:73-78) writes its marker into the session before it rethrows, and commitSession runs on both paths, so app cleanup still occurs. Update session.test.ts:779-811 to expect the 303 and note the behavior in cart-sync.md.

The alternative — run onLogout before customerSession.logout() — keeps the 500 signal but breaks the documented "runs after logout" contract. Your call. The current order is the one option with no recovery path.

[frandiox]

Thanks for working on this! I like the direction but at the same time I feel we should make things a bit simpler for the most common path? 🤔

What if we provide something like this? (name tbd)

const cartBuyerIdentity = createCartBuyerIdentitySync({
  customerSession,
});

const cartHandlers = createCartServerHandlers({
  cartBuyerIdentity,
  // Or if we want to have top level hooks:
  // onCartCreated: cartBuyerIdentity.onCartCreated,
});

const customerAccountHandlers = createCustomerAccountServerHandlers({
  cartBuyerIdentity
  // Or with hooks:
  // ...cartBuyerIdentity.customerAccountHooks,
});

Hydrogen already writes the cart cookie and receives the trusted cart ID directly from the Storefront API when it creates the cart. The helper would save that same ID in protected session storage and commit it on the response. It would not trust a cart ID sent by the browser.

createCartBuyerIdentitySync would run cartBuyerIdentityUpdate after login and refresh, clear the identity on logout, and own cookie cleanup and request ordering. The helper is opt-in and tree-shakeable.

We could still consider keeping the the lifecycle hooks if we want to be extra flexible as a low-level API and this helper can use it. If not, the helper can keep that lifecycle wiring internal and expose only the cart-specific API.

[frandiox]

If the access token expires and only a valid refresh token remains, isLoggedIn returns true, but getAccessToken does not refresh it. New carts are then created without buyer identity.

The /api/cart handler also does not save the trusted cart ID needed to attach the customer after the token is refreshed. Should the helper handle this automatically somehow? 🤔

[fredericoo]

we have getOrRefreshAccessToken for that, but i believe this is quite complex and easy to miss

[frandiox]

What if refresh + logout both overlap and refresh ends later? It's virtually re-logged-in?

Could the safe default be to always remove the protected cart binding and expire or rotate the cart cookie during logout?

[frandiox]

I don't think we want these examples in the readme? Also it's not complete because it also needs requestContext etc.

[frandiox]

I think basically app and checkout have different meanings of "logged in"? If so maybe a returning customer could get an anonymous cart?

[frandiox]

So at this point the user is actually authenticated, but something in the hook went wrong? I'm not sure what's the correct response to this... 500 might be misleading since auth actually worked, and it would be stuck in the callback URL?

[frandiox]

Could we validate storefrontClient before updating the session, and give the app a safe way to observe hook errors? Right now every failure becomes the same generic log, so it is hard to tell what went wrong.

[fredericoo]

Thanks for working on this! I like the direction but at the same time I feel we should make things a bit simpler for the most common path? 🤔

What if we provide something like this? (name tbd)

const cartBuyerIdentity = createCartBuyerIdentitySync({
  customerSession,
});

const cartHandlers = createCartServerHandlers({
  cartBuyerIdentity,
  // Or if we want to have top level hooks:
  // onCartCreated: cartBuyerIdentity.onCartCreated,
});

const customerAccountHandlers = createCustomerAccountServerHandlers({
  cartBuyerIdentity
  // Or with hooks:
  // ...cartBuyerIdentity.customerAccountHooks,
});

Hydrogen already writes the cart cookie and receives the trusted cart ID directly from the Storefront API when it creates the cart. The helper would save that same ID in protected session storage and commit it on the response. It would not trust a cart ID sent by the browser.

createCartBuyerIdentitySync would run cartBuyerIdentityUpdate after login and refresh, clear the identity on logout, and own cookie cleanup and request ordering. The helper is opt-in and tree-shakeable.

We could still consider keeping the the lifecycle hooks if we want to be extra flexible as a low-level API and this helper can use it. If not, the helper can keep that lifecycle wiring internal and expose only the cart-specific API.

my original idea was on the lines of createCustomerAccountServerHandlers({cartServerHandlers}) this way we call cartServerHandlers.updateBuyerIdentity automatically whenever the user is authorised or logs out

a security subagent flagged that this could mean we attach a non httpOnly cookie that can be fiddled with by the user, to an encrypted user session. to work around that i exposed the hooks that make it possible to do it yourself, but it's now down to the implementer to keep the cart cookie safe however they want

i would now suggest we do it like the initial idea (binding customer account with cart handlers like my code example) and consider either encrypting the cart cookie or just live with it, it's not really a security concern, the cart id cookie is already exposed and does nothing, attaching a modified cart id to your session means nothing at all to us

it felt much simpler to operate in the initial implementatioin than it does not (surely a lot less docs)