[bendvc]

Summary

Ports the app_pwakit_base B2C Commerce cartridge from sf-next into the PWA Kit template, and fixes the GLO verify authentication that was broken when enablePWAKitPrivateClient is used.

Deployed environment: https://scaffold-pwa-bens-playground.mobify-storefront.com/global/en-US

What's included

New: app_pwakit_base cartridge (packages/template-retail-react-app/cartridges/app_pwakit_base/)

Component	Purpose
scripts/hooks/sendOrderAccessCode.js	Implements sfcc.app.order.sendOrderAccessCode — called by SCAPI's requestOrderAccessCode to send the GLO access-code email
rest-apis/pwakit-notify/Notify.js	SCAPI Custom REST API (c_pwakit_notify scope) — called by the PWA Kit SSR server after a SLAS passwordless/OTP/password-reset callback to send the corresponding email
scripts/helpers/sendNotification.js	Renders ISML templates and delivers via dw/net/Mail (HTML body). Replace the body of send() to swap in any third-party provider (SendGrid, Mailchimp, etc.)
scripts/helpers/getStorefrontHost.js	Reads the pwakitStorefrontHost site preference for this site. Returns null when unset — callers omit magic-link CTAs but still send the email. Stubbed for the future Site.getCurrent().mrtExternalHostname platform API.
scripts/helpers/buildOrderLookupUrl.js	Shared helper that constructs the GLO verification URL (https://{host}/{siteId}/{locale}/order-lookup/verify/{orderNo}?token=…)
templates/default/email/	Four ISML templates: guestOrderLookup, passwordlessLogin (with inline access code), registrationVerification, passwordReset. CTA button and copy-URL fallback are conditionally rendered — templates degrade gracefully when no host can be resolved.
hooks.json + package.json	Hook registration (required — SFCC discovers hooks only at code-version activation)
staticfiles/…/OrganizationPreferences.xml	Registers pwakitNotifyEnabled (bool) under Administration → Global Preferences → PWA Kit
staticfiles/…/SitePreferences.xml	Registers pwakitStorefrontHost (string) under Merchant Tools → Custom Preferences → pwakit (per-site)
README.md	Full install, config, and customization guide

Fix: GLO verify 401 with enablePWAKitPrivateClient (packages/template-retail-react-app/app/ssr.js)

All 5 GLO SSR endpoints were reading the SLAS token from the cc-at_* cookie. This is wrong — cc-at_* is only written in SFRA hybrid mode. With a standard SLAS setup the access token lives in localStorage and is never in any cookie. The client (verify.jsx) was already sending Authorization: Bearer <jwt> via useAccessToken().getTokenWhenReady(). The fix reads req.headers.authorization directly, which works for both public and private client configurations.

Fix: null-token guard in verify.jsx

Added if (!token) throw new Error('No access token available') after getTokenWhenReady() resolves. Without this, a null/empty token produces Authorization: Bearer null — a truthy string that passes the server's if (!authorization) check and reaches SCAPI with an invalid credential. The guard routes this case into the existing catch block, showing the generic error UI. Test coverage added.

Fix: pwa-kit-create-app scaffold templates (packages/pwa-kit-create-app/assets/…/ssr.js.hbs)

Both scaffold templates had the same broken cc-at_* cookie auth as the main ssr.js. Updated to match.

---

Enhancements over the sf-next version

Area	sf-next	This PR
getStorefrontHost.js	Hard-coded single site preference + caller-supplied callerHost allowlist validation (org-level, comma-separated)	Simplified: reads pwakitStorefrontHost directly from the site preference for the current site — no allowlist, no caller-supplied hostname. Stubbed for future Site.getCurrent().mrtExternalHostname platform API.
pwakitNotifyEnabled preference	Not present	Allows disabling the cartridge's built-in delivery without removing it from the cartridge path — useful when plugging in Marketing Cloud or another provider
sendOrderAccessCode hook chaining	Calls HookMgr.callNextHook() (not a valid B2C API — the platform chains hooks automatically)	Removed; B2C handles chaining implicitly
isNotifyEnabled() error handling	Crashes if preference schema not imported	Catches the dw.system exception and defaults to enabled — safe to deploy before importing OrganizationPreferences.xml
Template naming	Content-based (gloAccessCode, passwordlessMagicLink, otpVerification, passwordResetMagicLink)	Flow-based (guestOrderLookup, passwordlessLogin, registrationVerification, passwordReset)
passwordlessLogin email	Magic link only	Includes inline access code display — the token is extracted from magicLinkPath and shown in the email so users can sign in without clicking the link
sendOrderAccessCode when host unconfigured	Constructs a broken https://null/… URL	Warns and sends the email with lookupLink: null — template degrades gracefully (CTA and copy-URL hidden via <isif>, disclaimer and access code still shown)
URL construction	Inline in each call site	Extracted into buildOrderLookupUrl.js shared helper — used by both Notify.js and sendOrderAccessCode.js
Locale forwarding	Not present	ssr.js extracts the locale from the redirectUrl query param (e.g. /en-US/account) via extractLocaleFromUrl and appends ?locale=en-US to the pwakit-notify API call. The cartridge reads request.locale (set by B2C from the query param) and passes it to sendNotification, which hands it to ISML so email templates render in the shopper's language rather than the site default

---

How to test

Deployed environment: https://scaffold-pwa-bens-playground.mobify-storefront.com/global/en-US

Prerequisites

• Cartridge uploaded to WebDAV and on the cartridge path for RefArchGlobal
• Both OrganizationPreferences.xml and SitePreferences.xml imported
• Code version deactivated and reactivated (required for hook + Custom API discovery)
• pwakitStorefrontHost set to scaffold-pwa-bens-playground.mobify-storefront.com (Merchant Tools → Custom Preferences → pwakit, per site)

Flow 1 — Guest Order Lookup (GLO)

Requires a B2C order placed as a guest on RefArchGlobal.

1. Navigate to /global/en-US/order-lookup
2. Enter a valid guest order number and the email used to place it, click Find My Order
3. Check your inbox — you should receive an access code email rendered from guestOrderLookup.isml containing both an access code and a "View Order" button
4. Enter the access code on the verify screen — you should land on the order detail page
5. Magic link path: click the link in the email directly — it should pre-fill the code and auto-submit
6. Error path: enter a wrong code — confirm "invalid or expired" error appears
7. Rate-limit path: submit an incorrect code 5+ times in quick succession — confirm 429 "Too many attempts" error

Flow 2 — Passwordless login

1. On the login page, choose Send Magic Link / passwordless option
2. Enter your email, submit
3. Check inbox — you should receive a passwordless email from passwordlessLogin.isml that contains both a magic link button and an inline access code
4. Click the link — you should be logged in on the storefront
5. Alternatively, enter the inline code on the sign-in screen to verify that path works too

Flow 3 — OTP verification

1. Trigger an OTP verification flow (e.g. email change, depending on storefront config)
2. Check inbox for OTP email from registrationVerification.isml
3. Enter the code to confirm

Flow 4 — Password reset

1. Click Forgot password on the login page
2. Enter your email
3. Check inbox — you should receive a reset-password magic-link email from passwordReset.isml
4. Click the link — you should land on the reset-password landing page

Disabling the cartridge

1. In Business Manager, set Administration → Global Preferences → Custom Preferences → PWA Kit → Notifications Enabled to false
2. Repeat any flow above — emails should NOT be delivered, but the flows should complete without error (the hook no-ops and returns OK)

---

Decisions worth calling out

1. Auth reads req.headers.authorization, not cookies

The GLO endpoints now trust the Authorization header sent by the client. This means the SSR server does not independently verify the token — it forwards whatever the client sends. This is consistent with how all other SCAPI-proxied endpoints in PWA Kit work. A malicious client could theoretically send someone else's token, but that token is tied to their own SLAS session, not to the order — the real gate is the {orderViewCode, email} pair validated by SCAPI.

2. Email stored in cc-goa_* cookie

After verify, the server stores {email, verifiedCode} in an HttpOnly / Secure / SameSite=Strict session cookie (Max-Age=900). This is needed because subsequent endpoints (/order, /cancel, /return) must re-authenticate with SCAPI using the same {email, orderViewCode} pair, and the client pages don't re-supply the email. The alternative — having the client re-send email on every request — was considered and rejected because it would require the server to trust whatever email the client provides rather than what was actually verified.

3. guestOrderLookup.enabled is false by default

The feature is off unless explicitly enabled in config/default.js. This is intentional — GLO requires a B2C instance with the requestOrderAccessCode SCAPI endpoint enabled and the cartridge deployed. Turning it on for a project that doesn't have those prerequisites would silently fail.

4. Magic link uses siteId.toLowerCase(), not siteAlias

The magic link path is built as /<siteId-lowercase>/<locale>/order-lookup/verify/<orderNo>?token=<code>. If the storefront registers a siteAlias in config/default.js (e.g. RefArchGlobal → global), the generated path (/refarchglobal/…) won't match the registered route (/global/…). This is documented as a known limitation in the README and in sendOrderAccessCode.js. Adding an alias-mapping preference was explicitly rejected to avoid creating a second place to maintain the alias mapping — the recommended fix is a CDN redirect or a custom hook override.

5. pwakitNotifyEnabled defaults to true when the preference is unset

On first deploy, before OrganizationPreferences.xml is imported, isNotifyEnabled() returns true. This means emails fire on the first activation. The alternative (default-disabled until explicitly enabled) was considered worse UX for the common case where the merchant just wants email to work out of the box.

6. pwakitStorefrontHost is a site preference, not an org preference

The host used for magic-link URL construction is now configured per-site in Merchant Tools → Custom Preferences → pwakit, rather than as an org-level comma-separated allowlist. This is simpler to configure for multi-site setups and removes the need for callerHost validation — the cartridge reads the host it already knows from its own configuration rather than trusting a value supplied by the caller. When the B2C Script API gains native access to the MRT/eCDN hostname (e.g. Site.getCurrent().mrtExternalHostname), the site preference becomes a fallback only.

7. Locale forwarding uses extractLocaleFromUrl, not Accept-Language

The SSR sendMagicLinkEmail handler receives the redirectUrl that the storefront passes when initiating a passwordless or reset-password flow (e.g. https://mystore.com/en-US/account). The locale is extracted from the first or second path segment via extractLocaleFromUrl — the regex matches both /en-US/... (locale-first) and /us/en-US/... (site-alias-first, which is the retail-react-app default URL shape) — and appended as ?locale= to the pwakit-notify API call. B2C sets request.locale from this query param, which is then forwarded to ISML. This approach avoids relying on the Accept-Language header (which may not match the storefront locale) and works for both absolute URLs and relative paths.

The cartridge additionally treats request.locale === 'default' (B2C's sentinel for "no locale set") as unset and falls through to Site.defaultLocale, so emails always render in a real locale rather than the literal string 'default'.

---

Pre-merge review fixes

Addressed in the final round of review before merge:

• extractLocaleFromUrl locale extraction: regex updated to match locale as the first or second URL path segment, so retail URLs (/us/en-US/...) are handled correctly alongside plain locale-first paths (/en-US/...)
• Registration-verification callback gate: added the same passwordless.mode !== 'callback' guard present on the passwordless and reset-password callback routes — the endpoint now returns 400 when callback mode is not configured
• GLO verify 401/403 pass-through: SCAPI 401/403 responses from the verify endpoint now return 401 Unauthorized to the client instead of 502 Service error
• request.locale === 'default' sentinel: both sendNotification.js and sendOrderAccessCode.js now skip the 'default' sentinel and fall through to Site.defaultLocale
• notifyClientId default: restored the notifyClientId placeholder in config/default.js that was accidentally blanked during a credential-revert commit

[git2gus]

Git2Gus App is installed but the .git2gus/config.json doesn't have right values. You should add the required configuration.

[cc-prodsec]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[sf-jie-dai]

Findings at 54478e4f161ecadf9af7952bfa075b2f2865c922
P1 - release documentation still tells merchants to restore the public notification credential. packages/template-retail-react-app/CHANGELOG.md:3 tells readers to add c_pwakit_notify to a generic SLAS client's default scopes because the guest-login helpers cannot request a scope. That no longer matches the implementation: getNotifyToken() requires notifyClientId plus PWA_KIT_NOTIFY_SLAS_CLIENT_SECRET, then uses loginGuestUserPrivate against the dedicated notify client. If a merchant follows the changelog using the shopper client, browser-minted tokens regain c_pwakit_notify and can call the public Custom API directly. The entry also names the removed pwakitStorefrontHosts preference. Replace it with the dedicated-private-client setup from the cartridge README, explicitly prohibit granting this scope to the shopper client, and name pwakitStorefrontHost.\n\n-
P2 - the pre-merge SSR fixes were not synchronized to either generated SSR template. e7084ee48 fixes the canonical app/ssr.js, but both assets/bootstrap/js/overrides/app/ssr.js.hbs:343-350 and assets/templates/@salesforce/retail-react-app/app/ssr.js.hbs:343-350 still only recognize a locale as the first URL segment. Thus a standard /{site}/{locale}/... redirect URL, such as /global/en-GB/..., drops the locale when sendMagicLinkEmail calls pwakit-notify. The same templates also omit the new registration-verification callback-mode guard (canonical app/ssr.js:735-741) and still map SCAPI 401/403 on GLO verification to 502 rather than 401 (canonical app/ssr.js:927-943). Mirror all three changes in both templates and add generated-project coverage for a site-and-locale redirect URL.\n\n-
P2 - generated-flow comments and the create-app release notes remain contradictory. Both generated config templates emit mode: 'callback' but their adjacent comments still say the default is email (for example assets/bootstrap/js/config/default.js.hbs:87-88,112-113). packages/pwa-kit-create-app/CHANGELOG.md:3 likewise still documents the removed fallback to public loginGuestUser when the private secret is missing. The generated SSR code instead fails fast without notifyClientId and PWA_KIT_NOTIFY_SLAS_CLIENT_SECRET. Correct this release/config guidance so it does not direct a merchant to remove the private-client prerequisite or configure the wrong default flow.\n\n## Verification\n\n- Reviewed the exact current head and the post-review commits, including the merge from develop.\n- All published CI checks are green, including lint, generated-project checks on Linux and Windows, e2e private-client, bundle size, and the Node-version matrix.\n- git diff --check origin/develop...54478e4f161ecadf9af7952bfa075b2f2865c922 passes.\n- GitHub still reports mergeStateStatus: DIRTY for the PR despite the branch incorporating the fetched develop head; recheck its mergeability after the above fixes.

[bendvc]

Addressed all three findings from the Oct 13 review in a6eadaacf:

P1 — Release notes instruct the retired public-client model
Fixed in both changelogs:

• template-retail-react-app/CHANGELOG.md: replaced the old "add `c_pwakit_notify` to your SLAS client's default Scopes" guidance with the dedicated private-client requirement (`notifyClientId` + `PWA_KIT_NOTIFY_SLAS_CLIENT_SECRET`); renamed `pwakitStorefrontHosts` → `pwakitStorefrontHost`; added an explicit warning not to add this scope to the shopper/public client.
• pwa-kit-create-app/CHANGELOG.md: removed the stale public-client fallback description; now correctly states that `getNotifyToken()` requires `notifyClientId` and `PWA_KIT_NOTIFY_SLAS_CLIENT_SECRET` with no fallback.

P2 — Pre-merge SSR fixes not synchronized to generated templates
Applied all three missing changes to both assets/bootstrap/js/overrides/app/ssr.js.hbs and assets/templates/@salesforce/retail-react-app/app/ssr.js.hbs:

• extractLocaleFromUrl regex now matches locale as first or second URL segment (^(?:\/[^/]*)?\/([a-z]{2}-[A-Z]{2})(\/|$)), handling /{site}/{locale}/... retail URLs
• Registration-verification callback route now includes the passwordless.mode !== 'callback' guard (mirrors canonical app/ssr.js:735-741)
• GLO /verify now maps SCAPI 401/403 → HTTP 401 instead of 502

P2 — Generated config comments and create-app changelog contradict shipped behavior
Fixed in both default.js.hbs templates: comments now say Defaults to: 'callback' instead of 'email', matching the emitted value.

[sf-jie-dai]

Approved at the requester's direction after reviewing current head a6eadaa. The prior generated-template and release-guidance findings are resolved. The PR remains conflicting with develop and has not completed its full CI matrix at this head; rebase/merge develop and required checks remain prerequisites to merge.

[sf-jie-dai]

Approved after reviewing merge commit 2a01f43. The develop merge resolves the prior changelog conflict without regressing the reviewed dedicated-private-client, generated-template, or release-guidance changes. Full CI is green.

[sf-jie-dai]

Reviewed current head ba4ae17. The develop merge preserves the dedicated private notify-client, generated-template, and callback-route fixes. The new Vitest 4.1.11 override is correctly applied to the create-app package, generated extensible-app manifest, and retail template to cover npm 10 installs. All published CI checks, including generated projects on Linux and Windows and the Node/npm matrix, are green. Approved.

[sf-jie-dai]

Re-approving reviewed head ba4ae17 at requester direction. Published checks remain green.

[ddiazccrz]

[P1] This guard prevents new customers from receiving their registration OTP. SLAS creates the B2C profile only after the shopper exchanges the TOTP, not when authorizePasswordlessCustomer invokes this callback (platform contract). With the new register_customer: true caller, a fresh email therefore returns success here without sending the code needed to create the profile. Please remove the existing-customer requirement from the registration OTP branch, correct the corresponding README assumption, and test delivery when getCustomerByLogin() returns null. The dedicated notify-client scope and authenticated SSR callback should remain in place.

[ddiazccrz]

[P2] A magic-link arrival submits partial email addresses while the shopper types. This effect reruns on every email edit and submits after only 100 ms; the form uses noValidate, and onSubmit checks code completeness but not email validity. Opening ?token=123456 and pausing after typing a therefore sends that partial address to the verify endpoint, disables the input while pending, and consumes one of the five allowed attempts. Please limit auto-submission to email supplied through router state; for direct arrivals, prefill the code and require validated email plus explicit submission. Add a test asserting that typing an email does not trigger a verification request.

[ddiazccrz]

[P2] The recipient email is not necessarily the customer's login. SLAS reset callbacks distinguish email_id from login_id and explicitly support profiles where they differ (contract). SSR forwards email_id as recipient, so a valid account with login shopper-login and email shopper@example.com is silently skipped by this login lookup. The passwordless branch has the same problem. Please resolve the profile by its email, or carry login_id through the authenticated callback and verify the resolved profile's email matches the recipient; cover differing login/email values in a regression test.

[ddiazccrz]

[P2] Registration delivery is gated by the unrelated passwordless-login mode. UserRegistration now requests mode: 'callback' for both initial send and resend using login.registrationVerification.callbackURI, independently of login.passwordless.mode. A storefront retaining native email mode for ordinary login therefore receives a 400 here for every checkout registration callback, even with valid notify credentials. Please use registration-specific configuration consistently with its caller rather than this login-mode guard, update both SSR templates, and test registration with passwordless.mode: 'email'.

[ddiazccrz]

[P2] This command cannot configure the required notification secret. pwa-kit-dev push has no --set-env option; its CLI only uploads/deploys a bundle, so following this setup example cannot set PWA_KIT_NOTIFY_SLAS_CLIENT_SECRET and leaves callbacks failing on missing configuration. Please remove this command and use the MRT environment-variable UI already described below, or replace it with a verified supported environment-management command.

[ddiazccrz]

+1 With follow up for smaller issues