sfnext-authentication

Storefront Next Authentication

Authentication is server-only. One middleware (src/middlewares/auth.server.ts, registered in the middleware array of src/root.tsx) runs on every request: it reads cookies, validates or refreshes the SLAS access token, performs a guest login when nothing usable exists, and writes Set-Cookie. Tokens never reach the browser. Components only see a small non-sensitive slice through useAuth().

Read docs/README-AUTH.md in your project for the full reference; this skill is the task-oriented summary. Route modules use server loader/action only, never clientLoader/clientAction.

Request flow

1. Valid access token (JWT exp in the future): use it.
2. Expired access token with a refresh token: refresh, rewrite cc-at.
3. No tokens: guest login.
4. Registered shopper whose refresh fails: 307 to /login?returnUrl=<path>&error=session_expired (site/locale prefix included) and a fresh guest session is created in parallel. Guests are silently re-issued a guest session.
5. A SCAPI call returning 401 throws AuthTokenInvalidError; the middleware clears state, re-runs login/refresh and 307-redirects to the same URL. The short-lived cc-auth-recover cookie (30 s) prevents loops.

User type comes from the access-token JWT (registered tokens carry an rcid claim), not from which cookie exists. customerId is not a cookie; it is derived per request from the JWT.

Read auth on the server

import { getAuth } from '@/middlewares/auth.server';
import type { LoaderFunctionArgs } from 'react-router';

export async function loader({ context }: LoaderFunctionArgs) {
    const auth = getAuth(context); // full SessionData, server only
    const isRegistered = auth.userType === 'registered';
    return { isRegistered };       // never return auth.accessToken / refreshToken
}

Read auth in components

import { useAuth } from '@/providers/auth';

function AccountBadge() {
    const auth = useAuth(); // PublicSessionData | undefined
    return auth?.userType === 'registered' ? <span>Welcome back</span> : <SignInLink />;
}