docs: add mqtt connection type design

docs/plans/2026-02-23-mqtt-connection-type-design.md

@@ -0,0 +1,93 @@
+# MQTT Connection Type Port Design
+
+## Goal
+Port MQTT-related connection type parity from Go into the .NET server for two scoped areas:
+1. JWT `allowed_connection_types` behavior for `MQTT` / `MQTT_WS` (plus existing known types).
+2. `/connz` filtering by `mqtt_client`.
+
+## Scope
+- In scope:
+  - JWT allowed connection type normalization and enforcement semantics.
+  - `/connz?mqtt_client=` option parsing and filtering.
+  - Unit/integration tests for new and updated behavior.
+  - `differences.md` updates after implementation is verified.
+- Out of scope:
+  - Full MQTT transport implementation.
+  - WebSocket transport implementation.
+  - Leaf/route/gateway transport plumbing.
+
+## Architecture
+- Add an auth-facing connection-type model that can be passed through `ClientAuthContext`.
+- Implement Go-style allowed connection type conversion and matching in `JwtAuthenticator`:
+  - normalize input to uppercase.
+  - retain recognized types.
+  - collect unknown types as non-fatal if at least one valid type remains.
+  - reject when only unknown types are present.
+  - enforce current connection type against the resulting allowed set.
+- Extend connz monitoring options to parse `mqtt_client` and apply exact-match filtering before sort/pagination.
+
+## Components
+- `src/NATS.Server/Auth/IAuthenticator.cs`
+  - Extend `ClientAuthContext` with a connection-type value.
+- `src/NATS.Server/Auth/Jwt/JwtConnectionTypes.cs` (new)
+  - Canonical constants for known connection types:
+    - `STANDARD`, `WEBSOCKET`, `LEAFNODE`, `LEAFNODE_WS`, `MQTT`, `MQTT_WS`, `INPROCESS`.
+  - Helper(s) for normalization and validation behavior.
+- `src/NATS.Server/Auth/JwtAuthenticator.cs`
+  - Evaluate `userClaims.Nats?.AllowedConnectionTypes` using Go-compatible semantics.
+  - Enforce against current `ClientAuthContext.ConnectionType`.
+- `src/NATS.Server/NatsClient.cs`
+  - Populate auth context connection type (currently `STANDARD`).
+- `src/NATS.Server/Monitoring/Connz.cs`
+  - Add `MqttClient` to `ConnzOptions` with JSON field `mqtt_client`.
+- `src/NATS.Server/Monitoring/ConnzHandler.cs`
+  - Parse `mqtt_client` query param.
+  - Filter connection list by exact `MqttClient` match when provided.
+- `src/NATS.Server/Monitoring/ClosedClient.cs`
+  - Add `MqttClient` field to closed snapshots.
+- `src/NATS.Server/NatsServer.cs`
+  - Persist `MqttClient` into `ClosedClient` snapshot (empty for now).
+
+## Data Flow
+1. Client sends `CONNECT`.
+2. `NatsClient.ProcessConnectAsync` builds `ClientAuthContext` with `ConnectionType=STANDARD`.
+3. `AuthService` invokes `JwtAuthenticator` for JWT-based auth.
+4. `JwtAuthenticator`:
+   - converts `allowed_connection_types` to valid/unknown buckets.
+   - rejects unknown-only lists.
+   - enforces connection-type membership when valid list is non-empty.
+5. Monitoring request `/connz`:
+   - `ConnzHandler.ParseQueryParams` reads `mqtt_client`.
+   - open/closed conn rows are materialized.
+   - rows are filtered on exact `MqttClient` when filter is present.
+   - sorting and pagination run on filtered results.
+
+## Error Handling and Compatibility
+- Auth failures remain non-throwing (`Authenticate` returns `null`).
+- Unknown connection type tokens in JWT are tolerated only when at least one known allowed type remains.
+- Unknown-only allowed lists are rejected to avoid unintended allow-all behavior.
+- `mqtt_client` query parsing is lenient and string-based; empty filter means no filter.
+- Existing JSON schema compatibility is preserved.
+
+## Current Runtime Limitation (Explicit)
+- MQTT transport is not implemented yet in this repository.
+- Runtime connection type currently resolves to `STANDARD` in auth context.
+- `mqtt_client` values remain empty until MQTT path populates them.
+
+## Testing Strategy
+- `tests/NATS.Server.Tests/JwtAuthenticatorTests.cs`
+  - allow `STANDARD` for current client context.
+  - reject `MQTT` for current client context.
+  - allow mixed known+unknown when current type is known allowed.
+  - reject unknown-only list.
+  - validate case normalization behavior.
+- `tests/NATS.Server.Tests/MonitorTests.cs`
+  - `/connz?mqtt_client=<id>` returns matching connections only.
+  - `/connz?state=closed&mqtt_client=<id>` filters closed snapshots.
+  - non-existing ID yields empty connection set.
+
+## Success Criteria
+- JWT `allowed_connection_types` behavior matches Go semantics for known/unknown mixing and unknown-only rejection.
+- `/connz` supports exact `mqtt_client` filtering for open and closed sets.
+- Added tests pass.
+- `differences.md` accurately reflects implemented parity.