toga-ai 1.0.874 → 1.0.876

package/knowledge/clients/nychh/features/transfer-order-notification-emails.md

@@ -6,8 +6,8 @@ project: Worker
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-18
-owners: ["bala"]
+updated: 2026-09-23
+owners: ["bala", "rgirish"]
 files:
   - worker2/Worker/Client/Nychh/TransferOrderEmails.php
   - _underscore/Model/Nychh/TransferOrder.php
@@ -211,9 +211,23 @@ Cost of the split, stated so nobody is surprised later:
   templates and the tracking line are Plus Jakarta Sans. Outlook gets Arial inside an
   `<!--[if mso]-->` block because it cannot load web fonts.
 - **Detail box:** *Site Contact* falls back to the person who raised the order — 3 of the 6 supply
-  orders in prod have no contact, and that is the same fallback the greeting already used. And
-  `CONCAT_WS` skips NULL but **not** an empty string, so a blank address line 2 produced
-  `451 Clarkson Ave , Brooklyn`; every part is `NULLIF`'d before joining.
+  orders in prod have no contact. (The greeting used to share that fallback; since 2026-09-23 it
+  runs the other way round — see below.) And `CONCAT_WS` skips NULL but **not** an empty string, so
+  a blank address line 2 produced `451 Clarkson Ave , Brooklyn`; every part is `NULLIF`'d before
+  joining.
+- **The greeting addresses the SUBMITTER, the detail box shows the CONTACT.** They are two different
+  people and the email shows both:
+
+  | Slot | Source column | Shape |
+  |---|---|---|
+  | `greetingName` ("Hi …,") | `CreatedByUsers.firstName` → `submittedByFirstName`, falling back to `Contacts.firstName` | **first name** |
+  | *Site Contact* row | `Contacts.firstName`+`lastName` → `siteContactName`, falling back to `submittedByName` | full name |
+  | *Submitted by* row | `CreatedByUsers.firstName`+`lastName` → `submittedByName` | full name |
+
+  Both greeting sources must be **`firstName` columns**. The original fallback was
+  `contactFirstName ?: submittedByName`, and `submittedByName` is the `CONCAT_WS` **full** name — so
+  an order with no contact greeted *"Hi Carol Ann Rosado,"*. Never fall back from a first-name slot
+  to a `…Name` full-name alias.
 
 ## Gotchas / known issues
 
@@ -247,6 +261,15 @@ unescaped values and both detail-box defects were all found there, not in produc
 
 ## Change history
 
+- 2026-09-23 — **The greeting now addresses whoever raised the order, not the site contact.**
+  `readTransferOrderForEmail()` selects `CreatedByUsers.firstName AS submittedByFirstName`, and
+  `greetingName` flipped from `contactFirstName ?: submittedByName` to
+  `submittedByFirstName ?: contactFirstName`. Found live: an order raised by Carol Ann Rosado
+  opened *"Hi Shehu,"* — the site contact. Fixing the order of preference also fixed a second
+  latent bug: the old fallback reached for `submittedByName`, the **full** name, so it could render
+  *"Hi Carol Ann Rosado,"*; both sides of the fallback are now first-name columns. *Site Contact*
+  and *Submitted by* in the details box are unchanged. (worker2 `ed6d566` on `_production`)
+  (rgirish)
 - 2026-09-18 — **Moved the whole feature out of `_underscore` into worker2.** Deleted
   `_Trait_Nychh_TransferOrderEmail`; `worker2/Worker/Client/Nychh/TransferOrderEmails.php` now holds
   the queued `SendSubmitted` / `SendFulfillment` entry points, the `SendPending` cron, every query

package/knowledge/sessions/2026-09-23-commerce-sso-and-cache-apeterson.md

@@ -0,0 +1,212 @@
+---
+type: session
+slug: commerce-sso-and-cache
+title: Commerce persisted-cache, session-gating and SSO sign-in screen
+author: apeterson
+repos: [toga2-commerce]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-09-23
+updated: 2026-09-23
+---
+
+# Session: commerce-sso-and-cache
+**Date:** 2026-09-23
+**Project/Repo:** toga2-commerce (2.0), branch `TRUE-81991`
+**Task:** Implement the 2026-09-03 cache-diagnosis plan in toga2-commerce, then build an SSO sign-in screen for SSO tenants and consolidate how the app decides someone is signed in.
+
+---
+
+## What WORKED
+
+**The 2026-09-03 plan, implemented and verified.**
+- App default `staleTime` 24h → `0` plus `refetchOnWindowFocus: false` (`src/App.tsx`); heavy hooks
+  got `staleTime: 30_000` + `gcTime: 1h` (`src/pages/BundleView/hooks/useBundleQueryData.ts:26,42`,
+  `src/pages/Home/viewModel/useHomeViewModel.ts:150,175,201`). Evidence: `npx tsc --noEmit -p
+  tsconfig.app.json` exit 0 and `npx vite build` succeeded after each change.
+- `src/lib/queryCacheRestoration.ts` (new) — every cache clear now waits for restoration, cancels
+  in-flight queries, then clears; capped at 1.5s; an epoch counter makes a superseded clear no-op.
+  Persister set to `throttleTime: 0` (the 1000ms default let a queued write land AFTER the clear).
+- `src/lib/authStorage.ts` (new) — one `AUTH_STORAGE_KEYS` list used by BOTH logout paths, and by
+  `resetClientState()` which now runs on login as well as logout.
+- Build-id `buster` via `__BUILD_ID__` (`vite.config.ts` `define`, declared in `src/vite-env.d.ts`).
+  Verified in the bundle: 0 unresolved `__BUILD_ID__` occurrences, the `"dev"` literal present once.
+
+**Real bugs found and fixed (each confirmed in source before changing anything).**
+- `AUTH_STORAGE_KEYS` contained `"zu-cart-store"`, which is not a real key — the cart persists under
+  `"zu-cart"` (`src/stores/useCartStoreZu.ts:956`). The previous user's cart survived a 401 logout.
+- Clearing a persisted key is not enough: the zustand store must ALSO be reset in memory or the next
+  `set()` re-persists the old user's state. Added a `clearSettingsModal` action (that store had none)
+  and wired `useBundleBuilderZu` / `useUserStore` resets into `resetClientState()`.
+- `fetchPublicToken()` wrote the ANONYMOUS token to `localStorage` under `"accessToken"` — the same
+  key a real login writes — so every "is there an accessToken?" check was true for a logged-out
+  visitor. Root-caused: the public token is now a module variable in `src/api/axiosInstance.ts`,
+  never stored, and its refresh token is not stored at all.
+- The 401 handler gated logout on `"zu-user"`, a zustand store that clears itself independently. With
+  that key gone but the session live, logout was skipped and the app sat looping on 401.
+
+**Security fixes (all found by the `cso` reviewer, all verified in source).**
+- Open redirect on the post-auth return path (`src/utils/postAuthRedirect.ts`). Visiting
+  `https://<tenant>//evil.com` gives `pathname === "//evil.com"`, which the browser treats as
+  protocol-relative — so after a SUCCESSFUL login the user went to another origin with a live
+  session. Now only a single-slash same-origin path is stored or restored.
+- `window.location.href = ssoUrl` with no scheme check. Now must be `https:`, checked where fetched
+  AND at the click; a bad value means "not SSO" so the tenant falls back to the credential form.
+- Token refresh could run under the wrong identity. Made single-flight, then identity-scoped with an
+  epoch in `src/lib/session.ts` bumped on sign-in, sign-out and view-as, plus a second guard
+  comparing the stored refresh token.
+- View-as swap stored `response?.data.tokens.access` with only `response` optional-chained — a
+  malformed reply wrote the literal string `"undefined"` (truthy), so the app sent `Bearer undefined`
+  on every call. Now both tokens are validated and the session is left untouched on a bad reply.
+
+**SSO sign-in screen built.** Detection already existed inside `useAuthenticationFlow` as a mutation
+that jumped straight to the IdP — the user never saw a page. Extracted to `src/hooks/useClientSsoUrl.ts`
+(React Query, so the auth flow and the login page share one cached answer). `/login` now renders
+`src/pages/Login/view/SsoSignIn.tsx` for SSO tenants, else the credential form. Design came from the
+Claude Design project "TOGa Supply - SSO Sign In", rebuilt with commerce's own logo, theme tokens and
+per-tenant FIELDS copy. Every logout path already lands on `/login`, so SSO users get the SSO screen
+on sign-out with no extra code — verified by reading `src/routes.tsx`, NOT by running it.
+
+**First unit-test harness in the repo.** vitest + jsdom, `npm test` / `npm test:watch`,
+`vitest.config.ts`. 19 tests pass. Each was proven to fail on the pre-fix code first: reverting
+`hasSession` turned **5 red**; removing the single-flight and identity guards turned **3 red**
+(including both race tests). Race tests use a held-open promise, not real timing, so no flake.
+
+---
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **Falling back to the anonymous token when a session exists but `accessToken` is missing.** I wrote
+  this thinking it fixed "a 401 with no explanation". It is backwards — the 401 IS the point. The
+  `cso` agent confirmed against api2 (`Component/Api/V2/V2.php:578-598`): `/auth/public` mints a
+  FULLY VALID JWT carrying `KEY_PUBLIC_ROLE`, and its client comes from the **Domains row, not the
+  user**. So the request would NOT 401 — it would return 200 with public-scoped rows (or `EZ-1`),
+  the refresh/logout path would never fire, and the tab would stay silently anonymous under a real
+  session. On a domain whose `clientId` differs from the signed-in user's, a write could land in the
+  wrong tenant's database. **Reverted.** A live session with no `accessToken` must send NO
+  `Authorization` header so it 401s.
+- **`hasSession()` as `Boolean(localStorage.getItem("user"))`.** Too loose — `"{}"`, `"null"` or a
+  half-written value booted the app into the signed-in state with no identity behind it. It must
+  parse and require a `uuid`. (This is one of the 5 tests that goes red on the loose version.)
+- **Anchoring the SSO footer inside the form column.** It only worked by accident of the nearest
+  positioned ancestor, and escaped the `xl:w-96` width. The footer belongs to the left PANEL — it is
+  now `SsoSignInFooter`, rendered as a sibling of the form column.
+- **Prefixing every per-session localStorage key so logout can clear by prefix.** My idea; the `cto`
+  agent rejected it with a concrete reason: renaming every zustand `persist` name silently orphans
+  every existing user's persisted state on deploy, and touches every `localStorage.getItem("zu-user")`
+  call site scattered through `src/api/`. Cheaper answer, which supply already uses: plain
+  `localStorage.clear()` on logout, since every key commerce writes is session state.
+- **`grep --include=*.ts` under zsh** fails with "no matches found" when the glob is unquoted —
+  quote it (`--include="*.ts"`). Cost two wasted tool calls.
+- **Python string-replace edits against this repo assuming space indentation.** Source is TABS, and
+  one line in `axiosInstance.ts` had a trailing-space blank line. Two `AssertionError`s before I
+  matched the real bytes. Check with `sed 's/\t/<TAB>/g'` first.
+
+---
+
+## Not tried yet (candidates for next session)
+
+1. **Compass Canada production SSO** — `https://compasscanada.togacommerce.com/home` sends users to
+   the credential form though the client uses SSO. Diagnostic SQL was handed over, NOT run. Candidate
+   causes in order: no `Domains` row matching the exact `https://compasscanada.togacommerce.com`
+   string; no `ClientAuthentications` row for that `clientId`+`environmentId`; `type` not the literal
+   `'SSO'`; or the PUBLIC role lacking `AclFieldPermissions` to read `ClientAuthentications.type`
+   (the call runs pre-login on the public token, so a null field fails silently). Note the production
+   build is plain `vite build` with NO `--mode`, so `MODE` is `production` and the query asks for
+   `Environments.slug LIKE 'PRODUCTION'`.
+2. **blox `fetchPublicToken` defect** (`toga-blox-npm/src/api/auth.ts:48-60`) — same bug commerce just
+   fixed locally; supply works around it in three places. Needs its own ticket; do NOT bundle it.
+3. **CTO-ranked, not done:** replace the `window.history.pushState`/`replaceState` monkey-patch in
+   `AuthContext.tsx` with supply's poll-on-interval + focus (Sentry patches history too, so the
+   cleanup can clobber it); make `login()` fail loudly instead of swallowing errors after tokens are
+   already written.
+4. **Narrow the core-parameters forced logout** to `META_LAST_REFRESH_DATETIME` only (it currently
+   compares the WHOLE `/core-parameters` blob, so any parameter edit logs out every user) and add
+   supply's notice toast.
+5. **Constrain the SSO URL's HOST**, not just its scheme, to the tenant's configured IdP domain. No
+   allowlist source exists today.
+6. **Unanswered since 2026-09-03:** do commerce bundle/item payloads carry prices or stock counts? If
+   they do, those queries need their spinner on `isFetching`, not `isLoading`.
+7. Point `performLogout` and the core-parameters logout at `/login` directly instead of `/`, to remove
+   the brief blank screen while `AuthRedirect` renders nothing.
+
+---
+
+## Current file state
+
+All work is on branch `TRUE-81991` in `toga2-commerce`, as three commits.
+`e546db3d` is pushed; **`93616f20 "Save"` and `fd92de42 "Save"` are LOCAL ONLY** and were made by the
+developer, not by Claude. Working tree otherwise clean (only `.env.development` modified, unrelated).
+
+| File | Status | Notes |
+|------|--------|-------|
+| `src/lib/session.ts` | new | `hasSession()` (parses `user`, requires a uuid, storage read inside the try) + the identity epoch |
+| `src/lib/session.test.ts` | new | 11 tests; 5 go red if `hasSession` is loosened |
+| `src/lib/authStorage.ts` | new | `AUTH_STORAGE_KEYS` + `clearAuthStorage()`, shared by both logout paths |
+| `src/lib/queryCacheRestoration.ts` | new | restoration gate, `clearPersistedQueryCache()`, epoch guard, 1.5s cap |
+| `src/hooks/useClientSsoUrl.ts` | new | `/domains` + `singleSignOnServiceUrl` lookup, `isSafeSsoUrl` https check |
+| `src/pages/Login/view/SsoSignIn.tsx` | new | SSO panel + `SsoSignInFooter` (footer is a sibling of the form column) |
+| `src/api/refreshAuthTokens.test.ts` | new | 8 tests; 3 go red without the single-flight + identity guards |
+| `vitest.config.ts` | new | jsdom, `src/**/*.test.ts` |
+| `src/api/axiosInstance.ts` | modified | in-memory public token, single-flight + identity-scoped refresh, `hasSession()` gates, `clearPublicToken()` |
+| `src/contexts/AuthContext.tsx` | modified | `resetClientState()` on login AND logout, async `logout()`, storage listener uses `hasSession()` only |
+| `src/hooks/useAuthenticationFlow.ts` | modified | SSO lookup removed; navigates to `/login`; gates on `hasSession()` |
+| `src/pages/Login/LoginPage.tsx` | modified | branches to the SSO panel; left panel is now `relative` |
+| `src/pages/Cart/api/CartApi.ts` | modified | view-as token validation + epoch bump + `clearPublicToken()` |
+| `src/utils/postAuthRedirect.ts` | modified | `isSafeDestination()` blocks the protocol-relative open redirect |
+| `src/stores/useSettingsModalStore.ts` | modified | added `clearSettingsModal` |
+| `src/App.tsx` | modified | `staleTime: 0`, `refetchOnWindowFocus: false`, `buster`, `throttleTime: 0` |
+| `vite.config.ts` / `src/vite-env.d.ts` | modified | `__BUILD_ID__` define + declaration |
+| `src/pages/Login/viewModel/FIELDS/LOGINDUMMYFIELDS.json` | modified | `SSOSECTIONFIELDS` (button, loading, copyright) |
+| `package.json` / `package-lock.json` | modified | vitest + jsdom devDeps, `test` scripts. Blox pin untouched at `1.1.1-production.139` |
+
+---
+
+## Decisions made
+
+- **`gcTime`, not `staleTime`, is the speed knob.** React Query paints cached data instantly whatever
+  `staleTime` says, and commerce gates every spinner on `isLoading` (false when cached data exists) —
+  so lowering `staleTime` costs no spinner. Rejected: keeping the 24h `staleTime` "for speed".
+- **One `hasSession()` predicate.** Four sites decided this off three different keys with three
+  different predicates, and the disagreements WERE the bugs. Rejected (CTO advice): collapsing `user`
+  and `zu-user` into one store — ~15 files, no user-visible gain. Unify the predicate, not the storage.
+- **`hasSession()` is a routing/UI signal only, never an authorization check.** The value is
+  user-writable; api2 enforces every permission server-side. Noted in the file so it does not drift.
+- **Keep tokens in `localStorage`.** api2 is Bearer-only with no cookie session; switching means
+  backend work plus CSRF protection that does not exist. Matches `2.0/standards/frontend.md` §12.
+- **SSO tenants land on `/login` and click through, rather than auto-redirecting.** Developer's call.
+  `/login` IS the SSO page — the same URL decides which screen to show.
+- **Commerce keeps its own FIELDS copy and theme**, not the Supply wording/art from the design.
+  Developer's call. Deviations from the mockup were listed rather than silently absorbed.
+- **Fix the public-token bug app-local, not in blox.** Per the app-level-over-core rule; the blox fix
+  changes behavior for every consumer and needs its own review.
+- **Dropped the `?ssoPreview=1` dev switch** at the developer's request after using it to verify the
+  screen. The `isSafeSsoUrl` https check stayed — that is a security fix, not test code.
+
+---
+
+## Blockers
+
+- **Compass Canada production SSO is broken and the cause is unconfirmed.** The diagnostic SQL has
+  not been run. Until the `/domains` lookup returns SSO for that tenant, the new screen cannot be
+  seen there — and it cannot be seen locally either, since the dev preview switch was removed.
+- **`93616f20` and `fd92de42` are unpushed local commits** with generic "Save" messages. They need
+  real commit messages (or a squash) before a PR.
+- The mid-session checkout moved to `_production` and back; the work was never lost, but confirm
+  `git branch --show-current` is `TRUE-81991` before doing anything.
+
+---
+
+## Exact next step
+
+> Run the Compass Canada diagnostic against the **Core production** database — the `SELECT` joining
+> `Core.Domains` → `Core.Environments` → `Core.Clients` → `Core.ClientAuthentications` filtered on
+> `d.domain LIKE '%compasscanada%'`. Read the result against four causes in order: no row / wrong
+> `domain` string, `authType` NULL (no `ClientAuthentications` row for that clientId+environmentId),
+> `authType` not the literal `'SSO'`, or — if the data is right — the PUBLIC role missing
+> `AclFieldPermissions` on `ClientAuthentications.type`, which you check by opening the site in a
+> private window and looking at the `/v2/domains` response in the Network tab.
+
+---
+_Saved by /session-save on 2026-09-23_

package/package.json

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