@doswiftly/storefront-sdk 11.4.0 → 11.5.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 11.5.0
+
+### Minor Changes
+
+- 190fd9d: `CartClient.complete()` now returns `Order.accessToken` — unblocks guest order summary flow end-to-end.
+
+  **What changed:**
+
+  Internal `ORDER_FRAGMENT` selection set now includes `accessToken: String!`. Before this version the SDK omitted the field defensively (the backend resolver was incomplete in 11.4.0 — selecting `accessToken` crashed the entire response with a non-nullable violation). The backend resolver is now fixed; this version restores `accessToken` selection so `cartComplete.order.accessToken` returns the token that you pass to `OrderByToken` for guest summary pages.
+
+  **Upgrade impact:**
+  - After upgrade, `cart.complete()` response includes `order.accessToken` (non-empty UUID v4 string). Use it to build guest summary URLs (e.g. `/order/summary?token=${order.accessToken}`).
+  - No breaking change — existing code that destructures the `order` object continues to work; the new field is additive.
+
+  **Backward compatibility:** SDK consumers on the previous version that already destructure `order` keep working. The new `accessToken` field is added; existing fields (`id`, `orderNumber`, `totals`, `status`, etc.) are unchanged.
+
+  **Companion**: `@doswiftly/storefront-operations` ships the same field in its `Order` fragment and the new `OrderByToken` query (see that changelog entry for full security model — rate limit, email guard, Cache-Control).
+
+- e6c80ce: Auth route handlers (`createSetTokenHandler`, `createClearTokenHandler`, `createWhoamiHandler`) now accept an optional `isTrustedOrigin` predicate. This unblocks the BFF auth flow when the storefront runs behind a reverse proxy (DoSwiftly hosting, Vercel, custom edge proxy) that rewrites or strips the `Host` header — since 11.3.0 the strict `Origin host = Host` comparison returned 403 for every login, logout, and page-load hydration in that topology, leaving the auth cookie unset and every auth-gated route redirecting to login.
+
+  ### Fix
+
+  Each handler accepts a new `isTrustedOrigin` callback:
+
+  ```ts
+  type OriginValidator = (ctx: {
+    origin: string;
+    originHost: string;
+    request: Request;
+  }) => boolean | Promise<boolean>;
+  ```
+
+  When the predicate returns truthy the strict `Origin host = Host header` comparison is bypassed; when it returns falsy (or is not configured) the existing strict check applies. A thrown predicate fails closed — the error is logged and the strict check applies as if the predicate returned `false`.
+
+  Two pre-built predicates are exported:
+  - `trustedForwardedHostValidator` — passes when `Origin host` equals `X-Forwarded-Host` (falling back to `X-Original-Host`). Use this when a reverse proxy you control sets one of those headers per request. The DoSwiftly hosting platform and Vercel both qualify.
+  - `originAllowlistValidator(['https://shop.example.com', 'other-shop.example'])` — passes when `Origin` matches an entry in a static list. Useful when one storefront is hosted on multiple hostnames (custom apex + platform subdomain) and you do not want to depend on forwarded-host headers.
+
+  ### Upgrade impact
+  - New storefronts scaffolded via `doswiftly init` ship with `isTrustedOrigin: trustedForwardedHostValidator` configured by default.
+  - Existing storefronts using the SDK behind a reverse proxy need a 3-line change to each route handler under `app/api/auth/`:
+    ```ts
+    import {
+      createSetTokenHandler,
+      trustedForwardedHostValidator,
+    } from "@doswiftly/storefront-sdk";
+    export const POST = createSetTokenHandler({
+      isTrustedOrigin: trustedForwardedHostValidator,
+    });
+    ```
+  - Storefronts deployed without a reverse proxy (single-tier hosting where the Next.js process receives traffic directly) need no changes — the default strict check still works because the Host header arrives intact.
+
+  ### Security
+
+  The predicate is invoked AFTER the Origin header is parsed (rejecting malformed origins) and BEFORE the strict Host comparison. Forwarded-host validation is safe because the trusted intermediary overwrites those headers on every inbound request (`headers.set(...)`, not `append`), so an attacker cannot forge them via a browser `fetch()` — browsers cannot set `X-Forwarded-*` from JavaScript (they are forbidden request headers per the fetch spec).
+
+  Defense-in-depth layers continue to apply: CORS preflight at the backend, `SameSite=Lax` on the auth cookie, `HttpOnly` + `Secure` cookie attributes, and the strict Origin URL parse (still rejects malformed origin and the `?host=trusted` query-string bypass).
+
+- 6b9f907: `createWhoamiHandler` now allows missing `Origin` header for safe (GET) requests — fixes "user logged out after refresh" regression introduced in 11.3.0.
+
+  **Background:**
+
+  Per fetch spec § 3.5.6, browsers OMIT the `Origin` header for same-origin GET/HEAD requests. The hardened `validateOrigin()` introduced in 11.3.0 required `Origin` for every call, so every page-load hydration via `GET /api/auth/whoami` returned 403 — the in-memory auth store stayed empty even though the httpOnly cookie was valid, and the UI reverted to "Sign in" on refresh. Auth-protected mutations kept working (the cookie was sent automatically), only the UI hydration was broken.
+
+  **Fix:**
+
+  `validateOrigin()` accepts an optional `{ allowMissingOrigin: true }` flag. When set, missing `Origin` is allowed (typical same-origin GET); when `Origin` is present, mismatch is still rejected (defense-in-depth for cross-origin GET edge cases — e.g. `fetch(..., { mode: 'cors' })` does send `Origin`). `createWhoamiHandler` opts into the lenient check because `GET /whoami` is CSRF-safe (idempotent, no state change, response is JSON same-origin attackers cannot read anyway). `createSetTokenHandler` and `createClearTokenHandler` keep the strict check — they are POST and browsers always send `Origin` for state-changing methods.
+
+  **Upgrade impact:**
+  - After upgrade, `GET /api/auth/whoami` succeeds for same-origin browser fetch with no `Origin` header — the auth store hydrates correctly on page-load, the UI shows the signed-in customer instead of "Sign in".
+  - No code change required in your storefront — the SDK's BFF handler is the only thing that needs updating.
+  - POST handlers (`createSetTokenHandler`, `createClearTokenHandler`) are unchanged; existing strict `Origin` validation stays in place for mutations.
+
 ## 11.4.0
 
 ### Minor Changes

package/dist/core/auth/handlers.d.ts

@@ -12,14 +12,119 @@
  * export const POST = createSetTokenHandler();
  * ```
  */
+/**
+ * Context passed to {@link OriginValidator} predicate callbacks.
+ *
+ * Includes the already-parsed `originHost` so factory helpers do not
+ * re-parse, and the full `Request` so a predicate can inspect any header
+ * set by a trusted intermediary (e.g. `X-Forwarded-Host`).
+ */
+export interface OriginValidatorContext {
+    /** Raw `Origin` header value (e.g. `https://shop.example.com`). */
+    origin: string;
+    /** Parsed `host` portion of the origin URL (e.g. `shop.example.com`). */
+    originHost: string;
+    /** Full incoming request — read additional headers as needed. */
+    request: Request;
+}
+/**
+ * Predicate that decides whether an incoming origin should be trusted
+ * even when the strict `Origin host = Host header` comparison would fail.
+ *
+ * When the predicate returns truthy, `validateOrigin` returns `null` (pass).
+ * When it returns falsy, the strict Host check applies (current behavior).
+ * When the predicate throws, `validateOrigin` fails closed — the throw is
+ * logged and the strict Host check applies as if the predicate returned `false`.
+ *
+ * Use {@link trustedForwardedHostValidator} for reverse-proxy deployments
+ * (Cloudflare Workers dispatch, Vercel, NGINX, etc.) or
+ * {@link originAllowlistValidator} for explicit hostname allowlists.
+ */
+export type OriginValidator = (ctx: OriginValidatorContext) => boolean | Promise<boolean>;
 interface SetTokenHandlerOptions {
+    /** Cookie `Max-Age` override (seconds). */
     maxAge?: number;
+    /** Optional predicate that bypasses strict Host check when truthy. */
+    isTrustedOrigin?: OriginValidator | null;
+}
+interface ClearTokenHandlerOptions {
+    /** Optional predicate that bypasses strict Host check when truthy. */
+    isTrustedOrigin?: OriginValidator | null;
 }
+/**
+ * Pre-built {@link OriginValidator} that passes when the parsed `Origin` host
+ * matches a hostname set by a trusted reverse proxy.
+ *
+ * Reads `X-Forwarded-Host` first (RFC 7239 de-facto standard, multiple values
+ * are comma-separated — the first entry is the original client-facing host).
+ * Falls back to `X-Original-Host` (a header the DoSwiftly dispatch worker
+ * emits alongside `X-Forwarded-Host`).
+ *
+ * Safety: this predicate is only spoof-resistant when invoked inside a runtime
+ * that sits behind a trusted intermediary which OVERWRITES these headers on
+ * every inbound request (the dispatch worker calls `headers.set(...)`, not
+ * `append`, so a client-sent value is replaced). Browsers cannot set
+ * `X-Forwarded-*` from JS — these are forbidden request headers per fetch
+ * spec — so CSRF requests from a malicious origin cannot forge them.
+ *
+ * Use this predicate when deploying behind the DoSwiftly dispatch worker,
+ * Vercel, NGINX, or any reverse proxy that strips/rewrites `Host` while
+ * preserving `Origin`.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/set-token/route.ts
+ * import {
+ *   createSetTokenHandler,
+ *   trustedForwardedHostValidator,
+ * } from '@doswiftly/storefront-sdk';
+ *
+ * export const POST = createSetTokenHandler({
+ *   isTrustedOrigin: trustedForwardedHostValidator,
+ * });
+ * ```
+ */
+export declare const trustedForwardedHostValidator: OriginValidator;
+/**
+ * Factory that returns an {@link OriginValidator} which passes when the
+ * parsed `Origin` host matches one of the entries in `allowedOrigins`.
+ *
+ * Each entry may be a full origin URL (`https://shop.example.com`) or a bare
+ * hostname (`shop.example.com`). The factory normalizes both forms to the
+ * hostname for comparison.
+ *
+ * Use this predicate when deploying without a reverse proxy that sets
+ * `X-Forwarded-Host`, or when hosting one storefront on multiple hostnames
+ * (custom apex + platform subdomain). When a custom domain is added to the
+ * merchant's shop, the integrator must redeploy with the new hostname in the
+ * list — for runtime-synced allowlists prefer {@link trustedForwardedHostValidator}
+ * behind a reverse proxy.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/set-token/route.ts
+ * import {
+ *   createSetTokenHandler,
+ *   originAllowlistValidator,
+ * } from '@doswiftly/storefront-sdk';
+ *
+ * export const POST = createSetTokenHandler({
+ *   isTrustedOrigin: originAllowlistValidator([
+ *     'https://shop.example.com',
+ *     'shop-example.doswiftly.pl',
+ *   ]),
+ * });
+ * ```
+ */
+export declare function originAllowlistValidator(allowedOrigins: string[]): OriginValidator;
 /**
  * Create a POST handler that sets the auth token in an httpOnly cookie.
  *
  * Security: origin validation, Content-Type check, CSRF (SameSite=Lax),
  * httpOnly (XSS protection), Secure in production.
+ *
+ * Pass `isTrustedOrigin` when running behind a reverse proxy that strips or
+ * rewrites the `Host` header — see {@link trustedForwardedHostValidator}.
  */
 export declare function createSetTokenHandler(overrides?: SetTokenHandlerOptions): (request: Request) => Promise<Response>;
 interface WhoamiHandlerOptions {
@@ -27,6 +132,8 @@ interface WhoamiHandlerOptions {
     apiUrl?: string;
     /** Shop slug header value (X-Shop-Slug). */
     shopSlug?: string;
+    /** Optional predicate that bypasses strict Host check when truthy. */
+    isTrustedOrigin?: OriginValidator | null;
 }
 /**
  * Create a GET handler that hydrates customer state z httpOnly cookie.
@@ -41,6 +148,8 @@ interface WhoamiHandlerOptions {
  * 4. Klient setAuth(customer, '') — token NIE w body (cookie kontynuuje per-request auth)
  *
  * Security: origin validation, fetch via Bearer (cookie nie crossuje API boundary).
+ * Pass `isTrustedOrigin` when running behind a reverse proxy — see
+ * {@link trustedForwardedHostValidator}.
  *
  * @example
  * ```ts
@@ -57,7 +166,10 @@ export declare function createWhoamiHandler(options?: WhoamiHandlerOptions): (re
  * Create a POST handler that clears the auth token cookie.
  *
  * Security: origin validation, immediate expiration (maxAge=0).
+ *
+ * Pass `isTrustedOrigin` when running behind a reverse proxy that strips or
+ * rewrites the `Host` header — see {@link trustedForwardedHostValidator}.
  */
-export declare function createClearTokenHandler(): (request: Request) => Promise<Response>;
+export declare function createClearTokenHandler(options?: ClearTokenHandlerOptions): (request: Request) => Promise<Response>;
 export {};
 //# sourceMappingURL=handlers.d.ts.map

package/dist/core/auth/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/core/auth/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,UAAU,sBAAsB;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,sBAAsB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAgEzC;AAED,UAAU,oBAAoB;IAC5B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA6DzC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAkCjF"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/core/auth/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,sBAAsB,KACxB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,UAAU,sBAAsB;IAC9B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAED,UAAU,wBAAwB;IAChC,sEAAsE;IACtE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAqHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,6BAA6B,EAAE,eAa3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EAAE,GACvB,eAAe,CAajB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,sBAAsB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiEzC;AAED,UAAU,oBAAoB;IAC5B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAwEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,CAAC,EAAE,wBAAwB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAoCzC"}

package/dist/core/auth/handlers.js

@@ -37,15 +37,31 @@ function serializeCookie(name, value, options) {
  * - `origin = "https://attacker.example/?host=trusted"` → substring match
  *   passes for any trusted host name.
  *
- * Both Origin and Host MUST be present (typical browser fetch sends Origin
- * for cross-origin and same-origin POSTs; server-to-server callers without
- * an Origin header should hit the GraphQL API directly, not these BFF
- * handlers).
+ * For state-changing methods (POST/PUT/PATCH/DELETE) browsers always send
+ * Origin (fetch spec § 3.5.6 — "method is neither GET nor HEAD"). For safe
+ * methods (GET/HEAD) browsers OMIT Origin for same-origin requests; passing
+ * `allowMissingOrigin: true` skips the "Origin required" check while still
+ * validating mismatch when Origin happens to be present (defense-in-depth
+ * for cross-origin GET edge cases).
+ *
+ * When `isTrustedOrigin` is provided, the predicate is evaluated AFTER the
+ * Origin is parsed but BEFORE the strict Host comparison. If the predicate
+ * returns truthy, the request passes — useful when running behind a reverse
+ * proxy that rewrites or strips the `Host` header (Cloudflare Workers
+ * dispatch, Vercel, etc.) while preserving the customer-facing host in
+ * `X-Forwarded-Host`. The predicate is consulted instead of (not in addition
+ * to) the strict check.
+ *
+ * Server-to-server callers without an Origin header should hit the GraphQL
+ * API directly, not these BFF handlers.
  */
-function validateOrigin(request) {
+async function validateOrigin(request, options) {
     const origin = request.headers.get('origin');
-    const host = request.headers.get('host');
-    if (!origin || !host) {
+    // GET/HEAD same-origin: browser omits Origin per fetch spec — pass through.
+    // Mutating methods (POST/etc.) MUST have Origin (browsers always send it).
+    if (!origin) {
+        if (options?.allowMissingOrigin)
+            return null;
         return new Response(JSON.stringify({ error: 'Origin and Host headers are required' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
     }
     let originHost;
@@ -58,6 +74,31 @@ function validateOrigin(request) {
             headers: { 'Content-Type': 'application/json' },
         });
     }
+    // Predicate gate (bypasses strict Host check for reverse-proxy deployments).
+    // Fail-closed: predicate throw is logged + fall through to strict check.
+    if (options?.isTrustedOrigin) {
+        try {
+            const trusted = await options.isTrustedOrigin({
+                origin,
+                originHost,
+                request,
+            });
+            if (trusted)
+                return null;
+        }
+        catch (err) {
+            console.warn('isTrustedOrigin predicate threw:', err);
+            // continue to strict Host check
+        }
+    }
+    // Strict Host check — backward compatible fallback when no predicate is
+    // configured or predicate returned false. Reverse proxies that drop the
+    // Host header MUST use a predicate; bare-metal deploys without a proxy
+    // see the original Host and pass strict.
+    const host = request.headers.get('host');
+    if (!host) {
+        return new Response(JSON.stringify({ error: 'Origin and Host headers are required' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
+    }
     if (originHost !== host) {
         return new Response(JSON.stringify({ error: 'Origin mismatch' }), {
             status: 403,
@@ -66,18 +107,115 @@ function validateOrigin(request) {
     }
     return null;
 }
+/**
+ * Pre-built {@link OriginValidator} that passes when the parsed `Origin` host
+ * matches a hostname set by a trusted reverse proxy.
+ *
+ * Reads `X-Forwarded-Host` first (RFC 7239 de-facto standard, multiple values
+ * are comma-separated — the first entry is the original client-facing host).
+ * Falls back to `X-Original-Host` (a header the DoSwiftly dispatch worker
+ * emits alongside `X-Forwarded-Host`).
+ *
+ * Safety: this predicate is only spoof-resistant when invoked inside a runtime
+ * that sits behind a trusted intermediary which OVERWRITES these headers on
+ * every inbound request (the dispatch worker calls `headers.set(...)`, not
+ * `append`, so a client-sent value is replaced). Browsers cannot set
+ * `X-Forwarded-*` from JS — these are forbidden request headers per fetch
+ * spec — so CSRF requests from a malicious origin cannot forge them.
+ *
+ * Use this predicate when deploying behind the DoSwiftly dispatch worker,
+ * Vercel, NGINX, or any reverse proxy that strips/rewrites `Host` while
+ * preserving `Origin`.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/set-token/route.ts
+ * import {
+ *   createSetTokenHandler,
+ *   trustedForwardedHostValidator,
+ * } from '@doswiftly/storefront-sdk';
+ *
+ * export const POST = createSetTokenHandler({
+ *   isTrustedOrigin: trustedForwardedHostValidator,
+ * });
+ * ```
+ */
+export const trustedForwardedHostValidator = ({ originHost, request, }) => {
+    const xfh = request.headers.get('x-forwarded-host');
+    if (xfh) {
+        // RFC 7239 — chain of proxies appends, first value is the original host.
+        const original = xfh.split(',')[0]?.trim();
+        if (original && original === originHost)
+            return true;
+    }
+    const xoh = request.headers.get('x-original-host');
+    if (xoh && xoh.trim() === originHost)
+        return true;
+    return false;
+};
+/**
+ * Factory that returns an {@link OriginValidator} which passes when the
+ * parsed `Origin` host matches one of the entries in `allowedOrigins`.
+ *
+ * Each entry may be a full origin URL (`https://shop.example.com`) or a bare
+ * hostname (`shop.example.com`). The factory normalizes both forms to the
+ * hostname for comparison.
+ *
+ * Use this predicate when deploying without a reverse proxy that sets
+ * `X-Forwarded-Host`, or when hosting one storefront on multiple hostnames
+ * (custom apex + platform subdomain). When a custom domain is added to the
+ * merchant's shop, the integrator must redeploy with the new hostname in the
+ * list — for runtime-synced allowlists prefer {@link trustedForwardedHostValidator}
+ * behind a reverse proxy.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/set-token/route.ts
+ * import {
+ *   createSetTokenHandler,
+ *   originAllowlistValidator,
+ * } from '@doswiftly/storefront-sdk';
+ *
+ * export const POST = createSetTokenHandler({
+ *   isTrustedOrigin: originAllowlistValidator([
+ *     'https://shop.example.com',
+ *     'shop-example.doswiftly.pl',
+ *   ]),
+ * });
+ * ```
+ */
+export function originAllowlistValidator(allowedOrigins) {
+    const allowedHosts = new Set();
+    for (const entry of allowedOrigins) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        // Support both `https://host[:port]` and bare `host[:port]` entries.
+        try {
+            allowedHosts.add(new URL(trimmed).host);
+        }
+        catch {
+            allowedHosts.add(trimmed);
+        }
+    }
+    return ({ originHost }) => allowedHosts.has(originHost);
+}
 /**
  * Create a POST handler that sets the auth token in an httpOnly cookie.
  *
  * Security: origin validation, Content-Type check, CSRF (SameSite=Lax),
  * httpOnly (XSS protection), Secure in production.
+ *
+ * Pass `isTrustedOrigin` when running behind a reverse proxy that strips or
+ * rewrites the `Host` header — see {@link trustedForwardedHostValidator}.
  */
 export function createSetTokenHandler(overrides) {
     const maxAge = overrides?.maxAge ?? AUTH_COOKIE_DEFAULTS.maxAge;
+    const isTrustedOrigin = overrides?.isTrustedOrigin ?? null;
     return async (request) => {
         try {
             // 1. CSRF: validate origin
-            const originError = validateOrigin(request);
+            const originError = await validateOrigin(request, { isTrustedOrigin });
             if (originError)
                 return originError;
             // 2. Validate Content-Type
@@ -132,6 +270,8 @@ export function createSetTokenHandler(overrides) {
  * 4. Klient setAuth(customer, '') — token NIE w body (cookie kontynuuje per-request auth)
  *
  * Security: origin validation, fetch via Bearer (cookie nie crossuje API boundary).
+ * Pass `isTrustedOrigin` when running behind a reverse proxy — see
+ * {@link trustedForwardedHostValidator}.
  *
  * @example
  * ```ts
@@ -144,9 +284,19 @@ export function createSetTokenHandler(overrides) {
  * ```
  */
 export function createWhoamiHandler(options = {}) {
+    const isTrustedOrigin = options.isTrustedOrigin ?? null;
     return async (request) => {
         try {
-            const originError = validateOrigin(request);
+            // GET /whoami is CSRF-safe (idempotent, no state change). Browsers OMIT
+            // Origin header for same-origin GET per fetch spec § 3.5.6 — strict
+            // Origin requirement would 403 every page load on storefronts using
+            // same-origin BFF setup (Next.js `/api/auth/whoami` Route Handler).
+            // We still validate mismatch when Origin is present (cross-origin GET
+            // edge case — fetch with `mode: 'cors'` does send Origin).
+            const originError = await validateOrigin(request, {
+                allowMissingOrigin: true,
+                isTrustedOrigin,
+            });
             if (originError)
                 return originError;
             const cookieHeader = request.headers.get('cookie') ?? '';
@@ -192,12 +342,16 @@ export function createWhoamiHandler(options = {}) {
  * Create a POST handler that clears the auth token cookie.
  *
  * Security: origin validation, immediate expiration (maxAge=0).
+ *
+ * Pass `isTrustedOrigin` when running behind a reverse proxy that strips or
+ * rewrites the `Host` header — see {@link trustedForwardedHostValidator}.
  */
-export function createClearTokenHandler() {
+export function createClearTokenHandler(options) {
+    const isTrustedOrigin = options?.isTrustedOrigin ?? null;
     return async (request) => {
         try {
             // 1. CSRF: validate origin
-            const originError = validateOrigin(request);
+            const originError = await validateOrigin(request, { isTrustedOrigin });
             if (originError)
                 return originError;
             // 2. Clear cookie (maxAge=0)

package/dist/core/index.d.ts

@@ -62,7 +62,8 @@ export { LANGUAGE_COOKIE_NAME, LANGUAGE_COOKIE_MAX_AGE, LANGUAGE_HEADER_NAME } f
 export { CURRENCY_COOKIE_NAME, CURRENCY_COOKIE_MAX_AGE, CURRENCY_HEADER_NAME } from './currency/cookie-config';
 export { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from './cart/cookie-config';
 export { matchesRoute, type RouteProtectionConfig } from './auth/routes';
-export { createSetTokenHandler, createClearTokenHandler, createWhoamiHandler } from './auth/handlers';
+export { createSetTokenHandler, createClearTokenHandler, createWhoamiHandler, originAllowlistValidator, trustedForwardedHostValidator, } from './auth/handlers';
+export type { OriginValidator, OriginValidatorContext } from './auth/handlers';
 export { createAuthTokenClient, type AuthTokenClient } from './auth/token-client';
 export { type ImageData, thumbHashToDataURL } from './image';
 export { getOperationName } from './client/operation-name';

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}

package/dist/core/index.js

@@ -73,7 +73,7 @@ export { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from './cart/cookie-config';
 // Auth route matching
 export { matchesRoute } from './auth/routes';
 // Auth cookie handlers (API route factories)
-export { createSetTokenHandler, createClearTokenHandler, createWhoamiHandler } from './auth/handlers';
+export { createSetTokenHandler, createClearTokenHandler, createWhoamiHandler, originAllowlistValidator, trustedForwardedHostValidator, } from './auth/handlers';
 // Auth token client (client-side fetch helpers)
 export { createAuthTokenClient } from './auth/token-client';
 // Image types (loaders removed — GraphQL returns ready-to-use CDN URLs with transform params)

package/dist/core/operations/cart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cart.d.ts","sourceRoot":"","sources":["../../../src/core/operations/cart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAuSH,eAAO,MAAM,UAAU,QAOrB,CAAC;AAMH,eAAO,MAAM,WAAW,QAWtB,CAAC;AAEH,eAAO,MAAM,cAAc,QAWzB,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,gBAAgB,QAW3B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAMH,eAAO,MAAM,yBAAyB,QAWpC,CAAC;AAEH,eAAO,MAAM,wBAAwB,QAWnC,CAAC;AAEH,eAAO,MAAM,2BAA2B,QAWtC,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,oBAAoB,QAW/B,CAAC;AAEH,eAAO,MAAM,qBAAqB,QAWhC,CAAC;AAEH,eAAO,MAAM,+BAA+B,QAW1C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAWxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QASzB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAoBtC,CAAC"}
+{"version":3,"file":"cart.d.ts","sourceRoot":"","sources":["../../../src/core/operations/cart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwSH,eAAO,MAAM,UAAU,QAOrB,CAAC;AAMH,eAAO,MAAM,WAAW,QAWtB,CAAC;AAEH,eAAO,MAAM,cAAc,QAWzB,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,gBAAgB,QAW3B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAMH,eAAO,MAAM,yBAAyB,QAWpC,CAAC;AAEH,eAAO,MAAM,wBAAwB,QAWnC,CAAC;AAEH,eAAO,MAAM,2BAA2B,QAWtC,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,oBAAoB,QAW/B,CAAC;AAEH,eAAO,MAAM,qBAAqB,QAWhC,CAAC;AAEH,eAAO,MAAM,+BAA+B,QAW1C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAWxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QASzB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAoBtC,CAAC"}

package/dist/core/operations/cart.js

@@ -229,6 +229,7 @@ const ORDER_FRAGMENT = `
   fragment Order on Order {
     id
     orderNumber
+    accessToken
     totals {
       total { ...Money }
       subtotal { ...Money }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "11.4.0",
+  "version": "11.5.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "sideEffects": false,