toga-ai 1.0.775 → 1.0.776

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

@@ -6,7 +6,7 @@ project: SAML SSO Gateway
 client: shared
 type: architecture
 status: active
-updated: 2026-08-27
+updated: 2026-09-04
 owners: ["rgirish", "jcardinal"]
 files:
   - saml/index.php
@@ -49,7 +49,7 @@ Legacy `/?meta`, `/?acs`, `/?sls` query-style paths are rewritten automatically.
 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/`.
+5. **Assertion decryption (dual-credential during cert overlap).** `/acs` builds two `X509Credential`s from the SP encryption keys in `_underscore/Assets/ssl/` (new + old) and calls `$reader->decryptMultiAssertion([$credentialNew, $credentialOld], $ctx)`. LightSaml's `decryptMulti()` tries each credential and only re-throws once all fail (fails closed), so an assertion encrypted to either the new or old SP key decrypts during a rotation overlap. See the SP cert-rotation workflow.
 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.
@@ -59,6 +59,10 @@ Legacy `/?meta`, `/?acs`, `/?sls` query-style paths are rewritten automatically.
 ### Failure responses
 `Invalid SAMLResponse (Code = 1–4)`, `SAML Authentication Failed`, `User Authentication Failed`.
 
+## /meta SP credential (signing vs encryption)
+
+`/meta` publishes TWO independent `KeyDescriptor`s: `use="signing"` and `use="encryption"`. They can carry **different** certs, which lets the SP encryption cert rotate without touching the signing cert. The private key that signs our **outbound** AuthnRequests lives in `_underscore` (`_Model_Core_ClientAuthentication::PATH_TO_PRIVATE_KEY`) and is **global — one key for all client IdPs**, so the signing cert cannot flip until every IdP has loaded the new metadata. Cert paths are set via class constants in `saml/Controller/Index.php` (`PATH_TO_SIGNING_CERTIFICATE`, `PATH_TO_ENCRYPTION_CERTIFICATE_NEW/OLD` + matching private-key constants — paths only, no key material). Full procedure: SP cert-rotation workflow.
+
 ## Per-client SSO extension pattern
 
 Identity mapping lives in `_underscore/Model/<ClientIdentifier>/ClientAuthentication.php`.
@@ -90,6 +94,7 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 - **`_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 — 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.
+- **`/meta` cert lines must be `trim()`-ed (CRLF).** The `.crt` files in `_underscore/Assets/ssl` are CRLF-encoded; the cert-format code does `explode("\n", ...)` and indents each line, so without a per-line `trim()` a stray `\r` ends up on every base64 line inside `<ds:X509Certificate>`. Trim each line in both the signing and encryption blocks.
 - **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.
 
@@ -97,3 +102,4 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 - 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)
 - 2026-08-27 — Documented non-prod shared-ALB self-registration postdeploy hook (`060_...sh` + `ebs/register_instance_to_shared_application_load_balancer.php`); skips `production`, requires `aws/aws-sdk-php` + two IAM actions; cross-linked worker2 ALB auto-registration feature (jcardinal)
+- 2026-09-04 — `/acs` now dual-credential decrypt (`decryptMultiAssertion([new, old])`) for SP encryption-cert overlap; documented `/meta`'s two KeyDescriptors (signing vs encryption) and the global outbound-signing key; added the CRLF `/meta` cert-line `trim()` gotcha. (jcardinal)

package/knowledge/2.0/apps/saml/workflows/rotating-the-saml-sp-certificate.md

@@ -6,7 +6,7 @@ project: SAML SSO Gateway
 client: shared
 type: workflow
 status: active
-updated: 2026-08-27
+updated: 2026-09-04
 owners: ["jcardinal"]
 files:
   - _underscore/Assets/ssl/togahub_com.crt
@@ -32,16 +32,58 @@ cert), see the SSL certificate trust-model strategy standard.
 
 ## How the SP credential is used
 
-- **Private key — signs outgoing SP AuthnRequests.** `_Model_Core_ClientAuthentication`
-  (`_underscore/Model/Core/ClientAuthentication.php`) points its `PATH_TO_PRIVATE_KEY` constant
-  at `_underscore/Assets/ssl/togahub_private_key.key` and signs with XMLSecLibs `RSA_SHA256`
-  (around lines 11 / 95 / 107).
-- **Public cert — published in SP metadata and used to decrypt assertions.** The `saml` repo's
-  `Controller/Index.php` uses the cert for assertion decryption; the `/meta` route publishes it
-  in SP metadata via `file_get_contents` read fresh on each request (no server-side cache).
+The SP cert/key is used in **four** places — three in `saml`, one in `_underscore`:
+
+- **(a) `/meta` signing `KeyDescriptor`** — `saml/Controller/Index.php` publishes the cert IdPs
+  use to verify our outbound AuthnRequest signature. Read fresh via `file_get_contents` on each
+  request (no server-side cache).
+- **(b) `/meta` encryption `KeyDescriptor`** — the cert IdPs use to encrypt assertions to us.
+- **(c) `/acs` assertion decryption** — `saml/Controller/Index.php` decrypts the inbound
+  encrypted assertion with the matching private key.
+- **(d) Outbound AuthnRequest signing (GLOBAL)** — `_Model_Core_ClientAuthentication`
+  (`_underscore/Model/Core/ClientAuthentication.php`, `PATH_TO_PRIVATE_KEY`, around lines
+  11 / 95 / 107) signs the redirect-binding AuthnRequest query string with XMLSecLibs
+  `RSA_SHA256`. **One key signs the login requests we send to ALL client IdPs — you cannot sign
+  per-client.** This is why signing and encryption rotate on different schedules (see
+  *Encryption-only rotation*).
+
 - **IdPs cache metadata up to 7 days** (`cacheDuration PT604800S`), so a cert change is not
   guaranteed to be picked up by every IdP immediately after deploy.
 
+## Encryption-only rotation with an overlap window (2026-09-04)
+
+Because a cert change is not picked up by every IdP at once, the safe rotation splits the two
+uses and **rotates encryption first, signing later**:
+
+- **Signing stays on the OLD cert.** If `/meta` advertised the new signing cert (or (d) signed
+  with the new key) before every IdP loaded the new metadata, any IdP that verifies our
+  AuthnRequest signature could **reject our login requests**. Signing flips only after all IdPs
+  are on the new metadata — a later, coordinated step.
+- **Encryption rotates now, with both keys accepted.** `/meta` presents TWO independent
+  `KeyDescriptor`s: `use="signing"` = current/old cert, `use="encryption"` = new cert. Two
+  independent KeyDescriptors is valid SAML metadata, so encryption can rotate without touching
+  signing.
+- **`/acs` accepts EITHER encryption key during overlap.** It builds two `X509Credential`s
+  (new + old) and calls `$reader->decryptMultiAssertion([$credentialNew, $credentialOld], $ctx)`.
+  In vendored LightSaml, `decryptMulti()` tries each credential and only re-throws once all fail
+  — so it fails closed. This lets an IdP that has re-encrypted to the new cert and one still on
+  the old cert both succeed.
+- **Class constants (paths only, no key material)** in `saml/Controller/Index.php` replaced the
+  old single pair: `PATH_TO_SIGNING_CERTIFICATE`; `PATH_TO_ENCRYPTION_CERTIFICATE_NEW` +
+  `PATH_TO_ENCRYPTION_PRIVATE_KEY_NEW`; `PATH_TO_ENCRYPTION_CERTIFICATE_OLD` +
+  `PATH_TO_ENCRYPTION_PRIVATE_KEY_OLD`.
+- **What forced it:** old cert `togahub_com.crt` (O=Agilant Solutions) expires **2026-09-16**;
+  new cert `togahub_com_2036-08-27.crt` (O=TOGA Technology, Inc.) is valid to 2036.
+
+### Remaining steps / follow-ups (not yet done)
+1. **Flip signing to the new cert** once every IdP has loaded the new metadata — advertise the
+   new signing cert in `/meta` and switch (d) to the new key. Coordinate the date.
+2. **Log which SP key decrypted** (new vs old, identifier only — never assertion data) so you can
+   see which IdPs have cut over and when it is safe to drop the old key.
+3. **Wrap the `/acs` decrypt in try/catch** and echo `Invalid SAMLResponse (Code = 5)` to match
+   the existing coded failure responses.
+4. **Dedupe the two `/meta` cert-format blocks** into a shared helper (non-blocking).
+
 ## Current credential (as of 2026-08-27, staged — cutover pending)
 
 A dedicated **self-signed** replacement was generated to decouple the SP credential from the
@@ -88,6 +130,14 @@ short-lived DigiCert/Thawte TLS wildcard that had been reused as the SP cert (se
 6. **Deploy the cert+key to the other bilateral services** that use the same SP credential —
    AS2 (AWS Transfer Family) and any other pinned endpoint — importing both cert and key.
 
+### Gotcha — trim each cert line (CRLF)
+
+The `.crt` files in `_underscore/Assets/ssl` are **CRLF-encoded**. The `/meta` cert-format code
+does `explode("\n", ...)` then indents each line. Without a per-line `trim()`, a stray carriage
+return (`\r`) is embedded on every base64 line inside `<ds:X509Certificate>` in the metadata XML.
+Fix: `trim()` each line in the cert-format code — applied to both the signing and encryption
+blocks. (Latent bug that pre-dated this change in the single original block.)
+
 ## Background — why the change
 
 The old `_underscore/Assets/ssl/togahub_com.crt` was a **reused DigiCert/Thawte multi-domain
@@ -105,5 +155,12 @@ every pinning partner to reinstall on each renewal. The dedicated self-signed 10
   `_underscore`-then-`saml` cutover ordering. Discovered the prior cert was a reused short-lived
   DigiCert wildcard TLS cert, which is the reason for the switch. Cutover itself still pending.
   (jcardinal)
-</content>
-</invoke>
+- 2026-09-04 — Documented the **encryption-only rotation** actually built in
+  `saml/Controller/Index.php`: `/meta` now presents two `KeyDescriptor`s (signing=old,
+  encryption=new) and `/acs` uses `decryptMultiAssertion([new, old])` so both encryption keys
+  work during overlap; new path-only class constants replaced the single cert/key pair.
+  Recorded that outbound AuthnRequest signing uses one GLOBAL key for all IdPs, which is why
+  signing stays on the old cert until every IdP loads the new metadata. Added the CRLF
+  per-line-`trim()` gotcha for `/meta` cert formatting, and the open follow-ups. Change is
+  working-tree only (deploys via `saml` on `_production`); Rate is testing against
+  `saml-production`. (jcardinal)

package/package.json

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