toga-ai 1.0.854 → 1.0.855

package/package.json

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

package/skills/order-for/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: order-for
+description: Everything about the Compass "Order For" feature, where user A places an order on behalf of user B. Covers the Users_DelegatorUsers table, the permission gate in _Model_Client_User and V2.php, the originalUserId audit column, the delegation-list GET call in toga2-commerce, the delegated token switch through /auth/delegator, and the ACL rows for Compass and Compass Canada. Use this skill whenever the user asks about "order for", "order on behalf of", delegation, delegator users, Users_DelegatorUsers, originalUserId, c_orderSubmittedById, the Order For dropdown, or why a delegation is being refused. Load it before changing any of those files.
+---
+
+# Compass "Order For"
+
+User A places an order for user B. B must be on A's list. The list is
+`Client_<Tenant>.Users_DelegatorUsers`. The server is the gate, never the UI.
+
+Built and verified on local 2026-09-21 against Client_Compass. Ticket TRUE-81848.
+
+---
+
+## The data
+
+`Users_DelegatorUsers` lives in **every** client database
+(`dbchanges2/Client/2026-09-18a - UsersDelegatorUsersTable.sql`):
+
+| column | meaning |
+|---|---|
+| `userId` | the person doing the ordering |
+| `delegatorUserId` | the person being ordered for |
+
+Read it as "userId may order for delegatorUserId". Unique key on the pair, so a
+row cannot be added twice. Model: `_Model_Client_Users_DelegatorUser`.
+
+**The table ships empty.** There is no admin screen and no import. Until rows are
+inserted, every dropdown is empty and every delegation is refused. That is correct
+behaviour, not a bug.
+
+Core metadata (`dbchanges2/Core/2026-09-18a`): record **362**, route
+`user-delegator-users`, `aclDatabase = CLIENT`, RecordFields **2604** id, **2605**
+uuid, **2606** userId, **2607** delegatorUserId. Registered as an inherent child of
+record 2 (Users), which is what makes `userDelegatorUsers` readable nested under a
+user.
+
+## The gate
+
+Two checks, both server side, both against the same table.
+
+**1. Minting the encrypted pair.** `_Model_Client_User::encryptedUser()` calls
+`canUserOrderForOtherUser()`. Self is always allowed so switching back works. Anyone
+not on the list gets a 403 and no pair.
+
+**2. Issuing the token.** `api2/Component/Api/V2/V2.php`, `case 'delegator'` sets
+`$isDelegatorAuthRequest = true` as its first statement, then falls through into
+`case 'encrypted'` where the pair is checked again. This second check matters because
+the encrypted pair has **no expiry and no MAC** (`_String::encryptWithKey`, AES-256-CBC
+keyed on `Core.Parameters.API_SECRET_REFRESH_TOKEN`), so a captured pair could
+otherwise be replayed forever.
+
+**3. Refresh.** `/auth/refresh` re-checks an active delegation, so deleting a row or
+deactivating either account ends the session instead of only blocking new switches.
+
+The flag defaults to **false**, not true. A forged or expired bearer leaves
+`$this->delegator` null, and a fail-open default would have minted a token.
+
+## The audit trail
+
+`Logs_<Client>.Api.originalUserId` (`dbchanges2/Logs_Client/2026-09-18a`), nullable,
+sits after `userId`. `V2.php` fills it at all three places it writes a client log row,
+plus the CloudWatch entry.
+
+- `userId` = who the token is for (the person being ordered for)
+- `originalUserId` = who actually signed in
+
+NULL means no delegation. Verified on order **SA136321**: `createdByUserId` Dawn
+Anderson, log row `userId 124256` / `originalUserId 127046` (Dev Team).
+
+Outbound logs (`_ApiRequest`, `_SoapRequest`, `direction = OUT`) never set either
+column. There is no signed-in user on a call TOGa makes out to NetSuite or UPS.
+
+## Front end
+
+### Getting the list
+
+`toga2-commerce/src/pages/Cart/api/CartApi.ts`:
+
+```ts
+const people = await fetchDelegationList(user.uuid);
+// [{ uuid, name, email }, ...]
+```
+
+Pass the **signed-in user's own uuid**. One call, no paging, the whole list arrives at
+once. Type `DelegationOption` is in `src/pages/Cart/types.ts`.
+
+Two rules that are easy to get wrong:
+
+1. **Call it before switching the token.** Once the token belongs to the other person,
+   the signed-in user's own record reads as a 403. Cache the list you already loaded.
+2. **Never request `id`.** Asking for `id` makes the whole GET fail with a 403 for
+   these roles. Use `uuid`.
+
+### Switching the token
+
+Order For is only real if the token changes. The steps, same as View As in
+`src/components/NavIcons/NavIconList.tsx`:
+
+1. `GET /users/encryptedUser?uuid=<target>` returns `{client, user}` ciphertext.
+2. `POST /auth/delegator` with that pair returns the delegated token pair.
+3. `beginDelegation(tokens, originalUserUuid)` from `src/api/sessionTokens.ts` parks
+   the signed-in person's own pair and makes the delegated pair active.
+4. `restoreOriginalTokens(originalUserUuid)` puts them back, no new login needed.
+
+In the JWT, `id.client.user` is the target and `id.delegator` is the real human.
+
+**If you skip the switch and only keep the pick as a form value, none of the backend
+work runs.** `$api->delegator` is never set, `originalUserId` stays NULL, the
+`Users_DelegatorUsers` check never fires, and the user browses their own catalog and
+prices while "ordering for" someone else.
+
+There is one parked-token slot shared with View As, so the two features cannot be
+nested. Guard whichever one you are building against the other.
+
+## ACL
+
+Read only on purpose. A role that can write its own row here can self-grant the right
+to order for anyone in the tenant, which defeats the whole gate.
+
+| | Compass Base | Manager |
+|---|---|---|
+| US `Client_Compass` | role 7 | role 8 |
+| Canada `Client_CompassCanada` | role **8** | role **9** |
+
+**Canada role ids are different from US.** Do not copy the US file and rename it.
+
+`appId` 5 is TOGa Commerce. The row expression is scoped to the caller, not `1`:
+
+```sql
+CASE WHEN Users_DelegatorUsers.userId = AclUser.id THEN 1 ELSE 0 END
+```
+
+`user-delegator-users` is a real route, so a plain `1` would let any user call
+`GET /v2/user-delegator-users` and list who every colleague can order for. `AclUser`
+is joined by `_Model_True::isPermitted` on the logged-in user.
+
+Canada also needed `Core.RecordScripts` id **16** (`encryptedUser`) granted to its
+roles 8 and 9. Canada shipped with only role 1 (Base), so a normal Canada user got a
+403 on every pick. US Compass already had it.
+
+## Traps that cost real time
+
+- **`empty()` and `isset()` always lie on a `_Model` field.** `_Model::initialize()`
+  unsets every declared property and `_Model` has no `__isset`, so `empty($api->user->id)`
+  is always true. Use `(int)$x->id > 0`. This silently made the gate refuse everyone,
+  including a user acting as themself, and both reviewers and `php -l` passed it.
+- **An ACL permission with no logic group denies everything.** `buildSqlExpression()`
+  returns `(0)`. `allowRead = 1` on its own grants nothing. You need the
+  `AclRecordExpressions` row, an `AclLogicGroups` row, and the link row.
+- **Core rows are ignored for a CLIENT record.** Record 362 is `aclDatabase = CLIENT`,
+  and every lookup in `V2.php` (3236, 4057, 6502, 7307) switches on that and reads only
+  the matching bucket. Anything you put in `Core.AclRecordPermissions` for 362 is dead.
+- **Core cannot name an api2 class.** Use `$api->response::DEFINED_MESSAGE_ERROR_UNAUTHORIZED`
+  from inside `_underscore`, not `\api\_Component_Api_V2_Response`.
+- **Never join Core and `Client_<Tenant>` in one query.** Separate prod clusters.
+
+## Still open
+
+- **Nothing seeds `Users_DelegatorUsers`.** No admin screen, no import.
+- **`c_orderSubmittedById` is not stamped.** The column, `CustomRecordFields` id 40 on
+  record 14, and `_Model_Compass_SalesOrder:51` all already exist from Compass 1.0. It
+  is a plain `FIELD_INTEGER`, not a foreign key, so api2 will not resolve a `{uuid}` and
+  the client cannot set it. It belongs in `_Model_Compass_SalesOrder::prePost()` (line
+  445, interceptor id 24, already active as PRE on POST for record 14), read from
+  `$api->delegator->user`. Leave NULL when there is no delegation, matching 1.0's
+  `convertcarttoorder.php`. Note the old data is dirty: of 112,096 Compass orders 8,118
+  have the field set and 7,174 of those equal `createdByUserId`, because the 1.0 guard
+  compared a manager id against a contact id.
+- **Role 3 (API) has no grant on record 362 in any `Client_*` database**, only the dead
+  Core one, so no integration can read or write the table through api2.
+- **`/auth/encrypted` still accepts a delegation pair with no bearer** and records no
+  delegator. Narrowed because Commerce no longer calls it; toga2-desk still does for
+  client switching.
+
+## Files
+
+| repo | file |
+|---|---|
+| `_underscore` | `Model/Client/Users/DelegatorUser.php` |
+| `_underscore` | `Model/Client/User.php` (`canUserOrderForOtherUser`, `getRequestingUser`, `encryptedUser`) |
+| `_underscore` | `Model/Client/Logs/Api.php` (`originalUserId`) |
+| `api2` | `Component/Api/V2/V2.php` |
+| `dbchanges2` | `Client/2026-09-18a - UsersDelegatorUsersTable.sql` |
+| `dbchanges2` | `Core/2026-09-18a - UserDelegatorUserRecords.sql` |
+| `dbchanges2` | `Client_Compass/2026-09-18a - UserDelegatorUsersReadAcl.sql` |
+| `dbchanges2` | `Client_CompassCanada/2026-09-18a - UserDelegatorUsersReadAcl.sql` |
+| `dbchanges2` | `Logs_Client/2026-09-18a - ApiOriginalUserId.sql` |
+| `toga2-commerce` | `src/pages/Cart/api/CartApi.ts` (`fetchDelegationList`) |
+| `toga2-commerce` | `src/pages/Cart/types.ts` (`DelegationOption`) |
+| `toga2-commerce` | `src/components/OrderForDropdown/` (the UI) |
+| `toga2-commerce` | `src/api/sessionTokens.ts` (token parking) |
+
+## Checking a refusal
+
+```sql
+SELECT d.id, u.id AS orderingUserId, CONCAT(u.firstName,' ',u.lastName) AS orderingUser,
+       du.id AS forId, CONCAT(du.firstName,' ',du.lastName) AS orderedFor
+FROM Users_DelegatorUsers d
+JOIN Users u ON u.id = d.userId
+JOIN Users du ON du.id = d.delegatorUserId;
+```
+
+Then confirm the log stamped both people:
+
+```sql
+SELECT id, dtStamp, method, route, responseCode, userId, originalUserId
+FROM Logs_Compass.Api ORDER BY id DESC LIMIT 20;
+```