toga-ai 1.0.812 → 1.0.813

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

@@ -15,6 +15,7 @@
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki |
 | [Running 2.0 code from a bare CLI script (bootstrap + transactions)](features/cli-script-bootstrap.md) | A throwaway CLI script (a data check, a backfill dry-run, a render harness) that wants the real 2.0 framework — `_Model`, `_Query`, `_Database` — is **not** the |
 | [_Cloud S3 helpers (copy / get / delete / list)](features/cloud-s3-helpers.md) | `_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into workers or app code. |
+| [_Cloud Secrets Manager helper (_Cloud::getSecret)](features/cloud-secrets-manager.md) | `_Cloud::getSecret($secretName, $awsRegion = null): ?array` reads a value from **AWS Secrets Manager** for the 2.0 stack. |
 | [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP |
 | [_Config group access — the two-argument "optional" form does NOT rescue a missing GROUP](features/config-group-access.md) | `_Config::<group>('<property>')` reads a value out of the active `Config/<ENVIRONMENT>.ini`, and **it throws when the requested group is absent from the ini.** |
 | [Core.Domains — the app host registry (and why you cannot derive a host)](features/core-domains-app-host-registry.md) | `Core.Domains` is the **authoritative registry of which host serves which client's app in which environment**. |

package/knowledge/2.0/apps/_underscore/features/cloud-secrets-manager.md

@@ -0,0 +1,71 @@
+---
+title: _Cloud Secrets Manager helper (_Cloud::getSecret)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-09-15
+owners: ["jcardinal"]
+files:
+  - _underscore/Cloud.php
+related:
+  - ./cloud-s3-helpers.md
+  - ../../saml/workflows/rotating-the-saml-sp-certificate.md
+  - ../../saml/architecture.md
+---
+
+## Summary
+
+`_Cloud::getSecret($secretName, $awsRegion = null): ?array` reads a value from **AWS Secrets
+Manager** for the 2.0 stack. It lets code pull secret material (SSL certs/keys, credentials) at
+request time instead of shipping it on disk or in `production.ini`. First consumer: the SAML
+gateway's `/acs`, which builds SP encryption credentials from Secrets Manager (see the SAML SP
+certificate rotation workflow).
+
+## Key files / entry points
+
+- `_underscore/Cloud.php` — `_Cloud::getSecret(string $secretName, ?string $awsRegion = null): ?array`.
+
+## How it works
+
+1. Builds a `SecretsManagerClient` and calls `GetSecretValue` for `$secretName`.
+2. **Auth is the AWS default provider chain** — the EC2 instance role in prod, a local
+   profile/env in dev. It deliberately does **NOT** use the shared static `_Config::cloud`
+   access key that the S3 helpers use. Reason: keep the blast radius small — leaking that one
+   shared key must not also expose the SAML SP private keys. Grant the reading role its own
+   Secrets Manager permission instead.
+3. `$awsRegion` defaults to `null`; pass the secret's region explicitly (SAML passes
+   `'us-east-1'`).
+4. Returns the secret's JSON decoded to an **assoc array**. For the SSL secrets the keys are
+   `certificate`, `privateKey`, `certificateChain` (optional), `passphrase` (optional).
+5. **Caches per PHP process** (function-static) — repeated reads of the same secret in one
+   request hit the cache, not the API.
+6. **Never throws.** Any failure (missing secret, no permission, bad JSON) logs and returns
+   `null`, so a caller can skip one unusable secret and keep going rather than 500 the request.
+
+## Client variations
+
+None — shared core helper.
+
+## Gotchas / known issues
+
+- **Returns `null` on failure, does not throw.** A caller MUST null-check the result; a silent
+  `null` means "secret unavailable", not "empty secret".
+- **The role needs its own Secrets Manager grant.** Because it does not use the `_Config::cloud`
+  key, an instance/role with no `secretsmanager:GetSecretValue` gets `null` for every secret.
+  The `saml-production` EB instance role needed an inline policy added (see the SAML architecture
+  Deployment notes).
+- **A committed AWS access key + secret were found in a code comment in `Cloud.php` `initialize()`
+  and removed (2026-09-15).** Treat that key as leaked — it must be rotated separately from this
+  change. Never store credential VALUES in source or comments; reference secret names only.
+
+## Change history
+- 2026-09-15 — Added `_Cloud::getSecret()` Secrets Manager reader: default-provider-chain auth
+  (not the shared `_Config::cloud` key), per-process cache, returns decoded assoc array or `null`
+  on any failure (never throws). First used by SAML `/acs` to source SP encryption certs. Also
+  removed a committed AWS access key/secret from a `Cloud.php` `initialize()` comment — treat as
+  leaked, rotate separately. (jcardinal)
+</content>
+</invoke>

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

@@ -6,7 +6,7 @@ project: SAML SSO Gateway
 client: shared
 type: architecture
 status: active
-updated: 2026-09-04
+updated: 2026-09-15
 owners: ["rgirish", "jcardinal"]
 files:
   - saml/index.php
@@ -15,6 +15,7 @@ files:
   - saml/Config/production.ini
   - saml/.platform/hooks/prebuild/git.sh
   - saml/.ebextensions/git.php
+  - _underscore/Cloud.php
 related:
   - 2.0/apps/_underscore/architecture.md
 ---
@@ -49,7 +50,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 (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.
+5. **Assertion decryption (multi-cert, loaded from Secrets Manager at request time).** `/acs` loads the SP encryption cert+key pairs named in `ENCRYPTION_SECRET_NAMES` from AWS Secrets Manager (via `_Cloud::getSecret()`) at request time — **no key material lives on disk under `_underscore/Assets/ssl/`**. It builds an `X509Credential` per usable secret and calls `$reader->decryptMultiAssertion([...$credentials], $ctx)`. LightSaml's `decryptMulti()` tries each credential and only re-throws once all fail (fails closed), so an assertion encrypted to any current SP key decrypts, and rotation is just editing the secret list. 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.
@@ -58,10 +59,11 @@ Legacy `/?meta`, `/?acs`, `/?sls` query-style paths are rewritten automatically.
 
 ### Failure responses
 `Invalid SAMLResponse (Code = 1–4)`, `SAML Authentication Failed`, `User Authentication Failed`.
+Two codes cover the Secrets Manager cert path: **Code 5** — no usable SP credential (none of `ENCRYPTION_SECRET_NAMES` resolved to a valid cert+key); **Code 6** — a credential was built but every decrypt attempt failed (assertion not encrypted to any current SP key).
 
 ## /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.
+`/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. The signing cert path is still a class constant in `saml/Controller/Index.php` (`PATH_TO_SIGNING_CERTIFICATE`). For encryption, only `PATH_TO_ENCRYPTION_CERTIFICATE_NEW` remains — `/meta` still reads it to publish the current encryption `KeyDescriptor`. The old on-disk constants `PATH_TO_ENCRYPTION_PRIVATE_KEY_NEW`, `PATH_TO_ENCRYPTION_PRIVATE_KEY_OLD`, and `PATH_TO_ENCRYPTION_CERTIFICATE_OLD` are **removed** — `/acs` no longer reads encryption key material from disk (it comes from Secrets Manager, see /acs step 5). Full procedure: SP cert-rotation workflow.
 
 ## Per-client SSO extension pattern
 
@@ -75,6 +77,7 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 - **`_underscore` pulled at deploy time** via `.ebextensions/git.php` + prebuild hook — clones branch `_production`. Deploy `saml` after `_underscore` merges to pick up framework changes.
 - **CodePipeline:** Source (GitHub `_production`) → ManualApproval → Deploy (EB).
 - **Composer deps** installed at postdeploy via `015_install_composer.sh`.
+- **Secrets Manager read access.** The shared `ElasticBeanstalk-EC2-Instance-Profile` carries an inline `SecretsManagerReadAll` policy (`secretsmanager:GetSecretValue` + `DescribeSecret`, `Resource: "*"`) so `/acs` can read the SP encryption secrets at runtime. Developer chose account-wide `Resource: "*"` deliberately (shared profile across EB apps); verified effective access with the IAM policy simulator.
 - **Non-prod shared-ALB self-registration (2026-08-27).** Postdeploy hook
   `060_register_instance_to_shared_application_load_balancer.sh` + `ebs/register_instance_to_shared_application_load_balancer.php`
   register a non-production `saml` instance into the target group named exactly its EB env name;
@@ -95,6 +98,8 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 - **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.
+- **SP encryption certs load from Secrets Manager at request time.** `/acs` holds no encryption key material on disk (`_underscore/Assets/ssl/` no longer carries the SP encryption key). A rotation is now an edit to the `ENCRYPTION_SECRET_NAMES` list + the secrets themselves, not a redeploy of on-disk `.crt`/`.key` files.
+- **Committed AWS key must be rotated.** A hardcoded AWS key was removed from `_underscore/Cloud.php`; because it was committed to git history it is compromised — rotate it. Still open: the plaintext creds in `production.ini` and the hardcoded Sentry DSN (see next gotcha).
 - **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.
 
@@ -103,3 +108,4 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 - 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)
+- 2026-09-15 — `/acs` encryption certs now load from AWS Secrets Manager at request time via `_Cloud::getSecret()` (`ENCRYPTION_SECRET_NAMES`, no on-disk key material); added failure Codes 5 (no usable SP credential) and 6 (all decrypts failed); removed dead disk constants (`PATH_TO_ENCRYPTION_PRIVATE_KEY_NEW/_OLD`, `PATH_TO_ENCRYPTION_CERTIFICATE_OLD`), kept `PATH_TO_ENCRYPTION_CERTIFICATE_NEW` for `/meta`; documented the `SecretsManagerReadAll` inline policy on the shared EC2 instance profile; flagged the committed AWS key removed from `_underscore/Cloud.php` for rotation. (jcardinal)

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

@@ -6,16 +6,18 @@ project: SAML SSO Gateway
 client: shared
 type: workflow
 status: active
-updated: 2026-09-04
+updated: 2026-09-15
 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
+  - _underscore/Cloud.php
+  - _underscore/Model/Core/ClientAuthentication.php
+  - _underscore/Assets/ssl/togahub_com.crt
 related:
   - 2.0/apps/saml/architecture.md
   - 2.0/apps/saml/workflows/onboarding-a-new-sso-client.md
+  - 2.0/apps/_underscore/features/cloud-secrets-manager.md
+  - 2.0/standards/ssl-certificate-trust-model.md
 ---
 
 ## Summary
@@ -78,11 +80,65 @@ uses and **rotates encryption first, signing later**:
 ### 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).
+2. **Log which SP key decrypted** (secret name / identifier only — never assertion data) so you
+   can see which IdPs have cut over and when it is safe to drop a cert from the list.
+3. **Dedupe the two `/meta` cert-format blocks** into a shared helper (non-blocking).
+
+(Done 2026-09-15: the `/acs` decrypt is now wrapped and fails closed with coded responses —
+`Invalid SAMLResponse (Code = 5)` when no credential builds, `Code = 6` when all decrypts fail.)
+
+## Multi-cert decryption from Secrets Manager (2026-09-15)
+
+`/acs` no longer reads SP encryption keys from disk. It now sources **N** SP certs from AWS
+Secrets Manager and decrypts against all of them at once, so a partner can move to a different
+cert while other IdPs stay on the existing one — a superset of the earlier new/old overlap.
+
+- **Two class constants in `saml/Controller/Index.php` drive it:**
+  - `ENCRYPTION_SECRET_NAMES` — an **ordered list of Secrets Manager secret NAMES** (not values).
+  - `ENCRYPTION_SECRET_REGION` — `'us-east-1'`.
+- **How `/acs` builds credentials:** for each name it calls `_Cloud::getSecret($name, $region)`
+  (see the [_Cloud Secrets Manager helper](../../_underscore/features/cloud-secrets-manager.md)),
+  builds an `X509Credential`, then calls `decryptMultiAssertion($credentials, ...)`. An assertion
+  encrypted to ANY listed cert decrypts.
+- **Fails closed with coded responses:** `Invalid SAMLResponse (Code = 5)` if no usable
+  credential can be built at all; `Code = 6` if credentials build but every decrypt fails. Each
+  per-secret build is wrapped in try/catch — a bad/unreadable secret is skipped and logged, so
+  one broken secret does not 500 every login.
+- **Passphrase-aware, format-tolerant key loading:** PEM stored with escaped `\n` / `\r\n` is
+  normalized to real newlines before loading. The secret's `passphrase` is passed to
+  `KeyHelper::createPrivateKey` **only** when the private-key PEM header is the
+  `ENCRYPTED PRIVATE KEY` variant (ACM public-cert exports are always encrypted); a
+  plaintext key loads with no passphrase. A large "how this works" comment sits above
+  `ENCRYPTION_SECRET_NAMES` in the controller.
+- **To add or retire a cert: edit `ENCRYPTION_SECRET_NAMES` only** (and add/update the secret in
+  Secrets Manager) — no file swap on disk, no `_underscore` cert-file change. This replaces the
+  old "swap the `.crt`/`.key` files + redeploy" step for the encryption credential.
+- **Dead constants removed** from `saml/Controller/Index.php`:
+  `PATH_TO_ENCRYPTION_PRIVATE_KEY_NEW`, `PATH_TO_ENCRYPTION_PRIVATE_KEY_OLD`,
+  `PATH_TO_ENCRYPTION_CERTIFICATE_OLD`. `PATH_TO_ENCRYPTION_CERTIFICATE_NEW` **stays** — `/meta`
+  still reads it from disk to publish the encryption `KeyDescriptor`.
+- **The `saml-production` EB instance role needed a Secrets Manager grant** — see the SAML
+  architecture Deployment notes.
+
+### Secret names in `ENCRYPTION_SECRET_NAMES` (WHERE only — never the values)
+
+AWS Secrets Manager, account **654654170868**, region **us-east-1**. Each secret is JSON with
+keys `certificate`, `privateKey` (plaintext OR encrypted), `certificateChain` (optional),
+`passphrase` (optional; present only for an encrypted key):
+
+- `toga/ssl/togahub_com-selfsigned-2036` — the self-signed 10-year cert; kept for clients OK
+  with self-signed.
+- `toga/ssl/togahub_com-casigned-2027-03-31` — publicly-trusted (ACM exportable) cert.
+- `toga/ssl/togahub_com-casigned-2026-09-16` — publicly-trusted (ACM exportable) cert.
+
+### Why a public cert was added (Prudential)
+
+Prudential's IdP **refuses a self-signed cert, pins our exact leaf, and cannot auto-refresh our
+metadata by URL** — that combination forces a publicly-trusted cert. The correct source is an
+**ACM exportable public cert** (gives cert + private key), not ACM Private CA. Prudential moves
+to the public cert while other IdPs stay on the self-signed one; all coexist in the `/acs`
+multi-cert array. For the full trust-model rationale see the
+[SSL certificate trust-model strategy](../../standards/ssl-certificate-trust-model.md).
 
 ## Current credential (as of 2026-08-27, staged — cutover pending)
 
@@ -149,6 +205,16 @@ every pinning partner to reinstall on each renewal. The dedicated self-signed 10
 **decouples the SP credential from TLS renewals** — that is the whole point of the change.
 
 ## Change history
+- 2026-09-15 — `/acs` now sources SP encryption certs from **AWS Secrets Manager** (via
+  `_Cloud::getSecret`), not disk: two new constants `ENCRYPTION_SECRET_NAMES` (ordered secret
+  NAMES) + `ENCRYPTION_SECRET_REGION`, N-cert `decryptMultiAssertion`, fails closed with
+  `Code = 5`/`Code = 6`, per-secret try/catch, and passphrase-aware/format-tolerant key loading
+  (passphrase only for `ENCRYPTED PRIVATE KEY`). To add/retire a cert, edit the list only.
+  Removed dead disk-path constants (`PATH_TO_ENCRYPTION_PRIVATE_KEY_NEW/_OLD`,
+  `PATH_TO_ENCRYPTION_CERTIFICATE_OLD`); `PATH_TO_ENCRYPTION_CERTIFICATE_NEW` stays for `/meta`.
+  Added a publicly-trusted (ACM exportable) cert for Prudential, which refuses self-signed + pins
+  our leaf + cannot auto-pull metadata; self-signed and public certs now coexist in the array.
+  (jcardinal)
 - 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

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

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-27
+updated: 2026-09-15
 owners: [jcardinal]
 files: []
 related:
@@ -24,6 +24,8 @@ infra). It was established while replacing the 2.0 SAML SP credential — see th
 **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.
+**Exception:** a bilateral partner that **refuses a self-signed cert AND cannot auto-refresh
+metadata** gets an **ACM *exportable* public cert** (see case 1's carve-out) — not ACM Private CA.
 
 ## The decision
 
@@ -33,6 +35,13 @@ Family), PunchOut endpoints a buyer pins. Use a **self-signed** cert with a mult
 (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.
 
+**Carve-out — a partner that refuses self-signed AND can't auto-refresh metadata.** Some IdPs
+reject a self-signed SP cert but also won't re-pull our metadata on a schedule, so a short public
+cert would silently break them at every renewal. For these, use an **ACM *exportable* public
+cert** (publicly-trusted so they accept it; exportable so we can install cert+key into the SP).
+Do **not** reach for ACM Private CA (~$400/mo) to solve this — the exportable public cert covers
+it. You still redeploy on each ~198-day renewal (case 3's tradeoff), but the partner is happy.
+
 ### 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;
@@ -40,15 +49,28 @@ 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
+public cert** (a real 2025 AWS feature) — but only ~198-day validity today, so you must redeploy on
 every renewal — OR move the endpoint behind an ALB to get free auto-renew (option 2).
 
+### Hybrid end-state (bilateral endpoints with mixed partners)
+A single bilateral endpoint can end up serving **both** kinds of partner at once: some accept and
+pin our self-signed long-lived cert (case 1), others refuse self-signed and need an exportable
+public cert (the case-1 carve-out). These coexist. The SAML SP `/acs` handler already supports
+this: it holds **multiple** SP encryption cert+key pairs (`ENCRYPTION_SECRET_NAMES` in AWS Secrets
+Manager) and tries each on decrypt, so a self-signed keeper and a public-cert refuser can be live
+side by side — you add/rotate one partner's cert without disturbing the other. See the
+[saml architecture](../apps/saml/architecture.md) `/acs` flow.
+
 ## 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).
+**Every publicly-trusted cert, exportable or not, is short-lived and shrinking** under the
+CA/Browser Forum schedule: ~198 days today (what ACM issues now), stepping down to a **mandatory
+~47-day floor by 2029**. The often-quoted "10 days" is not the cert lifetime — it is the
+**domain-validation reuse window** (how long a prior validation can be reused before you must
+re-validate); the ~6-day Let's Encrypt cert is an **optional** short-lived offering, not the CA/B
+requirement. 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.

package/knowledge/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 83 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 84 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 69 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 26 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 19 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/prudential/profile.md

@@ -11,11 +11,12 @@ apps:
   - library
   - toga2-commerce
   - toga25-supply
+  - saml
 project: _Underscore
 client: prudential
 type: profile
 status: active
-updated: 2026-09-11
+updated: 2026-09-15
 owners: ["jcardinal", "rgirish", "bala", "mhammontree"]
 files: []
 related:

package/package.json

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