@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/content/guidance/storefront-next/sfnext-analytics-consent/references/CUSTOM-ADAPTER.md

@@ -0,0 +1,49 @@
+# Writing a custom engagement adapter
+
+Verify the types in `src/lib/adapters/engagement/types.ts` in your project first.
+
+## 1. Implement
+
+```ts
+// src/lib/adapters/engagement/my-adapter.ts
+import { hasConsent, type EngagementAdapter, type EngagementAdapterConfig } from '@/lib/adapters';
+import type { AnalyticsEvent, ConsentPreferences, EventSiteInfo } from '@salesforce/storefront-next-runtime/events';
+
+export function createMyAdapter(config: EngagementAdapterConfig): EngagementAdapter {
+  return {
+    name: 'my-adapter',
+    sendEvent: async (event: AnalyticsEvent, siteInfo?: EventSiteInfo, consentPreferences?: ConsentPreferences) => {
+      if (!hasConsent(config.consentCategory, consentPreferences)) return;
+      if (!config.eventToggles[event.eventType]) return;
+      navigator.sendBeacon('https://example.com/collect', JSON.stringify({ event, siteInfo }));
+    },
+  };
+}
+```
+
+`hasConsent(category, prefs)` is in `src/lib/adapters/engagement/utils.ts`; read it for the behavior when `category` is undefined.
+
+## 2. Register
+
+In `src/lib/adapters/engagement/register.ts`, inside `initializeEngagementAdapters(appConfig)`:
+
+```ts
+const mine = appConfig?.engagement?.adapters?.myAdapter;
+if (mine?.enabled) {
+  addAdapter('my-adapter', createMyAdapter({ consentCategory: mine.consentCategory, eventToggles: mine.eventToggles || {}, ...mine }));
+}
+```
+
+Follow the try/catch and logger pattern used for the built-in adapters.
+
+## 3. Configure
+
+Add `engagement.adapters.myAdapter: { enabled: true, consentCategory: 'marketing', eventToggles: { view_page: true } }` in `config.server.ts`. Add `'marketing'` (or your category) to `trackingConsent.consentCategories`.
+
+## 4. Allow the endpoint in CSP
+
+Beacons to a new host need `connect-src` (and script hosts need `script-src`). See `storefront-next:sfnext-security`.
+
+## 5. Test
+
+Unit-test the adapter with and without consent (see the `*.test.ts` files beside the built-in adapters for the pattern).

package/content/guidance/storefront-next/sfnext-authentication/SKILL.md

@@ -1,120 +1,127 @@
 ---
 name: sfnext-authentication
-description: Implement authentication in Storefront Next using split-cookie architecture, SLAS tokens, and auth middleware. Use when accessing user identity in loaders, detecting guest vs registered users, using getAuth or useAuth, or understanding session management and token refresh.
+description: >-
+  Work with Storefront Next's server-only authentication and session architecture (SLAS guest/registered tokens, httpOnly cookies, auth.server.ts middleware). Use for getAuth, useAuth, updateAuth, destroyAuth, protecting account routes, login/logout actions, guest-to-registered basket/wishlist merge, "session expired" redirects, 401 recovery loops, cc-at/cc-nx/usid/dwsid cookies, cookie names or expiry, passwordless login, social login, OTP email verification, passkeys, guest order lookup, or refresh-token lifetime settings. Do not use for Turnstile, CSP headers or cookie-domain config (use `storefront-next:sfnext-security`), calling SCAPI clients (use `storefront-next:sfnext-scapi`), or sharing sessions with SFRA (use `storefront-next:sfnext-hybrid-storefronts`).
 ---
 
-# Authentication Skill
+# Storefront Next Authentication
 
-This skill covers Storefront Next's split-cookie authentication architecture with SLAS (Shopper Login and API Access Service).
+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()`.
 
-## Overview
+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`.
 
-Storefront Next uses a split-cookie architecture separating server and client auth concerns:
+## Request flow
 
-- **Server middleware** (`auth.server.ts`) — Manages SLAS tokens, writes cookies, handles token refresh
-- **React Context** (`AuthProvider`) — Provides public session data (non-sensitive fields) to components via `useAuth()`
+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.
 
-## Cookie Design
+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.
 
-| Cookie | Purpose | User Type | Expiry | HttpOnly |
-|--------|---------|-----------|--------|----------|
-| `cc-nx-g` | Guest refresh token | Guest | 30 days | No |
-| `cc-nx` | Registered refresh token | Registered | 90 days | No |
-| `cc-at` | Access token | Both | 30 min | No |
-| `usid` | User session ID | Both | Matches refresh | No |
-| `customerId` | Customer ID | Registered | Matches refresh | No |
-
-**Key points:**
-- Only ONE refresh token exists at a time (guest OR registered, never both)
-- User type is derived from which refresh token is present
-- Cookies are auto-namespaced with `siteId`
-- Tokens auto-refresh when expired
-
-## Usage in Loaders/Actions
+## Read auth on the server
 
 ```typescript
 import { getAuth } from '@/middlewares/auth.server';
+import type { LoaderFunctionArgs } from 'react-router';
 
-export function loader({ context }: LoaderFunctionArgs) {
-    const auth = getAuth(context);
-
-    const { accessToken, customerId, userType } = auth;
-    const isGuest = userType === 'guest';
-    const isRegistered = userType === 'registered';
-
-    return { isGuest, customerId };
+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
 }
 ```
 
-## Usage in Components
+## Read auth in components
 
-```typescript
+```tsx
 import { useAuth } from '@/providers/auth';
 
-export function MyComponent() {
-    const auth = useAuth();
-
-    if (auth?.userType === 'guest') {
-        return <LoginPrompt />;
-    }
-
-    return <div>Welcome, customer {auth?.customerId}</div>;
+function AccountBadge() {
+    const auth = useAuth(); // PublicSessionData | undefined
+    return auth?.userType === 'registered' ? <span>Welcome back</span> : <SignInLink />;
 }
 ```
 
-## Common Patterns
+`PublicSessionData` is exactly `customerId`, `userType`, `usid`, `encUserId`, `trackingConsent`. The root loader derives it with `getPublicSessionData` (from `@/middlewares/auth.utils`) and passes it to `AuthProvider`; there is no client `getAuth`.
+
+## Protect a route
 
-### Protected Routes
+Branch inside the server loader. Prefer the existing account layout (`src/routes/_app.account.tsx`) for anything under `/account` instead of adding per-route checks.
 
 ```typescript
-export function loader({ context }: LoaderFunctionArgs) {
-    const auth = getAuth(context);
+import { redirect } from 'react-router';
+import { getAuth } from '@/middlewares/auth.server';
+import { buildUrlFromContext } from '@/lib/url.server';
+import { routes } from '@/route-paths';
 
-    if (auth.userType === 'guest') {
-        throw redirect('/login');
+export async function loader({ context }: LoaderFunctionArgs) {
+    if (getAuth(context).userType !== 'registered') {
+        throw redirect(buildUrlFromContext(routes.login, context)); // keeps site/locale prefix
     }
-
-    const clients = createApiClients(context);
-    return {
-        orders: clients.shopperOrders.getOrders({
-            params: { path: { customerId: auth.customerId } }
-        }).then(({ data }) => data),
-    };
+    // ...
 }
 ```
 
-### Conditional Data Loading
+## Log in and out
+
+Never write auth cookies yourself. Use the helpers exported from `@/middlewares/auth.server`:
 
 ```typescript
-export function loader({ context }: LoaderFunctionArgs) {
-    const auth = getAuth(context);
-    const clients = createApiClients(context);
-
-    const base = {
-        products: clients.shopperProducts.getProducts({...}).then(({ data }) => data),
-    };
-
-    if (auth.userType === 'registered') {
-        return {
-            ...base,
-            wishlist: clients.shopperCustomers.getWishlist({...}).then(({ data }) => data),
-        };
-    }
+import { loginRegisteredUser, updateAuth } from '@/middlewares/auth.server';
 
-    return base;
+export async function action({ request, context }: ActionFunctionArgs) {
+    const form = await request.formData();
+    const tokens = await loginRegisteredUser(context, String(form.get('email')), String(form.get('password')));
+    updateAuth(context, tokens);            // re-derives userType/customerId/usid, swaps cc-nx-g for cc-nx
+    return redirect('/account');
 }
 ```
 
-## Troubleshooting
+`updateAuth` accepts a SLAS token response or an updater function (`updateAuth(context, (cur) => ({ ...cur, codeVerifier }))`). Logout: `destroyAuth(context)` clears every auth cookie on the response; the shipped `src/routes/_empty.logout.ts` also calls `clients.auth.logout` and `destroyBasket`. Prefer `src/lib/api/auth/standard-login.server.ts` and `social-login.server.ts` over hand-rolled flows: they already handle the merge below.
+
+Other exported helpers: `loginGuestUser`, `refreshAccessToken`, `authorizePasswordless`, `getPasswordLessAccessToken`, `getPasswordResetToken`, `resetPasswordWithToken`, `requestOtp`, `verifyOtp`, `flashAuth(context, message)` (clear session plus an error message), `clearInvalidSessionAndRestoreGuest(context)` (deleted customer or corrupted session).
+
+## Guest to registered merge
+
+`customerId` changes from the guest `gcid` to the registered `rcid` at the token swap, and SCAPI rejects the guest id under the registered token. So: snapshot guest-owned data (wishlist) **before** the swap, then `mergeBasket` and `mergeWishlist` **after**. `src/lib/api/auth/social-login.server.ts` is the reference implementation. `dw_dnt` tracking consent is preserved across the swap.
+
+## Common SCAPI calls for account data
+
+These are real operations: `clients.shopperCustomers.getCustomerOrders`, `getCustomerProductLists` (wishlists), `getCustomer`. Use the existing helpers (`src/lib/api/order.server.ts`, `wishlist.server.ts`, `customer.server.ts`) rather than calling clients directly. Client setup and the `@/lib/api-clients.server` import are covered in `storefront-next:sfnext-scapi`.
+
+## Configuration
+
+| Setting | Where |
+|---|---|
+| Refresh-token lifetime | `PUBLIC_COMMERCE_API_GUEST_REFRESH_TOKEN_EXPIRY_SECONDS` (max 30 days), `PUBLIC_COMMERCE_API_REGISTERED_REFRESH_TOKEN_EXPIRY_SECONDS` (max 90 days) |
+| Feature flags | `features.passwordlessLogin`, `features.passkey`, `features.socialLogin`, `features.otpRequest`, `auth.otpLength` in `config.server.ts` |
+| Private SLAS client | `commerce.api.privateKeyEnabled` (required for passwordless / OTP) |
+| Cookie domain | `app.cookies.domain` (see `storefront-next:sfnext-security`) |
+
+`secure` on cookies is only set on deployed (HTTPS) environments; local `pnpm dev` over `http://localhost` writes non-secure cookies so Safari keeps them.
+
+## Pitfalls
+
+- Reading tokens with `document.cookie`: impossible by design (httpOnly). Use `useAuth()` or loader data.
+- Returning `getAuth(context)` from a loader leaks tokens into the page. Return only derived values.
+- Refreshing tokens manually in routes: the middleware already does it.
+- Logging `accessToken` or `refreshToken`: never.
+- Changing the cookie domain on a live site leaves old host-only cookies shadowing new ones; roll out in a quiet window.
+- A loop of redirects to `/login?error=session_expired` usually means refresh tokens are being rejected (SLAS client config, or cookie domain mismatch between hosts).
+
+## References
 
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| `auth` is undefined | Missing auth middleware | Ensure `auth.server.ts` middleware is configured |
-| Always guest | Refresh token expired | Check cookie expiry; SLAS auto-refreshes |
-| Token errors in SCAPI | Stale access token | Tokens auto-refresh; check SLAS client configuration |
+- [COOKIES.md](references/COOKIES.md): full cookie inventory, namespacing, expiry, hints.
+- [LOGIN-FLOWS.md](references/LOGIN-FLOWS.md): passwordless, social, OTP, passkeys, password reset, guest order lookup, email cartridge prerequisites.
+- In your project: `docs/README-AUTH.md`, `docs/README-EMAIL-VERIFICATION.md`, `docs/README-GUEST-ORDER-LOOKUP.md`, `docs/README-EMAIL-CARTRIDGE.md`.
 
 ## Related Skills
 
-- `storefront-next:sfnext-data-fetching` - Using auth context in loader functions
-- `storefront-next:sfnext-configuration` - SLAS client configuration
-- `storefront-next:sfnext-hybrid-storefronts` - Session bridging with SFRA
+- `storefront-next:sfnext-security` - Turnstile bot protection, CSP for social providers, cookie domain
+- `storefront-next:sfnext-scapi` - SCAPI clients and custom APIs
+- `storefront-next:sfnext-hybrid-storefronts` - shared `dwsid` session bridge with SFRA
+- `storefront-next:sfnext-analytics-consent` - `dw_dnt` tracking consent
+- `storefront-next:sfnext-configuration` - `config.server.ts` and `PUBLIC__` overrides
+- `b2c-cli:b2c-slas` - manage SLAS clients and scopes

package/content/guidance/storefront-next/sfnext-authentication/references/COOKIES.md

@@ -0,0 +1,39 @@
+# Storefront Next Auth Cookies
+
+Source of truth in your project: `docs/README-AUTH.md` (Cookie Architecture) and the constants in `src/middlewares/auth.utils.ts`. Cookie serialization lives in `src/lib/cookie-utils.server.ts` (`getCookieConfig`, `createCookie`).
+
+All auth cookies are `HttpOnly`, so client JavaScript cannot read them. The only exception is `dw_dnt` (the consent banner reads it). The browser still sends every cookie on each request, which is what lets the server middleware and a hybrid B2C Commerce (SFRA) storefront read them.
+
+| Cookie | Purpose | User type | Lifetime | Notes |
+|---|---|---|---|---|
+| `cc-nx-g` | Guest refresh token | Guest | Guest refresh expiry (max 30 days) | Mutually exclusive with `cc-nx` |
+| `cc-nx` | Registered refresh token | Registered | Registered refresh expiry (max 90 days) | Written on login; deletes `cc-nx-g` |
+| `cc-at` | Access token | Both | JWT `exp` | Refreshed by middleware |
+| `usid` | SLAS user session id (JWT `sub`) | Both | Refresh expiry, else access expiry | Keep httpOnly; never expose to JS |
+| `enc_user_id` | Encoded user id | Registered | Refresh expiry | Needed for some SLAS calls |
+| `idp_access_token` | Social-login IDP access token | Both | Access expiry | Social login only |
+| `id_token` | OIDC ID token | Both | Access expiry | |
+| `idp_refresh_token` | Social-login IDP refresh token | Both | Refresh expiry | |
+| `dw_dnt` | Tracking consent (value is the `TrackingConsent` enum) | Both | Session | Not httpOnly, not site-namespaced; cookie is the source of truth |
+| `dwsid` | B2C Commerce session id (hybrid bridge) | Both | Session | Not site-namespaced; taken from the SLAS `Set-Cookie` header |
+| `cc-cv` | PKCE code verifier | Both | 5 minutes | Social login flow |
+| `cc-auth-recover` | 401 / session-expiry redirect loop guard | Both | 30 seconds | Set by middleware, cleared on follow-up request |
+
+Related non-auth cookies you may see: `cc-tv_<siteId>` (Turnstile attestation, 30 min, see `storefront-next:sfnext-security`), `glo_order_*` / `glo_cd_*` (guest order lookup), site-context cookies for site, locale and currency, a JS-readable `__sfdc_usertype_<siteId>` hint that carries only guest/registered so cached app-shell HTML can restore header state, and a JS-readable basket snapshot cookie. The hint and basket cookies never carry tokens.
+
+## Rules
+
+- **Namespacing.** Cookies are suffixed with the site id (for example `cc-nx_RefArch`) so multi-site deployments do not collide. `dwsid` and `dw_dnt` are deliberately excluded (`COOKIE_NAMESPACE_EXCLUSIONS`) so B2C Commerce and external scripts can read them.
+- **No `userType` cookie.** It is derived from the access-token JWT (`rcid` claim means registered). The refresh-cookie name is only a cold-start fallback and a write-time decision about which refresh cookie to set or delete.
+- **No `customerId` cookie.** Derived from the JWT. A legacy `customer_id` cookie is only deleted on logout and error paths.
+- **Value source.** Token strings come from the SLAS token response body; `userType`, `customerId`, `usid`, expiry and consent are decoded from the JWT so they cannot drift from the token. `dwsid` is the exception (SLAS `Set-Cookie`).
+- **Expiry overrides.** `PUBLIC_COMMERCE_API_GUEST_REFRESH_TOKEN_EXPIRY_SECONDS` and `PUBLIC_COMMERCE_API_REGISTERED_REFRESH_TOKEN_EXPIRY_SECONDS` can shorten the refresh lifetime; values above 30 / 90 days are capped.
+- **Defaults.** `path: '/'`, `sameSite: 'lax'`, `secure` only on deployed HTTPS (gated on `isRemote()`); `SameSite=None` cookies used by Page Designer design mode always stay `Secure`. The resolved `app.cookies.domain` (or per-site `commerce.sites[].cookies.domain`) applies to every cookie the storefront writes.
+- **Never write auth cookies directly.** Use `updateAuth` / `destroyAuth`; the middleware owns serialization and deletes cookies with expired `Set-Cookie` headers.
+
+## Debugging checklist
+
+1. DevTools > Application > Cookies: do you see duplicates of the same name (host-only plus domain-scoped)? See cookie-domain rollout notes in `storefront-next:sfnext-security`.
+2. Login works but does not stick on Safari over `http://localhost`: `secure` cookies are refused; confirm you are on `pnpm dev`/`pnpm preview` (which write non-secure cookies) and not a tunnel or HTTPS proxy with mismatched host.
+3. Hybrid pages lose the session: confirm `dwsid` is present on both storefronts and the cookie-domain settings agree on both sides.
+4. Repeated `session_expired` redirects: check the SLAS client's refresh-token settings and that the cookie domain matches the serving host.

package/content/guidance/storefront-next/sfnext-authentication/references/LOGIN-FLOWS.md

@@ -0,0 +1,59 @@
+# Login Flows
+
+All flows end in `updateAuth(context, tokenResponse)` from `@/middlewares/auth.server`. Prefer the existing route and library code over new implementations:
+
+| Flow | Entry points in your project |
+|---|---|
+| Password login | `src/routes/_empty.login.tsx`, `src/lib/api/auth/standard-login.server.ts` |
+| Registration | `src/routes/_empty.signup.tsx`, `src/lib/api/auth/register.server.ts` |
+| Password reset | `src/routes/_empty.reset-password.tsx`, `action.request-password-reset.ts`, `resource.slas-reset-password-callback.ts`, `src/lib/api/auth/reset-password.server.ts` |
+| Passwordless / OTP | `action.authorize-passwordless-email.ts`, `action.verify-passwordless-otp.ts`, `action.otp-request.ts`, `action.otp-verify.ts`, `resource.slas-passwordless-login-callback.ts`, `src/lib/auth/passwordless-login.server.ts` |
+| Social login | `src/lib/api/auth/social-login.server.ts` |
+| Passkeys | `action.passkey-*.ts`, `resource.passkey-status.ts`, `_app.account.passkeys.tsx`, `src/components/passkeys/`, `src/lib/auth/passkey-support.ts`, `webauthn.ts` |
+| Guest order lookup | `_app.order-lookup.*`, `action.order-lookup-*.ts`, `src/lib/order/` |
+
+Auth helpers used by these flows (`authorizePasswordless`, `getPasswordLessAccessToken`, `requestOtp`, `verifyOtp`, `getPasswordResetToken`, `resetPasswordWithToken`, passkey start/finish functions) are exported from `@/middlewares/auth.server`.
+
+## Passwordless (magic link) and OTP
+
+- Enable in `config.server.ts` under `features.passwordlessLogin` (`enabled`, `mode: 'email' | 'callback'`, `callbackUri` default `/passwordless-login-callback`, `landingUri` default `/login`). The callback URL must be allowlisted in the SLAS client. The callback route takes no site/locale prefix so one SLAS entry covers all sites.
+- Requires a SLAS **private** client: set `commerce.api.privateKeyEnabled: true`. If it is `false`, passwordless is disabled at runtime regardless of other settings.
+- `features.otpRequest.mode`: `email` (SLAS sends the code; supports email verification) or `callback` (SLAS POSTs the code to your `callbackUri` and you deliver it; no email-verification UI). `auth.otpLength` must be 6 or 8 and match the SLAS client.
+- Email verification UI (verified badge, change email, passwordless registration) turns on with the Business Manager preference **Enable Email Verification** (Site Preferences > Storefront Login Preferences; up to 5 minutes to propagate). Changing login email also needs **Enable Loginid Updates for SCAPI** (request via Salesforce support) and B2C 24.7 or later.
+- Full detail and troubleshooting table: `docs/README-EMAIL-VERIFICATION.md`.
+
+## Email delivery (email cartridge)
+
+Magic links, password resets and OTPs are sent by the `app_storefrontnext_base` cartridge's `POST /notify` custom API, called server-side via `clients.sfnextNotify` (`src/lib/notify/notify.server.ts`). One-time setup:
+
+1. `sfnext setup-base-cartridge --slas-client-id <id>` registers the `c_sfnext_notify` scope on the SLAS client (idempotent; needs `SFCC_SHORTCODE`, `SFCC_TENANT_ID` and OAuth client credentials).
+2. Deploy the cartridge (`pnpm cartridge:deploy --reload`) and add `app_storefrontnext_base` to the site cartridge path.
+3. Complete the Business Manager steps in `docs/README-EMAIL-CARTRIDGE.md` (storefront host allowlist preference, etc.).
+
+To change how mail is sent, customize the cartridge's `sendNotification` helper rather than the storefront. Deploy and endpoint registration checks: `b2c-cli:b2c-code`, `b2c-cli:b2c-scapi-custom`.
+
+## Social login
+
+- Enable `features.socialLogin` (`enabled`, `providers`, `callbackUri` default `/social-callback`). Each provider also needs setup in Account Manager / SLAS.
+- Flow is authorization-code with PKCE: generate the challenge, store the verifier via `updateAuth(context, (cur) => ({ ...cur, codeVerifier }))` (lands in httpOnly `cc-cv`, 5 minutes), redirect to the IDP, exchange the code in the callback and call `updateAuth(context, tokenResponse)`.
+- Adding a provider beyond the defaults usually needs CSP changes (`connect-src`, redirect/popup origins): see `storefront-next:sfnext-security`.
+- Guest wishlist/basket must be captured before and merged after the token swap; copy the shape of `social-login.server.ts`.
+- In a hybrid setup add `^/social-callback.*` to `HYBRID_ROUTING_RULES` (see `storefront-next:sfnext-hybrid-storefronts`).
+
+## Passkeys
+
+Enable with `features.passkey.enabled`. Registration is authorized by an OTP whose delivery follows `features.passkey.mode` (`email` or `callback`, same allowlisting rules as above). Passkeys are managed on `/account/passkeys`.
+
+## Guest order lookup
+
+Lets a guest find an order by order number plus email, confirm a 6-digit access code (valid 15 minutes, fixed by SCAPI) and view a redacted read-only order.
+
+- Set `guestOrderLookup.enabled: true` (default `false`). When off, both pages 404 and the actions return `FEATURE_DISABLED`.
+- Set `GUEST_ORDER_LOOKUP_COOKIE_SECRET` (falls back to `CLIENT_SECRET`); without a secret the feature fails closed with `CONFIGURATION_ERROR`.
+- Implement the B2C Commerce hook `sfcc.app.order.sendOrderAccessCode(order, accessCode)` in a cartridge; the storefront never sends this email itself (the shipped email cartridge covers it).
+- `guestOrderLookup.allowedFields` is an allow-list applied to the order before it reaches the browser; `cooldownSeconds` and `orderNumberPattern` tune abuse controls. Turnstile is enforced on the request-code step only (`guestOrderLookup.turnstile`).
+- Full detail: `docs/README-GUEST-ORDER-LOOKUP.md`.
+
+## Bot protection on login
+
+The passwordless/OTP email step, checkout registration and order lookup can be gated with Cloudflare Turnstile. Configuration and rollout are in `storefront-next:sfnext-security`.

package/content/guidance/storefront-next/sfnext-commerce-features/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sfnext-commerce-features
+description: >-
+  Catalogue and router for optional Storefront Next commerce features: Shopper Context (qualifiers, source codes), Order Management returns/cancel/tracking (SOM/OMS), delivery estimates, feature stubs (@feature-stub), guest order lookup, the app_storefrontnext_base email cartridge, and the shipped extensions (bnpl, bopis, multiship, store-locator, ratings-reviews, customer-preferences, product-content, shipping-delivery, theme-switcher). For each: which flag, SLAS scope, Business Manager setting, cartridge, or extension registry entry it needs, and which in-project doc to read. Use when asked how to enable a feature, why a feature does not render, what prerequisites a feature has, or which stubs are mock data. Do not use for building a new extension (use `storefront-next:sfnext-extensions`), config loading (use `storefront-next:sfnext-configuration`), or SLAS login flows (use `storefront-next:sfnext-authentication`).
+---
+
+# Storefront Next Commerce Features
+
+Start with the feature table, then read the named doc in your project's `docs/` folder. Do not assume a feature is live: several ship as UI scaffolds with mock data (see Feature stubs).
+
+## Feature table
+
+| Feature | Enable with | Also needs | Read |
+|---|---|---|---|
+| Shopper Context | `features.shopperContext.enabled` (env: `PUBLIC__app__features__shopperContext__enabled=true`), default off | Shopper Context API access for the SLAS client; qualifiers arrive as URL params or via the `useShopperContext` hook, stored in cookies | `docs/README-SHOPPER-CONTEXT.md` |
+| Returns, cancel, tracking (Order Management) | Nothing to toggle | Salesforce Order Management connected to the B2C instance; order loader expands `['oms','oms_shipments']`; without `omsData` only tracking shows | `docs/README-ORDER-MANAGEMENT.md` |
+| Delivery estimates | Keep extension `SFDC_EXT_SHIPPING_DELIVERY` installed | SLAS scopes `sfcc.shopper-delivery-estimates` and `sfcc.shopper-standard`, a delivery-estimate Commerce App bound to `sfcc.app.shipping.estimate`, online products on the site | `docs/README-DELIVERY-ESTIMATES.md` |
+| Guest order lookup | `guestOrderLookup.enabled: true` in `config.server.ts` | `GUEST_ORDER_LOOKUP_COOKIE_SECRET` (or `CLIENT_SECRET` fallback) and a cartridge implementing hook `sfcc.app.order.sendOrderAccessCode` to email the code | `docs/README-GUEST-ORDER-LOOKUP.md` |
+| Email cartridge (`app_storefrontnext_base`) | Deploy cartridge, add to site cartridge path | SLAS scope `c_sfnext_notify` (`sfnext setup-base-cartridge --slas-client-id <id>`), import preference metadata, set `Storefront Hosts` global custom preference, callback mode in storefront config | `docs/README-EMAIL-CARTRIDGE.md` |
+| Feature stubs | n/a | Mock UI scaffolds, not integrations | `docs/README-FEATURE-STUBS.md` |
+
+## Extensions shipped in src/extensions
+
+Registry: `src/extensions/config.json` (keys `SFDC_EXT_*`). Each extension contributes components to `UITarget` points through its `target-config.json`. To install or remove one, follow the install/uninstall instructions in `instructions/*.mdc` when the registry entry references them; building new extensions is `storefront-next:sfnext-extensions`.
+
+| Extension | Registry key | Notes |
+|---|---|---|
+| Store Locator | `SFDC_EXT_STORE_LOCATOR` | Find stores by location. Guided install/uninstall in `instructions/`. |
+| Multiship | `SFDC_EXT_MULTISHIP` | Ship items to several addresses in one order. Guided install/uninstall. |
+| Buy Online Pickup In Store | `SFDC_EXT_BOPIS` | Depends on Store Locator and Multiship. Guided install/uninstall. |
+| Shipping and Delivery | `SFDC_EXT_SHIPPING_DELIVERY` | Registers `sfcc.pdp.estimatedDelivery`; see delivery estimates row. |
+| Buy Now Pay Later (demo) | `SFDC_EXT_BNPL` | Mock fixtures; `sfcc.pdp.bnpl.message` target. Replace API function bodies to integrate a provider. |
+| Ratings and Reviews (demo) | `SFDC_EXT_RATINGS_REVIEWS` | Mock fixtures for PDP, cart modal, order detail CTA. Integrate Bazaarvoice, PowerReviews, etc. by replacing API bodies. |
+| Product Content (demo) | `SFDC_EXT_PRODUCT_CONTENT` | Returns/warranty card, FAQ, collapsibles (`sfcc.pdp.returnsWarranty`, `sfcc.pdp.faq`, `sfcc.pdp.collapsibles`). Fixtures in `lib/api/product-content.server.ts`. |
+| Customer Preferences (demo) | `SFDC_EXT_CUSTOMER_PREFERENCES` | Interests/preferences on the account page. Mock data. |
+| Theme switcher | none in registry | Folder `src/extensions/theme-switcher` has no registry entry in the shipped project; check your project before relying on it. |
+
+Demo extensions are "(Demo)" in `config.json`. Treat them as reference implementations: read the extension `README.md` and replace fixture functions before go-live.
+
+## Feature stubs
+
+Working UI with no backend (express checkout buttons, BNPL, returns and warranty, customer interests, and others). Find all of them:
+
+```bash
+grep -r "@feature-stub" src/
+```
+
+Each marker explains how to strip or wire it. Review the list before launch so mock content does not ship.
+
+## Decision flow when "the feature is not showing"
+
+1. Flag off? (`shopperContext`, `guestOrderLookup`) - check `config.server.ts` and env overrides.
+2. Extension missing from `src/extensions/config.json`, or dependencies not installed (BOPIS needs Store Locator and Multiship)?
+3. Missing SLAS scope on the shopper client (see `storefront-next:sfnext-authentication`)? Confirm in your SLAS client config, then re-login to get a fresh token.
+4. Backend not configured: OMS not connected, Commerce App not bound, cartridge not on the site cartridge path.
+5. Result is mock data: it is a stub.
+
+More detail per group: [references/FEATURE-PREREQUISITES.md](references/FEATURE-PREREQUISITES.md).
+
+## Related Skills
+
+- `storefront-next:sfnext-extensions` - UITarget, target-config.json, authoring extensions
+- `storefront-next:sfnext-configuration` - feature flags and env overrides
+- `storefront-next:sfnext-authentication` - SLAS scopes and clients
+- `storefront-next:sfnext-scapi` - calling the backing SCAPI endpoints
+- `storefront-next:sfnext-deployment` - deploying cartridges and bundles
+- `b2c-cli:b2c-mrt` - Managed Runtime environment variables

package/content/guidance/storefront-next/sfnext-commerce-features/references/FEATURE-PREREQUISITES.md

@@ -0,0 +1,37 @@
+# Feature prerequisites checklist
+
+Verify each item in your project; these come from the shipped docs and config.
+
+## Shopper Context
+- Flag: `features.shopperContext.enabled` (default false). When off, the middleware makes no SCAPI calls.
+- Qualifiers come from URL query params (middleware) or `useShopperContext`; state persists in cookies and is sent to SCAPI as a full replace.
+- Customizing supported qualifiers: `docs/README-SHOPPER-CONTEXT.md` "Customization".
+
+## Order Management
+- No flag. Needs SOM connected; the order detail loader calls `shopperOrders.getOrder` with `expand: ['oms', 'oms_shipments']`.
+- Return/cancel render only for registered, owning shoppers with item-level availability (`omsData.quantityAvailableToReturn > 0`).
+- ECOM-only orders degrade to tracking.
+
+## Delivery estimates
+- SLAS scopes: `sfcc.shopper-delivery-estimates`, `sfcc.shopper-standard`.
+- Commerce App provider bound to `sfcc.app.shipping.estimate`.
+- API `403`/`500` falls back to merchant shipping-method descriptions as general guidance only.
+- Verify by requesting an estimate for a product and destination; troubleshooting section in the doc.
+
+## Guest order lookup
+- Flag `guestOrderLookup.enabled`; keys include `orderNumberPattern`, `cooldownSeconds`, `allowedFields`.
+- Cookie secret env var required or the feature fails closed.
+- Access code lifetime is set by SCAPI, email is sent by your hook implementation.
+- When disabled: page routes 404 and action routes return `FEATURE_DISABLED`.
+
+## Email cartridge
+1. `sfnext setup-base-cartridge --slas-client-id <id>` (idempotent; reads `SFCC_SHORTCODE`, `SFCC_TENANT_ID`, `SFCC_OAUTH_CLIENT_ID`, `SFCC_OAUTH_CLIENT_SECRET` or `dw.json`).
+2. Deploy: `pnpm cartridge:deploy` (script runs `sfnext deploy-cartridge`). The email-cartridge doc shows a different command spelling; prefer the script in your `package.json`.
+3. Add `app_storefrontnext_base` to the site cartridge path; import the preference metadata; set the `Storefront Hosts` preference to your MRT hostnames.
+4. Set callback mode and callback URIs in storefront config; register the matching URLs in SLAS.
+Also see `storefront-next:sfnext-deployment`.
+
+## Extensions
+- Registry entries list `dependencies` (BOPIS -> Store Locator, Multiship).
+- Store Locator, Multiship, BOPIS ship install/uninstall `.mdc` instructions in `instructions/`. Additional BM or backend setup for them is not documented in a single place; check the instructions and each extension folder.
+- Demo extensions use fixtures; replace the API function bodies before production.