toga-ai 1.0.670 → 1.0.671

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

@@ -6,3 +6,4 @@
 | [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 |
 | [Onboarding a New SSO Client with Just-In-Time User Provisioning](workflows/onboarding-a-new-sso-client.md) | The repeatable procedure for adding a new client to the 2.0 `saml` gateway when that client's users do **not** pre-exist in our database and must be created on | saml/Controller/Index.php, _underscore/Model/Core/ClientAuthentication.php, _underscore/Model/Rate/ClientAuthentication.php, _underscore/Database.php |
+| [Rotating the SAML SP Certificate](workflows/rotating-the-saml-sp-certificate.md) | The repeatable procedure for replacing the TOGa **SAML Service Provider (SP) credential** — the X.509 cert + private key at `_underscore/Assets/ssl/togahub_com. | _underscore/Assets/ssl/togahub_com.crt, _underscore/Assets/ssl/togahub_private_key.key, _underscore/Model/Core/ClientAuthentication.php, saml/Controller/Index.php |

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

@@ -0,0 +1,109 @@
+---
+title: Rotating the SAML SP Certificate
+framework: "2.0"
+repo: saml
+project: SAML SSO Gateway
+client: shared
+type: workflow
+status: active
+updated: 2026-08-27
+owners: ["jcardinal"]
+files:
+  - _underscore/Assets/ssl/togahub_com.crt
+  - _underscore/Assets/ssl/togahub_private_key.key
+  - _underscore/Model/Core/ClientAuthentication.php
+  - saml/Controller/Index.php
+related:
+  - 2.0/apps/saml/architecture.md
+  - 2.0/apps/saml/workflows/onboarding-a-new-sso-client.md
+---
+
+## Summary
+
+The repeatable procedure for replacing the TOGa **SAML Service Provider (SP) credential** — the
+X.509 cert + private key at `_underscore/Assets/ssl/togahub_com.crt` and
+`_underscore/Assets/ssl/togahub_private_key.key`. This credential is the SP's own identity, used
+to **sign outgoing AuthnRequests** and to **decrypt inbound assertions**. It is a bilateral,
+partner-pinned trust artifact, **not** the TLS cert that terminates browser HTTPS. There was no
+rotation runbook before this (git shows two prior undocumented swaps); this closes that gap.
+
+For *why* a self-signed, long-lived cert is the correct choice here (rather than a public-CA TLS
+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).
+- **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.
+
+## Current credential (as of 2026-08-27, staged — cutover pending)
+
+A dedicated **self-signed** replacement was generated to decouple the SP credential from the
+short-lived DigiCert/Thawte TLS wildcard that had been reused as the SP cert (see Background):
+
+- Self-signed X.509, RSA 2048, SHA-256.
+- Subject/Issuer: `C=US, ST=Illinois, L=Naperville, O=TOGA Technology, Inc., CN=togahub.com`
+  (reflects the new company name TOGA Technology, Inc. / Naperville, IL — formerly Agilant
+  Solutions, Inc.). CN only, **no SANs** — SANs are meaningless for bilateral SAML/AS2 trust.
+- Validity: **2026-08-27 → 2036-08-27** (10 years). Capped at 10y because RSA 2048 is
+  NIST-assured only to ~2030; a longer term would call for RSA 4096, and client compatibility
+  with 4096 is unconfirmed.
+- SHA-256 fingerprint:
+  `0E:1E:9E:11:35:B9:74:79:6F:07:2B:1F:E7:05:B8:B6:E9:07:00:0B:9E:A2:36:94:04:F6:AC:65:AC:B0:03:78`
+
+### Where the material lives (never paste the key)
+
+- **AWS Secrets Manager**, account **654654170868**, region **us-east-1**.
+- Secret name: **`toga/ssl/togahub_com-selfsigned-2036`**.
+- ARN: `arn:aws:secretsmanager:us-east-1:654654170868:secret:toga/ssl/togahub_com-selfsigned-2036-S2r3SR`.
+- JSON keys: `{certificate, privateKey}`. Retrieve the private key from here at cutover — it is
+  **not** stored anywhere else and must never be committed or pasted into chat/docs.
+- The public cert only was staged locally at `C:\TEMP\toga-ssl-2026\togahub_com.crt`; the local
+  private key was deleted.
+
+## Cutover procedure
+
+1. **PRE-CUTOVER SAFETY CHECK — confirm this cert is not serving live TLS.** Before replacing a
+   real CA cert with a self-signed one, verify the `.crt`/`.key` at `_underscore/Assets/ssl/` is
+   **not** also terminating browser/API TLS anywhere (check the `saml` repo + its EB/Apache
+   config). TLS is normally ACM-terminated at the ALB, so this repo file should only be the
+   SAML/AS2 credential — but verify against the checked-out `saml` repo first.
+2. **Distribute the new public cert to every pinning partner** (SAML IdPs, AS2 partners, any
+   PunchOut buyer that pins our leaf) and let them import it. Include the SHA-256 fingerprint
+   above as the verification line.
+3. **Coordinate a cutover date/time** with those partners.
+4. **Replace both files in `_underscore` on the `_production` branch** — via a feature branch +
+   PR, **never a direct commit to `_production`**. No code change is needed: the path constants
+   already point at these filenames.
+5. **Redeploy `saml` after the `_underscore` merge.** `saml` pulls `_underscore` from
+   `_production` at EB build time (`.ebextensions/git.php` + prebuild hook), so a saml-only
+   deploy will **not** pick up the new cert. Deploy target: `saml-production` EB env, us-east-1,
+   DNS `saml.togahub.com`.
+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.
+
+## Background — why the change
+
+The old `_underscore/Assets/ssl/togahub_com.crt` was a **reused DigiCert/Thawte multi-domain
+wildcard TLS cert** (issuer "Thawte TLS RSA CA G1"; SANs for togahub.com, togacommerce.com,
+togadesk.com, togaretail.com, togasupply.com, togaview.com, togaiq.com plus `*.` of each; RSA
+2048; validity Mar 2 2026 → Sep 16 2026, ~6.5 months). Reusing a short-lived public-CA TLS cert
+as the SAML SP credential accidentally coupled SAML to a ~6-month renewal treadmill and forced
+every pinning partner to reinstall on each renewal. The dedicated self-signed 10-year cert
+**decouples the SP credential from TLS renewals** — that is the whole point of the change.
+
+## Change history
+- 2026-08-27 — Created while replacing the SAML SP credential. Documented the SP cert's dual use
+  (signing AuthnRequests / decrypting assertions), the new self-signed 10-year cert identity and
+  its AWS Secrets Manager location, the pre-cutover TLS-usage safety check, and the
+  `_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>

package/knowledge/2.0/standards/ssl-certificate-trust-model.md

@@ -0,0 +1,82 @@
+---
+title: SSL Certificate Trust-Model Strategy
+framework: "2.0"
+project: _Underscore
+client: shared
+type: standard
+status: active
+updated: 2026-08-27
+owners: [jcardinal]
+files: []
+related:
+  - ../apps/saml/workflows/rotating-the-saml-sp-certificate.md
+  - ../apps/saml/architecture.md
+---
+
+## Summary
+
+Which kind of SSL/TLS certificate to use is decided by the **trust model** of the endpoint, not
+by habit. Pick wrong and you land on a renewal treadmill; pick right and renewals become either
+invisible or irrelevant. This standard is platform-wide (1.0, 2.0, standalone, and pure-AWS
+infra). It was established while replacing the 2.0 SAML SP credential — see the
+[SAML SP certificate rotation runbook](../apps/saml/workflows/rotating-the-saml-sp-certificate.md).
+
+**Critical rule:** if a partner installs/pins OUR specific cert, use a **self-signed, long-lived**
+cert. If AWS terminates the TLS for browsers/generic clients, use **ACM public, auto-renewing**.
+Never reuse a public-CA TLS cert as a pinned bilateral credential.
+
+## The decision
+
+### 1. Bilateral / pinned trust → self-signed, long-lived
+The partner installs and pins our specific certificate: SAML SP credential, AS2 (AWS Transfer
+Family), PunchOut endpoints a buyer pins. Use a **self-signed** cert with a multi-year validity
+(we generate 10-year). Distribute the public cert to the partner; import cert + key into the
+service. Because trust is by pinning, no public CA is involved and validity can be long.
+
+### 2. Standard HTTPS, AWS-terminated → ACM public, non-exportable, auto-renewing
+Browsers / generic clients reach the endpoint through an ALB, CloudFront, or API Gateway that AWS
+terminates. Use an **ACM public certificate** (non-exportable, auto-renewing). Distribute nothing;
+renewal is invisible.
+
+### 3. Standard HTTPS, NOT AWS-terminated → ACM exportable, or move behind an ALB
+A server terminates its own TLS (e.g. the legacy Vision box). Options: an **ACM *exportable*
+public cert** (a real 2025 AWS feature) — but still ~13-month validity, so you must redeploy on
+every renewal — OR move the endpoint behind an ALB to get free auto-renew (option 2).
+
+## Why long-lived ⇒ self-signed
+
+**Every publicly-trusted cert, exportable or not, is capped at ~398 days** by the CA/Browser
+Forum, dropping toward ~47 days by 2029. Only **self-signed / private-CA** certs can be
+multi-year. So "long-lived AND distributable" necessarily means self-signed (or AWS Private CA at
+~$400/mo — rejected here as overkill).
+
+The pain of "shrinking public-cert validity" is really a **distribution problem**: automate
+distribution via ACM and it disappears; a partner who pins the leaf breaks on every rotation.
+That is exactly why bilateral, pinned credentials should be self-signed and long-lived — and why
+reusing a short-lived public-CA TLS cert as a pinned SP/AS2 credential (as we accidentally did for
+SAML) couples an otherwise stable credential to a ~6-month treadmill.
+
+## Key sizing
+
+Self-signed long-lived certs use RSA 2048 / SHA-256 with validity capped at ~10 years, because
+RSA 2048 is NIST-assured only to ~2030. A longer term would want RSA 4096, but partner
+compatibility with 4096 is often unconfirmed — verify before choosing it.
+
+## Worked example — Vision / Canon cXML PunchOut (a split-trust endpoint)
+
+The Vision cXML PunchOut endpoint (`vision.asisystem.com`, a separate domain/cert from
+togahub.com) is a single cert serving **two legs with different trust models**, which is why its
+renewals are painful:
+
+- **Server-to-server cXML leg** — auth is a `<Credential>` **SharedSecret** (localVerifyIdentity),
+  not a client cert; our cert there is only the endpoint's TLS wrapper. The buyer reinstalling our
+  cert on every renewal indicates they **pin our leaf** — effectively bilateral trust → a
+  self-signed long-lived cert fits.
+- **PunchOut portal StartPage** (`punchoutSetupResponseUrlPrefix`) is a real **browser** session →
+  needs a public-CA cert (option 2).
+
+Bundling both on one cert is the root of the pain. The fix is to **split** them: ACM for the
+browser portal, self-signed for the pinned cXML endpoint. StartPage host is per-identity
+configurable, so the split is feasible. Canon is slated to move from Vision to TOGa Commerce (2.0,
+already ALB+ACM), which auto-solves the browser leg.
+</content>

package/knowledge/INDEX.md

@@ -23,7 +23,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 13 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
-- **saml** (SAML SSO Gateway) — 4 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
+- **saml** (SAML SSO Gateway) — 5 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 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) — 7 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)

package/package.json

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