toga-ai 1.0.807 → 1.0.809

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-08
+updated: 2026-09-14
 owners: ["jcardinal", "mhammontree", "tcox", "bala", "apeterson", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -46,6 +46,14 @@ AclRecordPermissions   →  AclLogicGroups   →  AclLogicGroupExpressions  →
    `sqlExpression` (TEXT). Unique on `(recordId, slug)`. The conventional "always allow" row is
    `slug = 'all'`, `sqlExpression = '1'`.
 
+> **A half-built chain fails with a NAMED message — search for it before guessing.** `V2.php`
+> tracks two flags as it walks a permission, `$aclLogicGroupsDefined` and
+> `$aclLogicGroupExpressionsDefined` (set ~L3930 and ~L5614). When the first is false the request is
+> rejected with the exact message **`No ACL Logic Groups defined for ACL Record Permissions`**
+> (~L4437 / ~L5845); a missing expression binding fails on the second flag the same way. So an
+> `AclRecordPermissions` row with no `AclLogicGroups` row returns UNAUTHORIZED carrying that string
+> — which means the **chain**, not the grant, is the problem.
+
 **Field visibility — `AclFieldPermissions`.** Record-level access alone does **not** expose
 fields. Each field needs a row: `recordFieldId`, `roleId`, `isWritable` (0 = read-only, 1 =
 writable). Without it the field is rejected on write **and** is unreadable:
@@ -314,6 +322,13 @@ Measured 2026-09-08: production `Core.Records` holds **328 rows, max id 358**; d
 > divergence recorded as an open question in the
 > [non-prod drift doc](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md), and it is why
 > the hardcoded-literal rule above is scoped to **established** rows only.)
+>
+> **One client/pair can match completely, and that still is not portability.** Checked 2026-09-10
+> for Compass: `Core.Records` ids, every `Core.RecordFields` id for the nine records in an ACL grant
+> script, plus `Client_Compass.AclRecordExpressions` and `CustomRecordFields` ids, were **identical
+> between production and client-sandbox**, so the prod-written script ran unchanged on
+> client-sandbox. Treat that as a **per-client, per-environment-pair** measurement you re-take each
+> time — never as licence to skip resolving ids to names.
 
 **3. In PRODUCTION you cannot join `Core` and `Client_<Tenant>` in one statement — so the diff query
 that works in sandbox breaks in prod.** Prod splits them across `prod-core` and `prod-client`; both
@@ -686,6 +701,31 @@ consequence, and the reason the "mirror a sibling field" practice works: **grant
 `Base` also grants it to the worker.** Conversely, when auditing what an end customer can reach,
 remember the reverse — a grant added "for the worker" on `Base` reaches customers too.
 
+### ⚠ That union is `Apis_Roles` and NOTHING else — and `appId` does not scope an API key
+
+Two facts verified in `api2/Component/Api/V2/V2.php` on 2026-09-10, both of which decide how you
+scope a machine consumer:
+
+1. **Roles are ASSIGNED, not merged (~L1639).** On API-key auth, `_Model_Client_Apis_Role` is
+   searched for the `apiId` and the result is assigned straight to `$id->client->roles` — the
+   `array_merge($id->client->roles, $clientRoles)` line immediately above it is **commented out**.
+   Core roles are then derived from those client roles' non-NULL `coreRoleId` values, so a new role
+   with `coreRoleId` NULL is perfectly fine for records whose `Core.Records.aclDatabase` is
+   `CLIENT`. A key's power is exactly its `Apis_Roles` rows.
+2. **`appId` scoping is void for an API key (~L1518 / L1961 / L3201).** `$this->app` is only set
+   when the JWT carries an app uuid, i.e. the domain/user login flow. API-key auth never sets it,
+   and every permission filter starts `(!isset($this->app) || is_null($perm->appId) || …)` — so
+   **every `appId`-scoped `AclRecordPermissions` row applies to an API key**. A grant deliberately
+   narrowed to one app (e.g. `appId = 5`, TOGa Commerce) is fully reachable by any key holding that
+   role.
+
+> **Consequence: the only way to limit a machine consumer is to give it its OWN role.** Wiring
+> several `Apis` rows to the same shared roles means the key identifies the caller but constrains
+> nothing. Worked example (first per-key role, Compass 2026-09-10):
+> [Giving a Compass API consumer its own scoped key](../../../../clients/compass-usa/workflows/granting-api-access.md),
+> and the auth/token mechanics in
+> [API-Key Authentication](../../api2/features/api-key-authentication-and-scoping.md).
+
 ## Client-DB grant migrations are re-runnable NO-OPs, and that is the design
 
 A `NOT EXISTS`-guarded `AclFieldPermissions` insert that finds its grants already present inserts
@@ -715,6 +755,16 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- 2026-09-14 — Added the **API-key scoping** rules, from building the first per-key Compass API role.
+  Three durable points, all verified in `V2.php`: a half-built chain fails with the exact message
+  **`No ACL Logic Groups defined for ACL Record Permissions`** (flags `$aclLogicGroupsDefined` /
+  `$aclLogicGroupExpressionsDefined`, ~L3930/L4437/L5614/L5845); an API key's roles are **assigned**
+  from `Apis_Roles` and merge with nothing (~L1639, the `array_merge` is commented out), with core
+  roles derived from `coreRoleId`; and **`appId` does not scope an API key** because `$this->app` is
+  only set on the domain/user login flow (~L1518/L1961), so every `appId`-scoped grant applies — the
+  only real lever is a dedicated role per key. Also recorded that Compass's `Core.Records` /
+  `RecordFields` / `AclRecordExpressions` / `CustomRecordFields` ids matched prod and client-sandbox
+  exactly, as a per-client measurement and not portability. No code changed. (bala)
 - 2026-09-08 — Added the **cross-environment ACL comparison** rules, from a read-only Adyen
   "works in sandbox, not in prod" investigation. Three durable points: **pin the environment from
   the JWT first** (a shared API domain resolves its tenant from the token, so `api.beta.togahub.com`

package/knowledge/2.0/apps/_underscore/features/cloud-s3-helpers.md

@@ -13,6 +13,7 @@ files:
 related:
   - ../../worker2/features/oneuptime-worker2-monitoring.md
   - ../../worker2/features/compass-vip-support-importer.md
+  - ../../worker2/features/s3-folder-retention-cleanup.md
 ---
 
 ## Summary

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

@@ -3,6 +3,7 @@
 | Doc | Summary |
 |-----|---------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. |
+| [API-Key Authentication (/v2/auth/api) and what a key can actually reach](features/api-key-authentication-and-scoping.md) | A machine caller authenticates with `POST /v2/auth/api` using a `Client_<Client>.Apis` row and gets a bearer token. |
 | [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli |
 | [cXML ShipNotice Gateway (ASN ingestion, carrier resolution, per-client provisioning)](features/cxml-shipnotice-gateway.md) | `_Component_Api_Cxml` accepts a supplier `ShipNoticeRequest` and translates it into a `POST /v2/advance-shipping-notices` on the V2 JSON engine. |

package/knowledge/2.0/apps/api2/features/api-key-authentication-and-scoping.md

@@ -0,0 +1,113 @@
+---
+title: API-Key Authentication (/v2/auth/api) and what a key can actually reach
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-09-14
+owners: ["bala"]
+files:
+  - api2/Component/Api/V2/V2.php
+related:
+  - ../architecture.md
+  - ./request-logging.md
+  - ../../_underscore/features/acl-permission-chain.md
+  - ../../../../clients/compass-usa/workflows/granting-api-access.md
+---
+
+## Summary
+
+A machine caller authenticates with `POST /v2/auth/api` using a `Client_<Client>.Apis` row and gets
+a bearer token. **The key's power is exactly the union of its `Apis_Roles` rows and nothing else.**
+Two consequences that surprise people: roles are **assigned, not merged**, so an API key never picks
+up any other role; and `appId` scoping on an ACL grant **does not constrain an API key at all**,
+because API-key auth never sets `$this->app`. If you want one consumer limited to a few reads, the
+only working lever is giving that key **its own role** (see
+[granting Compass API access](../../../../clients/compass-usa/workflows/granting-api-access.md) for
+a worked example).
+
+## The authentication call
+
+- **Route:** `POST {base}/auth/api`. The public caller base is `https://api.togahub.com/v2`.
+- **`transactionId` goes in the QUERY STRING**, not the body, and must be globally unique
+  (reuse → `EV-5`).
+- **Body is exactly three fields:**
+  - `client` — the `Core.Clients` uuid
+  - `api` — the `Client_<Client>.Apis` row uuid
+  - `secret` — that row's secret
+- **Response:** `data.tokens.access` and `data.tokens.refresh`, with
+  `expiresIn.access = 3600` (1 hour) and `expiresIn.refresh = 2592000` (30 days). Subsequent calls
+  carry `Authorization: Bearer <access>`.
+
+> **⚠ Do not copy the `authority` field into caller documentation.** The response envelope's
+> `authority` reports the **internal** server that handled the request (observed: `api1.togahub.com`,
+> `api-writer.togahub.com`). Callers must always use `https://api.togahub.com/v2`.
+
+### `maxAuthsPerHour` throttles authentication, not traffic
+
+`Apis.maxAuthsPerHour` (client keys are typically `255`) is enforced at ~L1131 of `V2.php` by
+counting `Logs_<Client>.Api` rows with `isAuthRequest = 1` in the last hour. Over the limit returns
+a message telling the caller to re-use tokens. Tell integrators to authenticate once, cache the
+access token for the hour, and use the refresh token — not to call `/auth/api` per request.
+
+## How an API key's authorization is decided
+
+At `V2.php` ~L1639, once the `Apis` row authenticates:
+
+1. `_Model_Client_Apis_Role` is searched for that `apiId`.
+2. Those `roleId`s are **assigned** to `$id->client->roles` — the `array_merge(...)` line directly
+   above it is **commented out**. So the key holds those roles and only those roles.
+3. Core roles are then derived by selecting `Client_<Client>.Roles.coreRoleId` for those client
+   roles, skipping NULLs.
+
+**A new client role with `coreRoleId` NULL is fine** for any record whose `Core.Records.aclDatabase`
+is `CLIENT`. Core roles only matter for records flagged `CORE` (the permission scan at ~L3159+).
+
+### ⚠ `appId` cannot scope an API key — every appId-scoped grant applies
+
+`$this->app` is only set when the JWT carries an app uuid (`V2.php` L1518 / L1961), which is the
+**domain/user login** flow. On API-key auth it is never set, and every permission filter reads:
+
+```php
+(!isset($this->app) || is_null($perm->appId) || $perm->appId == $this->app->id)
+```
+
+With `$this->app` unset the first clause short-circuits **true**, so **all** `appId`-scoped
+`AclRecordPermissions` rows for the key's roles apply. A grant that was deliberately narrowed to one
+app (e.g. `appId = 5`, TOGa Commerce) is fully available to any API key holding that role. Scope a
+machine consumer with a **dedicated role**, never with `appId`.
+
+### The grant chain still applies
+
+An `AclRecordPermissions` row on its own grants nothing — the request fails with
+`No ACL Logic Groups defined for ACL Record Permissions`. Full rules, tables and checklist:
+[ACL Permission Chain](../../_underscore/features/acl-permission-chain.md).
+
+## Auditing what a key actually did
+
+`Logs_<Client>.Api` carries `apiId`, `dtStamp`, `method`, `route`, `responseCode`, `queryString`,
+`requestPayload` and `responsePayload`. **Filter on `apiId`** to get one consumer's exact calls and
+responses — this is how you answer "what did this integrator really use". Note the client-vs-core
+log split (failed writes and pre-scope auth failures land in core `Logs`):
+[V2 Request Logging](./request-logging.md).
+
+## Gotchas
+
+- **Roles are replaced, not merged.** Auditing a key means reading `Apis_Roles` and nothing else.
+- **`appId` is not a security boundary for machine callers.** See above.
+- **A shared role across keys means the key identifies the caller but does not limit it.** If
+  several `Apis` rows point at the same roles, every one of them can do everything those roles
+  allow, regardless of what the integration's published documentation says.
+- **Never record a secret value in a doc or a committed SQL file.** Document only where it lives
+  (the `Client_<Client>.Apis` row) and hand it over out of band.
+
+## Change history
+- 2026-09-14 — Created from the Compass Refresh-team API build. Recorded the `/auth/api` call shape
+  (`transactionId` in the query string; body `{client, api, secret}`), the 1 hour / 30 day token
+  lifetimes, the `maxAuthsPerHour` auth-only throttle, and two authorization facts verified in
+  `V2.php`: API-key roles are **assigned** from `Apis_Roles` (the `array_merge` is commented out,
+  ~L1639), and `$this->app` is never set for key auth so **every `appId`-scoped ACL row applies**.
+  Also noted the `authority` response field exposes the internal host and must not be published to
+  callers. (bala)

package/knowledge/2.0/apps/api2/features/request-logging.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-10
+updated: 2026-09-14
 owners: ["mhammontree", "dfranks", "bala", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -15,6 +15,7 @@ files:
   - _underscore/Model/Core/Logs/Api.php
 related:
   - ../architecture.md
+  - ./api-key-authentication-and-scoping.md
   - ./api-payload-interceptors.md
   - ./v2-api-error-codes.md
   - ./v2-deadlock-retry.md
@@ -362,6 +363,16 @@ fact AIG **does** post live entitlements — the writes were **failing (HTTP 500
 core `Logs`**, not `Logs_Aig`. See
 [AIG entitlement intake → Intake is a live API feed](../../../../clients/aig/features/entitlement-intake.md).
 
+### Auditing ONE API consumer — filter `Logs_<Client>.Api` on `apiId`
+
+`Logs_<Client>.Api` carries `apiId` alongside `dtStamp`, `method`, `route`, `responseCode`,
+`queryString`, `requestPayload` and `responsePayload`. Filtering on a single `apiId` is how you
+answer "what did this integrator actually call, and what did it get back" — it was used to verify
+the new Compass Refresh key's routes and to lift real sample responses for its reference document.
+`isAuthRequest = 1` rows are that key's `/auth/api` calls, and are what `Apis.maxAuthsPerHour`
+counts. The blind spots above still apply — the key's **failed writes land in core `Logs`**. See
+[API-Key Authentication](./api-key-authentication-and-scoping.md).
+
 ## Querying prod `Logs.Api` without timing out (narrow first, fetch payloads last)
 
 Prod `Logs.Api` is large enough that **any `LIKE` over `requestPayload` / `responsePayload`
@@ -426,6 +437,11 @@ re-send.
 > replay operationally, not by pasting payloads into the KB.
 
 ## Change history
+- 2026-09-14 — Added the per-consumer audit note: filter `Logs_<Client>.Api` on **`apiId`** to get
+  one API key's exact routes, payloads and response codes (`isAuthRequest = 1` rows are its
+  `/auth/api` calls, the ones `Apis.maxAuthsPerHour` counts). Used to verify the new Compass Refresh
+  key. Cross-linked the new
+  [API-Key Authentication](./api-key-authentication-and-scoping.md) doc. (bala)
 - 2026-09-10 — Sharpened the client-vs-core routing on the auth codes: a **401 always lands in the
   base `Logs`** (decided in the auth chain ~L2088 before routing, client unresolved) while a **403
   lands in `Logs_<Client>`** (client already known) — verified on Prudential 31 Aug–1 Sep, where

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

@@ -46,6 +46,7 @@
 | [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- |
 | [QA/QC Branch Automation (auto-mirror + rebuild-from-ledger revert)](features/qa-qc-branch-automation.md) | Two CTO-approved (AGREE) pieces of GitHub branch automation, centralized in **worker2** rather than per-repo GitHub Actions. |
 | [QA/QC Review Pipeline (ClickUp review chain, QC batch + defect/client-review)](features/qa-qc-review-pipeline.md) | The ClickUp-driven review + promotion chain for the platform-wide QA/QC dev process (per the approved `QA-QC Plan.txt`), moving a task through **Development → Q |
+| [S3 folder retention cleanup worker action (CleanS3Folder)](features/s3-folder-retention-cleanup.md) | `_Worker_Infrastructure_Aws_Cleanup::CleanS3Folder` (action path `Infrastructure/Aws/Cleanup/CleanS3Folder`) deletes S3 objects under **one folder** (key prefix |
 | [Service Request → Sales Order → Purchase Order generation (Sync/ServiceRequest)](features/service-request-sales-order-generation.md) | `_Worker_Sync_ServiceRequest` turns a **Service Request into a Sales Order, and then into one Purchase Order per vendor**, for **any** tenant. |
 | [SSO Stability Monitor (Monitor/Operations/SsoStability)](features/sso-stability-monitor.md) | `_Worker_Monitor_Operations::SsoStability(): string` is the **reporter half** of the SAML uptime monitor. |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. |

package/knowledge/2.0/apps/worker2/features/cross-account-aws-access.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-24
+updated: 2026-09-14
 owners: [jcardinal, bala]
 files:
   - worker2/Component/Aws/Workloads/Workloads.php
@@ -171,8 +171,40 @@ that account is the
 `agilant-worker-alpha` and `agilant-worker-beta` as **separate EB environments that have no role
 registry at all**. An account-level EC2 scan would sweep them in and misreport them.
 
+### `agilant-as2` is in the LEGACY account 502614707982 — S3 work on it is cross-account
+
+The `agilant-as2` bucket (the Office Depot AS2/EDI drop bucket, `us-west-2`) is **not** in the
+868 production hub where worker2 runs. Verified via `aws s3api list-buckets` per profile: only
+account **502614707982** lists it. So any S3 work on `agilant-as2` is **cross-account**.
+
+**The fix (same model as this component):** pass the bucket's **owner** account id as
+`awsAccountId` so the worker assumes `WorkloadsRuntime` **in that account** and touches the
+bucket **same-account**. Then an identity policy on the owner account's `WorkloadsRuntime`
+role is enough — **no bucket policy is needed**. Every `WorkloadsRuntime` trusts the 868
+instance role, so assuming into 502 from 654 works.
+
+**Diagnostic tell — the AccessDenied wording tells you the account.** The SDK error
+`AccessDenied ... is not authorized to perform: s3:ListBucket ... because no resource-based
+policy allows the s3:ListBucket action` is AWS's **cross-account** signal. A same-account
+identity-policy gap instead says *"no identity-based policy"*. Seeing **"no resource-based
+policy"** means the resource lives in another account — assume into the owner account.
+
+**IAM ARN gotcha (bucket-level vs object-level).** `s3:ListBucket` and
+`s3:GetBucketLocation` are **bucket-level** → the `Resource` must be the **bucket** ARN
+`arn:aws:s3:::agilant-as2` with **no** `/*`. `s3:DeleteObject` is **object-level** → the
+`Resource` must end in `/*` (scope it, e.g. `arn:aws:s3:::agilant-as2/OUTBOX/processed/*`).
+Putting `ListBucket` on the `/*` ARN is the classic mistake and returns exactly this
+AccessDenied.
+
+First S3 consumer of this pattern: the
+[S3 folder retention cleanup action](./s3-folder-retention-cleanup.md).
+
 ## Gotchas / known issues
 
+- **`agilant-as2` is cross-account (owner 502614707982), not in the 868 hub.** Assume into the
+  owner account; the `AccessDenied ... no resource-based policy` wording is the cross-account
+  tell, and `ListBucket`/`GetBucketLocation` need the bare bucket ARN while `DeleteObject`
+  needs the `/*` ARN. See [the section above](#agilant-as2-is-in-the-legacy-account-502614707982--s3-work-on-it-is-cross-account).
 - **Do not assume the 1.0 worker fleet is in the 868 production hub.** `AWS_WORKER_QUEUE_URL`
   (654654170868) is the SQS queue only; the instances are in the legacy account 502614707982,
   `us-west-2`. See [the section above](#which-account-the-10-worker-fleet-lives-in-easy-and-expensive-to-get-wrong).
@@ -191,6 +223,13 @@ registry at all**. An account-level EC2 scan would sweep them in and misreport t
   see [creating-worker-actions.md](./creating-worker-actions.md).
 
 ## Change history
+- 2026-09-14 — Recorded that **`agilant-as2` is owned by the legacy account 502614707982**
+  (`us-west-2`), not the 868 production hub — so S3 work on it is cross-account: pass the
+  owner account id as `awsAccountId` and no bucket policy is needed. Added the diagnostic tell
+  (`AccessDenied ... no resource-based policy` = cross-account; *no identity-based policy* =
+  same-account) and the IAM ARN gotcha (`ListBucket`/`GetBucketLocation` need the bare bucket
+  ARN, `DeleteObject` needs the `/*` ARN). Found while building the
+  [S3 folder retention cleanup action](./s3-folder-retention-cleanup.md). (jcardinal)
 - 2026-08-24 — Pinned down **which account the 1.0 `worker` fleet actually runs in**:
   **502614707982** (`us-west-2`, EB env `agilant-worker`), **not** the 654654170868 production hub
   that `App_Worker::AWS_WORKER_QUEUE_URL` implies — that account holds only the SQS queue the 1.0

package/knowledge/2.0/apps/worker2/features/s3-folder-retention-cleanup.md

@@ -0,0 +1,130 @@
+---
+title: S3 folder retention cleanup worker action (CleanS3Folder)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-09-14
+owners: [jcardinal]
+files:
+  - worker2/Worker/Infrastructure/Aws/Cleanup.php
+  - dbchanges2/Core/2026-09-14a - Insert S3 Folder Cleanup CronJob.sql
+related:
+  - ./creating-worker-actions.md
+  - ./cross-account-aws-access.md
+  - ../../_underscore/features/cloud-s3-helpers.md
+  - ./platform-cache-cleanup.md
+---
+
+## Summary
+
+`_Worker_Infrastructure_Aws_Cleanup::CleanS3Folder` (action path
+`Infrastructure/Aws/Cleanup/CleanS3Folder`) deletes S3 objects under **one folder** (key
+prefix) that are older than a retention window. **Both the folder and the days-to-keep are
+cron parameters**, so one action + one `Core.CronJobs` row cleans any folder with **no code
+change**. First use case: keep 30 days of `s3://agilant-as2/OUTBOX/processed/`.
+
+> This is the **S3** folder cleanup. It is separate from the DB "Cleanup cron" — see
+> [platform-cache-cleanup](./platform-cache-cleanup.md) for that one.
+
+## Key files / entry points
+
+- `worker2/Worker/Infrastructure/Aws/Cleanup.php` — `_Worker_Infrastructure_Aws_Cleanup::CleanS3Folder`.
+- `dbchanges2/Core/2026-09-14a - Insert S3 Folder Cleanup CronJob.sql` — the seed
+  `Core.CronJobs` row (seed rows live in dbchanges2, **never** a `.sql` in worker2).
+
+## How it works
+
+1. Parses an `s3://bucket/prefix/` URI into bucket + prefix.
+2. Assumes credentials via
+   `_Component_Aws_Workloads::assumeCredentials($awsAccountId)` and builds **one**
+   `Aws\S3\S3Client` reused for both list and delete. It uses **no static keys** and does
+   **not** use the `_Cloud` static-key helpers — this is a role-based cross-account path (see
+   [cross-account-aws-access](./cross-account-aws-access.md)).
+3. Paginates `listObjectsV2`; keeps only keys whose `LastModified` is older than
+   `now - daysToKeep`.
+4. Batch-deletes via `deleteObjects` (max 1000 keys per call).
+5. Returns a JSON summary on **every** path: `bucket`, `prefix`, `region`, `daysToKeep`,
+   `cutoffUtc`, `dryRun`, `scanned`, `eligible`, `deleted`, `failed`, `failedSample`,
+   `complete` — a proof-of-work return, per the
+   [creating-worker-actions](./creating-worker-actions.md) null-return rule.
+
+### Self-chunking — carry the S3 list position, not a page number
+
+A non-scheduler action is hard-capped at **300s** (the watchdog only honours
+`CronJobs.maxExecutionTime` for scheduler-fired jobs, and it does not stop the process — see
+[creating-worker-actions](./creating-worker-actions.md#-the-real-time-budget-is-300s--and-for-a-hand-triggered-action-it-cannot-be-raised)).
+The action works a ~240s slice, then re-enqueues itself with `_Worker::runTask(self::ACTION, …)`.
+
+The cursor it carries in the `resume` param is the **S3 `continuationToken`**, not a page
+counter:
+
+- **Why a keyset-style cursor is required:** S3 lists keys in **name order, not date order**.
+  A chunk can burn its whole 240s budget paging through recent keys before it reaches any old
+  object, and delete nothing that pass. Re-listing from page 1 each chunk (an earlier draft
+  did this) then **stalls the sweep forever with no alert** — every chunk re-scans the same
+  front of the list. Carrying the `continuationToken` guarantees the sweep advances through
+  the whole prefix.
+- **Backstop:** `MAX_CHUNK_ATTEMPTS = 100`.
+- **Single-attempt hand-off:** `runTask` mints a fresh uuid per call, so a *retried* hand-off
+  would fork the chain — do not retry it (same rule as
+  [creating-worker-actions](./creating-worker-actions.md#do-not-retry-the-chunk-hand-off--a-failed-hand-off-must-break-the-chain)).
+- **Normalize `resume` with a full round trip** — `json_encode` then `json_decode(true)` —
+  because the dispatcher casts only the top level of parameters, so a nested object arrives as
+  `stdClass`.
+
+### Destructive-delete safety guards (reviewed by CTO + cso)
+
+This deletes production S3, so the action refuses to run unless the target is provably safe:
+
+- Refuses a missing `s3://` scheme.
+- Refuses an **empty prefix** (never a whole-bucket sweep).
+- Forces the prefix to end in `/`.
+- Refuses a prefix shallower than `MIN_PREFIX_DEPTH = 2` folder levels — so a mistyped row
+  cannot hit a top-level or a live feed like `OfficeDepot/`.
+- `daysToKeep` must be `1..3650`.
+- Skips the folder-placeholder key.
+- Validates `awsAccountId` against a **3-account allowlist** (`654654170868` prod,
+  `502614707982` legacy, `975050298201` non-prod) **before** assume-role, because
+  WorkloadsRuntime reaches all three with broad permissions.
+- Logs each failed `deleteObjects` key — `Errors[]` returns HTTP 200 and does **not** throw on
+  per-key failure — and carries a capped `failedSample`.
+
+## Scheduling
+
+The seed `Core.CronJobs` row is
+`dbchanges2/Core/2026-09-14a - Insert S3 Folder Cleanup CronJob.sql`:
+
+- action `Infrastructure/Aws/Cleanup/CleanS3Folder`
+- schedule `0 2 * * *` (daily, Central), `maxExecutionTime` 300
+- parameters
+  `{"folder":"s3://agilant-as2/OUTBOX/processed/","daysToKeep":30,"awsAccountId":"502614707982","awsRegion":"us-west-2"}`
+- guarded `INSERT ... SELECT ... FROM DUAL WHERE NOT EXISTS`, fresh random v4 uuid.
+
+`awsAccountId` is the **legacy** account `502614707982` because `agilant-as2` lives there — see
+[cross-account-aws-access](./cross-account-aws-access.md). Ship the worker2 code deploy and
+this dbchanges2 migration **together**.
+
+## Client variations
+
+None — shared infrastructure, not client-specific.
+
+## Gotchas / known issues
+
+- **S3 lists by name, not date** — the whole reason the cursor must be a `continuationToken`
+  and not a page number (see self-chunking above).
+- `deleteObjects` returns HTTP 200 with per-key `Errors[]` — it does not throw on a partial
+  failure, so you must read `Errors[]` yourself.
+- `agilant-as2` is in **us-west-2** and is owned by a **different AWS account** — pass the
+  right `awsRegion` and `awsAccountId` (see related docs).
+
+## Change history
+- 2026-09-14 — Created. Added the generic `CleanS3Folder` action (folder + days-to-keep are
+  cron params, one row per folder, no code change), its self-chunking sweep carrying the S3
+  `continuationToken` (S3 lists by name not date, so a page-number cursor stalls the sweep),
+  and the destructive-delete guards (allowlist accounts, min prefix depth, prefix must end in
+  `/`, never whole-bucket). Seed cron row in dbchanges2 `Core/2026-09-14a`. (jcardinal)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -19,9 +19,9 @@ _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)
-- **worker2** (Worker) — 68 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 18 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/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)
 - **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) — 6 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)

package/knowledge/clients/compass-usa/INDEX.md

@@ -27,6 +27,7 @@
 | [Compass USA — reversing the 199-item catalog fold (MITS outage recovery)](workflows/catalog-fold-reversal.md) | 2.0 | The **root cause** of the Compass MITS transmission outage (the `assetType`-NULL and duplicate-vendor symptoms) was an ad-hoc cross-client **duplicate-items mer |
 | [Changing what is IN a Compass kit (adding / swapping a BundleItems line)](workflows/changing-a-kit-line-item.md) | 2.0 | "Add this fee/component to every kit that has X" is a recurring Compass request, and it looks like one `INSERT` into `Client_Compass.BundleItems`. |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe |
+| [Giving a Compass API consumer its own scoped key (one role per key)](workflows/granting-api-access.md) | 2.0 | "Give team X API access" on Compass used to mean handing out another key wired to the same two shared roles. |
 | [Granting a Compass user the same toga25-supply navigation as another user (role vs. SurfaceOverride)](workflows/granting-navigation-access.md) | 2.0 | "Give user X the same menu items user Y has" is the **navigation analog** of the recurring [bundle/persona grant](./granting-persona-bundle-access.md) request. |
 | [Granting a Compass user access to a bundle (persona grant) and the SuperUser role](workflows/granting-persona-bundle-access.md) | 2.0 | "Give user X sight of kit N" is a **recurring** Compass request, usually paired with "and make them a super user". |
 | [Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e |

package/knowledge/clients/compass-usa/profile.md

@@ -20,7 +20,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-09-04
+updated: 2026-09-14
 owners: [jcardinal, bala, tcox, apeterson, dfranks, akhokhani, ajean]
 files: []
 related:
@@ -32,6 +32,7 @@ related:
   - workflows/granting-persona-bundle-access.md
   - workflows/changing-a-kit-line-item.md
   - workflows/granting-navigation-access.md
+  - workflows/granting-api-access.md
   - features/mits-sales-order-transmission-alerting.md
   - features/oneuptime-ma-refresh-order-monitor.md
   - workflows/catalog-fold-reversal.md
@@ -206,6 +207,18 @@ separate, related client (see its own profile).
   the ⚠ rule that **deactivation is raw bulk SQL, so no model hook ever fires on it**.
 
 ## Notes
+- **⚠ Compass API keys: four of the five are NOT scoped (2026-09-10).** Agilant, MITS Service Hub,
+  Compass Group and Office Depot (Cxml) all share the same two roles — Base (1) and API (3) — so each
+  of them can create, update and delete across **291 records**, whatever its published integration
+  document says (MITS's lists 5 read lookups). `appId` cannot fix this: an API key never gets
+  `$this->app` set, so every appId-scoped grant applies to it. The **'Compass Refresh Team'** key
+  (prod `Apis.id 5`) is the first with its **own read-only role** ('Refresh API', prod roleId 17,
+  9 records / 0 writable) and is the template for the next consumer:
+  [Giving a Compass API consumer its own scoped key](workflows/granting-api-access.md).
+  **Open:** the generated secret is still in plain text inside
+  `dbchanges2/Client_Compass/2026-09-10 - RefreshTeamApiAccess.sql` (strip or rotate it), the
+  negative test was never run, the script was applied straight to prod, and the four older keys are
+  not migrated.
 - **Item modal "Restrict to Persona" needed a Surface opt-in that was never written (2026-09-04).**
   Core seeds the item modal's More-Info `restrictToPersona` field **OFF** for every client
   (surface 19 / element 57), expecting a per-client override — Compass USA had **none**, so the

package/knowledge/clients/compass-usa/workflows/granting-api-access.md

@@ -0,0 +1,142 @@
+---
+title: Giving a Compass API consumer its own scoped key (one role per key)
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: compass-usa
+type: workflow
+status: active
+updated: 2026-09-14
+owners: ["bala"]
+files:
+  - dbchanges2/Client_Compass/2026-09-10 - RefreshTeamApiAccess.sql
+related:
+  - ../profile.md
+  - ./granting-navigation-access.md
+  - ../../../2.0/apps/api2/features/api-key-authentication-and-scoping.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../2.0/apps/api2/features/request-logging.md
+---
+
+## Summary
+
+"Give team X API access" on Compass used to mean handing out another key wired to the same two
+shared roles. **Every pre-existing Compass key can read and write almost everything**, so the key
+identified the caller but did not limit it. The Refresh-team key (built 2026-09-10) is the first
+Compass key with **one dedicated, read-only role of its own**, and its migration
+`dbchanges2/Client_Compass/2026-09-10 - RefreshTeamApiAccess.sql` is the template for the next
+consumer: copy it and change the record list.
+
+Why a dedicated role is the only lever: an API key's roles come **only** from `Apis_Roles`, and
+`appId` scoping does not bind a key at all — see
+[API-Key Authentication](../../../2.0/apps/api2/features/api-key-authentication-and-scoping.md).
+
+## ⚠ The four older Compass keys are NOT scoped
+
+All four pre-existing `Client_Compass.Apis` rows — **Agilant**, **MITS Service Hub**,
+**Compass Group**, **Office Depot (Cxml)** — are wired in `Apis_Roles` to the **same two roles**:
+
+| Role | id | Record permissions | Writable |
+|---|---|---|---|
+| Base | 1 | 123 | 115 |
+| API | 3 | 291 | **all 291** |
+
+So MITS, whose published integration document lists **5 read lookups**, can in fact create, update
+and delete across 291 records. Nothing in the database constrains any of those four keys to its
+documented calls. Anyone auditing Compass API access needs to start from this fact. Migrating those
+four keys onto per-key roles (starting with MITS) is **intended but not done**.
+
+## The Refresh-team key (the worked example)
+
+Landed on **production** 2026-09-10:
+
+- `Client_Compass.Apis` row **'Compass Refresh Team'** (prod `id = 5`).
+- `Apis_Roles` binds it to exactly **one** new client role, **'Refresh API'** (prod `roleId = 17`).
+- Read-only: **9 records**, **83 field permissions**, **18 custom-field permissions**,
+  **0 writable anywhere**.
+- Records granted (`Core.Records.id`): **2** users, **11** locations, **37** contacts,
+  **38** contact-email-addresses, **39** contact-phone-numbers, **40** personas,
+  **201** user-personas, **273** user-roles, **274** roles.
+- Field grants were **cloned from the shared API role (roleId 3)** for those same records, minus the
+  two fields listed below.
+
+The consumer calls four requests: auth, cost center by number (`/locations`), user by email
+(`/users`), and user by Compass username (`/users`).
+
+## Steps
+
+1. Create the `Client_Compass.Roles` row for the consumer (one role, one key). `coreRoleId` may stay
+   NULL — every record here has `Core.Records.aclDatabase = 'CLIENT'`.
+2. Insert the `Client_Compass.Apis` row with a generated uuid and secret, then the single
+   `Apis_Roles` row binding it to that new role only.
+3. For each record the consumer needs, build the **whole** ACL chain — `AclRecordPermissions` +
+   `AclLogicGroups` + `AclLogicGroupExpressions` + `AclRecordExpressions`. A permission row alone
+   fails the request with `No ACL Logic Groups defined for ACL Record Permissions`
+   ([ACL Permission Chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)).
+4. Clone the field grants from role 3 for those records, with `isWritable = 0`, **dropping**:
+   - `Users.password` — `recordFieldId 611`
+   - `Users.ldapDn` — `recordFieldId 1329`
+5. Reuse `AclRecordExpressions.id = 4` on record 2 (Users). That expression is the row filter that
+   **hides every user whose email ends in `@togatech.com`**, so internal TOGa staff accounts never
+   appear in an API user lookup. Any new role reading Users should reuse it.
+6. Verify before handover (see below), then hand the uuid and secret to the consumer out of band.
+7. Produce the consumer's reference document (see below).
+
+### ⚠ Do not clone `AclLogicGroup id 20` wholesale
+
+Logic group **20** (role 3, Users) also links `AclRecordExpressions id 16` — but expression 16
+belongs to `recordId 22`, not 2. It is a **stray mis-linked row** in the shared role. It was
+deliberately **not** copied into the Refresh role. Read what an expression actually points at before
+mirroring it.
+
+## Verification
+
+- Counts: 9 records / 83 field permissions / 18 custom-field permissions / 0 writable — all passed
+  on prod.
+- `Apis_Roles` for the new `apiId` returns **exactly one** `roleId`.
+- Call each intended route with the new key, then read `Logs_Compass.Api` filtered on the new
+  `apiId` to confirm the exact routes and response payloads
+  ([V2 Request Logging](../../../2.0/apps/api2/features/request-logging.md)).
+
+## Environment note — Compass Core ids matched prod and client-sandbox
+
+Checked 2026-09-10 for this client: `Core.Records` ids, every `Core.RecordFields` id for records
+2/11/37/38/39/40/201/273/274, `Client_Compass.AclRecordExpressions` ids and
+`Client_Compass.CustomRecordFields` ids were **identical between production and client-sandbox**. So
+this ACL script, written against prod ids, runs unchanged on client-sandbox for Compass.
+
+> This contradicts the usual assumption that `RecordFields` ids are environment-specific. Treat it
+> as a **Compass prod to client-sandbox** observation, not a general rule — re-check per client and
+> per environment before reusing a script elsewhere. The general rule (resolve ids to names before
+> diffing environments) still stands.
+
+## The consumer-facing reference document
+
+Each API consumer gets a Word reference document, mirroring the existing MITS one. It is generated
+with `python-docx` using the MITS `.docx` as the style template, and covers the four requests, real
+sample responses lifted from `Logs_Compass.Api`, Postman links, token lifetimes, and a plain-English
+"what your key can access" section. **Credentials in the document are placeholders only.** The file
+lives outside the repos (the developer's local Downloads) — the binary is not stored in git or the
+knowledge base.
+
+## Open items (as of 2026-09-14)
+
+- **⚠ The generated secret is sitting in plain text inside
+  `dbchanges2/Client_Compass/2026-09-10 - RefreshTeamApiAccess.sql`, which is a git repo.** Strip it
+  before commit or rotate the secret. Never commit a secret value.
+- The **negative test has not been run** — calling a route outside the grant (e.g. `/items`) with the
+  Refresh key to confirm `UNAUTHORIZED`.
+- The script was run **directly on production**; the intended client-sandbox dry run was skipped.
+- Migrating the four older keys (Agilant, MITS Service Hub, Compass Group, Office Depot (Cxml)) off
+  the shared Base + API roles onto per-key roles is **not started**.
+
+## Change history
+- 2026-09-14 — Created. Built the first per-key Compass API role: `Apis` row 'Compass Refresh Team'
+  (prod id 5) bound to the single read-only role 'Refresh API' (prod roleId 17) over 9 records / 83
+  field grants / 18 custom-field grants, 0 writable, cloned from role 3 minus `Users.password` (611)
+  and `Users.ldapDn` (1329). Recorded that the four older Compass keys all share Base (1) + API (3)
+  and are therefore fully writable across 291 records; that `AclRecordExpressions id 4` is the
+  `@togatech.com` staff-hiding row filter to reuse; that logic group 20 links a stray expression
+  (id 16, wrong record) not to be cloned; and that Compass Core metadata ids matched prod and
+  client-sandbox. Open: secret still in the SQL file, negative test not run, prod-only run, older
+  keys not migrated. (bala)

package/package.json

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