esp-idf-provisioning-web 0.0.1

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * ESP-IDF Provisioning Web SDK
+ *
+ * A TypeScript library for provisioning ESP32 devices via Web Bluetooth API and HTTP.
+ * Supports both BLE and SoftAP transport modes with Security0, Security1, and Security2.
+ *
+ * Note: Browser limitations apply:
+ * - BLE requires user interaction to select devices
+ * - SoftAP requires manual WiFi connection by the user
+ * - Some security features may require additional crypto libraries for production use
+ */
+
+export { ESPDevice } from './ESPDevice';
+export { ESPProvisionManager } from './ESPProvisionManager';
+
+export {
+  ESPWifiAuthMode,
+  ESPWifiStaState,
+  type ESPDeviceInterface,
+  type ESPSecurity1Config,
+  type ESPSecurity2Config,
+  type ESPWifiAp,
+  type ESPScanStatusResponse as ESPStatusResponse,
+  type ESPConnectFailReason,
+  type ESPWifiStatus,
+} from './types';
+
+export {
+  FALLBACK_SERVICE_UUID,
+  DEFAULT_DEVICE_PREFIX,
+} from './constants';

package/src/proto/constants.proto

@@ -0,0 +1,14 @@
+syntax = "proto3";
+
+/* Allowed values for the status
+ * of a protocomm instance */
+enum Status {
+    Success = 0;
+    InvalidSecScheme = 1;
+    InvalidProto = 2;
+    TooManySessions = 3;
+    InvalidArgument = 4;
+    InternalError = 5;
+    CryptoError = 6;
+    InvalidSession = 7;
+}

package/src/proto/sec0.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+import "constants.proto";
+
+/* Data structure of Session command/request packet */
+message S0SessionCmd {
+
+}
+
+/* Data structure of Session response packet */
+message S0SessionResp {
+    Status status = 1;
+}
+
+/* A message must be of type Cmd or Resp */
+enum Sec0MsgType {
+    S0_Session_Command = 0;
+    S0_Session_Response = 1;
+}
+
+/* Payload structure of session data */
+message Sec0Payload {
+    Sec0MsgType msg = 1;        /*!< Type of message */
+    oneof payload {
+        S0SessionCmd sc = 20;   /*!< Payload data interpreted as Cmd */
+        S0SessionResp sr = 21;  /*!< Payload data interpreted as Resp */
+    }
+}

package/src/proto/sec1.proto

@@ -0,0 +1,45 @@
+syntax = "proto3";
+
+import "constants.proto";
+
+/* Data structure of Session command1 packet */
+message SessionCmd1 {
+    bytes client_verify_data = 2;
+}
+
+/* Data structure of Session response1 packet */
+message SessionResp1 {
+    Status status = 1;
+    bytes device_verify_data = 3;
+}
+
+/* Data structure of Session command0 packet */
+message SessionCmd0 {
+    bytes client_pubkey = 1;
+}
+
+/* Data structure of Session response0 packet */
+message SessionResp0 {
+    Status status = 1;
+    bytes device_pubkey = 2;
+    bytes device_random = 3;
+}
+
+/* A message must be of type Cmd0 / Cmd1 / Resp0 / Resp1 */
+enum Sec1MsgType {
+    Session_Command0 = 0;
+    Session_Response0 = 1;
+    Session_Command1 = 2;
+    Session_Response1 = 3;
+}
+
+/* Payload structure of session data */
+message Sec1Payload {
+    Sec1MsgType msg = 1;        /*!< Type of message */
+    oneof payload {
+        SessionCmd0 sc0 = 20;   /*!< Payload data interpreted as Cmd0 */
+        SessionResp0 sr0 = 21;  /*!< Payload data interpreted as Resp0 */
+        SessionCmd1 sc1 = 22;   /*!< Payload data interpreted as Cmd1 */
+        SessionResp1 sr1 = 23;  /*!< Payload data interpreted as Resp1 */
+    }
+}

package/src/proto/sec2.proto

@@ -0,0 +1,48 @@
+syntax = "proto3";
+
+import "constants.proto";
+
+/* A message must be of type Cmd0 / Cmd1 / Resp0 / Resp1 */
+enum Sec2MsgType {
+    S2Session_Command0 = 0;
+    S2Session_Response0 = 1;
+    S2Session_Command1 = 2;
+    S2Session_Response1 = 3;
+}
+
+// NOTE: Client: Host (shell, Android/iOS) | Device: ESP32-XX
+/* Data structure of Session command0 packet */
+message S2SessionCmd0 {
+    bytes client_username = 1;
+    bytes client_pubkey = 2;
+}
+
+/* Data structure of Session response0 packet */
+message S2SessionResp0 {
+    Status status = 1;
+    bytes device_pubkey = 2;
+    bytes device_salt = 3;
+}
+
+/* Data structure of Session command1 packet */
+message S2SessionCmd1 {
+    bytes client_proof = 1;
+}
+
+/* Data structure of Session response1 packet */
+message S2SessionResp1 {
+    Status status = 1;
+    bytes device_proof = 2;
+    bytes device_nonce = 3;
+}
+
+/* Payload structure of session data */
+message Sec2Payload {
+    Sec2MsgType msg = 1;        /*!< Type of message */
+    oneof payload {
+        S2SessionCmd0 sc0 = 20;   /*!< Payload data interpreted as Cmd0 */
+        S2SessionResp0 sr0 = 21;  /*!< Payload data interpreted as Resp0 */
+        S2SessionCmd1 sc1 = 22;   /*!< Payload data interpreted as Cmd1 */
+        S2SessionResp1 sr1 = 23;  /*!< Payload data interpreted as Resp1 */
+    }
+}

package/src/proto/session.proto

@@ -0,0 +1,25 @@
+syntax = "proto3";
+
+import "sec0.proto";
+import "sec1.proto";
+import "sec2.proto";
+
+/* Allowed values for the type of security
+ * being used in a protocomm session */
+enum SecSchemeVersion {
+    SecScheme0 = 0;  /*!< Unsecured - plaintext communication */
+    SecScheme1 = 1;  /*!< Security scheme 1 - Curve25519 + AES-256-CTR*/
+    SecScheme2 = 2;  /*!< Security scheme 2 - SRP6a + AES-256-GCM*/
+
+}
+
+/* Data structure exchanged when establishing
+ * secure session between Host and Client */
+message SessionData {
+    SecSchemeVersion sec_ver = 2;   /*!< Type of security */
+    oneof proto {
+        Sec0Payload sec0 = 10;      /*!< Payload data in case of security 0 */
+        Sec1Payload sec1 = 11;      /*!< Payload data in case of security 1 */
+        Sec2Payload sec2 = 12;      /*!< Payload data in case of security 2 */
+    }
+}

package/src/proto/wifi_config.proto

@@ -0,0 +1,57 @@
+syntax = "proto3";
+
+import "constants.proto";
+import "wifi_constants.proto";
+
+message CmdGetStatus {
+
+}
+
+message RespGetStatus {
+    Status status = 1;
+    WifiStationState sta_state = 2;
+    oneof state {
+        WifiConnectFailedReason fail_reason = 10;
+        WifiConnectedState connected = 11;
+    }
+}
+
+message CmdSetConfig {
+    bytes ssid = 1;
+    bytes passphrase = 2;
+    bytes bssid = 3;
+    int32 channel = 4;
+}
+
+message RespSetConfig {
+    Status status = 1;
+}
+
+message CmdApplyConfig {
+
+}
+
+message RespApplyConfig {
+    Status status = 1;
+}
+
+enum WiFiConfigMsgType {
+    TypeCmdGetStatus = 0;
+    TypeRespGetStatus = 1;
+    TypeCmdSetConfig = 2;
+    TypeRespSetConfig = 3;
+    TypeCmdApplyConfig = 4;
+    TypeRespApplyConfig = 5;
+}
+
+message WiFiConfigPayload {
+    WiFiConfigMsgType msg = 1;
+    oneof payload {
+        CmdGetStatus cmd_get_status = 10;
+        RespGetStatus resp_get_status = 11;
+        CmdSetConfig cmd_set_config = 12;
+        RespSetConfig resp_set_config = 13;
+        CmdApplyConfig cmd_apply_config = 14;
+        RespApplyConfig resp_apply_config = 15;
+    }
+}

package/src/proto/wifi_constants.proto

@@ -0,0 +1,32 @@
+syntax = "proto3";
+
+enum WifiStationState {
+    Connected = 0;
+    Connecting = 1;
+    Disconnected = 2;
+    ConnectionFailed = 3;
+}
+
+enum WifiConnectFailedReason {
+    AuthError = 0;
+    NetworkNotFound = 1;
+}
+
+enum WifiAuthMode {
+    Open = 0;
+    WEP  = 1;
+    WPA_PSK = 2;
+    WPA2_PSK = 3;
+    WPA_WPA2_PSK = 4;
+    WPA2_ENTERPRISE = 5;
+    WPA3_PSK = 6;
+    WPA2_WPA3_PSK = 7;
+}
+
+message WifiConnectedState {
+    string ip4_addr = 1;
+    WifiAuthMode auth_mode = 2;
+    bytes ssid = 3;
+    bytes bssid = 4;
+    int32 channel = 5;
+}

package/src/proto/wifi_ctrl.proto

@@ -0,0 +1,38 @@
+syntax = "proto3";
+
+import "constants.proto";
+
+message CmdCtrlReset {
+
+}
+
+message RespCtrlReset {
+
+}
+
+message CmdCtrlReprov {
+
+}
+
+message RespCtrlReprov{
+
+}
+
+enum WiFiCtrlMsgType {
+    TypeCtrlReserved = 0;
+    TypeCmdCtrlReset = 1;
+    TypeRespCtrlReset = 2;
+    TypeCmdCtrlReprov = 3;
+    TypeRespCtrlReprov = 4;
+}
+
+message WiFiCtrlPayload {
+    WiFiCtrlMsgType msg = 1;
+    Status status = 2;
+    oneof payload {
+        CmdCtrlReset cmd_ctrl_reset = 11;
+        RespCtrlReset resp_ctrl_reset = 12;
+        CmdCtrlReprov cmd_ctrl_reprov = 13;
+        RespCtrlReprov resp_ctrl_reprov = 14;
+    }
+}

package/src/proto/wifi_scan.proto

@@ -0,0 +1,63 @@
+syntax = "proto3";
+
+import "constants.proto";
+import "wifi_constants.proto";
+
+message CmdScanStart {
+    bool blocking = 1;
+    bool passive = 2;
+    uint32 group_channels = 3;
+    uint32 period_ms = 4;
+}
+
+message RespScanStart {
+
+}
+
+message CmdScanStatus {
+
+}
+
+message RespScanStatus {
+    bool scan_finished = 1;
+    uint32 result_count = 2;
+}
+
+message CmdScanResult {
+    uint32 start_index = 1;
+    uint32 count = 2;
+}
+
+message WiFiScanResult {
+    bytes ssid = 1;
+    uint32 channel = 2;
+    int32 rssi = 3;
+    bytes bssid = 4;
+    WifiAuthMode auth = 5;
+}
+
+message RespScanResult {
+    repeated WiFiScanResult entries = 1;
+}
+
+enum WiFiScanMsgType {
+    TypeCmdScanStart = 0;
+    TypeRespScanStart = 1;
+    TypeCmdScanStatus = 2;
+    TypeRespScanStatus = 3;
+    TypeCmdScanResult = 4;
+    TypeRespScanResult = 5;
+}
+
+message WiFiScanPayload {
+    WiFiScanMsgType msg = 1;
+    Status status = 2;
+    oneof payload {
+        CmdScanStart cmd_scan_start = 10;
+        RespScanStart resp_scan_start = 11;
+        CmdScanStatus cmd_scan_status = 12;
+        RespScanStatus resp_scan_status = 13;
+        CmdScanResult cmd_scan_result = 14;
+        RespScanResult resp_scan_result = 15;
+    }
+}

package/src/protocol/protocol.ts

@@ -0,0 +1,23 @@
+import * as proto from '../generated/proto.js';
+import { ESPWifiAuthMode } from '../types.js';
+
+export function wifiAuthModeToESPWifiAuthMode(mode: proto.WifiAuthMode): ESPWifiAuthMode {
+  switch (mode) {
+    case proto.WifiAuthMode.Open:
+      return ESPWifiAuthMode.open;
+    case proto.WifiAuthMode.WEP:
+      return ESPWifiAuthMode.wep;
+    case proto.WifiAuthMode.WPA_PSK:
+      return ESPWifiAuthMode.wpaPsk;
+    case proto.WifiAuthMode.WPA2_PSK:
+      return ESPWifiAuthMode.wpa2Psk;
+    case proto.WifiAuthMode.WPA_WPA2_PSK:
+      return ESPWifiAuthMode.wpaWpa2Psk;
+    case proto.WifiAuthMode.WPA2_ENTERPRISE:
+      return ESPWifiAuthMode.wpa2Enterprise;
+    case proto.WifiAuthMode.WPA3_PSK:
+      return ESPWifiAuthMode.wpa3Psk;
+    case proto.WifiAuthMode.WPA2_WPA3_PSK:
+      return ESPWifiAuthMode.wpa2Wpa3Psk;
+  }
+}

package/src/protocol/wifiConfig.ts

@@ -0,0 +1,108 @@
+import * as proto from '../generated/proto.js';
+import { ESPConnectFailReason, ESPWifiAp, ESPWifiStaState, ESPWifiStatus } from '../types.js';
+import { bytesToHex, bytesToString, stringToBytes } from '../utils/crypto.js';
+import { wifiAuthModeToESPWifiAuthMode } from './protocol.js';
+
+export function getConfigStatusRequest(): Uint8Array {
+  let configRequest = proto.WiFiConfigPayload.create({});
+  configRequest.msg = proto.WiFiConfigMsgType.TypeCmdGetStatus;
+  configRequest.cmdGetStatus = proto.CmdGetStatus.create({});
+  return proto.WiFiConfigPayload.encode(configRequest).finish();
+}
+
+export function processConfigStatusResponse(response: Uint8Array): ESPWifiStatus {
+  try {
+    const configResponse = proto.WiFiConfigPayload.decode(response);
+    const result = configResponse.respGetStatus as proto.RespGetStatus;
+    if (result.status !== proto.Status.Success) {
+      throw new Error(`Config status failed: ${result.status}`);
+    }
+    let staState: ESPWifiStaState;
+    switch (result.staState) {
+      case proto.WifiStationState.Disconnected:
+        staState = ESPWifiStaState.disconnected;
+        break;
+      case proto.WifiStationState.Connecting:
+        staState = ESPWifiStaState.connecting;
+        break;
+      case proto.WifiStationState.Connected:
+        staState = ESPWifiStaState.connected;
+        break;
+      case proto.WifiStationState.ConnectionFailed:
+        staState = ESPWifiStaState.failed;
+        break;
+    }
+
+    let failedReason: ESPConnectFailReason | undefined;
+    switch (result.failReason) {
+      case proto.WifiConnectFailedReason.AuthError:
+        failedReason = ESPConnectFailReason.authError;
+        break;
+      case proto.WifiConnectFailedReason.NetworkNotFound:
+        failedReason = ESPConnectFailReason.networkNotFound;
+        break;
+      default:
+        break;
+    }
+
+    let connected: ESPWifiAp | undefined;
+    if (result.connected) {
+      connected = {
+        ssid: bytesToString(result.connected.ssid),
+        rssi: result.connected.rssi,
+        auth: wifiAuthModeToESPWifiAuthMode(result.connected.auth),
+        bssid: bytesToHex(result.connected.bssid),
+        channel: result.connected.channel,
+      };
+    }
+
+    return {
+      staState,
+      failedReason,
+      connected,
+    };
+  } catch (error) {
+    throw new Error('Failed to decode config status response');
+  }
+}
+
+export function getConfigUpdateRequest(ssid: string, passphrase: string): Uint8Array {
+  let configRequest = proto.WiFiConfigPayload.create({});
+  configRequest.msg = proto.WiFiConfigMsgType.TypeCmdSetConfig;
+  configRequest.cmdSetConfig = proto.CmdSetConfig.create({
+    ssid: stringToBytes(ssid),
+    passphrase: stringToBytes(passphrase),
+  });
+  return proto.WiFiConfigPayload.encode(configRequest).finish();
+}
+
+export function processConfigUpdateResponse(response: Uint8Array): void {
+  try {
+    const configResponse = proto.WiFiConfigPayload.decode(response);
+    const result = configResponse.respSetConfig as proto.RespSetConfig;
+    if (result.status !== proto.Status.Success) {
+      throw new Error(`Config update failed: ${result.status}`);
+    }
+  } catch (error) {
+    throw new Error('Failed to decode config update response');
+  }
+}
+
+export function getConfigApplyRequest(): Uint8Array {
+  let configRequest = proto.WiFiConfigPayload.create({});
+  configRequest.msg = proto.WiFiConfigMsgType.TypeCmdApplyConfig;
+  configRequest.cmdApplyConfig = proto.CmdApplyConfig.create({});
+  return proto.WiFiConfigPayload.encode(configRequest).finish();
+}
+
+export function processConfigApplyResponse(response: Uint8Array): void {
+  try {
+    const configResponse = proto.WiFiConfigPayload.decode(response);
+    const result = configResponse.respApplyConfig as proto.RespApplyConfig;
+    if (result.status !== proto.Status.Success) {
+      throw new Error(`Config apply failed: ${result.status}`);
+    }
+  } catch (error) {
+    throw new Error('Failed to decode config apply response');
+  }
+}

package/src/protocol/wifiScan.ts

@@ -0,0 +1,91 @@
+import * as proto from '../generated/proto.js';
+import { ESPScanStatusResponse, ESPWifiAp } from '../types.js';
+import { bytesToHex, bytesToString } from '../utils/crypto.js';
+import { wifiAuthModeToESPWifiAuthMode } from './protocol.js';
+
+export function getScanStartRequest(
+  blocking: boolean = true,
+  passive: boolean = false,
+  groupChannels: number = 5,
+  periodMs: number = 120
+): Uint8Array {
+  let cmd = proto.CmdScanStart.create({});
+  cmd.blocking = blocking;
+  cmd.passive = passive;
+  cmd.groupChannels = groupChannels;
+  cmd.periodMs = periodMs;
+  const scanRequest = proto.WiFiScanPayload.create({
+    msg: proto.WiFiScanMsgType.TypeCmdScanStart,
+    cmdScanStart: cmd,
+  });
+  return proto.WiFiScanPayload.encode(scanRequest).finish();
+}
+
+export function processScanStartResponse(response: Uint8Array): void {
+  try {
+    const scanResponse = proto.WiFiScanPayload.decode(response);
+    if (scanResponse.status !== proto.Status.Success) {
+      throw new Error(`Scan start failed: ${scanResponse.status}`);
+    }
+  } catch (error) {
+    console.error('Error processing scan start response:', error);
+  }
+}
+
+export function getScanStatusRequest(): Uint8Array {
+  const scanRequest = proto.WiFiScanPayload.create({
+    msg: proto.WiFiScanMsgType.TypeCmdScanStatus,
+    cmdScanStatus: proto.CmdScanStatus.create({}),
+  });
+  return proto.WiFiScanPayload.encode(scanRequest).finish();
+}
+
+export function processScanStatusResponse(response: Uint8Array): ESPScanStatusResponse {
+  try {
+    const scanResponse = proto.WiFiScanPayload.decode(response);
+    if (scanResponse.status !== proto.Status.Success) {
+      throw new Error(`Scan status failed: ${scanResponse.status}`);
+    }
+    const result = scanResponse.respScanStatus as proto.RespScanStatus;
+    return {
+      scanFinished: result.scanFinished,
+      count: result.resultCount,
+    };
+  } catch (error) {
+    throw new Error('Failed to decode scan status response');
+  }
+}
+
+export function getScanResultRequest(index: number, count: number): Uint8Array {
+  let cmd = proto.CmdScanResult.create({});
+  cmd.startIndex = index;
+  cmd.count = count;
+  const scanRequest = proto.WiFiScanPayload.create({
+    msg: proto.WiFiScanMsgType.TypeCmdScanResult,
+    cmdScanResult: cmd,
+  });
+  return proto.WiFiScanPayload.encode(scanRequest).finish();
+}
+
+export function processScanResultResponse(response: Uint8Array): ESPWifiAp[] {
+  try {
+    const scanResponse = proto.WiFiScanPayload.decode(response);
+    if (scanResponse.status !== proto.Status.Success) {
+      throw new Error(`Scan result failed: ${scanResponse.status}`);
+    }
+    const result = scanResponse.respScanResult as proto.RespScanResult;
+    const wifiList: ESPWifiAp[] = result.entries.map((entity) => {
+      const wifi = entity as proto.WiFiScanResult;
+      return {
+        ssid: bytesToString(wifi.ssid),
+        rssi: wifi.rssi,
+        auth: wifiAuthModeToESPWifiAuthMode(wifi.auth),
+        bssid: bytesToHex(wifi.bssid),
+        channel: wifi.channel,
+      };
+    });
+    return wifiList;
+  } catch (error) {
+    throw new Error('Failed to decode scan result response');
+  }
+}

package/src/security/Security.ts

@@ -0,0 +1,29 @@
+/**
+ * Base class for security implementations
+ */
+export abstract class Security {
+  /**
+   * Encrypt data for transmission
+   */
+  abstract encrypt(data: Uint8Array): Promise<Uint8Array>;
+
+  /**
+   * Decrypt received data
+   */
+  abstract decrypt(data: Uint8Array): Promise<Uint8Array>;
+
+  /**
+   * Get session setup request data
+   */
+  abstract getSessionSetupRequest(): Promise<Uint8Array>;
+
+  /**
+   * Process session setup response
+   */
+  abstract processSessionSetupResponse(response: Uint8Array): Promise<void>;
+
+  /**
+   * Check if security is established
+   */
+  abstract isEstablished(): boolean;
+}

package/src/security/Security0.ts

@@ -0,0 +1,40 @@
+import { Security } from './Security';
+import * as proto from '../generated/proto.js';
+
+/**
+ * Security0 - No encryption (unsecure mode)
+ */
+export class Security0 extends Security {
+  private established: boolean = false;
+
+  async encrypt(data: Uint8Array): Promise<Uint8Array> {
+    return data;
+  }
+
+  async decrypt(data: Uint8Array): Promise<Uint8Array> {
+    return data;
+  }
+
+  async getSessionSetupRequest(): Promise<Uint8Array> {
+    let setupReq = proto.SessionData.create({});
+    setupReq.secVer = proto.SecSchemeVersion.SecScheme0;
+    setupReq.sec0 = proto.Sec0Payload.create({
+      msg: proto.Sec0MsgType.S0_Session_Command,
+      sc: proto.S0SessionCmd.create({})
+    });
+    return proto.Sec0Payload.encode(setupReq).finish();
+  }
+
+  async processSessionSetupResponse(response: Uint8Array): Promise<void> {
+    const setupResp = proto.SessionData.decode(response);
+    if (setupResp.secVer === proto.SecSchemeVersion.SecScheme0 && setupResp.sec0) {
+      this.established = true;
+    } else {
+      throw new Error('Invalid session setup response for Security0');
+    }
+  }
+
+  isEstablished(): boolean {
+    return this.established;
+  }
+}