toga-ai 1.0.821 → 1.0.823

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

@@ -61,4 +61,5 @@
 | [USPS DPV Deliverability Verdict (is this address actually insurable/shippable?)](features/usps-dpv-deliverability.md) | **USPS returning HTTP 200 with a populated address is NOT evidence that the address is deliverable.** The authoritative signal is USPS's **DPV (Delivery Point V |
 | [Refreshing a Local Dev Database from Beta (dev-sandbox)](workflows/local-db-refresh-from-beta.md) | How to reset a local 2.0 dev database from the **beta / dev-sandbox** environment: dump each schema (`Core`, `Client_<Id>`, `Logs_<Id>`, …) from the beta host, |
 | [Deleting a shared branch does not remove bad commits — a stale local clone merges them back](workflows/recreated-shared-branch-stale-local-remerge.md) | **Deleting and recreating a shared environment branch removes only the *ref*.** Every teammate who still has that branch checked out locally keeps the full pre- |
+| [Rotating Public TLS Certificates (ACM, CloudFront, ALB, Elastic Beanstalk)](workflows/rotating-public-tls-certificates.md) | How to replace the public TLS certificates that terminate HTTPS for TOGa front-end domains (togahub, togacommerce, togadesk, togaretail, togasupply, togaview, t |
 | [Running a 2.0 App Locally (browser, end-to-end via api2)](workflows/running-a-2.0-app-locally.md) | The full dependency chain required to run a 2.0 client app **through the browser**, end-to-end, against a **local `api2`** (e.g. |

package/knowledge/2.0/apps/_underscore/workflows/rotating-public-tls-certificates.md

@@ -0,0 +1,178 @@
+---
+title: Rotating Public TLS Certificates (ACM, CloudFront, ALB, Elastic Beanstalk)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: workflow
+status: active
+updated: 2026-09-16
+owners: ["rgirish"]
+files: []
+related:
+  - 2.0/standards/ssl-certificate-trust-model.md
+  - 2.0/apps/saml/workflows/rotating-the-saml-sp-certificate.md
+  - 1.0/apps/tools/features/cloudfront-client-setup.md
+---
+
+## Summary
+
+How to replace the public TLS certificates that terminate HTTPS for TOGa front-end domains
+(togahub, togacommerce, togadesk, togaretail, togasupply, togaview, togaiq) before they
+expire. This is the browser-facing TLS cert on CloudFront and ALBs — **not** the SAML SP
+credential (that is a pinned bilateral cert, see
+[Rotating the SAML SP Certificate](../../saml/workflows/rotating-the-saml-sp-certificate.md)).
+
+This runbook was written from the 2026-09-16 rotation in AWS account **654654170868**, where
+one IMPORTED multi-domain cert (14 SANs, copied into us-east-1, us-west-2 and eu-west-1) served
+4 CloudFront distributions and 12 ALB listeners and expired the same day.
+
+**The three things that bite you:**
+1. **Elastic Beanstalk keeps its own saved cert setting**, separate from the ALB listener. Fixing
+   the listener is not enough — the next deploy puts the old cert straight back.
+2. **CloudFront holds exactly ONE cert per distribution.** There is no staging. The swap *is* the
+   cutover, and it takes 5-15 minutes.
+3. **An ACM wildcard matches exactly one label.** `*.togasupply.com` covers
+   `elite.togasupply.com` but **not** `compass.beta.togasupply.com`.
+
+**Root cause to avoid repeating:** an **IMPORTED** ACM cert never auto-renews. Always replace with
+**Amazon-issued, DNS-validated** ACM certs, which renew themselves.
+
+## When to run this
+
+- A cert is nearing expiry (ACM emails, or your own audit finds it).
+- You are moving off an imported cert onto Amazon-issued certs.
+- Any time you suspect a cert is expired — run the audit in step 1 regardless; it is cheap.
+
+## Step 1 — Audit EVERYTHING, not just the cert you know about
+
+Do **not** just follow the expiring cert's `InUseBy` list. Enumerate **all** CloudFront
+distributions and **all** ALB listeners in **every** region, resolve each attached cert's
+`NotAfter`, and flag anything expiring before your cutoff.
+
+This is how the 2026-09-16 rotation found a **second** cert that had already expired six months
+earlier (2026-03-24) and was still the only cert on 2 ALB listeners and 2 CloudFront
+distributions — 4 live togadesk hosts had been serving cert errors since March and nobody noticed.
+
+Also audit **every Elastic Beanstalk environment's saved config**, including suspended ones. A
+suspended environment with no live listener can still hold a stale cert ARN that comes back when
+it is rebuilt.
+
+**Check each CloudFront distribution's origins before you plan work on it.** One distribution in
+this rotation had a real alias and live DNS but all 3 origins pointed at load balancers that no
+longer existed — a dead leftover. Do not spend change-window time on it.
+
+## Step 2 — Decide the cert shape: one cert per domain
+
+Replace a bundled multi-domain cert with **one cert per domain** (root + wildcard, e.g.
+`togahub.com` + `*.togahub.com`). Reasons:
+
+- A 14-SAN request exceeds ACM's default 10-domain quota.
+- One domain's problem no longer takes down all seven.
+- Each distribution only needs the domain it actually serves.
+
+All new certs must be **Amazon-issued and DNS-validated** so they auto-renew. This is case 2 of
+the [SSL Certificate Trust-Model Strategy](../../../standards/ssl-certificate-trust-model.md):
+AWS terminates the TLS, so use ACM public, non-exportable, auto-renewing.
+
+## Step 3 — Request the certs in the right regions
+
+Region rules:
+
+- **CloudFront only reads certs from `us-east-1`.** No exceptions.
+- **An ALB reads certs from its own region.** A togahub ALB in us-west-2 needs a us-west-2 cert;
+  the same domain on an eu-west-1 ALB needs a separate eu-west-1 cert.
+
+Check ACM first — unused per-domain certs may already exist (3 did in this rotation). Then request
+only what is missing.
+
+## Step 4 — Validate by DNS in Route 53
+
+Add the validation CNAMEs to Route 53. Certs for the **same domain in different regions share ONE
+validation record** — the CNAME name and value are identical, so 6 certs across 3 regions needed
+only 5 CNAMEs.
+
+Validation completes in about 2 minutes once the records are live. Wait for `ISSUED` before
+touching anything.
+
+## Step 5 — Stage the ALB listeners first (safe, additive)
+
+`aws elbv2 add-listener-certificates` is **purely additive**. A listener holds many certs and picks
+by SNI, so adding the new cert alongside the old one changes nothing for live traffic. Do this
+ahead of the change window for every listener.
+
+## Step 6 — THE ONE PEOPLE MISS: update the Elastic Beanstalk saved config
+
+Adding a cert to an ALB listener does **not** update the EB environment's saved setting
+`aws:elbv2:listener:443 / SSLCertificateArns`. After all 12 listeners were fixed and verified
+healthy in this rotation, 12 EB environments still named the **old** cert in their saved config.
+
+Nothing breaks right away — the listener serves traffic. But the next **deploy, restart, rebuild or
+scaling event** re-applies the saved config and puts the expired cert back. A listener-level audit
+does not catch this.
+
+```
+aws elasticbeanstalk update-environment \
+  --environment-name <env> \
+  --option-settings "Namespace=aws:elbv2:listener:443,OptionName=SSLCertificateArns,Value=<new-arn>"
+```
+
+Observed behaviour: this cleanly **replaced** the old cert on the listener (leaving only the new
+one), and every environment stayed Green/Ok through the update — no traffic disruption.
+
+**Gotcha:** an EB environment whose CloudFormation stack is in `DELETE_FAILED` cannot be updated at
+all — `update-environment` is refused. That needs separate stack cleanup.
+
+## Step 7 — Check alias coverage before any CloudFront swap
+
+CloudFront **rejects** an update if any alias on the distribution is not covered by the new cert.
+Check every alias against the new cert's SANs **programmatically** — this is where the one-label
+wildcard rule bites: `*.togasupply.com` does not cover `compass.beta.togasupply.com`. Beta and
+gamma environments generally need their own certs for this reason.
+
+## Step 8 — Swap CloudFront, smallest blast radius first
+
+`ViewerCertificate.ACMCertificateArn` is a **single string**, not a list. There is no
+"add new alongside old" for CloudFront: the swap is the cutover, and it deploys in 5-15 minutes.
+
+Order used, lowest risk first:
+
+1. Distributions that are **already broken** (nothing to lose).
+2. Single-alias distributions.
+3. Mid-size (9 aliases).
+4. The largest last (the 21-alias distribution fronting 21 named enterprise clients).
+
+Back up each distribution's config before every swap — `aws cloudfront get-distribution-config`,
+and keep the **ETag**; you need it to update.
+
+**Hard edge:** once the old cert's expiry moment has passed there is no useful CloudFront rollback,
+because rolling back restores an expired cert. Only forward.
+
+## Step 9 — Verify on the live hosts
+
+```
+echo | openssl s_client -servername HOST -connect HOST:443 2>/dev/null \
+  | openssl x509 -noout -issuer -enddate
+```
+
+Also run it **without** `-servername` to check the no-SNI / default-cert path — that path can still
+be serving the old cert after everything else looks fine.
+
+Finish by re-running the step 1 audit: every CloudFront distribution, every ALB listener, and every
+EB saved config should name a cert with a future `NotAfter`.
+
+## Gotchas
+
+- **IMPORTED certs never auto-renew.** If the audit shows `Type: IMPORTED`, it is a future outage.
+- **A cert copied into 3 regions is 3 separate certs** — all 3 expire at once, and all 3 need
+  replacing.
+- **EB saved config is the silent landmine.** See step 6.
+- **CloudFront takes one cert; ALBs take many.** Two completely different risk profiles in the same
+  rotation — plan them separately.
+- **Wildcards match one label only.** Verify alias coverage with code, not by eye.
+- **Expired certs hide.** Sweep the whole account; do not trust `InUseBy`.
+
+## Change history
+- 2026-09-16 — Created from the account 654654170868 rotation: replaced an expiring 14-SAN IMPORTED
+  cert with 6 per-domain Amazon-issued DNS-validated certs, relinked 12 ALB listeners, 6 CloudFront
+  distributions and 11 EB environment configs; documented the EB saved-config trap. (rgirish)

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

@@ -64,12 +64,21 @@ lands in `api()`.
 
 `api()` is the protocol router and the **transaction/logging boundary**:
 - **CORS (2026-09-16):** **reflects the caller's `Origin` header** back in
-  `Access-Control-Allow-Origin` (per-request echo) instead of a wide-open `*`, and sends
-  `Access-Control-Allow-Credentials: true`; still returns 200 for the `OPTIONS` preflight. A
-  wildcard `*` cannot be combined with credentialed requests, so echoing the Origin is what lets
-  a future cookie/session flow work without reopening the hole — but it is **not** an allowlist:
-  every Origin is still reflected. Tighten to a real allowlist before adding any cookie/session
-  auth here.
+  `Access-Control-Allow-Origin` when `$_SERVER['HTTP_ORIGIN']` is present and matches a strict
+  shape regex `^https?://[A-Za-z0-9.\-]+(:\d+)?$` (with the `D` end-anchor flag); otherwise it
+  falls back to `*`. It also emits `Vary: Origin`. This block sits **before** the `OPTIONS`
+  preflight short-circuit (still 200 for `OPTIONS`). The reflected value must be the **whole
+  origin — `scheme://host[:port]` (e.g. `http://compass.togacommerce`)** — because the browser
+  compares it byte-for-byte; do **not** strip the scheme or "clean" `HTTP_ORIGIN` (it is an
+  origin, not a URL with a path). Why: some higher-security client networks strip or reject a
+  wildcard `*`, so a client's app fails with a CORS "no Access-Control-Allow-Origin" error
+  **inside** their network while working fine outside it. **Security:** reflecting any
+  well-formed origin is effectively equivalent to `*` here because auth is **Bearer-token, never
+  cookies** — no new exposure; the regex is a strict allowlist that blocks header injection, and
+  PHP `header()` also rejects CR/LF. **`Access-Control-Allow-Credentials` is deliberately NOT set
+  — do NOT add it on top of this reflection without a cookie-auth security review; that
+  combination would be a cross-site data-theft hole.** `Vary: Origin` stops a shared cache
+  serving one origin's header to another.
 - **`/health`:** 200 + empty object (EB/LB probe — keep it working).
 - **Sentry:** initialized per request; EC2 instance metadata attached.
 - **Core DB bootstrap (now guarded, 2026-07-23):** registers `Core` (`DB_CORE`), preferring a
@@ -396,13 +405,15 @@ they are the known sharp edges. Do not re-discover these from scratch.
    `Core.Database` row (`id = CORE_LOGS_DATABASE_ID`); a local Logs DB whose actual schema name
    differs throws `Unknown database`. This is environment config, not a code bug — fix the row or
    the local schema name, don't patch the bootstrap.
-5. **CORS reflects the caller's `Origin` (not an allowlist) (updated 2026-09-16).** The front
-   controller now echoes the request `Origin` into `Access-Control-Allow-Origin` and sends
-   `Access-Control-Allow-Credentials: true` (was a wide-open `Access-Control-Allow-*`). This
-   retires the old "wide-open CORS" risk for the current bearer-token auth, but it is **still not
-   a restriction** — every Origin is reflected. If any cookie/session-backed auth is ever added
-   here, replace the Origin echo with a real hardcoded allowlist first; reflecting the Origin
-   while sending credentials would otherwise be an exploitable hole.
+5. **CORS reflects the caller's `Origin`, falling back to `*` (updated 2026-09-16).** The front
+   controller now echoes the request `Origin` into `Access-Control-Allow-Origin` when it matches a
+   strict shape regex, else falls back to `*`, and adds `Vary: Origin` (was a wide-open
+   `Access-Control-Allow-*`). Safe **only** because auth is Bearer-token, never cookie/session —
+   `Access-Control-Allow-Credentials` is intentionally **unset**, and reflecting the origin is
+   effectively equivalent to `*` here (no new exposure). It is a shape check, **not** a trusted-
+   origin allowlist — every well-formed Origin is reflected. If any cookie/session-backed auth is
+   ever added here, do not set credentials and re-tighten CORS to a real hardcoded allowlist first;
+   origin-reflection + credentials would be a cross-site data-theft hole.
 6. **`_underscore` is cloned at build from a moving branch** (`_<ENVIRONMENT>`), not pinned to a
    commit. Two deploys of the same api2 commit can produce different runtime behavior. Check the
    framework branch state when triaging an "it worked yesterday" regression.
@@ -457,13 +468,17 @@ they are the known sharp edges. Do not re-discover these from scratch.
 
 ## Change history
 - 2026-09-16 — **CORS now reflects the caller's `Origin`** instead of a wide-open
-  `Access-Control-Allow-*`: the front controller (`Controller/Index.php`) echoes the request
-  `Origin` into `Access-Control-Allow-Origin` and sends `Access-Control-Allow-Credentials: true`,
-  still returning 200 for the `OPTIONS` preflight. Updated the front-controller CORS bullet and
-  **retired the old "CORS is fully permissive" wide-open risk** (Known issue #5) — reframed to
-  note the header is now a per-request Origin echo, **not** an allowlist, so it must still be
-  replaced with a hardcoded allowlist before any cookie/session-backed auth is added here.
-  (jcardinal)
+  `Access-Control-Allow-*`: the front controller (`Controller/Index.php`, `_Controller_Index::api()`,
+  before the `OPTIONS` short-circuit) echoes the request `Origin` into `Access-Control-Allow-Origin`
+  when `HTTP_ORIGIN` matches `^https?://[A-Za-z0-9.\-]+(:\d+)?$` (`D` flag), else falls back to `*`,
+  and adds `Vary: Origin` (whole origin incl. scheme — browser compares byte-for-byte). Motivation:
+  some higher-security client networks strip/reject a wildcard `*`, so a client failed with a CORS
+  "no Access-Control-Allow-Origin" error inside their network while it worked outside. Retires Known
+  issue #5. `Access-Control-Allow-Credentials` deliberately **NOT** set (auth is Bearer-token, never
+  cookies — reflection is equivalent to `*` here with no new exposure; adding credentials on top
+  would be a cross-site data-theft hole and needs a cookie-auth review). Reviewed clean by
+  php-reviewer (valid PHP 8.2) and cso (SAFE TO SHIP). Note: the code change is a working-tree edit,
+  not yet committed. (jcardinal)
 - 2026-09-01 — Recorded a **sixth EB-`Degraded` cause — a client 4xx BURST**: EB Enhanced Health
   counts application/ELB 4xx toward env health via two default-Enabled `ConfigDocument` rules
   (`ApplicationRequests4xx`, `ELBRequests4xx`, namespace

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 85 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 86 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/package.json

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