toga-ai 1.0.59 → 1.0.60

package/knowledge/2.0/apps/_underscore/architecture.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-06-09
-owners: [jcardinal]
+updated: 2026-06-11
+owners: ["jcardinal", "rgirish"]
 files:
   - _underscore/_underscore.php
   - _underscore/Loader.php
@@ -273,3 +273,10 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
 | `_Database` / `_Query` | Connection pool + read/write routing / MySQLi wrapper with caching |
 | `_Route` / `_Component` | URI router / HTML component renderer |
 | `_Config` / `_Environment` / `_Loader` / `_Http` / `_Error` | config, env/debug, autoload, JWT/HTTP, errors |
+
+## Gotchas / known issues
+
+- **`_Database::register()` auto-starts a lazy transaction (since Apr 2 2026, commit `fa7835ed`).** Any code that calls `register()` and then writes to that DB must call `_Database::transactionCommit()` before the request ends — otherwise MySQL silently rolls back all writes when the connection closes. Lazy transactions only materialise on the first write, so read-only callers are unaffected. See `_underscore/Database.php:48`. First discovered when Rate SAML user provisioning silently discarded all new user INSERTs (Jun 2026).
+
+## Change history
+- 2026-06-11 — Documented lazy transaction gotcha in `_Database::register()` (rgirish)

package/knowledge/2.0/apps/saml/INDEX.md

@@ -0,0 +1,6 @@
+# saml (SAML SSO Gateway) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [saml Architecture](architecture.md) | The `saml` repo is the SAML 2.0 / SSO gateway for all TOGa applications. | saml/index.php, saml/_.php, saml/Controller/Index.php, saml/Config/production.ini, saml/.platform/hooks/prebuild/git.sh, saml/.ebextensions/git.php |
+| [Rate SAML User Provisioning](features/rate-user-provisioning.md) | When a Rate user authenticates via SSO, `_Model_Rate_ClientAuthentication::getAuthenticatedSsoUser()` is called by the saml gateway. | _underscore/Model/Rate/ClientAuthentication.php, _underscore/Model/Rate/User.php, _underscore/Model/Rate/Customer.php, _underscore/Model/Rate/Contact.php |

package/knowledge/2.0/apps/saml/architecture.md

@@ -0,0 +1,88 @@
+---
+title: saml Architecture
+framework: "2.0"
+repo: saml
+project: SAML SSO Gateway
+client: shared
+type: architecture
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files:
+  - saml/index.php
+  - saml/_.php
+  - saml/Controller/Index.php
+  - saml/Config/production.ini
+  - saml/.platform/hooks/prebuild/git.sh
+  - saml/.ebextensions/git.php
+related:
+  - 2.0/apps/_underscore/architecture.md
+---
+
+## Summary
+
+The `saml` repo is the SAML 2.0 / SSO gateway for all TOGa applications. It acts as the
+SAML **Service Provider (SP)** — customer Identity Providers (IdPs: Azure AD, Compass,
+Rate, Prudential, etc.) POST authentication assertions here. The gateway validates the
+assertion, maps the identity to a TOGa user, and redirects the browser back to the
+requesting TOGa app with an encrypted auth handoff payload.
+
+Built on the `_underscore` PHP framework. Deployed on AWS Elastic Beanstalk (us-east-1).
+
+## Entry point & routing
+
+All requests rewrite to `index.php` via `.htaccess`. `_.php` sets
+`DEFAULT_CONTROLLER_METHOD = ['_Controller_Index', 'saml']`. Sub-routes:
+
+| Path | Purpose |
+|---|---|
+| `/meta` | SP metadata XML — IdPs consume this to configure the integration |
+| `/acs` | Assertion Consumer Service — receives IdP SAMLResponse + RelayState POST |
+| `/sls` | Advertised in metadata but not implemented |
+| *(default)* | Echoes `TOGaHub SAML SSO receiver` |
+
+Legacy `/?meta`, `/?acs`, `/?sls` query-style paths are rewritten automatically.
+
+## /acs flow
+
+1. **RelayState decryption** — `_String::decryptWithKey()` with `API_SECRET_ACCESS_TOKEN`; retries with `_PREVIOUS` for rotation window support.
+2. **Version + time check** — RelayState JSON: `v` (currently `1`), `time`, `domain` UUID, optional `urlParameters`. Validated against `MAX_TIME_TO_LIVE` (300s).
+3. **Parse SAMLResponse** — base64-decoded, deserialized via LightSaml.
+4. **Status check** — proceeds only on `STATUS_SUCCESS`.
+5. **Assertion decryption** — TOGa SP credential from `_underscore/Assets/ssl/`.
+6. **Resolve client + environment** — `_Model_Core_Domain` by RelayState `domain` UUID → `_Model_Core_Client` + `_Model_Core_Environment`. Dev on real AWS instance downgrades to beta.
+7. **Dynamic DB registration** — SQL joins `Clients`, `Databases`, `DatabaseHosts`, `Environments` for the environment slug. Calls `_Database::register()` + `connect()` for `DB_CLIENT`, `DB_CLIENT_LOGS`, `DB_CLIENT_ARCHIVE`.
+8. **Identity mapping** — `_Model_<ClientIdentifier>_ClientAuthentication::getAuthenticatedSsoUser($assertion)`. Wrapped in try/catch; exceptions sent to Sentry.
+9. **Commit DB writes** — `_Database::transactionCommit()` called after provisioning succeeds (see Gotchas).
+10. **Handoff** — encrypts client UUID + user UUID under `API_SECRET_ACCESS_TOKEN`, base64-encodes `{auth: 'encrypted-user-uuid', payload: {client, user}}`, redirects to `<domain>?saml=<payload>`.
+
+### Failure responses
+`Invalid SAMLResponse (Code = 1–4)`, `SAML Authentication Failed`, `User Authentication Failed`.
+
+## Per-client SSO extension pattern
+
+Identity mapping lives in `_underscore/Model/<ClientIdentifier>/ClientAuthentication.php`.
+Each class extends `_Model_Core_ClientAuthentication` + uses `_Trait_ClientAuthentication`.
+To onboard a new SSO client, add the class in `_underscore` — not in this repo.
+
+## Deployment
+
+- **EB environment:** `saml-production` (us-east-1). DNS: `saml.togahub.com → saml-production.us-east-1.elasticbeanstalk.com`
+- **`_underscore` pulled at deploy time** via `.ebextensions/git.php` + prebuild hook — clones branch `_production`. Deploy `saml` after `_underscore` merges to pick up framework changes.
+- **CodePipeline:** Source (GitHub `_production`) → ManualApproval → Deploy (EB).
+- **Composer deps** installed at postdeploy via `015_install_composer.sh`.
+
+## Dependencies
+
+- **`litesaml/lightsaml` ^3.0** — SAML 2.0 parsing, assertion decryption, X509.
+- **`sentry/sentry` ^4.9** — exception reporting, initialized at top of `saml()`.
+
+## Gotchas / known issues
+
+- **`_Database::register()` auto-starts a lazy transaction (since Apr 2 2026).** Any code that registers DBs then writes must call `_Database::transactionCommit()` before exiting — otherwise MySQL silently rolls back all writes on connection close. The `/acs` handler calls `transactionCommit()` after `getAuthenticatedSsoUser()` succeeds and before the redirect. See `_underscore/Database.php:48`.
+- **SAML signature verification is commented out.** The IdP X509 cert verification block is disabled. The only gate is the encrypted RelayState. Re-enabling per-IdP signature verification is a priority security improvement.
+- **SLS not implemented.** `/sls` falls through to the default banner.
+- **`set_exception_handler(null)` at top of `saml()`.** Unhandled exceptions output raw PHP errors. All exceptions from `getAuthenticatedSsoUser()` are caught and sent to Sentry.
+
+## Change history
+- 2026-06-11 — Added `transactionCommit()` before redirect; wrapped `getAuthenticatedSsoUser()` in try/catch with Sentry; echo+exit on auth failure (rgirish)

package/knowledge/2.0/apps/saml/features/rate-user-provisioning.md

@@ -0,0 +1,57 @@
+---
+title: Rate SAML User Provisioning
+framework: "2.0"
+repo: saml
+project: SAML SSO Gateway
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Rate/ClientAuthentication.php
+  - _underscore/Model/Rate/User.php
+  - _underscore/Model/Rate/Customer.php
+  - _underscore/Model/Rate/Contact.php
+related:
+  - 2.0/apps/saml/architecture.md
+  - clients/rate/features/saml-sso.md
+---
+
+## Summary
+
+When a Rate user authenticates via SSO, `_Model_Rate_ClientAuthentication::getAuthenticatedSsoUser()`
+is called by the saml gateway. It either finds the existing user by `borrowerID` or
+provisions a full new user record chain in `Client_Rate`.
+
+## How it works
+
+1. **Extract attributes** from the SAML assertion — all keys use null-safe access (`?? null`).
+2. **Validate required attributes** — `borrowerID` and `email` must be non-empty. Throws `\Exception('SAML assertion missing required attributes: ...')` if either is missing; caught by saml controller and sent to Sentry.
+3. **Load existing user** — `_Model_Rate_User` searched by `c_borrowerId`. If found, return immediately.
+4. **Provision new user** (if not found):
+   - Create `_Model_Rate_Customer` (`c_borrowerId`, `name`)
+   - Create `_Model_Rate_Contact` (`firstName`, `lastName`, `customerId`)
+   - Create `_Model_Client_ContactEmailAddress` (`contactId`, `name`, `emailAddress`)
+   - Update Contact with `primaryContactEmailAddressId`
+   - Create `_Model_Rate_User` with all fields; reload by PK (`new _Model_Rate_User($userId)`) to populate `uuid`
+   - Create `_Model_Client_Users_Role` with `roleId = 1` (Loan Officer default)
+5. Return User object with `id` and `uuid` populated.
+
+## Data model
+
+- `Client_Rate.Users` — `c_borrowerId VARCHAR(64)` (UUID from IdP)
+- `Client_Rate.Customers` — `c_borrowerId VARCHAR(128)`, `c_netsuiteInternalCustomerId INT`
+- `Client_Rate.Contacts` — `c_loid VARCHAR(64)`, `c_togaCustomerId INT`
+- `Client_Rate.ContactEmailAddresses` — standard base model
+- `Client_Rate.Users_Roles` — `roleId = 1` hardcoded as Loan Officer default
+
+## Gotchas / known issues
+
+- **`borrowerID` from Rate's IdP is a UUID string**, not a numeric ID.
+- **`phoneNumber` may not be sent by the IdP** — null-safe, nullable in DB. Do not add to required validation.
+- **`_Database::register()` starts a lazy transaction (since Apr 2 2026).** The saml controller must call `_Database::transactionCommit()` after this method returns — otherwise all INSERTs are silently rolled back on connection close. This was the root cause of new users never persisting. See `_underscore/Database.php:48`.
+- **`load()` scopes only by `c_borrowerId`** — no `clientId` filter. Two users sharing a `borrowerID` causes `load()` to return false (count != 1) and triggers duplicate provisioning.
+
+## Change history
+- 2026-06-11 — Added null-safe attribute extraction, required validation for `borrowerID` + `email`, Sentry-caught exceptions (rgirish)

package/knowledge/INDEX.md

@@ -14,6 +14,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 2 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
+- **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
+- **toga2-view** (TOGa View Frontend) — 0 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 
 ## Clients
 
@@ -22,4 +24,5 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Elite** (`elite`) → [clients/elite/INDEX.md](clients/elite/INDEX.md)
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
+- **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
 

package/knowledge/clients/rate/INDEX.md

@@ -0,0 +1,6 @@
+# Client: Rate `rate`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
+| [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/saml-sso.md

@@ -0,0 +1,58 @@
+---
+title: Rate SAML SSO
+framework: "2.0"
+project: SAML SSO Gateway
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Rate/ClientAuthentication.php
+  - saml/Controller/Index.php
+  - toga2-view/src/hooks/useAuthenticationFlow.ts
+related:
+  - 2.0/apps/saml/architecture.md
+  - 2.0/apps/saml/features/rate-user-provisioning.md
+---
+
+## Summary
+
+Rate uses Azure AD as its IdP (`login.rate.com`). Users sign in at Rate's portal, which
+redirects to the TOGa SAML gateway at `saml.togahub.com/acs`. On success the gateway
+redirects the browser back to the Rate frontend with a `?saml=` encrypted payload.
+
+## SAML assertion attributes
+
+Rate's Azure AD sends these attributes in the assertion:
+
+| Attribute key | Description | Required |
+|---|---|---|
+| `borrowerID` | Borrower UUID — used as `c_borrowerId` to identify/create users | Yes |
+| `email` | User email address | Yes |
+| `firstName` | First name | No (null-safe) |
+| `lastName` | Last name | No (null-safe) |
+| `phoneNumber` | Phone number | No (null-safe) |
+
+`borrowerID` is a UUID string (not numeric).
+
+## Frontend SAML landing (`useAuthenticationFlow.ts`)
+
+1. If `?saml=` is in the URL: strip it immediately via `window.history.replaceState` (prevents stale payload replay on refresh), then call `/v2/auth/encrypted-user-uuid`.
+2. On success: decode `urlParameters` into localStorage, upsert loan officer contact, call `login()`, navigate to `/landing`.
+3. On error: navigate to `/login`.
+
+## Loan officer upsert
+
+After successful auth, if `urlParameters` contains `loid` + `loname`:
+1. Fetch the user's Contact to get their Customer UUID.
+2. Search `Contacts` by `c_loid` — PUT to update name if found; POST to create with `contactType = 'Loan Officer'` (UUID `d1f67efc-a984-aebc-42f5-5313f44f52ed`) linked to the customer.
+
+## Gotchas / known issues
+
+- **`?saml=` replay** — the frontend strips the param immediately after processing. Before this fix, refreshing replayed the stale payload → EZ-1 "Invalid User".
+- **New users silently not created (Apr 2 – Jun 11 2026)** — `_Database::register()` auto-starts a lazy transaction; saml gateway never called `transactionCommit()`, so all new user INSERTs were rolled back silently. Fixed by adding `_Database::transactionCommit()` before the redirect in `saml/Controller/Index.php`.
+- **Both saml and _underscore must be deployed together** — saml pulls `_underscore` at EB build time. A fix in `_underscore` requires a saml redeploy to take effect.
+
+## Change history
+- 2026-06-11 — Fixed new user creation (missing transactionCommit); fixed ?saml= URL replay; added null-safe attribute extraction and required validation (rgirish)

package/knowledge/clients/rate/profile.md

@@ -0,0 +1,24 @@
+---
+title: "Rate"
+framework: "2.0"
+project: SAML SSO Gateway
+client: rate
+type: profile
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files: []
+related:
+  - clients/rate/features/saml-sso.md
+---
+
+## Summary
+
+Rate is a mortgage/lending client. Their TOGa integration covers home warranty and home
+tech support products. Users authenticate via SAML SSO from Rate's Azure AD IdP
+(`login.rate.com`). New users are auto-provisioned on first login.
+
+- **Client DB:** `Client_Rate`
+- **Client identifier:** `Rate`
+- **Production domains:** `https://homewarranty.rate.com`, `https://hometechsupport.rate.com`
+- **Frontend app:** TOGa View (`toga2-view`)

package/knowledge/registry.json

@@ -5,5 +5,7 @@
   { "repo": "dbchanges2",  "project": "Database Changes", "framework": "2.0", "role": "core", "dependsOn": [] },
   { "repo": "library",     "project": "Library",     "framework": "1.0", "role": "core", "dependsOn": [] },
   { "repo": "worker",      "project": "Worker",      "framework": "1.0", "role": "app",  "dependsOn": [] },
-  { "repo": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] }
+  { "repo": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
+  { "repo": "saml",        "project": "SAML SSO Gateway", "framework": "2.0", "role": "app",  "dependsOn": [] },
+  { "repo": "toga2-view",  "project": "TOGa View Frontend", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] }
 ]

package/package.json

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