@open-rlb/nestjs-amqp 2.0.8 → 2.0.10

package/schematics/nest-add/files/skills/rlb-amqp/references/config-schema.md

@@ -134,7 +134,7 @@ auth-providers:
   - name: gateway-jwks
     type: jwks                       # jwt | jwks | basic | str-compare | none
     headerPrefix: "X-GTW-AUTH-"      # prefix for mapped claim headers (and <prefix>USERID)
-    uidClaim: sub                    # claim → <prefix>USERID; REQUIRED for role checks
+    uidClaim: sub                    # claim → <prefix>USERID; REQUIRED for action checks
     jwtMap:                          # 'source:dest' pairs → <prefix><DEST>; WITHOUT it NO claims forwarded
       - sub:userId                   #   → X-GTW-AUTH-USERID
       - email:email                  #   → X-GTW-AUTH-EMAIL
@@ -159,8 +159,8 @@ Type behaviour:
 
 Hardening: `algorithms` REQUIRED for `jwt`/`jwks` (omit → denied; algorithm-confusion guard).
 Define `jwtMap` or no identity is forwarded (token still `success:true` — fail-safe, not leak).
-`usernameClaim` is deprecated; `aclTopic`/`aclAction` are removed (gateway role check is in-process
-via `IAclRoleService.canUserDoGtw`).
+`usernameClaim` is deprecated; `aclTopic`/`aclAction` are removed (the gateway action check is
+in-process via `IAclRoleService.checkAction(userId, ctx, action)`).
 
 > DB-stored auth-providers (name-keyed `gw-auth-*` upserts) layer on top of this static list —
 > see `docs/gateway-admin.md`.
@@ -211,8 +211,8 @@ control-topic subscriber ignores every other message. Concurrent `reload()`s are
   mode: rpc               # rpc | event
   timeout: 15000          # rpc only (ms)
   auth: gateway-jwks      # auth-provider name
-  allowAnonymous: false   # true → skip the auth/role gate entirely
-  roles: [user, admin]    # caller must hold AT LEAST ONE; requires auth + IAclRoleService
+  allowAnonymous: false   # true → skip the auth/action gate entirely
+  actions: [doc.read, doc.admin]   # caller must hold AT LEAST ONE on (companyId, resourceId); needs auth + IAclRoleService
   successStatusCode: 200  # default 200 rpc / 202 event / 204 empty rpc reply
   binary: true            # treat a raw (non-JSON) reply as base64 → binary body
   redirect: 302           # rpc only → redirect with this status, using the reply as Location
@@ -238,9 +238,13 @@ Uploads → `$files` (buffers as binary strings), raw → `$raw`.
 ForbiddenError→403, NotFoundError→404, ConflictError→409, else→500.
 **event status:** successful publish → `successStatusCode || 202`; publish failure → `503`.
 
-Auth gate (per request): `allowAnonymous:true` → gate skipped; `auth` no `roles` → authn only
-(401 if invalid); `auth` + `roles` → authn then in-process `canUserDoGtw(roles, userId)` (403 if
-no role). `roles` without `auth` fails closed (every request 403).
+Auth gate (per request): `allowAnonymous:true` → gate skipped; `auth` no `actions` → authn only
+(401 if invalid); `auth` + `actions` → authn then in-process
+`checkAction(userId, { companyId, resourceId }, actions)` (403 if the caller holds none of
+`actions` on that pair). `actions` without `auth` fails closed (every request 403).
+
+The gateway reads the canonical `companyId`/`resourceId` from the request (precedence
+params → query → body) and matches them exactly for the action check.
 
 ### gateway.events[]  (WebSocketEvent — WS / webhook)
 
@@ -251,7 +255,7 @@ no role). `roles` without `auth` fails closed (every request 403).
   routingKey: chat.messages
   auth: gateway-jwks       # provider that verifies the token + maps claims FOR THIS event (at subscribe)
   requireAuth: true        # default true when `auth` is set; false → auth optional (anon allowed)
-  roles: [user]            # ACL check via IAclRoleService (needs auth)
+  actions: [chat.read]     # ACL check via IAclRoleService.checkAction (needs auth); WS gates resource-agnostically
   scopeClaim: userId       # per-user isolation: the mapped claim value...
   payloadKey: userId       # ...must equal payload[payloadKey]; without payloadKey → denies everything
   # type: http only:
@@ -282,11 +286,10 @@ ACL (topic `rlb-acl`):
 
 | Method | Path | Action |
 | --- | --- | --- |
-| GET | `/acl/check` | `acl-can-user-do-gtw` (resource-agnostic; `200` true/false) |
-| GET | `/acl/check-resource` | `acl-can-user-do` (resource-scoped; `200` true/false) |
+| GET | `/acl/check` | `acl-check-action` (`?userId=&action=&companyId?=&resourceId?=`; exact-match; `200` true/false) |
 | GET | `/acl/resources` | `acl-list-resources-by-user` (auth, reads `X-GTW-AUTH-USERID`) |
-| POST | `/acl/grants` | `acl-grant` (`{userId, roles, resourceId?, companyId?}`) |
-| DELETE | `/acl/grants` | `acl-revoke` (same shape; `roles` REQUIRED) |
+| POST | `/acl/grants` | `acl-grant` (`{userId, roles, resourceId?, companyId?}`; caller needs `role-management` on target) |
+| DELETE | `/acl/grants` | `acl-revoke` (same shape; `roles` REQUIRED; caller needs `role-management` on target) |
 | GET / PUT / DELETE | `/acl/actions[/get?name=]` | `acl-action-list`/`-update`/`-delete`/`-get` |
 | GET / PUT / DELETE | `/acl/roles[/get?name=]` | `acl-role-list`/`-update`/`-delete`/`-get` |
 
@@ -301,4 +304,5 @@ Gateway-admin (topic `rlb-gateway-admin`, except reload):
 | POST | `/admin/metrics/track` | `gw-metrics-track` (`mode: event`) |
 | POST | `/admin/reload` | `gw-reload` on `rlb-gateway-control` (`mode: event`) |
 
-> Removed: `acl-list-by-user`, `acl-verify-access`, `gw-auth-create`, all id-based ACL CRUD.
+> Removed: `acl-list-by-user`, `acl-verify-access`, `acl-can-user-do`, `acl-can-user-do-gtw`
+> (all collapsed into `acl-check-action`), `gw-auth-create`, all id-based ACL CRUD.

package/schematics/nest-add/files/skills/rlb-amqp/references/gotchas.md

@@ -76,29 +76,54 @@ Ported from `docs/gotchas.md` (re-verified against post-2.0.5 code).
     NOT a metrics dump. Use `/admin/metrics*` (`gw-metrics-*`) for metrics.
 
 ## Auth / ACL
-21. **`roles` require `auth` on the same path/event.** No `auth` → no identity → fails closed
-    (every request `403`, logged at boot). Always pair `roles: [...]` with `auth: <provider>`.
-22. **`roles` require an `IAclRoleService`** registered via `RLB_GTW_ACL_ROLE_SERVICE` in
+21. **`actions` require `auth` on the same path/event.** No `auth` → no identity → fails closed
+    (every request `403`, logged at boot). Always pair `actions: [...]` with `auth: <provider>`.
+22. **`actions` require an `IAclRoleService`** registered via `RLB_GTW_ACL_ROLE_SERVICE` in
     `ProxyModule.forRootAsync({ providers: [...] })`. Missing → deny (403). The gateway check is
-    **role-based, OR, resource-agnostic** (`canUserDoGtw(roles, userId)`): `roles` lists ROLE NAMES,
-    the user passes holding AT LEAST ONE. The provider only needs `uidClaim` (+ `headerPrefix`).
-23. **Two ACL check actions on `rlb-acl`** (both cached, both HTTP GET → `200` true/false):
-    `acl-can-user-do-gtw` → `canUserDoGtw(roles, userId)` (gateway filter, OR, resource-agnostic,
-    `GET /acl/check`) and `acl-can-user-do` → `canUserDo(roles, userId, resource)` (**ms-side**;
-    a global grant OR a grant on that resource passes, `GET /acl/check-resource`).
+    **action-based, OR, resource-SCOPED** (`checkAction(userId, ctx, actions)`): `actions` lists
+    ACTION NAMES, the caller is authorized if it holds AT LEAST ONE on the request's
+    `(companyId, resourceId)`. The provider only needs `uidClaim` (+ `headerPrefix`).
+23. **One ACL check action on `rlb-acl`: `acl-check-action`** (cached, HTTP GET → `200` true/false).
+    `checkAction(userId, ctx, action)`, `ctx = { companyId?, resourceId? }`,
+    `action = string | string[]` (OR). It resolves action→roles-that-include-it, then matches the
+    user's grants. A grant authorizes **iff** `grant.companyId === req.companyId &&
+    grant.resourceId === req.resourceId` (undefined/null/`''` = absent). The ONLY carve-out: both
+    ids absent on request AND grant. **No wildcard** — a `null` `resourceId` does NOT match
+    everything; `companyId` is load-bearing. Replaces the old `acl-can-user-do` /
+    `acl-can-user-do-gtw` and the merged `GET /acl/check` + `/acl/check-resource`.
+23a. **Gateway gating is ACTION-based, not role-based.** `gateway.paths[].actions` /
+    `events[].actions` name ACTIONS (was `roles`). The gateway resolves `userId` from the auth
+    provider, extracts `(companyId, resourceId)` from the request, and authorizes if the caller
+    holds one of `actions` on that pair. It reads the canonical `companyId`/`resourceId` from the
+    request (precedence params→query→body) and matches them exactly. WS events gate by `actions`
+    **resource-agnostically**.
+23b. **`@BrokerAuth`'s 3rd param is now `actions` (was `roles`).** Signature:
+    `@BrokerAuth(authName, allowAnonymous?, actions?, httpName?)`. Pass action names there for an
+    auto-discovered route's action gate.
 24. **Actions, roles & auth-providers are NAME-KEYED. PUT upserts; there is NO POST.** The `name`
     IS the key (no id). `PUT` creates-or-updates, `GET` lists, `GET .../get?name=` reads one,
     `DELETE` removes by `name`. The old id-based ACL CRUD and `POST`-create endpoints are GONE.
     (Gateway-admin **paths** are the exception — they keep id-keyed CRUD and a POST create.)
 25. **`acl-grant` / `acl-revoke` both REQUIRE `userId` + `roles`** (optional `resourceId` +
-    `companyId`). `grant` MERGES roles into the single `(userId, resourceId)` record (idempotent).
-    `revoke` REMOVES exactly those roles and **deletes the record once it has no roles left**.
-    `revoke` without `roles` throws `400 roles are required` — to wipe a grant, revoke all its roles.
-26. **`companyId` is grouping metadata only.** It replaced `resourceBusinessId` and plays NO part
-    in authorization — it only groups resources in `acl-list-resources-by-user`. Targeting is by
-    `(userId, resourceId)` only. Both grant/revoke validate every role exists (unknown → `400`).
-27. **Removed actions:** `acl-list-by-user` and `acl-verify-access` no longer exist. Use
-    `acl-can-user-do` for resource-scoped checks and `acl-list-resources-by-user` to list resources.
+    `companyId`). The grant record is keyed by `(userId, companyId, resourceId)`. `grant` MERGES
+    roles into that triple (idempotent). `revoke` REMOVES exactly those roles and **deletes the
+    record once it has no roles left**. `revoke` without `roles` throws `400 roles are required` —
+    to wipe a grant, revoke all its roles. **Grants assign ROLES (keep the `roles` param); roles
+    contain actions.** Only the gateway/route GATE switched to action names.
+25a. **`acl-grant` / `acl-revoke` are GATED.** The caller (forwarded `X-GTW-AUTH-USERID`) must hold
+    the `role-management` action on the TARGET `(companyId, resourceId)`, else `403`. The gate
+    action defaults to `role-management`, overridable via `AclModuleOptions.roleManagementAction`.
+    **Chicken-and-egg:** no caller can grant the very first `role-management`, so **bootstrap by
+    seeding the first `role-management` grant directly in the DB**.
+26. **`companyId` is LOAD-BEARING in authorization.** It replaced `resourceBusinessId` and is
+    BOTH part of the grant identity AND matched during `checkAction`: a grant authorizes only when
+    `grant.companyId === req.companyId` (and `resourceId` likewise). It also groups
+    `acl-list-resources-by-user` output. There is **no wildcard** — a `null`/absent `resourceId`
+    only matches a request with that id also absent. Both grant/revoke validate every role exists
+    (unknown → `400`).
+27. **Removed actions:** `acl-list-by-user`, `acl-verify-access`, `acl-can-user-do`, and
+    `acl-can-user-do-gtw` no longer exist (the last two collapsed into `acl-check-action`). Use
+    `acl-check-action` for authorization checks and `acl-list-resources-by-user` to list resources.
 28. **Auth & gateway config go to `ProxyModule`** (`authOptions` / `gatewayOptions`), not
     `BrokerModule`. `BrokerModule` owns only `options` / `topics` / `appOptions`.
 

package/schematics/nest-add/files/skills/rlb-amqp-acl/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rlb-amqp-acl
-description: Manage role-based access control (ACL) with @open-rlb/nestjs-amqp — actions, roles, grants/revokes, and "can user do X" checks. Use when wiring AclModule, gating gateway routes by roles, granting/revoking a user's roles, listing a user's resources, or answering authorization/permission questions (roles, grants, acl-check).
+description: Manage access control (ACL) with @open-rlb/nestjs-amqp — actions, roles, grants/revokes, and "can user do X" checks. Use when wiring AclModule, gating gateway routes by actions, granting/revoking a user's roles, listing a user's resources, or answering authorization/permission questions (actions, roles, grants, acl-check).
 ---
 
 # Manage ACL (@open-rlb/nestjs-amqp)
@@ -11,15 +11,16 @@ Read first when you need depth:
 - `sample/config-sample/acl.yaml` (annotated broker + gateway reference)
 - `sample/config-sample/gateway-in-memory/src/app.module.ts` (forRoot wiring)
 
-Use when: managing **actions/roles/grants**, wiring `AclModule`, role-gating routes
-(`roles: [...]`), or answering "can user do X".
+Use when: managing **actions/roles/grants**, wiring `AclModule`, action-gating routes
+(`actions: [...]`), or answering "can user do X".
 
 ## Model (3 entities)
 
 - **Action** — atomic capability (`read-doc`). Name-keyed.
 - **Role** — bundle of action names (`editor = [read-doc, write-doc]`). Name-keyed.
-- **Grant** — binds a `userId` → role names; one record per `(userId, resourceId)`.
-- **Checks** match on **roles, never action strings**.
+- **Grant** — binds a `userId` → role names; one record per `(userId, companyId, resourceId)`.
+- **Checks** resolve the requested **action** → roles-that-include-it, then match the
+  user's grants. The route/gate names **actions**; grants still assign **roles**.
 
 ## Decorator-bound (NOT configurable)
 
@@ -28,8 +29,8 @@ reference them literally. The queue / exchange / routingKey that carry the topic
 
 `ACL_ACTIONS`: `acl-action-list`, `acl-action-get`, `acl-action-update`,
 `acl-action-delete`, `acl-role-list`, `acl-role-get`, `acl-role-update`,
-`acl-role-delete`, `acl-grant`, `acl-revoke`, `acl-can-user-do-gtw`,
-`acl-can-user-do`, `acl-list-resources-by-user`, `acl-invalidate`.
+`acl-role-delete`, `acl-grant`, `acl-revoke`, `acl-check-action`,
+`acl-list-resources-by-user`, `acl-invalidate`.
 
 > **Removed in 2.0.5:** `acl-list-by-user`, `acl-verify-access`, `acl-create` /
 > id-based ACL CRUD. Entities are name-keyed: **PUT upserts, no POST.**
@@ -38,30 +39,40 @@ reference them literally. The queue / exchange / routingKey that carry the topic
 
 No id, no POST. `PUT` upserts by `name` (idempotent), `GET` lists (`?page=&limit=`),
 `GET …/get?name=` reads one, `DELETE` removes by `name`. Role upsert: every referenced
-action must already exist (else **400**).
+action must already exist (else **400**). The `*-search` actions (`acl-action-search`,
+`acl-role-search`, `acl-grant-search`) now take `?q=&page=&limit=` and return
+`PaginationModel<T>` (`{ page, limit, total, data }`), not a bare array.
 
-## Grants — dual grant/revoke
+## Grants — dual grant/revoke (now GATED)
 
-One record per `(userId, resourceId)`. Both ops **require `userId` + `roles`**;
-`resourceId` + `companyId` are **optional**.
+One record per `(userId, companyId, resourceId)`. Both ops **require `userId` + `roles`**;
+`resourceId` + `companyId` are **optional** but PART of the record identity.
 
-- `acl-grant` — merges roles into the pair (creates if absent; idempotent).
+- `acl-grant` — merges roles into the triple (creates if absent; idempotent).
 - `acl-revoke` — removes roles; deletes the record once empty.
 - Both validate every role exists (unknown role → **400**) and invalidate the user's cache.
-- `companyId` (replaced `resourceBusinessId`) is **grouping metadata only** — it groups
-  `acl-list-resources-by-user` output and plays **no part** in authorization.
-
-## Checks — GET → 200 with `true`/`false`
-
-`false` is real content; only `null`/`undefined` collapses to 204. Both return `false`
-(never throw) on missing input or error.
-
-- `acl-can-user-do-gtw` — resource-**agnostic**, the gateway's primary filter. `true` if
-  the user holds **≥1** requested role. Query: `?userId=&roles=user&roles=admin`.
-- `acl-can-user-do` — resource-**scoped**: `true` if a **global** grant OR a grant bound
-  to that exact `resource` gives a matching role. Query: `?userId=&roles=admin&resource=doc-1`.
-  Normally called over the broker by the owning microservice.
-- `acl-list-resources-by-user` — **auth-gated** (needs `auth`, no roles): reads `userId`
+- `companyId` (replaced `resourceBusinessId`) is **load-bearing**: it is part of the grant
+  identity AND part of authorization (a grant matches only when its `companyId` equals the
+  request's). It also groups `acl-list-resources-by-user` output.
+- **Caller gating:** `acl-grant`/`acl-revoke` require the caller (forwarded
+  `X-GTW-AUTH-USERID`) to hold the `role-management` action on the TARGET
+  `(companyId, resourceId)`, else **403**. The gate action defaults to `role-management`,
+  overridable via `AclModuleOptions.roleManagementAction`. Bootstrap by seeding the first
+  `role-management` grant directly in the DB (no caller can grant it otherwise).
+
+## Checks — single primitive, GET → 200 with `true`/`false`
+
+`false` is real content; only `null`/`undefined` collapses to 204. Returns `false`
+(never throws) on missing input or error.
+
+- `acl-check-action` → `checkAction(userId, ctx, action)`, `ctx = { companyId?, resourceId? }`,
+  `action = string | string[]` (OR). Resolves the action(s) → roles-that-include-it, then
+  matches the user's grants. A grant authorizes **iff** `grant.companyId === req.companyId &&
+  grant.resourceId === req.resourceId` (undefined/null/`''` all count as absent). The ONLY
+  carve-out: both ids absent on the request AND on the grant. **No wildcard** — a `null`
+  `resourceId` no longer matches everything; `companyId` is load-bearing.
+  Query: `?userId=&action=read-doc&companyId=acme&resourceId=doc-1`.
+- `acl-list-resources-by-user` — **auth-gated** (needs `auth`, no actions): reads `userId`
   from the forwarded `X-GTW-AUTH-USERID` header; lists accessible resources grouped by
   `companyId` with resolved actions.
 
@@ -88,8 +99,9 @@ AclModule.forRoot(
 );
 ```
 
-Gateway side — let route `roles: [...]` filters run **in-process** (no broker hop) by
-binding the gateway token to the same `AclService`:
+Gateway side — let route `actions: [...]` gates run **in-process** (no broker hop) by
+binding the gateway token to the same `AclService` (implements
+`IAclRoleService.checkAction(userId, ctx, action)`):
 
 ```ts
 import { ProxyModule, AclService, RLB_GTW_ACL_ROLE_SERVICE } from '@open-rlb/nestjs-amqp';
@@ -99,8 +111,9 @@ ProxyModule.forRoot({
 });
 ```
 
-Same process → `useExisting`. Separate services → gateway RPCs `acl-can-user-do-gtw` on
-`rlb-acl` instead. A route's `roles` are ROLE NAMES; the user passes with **≥1**.
+Same process → `useExisting`. Separate services → gateway RPCs `acl-check-action` on
+`rlb-acl` instead. A route's `actions` are ACTION NAMES; the caller is authorized if it
+holds **≥1** of them on the request's `(companyId, resourceId)`.
 
 ## YAML — topic + queue (names fixed, transport yours)
 
@@ -131,14 +144,16 @@ the fixed library string.
 | acl-action-get | GET | /acl/actions/get | query | acl-action-get |
 | acl-action-upsert | PUT | /acl/actions | body | acl-action-update |
 | acl-action-delete | DELETE | /acl/actions | body | acl-action-delete |
+| acl-action-search | GET | /acl/actions/search | query | acl-action-search (`?q=&page=&limit=` → `PaginationModel<AclAction>`) |
 | acl-role-list | GET | /acl/roles | query | acl-role-list |
 | acl-role-get | GET | /acl/roles/get | query | acl-role-get |
 | acl-role-upsert | PUT | /acl/roles | body | acl-role-update |
 | acl-role-delete | DELETE | /acl/roles | body | acl-role-delete |
-| acl-grant | POST | /acl/grants | body | acl-grant |
-| acl-revoke | DELETE | /acl/grants | body | acl-revoke |
-| acl-check-gtw | GET | /acl/check | query | acl-can-user-do-gtw |
-| acl-check-resource | GET | /acl/check-resource | query | acl-can-user-do |
+| acl-role-search | GET | /acl/roles/search | query | acl-role-search (`?q=&page=&limit=` → `PaginationModel<AclRole>`) |
+| acl-grant | POST | /acl/grants | body | acl-grant (gated: caller needs `role-management`) |
+| acl-revoke | DELETE | /acl/grants | body | acl-revoke (gated: caller needs `role-management`) |
+| acl-grant-search | GET | /acl/grants/search | query | acl-grant-search — access search (`?q=&page=&limit=` → `PaginationModel<AclGrant>`) |
+| acl-check | GET | /acl/check | query | acl-check-action |
 | acl-list-resources-by-user | GET | /acl/resources | query | acl-list-resources-by-user (+ `auth:`) |
 
 ```yaml
@@ -153,18 +168,18 @@ gateway:
       action: acl-role-update
       mode: rpc
     - name: acl-grant              # body: { userId, roles, resourceId?, companyId?, friendlyName? }
-      method: POST
+      method: POST                 # gated: caller (X-GTW-AUTH-USERID) needs role-management on target
       path: /acl/grants
       dataSource: body
       topic: rlb-acl
       action: acl-grant
       mode: rpc
-    - name: acl-check-gtw          # ?userId=&roles=user&roles=admin → 200 true/false
+    - name: acl-check              # ?userId=&action=read-doc&companyId=&resourceId= → 200 true/false
       method: GET
       path: /acl/check
       dataSource: query
       topic: rlb-acl
-      action: acl-can-user-do-gtw
+      action: acl-check-action
       mode: rpc
     - name: acl-list-resources-by-user   # auth-gated; userId from X-GTW-AUTH-USERID
       method: GET
@@ -180,6 +195,9 @@ gateway:
 
 - topic `rlb-acl` + its queue declared on the consuming service; gateway paths use the
   literal `action` strings above.
-- role-gated routes (`roles: [...]`) → `RLB_GTW_ACL_ROLE_SERVICE` bound to an
-  `IAclRoleService` (`AclService`). Auth-provider needs `uidClaim` (+ `headerPrefix`).
+- action-gated routes (`actions: [...]`) → `RLB_GTW_ACL_ROLE_SERVICE` bound to an
+  `IAclRoleService` (`AclService`, `checkAction`). Auth-provider needs `uidClaim`
+  (+ `headerPrefix`).
+- `acl-grant`/`acl-revoke` are gated — seed the first `role-management` grant directly in
+  the DB or every caller gets `403`.
 - a check returning `false` is a **200**, not an error.

package/schematics/nest-add/files/skills/rlb-amqp-add-action/SKILL.md

@@ -97,8 +97,9 @@ Two independent pairings sit on the method, each only needed in the multi case:
   `@BrokerAuth` is **public**.
 
 Auth lives in a separate, decoupled decorator —
-`@BrokerAuth(authName, allowAnonymous?, roles?, httpName?)` — never inside `@BrokerHTTP`'s options.
-This lets two HTTP paths for the SAME action carry DIFFERENT auth.
+`@BrokerAuth(authName, allowAnonymous?, actions?, httpName?)` — never inside `@BrokerHTTP`'s options.
+The 3rd param is `actions` (ACL action names, was `roles`). This lets two HTTP paths for the SAME
+action carry DIFFERENT auth.
 
 Simple case — one route, auth auto-pairs (no names needed):
 
@@ -118,7 +119,7 @@ Multi case — two routes for ONE action, each name-paired to its own auth:
 @BrokerHTTP('GET', '/bookings/:id',       'params', { name: 'get-booking' })
 @BrokerAuth('cust-jwks', true, undefined, 'get-booking')          // httpName ⇄ route name
 @BrokerHTTP('GET', '/admin/bookings/:id', 'params', { name: 'admin-get-booking' })
-@BrokerAuth('admin-jwks', undefined, ['admin'], 'admin-get-booking')
+@BrokerAuth('admin-jwks', undefined, ['booking.admin'], 'admin-get-booking')  // 3rd param = ACL actions
 async getBooking(@BrokerParam('params', 'id') id: string) {
   return this.bookings.find(id);
 }

package/schematics/nest-add/files/skills/rlb-amqp-add-route/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rlb-amqp-add-route
-description: Expose a broker action over HTTP through the @open-rlb/nestjs-amqp gateway by adding a gateway.paths[] entry. Use when the user wants a new HTTP endpoint/REST route that forwards to a topic/action, choosing rpc (wait reply) vs event (fire-and-forget with confirm), with auth, roles, dataSource, timeout, file upload or raw body. Generates the YAML path fragment and flags required bootstrap/ACL wiring.
+description: Expose a broker action over HTTP through the @open-rlb/nestjs-amqp gateway by adding a gateway.paths[] entry. Use when the user wants a new HTTP endpoint/REST route that forwards to a topic/action, choosing rpc (wait reply) vs event (fire-and-forget with confirm), with auth, actions (ACL gate), dataSource, timeout, file upload or raw body. Generates the YAML path fragment and flags required bootstrap/ACL wiring.
 ---
 
 # Add an HTTP gateway route (gateway.paths[])
@@ -20,7 +20,9 @@ Canonical example: `sample/config-sample/gateway-in-memory/config/config.yaml`.
 - **dataSource**: how the payload is assembled — `req.params` are ALWAYS merged in, plus:
   `body` | `query` | `params` | `body-query` (body wins) | `query-body` (query wins).
 - **auth**: an `auth-provider` name (validates the request, maps claims to `X-GTW-AUTH-*`
-  headers). `allowAnonymous: true` skips the gate. `roles: [...]` adds a role check.
+  headers). `allowAnonymous: true` skips the gate. `actions: [...]` adds an ACL action check
+  scoped to the request's `(companyId, resourceId)` (read from the canonical fields,
+  params → query → body).
 - Extras: `timeout` (rpc), `successStatusCode`, `binary`, `redirect`, `parseRaw`, static
   `headers`, `forwardHeaders`.
 
@@ -36,7 +38,7 @@ Canonical example: `sample/config-sample/gateway-in-memory/config/config.yaml`.
 | `dataSource` | `body` \| `query` \| `params` \| `body-query` \| `query-body`. |
 | `auth` | Auth-provider name; validates + maps claims. |
 | `allowAnonymous` | `true` → gate skipped (token still mapped if present & valid). |
-| `roles` | Role NAMES; caller passes with AT LEAST ONE. Requires `auth`. |
+| `actions` | ACTION NAMES; caller passes holding AT LEAST ONE on the request's `(companyId, resourceId)`. Requires `auth`. |
 | `timeout` | RPC timeout (ms), `rpc` only. |
 | `binary` | Treat a raw (non-JSON) RPC reply as base64 → binary body. |
 | `parseRaw` | Adds the raw request body as `$raw` (needs `rawBody: true`). |
@@ -60,7 +62,7 @@ gateway:
       action: <action>
       mode: rpc                    # or event
       auth: gateway-jwks           # optional
-      roles: [resource.write]      # optional → needs RLB_GTW_ACL_ROLE_SERVICE
+      actions: [resource.write]    # optional → needs RLB_GTW_ACL_ROLE_SERVICE; checked on (companyId, resourceId)
       timeout: 7000                # rpc only
       successStatusCode: 201
 ```
@@ -71,15 +73,18 @@ For every request the gateway runs `processAuthData` (best-effort), then:
 
 1. **`allowAnonymous: true`** → gate SKIPPED. A valid token still gets its claims mapped &
    forwarded; a missing/invalid token is NOT blocked.
-2. **`auth` set, no `roles`** → authentication only. Provider must validate (else `401`);
+2. **`auth` set, no `actions`** → authentication only. Provider must validate (else `401`);
    on success the `X-GTW-AUTH-*` headers are forwarded downstream.
-3. **`auth` + `roles`** → authn + role authz. After a valid token the gateway reads the user
-   id from the provider's `uidClaim` and calls `IAclRoleService.canUserDoGtw(roles, userId)`
-   in-process. Passes with at least one role, else `403`.
+3. **`auth` + `actions`** → authn + action auth. After a valid token the gateway reads the
+   user id from the provider's `uidClaim`, extracts `(companyId, resourceId)` from the request
+   (canonical fields, params → query → body), and calls
+   `IAclRoleService.checkAction(userId, { companyId, resourceId }, actions)` in-process. Passes
+   if the caller holds at least one of `actions` on that pair, else `403`. The check is
+   **exact-match on `(companyId, resourceId)` — there is no wildcard**, and `companyId` is
+   load-bearing.
 
-> `roles` WITHOUT `auth` is a misconfiguration: no identity → fails closed (every request
-> `403`, logged loudly at boot). The resource-scoped check (`acl-can-user-do`) is NOT run by
-> the gateway — it lives on the target microservice.
+> `actions` WITHOUT `auth` is a misconfiguration: no identity → fails closed (every request
+> `403`, logged loudly at boot).
 
 ## Status mapping
 
@@ -109,9 +114,10 @@ For every request the gateway runs `processAuthData` (best-effort), then:
 ## Required wiring to flag
 
 - If `parseRaw: true` → bootstrap with `NestFactory.create(AppModule, { rawBody: true })`.
-- If `roles` is used → an `IAclRoleService` must be registered via `RLB_GTW_ACL_ROLE_SERVICE`
-  in `ProxyModule.forRootAsync({ providers: [{ provide: RLB_GTW_ACL_ROLE_SERVICE, useExisting: AclService }] })`.
-  If a path declares `roles` and the service is NOT registered → request DENIED (`403`) +
+- If `actions` is used → an `IAclRoleService` (`checkAction`) must be registered via
+  `RLB_GTW_ACL_ROLE_SERVICE` in
+  `ProxyModule.forRootAsync({ providers: [{ provide: RLB_GTW_ACL_ROLE_SERVICE, useExisting: AclService }] })`.
+  If a path declares `actions` and the service is NOT registered → request DENIED (`403`) +
   error logged. The auth-provider needs a `uidClaim` (+ `headerPrefix`) to resolve the userId.
 - Forwarded auth claims reach the handler as prefixed/uppercased headers
   (e.g. `X-GTW-AUTH-USERID`) — read them with `@BrokerParam('header', ...)`. Request headers

package/schematics/nest-add/files/skills/rlb-amqp-add-ws-event/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rlb-amqp-add-ws-event
-description: Add a secure WebSocket event (or HTTP webhook) to the @open-rlb/nestjs-amqp gateway by adding a gateway.events[] entry. Use when the user wants to push broker messages to connected WebSocket clients or to a webhook, with authentication (token in subprotocol), per-event roles/ACL, and per-user scoping to avoid leaking other users' data. Generates the YAML event fragment plus the exchange/queue and ws options, and flags the security wiring.
+description: Add a secure WebSocket event (or HTTP webhook) to the @open-rlb/nestjs-amqp gateway by adding a gateway.events[] entry. Use when the user wants to push broker messages to connected WebSocket clients or to a webhook, with authentication (token in subprotocol), per-event actions/ACL, and per-user scoping to avoid leaking other users' data. Generates the YAML event fragment plus the exchange/queue and ws options, and flags the security wiring.
 ---
 
 # Add a WebSocket / webhook event (gateway.events[])
@@ -27,14 +27,15 @@ each message out to the connected clients of EVERY gateway instance. Secure it b
     required to subscribe.
   - `requireAuth: false` → makes `auth` optional (anonymous allowed; claims mapped if a token
     is present — handy with `scopeClaim`). Defaults to `true` when `auth` is set.
-  - `roles: [...]` → ACL check (needs `IAclRoleService`); requires `auth` for the identity.
+  - `actions: [...]` → ACL action check via `IAclRoleService.checkAction` (needs `IAclRoleService`);
+    requires `auth` for the identity. WS events gate **resource-agnostically** (both ids absent).
   - `scopeClaim` + `payloadKey` → per-user isolation: a client only receives messages where
     `payload[payloadKey] === claims[scopeClaim]`. `scopeClaim` is the MAPPED claim
     (with `headerPrefix`, e.g. `X-GTW-AUTH-USERID`). Without `payloadKey` it denies all
     (gotcha 16). With `auth` but no `scopeClaim`/`payloadKey`, every authorized subscriber
     gets ALL messages (warned at boot).
 
-> Auth/roles/scope are declared PER-EVENT. `gateway.ws` only holds connection-level limits,
+> Auth/actions/scope are declared PER-EVENT. `gateway.ws` only holds connection-level limits,
 > heartbeat, origin allowlist and message-size cap (no auth fields). Different events may use
 > different providers.
 
@@ -57,7 +58,7 @@ gateway:
       routingKey: orders.#
       auth: gateway-jwks                # verifies token + maps claims for this event
       requireAuth: true                 # default true when auth is set; false → optional
-      roles: [orders.read]              # optional → needs IAclRoleService
+      actions: [orders.read]            # optional → needs IAclRoleService (checkAction); resource-agnostic for WS
       scopeClaim: X-GTW-AUTH-USERID     # optional per-user scoping (MAPPED claim)
       payloadKey: userId                # message field compared to scopeClaim
 
@@ -89,8 +90,8 @@ broker:
   `sample/config-sample/gateway-in-memory/src/main.ts`).
 - `events[].auth` must reference a `jwt`/`jwks` provider; subscribing without a valid token
   yields `{ topic:'onError', data:{ event, error:'unauthorized' } }` (unless `requireAuth:false`).
-  A failed role check yields `error:'forbidden'`.
-- `roles` → `IAclRoleService` via `RLB_GTW_ACL_ROLE_SERVICE` in
+  A failed action check yields `error:'forbidden'`.
+- `actions` → `IAclRoleService` (`checkAction`) via `RLB_GTW_ACL_ROLE_SERVICE` in
   `ProxyModule.forRootAsync({ providers: [...] })` (gotcha 15).
 - Do NOT add a fixed durable queue for the event — the lib creates a per-instance exclusive
   ephemeral auto-delete queue for fan-out (gotcha 17).

package/schematics/nest-add/files/skills/rlb-amqp-gateway-admin/SKILL.md

@@ -43,7 +43,21 @@ GatewayAdminModule.forRoot([
 
 Use `forRootAsync` to resolve the **consumer-side** `routeDiscovery { exchange, queue }`
 from config (see Route auto-discovery). Exports `GatewayPathService`,
-`GatewayAuthService`, `GatewayMetricsService`.
+`GatewayAuthService`, `GatewayMetricsService`, `GatewayMetricsRollupService`,
+`GatewayHealthService`, `GatewayRetentionService`.
+
+**Options also carry `retentionDays`** (default `90` ≈ 3 months; `0`/negative disables) **and
+`rollupRetentionDays`** (default `365` ≈ 1 year; `0`/negative disables rollups). A daily
+`GatewayRetentionService` job prunes the route journal + raw metric points (`retentionDays`, via
+`prune`/`prunePoints`) and the hourly rollups (`rollupRetentionDays`, via `pruneRollups`). An hourly
+`GatewayMetricsRollupService` downsamples the previous hour's raw points into persisted
+`HttpMetricRollup` rows (`recordRollups`) so long-term trends survive raw-point pruning;
+`gw-metrics-rollups` reads them back via `rollupSeries`.
+
+**New repo contract methods consumers must implement:** every `*Repository.search(q?, page?, limit?)`
+now returns `Promise<PaginationModel<T>>` (not a bare array); `RouteSyncLogRepository.query(filter,
+page?, limit?)` backs `gw-route-log-search`; `RouteSyncLogRepository.prune` + `HttpMetricRepository.prunePoints`
+back retention.
 
 ## Broker topic + queue (required)
 
@@ -88,10 +102,13 @@ auth/ACL resources. `create` rejects a `(method, path)` collision (409).
 | --- | --- | --- | --- | --- |
 | POST   | `/admin/paths`        | `gw-path-create` | body  | needs `name,method,path,topic`; 409 on collision |
 | GET    | `/admin/paths`        | `gw-path-list`   | query | `?page=&limit=` |
+| GET    | `/admin/paths/search` | `gw-path-search` | query | free-text → `PaginationModel<StoredHttpPath>`; `?q=&page=&limit=` |
 | GET    | `/admin/paths/export` | `gw-path-export` | query | enabled, ordered; used by `loadConfig.paths` |
 | PUT    | `/admin/paths`        | `gw-path-update` | body  | needs `id`; re-checks collisions |
 | GET    | `/admin/paths/get`    | `gw-path-get`    | query | `?id=` |
 | DELETE | `/admin/paths`        | `gw-path-delete` | body  | `{ id }` |
+| GET    | `/admin/route-log`    | `gw-route-log-list`   | query | route journal (who changed what); `?limit=` |
+| GET    | `/admin/route-log/search` | `gw-route-log-search` | query | filtered + paginated journal → `PaginationModel<RouteSyncLogEntry>`; `?actor=&service=&event=&routeKey=&from=&to=&page=&limit=` |
 
 ## Auth-provider management — `gw-auth-*` (name-keyed PUT-upsert)
 
@@ -104,6 +121,7 @@ DB-stored providers, ON TOP of the static `auth-providers[]` in YAML.
 | PUT    | `/admin/auth`     | `gw-auth-update` | body  | upsert by name; `{ name, type, ... }` |
 | GET    | `/admin/auth/get` | `gw-auth-get`    | query | `?name=` |
 | DELETE | `/admin/auth`     | `gw-auth-delete` | body  | `{ name }` |
+| GET    | `/admin/auth/search` | `gw-auth-search` | query | free-text → `PaginationModel<StoredAuthProvider>`; `?q=&page=&limit=` |
 
 `gw-auth-export` (dump all enabled) also exists; not in the sample YAML.
 
@@ -111,12 +129,30 @@ DB-stored providers, ON TOP of the static `auth-providers[]` in YAML.
 
 | Method | Path | action | mode | dataSource | Returns |
 | --- | --- | --- | --- | --- | --- |
-| GET  | `/admin/metrics`        | `gw-metrics-get`    | rpc   | query | counters/route (`count,errorCount,avgDurationMs`); `?route=` |
-| GET  | `/admin/metrics/series` | `gw-metrics-series` | rpc   | query | buckets: `?bucketMs=60000&from=&to=&method=&route=&name=` |
-| GET  | `/admin/metrics/points` | `gw-metrics-points` | rpc   | query | raw points newest-first: `?method=&route=&from=&to=&limit=` |
-| POST | `/admin/metrics/track`  | `gw-metrics-track`  | event | body  | fire-and-forget sink (wired via `gateway.metrics`) |
+| GET  | `/admin/metrics`            | `gw-metrics-get`        | rpc   | query | counters/route (`count,errorCount,avgDurationMs,errorRate,lastErrorCode`); `?route=` |
+| GET  | `/admin/metrics/series`     | `gw-metrics-series`     | rpc   | query | enriched buckets w/ `p50/p95/p99`+`byStatus`: `?bucketMs=60000&from=&to=&method=&route=&name=` |
+| GET  | `/admin/metrics/points`     | `gw-metrics-points`     | rpc   | query | raw points (incl. error `code`) newest-first: `?method=&route=&from=&to=&limit=` |
+| GET  | `/admin/metrics/summary`    | `gw-metrics-summary`    | rpc   | query | overview `MetricSummary` (totals,errorRate,p50/95/99,byStatus,top-N): `?from=&to=&method=&route=&name=&topN=10` |
+| GET  | `/admin/metrics/prometheus` | `gw-metrics-prometheus` | rpc   | query | Prometheus text exposition of counters (`text/plain`) |
+| GET  | `/admin/metrics/rollups`    | `gw-metrics-rollups`    | rpc   | query | hourly rollups (`HttpMetricRollup[]`, survive retention): `?from=&to=&method=&route=` |
+| POST | `/admin/metrics/track`      | `gw-metrics-track`      | event | body  | fire-and-forget sink (wired via `gateway.metrics`) |
+
+`series`/`summary` are computed **app-side from raw points** (latency percentiles are exact); the
+counters stay O(1) per route. `prometheus` needs the route's `headers: { Content-Type: text/plain }`.
+
+`gw-health` is a **readiness** probe (NOT a metrics dump). Returns
+`{ status: 'up'|'down', broker: { status, detail? }, dependencies: { <name>: { status, detail? } } }`;
+`status` is `'down'` if the broker OR any dependency is down. The broker (AmqpConnection) is checked
+built-in; DB/redis/external checks are **consumer-supplied** via `RLB_GW_HEALTH_INDICATORS` (array of
+`GatewayHealthIndicator { name; check(): Promise<{status:'up'|'down', detail?}> }`, both exported from
+`@open-rlb/nestjs-amqp`). The HTTP response is **always 200** (the gateway forwards an rpc result,
+can't set 503) — readiness must inspect `status`.
 
-`gw-health` → `{ status: 'ok' }`, a real 200 liveness probe (NOT a metrics dump):
+```ts
+{ provide: RLB_GW_HEALTH_INDICATORS, useValue: [
+  { name: 'database', check: async () => ({ status: 'up' }) },
+] satisfies GatewayHealthIndicator[] }
+```
 
 ```yaml
 - name: health
@@ -203,7 +239,7 @@ routes over the same action can publish with different auth — a route with no
 
 ```ts
 @BrokerHTTP('GET', '/admin/bookings/:id', 'params', { name: 'admin-get-booking' })
-@BrokerAuth('admin-jwks', undefined, ['admin'], 'admin-get-booking')  // pairs by httpName
+@BrokerAuth('admin-jwks', undefined, ['booking.admin'], 'admin-get-booking')  // 3rd param = ACL actions; pairs by httpName
 ```
 
 ### Consumer (gateway ← microservice) — `GatewayAdminModule` `routeDiscovery`
@@ -212,8 +248,12 @@ Wired by `GatewayAdminModule` (NOT YAML). Asserts the fanout exchange, subscribe
 to the durable queue (competing consumers), then per manifest: diffs vs DB scoped
 to the publishing service, applies only changes (insert/update; soft-disable stale
 to `enabled:false`; skip collisions — existing owner keeps `(method,path)`),
-journals every event via `RouteSyncLogRepository`, and publishes `gw-reload` when
-anything changed. Never throws (acks; no poison loop).
+journals every event via `RouteSyncLogRepository` (each row has `actor:'system'`;
+`skipped` rows mark user-modified routes left untouched; `updated` rows carry a
+`changes` per-field diff like `actions: [+x, -y]`), and publishes `gw-reload` when
+anything changed. Never throws (acks; no poison loop). Stored routes carry `source`
+(`'microservice'|'user'`) and `modified`; user CRUD (`gw-path-*`) is audited too —
+`actor`=`X-GTW-AUTH-USERID` (else `'unknown'`), event `created`/`updated`/`deleted`.
 
 ```ts
 GatewayAdminModule.forRootAsync({

package/schematics/nest-add/files/skills/rlb-amqp-scaffold/SKILL.md

@@ -277,10 +277,10 @@ export class AppService {
 }
 ```
 
-Add auth with `@BrokerAuth(authName, allowAnonymous?, roles?, httpName?)` — decoupled from
-`@BrokerHTTP`. With one `@BrokerHTTP` it auto-pairs (no `httpName` needed); with multiple,
-each `@BrokerHTTP` sets a `name` and each `@BrokerAuth` targets it via `httpName`. A route
-with no `@BrokerAuth` is public.
+Add auth with `@BrokerAuth(authName, allowAnonymous?, actions?, httpName?)` — decoupled from
+`@BrokerHTTP` (3rd param is ACL action names). With one `@BrokerHTTP` it auto-pairs (no
+`httpName` needed); with multiple, each `@BrokerHTTP` sets a `name` and each `@BrokerAuth`
+targets it via `httpName`. A route with no `@BrokerAuth` is public.
 
 ## Verify
 - topic/queue/exchange names line up across `broker`/`topics`/paths (gotchas 5–7);