toga-ai 1.0.201 → 1.0.202

package/knowledge/1.0/apps/library/INDEX.md

@@ -6,6 +6,7 @@
 | [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | `App_Model_Toga_Diagnostic::initializeDiagnosticDialog()` renders the device modal used across all TOGa service request views. | library/app/model/toga/diagnostic.php |
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
+| [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php |
 | [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. | library/app/api/toga2.php |

package/knowledge/1.0/apps/library/features/mvc-page-pattern-and-app-skeleton.md

@@ -0,0 +1,113 @@
+---
+title: 1.0 MVC Page Pattern & New-App Skeleton
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - library/app/framework.php
+  - library/app/frameworkindex.php
+  - library/app/mvc.php
+  - library/app/database.php
+  - library/app/model.php
+  - library/app/config.php
+related:
+  - ../architecture.md
+  - ../../togaview/architecture.md
+---
+
+## Summary
+
+This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding
+pages to one — the folder-based MVC routing, the page lifecycle, the model/DB conventions, and
+the minimal new-app skeleton. The `library` core supplies all of it; an app contributes only its
+`index.php`, config, `_/app/` framework subclasses, `mvc/` pages, and `common/` templates.
+togaview is the reference implementation (see its architecture doc for the multi-tenant
+specifics); this doc captures the framework-level pattern that any new 1.0 app reuses.
+
+## How it works
+
+### Folder-based, classless routing
+A URL maps directly to a file on disk — **the file path IS the route**, there is no routing
+config and no controller classes. `App_MVC::parseRoute()` turns the request URI into
+`mvc/<folder…>/<httpmethod>.php`, matching **longest-to-shortest** so overlapping paths resolve
+to the most specific folder.
+
+```
+GET  /task_list/ajax   ->  mvc/task_list/ajax/get.php
+POST /login            ->  mvc/login/post.php
+```
+
+- `<httpmethod>` is `get` or `post`, taken from the HTTP verb (overridable via a `_method` POST param).
+- `get.php` renders a page; `post.php` does writes then redirects via `App_MVC::routeTo()`
+  (`header('Location: …'); exit;`).
+- Because matching is longest-to-shortest, keep route folders distinct to avoid surprise matches.
+
+### Entry point (3 lines)
+```php
+require '_.php';                          // bootstraps library core + autoloader
+App_Framework_<App>::initialize();        // env, config, DB links, session, Sentry
+App_Framework_<App>::renderIndex();       // resolves stylePath + dispatches the page
+```
+App-specific framework classes live in `<app>/_/app/` and extend the library bases
+`App_Framework` (`framework.php`) and `App_FrameworkIndex` (`frameworkindex.php`).
+
+### Page lifecycle (no template engine)
+`App_FrameworkIndex::body()` loads the matched mvc file **inline** between
+`common/<stylePath>/header.php` and `common/<stylePath>/footer.php`. There is no master-template
+engine — pages are inline PHP + HTML. `stylePath` is selected by `$_SERVER['HTTP_HOST']` in
+`framework.php::renderIndex()`, giving per-brand CSS under `assets/css/<stylePath>/`. Pages guard
+auth themselves by checking `$_SESSION` at the top.
+
+### Adding a page
+Create `mvc/<page>/get.php` (and `post.php` if it writes). Scaffold from `mvc/_TEMPLATE/`.
+
+### Models
+Extend `App_Model`, named `App_Model_<Db>_<Table>`, declaring `const TABLENAME`, `const DATABASE`,
+and `public $field = self::FIELDTYPE_*` for each column. Field types: `PRIMARYKEY`, `INT`, `CHAR`,
+`DATETIME`, `BLOB`, `BLOBSTORAGE`, `FOREIGNKEY`, `SERIALIZED`, `DATETIME_CREATED`,
+`DATETIME_UPDATED`.
+
+```php
+class App_Model_Toga_Client extends App_Model {
+    const TABLENAME = 'Clients';
+    const DATABASE  = 'db_toga';
+    public $id         = self::FIELDTYPE_PRIMARYKEY;
+    public $clientName = self::FIELDTYPE_CHAR;
+}
+```
+Usage: `new App_Model_X($id)` loads a row; `->save()` persists; `App_Model_X::lookupValueByField()`.
+
+### Databases (multiple are first-class)
+DB access is mysqli via `App_Database::query($sql, 'db_<name>')`. **Multiple databases are
+first-class:** each `[database_<name>]` section in `config.<env>.ini` is registered as registry
+key `db_<name>` by `App_Database::registerDatabaseConnect()`. SELECTs **auto-route to
+`<link>_read`** when the host is an RDS cluster (read-cluster support). Escape with
+`App_Database::sqlEscape()`; read results with `buildArrayOfRows()` / `fetchRow()`.
+
+### Config
+`App_Config` does `parse_ini_file(config.<ENVIRONMENT>.ini)`; the environment comes from
+`getenv('ENVIRONMENT')` (defaults to `'worker'` — an unset env loads the wrong file). Sections:
+`[internal]`, `[database_*]`, `[email]`, `[external]`, `[modules]`, `[api]`.
+
+> **Secrets are currently stored in plaintext ini files** — a known practice, not a recommended
+> one. Document where a credential lives, never its value.
+
+## Minimal new-app skeleton
+```
+index.php                              # the 3-line entry point
+config.<env>.ini                       # per-environment config + DB sections
+mvc/_TEMPLATE/get.php                  # page scaffold
+mvc/<page>/{get,post}.php              # one folder per route
+common/<stylePath>/{header,footer}.php # brand shell wrapped around each page
+common/404.php
+assets/                                # css/js per stylePath
+```
+The app depends on the `library` core repo (bootstrapped via `_.php`).
+
+## Change history
+- 2026-06-25 — Documented the 1.0 folder-based MVC page pattern, model/multi-DB conventions, and the minimal new-app skeleton, discovered while planning the new "Toolbox" 1.0 app (reference: togaview) (jcardinal)

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

@@ -3,4 +3,5 @@
 | 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 |
+| [SAML Downstream Integration Contract](features/downstream-integration-contract.md) | The contract a **downstream TOGa app** implements to authenticate users through the SAML gateway (`saml.togahub.com`). | saml/Controller/Index.php, _underscore/Model/Core/ClientAuthentication.php, _underscore/Model/True/ClientAuthentication.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

@@ -7,7 +7,7 @@ client: shared
 type: architecture
 status: active
 updated: 2026-06-11
-owners: ["rgirish"]
+owners: ["rgirish", "jcardinal"]
 files:
   - saml/index.php
   - saml/_.php
@@ -80,9 +80,11 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 ## 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.
+- **SAML signature verification is commented out — this is the repo's top security priority.** The IdP X509 cert verification block in the `/acs` flow is disabled, so the gateway accepts any well-formed, status-success `SAMLResponse` without proving it was signed by the expected IdP. The only remaining gate is the encrypted RelayState, which authenticates the *originating TOGa request* — not the *asserting IdP*. Threat model: an attacker who can craft or replay a `SAMLResponse` (or a malicious/compromised IdP) can forge an identity assertion for any user, since nothing binds the assertion to a trusted signing key. Re-enabling per-IdP X509 signature verification is the single highest-impact security fix for this repo.
+- **Plaintext secrets in source — move to AWS SSM Parameter Store.** `saml/Config/production.ini` stores credentials in plaintext, and a Sentry DSN is hardcoded in `saml/Controller/Index.php`. Both are checked into the repo. Migrate these to AWS SSM Parameter Store (SecureString) and load at runtime; the source tree should reference parameter names only, never literal credential values.
 - **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)
+- 2026-06-25 — Sharpened signature-verification gotcha with explicit threat model and flagged it as the repo's top security priority; documented plaintext secrets in `production.ini` + hardcoded Sentry DSN in `Controller/Index.php` with SSM Parameter Store recommendation (jcardinal)

package/knowledge/2.0/apps/saml/features/downstream-integration-contract.md

@@ -0,0 +1,81 @@
+---
+title: SAML Downstream Integration Contract
+framework: "2.0"
+repo: saml
+project: SAML SSO Gateway
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - saml/Controller/Index.php
+  - _underscore/Model/Core/ClientAuthentication.php
+  - _underscore/Model/True/ClientAuthentication.php
+related:
+  - ../architecture.md
+  - ../../_underscore/architecture.md
+  - ../../../clients/rate/features/saml-sso.md
+---
+
+## Summary
+
+The contract a **downstream TOGa app** implements to authenticate users through the SAML gateway
+(`saml.togahub.com`). The architecture doc covers the gateway internals; this doc is the
+**integration recipe** for an app that wants SSO — how to initiate the flow, what the gateway
+hands back, and how to consume it. Reusable for any new SSO-consuming app.
+
+## How it works
+
+### SP-initiated flow
+1. The downstream app calls
+   `_Model_Core_ClientAuthentication::singleSignOnServiceUrl(uuid, domainUuid, urlParameters)`
+   to build a signed SAML AuthnRequest (HTTP-Redirect binding). The RelayState
+   (`{v:1, time, domain, urlParameters}`) is encrypted with the Core `API_SECRET_ACCESS_TOKEN`
+   and carries a 300-second TTL.
+2. The user authenticates at the client IdP, which POSTs the `SAMLResponse` to the gateway `/acs`.
+3. `/acs` decrypts RelayState (supports key rotation via `API_SECRET_ACCESS_TOKEN_PREVIOUS`),
+   resolves Core `Domain → Client → Environment`, **dynamically registers the client DBs**
+   (`DB_CLIENT`, `DB_CLIENT_LOGS`, `DB_CLIENT_ARCHIVE`), then calls the client-specific mapper
+   `_Model_<ClientIdentifier>_ClientAuthentication::getAuthenticatedSsoUser($assertion)` to
+   resolve or create the user.
+   - Base `_Model_True_ClientAuthentication` matches by **email** (from the NameID).
+   - Compass matches `c_hrEmpUsername`; Rate matches `borrowerID`.
+
+### Handoff back to the downstream app
+The gateway redirects the browser to:
+```
+<appDomain>?saml=<base64(json)>
+```
+where the JSON is:
+```json
+{
+  "auth": "encrypted-user-uuid",
+  "payload": { "client": "encryptWithKey(client.uuid)", "user": "encryptWithKey(user.uuid)" }
+}
+```
+all encrypted under the Core `API_SECRET_ACCESS_TOKEN`. An optional `?urlParameters` is forwarded
+through.
+
+The downstream app then: base64-decodes the `saml` param, JSON-parses it, decrypts the client and
+user UUIDs with `_String::decryptWithKey()`, loads the user, and **establishes its own session**.
+The gateway holds no session — session ownership is entirely the downstream app's.
+
+### Integrating a NEW downstream app
+1. Ensure an SSO config row exists in `_Model_Core_ClientAuthentications_Sso`.
+2. Implement/extend `_Model_<Client>_ClientAuthentication::getAuthenticatedSsoUser()` in
+   `_underscore` (the gateway repo is not modified — see the per-client extension pattern in the
+   architecture doc).
+3. Initiate SSO via `singleSignOnServiceUrl()`.
+4. Consume the `?saml=` handoff and decrypt the UUIDs with `API_SECRET_ACCESS_TOKEN`.
+
+## Gotchas / known issues
+
+- **Lazy-transaction write-drop.** `_Database::register()` auto-starts a lazy transaction (since
+  Apr 2026). Any `/acs` write path (e.g. user auto-creation) must call
+  `_Database::transactionCommit()` before exit or the writes are silently rolled back.
+- **Gateway holds no session** — every downstream app must build and own its own session from the
+  decrypted handoff.
+
+## Change history
+- 2026-06-25 — Documented the downstream integration contract (SP-initiated flow, `?saml=` handoff shape, and the 4 onboarding steps), discovered while planning a new SSO-consuming app (reference: saml) (jcardinal)

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 8 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 9 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 10 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 8 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
@@ -20,7 +20,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **api2** (API) — 6 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 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)
+- **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 4 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
@@ -51,6 +51,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Quad Graphics** (`quad`) → [clients/quad/INDEX.md](clients/quad/INDEX.md)
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
 - **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)
+- **TOGA Technology** (`true`) → [clients/true/INDEX.md](clients/true/INDEX.md)
 - **Walmart Client Profile** (`walmart`) → [clients/walmart/INDEX.md](clients/walmart/INDEX.md)
 - **Wiss, Janney, Elstner Associates, Inc.** (`wje`) → [clients/wje/INDEX.md](clients/wje/INDEX.md)
 

package/knowledge/clients/true/INDEX.md

@@ -0,0 +1,6 @@
+# Client: TOGA Technology `true`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [True Users / Personas Data Model](features/users-personas-data-model.md) | 2.0 | The `Client_True` schema models internal/staff users and their **personas** — used to gate UI and navigation by staff role in downstream tooling. |  |
+| [TOGA Technology](profile.md) | 2.0 | "True" is TOGa's own **internal / staff tenant** — the base client whose data lives in the `Client_True` schema in production. |  |

package/knowledge/clients/true/features/users-personas-data-model.md

@@ -0,0 +1,45 @@
+---
+title: True Users / Personas Data Model
+framework: "2.0"
+project: _Underscore
+client: true
+type: client-feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files: []
+related:
+  - clients/true/profile.md
+  - 2.0/apps/saml/features/downstream-integration-contract.md
+---
+
+## Summary
+
+The `Client_True` schema models internal/staff users and their **personas** — used to gate UI and
+navigation by staff role in downstream tooling. After SSO resolves a user, an app looks up that
+user's personas and drives visibility from persona membership.
+
+## How it works
+
+### Tables
+- **`Users`** — key columns: `id`, `uuid` (char, unique), `email` (varchar, unique), `firstName`,
+  `lastName`, `displayName`, `isActive` (tinyint, default `1`), `password` (char, nullable), plus
+  FKs `contactId`, `clientId`, `locationId`, `userTypeId`, `supervisorUserId`.
+- **`Personas`** — `id`, `uuid`, `name`, `number`.
+- **`Users_Personas`** (many-to-many bridge) — `id`, `uuid`, `userId`, `personaId`.
+
+### Live personas (production)
+TOGa Technology, Development Team, Legal Team, Contact Center, Operations, Executive, Audit.
+
+### Usage pattern for downstream apps
+After SSO resolves the user, look up their personas via
+`Users JOIN Users_Personas JOIN Personas`, then drive UI / navigation visibility by persona
+membership.
+
+## Gotchas / known issues
+
+- **Cache personas in session.** Cache the resolved persona names in `$_SESSION` at login to avoid
+  a per-request DB read for visibility checks.
+
+## Change history
+- 2026-06-25 — Documented the Client_True Users/Personas data model and persona-gated UI usage pattern, discovered via prod DB schema inspection while planning persona-gated internal tooling (jcardinal)

package/knowledge/clients/true/profile.md

@@ -0,0 +1,26 @@
+---
+title: "TOGA Technology"
+framework: "2.0"
+apps:
+  - _underscore
+project: _Underscore
+client: true
+type: profile
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files: []
+related:
+  - clients/true/features/users-personas-data-model.md
+---
+
+## Summary
+
+"True" is TOGa's own **internal / staff tenant** — the base client whose data lives in the
+`Client_True` schema in production. It is also the default SSO identity mapper
+(`_Model_True_ClientAuthentication`, which matches users by email). Internal tooling that gates UI
+by staff role (e.g. the planned Toolbox app) reads its `Users` / `Personas` model.
+
+- **Client DB:** `Client_True`
+- **Client identifier:** `True`
+- **SSO mapper:** `_Model_True_ClientAuthentication` (base; matches by email from NameID)

package/package.json

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