toga-ai 1.0.211 → 1.0.213

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
+| [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | `App_Sso` (`library/app/sso.php`) is the **1.0 port of the 2.0 SAML gateway's SP-initiated SSO initiation**, packaged as a reusable, framework-level capability | library/app/sso.php, library/sso/togahub_private_key.key |
 | [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 |

package/knowledge/1.0/apps/library/features/app-sso-initiation.md

@@ -0,0 +1,106 @@
+---
+title: App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-06-26
+owners: [jcardinal]
+files:
+  - library/app/sso.php
+  - library/sso/togahub_private_key.key
+related:
+  - ../architecture.md
+  - ./mvc-page-pattern-and-app-skeleton.md
+  - ../../../2.0/apps/saml/features/downstream-integration-contract.md
+  - ../../apps/tools/features/saml-sso-auth.md
+  - ../../apps/tools/workflows/deploy-to-elastic-beanstalk-al2023.md
+---
+
+## Summary
+
+`App_Sso` (`library/app/sso.php`) is the **1.0 port of the 2.0 SAML gateway's SP-initiated SSO
+initiation**, packaged as a reusable, framework-level capability so **any 1.0 `App_` app** can
+adopt SSO through `saml.togahub.com` without touching 2.0. It is the 1.0 counterpart to the 2.0
+`_Model_Core_ClientAuthentication::singleSignOnServiceUrl()` builder described in the
+[SAML downstream integration contract](../../../2.0/apps/saml/features/downstream-integration-contract.md).
+
+Design intent (read before adopting): the class is **config-driven and has NO Core DB
+dependency** — a consuming 1.0 app never queries Core. The team's standing preference is **not to
+modify 2.0**; 1.0 SSO initiation logic lives here in `App_Sso`. This is the canonical doc to
+follow for any future "add SSO to `<1.0 app>`" request.
+
+## How it works
+
+`App_Sso::initiate(array $params): string` builds a signed SAML 2.0 `AuthnRequest` and returns the
+full IdP redirect URL (`idpSsoUrl?QUERY&Signature=...`). It uses the **HTTP-Redirect binding**:
+
+1. Build the `AuthnRequest` XML, then encode it for the redirect binding:
+   `XML → gzdeflate → base64 → urlencode`.
+2. Build the **RelayState** payload `{v:1, time, domain, urlParameters}` and encrypt it with
+   `App_String::encryptWithKey` (AES-256-CBC, output `base64(iv . ciphertext)`). This is
+   **byte-for-byte compatible** with the 2.0 `_String::encryptWithKey`, so the gateway `/acs` can
+   decrypt the RelayState the 1.0 app produced.
+3. Sign the assembled query string with `openssl_sign` + `OPENSSL_ALGO_SHA256` using the bundled
+   private key, and append `&Signature=<base64>`.
+   - `SIGNATURE_ALGORITHM = http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
+   - `PRIVATE_KEY_PATH = __DIR__/../sso/togahub_private_key.key`
+     (`library/sso/togahub_private_key.key`, the togahub signing key, copied from the 2.0
+     `_underscore` `Assets/ssl`).
+
+### Parameters
+**Required:** `idpSingleSignOnServiceUrl`, `idpEntityIdentifier`, `assertionConsumerServiceUrl`,
+`domainUuid`, `apiSecretAccessToken`. **Optional:** `urlParameters`.
+Throws `InvalidArgumentException` on a missing required param; `RuntimeException` on signing failure.
+
+### Deliberate deviation from 2.0
+`App_Sso` emits a **valid** closing tag `</samlp:AuthnRequest>`, whereas the 2.0 builder emits a
+malformed `<\samlp:AuthnRequest>`. `App_Sso` is the corrected version — this is intentional, not a
+bug to "fix back."
+
+## Adopting SSO in another 1.0 app (step-by-step)
+
+(a) **Config — add a `[saml]` section** with:
+`idp_single_sign_on_service_url`, `idp_entity_identifier` (= `https://saml.togahub.com/meta`),
+`assertion_consumer_service_url` (= `https://saml.togahub.com/acs`), `domain_uuid`,
+`api_secret_access_token` (+ `..._previous` for rotation), and the client uuid(s) the consumer
+validates against. Document **where** these secrets live; never paste the values.
+
+(b) **Initiation route** (e.g. `mvc/sso/initiate/get.php`): guard `isLoggedIn`, read `config[saml]`,
+call `App_Sso::initiate([...])`, then `App_MVC::routeTo($url); exit;`.
+
+(c) **Handoff consumer route** `mvc/sso/get.php`: base64-decode the `?saml=` payload, JSON-parse,
+decrypt the client/user values with the shared API secret (**current then previous** key, for a
+rotation grace window), validate the UUIDs, look up the user, and establish the session. See the
+Tools implementation in [Tools SAML SSO Consumer & Persona-Gated Auth](../../apps/tools/features/saml-sso-auth.md).
+
+(d) **Register a `Core.Domains` row** (`uuid, clientId, appId, environmentId, domain =
+https://<app-host>/sso`). The `uuid` **MUST equal** the config `domain_uuid` (use a fixed uuid, not
+`UUID()`). The gateway resolves client + environment + return URL from this row.
+
+(e) **AWS — the app host MUST have a working HTTPS (443) listener + an ACM cert covering that exact
+hostname**, or the gateway's return redirect to `https://<host>/sso` fails with a connection
+timeout. See the gotcha below.
+
+## Gotchas / known issues
+
+- **Return-leg "connection timeout" is usually a missing HTTPS listener, not code.** When a SAML
+  SSO return leg times out in the browser, **verify the EB/ALB HTTPS (443) listener + ACM cert
+  cover the EXACT return hostname before debugging PHP/SAML.** Diagnosis signature: `curl` to the
+  public `https://` URL **from the instance itself** returns `http=000` after the full timeout,
+  while `curl http://127.0.0.1` with a `Host:` header returns `200` fast. Reusable for any TOGA app
+  behind Elastic Beanstalk; see the
+  [Tools EB deploy workflow](../../apps/tools/workflows/deploy-to-elastic-beanstalk-al2023.md).
+- **Consumer route runs mid-render in 1.0.** The 1.0 framework runs `mvc/sso/get.php` **inside** the
+  page render (`frameworkindex → body → loadFile`) after `common/header.php` has already emitted
+  output, so headers are sent. `session_regenerate_id(true)` (and any `http_response_code` on the
+  failure path) fatals with "headers already sent." Guard `session_regenerate_id` with
+  `if (!headers_sent())`. The proper long-term fix is to route `/sso` **before any output** and
+  `exit`; until then this is a known architectural limitation any 1.0 consumer inherits.
+
+## Change history
+- 2026-06-26 — Built `App_Sso::initiate()`: 1.0 port of the 2.0 SP-initiated SSO builder, config-driven with no Core DB dependency, RelayState encrypted via `App_String::encryptWithKey` (2.0-compatible), rsa-sha256 query signing with the bundled togahub key, and a corrected `</samlp:AuthnRequest>` closing tag. Captured the 5-step adoption guide and the HTTPS-listener / mid-render headers-sent gotchas for any 1.0 app adopting SSO (jcardinal)
+</content>
+</invoke>

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

@@ -2,8 +2,8 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
-| [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md |
+| [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md |
 | [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 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 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/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/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 |
 | [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/architecture.md

@@ -6,12 +6,16 @@ project: Tools
 client: shared
 type: architecture
 status: active
-updated: 2026-06-25
+updated: 2026-06-26
 owners: [jcardinal]
 files:
   - tools/index.php
   - tools/_/app/framework.php
   - tools/_/app/frameworkindex.php
+  - tools/assets/img/favicon/favicon.ico
+  - tools/assets/img/favicon/favicon-32x32.png
+  - tools/assets/img/favicon/favicon-16x16.png
+  - tools/assets/img/favicon/apple-touch-icon.png
   - tools/_/app/auth.php
   - tools/_/app/nav.php
   - tools/common/header.php
@@ -57,14 +61,22 @@ calling the parent initialize.
 
 No per-host `stylePath` subfolder — one `assets/css/style.css`. Uses TOGA Technology logos in
 `assets/img` (`toga-brandmark-white.png` in the dark sidebar; `toga-horizontal-colored.png` on
-login/welcome). A fixed left two-column shell: dark left sidebar (`.app-nav`) with brand at top,
+login). **Favicons are app-local** under `assets/img/favicon/` (`apple-touch-icon.png` 180x180,
+`favicon-32x32.png`, `favicon-16x16.png`, `favicon.ico`, sourced from togatech.com) and registered
+in `_/app/frameworkindex.php` — **not** the shared `resources/images/favicon/` (Agilant) set
+referenced via `__ASSETS__`. **Convention:** a per-app favicon/brand asset belongs under that app's
+own `/assets`, never the shared `resources` repo, so changing one 1.0 app's favicon never affects
+sibling apps. A fixed left two-column shell: dark left sidebar (`.app-nav`) with brand at top,
 persona-filtered nav in the middle, pinned footer with the user's name + a ghost "Log out"
 button; content area on the right. **No top header bar** (see Critical rules).
 
 ## Home route
 
 `/` (`mvc/get.php`) renders a persona-filtered dashboard of available tools (tiles grouped by
-folder) when logged in, via `App_Nav::visibleGroups()`, or a welcome/sign-in card when not.
+folder) when logged in, via `App_Nav::visibleGroups()`. When **not** logged in, `/` immediately
+routes to `/login` (one-step SSO sign-in — no intermediate welcome card). A persona-less but
+authenticated user gets the dashboard's explicit empty-state (see
+`features/persona-gated-navigation.md`).
 
 ## Adding a tool
 
@@ -79,3 +91,6 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
   **accepted this for now** (developer decision, 2026-06-25). Future remediation: git-ignore the
   config files and rotate all exposed credentials. (Location only — no values recorded here.)
 - **SSO initiation + replay defense are open items** — see `features/saml-sso-auth.md`.
+
+## Change history
+- 2026-06-26 — Documented app-local favicons under `assets/img/favicon/` (registered in `_/app/frameworkindex.php`, not the shared `resources/` set) + the per-app-asset convention; refreshed the home-route description for one-step SSO sign-in and the persona-less empty-state (jcardinal)

package/knowledge/1.0/apps/tools/features/persona-gated-navigation.md

@@ -6,10 +6,11 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
+updated: 2026-06-26
 owners: [jcardinal]
 files:
   - tools/_/app/nav.php
+  - tools/mvc/get.php
 related:
   - ../architecture.md
   - ./saml-sso-auth.md
@@ -40,5 +41,25 @@ An action's `route` (e.g. `/developers/uuid`) maps **1:1** to `mvc/<route>/get.p
 tool means creating that file and adding one entry to `definition()` — see
 `docs/ADDING_A_TOOL.md` and the architecture doc.
 
+## Authorization model — authentication and authorization are separate
+
+**Authentication (SSO) and authorization (persona-gated nav) are independent.** Any valid,
+active Client_True user authenticates and gets a session (see
+[saml-sso-auth](./saml-sso-auth.md)) **regardless of personas** — having zero matching personas
+does **not** block login. Authorization is then applied entirely by `App_Nav::definition()`
+folder/action `personas` gates.
+
+**Persona-less user (authenticated, zero tools):** `App_Nav::render()` skips every folder/action
+the user lacks personas for, and skips now-empty groups, so the left rail renders **no links**.
+The home dashboard (`mvc/get.php`) detects the empty result and shows an explicit empty-state
+rather than a blank page:
+- subtitle: *"There are no tools available for you to see."*
+- a card: *"Your account doesn't have access to any tools. Tool access is granted by persona —
+  if you believe you should have access, contact the development team."* + a Log out action.
+
+This is intentional: a valid user is never shown a broken/blank dashboard, and access is granted
+purely by assigning personas — no code change is needed to grant a user access to an existing tool.
+
 ## Change history
+- 2026-06-26 — Documented the authorization model: authentication (SSO) and authorization (persona-gated nav) are separate — any valid user logs in regardless of personas; a persona-less user gets an empty left rail and an explicit dashboard empty-state ("no tools available", contact-dev card + Log out) instead of a blank page (jcardinal)
 - 2026-06-25 — Built App_Nav: hard-coded two-level persona-gated navigation; render() for the left rail, visibleGroups() for the dashboard, personasForRoute() for page self-guarding; route maps 1:1 to mvc/<route>/get.php (jcardinal)

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

@@ -6,16 +6,20 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
+updated: 2026-06-26
 owners: [jcardinal]
 files:
   - 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
 related:
   - ../architecture.md
+  - ../../library/features/app-sso-initiation.md
   - ../../../2.0/apps/saml/features/downstream-integration-contract.md
   - ../../../clients/true/features/users-personas-data-model.md
 ---
@@ -30,6 +34,18 @@ auto-created.
 
 ## How it works
 
+### Wiring overview
+- **`/sso/initiate`** (`mvc/sso/initiate/get.php`) — guards `isLoggedIn`, reads `config[saml]`,
+  calls `App_Sso::initiate([...])` and `App_MVC::routeTo($url); exit;`. Initiation now uses the
+  reusable 1.0 [`App_Sso`](../../library/features/app-sso-initiation.md) library class (no longer a
+  placeholder).
+- **`/sso`** (`mvc/sso/get.php`) — the handoff consumer (below).
+- **Core.Domains** — a fixed-uuid row registers this app's return domain so the gateway resolves
+  client/environment/return URL: `uuid 2927bc15-e347-4358-a430-fb28f9446d27`, `clientId 1` (True),
+  `appId 30`, `environmentId 1` (production), `domain https://tools.togatech.com/sso`. The uuid
+  **equals** config `domain_uuid` (created in `dbchanges2/Core/2026-06-26a - ToolsSsoDomain.sql`,
+  applied to live Core).
+
 ### 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`.
@@ -42,7 +58,8 @@ auto-created.
 4. Load the active Client_True user: `WHERE uuid = ? AND isActive = 1`. No match → fail closed.
 
 ### Session establishment (`establishSession()`)
-- Calls `session_regenerate_id(true)`, then caches the user and **persona names** in `$_SESSION`.
+- Calls `session_regenerate_id(true)` **guarded by `if (!headers_sent())`** (see gotcha), then
+  caches the user and **persona names** in `$_SESSION`.
 - Persona lookup (read-only `db_true`):
   `SELECT p.name FROM Users u JOIN Users_Personas up ON up.userId=u.id JOIN Personas p ON p.id=up.personaId WHERE u.uuid = <escaped>`.
 - The session cookie is set **HttpOnly + SameSite=Lax** in `App_Framework_Tools::initialize()`
@@ -51,26 +68,42 @@ auto-created.
 ### Page guarding
 - `requireAuth([personas])` at the top of each page; `hasAnyPersona()` is `array_intersect`
   against the cached session personas. App_Nav uses the same cached data to filter the nav.
+- **Authentication ≠ authorization.** A session establishes for **any** valid/active user even
+  when they have **zero** matching personas; in that case the nav is empty and the dashboard shows
+  an explicit empty-state — see [persona-gated-navigation](./persona-gated-navigation.md).
 
 ### Dev bypass (double-gated, fails closed in prod)
 `mvc/login/post.php` permits **email-only** login **only** when config `[internal] dev_mode`
 is truthy **and** `App_Registry::inDevMode()` — both must hold. When used it writes a `SECURITY`
 line to `error_log`.
 
+### One-step sign-in
+Home route `/` (`mvc/get.php`), when not logged in, does `App_MVC::routeTo('/login'); return;` so the
+SSO button is the only click — the previous welcome-card "Sign in" → `/login` intermediate step was
+removed.
+
 ## Gotchas / known issues
 
-- **SSO initiation is not implemented in this 1.0 app.** Building the signed AuthnRequest lives
-  in 2.0 `_underscore` (`singleSignOnServiceUrl()`); login here points at a configurable
-  `[saml] initiation_url` **placeholder**. Open item: needs a gateway initiation entry point or
-  a ported builder.
+- **Consumer route runs mid-render → headers already sent.** The 1.0 framework runs `mvc/sso/get.php`
+  **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).
 - **No app-side replay defense.** The handoff token carries no nonce/timestamp the app verifies.
   Recommend the gateway embed `iat` + `jti`.
 
 ## Config keys
 
 `[database_true]` (read-only Client_True); `[saml]` `api_secret_access_token` /
-`api_secret_access_token_previous`, `initiation_url`, `client_authentication_uuid`,
-`domain_uuid`, `true_client_uuid`; `[internal]` `dev_mode`.
+`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.
 
 ## Change history
+- 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/apps/tools/workflows/deploy-to-elastic-beanstalk-al2023.md

@@ -117,8 +117,19 @@ setup — the git clone (`020`) deliberately does **not** use it (see gotchas).
   e.g. `GIT=$(which git || echo /usr/bin/git)`.
 - **cfn-init `files:` runs before `container_commands`** — the correct pattern for writing a
   script and then executing it in the same config.
+- **A SAML SSO return-leg "connection timeout" is a missing HTTPS listener, not code. (CONFIRMED + RESOLVED.)**
+  When the gateway's return redirect to `https://<host>/sso` times out in the browser, verify the
+  **EB/ALB HTTPS (443) listener + ACM cert cover the EXACT return hostname before debugging
+  PHP/SAML.** Root cause for Tools was **confirmed**: the `tools.togatech.com` EB environment had
+  **no HTTPS (443) listener configured at all**. Adding the HTTPS:443 listener (with an ACM cert
+  covering the exact return hostname) fixed the SSO return leg completely — **no code change was
+  involved.** Diagnosis signature: `curl` to the public `https://` URL **from the instance itself**
+  returns `http=000` after the full timeout, while `curl http://127.0.0.1` with a `Host:` header
+  returns `200` fast. Reusable for any TOGA app behind Elastic Beanstalk.
 
 ## Change history
+- 2026-06-26 — CONFIRMED + RESOLVED the SAML SSO return-leg gotcha: the `tools.togatech.com` EB environment had no HTTPS (443) listener at all; adding the HTTPS:443 listener + ACM cert covering the exact return hostname fixed the SSO return leg with no code change (jcardinal)
+- 2026-06-26 — Added the SAML SSO return-leg gotcha: a "connection timeout" on `https://<host>/sso` was a missing EB/ALB HTTPS (443) listener for the new `togatech.com` hostname (not PHP/SAML); documented the curl `http=000` vs `127.0.0.1` 200 diagnosis (jcardinal)
 - 2026-06-26 — Documented the AL2 → AL2023 (PHP 8.5) EB migration for Tools: package renames
   (`libstdc++48`→`libstdc++`, `php73-ldap`→`php-ldap`, drop `libcurl`), php ini via cfn-init
   `files:` writing `/etc/php.d/application.ini`, bash-based library clone replacing the

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)_ — 9 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 10 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)

package/knowledge/clients/true/profile.md

@@ -8,7 +8,7 @@ project: _Underscore
 client: true
 type: profile
 status: active
-updated: 2026-06-25
+updated: 2026-06-26
 owners: [jcardinal]
 files: []
 related:
@@ -26,5 +26,8 @@ by staff role (e.g. the planned Toolbox app) reads its `Users` / `Personas` mode
 - **Client identifier:** `True`
 - **SSO mapper:** `_Model_True_ClientAuthentication` (base; matches by email from NameID)
 
-The new **Tools** app (1.0; repo `tools`) reads the `Client_True` DB **read-only** to gate its
-internal tooling by staff persona (see `1.0/apps/tools/`).
+The **Tools** app (1.0; repo `tools`) authenticates True users via **SSO** through
+`saml.togahub.com` and reads the `Client_True` DB **read-only** to gate its internal tooling by
+staff persona (see `1.0/apps/tools/`). Its gateway return domain is registered in `Core.Domains`
+(`uuid 2927bc15-e347-4358-a430-fb28f9446d27`, `clientId 1`, `appId 30`, env 1,
+`https://tools.togatech.com/sso`).

package/package.json

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