toga-ai 1.0.206 → 1.0.207

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

@@ -103,3 +103,13 @@ packages: `phpoffice/phpspreadsheet ^1.6`, `smalot/pdfparser ^0.14.0`.
 - **Timezone** is always `America/Chicago` (set in `_.php`).
 - **`__APPROOT__`** is resolved by locating an ancestor folder named `_`; each app must
   have that `_` folder at its root.
+
+## App_String cross-framework crypto (`encryptWithKey` / `decryptWithKey`)
+
+`App_String::encryptWithKey($data, $key)` and `decryptWithKey($data, $key)` (public static) do
+**AES-256-CBC**: random IV via `random_bytes`, returning `base64(iv . ciphertext)` with openssl
+flag `0`. They are **deliberately byte-for-byte interoperable** with the 2.0
+`_String::encryptWithKey` / `decryptWithKey`, so a SAML handoff token encrypted by the 2.0
+gateway decrypts in any 1.0 app (round-trip verified). Net-new methods — no existing method
+changed, no behavior change for existing apps. First consumer: the Tools app's `App_Auth`
+(`1.0/apps/tools/features/saml-sso-auth.md`).

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

@@ -0,0 +1,8 @@
+# tools (Tools) — 1.0 knowledge
+
+| 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 — 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 |

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

@@ -0,0 +1,81 @@
+---
+title: Tools (1.0 Internal-Tools App) Architecture
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: architecture
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - 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
+related:
+  - ./features/saml-sso-auth.md
+  - ./features/persona-gated-navigation.md
+  - ./features/developer-tools.md
+  - ../library/architecture.md
+  - ../library/features/mvc-page-pattern-and-app-skeleton.md
+---
+
+## Summary
+
+**Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind
+simple interfaces, gated by Client_True staff persona. It is modeled on `togaview` and depends on
+the `library` core. Auth comes via the SAML gateway `?saml=` handoff; the app owns its own
+session and reads `Client_True` **read-only**. Adding a tool = create `mvc/<route>/get.php`
+(copy `mvc/_TEMPLATE`) + add one `App_Nav::definition()` entry + `App_Auth::requireAuth([...])`.
+
+**Critical rules:** Do NOT use bare `<header>` elements in this app — they inherit the legacy
+dashboard stylesheet's `header{position:fixed;width:100vw}` rule and cause horizontal scroll
+(the top header bar was removed for exactly this reason). A nav action's `route` maps **1:1** to
+`mvc/<route>/get.php`. Auth fails **closed** and never auto-creates users; the dev bypass is
+double-gated (`[internal] dev_mode` AND `App_Registry::inDevMode()`). `config.*.ini`
+(incl. `config.prod.ini`) is committed with plaintext production secrets — a known, team-accepted
+risk (see Known issues); never add more secrets and treat these as compromised if leaked.
+
+## Boot & structure
+
+Standard 3-line `index.php`: `require '_.php'; App_Framework_Tools::initialize();
+App_Framework_Tools::renderIndex();`. App-specific framework subclasses
+`App_Framework_Tools` / `App_FrameworkIndex_Tools` live in `_/app/`. The 1.0 folder-based MVC
+page pattern is unchanged from the library skeleton (see the library feature doc).
+
+`App_Framework_Tools::initialize()` sets the session cookie HttpOnly + SameSite=Lax before
+calling the parent initialize.
+
+## Layout (single-style app)
+
+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,
+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.
+
+## Adding a tool
+
+Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one entry to
+`App_Nav::definition()`, and put `App_Auth::requireAuth([...personas])` at the top. Documented in
+`docs/ADDING_A_TOOL.md`. See the App_Nav and App_Auth feature docs.
+
+## Known issues / security
+
+- **Plaintext secrets committed to git.** `config.*.ini` (incl. `config.prod.ini`) contains
+  plaintext production secrets (RDS master password, SMTP, Payeezy, NetSuite). The team has
+  **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`.

package/knowledge/1.0/apps/tools/features/developer-tools.md

@@ -0,0 +1,37 @@
+---
+title: Tools — Developers Folder (UUID & Password Generators)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/mvc/developers/uuid/get.php
+  - tools/mvc/developers/password/get.php
+related:
+  - ../architecture.md
+  - ./persona-gated-navigation.md
+---
+
+## Summary
+
+The first two tools shipped in the Tools app, both under the **Developers** folder and gated to
+personas **Development Team** / **TOGa Technology**. They are the reference example of the
+"one small tool = one `mvc/<route>/get.php`" pattern.
+
+## How it works
+
+### Generate UUID (`mvc/developers/uuid/get.php`)
+- Server generates an RFC 4122 **v4** UUID via `random_bytes(16)` with version/variant bits set.
+- UI is click-to-copy, then instant **client-side** regenerate using `crypto.getRandomValues`.
+
+### Generate Password (`mvc/developers/password/get.php`)
+- Reproduces the standalone `test/team/generate_password.php` script.
+- `App_String::generateSupportCode(8)` produces the password; `App_String::passwordHash()`
+  produces the bcrypt hash. The page shows **both** the password and the hash, each copyable.
+
+## Change history
+- 2026-06-25 — Built the first two Developers tools: RFC 4122 v4 UUID generator and a password+bcrypt-hash generator (ported from test/team/generate_password.php), both gated to Development Team / TOGa Technology personas (jcardinal)

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

@@ -0,0 +1,44 @@
+---
+title: Tools Persona-Gated Navigation (App_Nav)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/_/app/nav.php
+related:
+  - ../architecture.md
+  - ./saml-sso-auth.md
+---
+
+## Summary
+
+`App_Nav` is the Tools app's two-level, **persona-gated** navigation. The structure is a single
+**hard-coded `definition()` array** (NOT in the DB), so developers/Claude edit it directly. It
+drives both the left-rail nav and the home dashboard, and is the single source of truth for which
+personas may reach a given route.
+
+## How it works
+
+### Structure
+- Two levels: **folders** (grouping) → **actions** (each loads a page).
+- Each folder and each action carries a `personas` list. An item is visible iff
+  `App_Auth::hasAnyPersona()` matches — folder gate plus an optional per-action gate.
+
+### Render surfaces
+- `render()` — emits the filtered left-rail nav with active-route highlighting.
+- `visibleGroups()` — returns the filtered structure as data for the home dashboard tiles.
+- `personasForRoute()` — returns the union of folder+action personas so a page can self-guard
+  with `App_Auth::requireAuth(...)` using the same data the nav used.
+
+### Route convention
+An action's `route` (e.g. `/developers/uuid`) maps **1:1** to `mvc/<route>/get.php`. Adding a
+tool means creating that file and adding one entry to `definition()` — see
+`docs/ADDING_A_TOOL.md` and the architecture doc.
+
+## Change history
+- 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

@@ -0,0 +1,76 @@
+---
+title: Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/_/app/auth.php
+  - tools/mvc/sso/get.php
+  - tools/mvc/login/get.php
+  - tools/mvc/login/post.php
+  - tools/mvc/logout/get.php
+related:
+  - ../architecture.md
+  - ../../../2.0/apps/saml/features/downstream-integration-contract.md
+  - ../../../clients/true/features/users-personas-data-model.md
+---
+
+## Summary
+
+`App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=`
+handoff (see the 2.0 SAML downstream integration contract), establishes its own session, and
+gates every page by **Client_True persona**. The gateway holds no session — session ownership
+is entirely this app's. Auth fails **closed** to a self-contained 401 page; users are **never**
+auto-created.
+
+## How it works
+
+### 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).
+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.
+
+### Session establishment (`establishSession()`)
+- Calls `session_regenerate_id(true)`, 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()`
+  before the parent initialize runs.
+
+### 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.
+
+### 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`.
+
+## 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.
+- **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`.
+
+## Change history
+- 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/INDEX.md

@@ -12,6 +12,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 11 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
+- **tools** (Tools) — 4 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 
@@ -27,7 +28,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 6 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 6 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 7 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 
 ## standalone framework

package/knowledge/clients/true/profile.md

@@ -3,6 +3,7 @@ title: "TOGA Technology"
 framework: "2.0"
 apps:
   - _underscore
+  - tools
 project: _Underscore
 client: true
 type: profile
@@ -24,3 +25,6 @@ by staff role (e.g. the planned Toolbox app) reads its `Users` / `Personas` mode
 - **Client DB:** `Client_True`
 - **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/`).

package/knowledge/registry.json

@@ -182,5 +182,14 @@
     "framework": "2.0",
     "role": "app",
     "dependsOn": []
+  },
+  {
+    "repo": "tools",
+    "project": "Tools",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
   }
 ]

package/package.json

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