@open-rlb/nestjs-amqp 2.0.3 → 2.0.5

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

@@ -1,104 +1,145 @@
 # Gotchas — bug-prone cases checklist
 
-Scan this before adding/changing a topic, queue, exchange, action, route, auth provider
-or WS event. Each item is a real failure mode in this codebase.
+Scan this before adding/changing a topic, queue, exchange, action, route, auth provider,
+WS event, or route-discovery wiring. Each item is a real failure mode in this codebase.
+Ported from `docs/gotchas.md` (re-verified against post-2.0.5 code).
 
 ## Decorators & handlers
 1. **No destructuring in `@BrokerAction` parameters.** Param→message mapping parses the
-   function source with a regex (`getParamNames`). `fn({a,b})` misaligns indices. Use flat
-   params.
+   function source with a regex (`getParamNames`). `fn({a,b})` misaligns indices → params
+   arrive `undefined`. Use flat params + an explicit `@BrokerParam` name on each.
 2. **Avoid default parameter values.** Only a basic `= value` strip exists
    (`removeDefaultsFromParams`); complex defaults misalign mapping. Always pass an explicit
    `name` to `@BrokerParam`.
-3. **`(topic, action)` must be unique.** All `@BrokerAction` of a topic share ONE
-   consumer/queue, dispatched by `action`. A duplicate `(topic, action)` overwrites the
-   previous one silently.
+3. **`(topic, action)` must be unique.** All `@BrokerAction` of a topic share ONE consumer/queue,
+   dispatched by `action`. A duplicate `(topic, action)` overwrites the previous one silently —
+   no error, the old handler just stops being called.
 4. **Forwarded headers are UPPERCASE + prefixed.** Read `@BrokerParam('header',
-   'X-GTW-AUTH-USERID')`, not `'userId'`.
+   'X-GTW-AUTH-USERID')`, not `'userId'`. The exact name = provider `headerPrefix` + `uidClaim`.
+5. **`handle`/`broadcast` handlers must return `void`.** A return value logs
+   `Subscribe handlers should only return void`. Only `rpc` handlers return data.
+6. **One method, multiple `@BrokerAction`s:** any `@BrokerHTTP` / `@BrokerAuth` on that method
+   MUST name its `action` to pair deterministically — decorator order is never used.
 
 ## Topic ↔ queue ↔ exchange wiring
-5. **The topic `name` must match everywhere**: `@BrokerAction`, `topics[].name`,
+7. **The topic `name` must match everywhere**: `@BrokerAction`, `topics[].name`,
    `requestData`/`publishMessage`, `gateway.paths[].topic` / `events[]`. Typo →
    `Topic X not found in configuration`.
-6. **`mode: rpc`/`handle` need `topics[].queue` in `broker.queues[]`**, and that queue's
+8. **`mode: rpc`/`handle` need `topics[].queue` in `broker.queues[]`**, and that queue's
    `exchange` in `broker.exchanges[]`. In `handle` a missing queue throws NPE at boot
    (`queue.exchange`).
-7. **Exchange `type: topic` → queue MUST have `routingKey`**, else boot throws
-   `Queue ... has no routing key`.
-8. **`broadcast` + WebSocket gateway require `connection_name`** (`clientProperties`), else
-   throw.
+9. **Exchange `type: topic` → queue MUST have `routingKey`**, else boot throws
+   `Queue ... has no routing key`. (The samples use a `direct` exchange with matching keys.)
+10. **The gateway can only forward to topics it declares.** Route auto-discovery teaches the
+    gateway the HTTP route, NOT how to reach the microservice's broker topic. That topic (+ its
+    queue/exchange) must ALSO exist in the **gateway's own** `broker` config, or the forwarded
+    request fails with `Topic ... not found in configuration`.
+
+## connection_name (broadcast / WebSocket / route-discovery)
+11. **`broadcast` + WebSocket require `connection_name`** (`clientProperties.connection_name`,
+    or `broker.routeDiscovery.serviceName` which fills it when unset), else throw at boot.
+12. **Every instance needs a DISTINCT `connection_name`.** Sharing it makes RabbitMQ treat the
+    per-instance queues as one consumer group and **round-robin** broadcast/WS messages — reloads
+    land on "every other" instance, WS clients miss events delivered to the other one.
 
 ## RPC / timeout / errors
-9. **RPC reply routing**: `requestData` resolves `replyTo` from `broker.replyQueues[exchange]`;
-   absent → RabbitMQ direct-reply-to. Wrong exchange key in `replyQueues` → no reply → timeout.
-10. **Handler exceptions don't throw on the consumer**: returned as `{success:false,error}`;
-    `requestData` re-throws to the caller. Gateway status derives from `error.name` — give
-    errors a meaningful `name`.
-11. **Default RPC timeout 10s** (or `broker.defaultRpcTimeout`). Set `timeout` per path /
-    per `requestData` call for slow RPCs.
+13. **Wrong `replyQueues` key → silent timeout.** `requestData` resolves `replyTo` from
+    `broker.replyQueues[exchange]`; absent → RabbitMQ direct-reply-to. Wrong exchange key → no
+    reply routed back → the call just times out.
+14. **Handler exceptions don't crash the consumer.** Returned as `{success:false,error}`;
+    `requestData` re-throws on the caller side. Gateway HTTP status derives from `error.name` —
+    give errors a meaningful `name` (`BadRequestError`, `NotFoundError`, `ConflictError`,
+    `ForbiddenError`, `UnauthorizedError`); anything unrecognized → 500.
+15. **Default RPC timeout 10s** (`broker.defaultRpcTimeout`). Override per route (`paths[].timeout`)
+    or per `requestData` call for slow RPCs.
 
 ## Gateway HTTP
-12. **`parseRaw: true` needs `NestFactory.create(AppModule, { rawBody: true })`** or `$raw`
-    is `undefined`.
-13. **Route params win over body/query** (re-applied last). Watch key collisions (`:id`
-    vs `body.id`).
-14. **Uploads are in `$files`** (multer `.any()`); buffers are converted to binary strings —
-    handle re-encoding carefully on the consumer side.
+16. **Boolean RPCs return `200` with `true`/`false`, not `204`.** A *defined* result — including
+    falsy `false`/`0`/`""` — is real content, sent as `200` + JSON. Only `null`/`undefined`
+    collapses to `204`. So `GET /acl/check?...` answers `200 false` for "no" — don't treat any
+    2xx as "allowed", read the body. (The old "always 204" bug is fixed.)
+17. **`parseRaw: true` needs `NestFactory.create(AppModule, { rawBody: true })`** or `$raw` is
+    `undefined`.
+18. **Route params win over body/query** (merged in last). Watch key collisions (`:id` vs `body.id`).
+19. **Uploads live in `$files`** (multer `.any()`); buffers are converted to **binary strings** —
+    re-encode carefully on the consumer (`Buffer.from(str, 'binary')`).
+20. **`/health` is a tiny liveness probe.** Action `gw-health` → `{ status: 'ok' }` (a real 200),
+    NOT a metrics dump. Use `/admin/metrics*` (`gw-metrics-*`) for metrics.
 
 ## Auth / ACL
-15. **`roles` on an HTTP path require an `IAclRoleService`** registered via
-    `RLB_GTW_ACL_ROLE_SERVICE` in `ProxyModule.forRootAsync({ providers: [...] })`. The
-    gateway check is **role-based** (`canUserDoGtw(path.roles, userId)`): `path.roles` lists
-    ROLE NAMES and the user passes if they hold AT LEAST ONE (resource-agnostic primary
-    filter). The provider only needs `uidClaim` (+ `headerPrefix`) to extract the userId —
-    no topic/action.
-16. **Two role-based ACL checks** on `rlb-acl` (both cached, inputs = userId + roles only):
-    `acl-can-user-do-gtw` → `canUserDoGtw(roles, userId)` (gateway primary filter, OR,
-    resource-agnostic) and `acl-can-user-do` → `canUserDo(roles, userId, resourceId)`
-    (**ms-side**; a global grant OR a grant on that resource satisfies it — the resource is
-    known only to the target ms).
-17. **Auth-providers + gateway config are passed to `ProxyModule`** (`authOptions` /
-    `gatewayOptions`), not `BrokerModule`. `BrokerModule` owns only `options`/`topics`/`appOptions`.
+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
+    `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`).
+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.
+28. **Auth & gateway config go to `ProxyModule`** (`authOptions` / `gatewayOptions`), not
+    `BrokerModule`. `BrokerModule` owns only `options` / `topics` / `appOptions`.
 
-## WebSocket
-16. **Auth is per-event, not global.** `events[].auth` names the provider that verifies the
-    connection token AND maps its claims for THAT event (at subscribe time, memoized per
-    provider). `scopeClaim` references the MAPPED claim (with `headerPrefix`, e.g.
-    `X-GTW-AUTH-USERID`), not the raw token claim. `payloadKey` is the event-payload field.
-    `scopeClaim` without `payloadKey` denies everything (safe default). `requireAuth: false`
-    on an event makes `auth` optional (anon allowed, claims mapped if a token is present).
-    `gateway.ws` only carries connection-level limits/heartbeat — no auth fields.
-17. **Don't use a fixed durable queue for WS events.** The lib creates a per-instance
-    exclusive ephemeral queue for fan-out; a shared queue makes instances compete and clients
-    on one instance miss messages.
-18. **Token transport is the subprotocol**: `new WebSocket(url, [token])`. Browsers can't set
-    custom handshake headers.
+## Auth providers (hardening)
+29. **JWKS verifies TLS by default.** `httpsAllowUnauthorized: true` only for self-signed dev issuers.
+30. **`algorithms` is REQUIRED for `jwt`/`jwks`.** Omitting denies verification (algorithm-confusion
+    guard). For `jwks` only asymmetric algs are allowed (`RS*`/`ES*`/`PS*`); `HS*`/`none` rejected.
+31. **Define `jwtMap` or NO claims are forwarded.** Without it the token is still accepted
+    (`success:true`) but no identity headers go downstream — fail-safe, not a leak. Declare it to
+    emit `X-GTW-AUTH-USERID` and friends.
+32. **`str-compare`/`basic` PASS THROUGH when their secret is unset — by design.** A `str-compare`
+    with no `secret`, or a `basic` with no `clientSecret`, authenticates EVERY request (effectively
+    open/disabled). Set the secret to enforce it.
+33. **Credential `mechanism` must be `PLAIN` | `EXTERNAL` | `AMQPLAIN`** (case-insensitive). Unknown
+    value leaves SASL `response` unset → AMQP auth fails.
 
-## Publish / event
-19. **`publishMessage` is `async` — `await` it** for the publisher-confirm guarantee and to
-    catch failures. Un-awaited = fire-and-forget without guarantee.
-20. **`handle`/`broadcast` handlers must return `void`**; a return value logs
-    `Subscribe handlers should only return void`.
+## WebSocket
+34. **Auth is per-event, not global.** `events[].auth` names the provider that verifies the
+    connection token AND maps its claims for THAT event (memoized per provider at subscribe). `scopeClaim`
+    references the MAPPED claim (prefixed, e.g. `X-GTW-AUTH-USERID`), `payloadKey` is the payload
+    field. **`scopeClaim` without `payloadKey` denies everything** (safe default). `requireAuth:false`
+    makes `auth` optional (anon allowed; claims mapped if a token is present). `gateway.ws` carries
+    only connection-level limits/heartbeat — no auth fields.
+35. **Don't bind a WS event to a fixed durable queue.** The lib creates a per-instance exclusive
+    ephemeral queue for fan-out; a shared/durable queue makes instances compete and clients on one
+    instance miss messages delivered to another.
+36. **Token rides in the subprotocol**: `new WebSocket(url, [token])` (browsers can't set handshake
+    headers). The session is bounded by the JWT `exp` — closed with `1008` on expiry, nothing
+    delivered afterward. Long-lived clients need token refresh + reconnect.
+37. **Set `gateway.ws.allowedOrigins`** to reject cross-site handshakes; omitted → all Origins
+    accepted (logged at boot). `maxMessageBytes` (default 16384) drops oversized client frames.
 
-## TLS / credentials / provider hardening
-21. **JWKS verifies TLS by default.** `httpsAllowUnauthorized: true` only for self-signed dev
-    issuers.
-22. **Credential `mechanism`**: `PLAIN` | `EXTERNAL` | `AMQPLAIN` (case-insensitive). Unknown
-    value leaves `response` unset → auth fails.
-23. **`algorithms` is REQUIRED for `jwt`/`jwks`.** If omitted, verification is denied
-    (algorithm-confusion guard). For `jwks` only asymmetric algs are allowed (RS*/ES*/PS*);
-    `HS*`/`none` are rejected.
-24. **`str-compare`/`basic` PASS THROUGH when their secret is unset.** A `str-compare`
-    without `secret` or a `basic` without `clientSecret` treats every request as authenticated
-    (provider effectively open/disabled — by design). Set the secret to actually enforce it.
-25. **Define `jwtMap`.** Without it NO claims are forwarded (the token is still accepted,
-    `success:true`): the gateway fails safe instead of leaking the whole payload. Declare it
-    to forward identity headers (e.g. `X-GTW-AUTH-USERID`).
+## Publish / events
+38. **`publishMessage` is `async` — `await` it** for the publisher-confirm guarantee and to catch
+    failures. Un-awaited = fire-and-forget without guarantee. (For an `event`-mode route the gateway
+    awaits the confirm before returning the 2xx — the success status is not optimistic.)
 
-## WebSocket session/transport security
-26. **WS sessions are bounded by the token `exp`.** The connection is closed (`1008`) when the
-    JWT expires; no delivery happens afterward. Long-lived sockets need token refresh +
-    reconnect.
-27. **Set `gateway.ws.allowedOrigins`** to reject cross-site handshakes; if omitted, all
-    Origins are accepted (logged at boot). `maxMessageBytes` (default 16384) drops oversized
-    client frames.
+## Reload & route auto-discovery
+39. **The only reload action is `gw-reload`** (`GW_RELOAD_ACTION`). The control-topic subscriber
+    rebuilds routes ONLY for `gw-reload`; every other message on the control topic is ignored.
+    Seed then reload: `POST /admin/paths` → `POST /admin/reload` (publishes `gw-reload` on
+    `rlb-gateway-control`). No restart. Concurrent reloads are coalesced into one extra pass.
+40. **Route-discovery config is SPLIT; exchange/queue MUST match on both sides.**
+    - **Publisher (microservice):** `broker.routeDiscovery { serviceName, publishOnBoot, exchange?, queue? }`.
+      `serviceName` is required to publish and also fills `connection_name` when unset.
+    - **Consumer (gateway):** `GatewayAdminModule` `routeDiscovery { exchange?, queue? }` (NEST code,
+      no `serviceName` — the gateway only receives).
+    Both default to `exchange: rlb-route-discovery` / `queue: rlb-route-sync`. Override only to
+    namespace per env — but set the SAME values on BOTH sides or manifests never reach the gateway.
+41. **Topic NAMES `rlb-acl` / `rlb-gateway-admin` / `rlb-gateway-control` and all action strings
+    are decorator-bound and NOT configurable.** Only exchange/queue/routingKey and the
+    route-discovery exchange/queue are. The route-sync handler never throws (logs + acks, no poison
+    loop); an empty manifest soft-disables a service's existing routes (and logs a warning).

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

@@ -0,0 +1,185 @@
+---
+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).
+---
+
+# Manage ACL (@open-rlb/nestjs-amqp)
+
+Read first when you need depth:
+- `docs/acl.md` (model, wiring, URL table)
+- `libs/rlb-nestjs-amqp/src/modules/acl/const.ts` (`ACL_ACTIONS`, `ACL_TOPIC`)
+- `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".
+
+## 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**.
+
+## Decorator-bound (NOT configurable)
+
+Topic NAME `rlb-acl` (`ACL_TOPIC`) and every action string are bound in the library —
+reference them literally. The queue / exchange / routingKey that carry the topic ARE yours.
+
+`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`.
+
+> **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.**
+
+## Actions & roles — name-keyed CRUD
+
+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**).
+
+## Grants — dual grant/revoke
+
+One record per `(userId, resourceId)`. Both ops **require `userId` + `roles`**;
+`resourceId` + `companyId` are **optional**.
+
+- `acl-grant` — merges roles into the pair (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`
+  from the forwarded `X-GTW-AUTH-USERID` header; lists accessible resources grouped by
+  `companyId` with resolved actions.
+
+## Nest wiring
+
+Backend — `AclModule.forRoot([bindings], { cache })`. Bind the abstract repo tokens to
+your concrete impls + optional L2 store; second arg carries TTLs. Module is **global**,
+exports `AclService` + `AclCacheService`.
+
+```ts
+import {
+  AclModule, AclActionRepository, AclRoleRepository, AclGrantRepository,
+  RLB_ACL_CACHE_STORE,
+} from '@open-rlb/nestjs-amqp';
+
+AclModule.forRoot(
+  [
+    { provide: AclActionRepository, useClass: MyAclActionRepository },
+    { provide: AclRoleRepository,   useClass: MyAclRoleRepository },
+    { provide: AclGrantRepository,  useClass: MyAclGrantRepository },
+    { provide: RLB_ACL_CACHE_STORE, useClass: MyRedisAclCacheStore }, // OPTIONAL L2 (omit → RAM-only)
+  ],
+  { cache: { ramTtlMs: 30_000, l2TtlSec: 600 } }, // L1 RAM (default 30000) / L2 (default 600s)
+);
+```
+
+Gateway side — let route `roles: [...]` filters run **in-process** (no broker hop) by
+binding the gateway token to the same `AclService`:
+
+```ts
+import { ProxyModule, AclService, RLB_GTW_ACL_ROLE_SERVICE } from '@open-rlb/nestjs-amqp';
+
+ProxyModule.forRoot({
+  providers: [{ provide: RLB_GTW_ACL_ROLE_SERVICE, useExisting: AclService }],
+});
+```
+
+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**.
+
+## YAML — topic + queue (names fixed, transport yours)
+
+```yaml
+broker:
+  queues:
+    - name: rlb-acl          # consumed by the ACL backend handlers
+      exchange: rlb
+      routingKey: rlb-acl
+      createQueueIfNotExists: true
+      options: { durable: true }
+topics:
+  - name: rlb-acl            # ACL_TOPIC — must match exactly
+    mode: rpc
+    queue: rlb-acl
+    exchange: rlb
+    routingKey: rlb-acl
+```
+
+## Gateway paths[] — full ACL table
+
+Every path forwards to topic `rlb-acl`, `mode: rpc`. `name` is a free label; `action` is
+the fixed library string.
+
+| name | method | path | dataSource | action |
+|---|---|---|---|---|
+| acl-action-list | GET | /acl/actions | query | acl-action-list |
+| 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-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-list-resources-by-user | GET | /acl/resources | query | acl-list-resources-by-user (+ `auth:`) |
+
+```yaml
+gateway:
+  mode: gateway
+  paths:
+    - name: acl-role-upsert        # PUT upserts by name. body: { name, actions, description? }
+      method: PUT
+      path: /acl/roles
+      dataSource: body
+      topic: rlb-acl
+      action: acl-role-update
+      mode: rpc
+    - name: acl-grant              # body: { userId, roles, resourceId?, companyId?, friendlyName? }
+      method: POST
+      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
+      method: GET
+      path: /acl/check
+      dataSource: query
+      topic: rlb-acl
+      action: acl-can-user-do-gtw
+      mode: rpc
+    - name: acl-list-resources-by-user   # auth-gated; userId from X-GTW-AUTH-USERID
+      method: GET
+      path: /acl/resources
+      dataSource: query
+      topic: rlb-acl
+      action: acl-list-resources-by-user
+      mode: rpc
+      auth: gateway-jwks
+```
+
+## Verify
+
+- 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`).
+- a check returning `false` is a **200**, not an error.

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

@@ -12,13 +12,17 @@ First, read the shared reference (schema + gotchas):
 - `.claude/skills/rlb-amqp/references/config-schema.md`
 - `.claude/skills/rlb-amqp/references/gotchas.md`
 
+Authoritative source of truth: `docs/broker.md` (decorators + modes) and the runnable
+`sample/config-sample/calculator.ms` (its `src/app.service.ts` + `config/config.yaml`).
+
 Then locate the project's `config.yaml` (commonly `config/config.yaml`) and the service file.
 
 ## Inputs to determine (ask only if not inferable)
 
 - **topic** (logical name), **action** (string), **mode** intended: `rpc` (default) or `event`.
 - Payload fields the method needs, and any forwarded headers (e.g. `X-GTW-AUTH-USERID`).
-- Whether to also expose it over HTTP (if yes, see the `rlb-amqp-add-route` skill) or WS.
+- Whether to also expose it over HTTP — inline via `@BrokerHTTP` (auto-publish to a gateway,
+  see Step 1b) or via a `gateway.paths[]` entry (`rlb-amqp-add-route` skill), or over WS.
 
 ## Step 1 — the handler method
 
@@ -31,7 +35,7 @@ import { BrokerAction, BrokerParam } from '@open-rlb/nestjs-amqp';
 
 @Injectable()
 export class <Domain>ActionService {
-  @BrokerAction('<topic>', '<action>', 'rpc')
+  @BrokerAction('<topic>', '<action>', 'rpc')   // type? = 'rpc' (default) | 'event'
   async <method>(
     @BrokerParam('body', '<field>') field: string,
     @BrokerParam('header', 'X-GTW-AUTH-USERID') userId: string,
@@ -46,6 +50,48 @@ Ensure the service is a provider in a module that NestJS loads (the
 `MetadataScannerService` auto-discovers it at boot). Throwing an error whose `name` maps to
 an HTTP status (e.g. `NotFoundError`) yields the right gateway status.
 
+### `@BrokerAction(topic, action, type?)`
+
+- `topic` must match a `topics:` entry (an `rpc` topic). `action` is the dispatch key.
+- **`(topic, action)` must be unique** across the whole app — all actions of a topic share
+  ONE consumer/queue, dispatched by `action` (gotcha 3).
+- A single method may carry **multiple** `@BrokerAction`s. When it does, any `@BrokerHTTP` /
+  `@BrokerAuth` on that method **must name its `action`** to pair deterministically (decorator
+  order is never used).
+
+### `@BrokerParam(source, name?, pipe?)` — one source per argument
+
+No object destructuring; declare a separate param per field. A param with no `@BrokerParam`
+defaults to `source: 'body'` keyed by its own name. Optional `pipe` is a `PipeTransform`.
+
+| `source` | Resolves to |
+|---|---|
+| `body` | `payload[name ?? paramName]` — a single body field. |
+| `body-full` | the entire `payload` object. |
+| `header` | `headers[name ?? paramName]` — one AMQP/forwarded header (UPPERCASE+prefixed, gotcha 4). |
+| `tag` | the consumer tag of the delivery. |
+| `action` | the dispatched action string. |
+| `topic` | the topic name. |
+
+## Step 1b (optional) — `@BrokerHTTP` for route auto-publish
+
+To expose the same handler over HTTP **without** hand-editing the gateway, stack
+`@BrokerHTTP("METHOD", "/path", dataSource, options?)` on top of the `@BrokerAction`. On boot
+the microservice publishes its `@BrokerHTTP` routes as a manifest to the gateway (route
+auto-discovery), which persists + registers them. This requires `broker.routeDiscovery`
+(see `rlb-amqp` reference / `docs/gateway-admin.md`); the gateway must also declare this
+service's topic so it can forward calls.
+
+```ts
+@BrokerAction('calculator', 'sum')
+@BrokerHTTP('POST', '/calculator/sum', 'body')   // dataSource: body | query | params | ...
+async sum(@BrokerParam('body', 'values') values: number[]) {
+  return values.reduce((a, v) => a + v, 0);
+}
+```
+
+(Pattern taken verbatim from `sample/config-sample/calculator.ms/src/app.service.ts`.)
+
 ## Step 2 — YAML sync (the critical part)
 
 Reconcile `config.yaml` so the topic resolves. Add ONLY what's missing (idempotent):
@@ -85,6 +131,7 @@ single consumer dispatches by `action`.
 - topic-type exchange ⇒ queue has `routingKey` (gotcha 7)
 - `(topic, action)` unique (gotcha 3)
 - header params read the prefixed/uppercased name (gotcha 4)
+- if multiple `@BrokerAction` on one method ⇒ each `@BrokerHTTP`/`@BrokerAuth` names its `action`
 
 ## Step 4 — build
 

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

@@ -7,22 +7,46 @@ description: Expose a broker action over HTTP through the @open-rlb/nestjs-amqp
 
 Read first:
 - `.claude/skills/rlb-amqp/references/config-schema.md` (the `gateway.paths[]` section)
-- `.claude/skills/rlb-amqp/references/gotchas.md` (HTTP + auth items 11–15)
+- `.claude/skills/rlb-amqp/references/gotchas.md` (HTTP + auth items)
+- `docs/gateway.md` is the authority for the `PathDefinition` fields and status mapping.
 
 The target `topic`+`action` should already have a handler (otherwise also run
 `rlb-amqp-add-action`). The route only needs the topic to exist in `topics[]`.
+Canonical example: `sample/config-sample/gateway-in-memory/config/config.yaml`.
 
 ## Decide
 
-- **mode**: `rpc` (return the handler's response) or `event` (202 after publisher confirm,
-  503 on failure).
-- **dataSource**: how to build the payload — `body` | `query` | `params` | `body-query` |
-  `query-body` (see the composition table in the schema).
-- **auth**: an `auth-provider` name; `allowAnonymous: true` to permit unauthenticated access;
-  `roles: [...]` for ACL.
+- **mode**: `rpc` (return the handler's reply) or `event` (publish-and-confirm, no reply).
+- **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.
 - Extras: `timeout` (rpc), `successStatusCode`, `binary`, `redirect`, `parseRaw`, static
   `headers`, `forwardHeaders`.
 
+## PathDefinition fields (all of them)
+
+| Field | Notes |
+| --- | --- |
+| `name` | Unique; used in logs + metrics. |
+| `method` | `GET` `POST` `PUT` `DELETE` `PATCH` … |
+| `path` | Express route, may carry `:params` (e.g. `/users/:id`). |
+| `topic` / `action` | Broker destination. Action strings are decorator-bound on the backend. |
+| `mode` | `rpc` \| `event`. |
+| `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`. |
+| `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`). |
+| `successStatusCode` | Override success status (default 200 rpc / 202 event / 204 empty). |
+| `redirect` | On an `rpc` route, redirect with this status using the reply as the location. |
+| `headers` | Static response headers `{ k: v }`. |
+| `forwardHeaders` | `{ dest: srcHeader }` — copy request headers downstream (prefixed by `gateway.headerPrefix`). |
+
+Uploaded multipart files (any field) are attached as `$files` (buffers → binary strings).
+
 ## YAML fragment
 
 ```yaml
@@ -36,28 +60,67 @@ gateway:
       action: <action>
       mode: rpc                    # or event
       auth: gateway-jwks           # optional
-      roles: [resource.write]      # optional → needs IAclRoleService
+      roles: [resource.write]      # optional → needs RLB_GTW_ACL_ROLE_SERVICE
       timeout: 7000                # rpc only
       successStatusCode: 201
 ```
 
+## The 3-case auth gate
+
+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`);
+   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`.
+
+> `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.
+
+## Status mapping
+
+**`rpc`** reply → status:
+
+| Reply | Status |
+| --- | --- |
+| Defined value (incl. falsy `false` / `0` / `''`) | `200` + body |
+| `null` / `undefined` | `204 No Content` |
+
+> ONLY `null`/`undefined` collapses to `204`. A defined falsy result is real content, so a
+> boolean check route answers `200` with body `false` — not an empty `204`.
+
+**`rpc`** error → status (by error `name`):
+
+| Error name | Status |
+| --- | --- |
+| `BadRequestError`, `InvalidParamsErrror` | `400` |
+| `UnauthorizedError` | `401` |
+| `ForbiddenError` | `403` |
+| `NotFoundError` | `404` |
+| `ConflictError` | `409` |
+| (any other) | `500` |
+
+**`event`** route: successful publish → `successStatusCode || 202`; publish failure → `503`.
+
 ## Required wiring to flag
 
-- If `parseRaw: true` → the app must bootstrap with
-  `NestFactory.create(AppModule, { rawBody: true })` (gotcha 12).
-- If `roles` is used → an `IAclRoleService` must be registered via
-  `RLB_GTW_ACL_ROLE_SERVICE` in `ProxyModule.forRootAsync({ providers: [...] })`. The check
-  is role-based (`canUserDoGtw(path.roles, userId)`): `roles` are ROLE NAMES and the user
-  passes with AT LEAST ONE. The auth-provider only needs `uidClaim` (+ `headerPrefix`) to
-  extract the userId (gotcha 15). For a resource-scoped decision, the target ms calls
-  `canUserDo(roles, userId, resourceId)` (RPC `acl-can-user-do`) itself.
+- 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`) +
+  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', ...)`.
+  (e.g. `X-GTW-AUTH-USERID`) — read them with `@BrokerParam('header', ...)`. Request headers
+  can never override mapped claim headers (anti-spoofing).
 
 ## Verify
 
-- topic exists in `topics[]` and resolves (gotchas 5–7).
-- route-param vs body/query key collisions are intentional (gotcha 13).
+- topic exists in `topics[]` and resolves.
+- route-param vs body/query key collisions are intentional (params always merge in).
 - `npm run build`, then optionally curl the route once the broker is up.
 
 Output the YAML fragment (with parent path), plus any bootstrap/ACL action the user still