toga-ai 1.0.846 → 1.0.847

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -13,12 +13,13 @@
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Per-tenant/language/role JSON config that drives almost all commerce UI text, fields, and login fetches (Layer A global + Layer B FIELDS registry); open before |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | Expedited shipping options are config-gated to show only when the cart holds a computer kit; open when touching cart shipping-method options or the gate config. |
 | [Filter / Search-Results Page & the Two Search Entry Points](features/filter-search-results-page.md) | Two search entry points (Home in-place vs Header→/filter) render the same card via different code paths and FIELDS files; open for any search-results or kit-car |
-| [Header "Order for <Name>" dropdown + the pending-pick hand-off to the cart](features/header-order-for-dropdown.md) | Header pill that lets a buyer pick who they are ordering for from any page, and the in-memory store that hands that pick to the cart's order-for cascade; open b |
+| [Header "Order for <Name>" dropdown + the persisted pick handed to the cart](features/header-order-for-dropdown.md) | Header pill that lets a buyer pick who they are ordering for from any page, and the persisted store that hands that pick to the cart's order-for cascade; open b |
 | [Inactive-item purchase gating (standalone lines only — kits are exempt by design)](features/inactive-item-purchase-gating.md) | `Items.isActive = 0` blocks standalone purchase but means something different on kit components, so the gate keys on purchase CONTEXT not the flag; open when to |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | How the hostname resolves the tenant and fans out to API base URL, theme (CSS variables), and fields; open when adding a tenant or debugging wrong-theme/wrong-A |
 | [Order-submit sync sequencing (useSubmitOrder) — why these calls must not run in parallel](features/order-submit-sync-sequencing.md) | The item sync must finish before the header sync on order submit, or concurrent line deletes race a depth-3 response into an uncaught api2 500; open when touchi |
 | [Config-Driven Shipping Cost Waiver (Standard Ground free for computer kits)](features/shipping-cost-waiver-gating.md) | Config-driven cost waiver making Standard Ground free for a bare computer kit (Compass USA); open when touching shipping cost gates or the Compass free-freight |
 | [Storefront persona gating — the Home page's kit / category / item counts, and the persona switcher](features/storefront-persona-gating-and-home-counts.md) | What a storefront user sees on the Home page is decided **in the front end**, from `user._personaIds`, not by the API's ACL. |
+| [View-as another user — parked admin tokens & return-to-self](features/view-as-session-tokens.md) | How an admin impersonates another user and gets back: the delegated token pair, the parked admin pair in localStorage, and the return path. |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How toga2-commerce builds/deploys on AWS Amplify (one dynamic amplify.yml, branch-per-env, per-env blox channel); open to deploy, stand up an env, resolve a blo |
 | [Cart e2e — Cypress conventions & harness (toga2-commerce)](workflows/cypress-testing.md) | Cypress e2e conventions + the Cart harness (cartV2.cy.ts) for toga2-commerce; read before adding any spec here, and note it doubles as the config-cart refactor |
 | [Diagnosing ERR_HTTP2_PROTOCOL_ERROR (one client fails, everyone else is fine)](workflows/http2-protocol-error-diagnosis.md) | Diagnose ERR_HTTP2_PROTOCOL_ERROR when one client/network fails a togacommerce tenant but everyone else works (usually the client's TLS-inspection proxy, not ou |

package/knowledge/2.0/apps/toga2-commerce/architecture.md

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: architecture
 status: active
-updated: 2026-09-17
+updated: 2026-09-21
 owners: ["apeterson", "tcox"]
 files:
   - src/main.tsx
@@ -15,6 +15,7 @@ files:
   - src/contexts/AuthContext.tsx
   - src/contexts/helpers/getLoginSettings.ts
   - src/api/axiosInstance.ts
+  - src/api/sessionTokens.ts
   - src/stores/
   - src/themeConfig/ThemeContext.tsx
   - src/fieldsConfig/index.ts
@@ -27,6 +28,7 @@ related:
   - 2.0/apps/toga2-commerce/workflows/amplify-build-and-deploy.md
   - 2.0/apps/api2/architecture.md
   - 2.0/apps/toga2-commerce/features/filter-search-results-page.md
+  - 2.0/apps/toga2-commerce/features/view-as-session-tokens.md
 ---
 
 Whole-repo map of the toga2-commerce React storefront (bootstrap, routing, MVVM pages, state, API, multi-tenant resolution); open when working anywhere in this repo.
@@ -124,7 +126,7 @@ Most use the `persist` middleware (localStorage). Verified files:
 | `useEditOrderZu` | "Edit existing order" mode flag + original snapshot |
 | `useEditOrderUuidStore` | UUID of the order being edited |
 | `useSelectedUserZu` | "Order for" user selected in cart |
-| `useOrderForZu` | Header "order for" **pending pick** handed to the cart cascade — **in memory only, never `persist`ed** |
+| `useOrderForZu` | Header "order for" pick — **persisted** (`order-for-zu`), owner-scoped: always read via `getOrderForUserFor(pick, ownerUuid)` (see header-order-for-dropdown) |
 | `useReturnOriginalUserFromViewAsStore` | "View as another user" return-to-self tracking |
 | `useEmailOptionsStore` | Notification CC email options (see cart-notification-emails) |
 | `useBundleBuilderZu` | Bundle-builder wizard selections |
@@ -146,7 +148,8 @@ Most use the `persist` middleware (localStorage). Verified files:
 - **Transaction id:** a request interceptor stamps every call with `params.transactionId = uuidv4()`.
 - **Auth token:** a second request interceptor attaches `Authorization: Bearer <token>` — using the stored `accessToken` if a `user` exists in localStorage, otherwise fetching a **public token** via `POST {baseURL}/auth/public`.
 - **1 ms delay interceptor:** a third request interceptor `await delay(1)` before sending.
-- **401 handling:** response interceptor attempts `POST {baseURL}/auth/refresh` (Bearer refresh token) once (`_retry`), retries the original request on success, else calls `performLogout()` (clears all auth + cart + `commerce` cache keys and redirects to `/`).
+- **401 handling:** response interceptor attempts `POST {baseURL}/auth/refresh` (Bearer refresh token) once (`_retry`), retries the original request on success, else calls `performLogout()` (clears all auth + cart + `commerce` cache keys and redirects to `/`). The refresh is **single-flight** (one module-level promise) and **identity-bound** — it returns `null` if `localStorage.refreshToken` changed while in flight, so it cannot overwrite a just-minted delegated pair.
+- **Token storage lives in `src/api/sessionTokens.ts`** (host from `src/api/apiBaseUrl.ts`). Besides `accessToken` / `refreshToken` it owns **`originalAuthTokens`** — the admin's own pair parked during view-as and restored on return; `/auth/encrypted` is never called to re-mint. See [view-as-session-tokens](features/view-as-session-tokens.md).
 - Failures are reported to **Sentry** with `errorType: "API"` tags.
 
 The backend (`api2`) returns the standard 2.0 envelope (`success`/`data`/`errors`; see api2 arch); generic CRUD helpers live in `src/api/genericApi.ts` (paginated `getData`, `saveData`, `updateData`, `deleteData`, optional `?depth=-1` for nested responses).

package/knowledge/2.0/apps/toga2-commerce/features/header-order-for-dropdown.md

@@ -1,17 +1,16 @@
 ---
-title: Header "Order for <Name>" dropdown + the pending-pick hand-off to the cart
+title: Header "Order for <Name>" dropdown + the persisted pick handed to the cart
 framework: "2.0"
 repo: toga2-commerce
 project: TOGa Commerce
 client: shared
 type: feature
-status: draft
+status: active
 updated: 2026-09-17
 owners: [tcox]
 files:
   - src/components/OrderForDropdown/OrderForDropdown.tsx
   - src/components/OrderForDropdown/useOrderForDropdownViewModel.ts
-  - src/components/OrderForDropdown/types.ts
   - src/stores/useOrderForZu.ts
   - src/components/Header/Header.tsx
   - src/pages/Cart/view/cartForm/EditCart.tsx
@@ -25,77 +24,81 @@ related:
   - 2.0/apps/toga2-commerce/features/client-fields.md
   - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
   - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
+  - 2.0/apps/toga2-commerce/features/view-as-session-tokens.md
   - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
 ---
 
-Header pill that lets a buyer pick who they are ordering for from any page, and the in-memory store that hands that pick to the cart's order-for cascade; open before touching the header pill, `useOrderForZu`, or the cart `orderFor` field.
+Header pill that lets a buyer pick who they are ordering for from any page, and the persisted store that hands that pick to the cart's order-for cascade; open before touching the header pill, `useOrderForZu`, or the cart `orderFor` field.
 
 ## Summary
 
-TRUE-81851. Before this, "order for someone else" existed **only** on the cart form. The header now renders an **"Order for <Name>"** pill (next to the logo on desktop, inside the mobile `SlideMenu`) that sets the same pick from any page. The header does **not** run the order-for cascade — it parks the pick in a new in-memory Zustand store and the **cart stays the single owner** of the cascade.
+TRUE-81851 (pill) + TRUE-81852 (persistence). Before this, "order for someone else" existed **only** on the cart form. The header now renders an **"Order for <Name>"** pill (next to the logo on desktop, inside the mobile `SlideMenu`) that sets the same pick from any page. The header does **not** run the order-for cascade — it stores the pick and the **cart stays the single owner** of the cascade.
 
-**Status: built on branch `TRUE-81851` (cut from `_production`), staged, not committed or merged.** The Cypress spec type-checks but was never run.
+**The pick is sticky.** Developer requirement: *"Order for needs to be persistent once chosen until the user changes it back to themself or logs out."* The store is persisted to localStorage and survives order submit, edit-order exit, view-as return, and page reload.
 
-**Per-role, per-tenant gated.** Copy and the on/off switch live in `HEADERFIELDS.json` under a new `orderFor` key, Compass USA only: `isEnabled` true for ADMIN / MANAGER / SUPERUSER, false for USER. Compass Canada and Quad have no key, so the component renders nothing (see gotchas).
+**Per-role, per-tenant gated.** Copy and the on/off switch live in `HEADERFIELDS.json` under an `orderFor` key, Compass USA only: `isEnabled` true for ADMIN / MANAGER / SUPERUSER, false for USER. Compass Canada and Quad have no key, so the component renders nothing (see gotchas).
 
 ## How it works
 
 ### 1. The pill (`src/components/OrderForDropdown/`)
 
-MVVM split: `OrderForDropdown.tsx` (view), `useOrderForDropdownViewModel.ts` (state + queries), `types.ts`, `index.ts`. Rendered from `src/components/Header/Header.tsx`; hidden in edit-order mode.
+MVVM split: `OrderForDropdown.tsx` (view), `useOrderForDropdownViewModel.ts` (state + queries), `types.ts`, `index.ts`. Rendered from `Header.tsx`; hidden in edit-order mode.
 
 - Trigger label: **"Order for Myself"** when ordering for yourself, else **"Order for <Name>"**.
-- Styling matches the Figma export: 18px/12px padding, radius 8, white, **no border in the base state**; a teal `#00B9A8` 1px outline + inset glow `rgba(64,203,190,0.20)` on hover, when open, and when someone other than the signed-in user is picked (`data-active="yes"`).
-- Icons are the **exact Figma SVG paths inlined** (24x24 user, 12.64x6.82 chevron) — not FontAwesome.
+- Teal `#00B9A8` outline + inset glow on hover, when open, and when someone other than the signed-in user is picked (`data-active="yes"`). Icons are the inlined Figma SVG paths, not FontAwesome.
 - Menu: search box → yourself first as **"<Name> (Myself)"** → the user list → **Load more** past 100. Check mark on the current pick. `aria` listbox/option roles, Escape closes and returns focus to the trigger, outside click closes.
 - Copy keys under `orderFor`: `isEnabled`, `label`, `searchPlaceholder`, `myselfLabel`, `loadingMessage`, `noOptionsFoundMessage`, `loadMoreLabel` — in all four COMPASS/ENGLISH role files.
 
 ### 2. There is no "delegation" API — it is the cart's own user list
 
-Verified 2026-09-17 across `toga2-commerce`, `api2`, `_underscore`, `dbchanges2` and the client-sandbox + prod databases (`%elegat%`): **no delegation endpoint or table exists.** api2's `/auth/delegator` is the view-as token, unrelated.
+Verified 2026-09-17 across `toga2-commerce`, `api2`, `_underscore`, `dbchanges2` and the client-sandbox + prod databases: **no delegation endpoint or table exists.** api2's `/auth/delegator` is the view-as token, unrelated (see [view-as-session-tokens](view-as-session-tokens.md)).
 
-The list is the same `GET /users` the cart already uses, via `getUserOptions()` / `getSearchValuesFromAdvancedInput()` in `src/pages/Cart/api/CartApi.ts`:
+The list is the same `GET /users` the cart uses, via `getUserOptions()` / `getSearchValuesFromAdvancedInput()` in `src/pages/Cart/api/CartApi.ts`:
 
 - **Admins** get all active users; server-side search when `CARTPAGE settings.isSearchAnyoneEnabled`.
 - **Supervisors** get their direct reports through the `Users@supervisor` join, filtered locally.
-- Field lists come from the per-tenant `CARTPAGE.ts` (`getUserOptionsFields`, `getSearchValuesFromAdvancedInputFields`), read through `useAssignClientFields(fieldKey, language, user).fields.CARTPAGEFIELDS`.
+- Field lists come from the per-tenant `CARTPAGE.ts`, read through `useAssignClientFields(fieldKey, language, user).fields.CARTPAGEFIELDS`.
 
 Hook queries: `useInfiniteQuery(["orderForDelegationList", user.uuid, fieldKey])` in pages of 100, and `useQuery(["orderForDelegationSearch", user.uuid, fieldKey, text])` debounced 400 ms with a 3-character minimum.
 
-### 3. The hand-off — `useOrderForZu` (decided, CTO-reviewed)
+### 3. `useOrderForZu` — persisted, owner-scoped
 
-The cart owns the cascade: `EditCart.tsx` watches the react-hook-form field `orderFor`, fetches the full user, then sets the sales-quote contact, manager name, cost center and notification emails, and stores the full user in `useSelectedUserZu`. The header **must not duplicate that** (~100 lines) and **must not write `useSelectedUserZu` directly** — the cascade needs the *previous* value and a *full* user object.
+`src/stores/useOrderForZu.ts` uses Zustand `persist` with localStorage key **`order-for-zu`**. Stored shape `{ uuid, name, email, ownerUuid }`, where `ownerUuid` is the **signed-in user's** uuid at pick time. Picking yourself is stored too, so the cart knows to reset.
 
-`src/stores/useOrderForZu.ts` instead holds a hand-off only:
+- `getOrderForUserFor(pick, ownerUuid)` returns the pick **only** when `pick.ownerUuid === ownerUuid`. A different login, or a view-as target, never inherits it. A stale pick (ownerUuid mismatch) is cleared on cart mount.
+- **Cleared only by:** picking yourself in the header · the cart's clear-user action (`CartPage.handleClearUser` → `clearOrderForUser()`) · logout (`AuthContext.logout`).
+- **Kept across:** order submit (`useSubmitOrder.ts`, `createNewSalesOrderSubmit.ts`), edit-order exit (`exitEditOrderModeGlobalSyncReset.ts`), view-as return (`AuthLayout.returnToYourViewOnClick`), and full page reload. The clears that used to live in those four places were removed.
 
-- `pendingOrderForUser: { uuid, name, email, ownerUuid } | null`, **in memory — deliberately no `persist`.** Every flow between a pick and the cart (view-as, login, 401 refresh failure, submit) reloads the page, and the pick must not outlive that.
-- `ownerUuid` is the signed-in user who made the pick. `getPendingOrderForUserFor(pending, ownerUuid)` returns `null` for anyone else, so a view-as switch or a new login can never inherit someone else's pick.
-- `EditCart.tsx` applies the pick to `orderFor` as **"Name (email)"** — the exact label shape the cart's own input produces — then clears the store.
-- An `appliedHeaderPickRef` is set **before** `setValue` and checked **both before and after** the mount seed's `await fetchUserByContactUuid(...)`, so a pick made while that fetch is in flight is not overwritten by the saved contact.
-- Header display order: pending pick (newest) → `useSelectedUserZu.selectedUser` → self.
+### 4. Header ↔ cart sync
 
-**Cleared on:** logout (`src/contexts/AuthContext.tsx`), order submit (`src/pages/OrderDetails/hooks/useSubmitOrder.ts` `clearAllCartStores` and `helpers/createNewSalesOrderSubmit.ts`), cart "clear user" (`CartPage.tsx` `handleClearUser`), leaving view-as (`src/components/AuthLayout/AuthLayout.tsx` `returnToYourViewOnClick`), and leaving edit-order mode (`src/utils/exitEditOrderModeGlobalSyncReset.ts`).
+The cart owns the cascade: `EditCart.tsx` watches the react-hook-form field `orderFor`, fetches the full user, then sets the sales-quote contact, manager name, cost center and notification emails, and stores the full user in `useSelectedUserZu`. The header must **not** duplicate that (~100 lines) and must **not** write `useSelectedUserZu` directly — the cascade needs the *previous* value and a *full* user object.
 
-Rejected: header writes `useSelectedUserZu` directly; header runs its own copy of the cascade.
-
-### 4. Failed user load now clears the cart, not just Sentry
+- `EditCart.tsx` applies the saved pick as **"Name (email)"** (the exact label shape the cart's own input produces) whenever the form's `orderFor` uuid differs from the stored pick. `appliedHeaderPickRef` is set **before** `setValue` and checked **both before and after** the mount seed's `await fetchUserByContactUuid(...)`, so the saved contact cannot overwrite a pick applied while that fetch is in flight.
+- The cart's user-load cascade writes back: `onSuccess` calls `setOrderForUser({ uuid, name: _name, email, ownerUuid: user.uuid })` so header and cart never drift.
+- `onError` calls `handleClearUser()` (required `EditCartTypes` prop passed from `CartPage.tsx`) and raises an error toast from the `CARTPAGE.ts` key `orderFor.settings.loadUserErrorMessage`, with the same string hardcoded as a fallback for tenants without the key.
+- Header display order: stored pick → `useSelectedUserZu.selectedUser` → self.
 
-`singleUsersData.mutate` `onError` in `EditCart.tsx` used to report to Sentry and leave a half-applied order-for. It now calls CartPage's full `handleClearUser()` (new **required** prop `handleClearUser` on `EditCartTypes` in `src/pages/Cart/types.ts`, passed from `CartPage.tsx`) and raises an error toast. Toast copy is the new `CARTPAGE.ts` key `orderFor.settings.loadUserErrorMessage` ("We could not load that user. Please choose the user again.") in the four COMPASS/ENGLISH role files, with the same string hardcoded as a fallback for tenants without the key.
+Rejected: header writes `useSelectedUserZu` directly; header runs its own copy of the cascade.
 
-### 5. e2e spec (written, not run)
+### 5. e2e spec
 
-`cypress/e2e/homePage/orderForDropdown.cy.ts`, Compass tenant only, `compassAdminLogin` + the existing `users?recordsPerPage=**` `bulkUsers` stub. Covers: default trigger shows "Myself"; open → list → pick sets `data-active="yes"`; the pick survives a route change to `/get-support` but **not** a reload (proving the store is in-memory); admin server search stubbed empty asserts "No options found"; picking yourself turns active off; Escape returns focus to the trigger; outside click closes.
+`cypress/e2e/homePage/orderForDropdown.cy.ts` — 4 tests, Compass tenant, **4/4 green**. Asserts the pick survives a route change (via the `account-icon` router Link) and `cy.reload()`, and reads `localStorage['order-for-zu'].state.orderForUser.uuid` / `.ownerUuid` directly.
 
 Test ids: `order-for-dropdown`, `order-for-trigger`, `order-for-current-name`, `order-for-menu`, `order-for-search`, `order-for-option`, `order-for-load-more` (mobile variants add `-mobile`).
 
 ## Gotchas
 
-- **Never `persist` `useOrderForZu`.** A persisted pick survives login, view-as and submit reloads and silently orders for the wrong person. The `ownerUuid` guard is the second line of defence, not a licence to persist.
+- **The `ownerUuid` guard is what makes persistence safe — never drop it.** A persisted pick with no owner check is inherited by the next login or by a view-as target and silently orders for the wrong person. Read the store through `getOrderForUserFor(pick, ownerUuid)`, never raw.
 - **Do not set `useSelectedUserZu` from the header.** The cascade reads the *previous* selected user out of the store (see [cart-notification-emails](cart-notification-emails.md)); writing it early makes the previous-user email cleanup a no-op and strands the old person's notification emails on the order.
-- **A missing `orderFor` key renders nothing, by design.** `useAssignClientFields` has no fallback for a missing key, so Compass Canada and Quad get `undefined` and the component returns `null` — a safe default-off, not a bug. Adding the tenant means adding the key to every role file for that tenant.
+- **A missing `orderFor` key renders nothing, by design.** `useAssignClientFields` has no fallback for a missing key, so Compass Canada and Quad get `undefined` and the component returns `null` — safe default-off. Adding a tenant means adding the key to every role file for that tenant.
 - **`appliedHeaderPickRef` must be checked after the awaited mount fetch too.** Checking only before the `await fetchUserByContactUuid(...)` lets the saved contact overwrite a pick made while the fetch was in flight.
-- **`_production` and `_sandbox-client` have diverged in `EditCart.tsx`** — `_production` lacks the sandbox delegate-manager code, so a stashed patch will not apply cleanly to that file. To move uncommitted work between branches (GitHub Desktop auto-stashes on branch switch as `!!GitHub_Desktop<branch>`): `git diff stash@{0}^1 stash@{0} > patch`, dry-run with `git apply --check --3way patch`, then `git apply --3way --exclude=<conflicting file> patch` and hand-port the conflicting file. Keep the stash until the work is committed.
-- **Tailwind: `max-h-300px` is not a token** (300px exists only on the height/width scales) — use `max-h-[300px]`. `w-345px`, `h-300px`, `border-1` and `shadow-subMenu` do exist.
+- **`_production` and `_sandbox-client` have diverged in `EditCart.tsx`** — `_production` lacks the sandbox delegate-manager code, so a stashed patch will not apply cleanly to that file. To move uncommitted work between branches: `git diff stash@{0}^1 stash@{0} > patch`, dry-run with `git apply --check --3way patch`, then `git apply --3way --exclude=<conflicting file> patch` and hand-port the conflicting file. Keep the stash until the work is committed.
+- **Tailwind: `max-h-300px` is not a token** — use `max-h-[300px]`. `w-345px`, `h-300px`, `border-1` and `shadow-subMenu` do exist.
+
+## Change history
+
+- 2026-09-17 — Pick is now persisted to `localStorage["order-for-zu"]` with an `ownerUuid` guard (TRUE-81852); the submit / edit-order-exit / view-as-return / reload clears were removed, and the cart writes the loaded user back to the store. Spec now 4/4 green. (tcox)
+- 2026-09-17 — Header order-for pill added (TRUE-81851), in-memory hand-off store, cart clears on failed user load. (tcox)
 
 ## Related
 
@@ -103,4 +106,5 @@ Test ids: `order-for-dropdown`, `order-for-trigger`, `order-for-current-name`, `
 - [client-fields](client-fields.md)
 - [cart-notification-emails](cart-notification-emails.md)
 - [cart-page-config-architecture](cart-page-config-architecture.md)
+- [view-as-session-tokens](view-as-session-tokens.md)
 - [cypress-testing](../workflows/cypress-testing.md)

package/knowledge/2.0/apps/toga2-commerce/features/view-as-session-tokens.md

@@ -0,0 +1,90 @@
+---
+title: View-as another user — parked admin tokens & return-to-self
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-09-17
+owners: [tcox]
+files:
+  - src/api/sessionTokens.ts
+  - src/api/apiBaseUrl.ts
+  - src/api/axiosInstance.ts
+  - src/contexts/AuthContext.tsx
+  - src/components/AuthLayout/AuthLayout.tsx
+  - src/components/NavIcons/NavIconList.tsx
+  - cypress/e2e/viewAs/viewAsUser.cy.ts
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - 2.0/apps/toga2-commerce/features/header-order-for-dropdown.md
+  - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
+  - 2.0/apps/api2/architecture.md
+---
+
+How an admin impersonates another user and gets back: the delegated token pair, the parked admin pair in localStorage, and the return path. Open before touching auth tokens, the axios refresh, or the view-as button.
+
+## Summary
+
+TRUE-81852 (commit `a8c3a537`). An admin can browse the storefront **as** another user. Previously, returning to yourself re-minted the admin's tokens through the privileged `/auth/encrypted` call. Now the admin's **own** token pair is parked in localStorage when delegation starts and put back on return — `/auth/encrypted` is no longer called on return at all.
+
+All token plumbing lives in **`src/api/sessionTokens.ts`** (new). `src/api/apiBaseUrl.ts` (new) exports `apiBaseUrl` so both the axios instance and the token helpers resolve the same host. `src/utils/auth.ts` and `handleClientAuthentication` / `UserData` in `Login/api/LoginApi.tsx` were dead and were deleted.
+
+## How it works
+
+### Entering view-as (`NavIconList.tsx` onSuccess)
+
+1. `fetchUserTokens(uuid, "/auth/delegator")` mints the delegated pair for the target user.
+2. `beginDelegation(delegatedPair, adminUuid)` parks the admin's current pair under localStorage key **`originalAuthTokens`** as `{ v: 1, access, refresh, userUuid, apiHost, savedAt }`, then writes the delegated pair into `accessToken` / `refreshToken`.
+3. It **never overwrites an existing parked pair** — view-as is one level deep. `isViewAsEnabled` also hides the button when `hasSavedOriginalTokens()` is true.
+4. On any error entering view-as, it rolls back: `restoreOriginalTokens` if a pair is parked, plus `clearOriginalUser()`.
+
+### Returning (`AuthLayout.returnToYourViewOnClick`)
+
+`restoreOriginalTokens(adminUuid)`:
+
+1. Checks `userUuid` **and** `apiHost` match, and age ≤ `PARKED_PAIR_MAX_AGE_MS` (**12h**). It **always removes** the parked key, pass or fail.
+2. On success: puts the admin pair back; if the access JWT is expired (`isAccessTokenExpired` decodes `exp`), calls `refreshAuthTokens()` once **before** the cache clear.
+3. On failure: logs a Sentry warning, clears the view-as store, logs out, navigates to `/`. There is **no** `/auth/encrypted` fallback.
+4. Removes `localStorage["commerce"]` (the persisted react-query cache) so the impersonated user's rows cannot rehydrate under the admin.
+
+### Where else the parked pair is cleared
+
+`login()` clears it (and the view-as store) first; `fetchPublicToken` and `performLogout` clear it; module load sweeps it when there is no `accessToken`.
+
+### Refresh safety (`axiosInstance.ts`)
+
+The 401 refresh is **single-flight** (one module-level promise shared by concurrent 401s) and **identity-bound**: `requestRefreshedTokens` returns `null` if `localStorage.refreshToken` changed while the refresh was in flight. That stops an in-flight admin refresh from overwriting a just-minted delegated pair (or the reverse).
+
+### Decisions (CSO review — SHIP WITH FIXES)
+
+Identity-bound refresh · one-level view-as · 12h max parked age · no `/auth/encrypted` fallback (log out instead) · never put error objects in `JSON.parse` failure logs · match on `apiHost` only (clientId dropped).
+
+### e2e (`cypress/e2e/viewAs/viewAsUser.cy.ts`)
+
+Seeds a long-lived `ADMIN_ACCESS_JWT`; stubs `/auth/delegator` → `mock-delegated-access-token` / `-refresh`, and `**/v2/pages/meta?page=home-page&app=commerce*`; the fetchUser stub matches on a RegExp over the `?fields=uuid,_name,...` list. Asserts: delegated pair active + parked pair present; after return, `accessToken === ADMIN_ACCESS_JWT`, parked key null, and **zero** calls to `/auth/encrypted`. 1/1 green.
+
+## Gotchas
+
+- **Never re-mint the admin's tokens on return.** The old `/auth/encrypted` path was a privileged call made from the browser. Restore the parked pair, or log out — those are the only two outcomes.
+- **Always remove `originalAuthTokens`, even on a failed restore.** Leaving a stale parked pair blocks the next view-as (`beginDelegation` refuses to overwrite) and keeps an old admin refresh token on disk.
+- **Clear `localStorage["commerce"]` on return.** The persisted query cache is shared; without the clear, the impersonated user's data rehydrates under the admin identity (see the 24h persisted-cache gotcha in [architecture](../architecture.md)).
+- **Keep the refresh identity-bound.** A refresh that resolves after the identity changed must return `null`, not write tokens.
+- **A view-as test must stub `/v2/pages/meta?page=home-page&app=commerce`.** Unstubbed, the real call fails and triggers the enter-view-as rollback, so the spec sees a return-to-admin it did not ask for.
+
+## Open items (out of ticket, not fixed)
+
+- `SENTRY_AUTH_TOKEN` is committed in 25 tracked `.env*` files — treat it as compromised and rotate it. (Never store the value in this KB.)
+- Confirm api2 authorizes `/auth/delegator` **server-side** as admin-only; the client-side gate is not a control.
+
+## Change history
+
+- 2026-09-17 — Created. Admin pair parked in `originalAuthTokens` on delegation and restored on return; `/auth/encrypted` re-mint removed; single-flight identity-bound refresh (TRUE-81852, commit a8c3a537). (tcox)
+
+## Related
+
+- [architecture](../architecture.md)
+- [header-order-for-dropdown](header-order-for-dropdown.md)
+- [cypress-testing](../workflows/cypress-testing.md)
+- [api2 architecture](../../api2/architecture.md)

package/knowledge/2.0/apps/toga2-commerce/workflows/cypress-testing.md

@@ -11,12 +11,12 @@ owners: [tcox]
 files:
   - toga2-commerce/cypress/e2e/cartPage/cartV2.cy.ts
   - toga2-commerce/cypress/e2e/homePage/orderForDropdown.cy.ts
+  - toga2-commerce/cypress/e2e/viewAs/viewAsUser.cy.ts
   - toga2-commerce/cypress/fixtures/cart/fetchUserShippingMethods.json
   - toga2-commerce/cypress/support/commands.ts
   - toga2-commerce/cypress/support/e2e.ts
   - toga2-commerce/src/pages/Cart/CartPage.tsx
   - toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx
-  - toga2-commerce/src/pages/Cart/view/cartForm/CartFormSection.tsx
   - toga2-commerce/src/pages/Cart/view/cartTable/CartContentsTable.tsx
   - toga2-commerce/src/pages/Cart/view/cartTable/CartTableItem.tsx
   - toga2-commerce/src/components/Inputs/AdvancedInput.tsx
@@ -27,6 +27,7 @@ related:
   - 2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - 2.0/apps/toga2-commerce/features/cart-bundle-submission-and-identity.md
   - 2.0/apps/toga2-commerce/features/header-order-for-dropdown.md
+  - 2.0/apps/toga2-commerce/features/view-as-session-tokens.md
   - 2.0/apps/toga25-supply/workflows/cypress-testing.md
 ---
 
@@ -100,7 +101,12 @@ The cart UI was instrumented with `data-testid` attributes so specs anchor on **
 
 ### Other active specs
 
-- `cypress/e2e/homePage/orderForDropdown.cy.ts` (2026-09-17, branch `TRUE-81851`) — the header order-for pill; COMPASS only, `compassAdminLogin` + the existing `users?recordsPerPage=**` `bulkUsers` stub. **Written and type-checked but never executed** — run it before trusting it. Ids `order-for-*` (see [header-order-for-dropdown](../features/header-order-for-dropdown.md)).
+- `cypress/e2e/homePage/orderForDropdown.cy.ts` — the header order-for pill, COMPASS only, 4 tests, **4/4 green**. Asserts the pick survives a route change and `cy.reload()` by reading `localStorage['order-for-zu']`. Ids `order-for-*` (see [header-order-for-dropdown](../features/header-order-for-dropdown.md)).
+- `cypress/e2e/viewAs/viewAsUser.cy.ts` — admin view-as enter/return, **1/1 green**. Seeds a long-lived admin JWT, stubs `/auth/delegator` and `**/v2/pages/meta?page=home-page&app=commerce*` (see [view-as-session-tokens](../features/view-as-session-tokens.md)).
+
+### Known-red specs (pre-existing, not yours)
+
+On prod base `aedd1f7a`, Compass tenant: **13 failures** — `getSupportV2` (4), `homePageContentV2` (7), `firstTimeLoggingIn` (2). Reproduced identically on an untouched `git archive aedd1f7a` copy, so they are **not** caused by feature work. Likely cause: the login command's `/users/{uuid}` stub field list no longer matches the app's request, so the call falls through to the real API and 401s. Full Compass suite on the TRUE-81852 feature branch: **54 pass / 13 fail** — the same 13.
 
 **Not yet covered — slice 2 work-list:**
 - **Bundle scenarios** — blocked on the stale bundle seeds (rebuild `seedCartBundle` / `seedSalesQuoteBundle` first, above).
@@ -114,13 +120,24 @@ The cart UI was instrumented with `data-testid` attributes so specs anchor on **
 2. Start the **dev server separately** first: `npm run compass` | `npm run compasscanada` | `npm run quad`.
 3. **Windows invocation:** `$env:TENANT="compass"; npm run cypress` — `cross-env` is **not** installed, so set the env var in the shell.
 4. Requires **hosts-file entries** `127.0.0.1 compass|compasscanada|quad.togacommerce` (present on this machine but **undocumented in the README** — a new dev must add them).
+5. Headless run (works despite there being no npm script): `Remove-Item Env:ELECTRON_RUN_AS_NODE` first (see gotcha), then `$env:TENANT="compass"; npx cypress run --env TENANT=compass` with vite dev serving `http://compass.togacommerce:5173`.
 
 ## Gotchas
 
+- **`ELECTRON_RUN_AS_NODE=1` breaks every spec in a VS Code terminal.** VS Code's integrated terminals set it, and `npx cypress run` then fails verification on every spec with `Cypress.exe ... bad option: --smoke-test`. Fix: `Remove-Item Env:ELECTRON_RUN_AS_NODE` in that shell before running. Reinstalling the Cypress binary does **not** help.
+- **The users API URL-encodes hyphens as `%2D`.** A glob like `**/v2/users?*no-such*` never matches — use a hyphen-free search term in the test, or match with a RegExp.
+- **"Get Support" in the header is a plain `<a>`** (full page reload). To test that state survives a *route change*, click `account-icon` — that one is a router `Link`.
+- **The `EnvironmentBadge` covers the header corner.** For outside-click tests, click `header-search-input` instead of the corner.
+- **A later `cy.intercept` wins over an earlier one for the same URL** — define the narrow override after the general stub, not before.
 - **`BaseButton` never sets the native `disabled` attribute (test-critical).** `src/components/BaseButton/BaseButton.tsx` sets `aria-disabled="true"|"false"` and suppresses `onClick` inside `handleClick` — it deliberately leaves the element enabled so a disabled button (e.g. **Proceed to Checkout**) still receives mouse events and its `BaseTooltip` (*"Please complete all required fields to proceed."*) works. Cypress assertions **MUST** use `.should('have.attr', 'aria-disabled', 'true'|'false')`, **never** `.should('be.disabled')` — `be.disabled` times out even though the button is visually/functionally disabled. (This cost the only 2 first-run failures.)
 - **Seed → then `cy.visit('/cart')`.** The persist stores rehydrate on load only; seeding `localStorage` and navigating in-app leaves the stores stale (see seeding section).
 - **Bundle seeds are on the legacy shape** — do not write a bundle spec against them until they are rebuilt to the `bundleZuCartUuid` + `bundleProgressContents` contract.
-- **ESLint fails repo-wide in a fresh checkout** because `.eslintrc.cjs` references `eslint-plugin-react-compiler`, which is not installed; `npm install --save-dev eslint-plugin-react-compiler` fixes it. To lint without touching the checkout, run `eslint --no-eslintrc` with the `react-hooks` and `no-unused-vars` rules instead. This is a local-environment issue, not a spec problem.
+- **ESLint fails repo-wide in a fresh checkout** because `.eslintrc.cjs` references `eslint-plugin-react-compiler`, which is not installed; `npm install --save-dev eslint-plugin-react-compiler` fixes it. To lint without touching the checkout, run `npx eslint --no-eslintrc --plugin react-hooks --plugin @typescript-eslint <files>`. This is a local-environment issue, not a spec problem.
+
+## Change history
+
+- 2026-09-17 — Added `viewAsUser.cy.ts`; orderForDropdown now green; recorded the `ELECTRON_RUN_AS_NODE` failure, the intercept pitfalls, and the 13 pre-existing red specs on base `aedd1f7a`. (tcox)
+- 2026-09-17 — Created with the V2 convention set and the `cartV2.cy.ts` cart harness (slice 1). (tcox)
 
 ## Related
 
@@ -128,4 +145,6 @@ The cart UI was instrumented with `data-testid` attributes so specs anchor on **
 - [cart-notification-emails](../features/cart-notification-emails.md)
 - [expedited-shipping-gating](../features/expedited-shipping-gating.md)
 - [cart-bundle-submission-and-identity](../features/cart-bundle-submission-and-identity.md)
+- [header-order-for-dropdown](../features/header-order-for-dropdown.md)
+- [view-as-session-tokens](../features/view-as-session-tokens.md)
 - [toga25-supply Cypress harness](../../toga25-supply/workflows/cypress-testing.md)

package/knowledge/INDEX.md

@@ -31,7 +31,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos-backend** (TOGa IQ Backend) — 1 doc(s) → [2.0/apps/talos-backend/INDEX.md](2.0/apps/talos-backend/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 23 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 24 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 21 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 14 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.846",
+  "version": "1.0.847",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",