@salesforce/b2c-cli 2.3.0 → 2.4.0

package/content/guidance/b2c/b2c-slas-auth-patterns/references/SESSION-BRIDGE.md

@@ -0,0 +1,267 @@
+# Session Bridge Reference
+
+> Illustrative of the flow; confirm platform-agnostic API contract with `b2c docs read commerce-api/slas-session-bridge-auth`. PWA Kit examples use framework-specific convenience wrappers.
+
+Detailed implementation patterns for session bridging between PWA Kit and SFRA.
+
+## Token Types
+
+| Token | Description | Duration |
+|-------|-------------|----------|
+| `dwsgst` | Guest session token | 30 minutes |
+| `dwsrst` | Registered session token | 30 minutes |
+| `dwsid` | SFRA session cookie | Session-based |
+
+## PWA Kit to SFRA
+
+### Step 1: Generate Bridge Tokens
+
+```javascript
+// commerce-sdk-isomorphic or direct API call
+async function generateBridgeTokens(shopperToken) {
+    const response = await shopperLogin.getSessionBridgeAccessToken({
+        headers: {
+            Authorization: `Bearer ${shopperToken.access_token}`
+        },
+        body: {
+            channel_id: siteId,
+            login_id: shopperToken.customer_id
+        }
+    });
+
+    return {
+        dwsgst: response.dwsgst,
+        dwsrst: response.dwsrst // Only present if logged in
+    };
+}
+```
+
+### Step 2: Redirect with Tokens
+
+Option A: URL Parameters (simple)
+
+```javascript
+function redirectToSFRA(bridgeTokens, targetPath) {
+    const url = new URL(sfraBaseUrl + targetPath);
+    url.searchParams.set('dwsgst', bridgeTokens.dwsgst);
+    if (bridgeTokens.dwsrst) {
+        url.searchParams.set('dwsrst', bridgeTokens.dwsrst);
+    }
+    window.location.href = url.toString();
+}
+```
+
+Option B: POST Form (more secure)
+
+```javascript
+function redirectViaPOST(bridgeTokens, targetPath) {
+    const form = document.createElement('form');
+    form.method = 'POST';
+    form.action = sfraBaseUrl + '/SessionBridge-Establish';
+
+    const addInput = (name, value) => {
+        const input = document.createElement('input');
+        input.type = 'hidden';
+        input.name = name;
+        input.value = value;
+        form.appendChild(input);
+    };
+
+    addInput('dwsgst', bridgeTokens.dwsgst);
+    if (bridgeTokens.dwsrst) {
+        addInput('dwsrst', bridgeTokens.dwsrst);
+    }
+    addInput('redirect', targetPath);
+
+    document.body.appendChild(form);
+    form.submit();
+}
+```
+
+### Step 3: SFRA Establishes Session
+
+```javascript
+// SFRA Controller: SessionBridge-Establish
+var server = require('server');
+var SLASBridge = require('*/cartridge/scripts/services/SLASBridge');
+
+server.post('Establish', function(req, res, next) {
+    var dwsgst = req.form.dwsgst;
+    var dwsrst = req.form.dwsrst;
+    var redirect = req.form.redirect || '/';
+
+    try {
+        // Exchange bridge tokens for session
+        var result = SLASBridge.establishSession(dwsgst, dwsrst);
+
+        if (result.success) {
+            // Session established, dwsid cookie is set by platform
+            res.redirect(redirect);
+        } else {
+            res.redirect('/login?error=bridge_failed');
+        }
+    } catch (e) {
+        res.redirect('/login?error=bridge_error');
+    }
+
+    next();
+});
+```
+
+## SFRA to PWA Kit
+
+### Step 1: Generate Bridge Tokens in SFRA
+
+```javascript
+// SFRA Helper
+var LocalServiceRegistry = require('dw/svc/LocalServiceRegistry');
+var Site = require('dw/system/Site');
+
+function getBridgeTokensForPWA() {
+    var customer = session.customer;
+    var svc = LocalServiceRegistry.createService('slas.sessionbridge', {
+        createRequest: function(svc, args) {
+            svc.setRequestMethod('POST');
+            svc.addHeader('Content-Type', 'application/x-www-form-urlencoded');
+
+            var params = 'channel_id=' + Site.current.ID;
+            if (customer.authenticated) {
+                params += '&login_id=' + customer.profile.credentials.login;
+            }
+            return params;
+        },
+        parseResponse: function(svc, response) {
+            return JSON.parse(response.text);
+        }
+    });
+
+    var result = svc.call();
+    return result.ok ? result.object : null;
+}
+```
+
+### Step 2: Redirect to PWA Kit
+
+```javascript
+// SFRA Controller: SessionBridge-ToPWA
+server.get('ToPWA', function(req, res, next) {
+    var SLASBridge = require('*/cartridge/scripts/services/SLASBridge');
+    var targetPath = req.querystring.path || '/';
+
+    var bridgeTokens = SLASBridge.getBridgeTokensForPWA();
+
+    if (bridgeTokens) {
+        var pwaUrl = 'https://pwa.yoursite.com/session-bridge/callback';
+        pwaUrl += '?dwsgst=' + encodeURIComponent(bridgeTokens.dwsgst);
+        if (bridgeTokens.dwsrst) {
+            pwaUrl += '&dwsrst=' + encodeURIComponent(bridgeTokens.dwsrst);
+        }
+        pwaUrl += '&redirect=' + encodeURIComponent(targetPath);
+
+        res.redirect(pwaUrl);
+    } else {
+        res.redirect('https://pwa.yoursite.com' + targetPath);
+    }
+
+    next();
+});
+```
+
+### Step 3: PWA Kit Handles Callback
+
+```javascript
+// PWA Kit: pages/session-bridge/callback.jsx
+import { useEffect } from 'react';
+import { useSearchParams, useNavigate } from 'react-router-dom';
+import { useAuth } from '@salesforce/commerce-sdk-react';
+
+export default function SessionBridgeCallback() {
+    const [searchParams] = useSearchParams();
+    const navigate = useNavigate();
+    const auth = useAuth();
+
+    useEffect(() => {
+        async function establishSession() {
+            const dwsgst = searchParams.get('dwsgst');
+            const dwsrst = searchParams.get('dwsrst');
+            const redirect = searchParams.get('redirect') || '/';
+
+            try {
+                // Exchange bridge tokens
+                await auth.loginSessionBridge({ dwsgst, dwsrst });
+                navigate(redirect);
+            } catch (error) {
+                console.error('Bridge failed:', error);
+                navigate('/login?error=bridge_failed');
+            }
+        }
+
+        establishSession();
+    }, [searchParams]);
+
+    return <div>Establishing session...</div>;
+}
+```
+
+## Hybrid Navigation Component
+
+```jsx
+// PWA Kit: components/hybrid-link.jsx
+import { useAuth } from '@salesforce/commerce-sdk-react';
+
+export function HybridLink({ href, children, ...props }) {
+    const auth = useAuth();
+
+    const handleClick = async (e) => {
+        // Check if href is SFRA
+        if (href.includes('sfra.yoursite.com')) {
+            e.preventDefault();
+
+            // Get bridge tokens
+            const tokens = await auth.getSessionBridgeTokens();
+
+            // Build SFRA URL with tokens
+            const url = new URL(href);
+            url.searchParams.set('dwsgst', tokens.dwsgst);
+            if (tokens.dwsrst) {
+                url.searchParams.set('dwsrst', tokens.dwsrst);
+            }
+
+            window.location.href = url.toString();
+        }
+        // Otherwise, let normal navigation happen
+    };
+
+    return (
+        <a href={href} onClick={handleClick} {...props}>
+            {children}
+        </a>
+    );
+}
+```
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `invalid_token` | Bridge token expired | Re-generate tokens |
+| `session_mismatch` | Different customer | Clear and restart |
+| `channel_mismatch` | Wrong site ID | Verify channel_id |
+| `bridge_disabled` | Feature not enabled | Enable in SLAS config |
+
+## Security Considerations
+
+1. **Token Expiry**: Bridge tokens expire quickly (30 min) - generate fresh tokens before redirect
+2. **HTTPS Only**: Always use HTTPS for token exchange
+3. **Referrer Validation**: Validate source domain on callback endpoints
+4. **Rate Limiting**: Implement rate limiting on bridge endpoints
+5. **Token Usage**: Each bridge token should only be used once
+
+## Testing
+
+```bash
+# Verify bridge token generation
+curl -X POST "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{orgId}/oauth2/session-bridge/token" \
+  -H "Authorization: Bearer {access_token}" \
+  -d "channel_id={siteId}&login_id={customerId}"
+```

package/content/guidance/b2c/b2c-slas-auth-patterns/references/TOKEN-LIFECYCLE.md

@@ -0,0 +1,367 @@
+# Token Lifecycle Reference
+
+Understanding token expiry, refresh patterns, and lifecycle management for SLAS.
+
+## Token Types and Expiry
+
+| Token Type | Default Expiry | Configurable | Use Case |
+|------------|----------------|--------------|----------|
+| Access Token | 30 minutes | Yes (SLAS Admin) | API requests |
+| Refresh Token (Public) | 90 days | Yes | Token renewal |
+| Refresh Token (Private) | 90 days | Yes | Token renewal |
+| Session Bridge Token | 30 minutes | No | Cross-platform auth |
+| Passwordless Token | 10 minutes | No | OTP verification |
+
+## Access Token Lifecycle
+
+```
+[Issue] → [Active] → [Expired]
+   ↓         ↓
+  Use    Refresh
+```
+
+### Best Practices for Access Tokens
+
+```javascript
+class TokenManager {
+    constructor(config) {
+        this.accessToken = null;
+        this.refreshToken = null;
+        this.expiresAt = null;
+        this.refreshThreshold = 5 * 60 * 1000; // 5 minutes
+    }
+
+    isExpired() {
+        return Date.now() >= this.expiresAt;
+    }
+
+    shouldRefresh() {
+        // Refresh when within threshold of expiry
+        return Date.now() >= (this.expiresAt - this.refreshThreshold);
+    }
+
+    async getValidToken() {
+        if (this.shouldRefresh()) {
+            await this.refresh();
+        }
+        return this.accessToken;
+    }
+
+    async refresh() {
+        const tokens = await this.slasRefresh(this.refreshToken);
+        this.setTokens(tokens);
+    }
+
+    setTokens(tokens) {
+        this.accessToken = tokens.access_token;
+        this.refreshToken = tokens.refresh_token;
+        this.expiresAt = Date.now() + (tokens.expires_in * 1000);
+    }
+}
+```
+
+## Refresh Token Patterns
+
+### Public Client (Single-Use)
+
+For browser-based apps without a backend:
+
+```javascript
+// Refresh tokens are single-use - must store new token
+async function refreshPublicClient(refreshToken) {
+    const response = await fetch(tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+            client_id: clientId,
+            channel_id: siteId
+        })
+    });
+
+    const tokens = await response.json();
+
+    // IMPORTANT: Old refresh token is now invalid
+    // Must use the new refresh_token for next refresh
+    return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token, // NEW token
+        expiresIn: tokens.expires_in
+    };
+}
+```
+
+### Private Client (Reusable)
+
+For server-side applications:
+
+```javascript
+// Refresh tokens are reusable with client secret
+async function refreshPrivateClient(refreshToken) {
+    const response = await fetch(tokenEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'Authorization': `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`
+        },
+        body: new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+            channel_id: siteId
+        })
+    });
+
+    const tokens = await response.json();
+
+    // Can reuse same refresh token (though new one may be provided)
+    return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token || refreshToken,
+        expiresIn: tokens.expires_in
+    };
+}
+```
+
+## Token Rotation Strategy
+
+### Public Clients - Handle Race Conditions
+
+```javascript
+class PublicTokenManager {
+    constructor() {
+        this.refreshPromise = null;
+        this.tokenVersion = 0;
+    }
+
+    async refresh() {
+        // Prevent multiple concurrent refreshes
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+
+        const currentVersion = this.tokenVersion;
+
+        this.refreshPromise = this._doRefresh()
+            .finally(() => {
+                this.refreshPromise = null;
+            });
+
+        return this.refreshPromise;
+    }
+
+    async _doRefresh() {
+        const tokens = await refreshPublicClient(this.refreshToken);
+
+        // Check for race condition
+        if (this.tokenVersion !== currentVersion) {
+            // Another refresh happened, tokens might be stale
+            throw new Error('Token version mismatch');
+        }
+
+        this.tokenVersion++;
+        this.setTokens(tokens);
+        return tokens;
+    }
+}
+```
+
+### Storage Strategies
+
+```javascript
+// Browser - httpOnly cookie preferred (requires BFF)
+// Fallback to localStorage with encryption
+
+class TokenStorage {
+    // Option 1: httpOnly cookies via BFF
+    async storeViaBackend(tokens) {
+        await fetch('/api/auth/store-tokens', {
+            method: 'POST',
+            credentials: 'include',
+            body: JSON.stringify(tokens)
+        });
+    }
+
+    // Option 2: localStorage (less secure)
+    storeLocally(tokens) {
+        // Consider encrypting before storage
+        localStorage.setItem('auth_tokens', JSON.stringify({
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+            expiresAt: Date.now() + (tokens.expires_in * 1000)
+        }));
+    }
+
+    // Option 3: Memory only (cleared on refresh)
+    storeInMemory(tokens) {
+        this._tokens = tokens;
+    }
+}
+```
+
+## Session Timeout Handling
+
+### Proactive Refresh
+
+```javascript
+class SessionManager {
+    constructor() {
+        this.refreshTimer = null;
+    }
+
+    scheduleRefresh(expiresIn) {
+        // Clear existing timer
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+        }
+
+        // Schedule refresh 5 minutes before expiry
+        const refreshIn = (expiresIn - 300) * 1000;
+
+        this.refreshTimer = setTimeout(() => {
+            this.refresh().catch(this.handleRefreshError);
+        }, refreshIn);
+    }
+
+    handleRefreshError(error) {
+        // Check if refresh token is also expired
+        if (error.message.includes('invalid_grant')) {
+            // Full re-authentication required
+            this.logout();
+            this.redirectToLogin();
+        }
+    }
+}
+```
+
+### Activity-Based Extension
+
+```javascript
+class ActivityTracker {
+    constructor(tokenManager) {
+        this.tokenManager = tokenManager;
+        this.lastActivity = Date.now();
+        this.activityTimeout = 15 * 60 * 1000; // 15 minutes
+
+        this.setupListeners();
+    }
+
+    setupListeners() {
+        ['click', 'keydown', 'scroll', 'mousemove'].forEach(event => {
+            window.addEventListener(event, () => this.recordActivity(), { passive: true });
+        });
+    }
+
+    recordActivity() {
+        const now = Date.now();
+        if (now - this.lastActivity > 60000) { // Throttle to 1 minute
+            this.lastActivity = now;
+            this.checkTokenRefresh();
+        }
+    }
+
+    checkTokenRefresh() {
+        if (this.tokenManager.shouldRefresh()) {
+            this.tokenManager.refresh();
+        }
+    }
+
+    isInactive() {
+        return Date.now() - this.lastActivity > this.activityTimeout;
+    }
+}
+```
+
+## Guest to Registered Transition
+
+When a guest user logs in, merge sessions:
+
+```javascript
+async function loginWithSessionMerge(credentials, guestAccessToken) {
+    const response = await fetch(tokenEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            // Include guest token for basket/session merge
+            'Authorization': `Bearer ${guestAccessToken}`
+        },
+        body: new URLSearchParams({
+            grant_type: 'password',
+            username: credentials.username,
+            password: credentials.password,
+            client_id: clientId,
+            channel_id: siteId
+        })
+    });
+
+    // Returns registered user tokens
+    // Guest basket is automatically merged
+    return response.json();
+}
+```
+
+## Logout and Token Revocation
+
+```javascript
+async function logout(accessToken, refreshToken) {
+    // Revoke refresh token
+    await fetch(
+        `https://${shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/${orgId}/oauth2/revoke`,
+        {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                token: refreshToken,
+                token_type_hint: 'refresh_token',
+                client_id: clientId,
+                channel_id: siteId
+            })
+        }
+    );
+
+    // Clear local storage
+    localStorage.removeItem('auth_tokens');
+
+    // Clear cookies if using BFF
+    await fetch('/api/auth/logout', {
+        method: 'POST',
+        credentials: 'include'
+    });
+}
+```
+
+## Error Handling Reference
+
+| Error | Meaning | Action |
+|-------|---------|--------|
+| `invalid_grant` | Refresh token expired/revoked | Re-authenticate |
+| `invalid_token` | Access token invalid | Try refresh |
+| `expired_token` | Access token expired | Refresh token |
+| `invalid_client` | Client credentials wrong | Check configuration |
+| `unauthorized_client` | Client not allowed | Check SLAS client settings |
+
+## Debugging Token Issues
+
+```javascript
+// Decode JWT without validation (for debugging only)
+function decodeToken(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+
+    const payload = JSON.parse(atob(parts[1]));
+    return {
+        subject: payload.sub,
+        issuer: payload.iss,
+        audience: payload.aud,
+        expiresAt: new Date(payload.exp * 1000),
+        issuedAt: new Date(payload.iat * 1000),
+        scopes: payload.scope?.split(' ') || []
+    };
+}
+
+// Check if token is expired
+function isTokenExpired(token) {
+    const decoded = decodeToken(token);
+    return decoded && Date.now() >= decoded.expiresAt.getTime();
+}
+```