esp-idf-provisioning-web 0.0.3 → 0.0.6

package/README.md

@@ -4,8 +4,8 @@ A TypeScript SDK for provisioning ESP32 devices from web browsers using the ESP-
 
 ## Features
 
-- [ ] **Multiple Security Modes**
-  - [ ] Security1 (not implemented)
+- [x] **Security 0 and Security 1**
+  - [x] Security1: X25519 + PoP + AES-256-CTR
   - [ ] Security2 (not implemented)
 - [x] **BLE Transport**: Uses Web Bluetooth API for wireless provisioning
 - [x] **SoftAP Transport**: HTTP-based provisioning for devices in AP mode
@@ -28,40 +28,99 @@ npm install esp-idf-provisioning-web
 
 ## Usage
 
-### BLE Provisioning
+### BLE with Security 0
+
+Security 0 sends provisioning data without application-layer encryption. Use it
+only when the device is configured for Security 0.
 
 ```typescript
 import { ESPProvisionManager } from 'esp-idf-provisioning-web';
 
-// Search for devices with BLE
 const device = await ESPProvisionManager.searchBLEDevice();
-
-// Connect with proof of possession
 await device.connect();
+const networks = await device.scanWifiList();
+await device.provision('MyWiFiSSID', 'MyWiFiPassword');
+// Poll fetchWifiStatus() until connected or failed, then disconnect.
+```
 
-// Scan for WiFi networks
-const wifiList = await device.scanWifiList();
+Runnable example: [BLE Security 0](examples/ble-provisioning.html).
 
-// Provision the device
+### BLE with Security 1
+
+Security 1 uses X25519, proof of possession (PoP), and AES-256-CTR. Supply the
+PoP expected by the device:
+
+```typescript
+import { ESPProvisionManager } from 'esp-idf-provisioning-web';
+
+const device = await ESPProvisionManager.searchBLEDevice();
+await device.connect({
+  type: 'Security1',
+  proofOfPossession: 'device-proof-of-possession',
+});
+const networks = await device.scanWifiList();
 await device.provision('MyWiFiSSID', 'MyWiFiPassword');
+// Poll fetchWifiStatus() until connected or failed, then disconnect.
+```
+
+Runnable example: [BLE Security 1](examples/ble-provisioning-security1.html).
+
+### Resolve Security 1 credentials asynchronously
+
+`connect()` reads the public `proto-ver` endpoint before starting the handshake.
+Pass a resolver to obtain credentials using the returned protocol and application
+metadata. `requestProofOfPossession` below is supplied by the consuming application:
+
+```typescript
+await device.connect(async (info) => {
+  if (info.prov.sec_ver !== 1) throw new Error('Expected Security 1');
+  const proofOfPossession = await requestProofOfPossession(info);
+  return { type: 'Security1', proofOfPossession };
+});
+```
+
+The SDK passes through custom metadata without interpreting it. Credential
+retrieval and authorization belong to the consuming application.
+
+A new `connect()` call reads fresh metadata and runs the resolver again. Failed
+authentication, resolver failure, or transport failure clears the session; retry
+with `connect()`. There is no automatic downgrade to Security 0. Security 2 is
+unsupported.
 
-// Wait for STA connected
-let result;
+### Custom endpoints and connection status
+
+After connecting with either security mode, use the same APIs for application
+endpoints and Wi-Fi status. Custom endpoints use the established security mode:
+
+```typescript
+const response = await device.sendData(
+  'custom-data', new TextEncoder().encode('{"command":"get"}')
+);
+```
+
+Requests are serialized because Security 1 shares one continuous AES-CTR stream
+across both directions. `sendData('proto-ver', ...)` remains plaintext;
+`prov-session` is managed internally. Other endpoints require a completed handshake.
+
+```typescript
+import { ESPWifiStaState } from 'esp-idf-provisioning-web';
+
+let status;
 do {
-  result = await device.fetchWifiStatus();
-  await new Promise((resolve) => setTimeout(resolve, 2000));
-} while (result.staState !== ESPWifiStaState.connecting);
-
-if (result.staState === ESPWifiStaState.connected) {
-  console.log('Provisioning successful!');
-} else {
-  console.log('Provisioning failed:', result);
-}
+  status = await device.fetchWifiStatus();
+  if (status.staState === ESPWifiStaState.connecting) {
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  }
+} while (status.staState === ESPWifiStaState.connecting);
 
-// Disconnect
 device.disconnect();
 ```
 
+Security 1 requires a secure browser context and native Web Crypto **X25519**
+support. Unsupported browsers fail the handshake instead of falling back to
+plaintext. See the [Web Crypto specification](https://www.w3.org/TR/webcrypto/)
+and [ESP-IDF protocol documentation](https://docs.espressif.com/projects/esp-idf/en/v5.3.3/esp32s3/api-reference/provisioning/provisioning.html).
+
 ### SoftAP Provisioning
 
 **Important**: The browser cannot automatically connect to WiFi networks. Users must manually connect to the ESP device's access point before running this code.
@@ -104,6 +163,10 @@ if (ESPProvisionManager.isBluetoothSupported()) {
 
 ## Development
 
+Use Node.js 24 LTS to build and lint the SDK.
+`npm pack` and `npm publish` rebuild the generated protocol code, bundles and
+type declarations before packaging.
+
 ```bash
 # Install dependencies
 npm install

package/dist/ESPDevice.d.ts

@@ -1,4 +1,4 @@
-import { ESPDeviceInterface, ESPWifiAp, ESPWifiStatus, ESPSecurityConfig } from './types';
+import { ESPDeviceInterface, ESPWifiAp, ESPWifiStatus, ESPSecurityConfig, ESPSecurityResolver } from './types';
 /**
  * ESP Device class for provisioning operations
  */
@@ -6,18 +6,14 @@ export declare class ESPDevice implements ESPDeviceInterface {
     private device;
     private transportImpl?;
     private securityImpl?;
+    private requestQueue;
     /**
      * Create a new ESPDevice instance
      * @param device - BluetoothDevice for BLE or URL for SoftAP
      */
     constructor(device: BluetoothDevice | URL);
-    /**
-     * Connect to the device
-     * @param proofOfPossession - Proof of possession for secure modes
-     * @param softAPPassword - Password for SoftAP mode (not used in browser)
-     * @param username - Username for authentication
-     */
-    connect(security?: ESPSecurityConfig): Promise<void>;
+    /** Connect, read public metadata, resolve credentials, then complete the handshake. */
+    connect(security?: ESPSecurityConfig | ESPSecurityResolver): Promise<void>;
     /**
      * Scan for available WiFi networks
      * @returns List of WiFi networks
@@ -50,17 +46,6 @@ export declare class ESPDevice implements ESPDeviceInterface {
      * Get device
      */
     getDevice(): BluetoothDevice | URL;
-    /**
-     * Initialize security layer based on security type
-     */
-    private initializeSecurity;
-    /**
-     * Establish secure session with device
-     */
     private establishSession;
-    /**
-     * Initialize transport layer based on transport type
-     */
-    private initializeTransport;
 }
 //# sourceMappingURL=ESPDevice.d.ts.map

package/dist/ESPDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ESPDevice.d.ts","sourceRoot":"","sources":["../src/ESPDevice.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,aAAa,EACb,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAwBjB;;GAEG;AACH,qBAAa,SAAU,YAAW,kBAAkB;IAClD,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,aAAa,CAAC,CAAY;IAClC,OAAO,CAAC,YAAY,CAAC,CAAW;IAEhC;;;OAGG;gBACS,MAAM,EAAE,eAAe,GAAG,GAAG;IAIzC;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1D;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAiC1C;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhE;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,aAAa,CAAC;IAc/C;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAgBnE;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB;;OAEG;IACH,SAAS,IAAI,eAAe,GAAG,GAAG;IAIlC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;YACW,gBAAgB;IAkB9B;;OAEG;YACW,mBAAmB;CAYlC"}
+{"version":3,"file":"ESPDevice.d.ts","sourceRoot":"","sources":["../src/ESPDevice.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EAEpB,MAAM,SAAS,CAAC;AA0BjB;;GAEG;AACH,qBAAa,SAAU,YAAW,kBAAkB;IAClD,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,aAAa,CAAC,CAAY;IAClC,OAAO,CAAC,YAAY,CAAC,CAAW;IAChC,OAAO,CAAC,YAAY,CAAoC;IAExD;;;OAGG;gBACS,MAAM,EAAE,eAAe,GAAG,GAAG;IAIzC,uFAAuF;IACjF,OAAO,CAAC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2ChF;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAiC1C;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhE;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,aAAa,CAAC;IAc/C;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IA2BnE;;OAEG;IACH,UAAU,IAAI,IAAI;IASlB;;OAEG;IACH,SAAS,IAAI,eAAe,GAAG,GAAG;YAIpB,gBAAgB;CAU/B"}