toga-ai 1.0.672 → 1.0.673

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

@@ -6,7 +6,7 @@ project: SAML SSO Gateway
 client: shared
 type: architecture
 status: active
-updated: 2026-06-11
+updated: 2026-08-27
 owners: ["rgirish", "jcardinal"]
 files:
   - saml/index.php
@@ -71,6 +71,14 @@ 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`.
+- **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;
+  **skips `production`** (so `saml-production` is unaffected) and always `exit 0`. Requires
+  `aws/aws-sdk-php` (now in `composer.json`, lock/vendor to be regenerated) and two IAM actions on
+  the instance profile (`elasticloadbalancing:DescribeTargetGroups` region-scoped +
+  `RegisterTargets` scoped to the non-prod target-group ARN). See
+  [ALB target-group auto-registration](../worker2/features/alb-target-group-auto-registration.md).
 
 ## Dependencies
 
@@ -88,3 +96,4 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 ## Change history
 - 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)

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Worker (worker2) Architecture](architecture.md) | Worker (repo `worker2`) is an AWS Elastic Beanstalk **Worker Tier** application that processes background jobs. | worker2/Controller/Index.php, worker2/Worker/, worker2/LambdaFunctions/, _underscore/Worker.php, worker2/composer.json |
-| [Deploy-Time Auto-Registration to the Shared ALB Target Group (non-production)](features/alb-target-group-auto-registration.md) | TOGA does **not** pay for EB-managed load-balancer registration, so an EB instance is normally **not** added to its environment's ALB target group — a fresh or | worker2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, worker2/ebs/register_instance_to_shared_application_load_balancer.php, worker2/.platform/hooks/prebuild/_shared/040-write-instance-id.sh, worker2/.platform/hooks/prebuild/_shared/041-write-region.sh, worker2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh, api2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh, worker2/.platform/hooks/postdeploy/015_install_composer.sh, api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |
+| [Deploy-Time Auto-Registration to the Shared ALB Target Group (non-production)](features/alb-target-group-auto-registration.md) | TOGA does **not** pay for EB-managed load-balancer registration, so an EB instance is normally **not** added to its environment's ALB target group — a fresh or | worker2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, worker2/ebs/register_instance_to_shared_application_load_balancer.php, worker2/.platform/hooks/_shared/040-write-instance-id.sh, worker2/.platform/hooks/_shared/041-write-region.sh, worker2/.platform/hooks/_shared/042-write-eb-environment.sh, worker2/.platform/hooks/postdeploy/015_install_composer.sh, saml/.platform/hooks/_shared/040-write-instance-id.sh, saml/.platform/hooks/_shared/041-write-region.sh, saml/.platform/hooks/_shared/042-write-eb-environment.sh, saml/.platform/hooks/prestart/040-write-instance-id.sh, saml/.platform/hooks/prestart/041-write-region.sh, saml/.platform/hooks/postdeploy/040-write-instance-id.sh, saml/.platform/hooks/postdeploy/041-write-region.sh, saml/.platform/hooks/postdeploy/042-write-eb-environment.sh, saml/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, saml/ebs/register_instance_to_shared_application_load_balancer.php, saml/composer.json, api2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh, api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |
 | [All-Client Email Queue Monitor (Monitor/Operations/EmailQueue)](features/all-client-email-queue-monitor.md) | `_Worker_Monitor_Operations::EmailQueue()` is the cross-client health check for the 2.0 outbound email queue (`Logs_<Client>.Email` — see [2.0 Email Send Pipeli | worker2/Worker/Monitor/Operations.php, _underscore/Database.php, _underscore/Query.php, dbchanges2/Logs_Client/2026-05-21 - Email.sql |
 | [Automated PR Merger — Concurrent Force-Push Clobber Race](features/automated-pr-merger-force-push-race.md) | The automated PR merger `_Worker_Team_GitHub::Merge` (`worker2` `Worker/Team/Github.php`) merges approved PRs to `_production` by **force-pushing from a clone t | Worker/Team/Github.php |
 | [Callback Scheduling ("call me back") — worker2 AI-BDR](features/callback-scheduling.md) | The **AI-BDR callback path**: what happens between a prospect saying *"call me back later"* on a Vapi call and the dialer actually placing that second call. | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php, worker2/Controller/Index.php |

package/knowledge/2.0/apps/worker2/features/alb-target-group-auto-registration.md

@@ -6,20 +6,32 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
+updated: 2026-08-27
 owners: [jcardinal]
 files:
   - worker2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh
   - worker2/ebs/register_instance_to_shared_application_load_balancer.php
-  - worker2/.platform/hooks/prebuild/_shared/040-write-instance-id.sh
-  - worker2/.platform/hooks/prebuild/_shared/041-write-region.sh
-  - worker2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh
-  - api2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh
+  - worker2/.platform/hooks/_shared/040-write-instance-id.sh
+  - worker2/.platform/hooks/_shared/041-write-region.sh
+  - worker2/.platform/hooks/_shared/042-write-eb-environment.sh
   - worker2/.platform/hooks/postdeploy/015_install_composer.sh
+  - saml/.platform/hooks/_shared/040-write-instance-id.sh
+  - saml/.platform/hooks/_shared/041-write-region.sh
+  - saml/.platform/hooks/_shared/042-write-eb-environment.sh
+  - saml/.platform/hooks/prestart/040-write-instance-id.sh
+  - saml/.platform/hooks/prestart/041-write-region.sh
+  - saml/.platform/hooks/postdeploy/040-write-instance-id.sh
+  - saml/.platform/hooks/postdeploy/041-write-region.sh
+  - saml/.platform/hooks/postdeploy/042-write-eb-environment.sh
+  - saml/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh
+  - saml/ebs/register_instance_to_shared_application_load_balancer.php
+  - saml/composer.json
+  - api2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh
   - api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh
   - api2/ebs/register_instance_to_shared_application_load_balancer.php
 related:
   - ../architecture.md
+  - ../../saml/architecture.md
   - ../../api2/workflows/codepipeline-codeconnections-deploy.md
   - ../../api2/architecture.md
 ---
@@ -34,8 +46,10 @@ pair automates that step for **non-production** environments: on every deploy th
 registers **itself** into the target group whose **name exactly equals the EB environment name**.
 
 Originally built in `api2`; ported to `worker2` on 2026-07-28 with three security hardenings
-(instance-profile credentials, native-PHP IMDSv2, fail-closed token handling). **`worker2` is now
-the reference implementation — `api2`'s copy has known defects, see below.**
+(instance-profile credentials, native-PHP IMDSv2, fail-closed token handling), and to `saml`
+(SAML SSO Gateway) on 2026-08-27 as a byte-faithful copy of the hardened `worker2` variant.
+**`worker2` is now the reference implementation — port from it, not from `api2`, whose copy has
+known defects (see below).**
 
 Non-prod `worker2` environments need this because they are reached **over HTTP for manual job
 invocation**, not through SQS.
@@ -50,8 +64,8 @@ invocation**, not through SQS.
 2. **`ebs/register_instance_to_shared_application_load_balancer.php`**
    - Reads the instance id and region from
      `/var/app/current/storage/instance-id.txt` and `storage/region.txt` (written earlier by the
-     `_shared/040-write-instance-id.sh` / `041-write-region.sh` prebuild hooks), falling back to a
-     direct **IMDSv2** lookup.
+     `_shared/040-write-instance-id.sh` / `041-write-region.sh` hooks — see the layout note
+     below), falling back to a direct **IMDSv2** lookup.
    - Reads the EB environment name via `get-config container -k environment_name`.
    - Uses the AWS SDK (`aws/aws-sdk-php`) ELBv2 client to `DescribeTargetGroups` and selects the
      target group whose **`TargetGroupName` is an exact string match** for the environment name —
@@ -64,13 +78,23 @@ invocation**, not through SQS.
 
 | Hook | Provides |
 |---|---|
-| `prebuild/_shared/040-write-instance-id.sh` | `storage/instance-id.txt` |
-| `prebuild/_shared/041-write-region.sh` | `storage/region.txt` |
-| `prebuild/_shared/042-write-eb-environment.sh` | `storage/eb-environment.txt` |
+| `_shared/040-write-instance-id.sh` (run via a phase wrapper) | `storage/instance-id.txt` |
+| `_shared/041-write-region.sh` (run via a phase wrapper) | `storage/region.txt` |
+| `_shared/042-write-eb-environment.sh` (run via a phase wrapper) | `storage/eb-environment.txt` |
 | `postdeploy/015_install_composer.sh` | `vendor/` (the AWS SDK) |
 
 Renumber it below `015` and the SDK autoloader does not exist yet.
 
+### Real on-disk hook layout — `_shared` + thin phase wrappers (corrected 2026-08-27)
+
+The canonical `040`/`041`/`042` scripts live at **`.platform/hooks/_shared/0xx.sh`** — **not**
+under `prebuild/`, as earlier revisions of this doc stated. Each deploy phase that needs one
+carries a **thin wrapper** in its own hook dir (`.platform/hooks/prestart/0xx.sh`,
+`.platform/hooks/postdeploy/0xx.sh`) that just runs `bash ../_shared/0xx.sh`. In the `worker2`
+and `saml` trees, `040`/`041` have both a `prestart` and a `postdeploy` wrapper, while `042` has
+a `postdeploy` wrapper only (no `prestart` copy). When porting, copy the canonical `_shared`
+script **and** the phase wrappers the tier needs — the wrappers are what actually execute.
+
 ### `042-write-eb-environment.sh` — the EB environment name, cached to disk (2026-08-04)
 
 Added to the same `_shared` hook family (plus a postdeploy hook) in **both `api2` and `worker2`**,
@@ -95,6 +119,21 @@ an identical `015_install_composer.sh`; and the same `get-config environment -k
 convention already used by `.ebextensions/git.php`. Check these four before porting the pair to
 any other 2.0 tier.
 
+**`saml` port (2026-08-27) — the two prerequisites a bare tier is missing.** `saml` had *none*
+of the hook family (prebuild was `git.sh` only, postdeploy was `015_install_composer.sh` only,
+no `ebs/` dir), so the port copied the canonical `_shared/040/041/042` scripts, their phase
+wrappers, `060_…​.sh`, and the hardened `ebs/register_instance_to_shared_application_load_balancer.php`.
+The two prerequisites it did **not** already meet:
+
+- **`aws/aws-sdk-php` was absent** from `composer.json` — added `aws/aws-sdk-php: ^3.337`
+  (the SDK's ELBv2 client is what the script uses). **`composer.lock` + `vendor/` must be
+  regenerated** with `composer require aws/aws-sdk-php:^3.337` before deploy (a developer step;
+  not done in the porting session).
+- **Stale `config.platform.php` pin.** `saml` pinned `7.2.33`, but the EB box runs PHP 8.5 (AL2023
+  / platform 4.13.1) and `aws-sdk-php ^3.337` needs PHP ≥ 8.1, so the stale pin would block
+  dependency resolution. Corrected to `8.1.0`. **Check the platform pin on any tier before
+  porting** — a low pin silently blocks the SDK install.
+
 ## Credentials — instance profile only (decision, 2026-07-28)
 
 **Deploy-time AWS credentials come from the EC2 instance profile. Never from source, never from
@@ -141,6 +180,12 @@ implementation instead:
   group name first when a non-prod env is unreachable after a deploy.
 - **Exit 0 hides failures.** Registration problems will not show in deploy status — read
   `/var/log/eb-hooks.log` on the instance.
+- **`saml` does nothing until it has a non-prod env + matching target group.** The team KB lists
+  `saml`'s only environment as `saml-production`, which this hook **self-skips**. The `saml` port
+  registers a target only on a **non-prod** `saml` env, and only if (a) that env's EC2 instance
+  profile carries the two IAM actions below (Describe scoped by `aws:RequestedRegion`, Register
+  scoped to the **non-prod** target-group ARN — never `targetgroup/*/*`), and (b) a target group
+  exists named **exactly** the non-prod env name. Naming equality is the whole contract.
 - **The hook turns on reachability; it does not secure it.** The target group and listener already
   exist by convention, but because this hook is what actually puts non-prod instances behind the
   shared ALB, the **listener rules and security groups must restrict non-prod to internal/VPN
@@ -172,6 +217,13 @@ which lists the other hooks but not `060` — pending an elevated-doc update.
 
 ## Change history
 
+- 2026-08-27 — Ported the hardened `worker2` hook pair to **`saml`** (SAML SSO Gateway): copied
+  `_shared/040/041/042`, their prestart/postdeploy wrappers, `060_…​.sh`, and the instance-profile
+  `ebs/register_instance_to_shared_application_load_balancer.php`. Added `aws/aws-sdk-php: ^3.337`
+  to `saml/composer.json` and corrected its stale `config.platform.php` pin `7.2.33 → 8.1.0`
+  (lock/vendor still to be regenerated by a developer). Also **corrected this doc's file paths**:
+  the canonical `040/041/042` scripts live at `.platform/hooks/_shared/`, not `prebuild/_shared/`,
+  and run via thin per-phase wrappers. (jcardinal)
 - 2026-08-04 — Added `_shared/042-write-eb-environment.sh` (+ a postdeploy hook) to **api2 and
   worker2**, caching the EB environment name to disk from `get-config` → `$EB_ENVIRONMENT_NAME` →
   the IMDS tag. Read from a file rather than shelled out to at use time because its first consumer

package/package.json

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