toga-ai 1.0.235 → 1.0.237

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

@@ -6,6 +6,6 @@
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |
 | [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php, tools/mvc/get.php |
-| [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/initiate/get.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php, tools/mvc/get.php, tools/config.production.ini |
+| [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/initiate/get.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php, tools/mvc/get.php, tools/config.production.ini, tools/config.local.ini |
 | [Talos Pricing UI (Onboarding, Dashboard, Benchmarks, Cost Factors + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus a client-side estimate engine. | tools/_/app/nav.php, tools/_/app/talos/estimator.php, tools/mvc/talos/onboarding/get.php, tools/mvc/talos/onboarding/post.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/benchmarks/get.php, tools/mvc/talos/factors/get.php, tools/mvc/talos/factors/post.php, tools/assets/css/style.css |
 | [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/ebs/git.json |

package/knowledge/1.0/apps/tools/features/mvc-data-access-patterns.md

@@ -6,13 +6,14 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-06-29
+updated: 2026-06-30
 owners: [jcardinal]
 files:
   - tools/_/app/nav.php
   - tools/mvc/get.php
 related:
   - ./persona-gated-navigation.md
+  - ./saml-sso-auth.md
   - ../architecture.md
   - ../../library/features/mvc-page-pattern-and-app-skeleton.md
 ---
@@ -69,9 +70,26 @@ $res  = App_Database::query($sql, 'db_team');
 $rows = App_Database::buildArrayOfRows($res, false);
 ```
 
+## Gotcha — a page CANNOT set HTTP status/headers (preloader already flushed)
+`App_FrameworkIndex::render()` turns on the preloader and calls `App_Page::flushCapture()`
+(`ob_end_flush + flush`, `library/app/page.php:213`) **before** `body() → App_MVC::loadFile()` runs
+your mvc page. So by the time any page executes, **headers are already sent**. Calling
+`http_response_code()`, `header()`, or `session_regenerate_id()` from inside a page **fatals**
+("headers already sent"), and the error handler escalates that to an uncaught `ErrorException` → a
+bare **500**. Always guard:
+
+```php
+if (!headers_sent()) { http_response_code(401); }   // matches App_MVC::routeTo's own check
+```
+
+`establishSession()` (auth.php) guards `session_regenerate_id` for the same reason; the SSO failure
+path hit this too — see [saml-sso-auth](./saml-sso-auth.md). The clean long-term fix is to handle
+status-setting routes **before any output** and `exit`.
+
 ## Autoloader
 `App_Foo_Bar` → `app/foo/bar.php`, **all lowercase** (per the library CLAUDE.md). E.g.
 `App_Talos_Estimator` → `_/app/talos/estimator.php`.
 
 ## Change history
+- 2026-06-30 — Added the preloader-flush gotcha: pages run after `App_Page::flushCapture()` flushes the output buffer, so `http_response_code`/`header`/`session_regenerate_id` from inside a page fatal on headers-already-sent (escalates to a 500) — guard with `!headers_sent()`. Surfaced by the SSO failure-path 500 fix. (jcardinal)
 - 2026-06-29 — Documented tools MVC routing (GET→get.php / POST→post.php; writes via mvc/<route>/post.php, not the legacy actionHandler path), Origin/Referer CSRF (no token field), `App_Database` query/row/txn API + `sqlEscape()` name, the by-reference row-helper warning gotcha, the persona-narrowing gotcha, and the lowercase autoloader mapping. Discovered building the Talos Pricing UI. (jcardinal)

package/knowledge/1.0/apps/tools/features/saml-sso-auth.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-06-26
+updated: 2026-06-30
 owners: [jcardinal]
 files:
   - tools/_/app/auth.php
@@ -17,6 +17,7 @@ files:
   - tools/mvc/logout/get.php
   - tools/mvc/get.php
   - tools/config.production.ini
+  - tools/config.local.ini
 related:
   - ../architecture.md
   - ../../library/features/app-sso-initiation.md
@@ -49,14 +50,30 @@ auto-created.
 ### Consuming the `?saml=` handoff (`mvc/sso/get.php` → `App_Auth`)
 1. Length-guard `$_GET['saml']`, then base64-decode → `json_decode` → read `payload.client`
    and `payload.user`.
-2. Decrypt each with `App_String::decryptWithKey()` using config `[saml] api_secret_access_token`,
-   with a **dual-key retry** against `api_secret_access_token_previous` (supports gateway key
-   rotation). This interoperates byte-for-byte with the 2.0 `_String::encryptWithKey()` that
-   produced the token (see the library `App_String` crypto methods).
+2. Decrypt each with `App_String::decryptWithKey()` (AES-256-CBC; see crypto format below) via
+   `App_Auth::decryptHandoffValue()`, with a **current → previous dual-key fallback** so an
+   in-flight gateway key rotation still decodes. **Keys come from `Core.Parameters` at runtime,
+   not from config** — see "Handoff key sourcing" below. This interoperates byte-for-byte with
+   the 2.0 `_String::encryptWithKey()` that produced the token.
 3. Validate the decrypted **client uuid == configured `true_client_uuid`** via `hash_equals`,
    and that both decrypted values match a UUID regex.
 4. Load the active Client_True user: `WHERE uuid = ? AND isActive = 1`. No match → fail closed.
 
+### Handoff key sourcing (`handoffKeys()` → `Core.Parameters`)
+The shared secret is **rotated regularly**, so the static `config.*.ini [saml]` token goes stale —
+that staleness was exactly why `decryptHandoffValue()` returned `false` and production login failed
+(the payload decoded to the correct iv+base64 shape; it was a **key** mismatch, not a format bug).
+- `App_Auth::handoffKeys()` (new private helper) `SELECT \`key\`,\`value\` FROM Parameters WHERE
+  \`key\` IN ('API_SECRET_ACCESS_TOKEN','API_SECRET_ACCESS_TOKEN_PREVIOUS')` over the **`db_toga2core`**
+  connection (2.0 PROD Core DB; `const CORE_DB = 'db_toga2core'`). Result is **cached per request**.
+  `\`key\`` and `\`value\`` are SQL reserved words → **must be backticked**.
+- `decryptHandoffValue()` then tries the current key, falling back to previous (rotation window).
+  Its **public signature is unchanged** — only `mvc/sso/get.php` calls it.
+- The old `[saml] api_secret_access_token` / `_previous` config values are now **dead** (removable).
+  `[saml] true_client_uuid` is **still used** (`sso/get.php:80-84`) and stays.
+- See [Core.Parameters key/value store](#coreparameters-key-value-store) for the table shape and
+  which DB cluster it lives on.
+
 ### Session establishment (`establishSession()`)
 - Calls `session_regenerate_id(true)` **guarded by `if (!headers_sent())`** (see gotcha), then
   caches the user and **persona names** in `$_SESSION`.
@@ -88,22 +105,51 @@ removed.
   **inside** the page render (`frameworkindex → body → loadFile`) after `common/header.php` has
   emitted output, so `session_regenerate_id(true)` fatals ("cannot be regenerated after headers
   already sent"). Fixed by guarding with `if (!headers_sent())`. **Known architectural limitation:**
-  the failure path (`tools_ssoFail → http_response_code` at `mvc/sso/get.php:23`) *also* fatals on
-  headers-sent; the proper long-term fix is to route `/sso` **before any output** and `exit`. Any
-  1.0 app adopting this consumer pattern inherits this — see
-  [App_Sso](../../library/features/app-sso-initiation.md).
+  the proper long-term fix is to route `/sso` **before any output** and `exit`. Any 1.0 app adopting
+  this consumer pattern inherits this — see [App_Sso](../../library/features/app-sso-initiation.md)
+  and the [preloader-flush gotcha](./mvc-data-access-patterns.md) for the general rule.
+- **Failure path also fataled → fixed (2026-06-30).** `tools_ssoFail()` called
+  `http_response_code(401)` to render the "Authentication failed" page, which itself fataled with
+  "headers already sent" and the error handler escalated it to an uncaught `ErrorException` → a bare
+  **500** instead of the intended 401 page. Root cause: `App_FrameworkIndex::render()` turns on the
+  preloader and runs `App_Page::flushCapture()` (`ob_end_flush + flush`, `library/app/page.php:213`)
+  **before** `body()/App_MVC::loadFile()` runs the mvc page. Fixed with the same
+  `if (!headers_sent()) { http_response_code(401); }` guard (matches `App_MVC::routeTo`'s own check).
 - **No app-side replay defense.** The handoff token carries no nonce/timestamp the app verifies.
   Recommend the gateway embed `iat` + `jti`.
 
+## Crypto format (`App_String::encryptWithKey` / `decryptWithKey`)
+`library/app/string.php:1075-1094`, AES-256-CBC: `encryptWithKey` returns
+`base64( iv . openssl_encrypt(..., flag 0) )` — i.e. a base64 envelope whose body is the raw IV
+followed by openssl's own base64 ciphertext; `decryptWithKey` reverses it. **Interoperable
+byte-for-byte with the 2.0 `_String::decryptWithKey()`** that the SAML gateway uses to produce the
+handoff token. The 2026-06-30 login failure decoded to the exact expected iv+base64 shape, proving
+the issue was a stale **key**, not a cipher/format mismatch.
+
+## Core.Parameters key/value store
+The platform's rotating key/value parameter store, on the **2.0 PROD Core DB** (`Core` schema).
+Columns: `id`, `uuid`, `\`key\`` (UNIQUE), `\`value\`` — `key`/`value` are reserved words and **must
+be backticked**. Holds the SSO/API shared secrets `API_SECRET_ACCESS_TOKEN` and
+`API_SECRET_ACCESS_TOKEN_PREVIOUS`. The tools app reaches it via the **`db_toga2core`** connection
+(`[database_toga2core]`, dbname `Core`, prod core cluster in `us-west-2`) — a cluster **distinct**
+from the 1.0 prod-cluster and from the 2.0 client cluster that backs `db_true`/`Client_True`.
+
 ## Config keys
 
-`[database_true]` (read-only Client_True); `[saml]` `api_secret_access_token` /
-`api_secret_access_token_previous`, `client_authentication_uuid`, `domain_uuid`,
-`true_client_uuid` (plus the IdP/ACS urls used by initiation); `[internal]` `dev_mode`. **Secret
-location:** `config.production.ini` holds the plaintext production secrets — including the shared
-Core `API_SECRET_ACCESS_TOKEN` — in its `[saml]` section (committed; developer explicitly accepted
-this). Document **where** they live, never the values.
+`[database_true]` (read-only Client_True); **`[database_toga2core]`** — new requirement: alias
+`db_toga2core`, dbname `Core`, the prod core cluster host (`production-core-cluster…us-west-2…`),
+needed in **each** `config.*.ini` so the handoff keys can be read at runtime (developer is adding
+creds). `[saml]`: `true_client_uuid` (still used), `client_authentication_uuid`, `domain_uuid`,
+plus the IdP/ACS urls used by initiation; `[internal]` `dev_mode`. The old `[saml]
+api_secret_access_token` / `_previous` are now **dead** (superseded by `Core.Parameters`).
+
+**Secret location.** Rotating secrets are now sourced from `Core.Parameters` **at runtime** rather
+than static config — an improvement over the old committed `config.production.ini [saml]` tokens.
+A **pre-existing reused plaintext DB password** across the `config.*.ini [database_*]` sections
+remains (already noted in tools knowledge) — **flag for rotation.** Document **where** secrets live,
+never the values.
 
 ## Change history
+- 2026-06-30 — Fixed prod SSO login failure: handoff decrypt keys now sourced from `Core.Parameters` (rotated `API_SECRET_ACCESS_TOKEN`/`_PREVIOUS`) via new `App_Auth::handoffKeys()` over `db_toga2core` (per-request cached, current→previous fallback), instead of the stale committed `config [saml]` tokens — the stale key was the root cause. Added `[database_toga2core]` connection requirement to every config and documented the AES-256-CBC crypto format. Fixed `tools_ssoFail()` 500→intended 401: `http_response_code(401)` fataled on headers-already-sent (preloader flushes before mvc page runs); guarded with `!headers_sent()`. (jcardinal)
 - 2026-06-26 — Wired up real SSO initiation via the new 1.0 `App_Sso` library class (`/sso/initiate`), replacing the `initiation_url` placeholder; registered the fixed-uuid Core.Domains return row (dbchanges2 `2026-06-26a`); fixed the `session_regenerate_id` headers-already-sent fatal (guarded with `!headers_sent()`) and documented the mid-render failure-path limitation; collapsed home → `/login` to one-step sign-in; noted prod secrets live in `config.production.ini [saml]` (jcardinal)
 - 2026-06-25 — Built App_Auth: SAML `?saml=` handoff consumer with dual-key decrypt, hash_equals client-uuid check, fail-closed 401, persona-cached session (HttpOnly+SameSite=Lax), and a double-gated dev bypass. Initiation + replay defense left as open items (jcardinal)

package/knowledge/1.0/standards/framework-rules.md

@@ -99,6 +99,19 @@ Before creating a new class in a 1.0 repo:
 3. Follow the naming convention exactly, including the type segment.
 4. If you are adding a class to the `library` core repo, be aware it affects all 1.0 apps — review `knowledge/1.0/apps/library/architecture.md` first.
 
+## Schema migrations — always in `dbchanges`
+
+**Application repos (`worker`, `togadesk`, `togaview`, `tools`, and any other 1.0 app)
+contain no standalone `.sql` migration or schema files.** All schema changes for any
+1.0 database — table creation, `ALTER` statements, index changes, seed data — go in the
+**`dbchanges`** repo.
+
+This rule applies regardless of which application repo the feature lives in. Even if you
+are adding a column that only `worker` reads, the `.sql` file goes in `dbchanges`.
+
+Never create a `.sql` file inside a 1.0 application repo. The SQL that belongs in those
+repos is only query strings embedded in PHP code — not standalone migration files.
+
 ## Error handling in controllers
 
 Controllers must not let exceptions bubble up to the framework unhandled. Catch specific exceptions, log them, and return an appropriate response.

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

@@ -39,6 +39,13 @@ processes background jobs. It's a `_underscore` 2.0 app (`index.php` is just
 | S3 `agilant-worker-fallback` | Failed webhook payloads (`webhook-fallback/{uuid}.json`, 7-day lifecycle). |
 | API Gateway `WorkerWebhookIngestion` | `webhook.togahub.com` → Lambda. Lambda Function URLs are blocked by an AWS Org SCP, so API Gateway is the only public entry point. |
 
+## Critical repo rule — no SQL migration files
+
+**This repo contains PHP and Python only. Never create `.sql` schema-migration files here.**
+All table creation, `ALTER` statements, index changes, and seed data — including for
+`Core.WorkerJobs` and `Core.CronJobs` — go in the `dbchanges2` repo using its
+`YYYY-MM-DD<letter> - <Description>.sql` naming convention.
+
 ## MySQL tables
 
 **`Core.WorkerJobs`** — unified execution record. Key columns: `uuid`,

package/knowledge/2.0/standards/backend-php.md

@@ -22,6 +22,14 @@ related:
 
 ## Database/SQL
 
+### Migration files belong in `dbchanges2`
+
+SQL query strings embedded in PHP code (SELECTs, INSERTs, UPDATEs) live in this repo as
+part of normal PHP files. **Standalone `.sql` migration files do not.** Any schema change
+— CREATE TABLE, ALTER TABLE, new index, seed rows — must be placed in the `dbchanges2`
+repo, not here. See `2.0/standards/framework-rules.md` § Schema migrations for naming
+conventions.
+
 ### Table Design
 
 #### **Order of Fields**

package/knowledge/2.0/standards/framework-rules.md

@@ -86,6 +86,22 @@ return [
 ];
 ```
 
+## Schema migrations — always in `dbchanges2`
+
+**Application repos (`worker2`, `api2`, `_underscore`) contain no standalone `.sql`
+migration or schema files.** All schema changes for any 2.0 database — table creation,
+`ALTER` statements, index changes, seed data — go in the **`dbchanges2`** repo.
+
+File naming in `dbchanges2`: `YYYY-MM-DD<letter> - <Description>.sql`
+(e.g. `2026-06-30a - Add WorkerJobs failureCode column.sql`).
+
+This rule applies regardless of which application repo the feature lives in. Even if you
+are adding a column that only `worker2` reads, the `.sql` file goes in `dbchanges2`.
+
+Never create a `.sql` file inside `worker2`, `api2`, `_underscore`, or any other 2.0
+application repo. The SQL that belongs in those repos is only query strings embedded in
+PHP code — not standalone migration files.
+
 ## Checking dependencies before touching shared code
 
 `dependsOn` in `knowledge/registry.json` means a repo extends or depends on another repo's classes. Before modifying a class in a dependency repo (e.g. `_underscore` core):

package/package.json

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