@annadata/capacitor-mqtt-quic 0.1.6 → 0.1.7

package/docs/CAPACITOR_MQTT_QUIC_PRODUCTION_PLUGIN.md

@@ -0,0 +1,190 @@
+# Making @annadata/capacitor-mqtt-quic a Production-Ready Plugin
+
+This document describes how the **capacitor-mqtt-quic** plugin is made production-ready so that **anyone can use it directly** (`npm install @annadata/capacitor-mqtt-quic`) and build Android/iOS **without app-side workarounds**.
+
+---
+
+## Start here: Publish a production plugin
+
+**This plugin is production-ready** when Options 1, 2, and 4 below are in place (they are). To **generate and publish** the production plugin, follow the step-by-step checklist:
+
+- **[docs/PRODUCTION_PUBLISH_STEPS.md](./PRODUCTION_PUBLISH_STEPS.md)** — Build native libs, clean, build JS, verify package, bump version, publish to npm.
+
+After publishing, consumers can `npm install @annadata/capacitor-mqtt-quic` and follow the README’s **Production / First-time build** section if they need to run the one-time WolfSSL/ngtcp2 build for Android.
+
+---
+
+## Current Situation
+
+- **Development:** Apps (e.g. annadata-app, test16) may work around the plugin by providing `deps-versions.sh` (pinned WolfSSL/ngtcp2 versions) and/or running setup scripts.
+- **Production / direct use:** A consumer who only runs `npm install` and `ionic cap run android` may hit:
+  - **Android:** CMake fails with "WolfSSL not found" if `android/install/wolfssl-android` (and ngtcp2/nghttp3 installs) are not shipped. Run the one-time `./build-native.sh --android-only` (or ship prebuilts).
+
+---
+
+## TLS backend: WolfSSL on both iOS and Android
+
+**iOS** and **Android** both use **WolfSSL** as the only TLS backend (license/size/QUIC support):
+
+- **iOS:** Podspec ships `libngtcp2_crypto_wolfssl.a` and `libwolfssl.a`; `NGTCP2Bridge.mm` uses `wolfSSL_*` APIs only.
+- **Android:** `android/src/main/cpp/CMakeLists.txt` finds and links WolfSSL (`libwolfssl.a`) and `libngtcp2_crypto_wolfssl.a`. `ngtcp2_jni.cpp` uses `ngtcp2_crypto_wolfssl.h` and `<wolfssl/ssl.h>` (same as iOS).
+
+For the **Android build** you need **WolfSSL** (and nghttp3, ngtcp2 built with WolfSSL) in `android/install/wolfssl-android/<abi>/`, etc. One-time setup: `./build-native.sh --android-only --abi <abi>` (or the individual `build-wolfssl.sh`, `build-nghttp3.sh`, `build-ngtcp2.sh` scripts).
+
+---
+
+## Process to Make the Plugin Complete (Production Setup)
+
+Choose **one** of the approaches below (or combine 1 + 2 for best UX).
+
+---
+
+### Option 1: Ship `deps-versions.sh` in the Plugin (Recommended minimum)
+
+**Goal:** One-time run of the plugin’s own `build-openssl.sh` works without the app providing any file.
+
+**Steps:**
+
+1. **Add `deps-versions.sh` in the plugin repo** (e.g. at repo root, next to `package.json`), with a **pinned QuicTLS commit** that still has the Perl `Configure` script:
+
+   ```bash
+   # deps-versions.sh (in plugin root)
+   export QUICTLS_REPO_URL="${QUICTLS_REPO_URL:-https://github.com/quictls/quictls.git}"
+   export OPENSSL_COMMIT="${OPENSSL_COMMIT:-2cc13b7c86fd76e5b45b5faa4ca365a602f92392}"
+
+   export NGHTTP3_REPO_URL="${NGHTTP3_REPO_URL:-https://github.com/ngtcp2/nghttp3.git}"
+   export NGHTTP3_COMMIT="${NGHTTP3_COMMIT:-78f27c1}"
+   export NGTCP2_REPO_URL="${NGTCP2_REPO_URL:-https://github.com/ngtcp2/ngtcp2.git}"
+   export NGTCP2_COMMIT="${NGTCP2_COMMIT:-3ce3bbead}"
+   ```
+
+2. **Include it in the published package:** in `package.json` add `"deps-versions.sh"` to the `files` array:
+
+   ```json
+   "files": ["dist", "ios", "android", "deps-versions.sh", "AnnadataCapacitorMqttQuic.podspec", "README.md"]
+   ```
+
+3. **Document one-time setup** in the plugin README (see “Consumer instructions” below).
+
+**Result:** Consumers run the plugin’s `build-openssl.sh` once (or your documented script); it sources `deps-versions.sh` from the plugin and uses `OPENSSL_COMMIT`, so the clone has `Configure` and the build succeeds. No app-side keys or copy steps.
+
+---
+
+### Option 2: Change Default Branch in `build-openssl.sh`
+
+**Goal:** Even without `deps-versions.sh`, cloning QuicTLS works (branch still has `Configure`).
+
+**Steps:**
+
+1. In **`android/build-openssl.sh`** (and iOS if applicable), change the default branch from `main` to a branch that still has the Perl Configure script, e.g.:
+
+   ```bash
+   QUICTLS_BRANCH="${QUICTLS_BRANCH:-openssl-3.2}"
+   ```
+
+   (Use the same in iOS `build-openssl.sh` if it uses QuicTLS.)
+
+2. Optionally still ship **Option 1** so that when `deps-versions.sh` is present, pinned commit takes precedence for reproducible builds.
+
+**Result:** If the consumer doesn’t have `deps-versions.sh`, the script still clones a branch that has `Configure` and builds.
+
+---
+
+### Option 3: Ship Prebuilt WolfSSL (wolfssl-android) in the npm Package (Zero-config)
+
+**Goal:** `npm install` + `ionic cap run android` works with **no** run of `build-wolfssl.sh`.
+
+**Steps:**
+
+1. **Build WolfSSL (wolfssl-android) once per ABI** using the plugin’s `build-wolfssl.sh` (or `./build-native.sh --android-only --abi <abi>`), for:
+   - `arm64-v8a`, `armeabi-v7a`, `x86_64` (and `x86` if you support it).
+
+2. **Keep the artifacts** under:
+   - `android/install/wolfssl-android/arm64-v8a/`
+   - `android/install/wolfssl-android/armeabi-v7a/`
+   - `android/install/wolfssl-android/x86_64/`
+   (each with `include/` and `lib/libwolfssl.a`). Also build nghttp3 and ngtcp2 so `android/install/nghttp3-android/<abi>/` and `android/install/ngtcp2-android/<abi>/` exist.
+
+3. **Include them in the published package:**
+   - Do **not** remove `android/install` in `clean:build-artifacts` (so prepack/prepublishOnly do not delete it).
+   - `android` is already in the `files` array, so `android/install/` is published when present.
+
+4. **iOS:** Ship prebuilt libs in `ios/libs/` and `ios/include/` (built with `./build-native.sh --ios-only`); the clean script already keeps these.
+
+**Result:** Consumers get WolfSSL (wolfssl-android) and ngtcp2/nghttp3 with the plugin; Gradle/CMake find them and the app builds without any one-time setup. Trade-off: larger npm package size.
+
+---
+
+### Option 4: Clear Docs and Build-Time Message
+
+**Goal:** When something is missing, the failure is clear and points to a single place.
+
+**Steps:**
+
+1. **README:** Add a short “Production / first-time build” section:
+   - **Android:** Before first `ionic cap run android`, run once (from project root):
+     ```bash
+     cd node_modules/@annadata/capacitor-mqtt-quic && \
+       ./build-native.sh --android-only --abi arm64-v8a && \
+       ./build-native.sh --android-only --abi armeabi-v7a && \
+       ./build-native.sh --android-only --abi x86_64
+     ```
+   - Or add an npm script in your app that runs the above.
+   - Require Android NDK (r25+).
+
+2. **Optional:** In the plugin’s Android CMake or Gradle, if WolfSSL is not found, fail with a message that points to the README (e.g. “WolfSSL not found. Run the one-time setup: …” and link to the plugin README).
+
+**Result:** No change to plugin code, but production users have a single, clear path and no guesswork.
+
+---
+
+## Recommended Combination for Production
+
+- **Do Option 1 + Option 2:**  
+  - Ship `deps-versions.sh` in the plugin and add it to `files`.  
+  - Default `QUICTLS_BRANCH` in `build-openssl.sh` to `openssl-3.2` (or another branch that has `Configure`).  
+  This gives reproducible builds when the file is used, and a working default when it is not.
+
+- **Do Option 4** in the plugin README so every consumer sees the one-time Android (and iOS if needed) setup.
+
+- **Option 3** is optional: only if you want true zero-config and accept a larger package.
+
+---
+
+## Consumer Instructions (for Plugin README)
+
+After the above are done, the plugin README can say:
+
+**Android (one-time setup)**  
+Before the first Android build, build WolfSSL (wolfssl-android) and ngtcp2/nghttp3 once. From your project root:
+
+```bash
+cd node_modules/@annadata/capacitor-mqtt-quic
+./build-native.sh --android-only --abi arm64-v8a
+./build-native.sh --android-only --abi armeabi-v7a
+./build-native.sh --android-only --abi x86_64
+```
+
+Or add to your app’s `package.json`:
+
+```json
+"setup:wolfssl-android": "cd node_modules/@annadata/capacitor-mqtt-quic && ./build-native.sh --android-only --abi arm64-v8a && ./build-native.sh --android-only --abi armeabi-v7a && ./build-native.sh --android-only --abi x86_64"
+```
+
+Then run `npm run setup:wolfssl-android` once. Requires Android NDK (r25+).
+
+**iOS**  
+(If applicable, add the corresponding one-time build steps for iOS here.)
+
+---
+
+## Summary
+
+| Approach | Effort | Result |
+|----------|--------|--------|
+| **1. Ship deps-versions.sh** | Low | One-time `build-native.sh` (or build-wolfssl.sh) works without app providing keys. |
+| **2. Default branch openssl-3.2** | Low | Clone works even without deps-versions.sh. |
+| **3. Ship prebuilt WolfSSL (wolfssl-android)** | Medium (build + package size) | No WolfSSL one-time step for consumers. |
+| **4. README + clear failure message** | Low | Direct use is documented and failures are understandable. |
+
+Making the **complete** production plugin means: at least **1 + 2 + 4** so that anyone who installs the plugin and follows the README can build without app-side workarounds.

package/docs/CAPACITOR_VERSION_SUPPORT.md

@@ -0,0 +1,65 @@
+# Capacitor Version Support
+
+This plugin supports **Capacitor >= 7.0.0**, including Capacitor 8. The following analysis and changes were applied to support the latest Capacitor JS version.
+
+## Architecture Analysis (ref-code/capacitor-mqtt-quic)
+
+### TypeScript / Web layer (`src/`)
+
+| File | Role | Capacitor API | Notes |
+|------|------|---------------|--------|
+| `index.ts` | Plugin registration | `registerPlugin<MqttQuicPlugin>('MqttQuic', { web: () => ... })` | Unchanged; API is stable in Cap 7 & 8. |
+| `definitions.ts` | Plugin interface | TypeScript interfaces only | No runtime Capacitor dependency. |
+| `web.ts` | Web/PWA implementation | None (uses `mqtt` npm package) | Fallback when not on native. |
+
+**Conclusion:** No code changes required for Capacitor 8. `registerPlugin` and the web fallback pattern are compatible with both versions.
+
+### Android (`android/`)
+
+| Component | Role | Changes for Cap 8 |
+|-----------|------|-------------------|
+| `MqttQuicPlugin.kt` | Bridge: `@CapacitorPlugin`, `Plugin`, `PluginCall`, `@PluginMethod` | None; same APIs in Cap 7 & 8. |
+| `build.gradle` | Build and Capacitor dependency | Updated (see below). |
+
+**Build changes applied:**
+
+- **Capacitor dependency:** Was `compileOnly 'com.getcapacitor:core:6.0.0'`. Now uses a variable so both Cap 7 and Cap 8 work:
+  - Cap 8: `com.capacitorjs:core:8.0.0` (default).
+  - Cap 7: app can set `capacitorCoreVersion` (e.g. `7.0.0`) and plugin uses `com.getcapacitor:core`.
+- **Gradle:** AGP 8.13.0, Gradle property assignment uses `=` where required.
+- **SDK:** `compileSdk`/`targetSdk` 36, `minSdkVersion` 24.
+- **AndroidX:** Optional versions aligned with Capacitor 8 plugin guide (e.g. JUnit 1.3.0, Espresso 3.7.0).
+
+### iOS (`ios/` and root `AnnadataCapacitorMqttQuic.podspec`)
+
+| Component | Role | Changes for Cap 8 |
+|-----------|------|-------------------|
+| `MqttQuicPlugin.swift` | Bridge: `CAPPlugin`, `CAPPluginCall`, `CAPBridgedPlugin`, `@objc` methods | None; same APIs in Cap 7 & 8. |
+| `AnnadataCapacitorMqttQuic.podspec` | CocoaPods spec | `s.ios.deployment_target = '15.0'` (was 14.0). |
+
+**Conclusion:** Plugin Swift code is unchanged. Only deployment target was raised to match Capacitor 8 (iOS 15+).
+
+## Summary of File Changes
+
+1. **package.json**
+   - `peerDependencies["@capacitor/core"]`: `"^7.0.0"` → `">=7.0.0"` (supports 7 and 8).
+   - `devDependencies`: All `@capacitor/*` set to `^8.0.0` for development against latest.
+
+2. **android/build.gradle**
+   - Capacitor dependency: variable-based `compileOnly` (Cap 7: `com.getcapacitor`, Cap 8: `com.capacitorjs`).
+   - `compileSdk`/`targetSdk` 36, `minSdkVersion` 24.
+   - Gradle 8–style property assignments (`=`) where applicable.
+   - AGP 8.13.0, optional AndroidX versions updated.
+
+3. **AnnadataCapacitorMqttQuic.podspec**
+   - `s.ios.deployment_target = '15.0'`.
+
+## Consuming Apps
+
+- **Capacitor 8:** Use as-is; plugin defaults to Cap 8 in Android build.
+- **Capacitor 7:** Ensure app uses `@capacitor/core@^7.x`. For Android, the plugin will resolve `com.getcapacitor:core` when `capacitorCoreVersion` is set to a 7.x value in the app’s root project.
+
+## References
+
+- [Updating Capacitor to 8.0 in your plugin](https://capacitorjs.com/docs/updating/plugins/8-0)
+- [Updating from Capacitor 7 to Capacitor 8](https://capacitorjs.com/docs/updating/8-0)

package/docs/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,246 @@
+# MQTT-over-QUIC Client Implementation Summary
+
+## ✅ Completed Phases
+
+### Phase 1: MQTT Protocol Layer + Transport Abstraction ✅
+**Status:** Complete
+
+**iOS (Swift):**
+- `MQTT/MQTTTypes.swift` - MQTT message types and constants
+- `MQTT/MQTTProtocol.swift` - Full MQTT 3.1.1 encode/decode (CONNECT, CONNACK, PUBLISH, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK, PINGREQ, PINGRESP, DISCONNECT)
+- `Transport/StreamTransport.swift` - StreamReader/StreamWriter interfaces + mock implementations
+- `Tests/MQTTProtocolTests.swift` - Unit tests
+
+**Android (Kotlin):**
+- `mqtt/MQTTTypes.kt` - MQTT message types and constants
+- `mqtt/MQTTProtocol.kt` - Full MQTT 3.1.1 encode/decode
+- `transport/StreamTransport.kt` - StreamReader/StreamWriter interfaces + mock implementations
+- `test/mqtt/MQTTProtocolTest.kt` - Unit tests
+
+**Deliverables:**
+- ✅ MQTT packet encode/decode (Swift + Kotlin)
+- ✅ Transport abstraction interfaces
+- ✅ Mock implementations for testing
+
+---
+
+### Phase 2: QUIC Transport Integration (ngtcp2 + nghttp3) ✅
+**Status:** Structure complete, ngtcp2 build pending
+
+**iOS (Swift):**
+- `QUIC/QuicTypes.swift` - QUIC stream and client protocols
+- `QUIC/QuicClientStub.swift` - Stub QUIC client (uses mock transport)
+- `Transport/QUICStreamAdapter.swift` - StreamReader/Writer adapters over QUIC stream
+
+**Android (Kotlin):**
+- `quic/QuicTypes.kt` - QUIC stream and client interfaces
+- `quic/QuicClientStub.kt` - Stub QUIC client (uses mock transport)
+- `transport/QUICStreamAdapter.kt` - StreamReader/Writer adapters over QUIC stream
+
+**Next Steps (ngtcp2/nghttp3 Integration):**
+1. **iOS:** Build ngtcp2/nghttp3 + OpenSSL/BoringSSL as static libraries, integrate via Xcode
+2. **Android:** Build ngtcp2/nghttp3 with NDK (CMake), produce `libngtcp2_client.so`
+3. Replace `QuicClientStub` with real ngtcp2-backed implementations
+4. Implement UDP: iOS `NWConnection`, Android `DatagramSocket`
+5. TLS 1.3 handshake integration
+
+**Deliverables:**
+- ✅ QUIC interface structure
+- ✅ Stream adapters (ready for ngtcp2)
+- ⏳ ngtcp2 build and integration (pending)
+
+---
+
+### Phase 3: MQTT Client API + Capacitor Plugin ✅
+**Status:** Complete
+
+**iOS (Swift):**
+- `Client/MQTTClient.swift` - High-level MQTT client (connect, publish, subscribe, unsubscribe, disconnect)
+- `MqttQuicPlugin.swift` - Capacitor plugin bridge
+
+**Android (Kotlin):**
+- `client/MQTTClient.kt` - High-level MQTT client
+- `MqttQuicPlugin.kt` - Capacitor plugin bridge
+
+**TypeScript:**
+- `src/definitions.ts` - Plugin interface definitions
+- `src/index.ts` - Plugin registration
+- `src/web.ts` - Web fallback stub
+
+**Deliverables:**
+- ✅ Native MQTT client API (Swift/Kotlin)
+- ✅ Capacitor plugin exposing API to TypeScript
+- ✅ Async/await support
+- ✅ Message loop for incoming PUBLISH
+- ✅ Error handling
+
+---
+
+### Phase 4: Platform Integration ✅
+**Status:** Complete
+
+**annadata-production Integration:**
+- ✅ Plugin added to `package.json`
+- ✅ MQTT endpoints added to `environment.ts` (`mqttQuic`, `mqttWs`)
+- ✅ `EndpointService` extended with `getMqttQuicUrl()`, `buildMqttQuicUrl()`
+- ✅ `MqttQuicService.ts` - Service using plugin on native, WSS fallback on web
+- ✅ Auth integration (device ID, token)
+
+**Deliverables:**
+- ✅ Plugin integrated in annadata-production
+- ✅ Endpoint configuration
+- ✅ MqttQuicService with native/web support
+- ✅ Auth and client ID alignment
+
+---
+
+## 📋 Remaining Work
+
+### Critical: ngtcp2/nghttp3 Build and Integration
+
+**iOS:**
+1. Build ngtcp2/nghttp3 + TLS library (OpenSSL or BoringSSL) as static libs
+2. Add to Xcode project (CocoaPods/SPM/vendored)
+3. Create `NGTCP2Client.swift` replacing `QuicClientStub`
+4. Implement UDP with `NWConnection`
+5. TLS 1.3 handshake
+
+**Android:**
+1. Build ngtcp2/nghttp3 with Android NDK (CMake)
+2. Create JNI wrapper (`quic/ngtcp2_jni.c`)
+3. Create `NGTCP2Client.kt` replacing `QuicClientStub`
+4. Implement UDP with `DatagramSocket`
+5. TLS 1.3 handshake
+
+**Resources:**
+- ngtcp2: https://github.com/ngtcp2/ngtcp2
+- nghttp3: https://github.com/ngtcp2/nghttp3
+- Server reference: `MQTTD/mqttd/transport_quic_ngtcp2.py`, `ngtcp2_bindings.py`
+
+### Optional: Web MQTT over WSS
+
+Implement `MqttQuicService` web fallback using `mqtt.js` or similar library.
+
+### Testing
+
+1. Unit tests: ✅ MQTT protocol tests exist
+2. Integration tests: Test against MQTTD QUIC server
+3. E2E: Connect from app → MQTTD, publish, subscribe, receive
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────┐
+│   annadata-production (TypeScript)  │
+│  ┌───────────────────────────────┐  │
+│  │  MqttQuicService              │  │
+│  └──────────────┬────────────────┘  │
+└─────────────────┼───────────────────┘
+                  │
+┌─────────────────▼───────────────────┐
+│   Capacitor Plugin (JS Bridge)      │
+│  ┌───────────────────────────────┐  │
+│  │  MqttQuicPlugin               │  │
+│  └──────────────┬────────────────┘  │
+└─────────────────┼───────────────────┘
+                  │
+     ┌────────────┴────────────┐
+     │                         │
+┌────▼─────┐          ┌───────▼──────┐
+│   iOS    │          │   Android    │
+│ (Swift)  │          │  (Kotlin)    │
+└────┬─────┘          └───────┬──────┘
+     │                        │
+┌────▼────────────────────────▼─────┐
+│  MQTTClient                       │
+│  ┌──────────────────────────────┐ │
+│  │  MQTT Protocol Layer         │ │
+│  └──────────────┬───────────────┘ │
+│                 │                 │
+│  ┌──────────────▼───────────────┐ │
+│  │  Transport Abstraction       │ │
+│  │  (StreamReader/Writer)       │ │
+│  └──────────────┬───────────────┘ │
+│                 │                 │
+│  ┌──────────────▼───────────────┐ │
+│  │  QUIC Transport (ngtcp2)     │ │
+│  │  [Currently: Stub]           │ │
+│  └──────────────────────────────┘ │
+└───────────────────────────────────┘
+                  │
+┌─────────────────▼──────────────────┐
+│   MQTTD Server (Python + ngtcp2)   │
+└────────────────────────────────────┘
+```
+
+---
+
+## 📦 Project Structure
+
+```
+capacitor-mqtt-quic/
+├── ios/
+│   ├── MqttQuicPlugin.podspec
+│   └── Sources/MqttQuicPlugin/
+│       ├── MQTT/              # Phase 1
+│       ├── Transport/         # Phase 1, 2
+│       ├── QUIC/              # Phase 2
+│       ├── Client/            # Phase 3
+│       └── MqttQuicPlugin.swift
+├── android/
+│   ├── build.gradle
+│   └── src/main/kotlin/ai/annadata/mqttquic/
+│       ├── mqtt/              # Phase 1
+│       ├── transport/         # Phase 1, 2
+│       ├── quic/              # Phase 2
+│       ├── client/            # Phase 3
+│       └── MqttQuicPlugin.kt
+└── src/                       # TypeScript bridge
+    ├── definitions.ts
+    ├── index.ts
+    └── web.ts
+
+annadata-production/
+└── src/
+    ├── config/
+    │   └── environment.ts     # Added mqttQuic, mqttWs
+    └── services/
+        ├── EndpointService.ts  # Added MQTT methods
+        └── MqttQuicService.ts  # New service
+```
+
+---
+
+## 🚀 Next Steps
+
+1. **Build ngtcp2 for iOS/Android** (4-6 weeks)
+   - Follow ngtcp2 build documentation
+   - Integrate with existing QUIC interfaces
+   - Test against MQTTD server
+
+2. **Replace stubs with real QUIC** (1-2 weeks)
+   - Implement `NGTCP2Client` (iOS/Android)
+   - UDP integration
+   - TLS 1.3 handshake
+
+3. **Testing** (1-2 weeks)
+   - Integration tests
+   - E2E with MQTTD server
+   - Performance testing
+
+4. **Web fallback** (optional, 1 week)
+   - Implement MQTT over WSS using mqtt.js
+
+---
+
+## 📝 Notes
+
+- All MQTT protocol code matches server format (`MQTTD/mqttd/protocol.py`)
+- Transport abstraction mirrors server pattern (`StreamReader`/`StreamWriter`)
+- QUIC structure ready for ngtcp2 integration
+- Plugin API matches Capacitor 7 patterns
+- Service integrates with existing auth/device ID system
+
+**Total Implementation Time:** ~10-15 weeks (with ngtcp2 build)

package/docs/MQTT5_CLIENT_COMPLIANCE.md

@@ -0,0 +1,48 @@
+# MQTT v5.0 Client Compliance Checklist
+
+This document describes how the Capacitor MQTT-over-QUIC plugin aligns with the **OASIS MQTT v5.0** specification and interoperability with the **mqttd** server.
+
+- **Specification:** [OASIS MQTT v5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html)
+- **Server compliance:** See [ref-code/mqttd/docs/MQTT5_SPEC_COMPLIANCE.md](../mqttd/docs/MQTT5_SPEC_COMPLIANCE.md) in the mqttd repo.
+
+## Implemented (required for spec and mqttd)
+
+| Area | Spec reference | Status | Notes |
+|------|----------------|--------|-------|
+| **§3.1 CONNECT** | Protocol name "MQTT", version 5; Connect Flags (reserved bit 0); CONNECT properties | ✅ | Reserved bit 0 explicitly masked to 0 (`flags & 0xFE`). No Will in CONNECT yet (optional). |
+| **§3.2 CONNACK** | Session Present, Reason Code, CONNACK properties | ✅ | **Server Keep Alive** (0x13) and **Assigned Client Identifier** (0x12) are read and applied; effective keepalive and client ID used for the session. |
+| **§3.3 PUBLISH** | V5 variable header and payload parsing; Topic Alias | ✅ | `parsePublishV5` in Android/iOS; Topic Alias resolved when topic length is 0; map updated when topic + alias present. |
+| **§3.8–3.9 SUBSCRIBE/SUBACK** | Subscription Options (at least QoS); reserved bits 6–7 = 0 | ✅ | Single topic per SUBSCRIBE; options byte masked with `0x3F` so reserved bits 6–7 are always 0 [MQTT-3.8.3-5]. |
+| **§3.14 DISCONNECT** | Handle server DISCONNECT | ✅ | Message loop handles DISCONNECT (0xE0); connection closed, state updated, loop exits. |
+| **§4.3.3 QoS 2 receive** | PUBREC → PUBREL → PUBCOMP | ✅ | Incoming QoS 2 PUBLISH: send PUBREC; on PUBREL send PUBCOMP. |
+| **§4.12 AUTH** | Connect loop until CONNACK | ✅ | After CONNECT, loop until CONNACK; if **AUTH** (packet type 15, 0xF0) received, client sends DISCONNECT (Bad authentication method) and closes—enhanced auth not supported. |
+
+## Packet type AUTH
+
+- **Spec:** AUTH is packet type **15**; fixed header first byte = `0xF0` (15 << 4).
+- **Android:** `MQTTTypes.kt` — `MQTTMessageType.AUTH: Byte = 0xF0`.
+- **iOS:** `MQTTTypes.swift` — `MQTTMessageType.AUTH = 0xF0`.
+
+Both platforms use this value in the connect loop to detect AUTH and fail cleanly when the server uses enhanced authentication.
+
+## Optional (not required for basic compliance)
+
+| Feature | Spec | Status | Notes |
+|---------|------|--------|-------|
+| **Subscription Options** | §3.8.3.1 No Local, Retain As Published, Retain Handling (0/1/2); reserved bits 6–7 = 0 | Optional | Currently only QoS (bits 0–1) sent; other options could be added to the API. |
+| **Multiple topic filters in one SUBSCRIBE** | §3.8 | Optional | One topic per SUBSCRIBE today; API could accept multiple filters + options. |
+| **Will message** | §3.1.2.5 Will Flag, Will Properties, Will Topic, Will Payload | Optional | CONNECT sends no Will; could add connect options for Will (topic, payload, QoS, retain, Will Delay Interval). |
+| **Flow control (Receive Maximum)** | §4.9 | Optional | Client can send Receive Maximum in CONNECT and read CONNACK; no enforcement of send quota for QoS 1/2 PUBLISH yet (could block when quota 0). |
+
+## Files (summary)
+
+| Area | Android (Kotlin) | iOS (Swift) |
+|------|------------------|-------------|
+| CONNACK props | `MQTTClient.kt` (connect path) | `MQTTClient.swift` (connect path) |
+| AUTH / connect loop | `MQTTClient.kt` | `MQTTClient.swift` |
+| Packet type AUTH | `MQTTTypes.kt` (AUTH = 0xF0) | `MQTTTypes.swift` (AUTH = 0xF0) |
+| DISCONNECT in loop | `MQTTClient.kt` (startMessageLoop) | `MQTTClient.swift` (startMessageLoop) |
+| parsePublishV5 + Topic Alias | `MQTT5Protocol.kt`, `MQTTClient.kt` | `MQTT5Protocol.swift`, `MQTTClient.swift` |
+| QoS 2 receive (PUBREC/PUBREL/PUBCOMP) | `MQTTProtocol.kt`, `MQTTClient.kt` | `MQTTProtocol.swift`, `MQTTClient.swift` |
+
+No changes to the mqttd server are required; the plugin is aligned with the server and the MQTT v5.0 spec for the implemented features above.