@doswiftly/storefront-sdk 17.0.0 → 18.0.0

package/dist/react/providers/storefront-provider.d.ts

@@ -10,14 +10,18 @@
  * @example
  * ```tsx
  * // app/layout.tsx
- * import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+ * import { cookies } from 'next/headers';
+ * import { StorefrontProvider, AUTH_COOKIE_NAME } from '@doswiftly/storefront-sdk';
  *
  * export default async function RootLayout({ children }) {
- *   const shopData = await fetchShop();
+ *   const [shopData, cookieStore] = await Promise.all([fetchShop(), cookies()]);
+ *   const initialAccessToken = cookieStore.get(AUTH_COOKIE_NAME)?.value ?? null;
+ *
  *   return (
  *     <StorefrontProvider
  *       config={{ apiUrl: '...', shopSlug: '...' }}
  *       shopData={shopData}
+ *       initialAccessToken={initialAccessToken}
  *     >
  *       {children}
  *     </StorefrontProvider>
@@ -35,14 +39,58 @@ export interface StorefrontProviderProps extends StorefrontClientProviderProps {
      * eliminating the flash of "Sign In" while Zustand persist rehydrates from localStorage.
      *
      * Read from cookies() in a Server Component (layout.tsx) and pass here.
+     *
+     * Defaults to `!!initialAccessToken` when omitted (raw token implies authenticated).
+     * Pass `false` explicitly to override that default in edge cases (opt-out flow,
+     * recovery banner that holds a token without claiming auth state).
      */
     initialIsAuthenticated?: boolean;
+    /**
+     * Server-side token seed. See {@link CreateAuthStoreOptions.initialAccessToken}
+     * for full semantics and security guarantees (token kept in memory, never
+     * persisted). Wire up from your Server Component with `cookies()` + `AUTH_COOKIE_NAME`.
+     *
+     * @example
+     * ```tsx
+     * // app/layout.tsx
+     * import { cookies } from 'next/headers';
+     * import { AUTH_COOKIE_NAME } from '@doswiftly/storefront-sdk';
+     *
+     * const cookieStore = await cookies();
+     * const initialAccessToken = cookieStore.get(AUTH_COOKIE_NAME)?.value ?? null;
+     *
+     * <StorefrontProvider initialAccessToken={initialAccessToken} ...>
+     * ```
+     */
+    initialAccessToken?: string | null;
     /**
      * Server-side language hint — pass the URL locale from next-intl params.
      * Eliminates flash of wrong language on first render by initializing the
      * language store with the correct value from the server.
      */
     initialLanguage?: string;
+    /**
+     * Proactive session refresh. Defaults to ON in the browser and OFF on the
+     * server — you do NOT need to pass it. When active, the SDK renews the access
+     * token shortly before it expires so an active buyer is never logged out
+     * mid-session, and fires a global `session-expired` signal (subscribe via
+     * `useSessionExpired`) when the session can no longer be kept alive. Pass
+     * `autoRefresh={false}` to opt out and drive refreshing yourself.
+     */
+    autoRefresh?: boolean;
+    /**
+     * Base path of the SDK-BFF auth route handlers (default `/api/auth`). The
+     * proactive scheduler and the reactive-401 renewal post to `${authBasePath}/refresh`
+     * (same-origin), which rotates the refresh cookie server-side. Override only for
+     * non-standard mounts — it must match where `createStorefrontAuthRoute` is mounted.
+     */
+    authBasePath?: string;
+    /**
+     * Server-side session-expiry seed (ISO 8601) — typically the readable
+     * `session-expiry` cookie value read in a Server Component. Lets the refresh
+     * scheduler arm on the first render (cold start) without a whoami round-trip.
+     */
+    initialExpiresAt?: string | null;
 }
-export declare function StorefrontProvider({ children, config, middleware, shopData, initialIsAuthenticated, initialLanguage, }: StorefrontProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function StorefrontProvider({ children, config, middleware, shopData, initialIsAuthenticated, initialAccessToken, initialExpiresAt, initialLanguage, autoRefresh, authBasePath, }: StorefrontProviderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=storefront-provider.d.ts.map

package/dist/react/providers/storefront-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storefront-provider.d.ts","sourceRoot":"","sources":["../../../src/react/providers/storefront-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,OAAO,EAA4B,KAAK,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAC5G,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAMnF,MAAM,WAAW,uBAAwB,SAAQ,6BAA6B;IAC5E,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC5C;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,MAAM,EACN,UAAU,EACV,QAAQ,EACR,sBAAsB,EACtB,eAAe,GAChB,EAAE,uBAAuB,2CA+BzB"}
+{"version":3,"file":"storefront-provider.d.ts","sourceRoot":"","sources":["../../../src/react/providers/storefront-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AASH,OAAO,EAA4B,KAAK,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAC5G,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AASnF,MAAM,WAAW,uBAAwB,SAAQ,6BAA6B;IAC5E,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;;;OAgBG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,MAAM,EACN,UAAU,EACV,QAAQ,EACR,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,GACb,EAAE,uBAAuB,2CAwCzB"}

package/dist/react/providers/storefront-provider.js

@@ -10,14 +10,18 @@
  * @example
  * ```tsx
  * // app/layout.tsx
- * import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+ * import { cookies } from 'next/headers';
+ * import { StorefrontProvider, AUTH_COOKIE_NAME } from '@doswiftly/storefront-sdk';
  *
  * export default async function RootLayout({ children }) {
- *   const shopData = await fetchShop();
+ *   const [shopData, cookieStore] = await Promise.all([fetchShop(), cookies()]);
+ *   const initialAccessToken = cookieStore.get(AUTH_COOKIE_NAME)?.value ?? null;
+ *
  *   return (
  *     <StorefrontProvider
  *       config={{ apiUrl: '...', shopSlug: '...' }}
  *       shopData={shopData}
+ *       initialAccessToken={initialAccessToken}
  *     >
  *       {children}
  *     </StorefrontProvider>
@@ -38,10 +42,23 @@ import { LanguageProvider } from './language-provider';
 import { createBotProtectionManager } from '../../core/bot-protection/create-manager';
 import { BotProtectionContext } from '../bot-protection/bot-protection-context';
 import { BotProtectionWidget } from '../bot-protection/bot-protection-widget';
-export function StorefrontProvider({ children, config, middleware, shopData, initialIsAuthenticated, initialLanguage, }) {
-    const authStoreRef = useRef(createAuthStore(initialIsAuthenticated));
+import { createSessionExpiredEmitter } from '../../core/auth/session-events';
+import { SessionExpiredContext } from '../hooks/use-session-expired';
+import { useSessionRefresh } from '../hooks/use-session-refresh';
+export function StorefrontProvider({ children, config, middleware, shopData, initialIsAuthenticated, initialAccessToken, initialExpiresAt, initialLanguage, autoRefresh, authBasePath, }) {
+    const authStoreRef = useRef(createAuthStore({ initialIsAuthenticated, initialAccessToken, initialExpiresAt }));
     const currencyStoreRef = useRef(createCurrencyStore());
     const languageStoreRef = useRef(createLanguageStore(initialLanguage));
+    const sessionExpiredRef = useRef(createSessionExpiredEmitter());
     const botProtectionRef = useRef(shopData.botProtection ? createBotProtectionManager(shopData.botProtection) : null);
-    return (_jsx(AuthStoreContext.Provider, { value: authStoreRef.current, children: _jsx(CurrencyStoreContext.Provider, { value: currencyStoreRef.current, children: _jsx(LanguageStoreContext.Provider, { value: languageStoreRef.current, children: _jsx(StorefrontClientProvider, { config: config, middleware: middleware, botProtection: botProtectionRef.current, botProtectionOperations: shopData.botProtection?.protectedOperations, children: _jsx(BotProtectionContext.Provider, { value: { manager: botProtectionRef.current }, children: _jsx(CurrencyProvider, { shopData: shopData, children: _jsxs(LanguageProvider, { shopData: shopData, children: [_jsx(BotProtectionWidget, { manager: botProtectionRef.current }), children] }) }) }) }) }) }) }));
+    return (_jsx(AuthStoreContext.Provider, { value: authStoreRef.current, children: _jsx(CurrencyStoreContext.Provider, { value: currencyStoreRef.current, children: _jsx(LanguageStoreContext.Provider, { value: languageStoreRef.current, children: _jsx(StorefrontClientProvider, { config: config, middleware: middleware, botProtection: botProtectionRef.current, botProtectionOperations: shopData.botProtection?.protectedOperations, sessionExpiredEmitter: sessionExpiredRef.current, authBasePath: authBasePath, children: _jsx(BotProtectionContext.Provider, { value: { manager: botProtectionRef.current }, children: _jsx(CurrencyProvider, { shopData: shopData, children: _jsxs(LanguageProvider, { shopData: shopData, children: [_jsx(BotProtectionWidget, { manager: botProtectionRef.current }), _jsx(SessionRefreshRunner, { autoRefresh: autoRefresh, emitter: sessionExpiredRef.current }), _jsx(SessionExpiredContext.Provider, { value: sessionExpiredRef.current, children: children })] }) }) }) }) }) }) }));
+}
+/**
+ * Internal — drives the proactive refresh scheduler from inside the provider
+ * tree (so it can read the client + auth store via context). Renders nothing.
+ * The scheduler itself is a browser-only no-op on the server.
+ */
+function SessionRefreshRunner({ autoRefresh, emitter, }) {
+    useSessionRefresh({ enabled: autoRefresh, sessionExpiredEmitter: emitter });
+    return null;
 }

package/dist/react/server/create-storefront-auth-route.d.ts

@@ -0,0 +1,63 @@
+/**
+ * createStorefrontAuthRoute — SDK-BFF auth route handlers.
+ *
+ * Generates the four same-origin auth route handlers that live on the storefront
+ * domain (`/api/auth/[action]`): `login`, `refresh`, `logout` (POST) and `whoami`
+ * (GET). Each handler calls the backend `/storefront/auth/*` namespace
+ * server-to-server with `X-Shop-Slug` as a routing hint, owns the first-party
+ * httpOnly cookies on the storefront domain, and returns ONLY
+ * `{ accessToken, expiresAt[, customer] }` to JavaScript — the refresh token is
+ * read server-side and never reaches the browser's JS.
+ *
+ * This is the universal auth transport: the route handlers live on the
+ * storefront's own domain, so first-party cookies work identically on a platform
+ * subdomain, a custom domain, and off-platform hosting (e.g. Vercel) —
+ * independent of any reverse proxy in front. The backend never emits a
+ * `Set-Cookie` to a browser (tokens travel in the server-to-server response
+ * body); the BFF sets the cookies here.
+ *
+ * 0 runtime dependencies — pure Web API (`Request`/`Response`/`fetch`). No React,
+ * no `next/*`. Mount it in a Next.js (or any framework) route:
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/[action]/route.ts
+ * import { createStorefrontAuthRoute, trustedForwardedHostValidator } from '@doswiftly/storefront-sdk/react/server';
+ *
+ * export const { GET, POST } = createStorefrontAuthRoute({
+ *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+ *   shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+ *   isTrustedOrigin: trustedForwardedHostValidator, // when behind a reverse proxy that rewrites Host
+ * });
+ * ```
+ */
+import { type OriginValidator } from '../../core/auth/handlers';
+export interface StorefrontAuthRouteOptions {
+    /** Backend base URL (e.g. `https://api.doswiftly.pl`). The server-to-server namespace is `${apiUrl}/storefront/auth/*`. */
+    apiUrl: string;
+    /** Shop slug forwarded as the `X-Shop-Slug` routing hint (selects the tenant; never binds the rotation family). */
+    shopSlug: string;
+    /**
+     * CSRF defense-in-depth predicate. When the storefront runs behind a reverse
+     * proxy that rewrites/strips `Host` (Cloudflare Workers, Vercel, NGINX),
+     * pass `trustedForwardedHostValidator`. This is NOT the primary control — the
+     * backend's protocol controls (rotation + reuse-detection + rate-limit +
+     * possession-proof) are. See {@link OriginValidator}.
+     */
+    isTrustedOrigin?: OriginValidator | null;
+    /**
+     * Base path the route is mounted at (default `/api/auth`). The refresh cookie's
+     * `Path` is set to it so the cookie reaches both the refresh and logout routes
+     * (siblings under this base) but not GraphQL data traffic, which lives on a
+     * different path.
+     */
+    authBasePath?: string;
+    /** Custom fetch (tests, non-standard runtimes). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface StorefrontAuthRouteHandlers {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+}
+export declare function createStorefrontAuthRoute(options: StorefrontAuthRouteOptions): StorefrontAuthRouteHandlers;
+//# sourceMappingURL=create-storefront-auth-route.d.ts.map

package/dist/react/server/create-storefront-auth-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-storefront-auth-route.d.ts","sourceRoot":"","sources":["../../../src/react/server/create-storefront-auth-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAOlC,MAAM,WAAW,0BAA0B;IACzC,2HAA2H;IAC3H,MAAM,EAAE,MAAM,CAAC;IACf,mHAAmH;IACnH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,2BAA2B;IAC1C,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC/C;AAgDD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,2BAA2B,CA+L7B"}

package/dist/react/server/create-storefront-auth-route.js

@@ -0,0 +1,239 @@
+/**
+ * createStorefrontAuthRoute — SDK-BFF auth route handlers.
+ *
+ * Generates the four same-origin auth route handlers that live on the storefront
+ * domain (`/api/auth/[action]`): `login`, `refresh`, `logout` (POST) and `whoami`
+ * (GET). Each handler calls the backend `/storefront/auth/*` namespace
+ * server-to-server with `X-Shop-Slug` as a routing hint, owns the first-party
+ * httpOnly cookies on the storefront domain, and returns ONLY
+ * `{ accessToken, expiresAt[, customer] }` to JavaScript — the refresh token is
+ * read server-side and never reaches the browser's JS.
+ *
+ * This is the universal auth transport: the route handlers live on the
+ * storefront's own domain, so first-party cookies work identically on a platform
+ * subdomain, a custom domain, and off-platform hosting (e.g. Vercel) —
+ * independent of any reverse proxy in front. The backend never emits a
+ * `Set-Cookie` to a browser (tokens travel in the server-to-server response
+ * body); the BFF sets the cookies here.
+ *
+ * 0 runtime dependencies — pure Web API (`Request`/`Response`/`fetch`). No React,
+ * no `next/*`. Mount it in a Next.js (or any framework) route:
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/[action]/route.ts
+ * import { createStorefrontAuthRoute, trustedForwardedHostValidator } from '@doswiftly/storefront-sdk/react/server';
+ *
+ * export const { GET, POST } = createStorefrontAuthRoute({
+ *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+ *   shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+ *   isTrustedOrigin: trustedForwardedHostValidator, // when behind a reverse proxy that rewrites Host
+ * });
+ * ```
+ */
+import { validateOrigin, serializeCookie, } from '../../core/auth/handlers';
+import { AUTH_COOKIE_DEFAULTS, REFRESH_COOKIE_DEFAULTS, SESSION_EXPIRY_COOKIE_DEFAULTS, } from '../../core/auth/cookie-config';
+const DEFAULT_AUTH_BASE_PATH = '/api/auth';
+function jsonResponse(body, status = 200, extraHeaders) {
+    const headers = extraHeaders ?? new Headers();
+    headers.set('content-type', 'application/json');
+    return new Response(JSON.stringify(body), { status, headers });
+}
+/** Last non-empty path segment — the `[action]` of `/api/auth/{action}`. */
+function resolveAction(request) {
+    const segments = new URL(request.url).pathname.split('/').filter(Boolean);
+    return segments[segments.length - 1] ?? '';
+}
+/** Read a single cookie value server-side (decoded). Cookie names are fixed constants. */
+function readCookie(request, name) {
+    const header = request.headers.get('cookie') ?? '';
+    const match = header.match(new RegExp(`(?:^|; )${name}=([^;]+)`));
+    return match ? decodeURIComponent(match[1]) : null;
+}
+/** Access-token cookie lifetime fallback (seconds) when `expiresAt` can't be parsed (rare backend error). */
+const ACCESS_FALLBACK_MAX_AGE_SECONDS = 60 * 30; // 30 minutes — a short, access-shaped fallback
+/** Cookie `Max-Age` (seconds) until an absolute ISO expiry; clamped at 0; falls back when unparseable. */
+function maxAgeFromExpiry(expiresAt) {
+    const ms = Date.parse(expiresAt);
+    if (Number.isNaN(ms))
+        return ACCESS_FALLBACK_MAX_AGE_SECONDS;
+    return Math.max(0, Math.floor((ms - Date.now()) / 1000));
+}
+export function createStorefrontAuthRoute(options) {
+    const apiBase = options.apiUrl.replace(/\/$/, '');
+    const shopSlug = options.shopSlug;
+    const isTrustedOrigin = options.isTrustedOrigin ?? null;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const authBasePath = (options.authBasePath ?? DEFAULT_AUTH_BASE_PATH).replace(/\/$/, '');
+    const backendUrl = (action) => `${apiBase}/storefront/auth/${action}`;
+    const backendHeaders = (extra) => ({
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        'X-Shop-Slug': shopSlug,
+        ...extra,
+    });
+    // ---- first-party cookie specs (host-only) ----
+    // The refresh cookie is scoped to the route's auth base (NOT `${authBasePath}/refresh`)
+    // so the sibling logout route also receives it and can revoke the family — a
+    // narrower path is not sent to a sibling endpoint.
+    const ACCESS_COOKIE = { ...AUTH_COOKIE_DEFAULTS };
+    const REFRESH_COOKIE = { ...REFRESH_COOKIE_DEFAULTS, path: authBasePath };
+    const EXPIRY_COOKIE = { ...SESSION_EXPIRY_COOKIE_DEFAULTS };
+    const buildCookie = (spec, value, maxAge) => serializeCookie(spec.name, value, {
+        maxAge,
+        path: spec.path,
+        sameSite: spec.sameSite,
+        secure: spec.secure,
+        httpOnly: spec.httpOnly,
+    });
+    // Expire all three cookies, each at the SAME path it was set with (a mismatched
+    // path would not delete the cookie).
+    const clearSetCookies = () => [ACCESS_COOKIE, REFRESH_COOKIE, EXPIRY_COOKIE].map((spec) => buildCookie(spec, '', 0));
+    /**
+     * Set the first-party cookies from a token pair and return the body the browser
+     * receives — access token + expiry (+ customer), NEVER the refresh token. The
+     * refresh cookie is only (re)written when the backend issued a new token: a
+     * `null` refresh means a grace-window hit or a guest, so the current cookie is
+     * kept untouched.
+     */
+    function tokensResponse(data) {
+        const headers = new Headers();
+        headers.append('Set-Cookie', buildCookie(ACCESS_COOKIE, data.access, maxAgeFromExpiry(data.expiresAt)));
+        // A null refresh means a grace-window hit or a guest — keep the current refresh cookie.
+        if (data.refresh)
+            headers.append('Set-Cookie', buildCookie(REFRESH_COOKIE, data.refresh, REFRESH_COOKIE.maxAge));
+        // The expiry hint outlives the access token (its own 30-day lifetime) so a
+        // returning visitor's cold start can recover even after the access token lapsed.
+        headers.append('Set-Cookie', buildCookie(EXPIRY_COOKIE, data.expiresAt, EXPIRY_COOKIE.maxAge));
+        const jsBody = { accessToken: data.access, expiresAt: data.expiresAt };
+        if (data.customer != null)
+            jsBody.customer = data.customer;
+        return jsonResponse(jsBody, 200, headers);
+    }
+    /**
+     * Forward a backend error to the browser without setting cookies. The backend
+     * body is already localized and free of platform internals, so it is passed
+     * through verbatim — the SDK reacts to the status (401 → SESSION_EXPIRED).
+     */
+    async function passthroughError(backendRes) {
+        const text = await backendRes.text();
+        return new Response(text, {
+            status: backendRes.status,
+            headers: { 'content-type': backendRes.headers.get('content-type') ?? 'application/json' },
+        });
+    }
+    // ---- action handlers ----
+    async function handleLogin(request) {
+        const originError = await validateOrigin(request, { isTrustedOrigin });
+        if (originError)
+            return originError;
+        let body;
+        try {
+            body = await request.json();
+        }
+        catch {
+            return jsonResponse({ error: 'Invalid JSON body' }, 400);
+        }
+        const backendRes = await fetchImpl(backendUrl('login'), {
+            method: 'POST',
+            headers: backendHeaders(),
+            body: JSON.stringify({ email: body.email, password: body.password }),
+        });
+        if (!backendRes.ok)
+            return passthroughError(backendRes);
+        const data = (await backendRes.json());
+        return tokensResponse(data);
+    }
+    async function handleRefresh(request) {
+        const originError = await validateOrigin(request, { isTrustedOrigin });
+        if (originError)
+            return originError;
+        const refreshToken = readCookie(request, REFRESH_COOKIE_DEFAULTS.name);
+        if (!refreshToken) {
+            // No first-party refresh cookie → nothing to rotate. Fail-closed (401) so the
+            // SDK surfaces SESSION_EXPIRED without a wasted server-to-server round-trip.
+            return jsonResponse({ error: 'No refresh session' }, 401);
+        }
+        const backendRes = await fetchImpl(backendUrl('refresh'), {
+            method: 'POST',
+            headers: backendHeaders(),
+            body: JSON.stringify({ refresh: refreshToken }),
+        });
+        if (!backendRes.ok)
+            return passthroughError(backendRes);
+        const data = (await backendRes.json());
+        return tokensResponse(data);
+    }
+    async function handleLogout(request) {
+        const originError = await validateOrigin(request, { isTrustedOrigin });
+        if (originError)
+            return originError;
+        const refreshToken = readCookie(request, REFRESH_COOKIE_DEFAULTS.name);
+        if (refreshToken) {
+            // Best-effort server-to-server revoke (possession-proof + family revoke happen backend-side).
+            // A failure must not block clearing the local cookies.
+            try {
+                await fetchImpl(backendUrl('logout'), {
+                    method: 'POST',
+                    headers: backendHeaders(),
+                    body: JSON.stringify({ refresh: refreshToken }),
+                });
+            }
+            catch {
+                // swallow — cookies are cleared regardless
+            }
+        }
+        const headers = new Headers();
+        for (const cookie of clearSetCookies())
+            headers.append('Set-Cookie', cookie);
+        return jsonResponse({ success: true }, 200, headers);
+    }
+    async function handleWhoami(request) {
+        // GET is CSRF-safe; browsers omit Origin for same-origin GET — allow missing.
+        const originError = await validateOrigin(request, { allowMissingOrigin: true, isTrustedOrigin });
+        if (originError)
+            return originError;
+        const accessToken = readCookie(request, AUTH_COOKIE_DEFAULTS.name);
+        const anon = { isAuthenticated: false, customer: null, expiresAt: null };
+        if (!accessToken)
+            return jsonResponse(anon);
+        let backendRes;
+        try {
+            backendRes = await fetchImpl(backendUrl('whoami'), {
+                method: 'GET',
+                headers: backendHeaders({ Authorization: `Bearer ${accessToken}` }),
+            });
+        }
+        catch {
+            return jsonResponse(anon);
+        }
+        if (!backendRes.ok)
+            return jsonResponse(anon);
+        const data = (await backendRes.json());
+        return jsonResponse({
+            isAuthenticated: !!data.isAuthenticated,
+            customer: data.customer ?? null,
+            expiresAt: data.expiresAt ?? null,
+        });
+    }
+    const POST = async (request) => {
+        const action = resolveAction(request);
+        switch (action) {
+            case 'login':
+                return handleLogin(request);
+            case 'refresh':
+                return handleRefresh(request);
+            case 'logout':
+                return handleLogout(request);
+            default:
+                return jsonResponse({ error: `Unknown auth action: ${action}` }, 404);
+        }
+    };
+    const GET = async (request) => {
+        const action = resolveAction(request);
+        if (action === 'whoami')
+            return handleWhoami(request);
+        return jsonResponse({ error: `Unknown auth action: ${action}` }, 404);
+    };
+    return { GET, POST };
+}

package/dist/react/server/get-initial-auth.d.ts

@@ -0,0 +1,57 @@
+/**
+ * getInitialAuth — server-only initial auth seed from the first-party cookies.
+ *
+ * Reads the cookies the SDK-BFF route handlers (`createStorefrontAuthRoute`) set
+ * on the storefront domain and maps them to the values `StorefrontProvider`
+ * expects, so the very first render already knows the buyer is signed in
+ * (no flash of signed-out UI) and the proactive scheduler can arm immediately on
+ * a cold start — both without a whoami round-trip.
+ *
+ * The access token is seeded into the in-memory auth store only — it is NEVER
+ * persisted to storage (the store's `partialize` excludes it, XSS hardening). The
+ * customer profile is hydrated client-side afterwards (e.g. via the same-origin
+ * whoami route), so it is intentionally not part of this cookie-only cold-start seed.
+ *
+ * Server-only — dynamically imports `next/headers`, so importing this module's
+ * sibling (`getStorefrontClient`) in a non-Next runtime stays unaffected.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx (Server Component)
+ * import { getInitialAuth } from '@doswiftly/storefront-sdk/react/server';
+ * import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+ *
+ * export default async function RootLayout({ children }) {
+ *   const { isAuthenticated, accessToken, expiresAt } = await getInitialAuth();
+ *   return (
+ *     <StorefrontProvider
+ *       config={{ apiUrl: '...', shopSlug: '...' }}
+ *       shopData={shopData}
+ *       initialIsAuthenticated={isAuthenticated}
+ *       initialAccessToken={accessToken}
+ *       initialExpiresAt={expiresAt}
+ *     >
+ *       {children}
+ *     </StorefrontProvider>
+ *   );
+ * }
+ * ```
+ */
+/**
+ * Cold-start auth seed read from the first-party cookies. Maps 1:1 to the
+ * `StorefrontProvider` props `initialIsAuthenticated` / `initialAccessToken` /
+ * `initialExpiresAt` (and to `CreateAuthStoreOptions`).
+ */
+export interface InitialAuth {
+    /**
+     * `true` when an access token OR the longer-lived session-expiry hint is present
+     * — drives the no-flash signed-in render even after the short access token lapsed.
+     */
+    isAuthenticated: boolean;
+    /** Raw access token from the httpOnly cookie — seeded into memory only, never persisted to storage. */
+    accessToken: string | null;
+    /** Absolute session expiry (ISO 8601) from the readable cookie, or null when unknown. */
+    expiresAt: string | null;
+}
+export declare function getInitialAuth(): Promise<InitialAuth>;
+//# sourceMappingURL=get-initial-auth.d.ts.map

package/dist/react/server/get-initial-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-initial-auth.d.ts","sourceRoot":"","sources":["../../../src/react/server/get-initial-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB,uGAAuG;IACvG,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yFAAyF;IACzF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAc3D"}

package/dist/react/server/get-initial-auth.js

@@ -0,0 +1,55 @@
+/**
+ * getInitialAuth — server-only initial auth seed from the first-party cookies.
+ *
+ * Reads the cookies the SDK-BFF route handlers (`createStorefrontAuthRoute`) set
+ * on the storefront domain and maps them to the values `StorefrontProvider`
+ * expects, so the very first render already knows the buyer is signed in
+ * (no flash of signed-out UI) and the proactive scheduler can arm immediately on
+ * a cold start — both without a whoami round-trip.
+ *
+ * The access token is seeded into the in-memory auth store only — it is NEVER
+ * persisted to storage (the store's `partialize` excludes it, XSS hardening). The
+ * customer profile is hydrated client-side afterwards (e.g. via the same-origin
+ * whoami route), so it is intentionally not part of this cookie-only cold-start seed.
+ *
+ * Server-only — dynamically imports `next/headers`, so importing this module's
+ * sibling (`getStorefrontClient`) in a non-Next runtime stays unaffected.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx (Server Component)
+ * import { getInitialAuth } from '@doswiftly/storefront-sdk/react/server';
+ * import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+ *
+ * export default async function RootLayout({ children }) {
+ *   const { isAuthenticated, accessToken, expiresAt } = await getInitialAuth();
+ *   return (
+ *     <StorefrontProvider
+ *       config={{ apiUrl: '...', shopSlug: '...' }}
+ *       shopData={shopData}
+ *       initialIsAuthenticated={isAuthenticated}
+ *       initialAccessToken={accessToken}
+ *       initialExpiresAt={expiresAt}
+ *     >
+ *       {children}
+ *     </StorefrontProvider>
+ *   );
+ * }
+ * ```
+ */
+import { AUTH_COOKIE_NAME, SESSION_EXPIRY_COOKIE_NAME } from '../../core/auth/cookie-config';
+export async function getInitialAuth() {
+    const { cookies } = await import('next/headers');
+    const store = await cookies();
+    const accessToken = store.get(AUTH_COOKIE_NAME)?.value ?? null;
+    const expiresAt = store.get(SESSION_EXPIRY_COOKIE_NAME)?.value ?? null;
+    return {
+        // Authenticated when EITHER cookie is present: a returning visitor whose short
+        // access token already lapsed still carries the longer-lived session-expiry
+        // hint, so the app renders signed-in and the scheduler recovers the session (a
+        // past expiry triggers an immediate refresh) instead of flashing signed-out.
+        isAuthenticated: !!accessToken || !!expiresAt,
+        accessToken,
+        expiresAt,
+    };
+}

package/dist/react/server/index.d.ts

@@ -1,2 +1,5 @@
 export { getStorefrontClient, type ServerClientOptions } from './get-storefront-client';
+export { createStorefrontAuthRoute, type StorefrontAuthRouteOptions, type StorefrontAuthRouteHandlers, } from './create-storefront-auth-route';
+export { getInitialAuth, type InitialAuth } from './get-initial-auth';
+export { trustedForwardedHostValidator, originAllowlistValidator, type OriginValidator, type OriginValidatorContext, } from '../../core/auth/handlers';
 //# sourceMappingURL=index.d.ts.map

package/dist/react/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGxF,OAAO,EACL,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,GACjC,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtE,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,0BAA0B,CAAC"}

package/dist/react/server/index.js

@@ -1 +1,7 @@
 export { getStorefrontClient } from './get-storefront-client';
+// SDK-BFF auth route handlers — mount at /api/auth/[action]/route.ts.
+export { createStorefrontAuthRoute, } from './create-storefront-auth-route';
+// Server-only cold-start auth seed from the first-party cookies.
+export { getInitialAuth } from './get-initial-auth';
+// Origin validators — wire CSRF defense-in-depth on the route handlers from a single import.
+export { trustedForwardedHostValidator, originAllowlistValidator, } from '../../core/auth/handlers';

package/dist/react/stores/auth.store.d.ts

@@ -7,6 +7,12 @@
  *
  * httpOnly cookie is managed separately (for SSR/middleware).
  */
+/**
+ * localStorage key for the persisted auth slice (customer + isAuthenticated only —
+ * accessToken is excluded by `partialize`, XSS hardening). Exported so tests and
+ * future migrations can reference a single source of truth.
+ */
+export declare const AUTH_STORAGE_KEY = "auth-storage";
 export interface CustomerInfo {
     id: string;
     email: string;
@@ -17,14 +23,52 @@ export interface CustomerInfo {
 export interface AuthStore {
     customer: CustomerInfo | null;
     accessToken: string | null;
+    /**
+     * Absolute session expiry (ISO 8601) from the latest authoritative response
+     * (login / refresh / whoami), or null when unknown. Runtime-only — NEVER
+     * persisted to localStorage (the readable `session-expiry` cookie is the
+     * cold-start hint; this value is re-synced from the backend on each response).
+     */
+    expiresAt: string | null;
     isAuthenticated: boolean;
     isLoading: boolean;
-    setAuth: (customer: CustomerInfo, accessToken: string) => void;
+    setAuth: (customer: CustomerInfo | null, accessToken: string, expiresAt?: string | null) => void;
     clearAuth: () => void;
+    /**
+     * Sync just the session expiry from an authoritative backend response
+     * (whoami / refresh) without touching the token or customer — used when the
+     * locally-known expiry diverges from the backend's view.
+     */
+    setExpiresAt: (expiresAt: string | null) => void;
     updateCustomer: (updates: Partial<CustomerInfo>) => void;
     setLoading: (isLoading: boolean) => void;
 }
-export declare const createAuthStore: (initialIsAuthenticated?: boolean) => Omit<import("zustand").StoreApi<AuthStore>, "setState" | "persist"> & {
+export interface CreateAuthStoreOptions {
+    /**
+     * Server-side auth hint — set to `true` when httpOnly auth cookie exists.
+     * Eliminates flash of "Sign In" while Zustand persist rehydrates from localStorage.
+     * Defaults to `!!initialAccessToken` when omitted (raw token implies authenticated).
+     */
+    initialIsAuthenticated?: boolean;
+    /**
+     * Server-side token seed — raw JWT from httpOnly cookie value, env var (dev seed),
+     * SSO redirect parameter, or magic link callback. Injected into `accessToken` so
+     * `authMiddleware` adds `Authorization: Bearer ...` from the very first request
+     * (no `/api/auth/whoami` round-trip required).
+     *
+     * Security: token lives only in memory (RAM) — never written to localStorage
+     * (XSS hardening, v3 persist `partialize` excludes `accessToken`).
+     */
+    initialAccessToken?: string | null;
+    /**
+     * Server-side session-expiry seed (ISO 8601) — typically the readable
+     * `session-expiry` cookie value read in a Server Component. Lets the proactive
+     * refresh scheduler arm on the very first render (cold start) without waiting
+     * for a whoami round-trip. Runtime-only, never persisted.
+     */
+    initialExpiresAt?: string | null;
+}
+export declare const createAuthStore: (options?: CreateAuthStoreOptions) => Omit<import("zustand").StoreApi<AuthStore>, "setState" | "persist"> & {
     setState(partial: AuthStore | Partial<AuthStore> | ((state: AuthStore) => AuthStore | Partial<AuthStore>), replace?: false | undefined): unknown;
     setState(state: AuthStore | ((state: AuthStore) => AuthStore), replace: true): unknown;
     persist: {