@open-rlb/nestjs-amqp 1.0.27 → 2.0.1

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

@@ -0,0 +1,214 @@
+# config.yaml — full schema
+
+Five top-level sections: `app`, `broker`, `topics`, `auth-providers`, `gateway`.
+Loaded by `config/config.loader.ts`. `app`/`broker`/`topics` go to `BrokerModule.forRootAsync`;
+`auth-providers` + `gateway` go to `ProxyModule.forRootAsync` (see the repo `README.md` Quick start).
+
+---
+
+## app
+
+```yaml
+app:
+  port: 3000
+  host: 0.0.0.0
+  environment: development   # development | production — controls error detail exposed by the gateway
+```
+
+`AppConfig` = `{ environment, port?, host? }`. In `production` gateway errors are reduced
+to `{ message, name }`; in `development` the full detail/stack is included.
+
+---
+
+## broker  (RabbitMQConfig)
+
+```yaml
+broker:
+  name: rabbitmq
+  uri: "amqp://user:pass@host:5672/vhost"     # string | string[] (failover)
+  prefetchCount: 10
+  defaultRpcTimeout: 10000                      # ms
+  defaultSubscribeErrorBehavior: ack            # ack | reject | requeue
+  defaultPublishErrorBehavior: reject
+
+  connectionManagerOptions:                     # amqp-connection-manager options
+    heartbeatIntervalInSeconds: 60
+    reconnectTimeInSeconds: 60
+    connectionOptions:
+      clientProperties:
+        connection_name: my-service             # REQUIRED for broadcast + WebSocket gateway
+      credentials:
+        mechanism: PLAIN                         # PLAIN | EXTERNAL | AMQPLAIN (case-insensitive)
+        username: guest
+        password: guest
+
+  exchanges:                                    # RabbitMQExchangeConfig[]
+    - name: users-ex
+      type: direct                               # direct | topic | fanout | headers
+      createExchangeIfNotExists: true            # false → checkExchange (must pre-exist)
+      options: { durable: true, autoDelete: false, internal: false }
+
+  queues:                                       # RabbitMQQueueConfig[]
+    - name: users-rpc-q
+      exchange: users-ex
+      routingKey: users.rpc                       # string | string[]; REQUIRED if exchange type == topic
+      createQueueIfNotExists: true
+      options: { durable: true, exclusive: false, autoDelete: false }
+      consumerTag: my-tag                         # optional, must be unique per channel
+
+  replyQueues:                                  # map exchange → reply queue (RPC responses)
+    users-ex: users-reply-q                       # omit → RabbitMQ direct-reply-to is used
+```
+
+Notes:
+- `exchanges[]` and `queues[]` are asserted/checked once at boot on the default channel.
+- `replyQueues` values are auto-consumed at boot.
+- Queue `options` is amqplib `Options.AssertQueue` (durable, exclusive, autoDelete,
+  messageTtl, deadLetterExchange, maxLength, maxPriority, arguments, ...).
+
+---
+
+## topics  (BrokerTopic[])
+
+A topic maps a logical name to an AMQP path. `mode` decides the semantics.
+
+```yaml
+topics:
+  - name: users-rpc          # logical name (must match @BrokerAction / requestData / gateway)
+    mode: rpc                 # rpc | handle | broadcast | event
+    queue: users-rpc-q        # for rpc/handle: must exist in broker.queues[]
+    exchange: users-ex        # for broadcast/event (direct exchange path)
+    routingKey: users.rpc     # for broadcast/event / topic exchanges
+    toObservable: false       # handle only: route to BrokerService.events$ instead of a handler
+```
+
+| mode        | required fields                                  | notes                                  |
+| ----------- | ------------------------------------------------ | -------------------------------------- |
+| `rpc`       | `name`, `queue` (or `exchange`+`routingKey`)     | request/response + timeout             |
+| `handle`    | `name`, `queue`                                  | simple queue worker                    |
+| `broadcast` | `name`, `exchange`, `routingKey`                 | fanout/topic; needs `connection_name`  |
+| `event`     | `name`, `queue` OR `exchange`+`routingKey`       | fire-and-forget                        |
+
+> A single `@BrokerAction` topic registers ONE consumer; multiple actions on the same
+> topic share it and are dispatched by `action`.
+
+---
+
+## auth-providers  (HandlerAuthConfig[])
+
+```yaml
+auth-providers:
+  - name: gateway-jwks
+    type: jwks                       # jwt | jwks | basic | str-compare | none
+    issuer: https://issuer/realms/x
+    jwksUri: https://issuer/certs    # jwks only
+    secret: s3cr3t                   # jwt / str-compare only
+    audience: my-aud                 # jwt only
+    algorithms: [RS256]
+    httpsAllowUnauthorized: false    # true ONLY for self-signed dev issuers
+    clientId: u                      # basic only
+    clientSecret: p                  # basic only
+    jwtMap: [sub:userId, roles:roles]# tokenClaim:destClaim  (dest is header-prefixed + uppercased)
+    headerPrefix: X-GTW-AUTH-        # prefix of headers propagated to microservices
+    uidClaim: USERID                 # dest used as user id for ACL
+    usernameClaim: USERNAME
+    aclTopic: acl                    # RPC topic queried for roles
+    aclAction: can-user-do
+```
+
+Mapping example: token `{ sub: "u_1" }` + `jwtMap: [sub:userId]` + `headerPrefix: X-GTW-AUTH-`
+→ header `X-GTW-AUTH-USERID = u_1`. Read it in a handler with
+`@BrokerParam('header', 'X-GTW-AUTH-USERID')`.
+
+Types: `jwt` (HS/RS secret), `jwks` (remote keys), `basic` (clientId/clientSecret),
+`str-compare` (static token after `headerPrefix` in Authorization).
+
+Provider notes: `algorithms` is REQUIRED for `jwt`/`jwks` (omit → denied; `jwks` allows only
+RS*/ES*/PS*, rejects HS*/none). `str-compare` without `secret` and `basic` without
+`clientSecret` PASS THROUGH (request treated as authenticated — provider effectively open).
+Define `jwtMap` to avoid forwarding unmapped claims.
+
+---
+
+## gateway  (GatewayConfig)
+
+```yaml
+gateway:
+  mode: gateway
+  headerPrefix: X-GTW-               # prefix for forwarded request headers (forwardHeaders)
+
+  ws:                                # WebSocketGatewayOptions — connection-level only
+    maxConnections: 5000
+    maxSubscriptionsPerClient: 50
+    heartbeatIntervalMs: 30000
+    allowedOrigins: [https://app.example.com]   # Origin allowlist (omit → all accepted)
+    maxMessageBytes: 16384                        # drop oversized client frames (default 16KB)
+    # auth/roles/scope are declared PER-EVENT on events[], not here
+
+  loadConfig:                        # optional remote load via RPC at boot
+    paths:  { topic: gtw.config, action: get-paths }
+    events: { topic: gtw.config, action: get-events }
+
+  paths:   [ ... ]                   # PathDefinition[] (HTTP routes) — see below
+  events:  [ ... ]                   # WebSocketEvent[] (WS / webhook) — see below
+```
+
+### gateway.paths[]  (PathDefinition — HTTP routes)
+
+```yaml
+- name: users-create
+  method: POST              # GET | POST | PUT | DELETE | PATCH
+  path: /users/:tenant?     # Express route, params supported
+  dataSource: body          # body | query | params | body-query | query-body
+  topic: users-rpc
+  action: user.create
+  mode: rpc                 # rpc | event
+  timeout: 7000             # rpc only (ms)
+  auth: gateway-jwks        # auth-provider name
+  allowAnonymous: false     # true → allow even without valid auth
+  roles: [users.create]     # requires IAclRoleService
+  successStatusCode: 201
+  binary: false             # true → response sent as base64-decoded Buffer
+  redirect: 302             # if set → redirect to the URL contained in the reply
+  parseRaw: false           # true → forward raw body as $raw (needs rawBody:true in bootstrap)
+  headers: { Cache-Control: no-store }    # static response headers
+  forwardHeaders: { Tenant: x-tenant }    # request header → forwarded to the microservice
+```
+
+dataSource payload composition:
+
+| value        | payload                          |
+| ------------ | -------------------------------- |
+| `body`       | `{...params, ...body}`           |
+| `query`      | `{...params, ...query}`          |
+| `params`     | `params`                         |
+| `body-query` | `{...params, ...query, ...body}` |
+| `query-body` | `{...params, ...body, ...query}` |
+
+Route params are re-applied last (win on key collisions). Uploads → `$files`, raw → `$raw`.
+Error `name` → HTTP status: BadRequestError/InvalidParamsErrror→400, UnauthorizedError→401,
+ForbiddenError→403, NotFoundError→404, else→500. `mode: event` confirm failure → 503.
+
+### gateway.events[]  (WebSocketEvent — WS / webhook)
+
+```yaml
+- name: orders
+  type: ws                 # ws | http (webhook)
+  exchange: orders-ex
+  routingKey: orders.#
+  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: [orders.read]     # ACL check via IAclRoleService
+  scopeClaim: X-GTW-AUTH-USERID   # forward only messages of this user...
+  payloadKey: userId              # ...where payload.userId === the mapped claim value
+  # type: http only:
+  url: https://hooks.example.com/orders
+  method: POST
+  timeout: 8000
+  headers: { Authorization: "Bearer ..." }
+```
+
+WS client connects with the JWT in the subprotocol: `new WebSocket(url, [token])`. The token
+is verified per-event with `events[].auth`'s provider (memoized per provider per connection).
+Client protocol: `{action:'subscribe'|'unsubscribe', topic, select?}`; inbound messages
+arrive as `{ topic: 'on<Name>', data }`, errors as `{ topic:'onError', data:{event,error} }`.

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

@@ -0,0 +1,95 @@
+# 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.
+
+## 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.
+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.
+4. **Forwarded headers are UPPERCASE + prefixed.** Read `@BrokerParam('header',
+   'X-GTW-AUTH-USERID')`, not `'userId'`.
+
+## Topic ↔ queue ↔ exchange wiring
+5. **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
+   `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.
+
+## 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.
+
+## 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.
+
+## Auth / ACL
+15. **`roles` (HTTP path or WS event) require an `IAclRoleService`** registered via
+    `RLB_GTW_ACL_ROLE_SERVICE` in `ProxyModule.forRootAsync({ providers: [...] })`. The
+    provider must define `aclTopic`, `aclAction`, `uidClaim`, `usernameClaim`, and
+    `uidClaim` must match a `jwtMap` dest. Missing → throw.
+16. **Auth-providers + gateway config are passed 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.
+
+## 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`.
+
+## 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, every token claim is forwarded unmapped (over-exposure).
+
+## 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.

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

@@ -0,0 +1,102 @@
+---
+name: rlb-amqp-add-action
+description: Add or modify a @BrokerAction handler in a @open-rlb/nestjs-amqp microservice AND keep config.yaml in sync. Use whenever the user adds/changes a broker action, RPC method, or event handler, or says the YAML must be updated to match a new @BrokerAction method (topic/queue/exchange, and optionally a gateway route). Generates the decorated method and the exact YAML fragments to add.
+---
+
+# Add a @BrokerAction handler and sync config.yaml
+
+Goal: when a broker handler is added or changed, produce BOTH the decorated method and the
+matching `config.yaml` fragments, with no missing wiring.
+
+First, read the shared reference (schema + gotchas):
+- `.claude/skills/rlb-amqp/references/config-schema.md`
+- `.claude/skills/rlb-amqp/references/gotchas.md`
+
+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.
+
+## Step 1 — the handler method
+
+Add an `@Injectable()` service method. Keep parameters FLAT (no destructuring, no default
+values — see gotchas 1–2). Always pass an explicit `name` to `@BrokerParam`.
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { BrokerAction, BrokerParam } from '@open-rlb/nestjs-amqp';
+
+@Injectable()
+export class <Domain>ActionService {
+  @BrokerAction('<topic>', '<action>', 'rpc')
+  async <method>(
+    @BrokerParam('body', '<field>') field: string,
+    @BrokerParam('header', 'X-GTW-AUTH-USERID') userId: string,
+  ) {
+    // rpc → return a value; event callers ignore it.
+    return { ok: true };
+  }
+}
+```
+
+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.
+
+## Step 2 — YAML sync (the critical part)
+
+Reconcile `config.yaml` so the topic resolves. Add ONLY what's missing (idempotent):
+
+1. **Topic** in `topics[]`:
+   ```yaml
+   - name: <topic>
+     mode: rpc            # or handle/event
+     queue: <topic>-q     # rpc/handle: must reference a queue below
+   ```
+2. **Queue** in `broker.queues[]` (for rpc/handle):
+   ```yaml
+   - name: <topic>-q
+     exchange: <exchange>
+     routingKey: <topic>          # REQUIRED if the exchange is type: topic
+     createQueueIfNotExists: true
+     options: { durable: true }
+   ```
+3. **Exchange** in `broker.exchanges[]` (if not present):
+   ```yaml
+   - name: <exchange>
+     type: direct                 # or topic — then queue.routingKey is mandatory
+     createExchangeIfNotExists: true
+     options: { durable: true }
+   ```
+4. For an **event-publishable** topic (no reply) you can instead use
+   `exchange` + `routingKey` directly on the topic.
+
+If the action is just another action on an EXISTING topic, do NOT add a new
+queue/exchange — only ensure the `(topic, action)` pair is unique (gotcha 3). The topic's
+single consumer dispatches by `action`.
+
+## Step 3 — verify against gotchas
+
+- topic `name` identical in code and YAML (gotcha 5)
+- queue exists and its exchange exists (gotcha 6)
+- topic-type exchange ⇒ queue has `routingKey` (gotcha 7)
+- `(topic, action)` unique (gotcha 3)
+- header params read the prefixed/uppercased name (gotcha 4)
+
+## Step 4 — build
+
+Run `npm run build`. Optionally show the user the RPC vs event call sites:
+
+```ts
+await broker.requestData('<topic>', '<action>', payload, headers);     // waits reply
+await broker.publishMessage('<topic>', '<action>', payload, headers);  // awaits confirm
+```
+
+## Output
+
+Present: (a) the handler diff, (b) the exact YAML fragments to insert (with their parent
+path), (c) a one-line note of any gotcha you had to satisfy. If multiple files/fragments,
+list them so the user can review before applying.

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

@@ -0,0 +1,61 @@
+---
+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.
+---
+
+# Add an HTTP gateway route (gateway.paths[])
+
+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)
+
+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[]`.
+
+## 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.
+- Extras: `timeout` (rpc), `successStatusCode`, `binary`, `redirect`, `parseRaw`, static
+  `headers`, `forwardHeaders`.
+
+## YAML fragment
+
+```yaml
+gateway:
+  paths:
+    - name: <unique-name>
+      method: POST                 # GET | POST | PUT | DELETE | PATCH
+      path: /resource/:id?
+      dataSource: body
+      topic: <topic>
+      action: <action>
+      mode: rpc                    # or event
+      auth: gateway-jwks           # optional
+      roles: [resource.write]      # optional → needs IAclRoleService
+      timeout: 7000                # rpc only
+      successStatusCode: 201
+```
+
+## 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: [...] })`, and the
+  auth-provider must define `aclTopic`/`aclAction`/`uidClaim`/`usernameClaim` (gotcha 15).
+- Forwarded auth claims reach the handler as prefixed/uppercased headers
+  (e.g. `X-GTW-AUTH-USERID`) — read them with `@BrokerParam('header', ...)`.
+
+## Verify
+
+- topic exists in `topics[]` and resolves (gotchas 5–7).
+- route-param vs body/query key collisions are intentional (gotcha 13).
+- `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
+needs to take.

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

@@ -0,0 +1,93 @@
+---
+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.
+---
+
+# Add a WebSocket / webhook event (gateway.events[])
+
+Read first:
+- `.claude/skills/rlb-amqp/references/config-schema.md` (the `gateway.events[]` + `gateway.ws`
+  sections)
+- `.claude/skills/rlb-amqp/references/gotchas.md` (WebSocket items 16–18, ACL item 15)
+
+A WS event subscribes to an exchange/routingKey and fans the messages out to the connected
+clients of EVERY gateway instance. Secure it by default.
+
+## Decide
+
+- **type**: `ws` (push to clients) or `http` (forward each message to a webhook `url`).
+- **source**: `exchange` + `routingKey` (the exchange must exist in `broker.exchanges[]`;
+  `connection_name` must be set — gotcha 8).
+- **security**:
+  - `auth: <provider>` → the provider that verifies the connection token AND maps its claims
+    for THIS event (at subscribe time). When set, a valid token is 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.
+  - `scopeClaim` + `payloadKey` → per-user scoping: 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).
+
+> Auth/roles/scope are declared PER-EVENT. `gateway.ws` only holds connection-level limits
+> and heartbeat (no auth fields). Different events may use different providers.
+
+## YAML fragments
+
+```yaml
+gateway:
+  ws:                                   # connection-level only (optional)
+    maxConnections: 5000
+    maxSubscriptionsPerClient: 50
+    heartbeatIntervalMs: 30000
+
+  events:
+    - name: orders
+      type: ws
+      exchange: orders-ex               # must exist in broker.exchanges[]
+      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
+      scopeClaim: X-GTW-AUTH-USERID     # optional per-user scoping
+      payloadKey: userId
+
+    - name: invoices                    # webhook variant
+      type: http
+      exchange: inv-ex
+      routingKey: inv.#
+      url: https://hooks.example.com/invoices
+      method: POST
+      timeout: 8000
+```
+
+Ensure the exchange exists:
+
+```yaml
+broker:
+  exchanges:
+    - name: orders-ex
+      type: topic
+      createExchangeIfNotExists: true
+      options: { durable: true }
+```
+
+## Required wiring to flag
+
+- The app bootstrap must register the WS adapter:
+  `app.useWebSocketAdapter(new WsAdapter(app))`.
+- `events[].auth` must reference a `jwt`/`jwks` provider; subscribing without a valid token
+  yields `{ topic:'onError', data:{ event, error:'unauthorized' } }` (unless `requireAuth:false`).
+- `roles` → `IAclRoleService` via `RLB_GTW_ACL_ROLE_SERVICE` (gotcha 15).
+- Do NOT add a fixed durable queue for the event — the lib creates a per-instance exclusive
+  queue for fan-out (gotcha 17).
+
+## Client snippet (for docs/testing)
+
+```js
+const ws = new WebSocket('ws://localhost:3000', [token]);   // token in subprotocol
+ws.onopen = () => ws.send(JSON.stringify({ action: 'subscribe', topic: 'orders' }));
+ws.onmessage = (e) => console.log(JSON.parse(e.data)); // { topic:'onOrders', data } | { topic:'onError', ... }
+```
+
+Output the YAML fragments (with parent paths) and the bootstrap/ACL items still required.