esp-idf-provisioning-web 0.0.1

package/src/transport/BLETransport.ts

@@ -0,0 +1,111 @@
+import { Transport } from './Transport';
+// import { BLE_SERVICE_UUID, BLE_PROVISIONING_UUID, BLE_SESSION_UUID } from '../constants';
+import { bytesToString } from '../utils/crypto';
+
+/**
+ * BLE Transport implementation using Web Bluetooth API
+ */
+export class BLETransport extends Transport {
+  private device: BluetoothDevice;
+  private serviceUUID: string;
+  private nuLookup: Map<string, string>;
+
+  private server?: BluetoothRemoteGATTServer;
+  private service?: BluetoothRemoteGATTService;
+  private connected: boolean = false;
+
+  constructor(device: BluetoothDevice, serviceUUID: string, nuLookup: Map<string, string>) {
+    super();
+    this.device = device;
+    this.serviceUUID = serviceUUID;
+    this.nuLookup = nuLookup;
+  }
+
+  async connect(): Promise<void> {
+    if (this.isConnected()) {
+      return;
+    }
+
+    try {
+      // Connect to GATT server
+      this.server = await this.device.gatt?.connect();
+      if (!this.server) {
+        throw new Error('Failed to connect to GATT server');
+      }
+
+      // Get provisioning services
+      try {
+        const services = await this.server.getPrimaryServices(this.serviceUUID);
+        if (services.length > 1) {
+          const service = services.find((s) => s.uuid === this.serviceUUID);
+          if (!service) {
+            throw new Error(`Service with UUID ${this.serviceUUID} not found`);
+          }
+          this.service = service;
+        } else {
+          this.service = services[0];
+        }
+      } catch (error) {
+        throw new Error(`Failed to get primary services: ${error}`);
+      }
+
+      const characteristics = await this.service.getCharacteristics();
+      for (const char of characteristics) {
+        const descriptors = await char.getDescriptors();
+        for (const desc of descriptors) {
+          if (desc.uuid.slice(4, 8) !== '2901') continue;
+          const rawName = await desc.readValue();
+          this.nuLookup.set(bytesToString(new Uint8Array(rawName.buffer)).toLowerCase(), char.uuid);
+        }
+      }
+
+      console.debug('BLE discovered characteristics:', this.nuLookup);
+      this.connected = true;
+    } catch (error) {
+      this.connected = false;
+      throw new Error(`BLE connection failed: ${error}`);
+    }
+  }
+
+  disconnect(): void {
+    if (this.server?.connected) {
+      this.server.disconnect();
+    }
+    this.server = undefined;
+    this.service = undefined;
+    this.connected = false;
+  }
+
+  async sendData(endpoint: string, data: Uint8Array): Promise<Uint8Array> {
+    if (!this.isConnected()) {
+      throw new Error('Not connected to device');
+    }
+
+    const charUUID = this.nuLookup.get(endpoint.toLowerCase());
+    if (!charUUID) {
+      throw new Error(`Characteristic UUID for endpoint ${endpoint} not found`);
+    }
+
+    const characteristic = await this.service?.getCharacteristic(charUUID);
+    if (!characteristic) {
+      throw new Error(`Characteristic for UUID ${charUUID} not found`);
+    }
+
+    // FIXME: Uint8Array have wrong generic type constraints in this case
+    const cleanData = new Uint8Array(data.buffer as ArrayBuffer, data.byteOffset, data.byteLength);
+    await characteristic.writeValueWithResponse(cleanData);
+    const response = await characteristic.readValue();
+    return new Uint8Array(response.buffer);
+  }
+
+  isConnected(): boolean {
+    return this.connected && this.server?.connected === true;
+  }
+
+  /**
+   * Get the underlying Bluetooth device
+   */
+  getDevice(): BluetoothDevice {
+    return this.device;
+  }
+}

package/src/transport/SoftAPTransport.ts

@@ -0,0 +1,89 @@
+import { Transport } from './Transport';
+
+/**
+ * SoftAP Transport implementation using HTTP
+ * Note: Browser cannot automatically connect to WiFi networks.
+ * User must manually connect to the device's SoftAP before using this transport.
+ */
+export class SoftAPTransport extends Transport {
+  private baseUrl: string;
+  private connected: boolean = false;
+
+  /**
+   * @param baseUrl - Base URL of the device (e.g., http://192.168.4.1)
+   */
+  constructor(baseUrl: string) {
+    super();
+    this.baseUrl = baseUrl;
+  }
+
+  async connect(): Promise<void> {
+    try {
+      // Verify connection by making a test request
+      const response = await fetch(`${this.baseUrl}/proto-ver`, {
+        method: 'GET',
+        mode: 'cors',
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      this.connected = true;
+    } catch (error) {
+      this.connected = false;
+      throw new Error(
+        `SoftAP connection failed. Please ensure you are connected to the device's WiFi network. Error: ${error}`
+      );
+    }
+  }
+
+  disconnect(): void {
+    this.connected = false;
+  }
+
+  async sendData(endpoint: string, data: Uint8Array): Promise<Uint8Array> {
+    if (!this.connected) {
+      throw new Error('Not connected to device');
+    }
+
+    try {
+      const response = await fetch(`${this.baseUrl}/${endpoint}`, {
+        method: 'POST',
+        headers: {
+          'Accept': 'text/plain',
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: data.buffer as ArrayBuffer,
+        mode: 'cors',
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      const arrayBuffer = await response.arrayBuffer();
+      return new Uint8Array(arrayBuffer);
+    } catch (error) {
+      throw new Error(`SoftAP communication failed: ${error}`);
+    }
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  /**
+   * Set custom base URL
+   */
+  setBaseUrl(url: string): void {
+    this.baseUrl = url;
+  }
+
+  /**
+   * Get current base URL
+   */
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+}

package/src/transport/Transport.ts

@@ -0,0 +1,24 @@
+/**
+ * Base class for transport implementations
+ */
+export abstract class Transport {
+  /**
+   * Connect to the device
+   */
+  abstract connect(): Promise<void>;
+
+  /**
+   * Disconnect from the device
+   */
+  abstract disconnect(): void;
+
+  /**
+   * Send data to a specific endpoint
+   */
+  abstract sendData(endpoint: string, data: Uint8Array): Promise<Uint8Array>;
+
+  /**
+   * Check if transport is connected
+   */
+  abstract isConnected(): boolean;
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+export type ESPSecurityConfig = ESPSecurity1Config | ESPSecurity2Config;
+
+export interface ESPSecurity1Config {
+  type: 'Security1';
+  proofOfPossession: string;
+}
+
+export interface ESPSecurity2Config {
+  type: 'Security2';
+  username: string;
+  password: string;
+}
+
+/**
+ * WiFi authentication modes
+ */
+export enum ESPWifiAuthMode {
+  open = 0,
+  wep = 1,
+  wpa2Enterprise = 2,
+  wpa2Psk = 3,
+  wpaPsk = 4,
+  wpaWpa2Psk = 5,
+  wpa3Psk = 6,
+  wpa2Wpa3Psk = 7,
+}
+
+/**
+ * WiFi STA state
+ */
+export enum ESPWifiStaState {
+  connected = 0,
+  connecting = 1,
+  disconnected = 2,
+  failed = 3,
+}
+
+/**
+ * WiFi scan failure reasons
+ */
+export enum ESPConnectFailReason {
+  authError = 1,
+  networkNotFound = 2,
+}
+
+export interface ESPWifiStatus {
+  staState: ESPWifiStaState;
+  failedReason?: ESPConnectFailReason;
+  connected?: ESPWifiAp;
+}
+
+/**
+ * WiFi network information returned by device scan
+ */
+export interface ESPWifiAp {
+  ssid: string;
+  rssi: number;
+  auth: ESPWifiAuthMode;
+  bssid: string;
+  channel: number;
+}
+
+/**
+ * Scan status response
+ */
+export interface ESPScanStatusResponse {
+  scanFinished: boolean;
+  count: number;
+}
+
+/**
+ * Device interface for ESP provisioning
+ */
+export interface ESPDeviceInterface {
+  connect(security?: ESPSecurityConfig): Promise<void>;
+
+  scanWifiList(): Promise<ESPWifiAp[]>;
+
+  disconnect(): void;
+
+  provision(ssid: string, passphrase: string): Promise<void>;
+
+  fetchWifiStatus(): Promise<ESPWifiStatus>;
+
+  getDevice(): BluetoothDevice | URL;
+}

package/src/utils/crypto.ts

@@ -0,0 +1,129 @@
+/**
+ * Cryptographic utilities for ESP provisioning protocol
+ */
+
+/**
+ * Generate random bytes
+ */
+export function generateRandomBytes(length: number): Uint8Array {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+/**
+ * Convert hex string to Uint8Array
+ */
+export function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Convert Uint8Array to hex string
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Convert string to Uint8Array
+ */
+export function stringToBytes(str: string): Uint8Array {
+  return new TextEncoder().encode(str);
+}
+
+/**
+ * Convert Uint8Array to string
+ */
+export function bytesToString(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes);
+}
+
+/**
+ * SHA-256 hash function
+ */
+export async function sha256(data: Uint8Array): Promise<Uint8Array> {
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data.buffer as ArrayBuffer);
+  return new Uint8Array(hashBuffer);
+}
+
+/**
+ * HMAC-SHA-256
+ */
+export async function hmacSha256(key: Uint8Array, data: Uint8Array): Promise<Uint8Array> {
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    key.buffer as ArrayBuffer,
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  );
+  const signature = await crypto.subtle.sign('HMAC', cryptoKey, data.buffer as ArrayBuffer);
+  return new Uint8Array(signature);
+}
+
+/**
+ * AES-CTR encryption
+ */
+export async function aesEncrypt(
+  key: Uint8Array,
+  counter: Uint8Array,
+  data: Uint8Array
+): Promise<Uint8Array> {
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    key.buffer as ArrayBuffer,
+    { name: 'AES-CTR' },
+    false,
+    ['encrypt']
+  );
+  const encrypted = await crypto.subtle.encrypt(
+    { name: 'AES-CTR', counter: counter.buffer as ArrayBuffer, length: 128 },
+    cryptoKey,
+    data.buffer as ArrayBuffer
+  );
+  return new Uint8Array(encrypted);
+}
+
+/**
+ * AES-CTR decryption
+ */
+export async function aesDecrypt(
+  key: Uint8Array,
+  counter: Uint8Array,
+  data: Uint8Array
+): Promise<Uint8Array> {
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    key.buffer as ArrayBuffer,
+    { name: 'AES-CTR' },
+    false,
+    ['decrypt']
+  );
+  const decrypted = await crypto.subtle.decrypt(
+    { name: 'AES-CTR', counter: counter.buffer as ArrayBuffer, length: 128 },
+    cryptoKey,
+    data.buffer as ArrayBuffer
+  );
+  return new Uint8Array(decrypted);
+}
+
+/**
+ * Concatenate multiple Uint8Arrays
+ */
+export function concatBytes(...arrays: Uint8Array[]): Uint8Array {
+  const totalLength = arrays.reduce((acc, arr) => acc + arr.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}