@annadata/capacitor-mqtt-quic 0.1.6 → 0.1.8

package/docs/PRODUCTION_PUBLISH_STEPS.md

@@ -0,0 +1,167 @@
+# Production publish steps – @annadata/capacitor-mqtt-quic
+
+This checklist makes the plugin **production-grade**: pack everything needed (including native libs under the plugin), then publish to npm so consumers can use it with no app-side workarounds.
+
+**Production readiness** (Options 1+2+4) is already in place; see [CAPACITOR_MQTT_QUIC_PRODUCTION_PLUGIN.md](./CAPACITOR_MQTT_QUIC_PRODUCTION_PLUGIN.md). Follow the steps below to build, pack, and publish.
+
+---
+
+## Prerequisites
+
+- Node.js 18+
+- **iOS:** macOS, Xcode 15+
+- **Android:** Android Studio, NDK r25+ (e.g. via `$ANDROID_HOME/ndk/<version>`)
+- npm account with access to `@annadata` scope
+
+---
+
+## Step 1: Build native libraries (required for packaging)
+
+Build **iOS** and **Android** native deps so they are included in the package.
+
+### iOS (required for podspec)
+
+```bash
+./build-native.sh --ios-only
+```
+
+This produces:
+
+- `ios/libs/` – static libs (e.g. `libngtcp2.a`, `libngtcp2_crypto_wolfssl.a`, `libnghttp3.a`, `libwolfssl.a`)
+- `ios/include/` – headers
+
+The podspec’s `vendored_libraries` point at `ios/libs/`; these **must** be present when you pack/publish.
+
+### Android (required for zero-config / “complete” package)
+
+Android uses **WolfSSL** (same TLS backend as iOS). To ship a **complete** plugin so clients don’t run any native build, build WolfSSL + nghttp3 + ngtcp2 for all ABIs:
+
+```bash
+npm run build:android-prebuilts
+```
+
+Or manually:
+
+```bash
+./build-native.sh --android-only --abi arm64-v8a
+./build-native.sh --android-only --abi armeabi-v7a
+./build-native.sh --android-only --abi x86_64
+```
+
+This populates `android/install/wolfssl-android/<abi>/`, `android/install/nghttp3-android/<abi>/`, and `android/install/ngtcp2-android/<abi>/`. The plugin’s `clean:build-artifacts` script **does not** remove `android/install`, so these will be included in the tarball when present.
+
+---
+
+## Step 2: Clean build artifacts (keeps libs)
+
+```bash
+npm run clean:build-artifacts
+```
+
+This removes only:
+
+- `android/build/`, `android/.gradle/`
+- `ios/build/`, `ios/install/`
+
+It **keeps**:
+
+- `ios/libs/`, `ios/include/` (required by podspec)
+- `android/install/` (prebuilt WolfSSL/wolfssl-android when you built it in Step 1)
+
+---
+
+## Step 3: Build the plugin (TypeScript + bundle)
+
+```bash
+npm run build
+```
+
+---
+
+## Step 4: Verify package contents
+
+```bash
+npm pack --dry-run
+```
+
+Check:
+
+- `dist/` – JS/TS build
+- `ios/` – including `ios/libs/*.a`, `ios/include/`
+- `android/` – including `android/install/` if you built WolfSSL (wolfssl-android)
+- `deps-versions.sh`, `build-native.sh` – for consumers who need to rebuild
+- `docs/` – includes this checklist and other docs (e.g. `docs/PRODUCTION_PUBLISH_STEPS.md`, `docs/PROJECT_OVERVIEW.md`)
+- `AnnadataCapacitorMqttQuic.podspec`, `README.md`
+
+Optional size check:
+
+```bash
+npm pack --dry-run | grep "unpacked size"
+```
+
+With prebuilt iOS + Android libs the package will be larger (tens of MB); without Android prebuilts it stays smaller.
+
+---
+
+## Step 5: Bump version
+
+```bash
+npm version patch   # 0.1.6 → 0.1.7
+# or
+npm version minor   # 0.1.6 → 0.2.0
+```
+
+Or edit `version` in `package.json` manually.
+
+---
+
+## Step 6: Publish to npm
+
+```bash
+npm publish --access public
+```
+
+Scoped packages (`@annadata/...`) need `--access public` unless the scope is private.
+
+---
+
+## Step 7: Verify
+
+```bash
+npm view @annadata/capacitor-mqtt-quic
+```
+
+---
+
+## Summary: what gets packed
+
+| Item | When it’s included |
+|------|--------------------|
+| `dist/` | Always (from `npm run build`) |
+| `ios/`, `android/` | Always (listed in `package.json` `files`) |
+| `ios/libs/`, `ios/include/` | When present; **not** removed by `clean:build-artifacts` |
+| `android/install/` | When present (after Android WolfSSL/ngtcp2 build); **not** removed by clean |
+| `deps-versions.sh`, `build-native.sh` | Always (in `files`) |
+| `docs/` | Always (in `files`; includes this checklist and PROJECT_OVERVIEW) |
+| `AnnadataCapacitorMqttQuic.podspec`, `README.md` | Always |
+| CA cert bundle (optional) | `ios/.../Resources/mqttquic_ca.pem`, `android/.../assets/mqttquic_ca.pem` — packed with `ios/` and `android/`; used for QUIC TLS verification unless overridden by `caFile`/`caPath` |
+
+`.npmignore` is set so that `ios/libs/`, `ios/include/`, and `android/install/` are **not** excluded when present. Certificate files (`.pem`) under `ios/` and `android/` are **included** in the package.
+
+---
+
+## Consumer experience after publish
+
+- **With prebuilt libs (iOS + Android):**  
+  `npm install @annadata/capacitor-mqtt-quic` → `npx cap sync` → build app. No extra steps.
+
+- **With only iOS prebuilts:**  
+  Same for iOS. For Android, consumers run the one-time WolfSSL/ngtcp2 build steps documented in the plugin README (Production / First-time build), e.g. `./build-native.sh --android-only --abi arm64-v8a` (and other ABIs).
+
+---
+
+## Troubleshooting
+
+- **502 on publish:** Package too large. Run `npm run clean:build-artifacts` and ensure you’re not including huge `deps/` or `ref-code/` (they should be gitignored and not in `files`).
+- **“WolfSSL not found” on consumer Android build:** They need the one-time WolfSSL/ngtcp2 build (see README), or you need to ship `android/install/` (Step 1).
+- **iOS pod install fails:** Ensure `ios/libs/` and `ios/include/` are present in the tarball (`npm pack && tar -tf *.tgz | grep ios/libs`).

package/docs/PROJECT_OVERVIEW.md

@@ -0,0 +1,193 @@
+# @annadata/capacitor-mqtt-quic — Complete Project Overview
+
+This document explains the **entire project**: what it is, how it’s built, and how the pieces fit together.
+
+---
+
+## 1. What This Project Is
+
+**@annadata/capacitor-mqtt-quic** is a **Capacitor plugin** that lets mobile and web apps talk **MQTT** (publish/subscribe messaging) over different transports:
+
+| Platform   | Transport              | Technology                          |
+|------------|------------------------|-------------------------------------|
+| **iOS**    | MQTT over **QUIC**     | ngtcp2 + WolfSSL (native C/C++/Swift) |
+| **Android**| MQTT over **QUIC**     | ngtcp2 + WolfSSL (native C++/Kotlin JNI) |
+| **Web**    | MQTT over **WebSocket** (default) | mqtt.js (WSS)                    |
+| **Web**    | MQTT over **WebTransport** (optional) | Browser’s HTTP/3/QUIC + mqtt-packet |
+
+Your app uses **one API** in JavaScript/TypeScript (`MqttQuic.connect`, `publish`, `subscribe`, etc.); the plugin picks the right implementation per platform.
+
+---
+
+## 2. Why MQTT + QUIC?
+
+- **MQTT**: Lightweight pub/sub protocol (topics, QoS, retain). Common in IoT and real-time apps.
+- **QUIC**: Modern transport (UDP + TLS 1.3). Faster handshake, better on bad networks, multiplexing.
+- **MQTT over QUIC**: Run MQTT on top of QUIC instead of TCP. Your server (e.g. mqtt.annadata.cloud:1884) speaks MQTT-over-QUIC; this plugin is the client for Capacitor apps.
+
+Browsers can’t use raw QUIC, so on **web** the plugin uses **WebSocket (WSS)** or, optionally, **WebTransport** (browser’s QUIC) when the server supports it.
+
+---
+
+## 3. High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Your Capacitor App (JavaScript/TypeScript)                      │
+│  import { MqttQuic } from '@annadata/capacitor-mqtt-quic';       │
+│  await MqttQuic.connect({ host, port: 1884, clientId });        │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Capacitor bridge (src/index.ts)                                 │
+│  registerPlugin('MqttQuic', { web: () => MqttQuicWeb });          │
+│  → On iOS/Android: calls native plugin                            │
+│  → On Web: uses MqttQuicWeb (src/web.ts)                         │
+└──────┬─────────────────────────────────────────────┬────────────┘
+       │                                               │
+       ▼                                               ▼
+┌──────────────────────┐                   ┌──────────────────────┐
+│  iOS (Swift)          │                   │  Android (Kotlin)     │
+│  MqttQuicPlugin       │                   │  MqttQuicPlugin       │
+│  → MQTTClient         │                   │  → MQTTClient         │
+│  → NGTCP2Client       │                   │  → NGTCP2Client (JNI) │
+│  → NGTCP2Bridge (C++) │                   │  → ngtcp2_jni.cpp     │
+│  → ngtcp2 + WolfSSL   │                   │  → ngtcp2 + WolfSSL   │
+└──────────────────────┘                   └──────────────────────┘
+       │                                               │
+       └───────────────────────┬───────────────────────┘
+                               │
+                               ▼
+                    ┌──────────────────────┐
+                    │  MQTT+QUIC server    │
+                    │  e.g. :1884          │
+                    └──────────────────────┘
+```
+
+---
+
+## 4. Repository Structure (What Lives Where)
+
+### 4.1 JavaScript/TypeScript (shared API and web)
+
+| Path | Purpose |
+|------|--------|
+| **src/index.ts** | Registers the plugin with Capacitor; exports `MqttQuic` and types. On native, Capacitor routes to iOS/Android; on web, uses the web implementation. |
+| **src/definitions.ts** | TypeScript interfaces: `MqttQuicConnectOptions`, `MqttQuicPublishOptions`, `MqttQuicSubscribeOptions`, plugin interface, and WebTransport path options (`webTransportUrl`, `webTransportDeviceId`, etc.). |
+| **src/web.ts** | Web implementation: `MqttQuicWeb` extends `WebPlugin`. Uses **mqtt.js** for WSS; optionally **WebTransport** + **mqtt-packet** when `webTransportUrl` is set. Same methods and events as native. |
+| **dist/** | Built output (from `npm run build`): ESM, CJS, and bundled `plugin.js` for the app. |
+
+### 4.2 iOS (native)
+
+| Path | Purpose |
+|------|--------|
+| **ios/Sources/MqttQuicPlugin/MqttQuicPlugin.swift** | Capacitor plugin entry: declares methods (connect, publish, subscribe, …), reads options from JS, calls `MQTTClient` and `NGTCP2Client`, and notifies listeners (`connected`, `subscribed`, `message`). |
+| **ios/Sources/.../Client/MQTTClient.swift** | MQTT protocol state machine: CONNECT, PUBLISH, SUBSCRIBE, UNSUBSCRIBE, DISCONNECT; uses a transport (stream read/write). |
+| **ios/Sources/.../MQTT/** | MQTT 3.1.1 and 5.0 parsing/serialization (types, reason codes, properties). |
+| **ios/Sources/.../QUIC/NGTCP2Client.swift** | Swift wrapper around the C++ QUIC client. |
+| **ios/Sources/.../QUIC/NGTCP2Bridge.mm** | C++ bridge to **ngtcp2** and **WolfSSL**: socket, TLS, QUIC handshake, streams; used by `NGTCP2Client`. |
+| **ios/Sources/.../Transport/** | Transport abstraction (stream reader/writer) and QUIC stream adapter. |
+| **ios/libs/** | Prebuilt static libs: `libngtcp2.a`, `libngtcp2_crypto_wolfssl.a`, `libnghttp3.a`, `libwolfssl.a` (shipped in the npm package for CocoaPods). |
+| **ios/include/** | Headers for ngtcp2/nghttp3/wolfssl. |
+| **AnnadataCapacitorMqttQuic.podspec** | CocoaPods spec: name, version, source files, vendored libs, link flags. |
+
+### 4.3 Android (native)
+
+| Path | Purpose |
+|------|--------|
+| **android/.../MqttQuicPlugin.kt** | Capacitor plugin: `@CapacitorPlugin`, methods (connect, publish, subscribe, …), calls `MQTTClient` and `NGTCP2Client`, notifies listeners. |
+| **android/.../client/MQTTClient.kt** | MQTT client logic (same role as iOS `MQTTClient`). |
+| **android/.../mqtt/** | MQTT 3.1.1 and 5.0 (types, protocol, properties). |
+| **android/.../quic/NGTCP2Client.kt** | Kotlin API for the native QUIC client. |
+| **android/.../cpp/ngtcp2_jni.cpp** | JNI layer: connects to ngtcp2 + **WolfSSL** (same TLS stack as iOS), implements QUIC + MQTT stream. |
+| **android/.../cpp/CMakeLists.txt** | CMake: builds the native `.so`, links WolfSSL and ngtcp2 (from `android/install/` after you run the build scripts). |
+| **android/install/** | After building: `wolfssl-android/<abi>/`, `ngtcp2-android/<abi>/`, `nghttp3-android/<abi>/`. Can be shipped in the package for zero-config. |
+
+### 4.4 Build and publish
+
+| Path | Purpose |
+|------|--------|
+| **build-native.sh** | One script to build native deps: WolfSSL → nghttp3 → ngtcp2 for iOS and/or Android (per ABI). |
+| **deps-versions.sh** | Pinned versions/commits for WolfSSL, ngtcp2, nghttp3; sourced by build scripts. |
+| **ios/build-wolfssl.sh**, **android/build-wolfssl.sh** | Build WolfSSL for iOS/Android. |
+| **ios/build-ngtcp2.sh**, **android/build-ngtcp2.sh** | Build ngtcp2 (with WolfSSL). |
+| **package.json** | Plugin name, version, `files`, `capacitor.ios/android/web`, scripts (`build`, `clean:build-artifacts`, `prepublishOnly`). |
+| **PRODUCTION_PUBLISH_STEPS.md** | Checklist: build native libs, clean, build JS, version, publish. |
+| **.npmignore** | Excludes build junk but keeps `ios/libs`, `ios/include`, and (if present) `android/install` so the package is self-contained. |
+
+---
+
+## 5. Data Flow (Example: Connect and Publish)
+
+1. **App** calls `MqttQuic.connect({ host: 'mqtt.annadata.cloud', port: 1884, clientId: 'x' })`.
+2. **Capacitor** invokes the native plugin (iOS/Android) or the web implementation.
+3. **Native (e.g. Android)**  
+   - `MqttQuicPlugin.connect()` parses options, sets CA env if needed.  
+   - Calls `NGTCP2Client` (JNI) to open a QUIC connection to host:1884.  
+   - `ngtcp2_jni.cpp` uses WolfSSL for TLS and ngtcp2 for QUIC, then runs MQTT over the QUIC stream.  
+   - `MQTTClient` sends CONNECT, gets CONNACK, then plugin calls `notifyListeners("connected", …)`.  
+4. **Web**  
+   - If no `webTransportUrl`: `mqtt.js` connects to `wss://host:8884` (or `ws://host:port`).  
+   - If `webTransportUrl` is set: open WebTransport, create one bidirectional stream, send MQTT CONNECT with mqtt-packet, wait for CONNACK, then notify `connected`.  
+5. **Publish**  
+   - App calls `MqttQuic.publish({ topic, payload })`.  
+   - Same bridge: native side uses `MQTTClient.publish` over the QUIC stream; web uses mqtt.js or mqtt-packet over WSS/WebTransport.  
+   - Incoming PUBLISH is delivered via `notifyListeners('message', { topic, payload })` (native) or `this.notifyListeners('message', …)` (web).
+
+So: **one API**, different transport per platform; events and method names are the same everywhere.
+
+---
+
+## 6. Web Behaviour in Detail
+
+- **Default (no WebTransport)**  
+  `webTransportUrl` not set → `MqttQuicWeb` uses **mqtt.js** and connects to `ws://host:port` or `wss://host:port` (WSS when port is 8884 or 443). Same `connect`/`publish`/`subscribe`/`unsubscribe`/`disconnect` and `addListener('connected'|'subscribed'|'message')`.
+
+- **With WebTransport**  
+  `webTransportUrl` set (and optionally `webTransportDeviceId`, `webTransportAction`, `webTransportPath`) → plugin builds URL like `https://host:443/mqtt-wt/devices/<deviceId>/<action>/<path>`, opens WebTransport, runs MQTT over one bidirectional stream using **mqtt-packet**. Browser uses HTTP/3/QUIC; server must support WebTransport and MQTT on that path.
+
+- Browsers **cannot** use the same native ngtcp2+WolfSSL stack (no UDP); so “QUIC on web” is only via WebTransport when the server supports it.
+
+---
+
+## 7. TLS and Certificates
+
+- **Native (iOS/Android)**  
+  QUIC uses TLS 1.3 (WolfSSL). CA can be: bundled PEM in the app (e.g. `mqttquic_ca.pem`), or `caFile`/`caPath` passed in `connect()`. Env vars `MQTT_QUIC_CA_FILE` / `MQTT_QUIC_CA_PATH` are used by the native layer.
+
+- **Web (WSS)**  
+  Certificate verification is done by the browser for the WebSocket connection.
+
+- **Web (WebTransport)**  
+  Same: HTTPS origin and server certificate are validated by the browser.
+
+---
+
+## 8. Build and Publish Summary
+
+- **JS/Web**  
+  `npm run build` → TypeScript compile + Rollup bundle → `dist/`. No native steps needed for web-only.
+
+- **iOS**  
+  Build native libs (WolfSSL, nghttp3, ngtcp2) with `./build-native.sh --ios-only` so `ios/libs/` and `ios/include/` exist. Podspec references these; `pod install` in the app links them.
+
+- **Android**  
+  Build WolfSSL + nghttp3 + ngtcp2 per ABI (e.g. `./build-native.sh --android-only --abi arm64-v8a`) so `android/install/` is populated. App’s CMake then finds them when building the plugin’s `.so`.
+
+- **Publish**  
+  See **PRODUCTION_PUBLISH_STEPS.md**: build native (if shipping prebuilts), `npm run clean:build-artifacts`, `npm run build`, bump version, `npm publish --access public`. The `files` in package.json and `.npmignore` control what gets into the tarball (e.g. `dist`, `ios`, `android`, `deps-versions.sh`, `build-native.sh`, and optionally prebuilt `ios/libs`, `android/install`).
+
+---
+
+## 9. Summary Table
+
+| Layer | iOS | Android | Web |
+|-------|-----|---------|-----|
+| **Plugin entry** | MqttQuicPlugin.swift | MqttQuicPlugin.kt | MqttQuicWeb (web.ts) |
+| **MQTT** | MQTTClient + MQTT/*.swift | MQTTClient + mqtt/*.kt | mqtt.js or mqtt-packet |
+| **Transport** | QUIC (ngtcp2) | QUIC (ngtcp2 via JNI) | WSS or WebTransport |
+| **TLS/QUIC libs** | WolfSSL + ngtcp2 (vendored .a) | WolfSSL + ngtcp2 (install/) | Browser / mqtt.js |
+| **Same API** | Yes | Yes | Yes |
+
+This is the complete picture of the project: a single Capacitor plugin that provides MQTT over QUIC on native and MQTT over WSS (or WebTransport) on web, with one consistent API and event model.

package/ios/.swiftpm/xcode/xcuserdata/annadata.xcuserdatad/xcschemes/xcschememanagement.plist

@@ -7,7 +7,7 @@
 		<key>MqttQuicPlugin.xcscheme_^#shared#^_</key>
 		<dict>
 			<key>orderHint</key>
-			<integer>3</integer>
+			<integer>32</integer>
 		</dict>
 	</dict>
 </dict>

package/ios/{MqttQuicPlugin.podspec → AnnadataCapacitorMqttQuic.podspec}

@@ -3,7 +3,7 @@ require 'json'
 package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
 
 Pod::Spec.new do |s|
-  s.name = 'MqttQuicPlugin'
+  s.name = 'AnnadataCapacitorMqttQuic'
   s.version = package['version']
   s.summary = 'MQTT-over-QUIC Capacitor plugin (iOS)'
   s.license = package['license']
@@ -12,7 +12,7 @@ Pod::Spec.new do |s|
   s.source = { :git => 'https://github.com/annadata/capacitor-mqtt-quic', :tag => s.version.to_s }
   s.source_files = 'Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
   s.resources = ['Sources/MqttQuicPlugin/Resources/*.pem']
-  s.ios.deployment_target = '14.0'
+  s.ios.deployment_target = '15.0'
   s.dependency 'Capacitor'
   s.swift_version = '5.1'
   s.vendored_libraries = [
@@ -25,8 +25,8 @@ Pod::Spec.new do |s|
   s.private_header_files = 'Sources/**/*.h', 'include/**/*.h'
   s.header_mappings_dir = 'Sources'
   s.pod_target_xcconfig = {
-    'HEADER_SEARCH_PATHS' => '$(PODS_ROOT)/MqttQuicPlugin/include/ngtcp2 $(PODS_ROOT)/MqttQuicPlugin/include/nghttp3 $(PODS_ROOT)/MqttQuicPlugin/include/wolfssl',
-    'LIBRARY_SEARCH_PATHS' => '$(PODS_ROOT)/MqttQuicPlugin/libs',
+    'HEADER_SEARCH_PATHS' => '$(PODS_ROOT)/AnnadataCapacitorMqttQuic/include/ngtcp2 $(PODS_ROOT)/AnnadataCapacitorMqttQuic/include/nghttp3 $(PODS_ROOT)/AnnadataCapacitorMqttQuic/include/wolfssl',
+    'LIBRARY_SEARCH_PATHS' => '$(PODS_ROOT)/AnnadataCapacitorMqttQuic/libs',
     'OTHER_LDFLAGS' => '-lngtcp2 -lngtcp2_crypto_wolfssl -lnghttp3 -lwolfssl',
     'SWIFT_ACTIVE_COMPILATION_CONDITIONS' => 'NGTCP2_ENABLED NGHTTP3_ENABLED'
   }

package/ios/App/App/capacitor.config.json

@@ -1,6 +1,6 @@
 {
 	"appId": "ai.annadata.mqttquic",
-	"appName": "MqttQuicPlugin",
+	"appName": "AnnadataCapacitorMqttQuic",
 	"webDir": "www",
 	"packageClassList": [
 		"MqttQuicPlugin"

package/ios/NGTCP2_BUILD_INSTRUCTIONS.md

@@ -34,7 +34,7 @@ If you have access to pre-built ngtcp2, nghttp3, and OpenSSL libraries:
 2. Place `libnghttp3.a` in `ios/libs/`
 3. Place OpenSSL libraries (`libssl.a`, `libcrypto.a`) in `ios/libs/`
 4. Place headers in `ios/include/ngtcp2/`, `ios/include/nghttp3/`, and `ios/include/openssl/`
-5. Update `MqttQuicPlugin.podspec` to link against these libraries
+5. Update `AnnadataCapacitorMqttQuic.podspec` to link against these libraries
 
 ### Option 2: Build from Source
 
@@ -154,7 +154,7 @@ Then clean and rebuild the iOS app so it links the new xcframework. See the app
 
 ### Option A: CocoaPods
 
-Update `ios/MqttQuicPlugin.podspec`:
+Update `ios/AnnadataCapacitorMqttQuic.podspec`:
 
 ```ruby
 Pod::Spec.new do |s|
@@ -322,6 +322,18 @@ brew install cmake
 - Check that header search paths are correct
 - Ensure OpenSSL and ngtcp2 are linked in the correct order
 
+### Enabling wolfSSL debug (ERR_CRYPTO / TLS handshake)
+
+To see why TLS verification fails (e.g. ERR_CRYPTO from ngtcp2/wolfSSL):
+
+1. **Set the env var** before the QUIC connection runs:
+   - In the host app (e.g. Xcode scheme or code): set `MQTT_QUIC_WOLFSSL_DEBUG=1`.
+   - The plugin’s native code (`NGTCP2Bridge.mm`) checks this and calls `wolfSSL_Debugging_ON()` when the SSL context is created.
+
+2. **Rebuild** the plugin (and the app that uses it), then connect. wolfSSL will print debug lines to stderr (Xcode console or device log) describing the handshake and any verification failure.
+
+3. **Note:** Debug output only appears if wolfSSL was built with `DEBUG_WOLFSSL` (or equivalent). If you see no extra output, the wolfSSL library may be a release build; rebuild wolfSSL with debug enabled if you need the logs.
+
 ## Next Steps
 
 After building ngtcp2:
@@ -330,4 +342,4 @@ After building ngtcp2:
 2. Replace `QuicClientStub` with `NGTCP2Client` in `MQTTClient.swift`
 3. Test connection to MQTT server over QUIC
 
-See `NGTCP2_INTEGRATION_PLAN.md` for detailed implementation guide.
+See [NGTCP2_INTEGRATION_PLAN.md](../docs/NGTCP2_INTEGRATION_PLAN.md) for detailed implementation guide.

package/ios/Package.swift

@@ -1,17 +1,16 @@
 // swift-tools-version: 5.9
 import PackageDescription
 
-// MqttQuicPlugin iOS – Swift Package for Capacitor 8 (SPM).
-// Requires Libs/MqttQuicLibs.xcframework. After building OpenSSL, ngtcp2, nghttp3
-// (see build-openssl.sh, build-ngtcp2.sh, build-nghttp3.sh), run:
+// AnnadataCapacitorMqttQuic – Swift Package for Capacitor 8 (SPM).
+// Requires Libs/MqttQuicLibs.xcframework. After building (see build-native.sh), run:
 //   ./create-xcframework.sh
 let package = Package(
-    name: "MqttQuicPlugin",
-    platforms: [.iOS(.v14)],
+    name: "AnnadataCapacitorMqttQuic",
+    platforms: [.iOS(.v15)],
     products: [
         .library(
-            name: "MqttQuicPlugin",
-            targets: ["MqttQuicPlugin"]
+            name: "AnnadataCapacitorMqttQuic",
+            targets: ["AnnadataCapacitorMqttQuic"]
         )
     ],
     dependencies: [
@@ -38,7 +37,7 @@ let package = Package(
             ]
         ),
         .target(
-            name: "MqttQuicPlugin",
+            name: "AnnadataCapacitorMqttQuic",
             dependencies: [
                 "NGTCP2Bridge",
                 .product(name: "Capacitor", package: "capacitor-swift-pm")

package/ios/Sources/MqttQuicPlugin/MqttQuicPlugin.swift

@@ -42,6 +42,12 @@ public class MqttQuicPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     private func bundledCaPath() -> String? {
+        // Prefer app bundle so TLS works when installed from npm pack (pod resources may be in separate .bundle)
+        if let mainPath = Bundle.main.path(forResource: "mqttquic_ca", ofType: "pem"),
+           let mainContents = try? String(contentsOfFile: mainPath),
+           mainContents.contains("BEGIN CERTIFICATE") {
+            return mainPath
+        }
         let bundle = Bundle(for: MqttQuicPlugin.self)
         guard let path = bundle.path(forResource: "mqttquic_ca", ofType: "pem") else {
             return nil

package/ios/Sources/MqttQuicPlugin/QUIC/NGTCP2Bridge.mm

@@ -5,6 +5,7 @@
 #include <ngtcp2/ngtcp2_crypto_wolfssl.h>
 
 #include <wolfssl/ssl.h>
+#include <wolfssl/wolfcrypt/logging.h>
 
 #include <arpa/inet.h>
 #include <fcntl.h>
@@ -327,6 +328,11 @@ class QuicClient {
     }
     wolfSSL_CTX_set_verify(ssl_ctx_, WOLFSSL_VERIFY_PEER, nullptr);
 
+    /* Optional: enable wolfSSL debug output when MQTT_QUIC_WOLFSSL_DEBUG is set (e.g. for ERR_CRYPTO) */
+    if (std::getenv("MQTT_QUIC_WOLFSSL_DEBUG") != nullptr) {
+      wolfSSL_Debugging_ON();
+    }
+
     ssl_ = wolfSSL_new(ssl_ctx_);
     if (!ssl_) {
       setError("wolfSSL_new failed");

package/ios/Tests/MQTTProtocolTests.swift

@@ -4,7 +4,7 @@
 //
 
 import XCTest
-@testable import MqttQuicPlugin
+@testable import AnnadataCapacitorMqttQuic
 
 final class MQTTProtocolTests: XCTestCase {
 

package/ios/build-openssl.sh

@@ -31,7 +31,7 @@ DEPS_DIR="${PROJECT_DIR}/deps"
 DEFAULT_OPENSSL_SOURCE_DIR="${DEPS_DIR}/openssl"
 OPENSSL_VERSION="${OPENSSL_VERSION:-3.2.0}"
 USE_QUICTLS="${USE_QUICTLS:-1}"
-QUICTLS_BRANCH="${QUICTLS_BRANCH:-main}"
+QUICTLS_BRANCH="${QUICTLS_BRANCH:-openssl-3.2}"
 ARCH="${ARCH:-arm64}"
 SDK="${SDK:-iphoneos}"
 IOS_DEPLOYMENT_TARGET="${IOS_DEPLOYMENT_TARGET:-15.0}"

package/ios/libs/MqttQuicLibs.xcframework/Info.plist

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>AvailableLibraries</key>
+	<array>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libmqttquic_native_simulator.a</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64_x86_64-simulator</string>
+			<key>LibraryPath</key>
+			<string>libmqttquic_native_simulator.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+				<string>x86_64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
+		</dict>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libmqttquic_native_device.a</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64</string>
+			<key>LibraryPath</key>
+			<string>libmqttquic_native_device.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+		</dict>
+	</array>
+	<key>CFBundlePackageType</key>
+	<string>XFWK</string>
+	<key>XCFrameworkFormatVersion</key>
+	<string>1.0</string>
+</dict>
+</plist>