esp-idf-provisioning-web 0.0.3 → 0.0.6

package/src/index.ts

@@ -1,13 +1,15 @@
+/// <reference types="web-bluetooth" preserve="true" />
+
 /**
  * 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.
+ * Supports both BLE and SoftAP transport modes with Security0 and Security1.
  *
  * 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
+ * - Security1 requires Web Crypto with X25519 support (HTTPS or localhost)
  */
 
 export { ESPDevice } from './ESPDevice';
@@ -16,12 +18,15 @@ export { ESPProvisionManager } from './ESPProvisionManager';
 export {
   ESPWifiAuthMode,
   ESPWifiStaState,
+  ESPConnectFailReason,
   type ESPDeviceInterface,
+  type ESPSecurityConfig,
+  type ESPSecurityResolver,
+  type ESPProvisioningInfo,
+  type ESPProvisioningMetadata,
   type ESPSecurity1Config,
   type ESPSecurity2Config,
   type ESPWifiAp,
-  type ESPScanStatusResponse as ESPStatusResponse,
-  type ESPConnectFailReason,
   type ESPWifiStatus,
 } from './types';
 

package/src/protocol/wifiConfig.ts

@@ -4,7 +4,7 @@ import { bytesToHex, bytesToString, stringToBytes } from '../utils/crypto.js';
 import { wifiAuthModeToESPWifiAuthMode } from './protocol.js';
 
 export function getConfigStatusRequest(): Uint8Array {
-  let configRequest = proto.WiFiConfigPayload.create({});
+  const configRequest = proto.WiFiConfigPayload.create({});
   configRequest.msg = proto.WiFiConfigMsgType.TypeCmdGetStatus;
   configRequest.cmdGetStatus = proto.CmdGetStatus.create({});
   return proto.WiFiConfigPayload.encode(configRequest).finish();
@@ -61,13 +61,13 @@ export function processConfigStatusResponse(response: Uint8Array): ESPWifiStatus
       failedReason,
       connected,
     };
-  } catch (error) {
+  } catch {
     throw new Error('Failed to decode config status response');
   }
 }
 
 export function getConfigUpdateRequest(ssid: string, passphrase: string): Uint8Array {
-  let configRequest = proto.WiFiConfigPayload.create({});
+  const configRequest = proto.WiFiConfigPayload.create({});
   configRequest.msg = proto.WiFiConfigMsgType.TypeCmdSetConfig;
   configRequest.cmdSetConfig = proto.CmdSetConfig.create({
     ssid: stringToBytes(ssid),
@@ -83,13 +83,13 @@ export function processConfigUpdateResponse(response: Uint8Array): void {
     if (result.status !== proto.Status.Success) {
       throw new Error(`Config update failed: ${result.status}`);
     }
-  } catch (error) {
+  } catch {
     throw new Error('Failed to decode config update response');
   }
 }
 
 export function getConfigApplyRequest(): Uint8Array {
-  let configRequest = proto.WiFiConfigPayload.create({});
+  const configRequest = proto.WiFiConfigPayload.create({});
   configRequest.msg = proto.WiFiConfigMsgType.TypeCmdApplyConfig;
   configRequest.cmdApplyConfig = proto.CmdApplyConfig.create({});
   return proto.WiFiConfigPayload.encode(configRequest).finish();
@@ -102,7 +102,7 @@ export function processConfigApplyResponse(response: Uint8Array): void {
     if (result.status !== proto.Status.Success) {
       throw new Error(`Config apply failed: ${result.status}`);
     }
-  } catch (error) {
+  } catch {
     throw new Error('Failed to decode config apply response');
   }
 }

package/src/protocol/wifiScan.ts

@@ -9,7 +9,7 @@ export function getScanStartRequest(
   groupChannels: number = 5,
   periodMs: number = 120
 ): Uint8Array {
-  let cmd = proto.CmdScanStart.create({});
+  const cmd = proto.CmdScanStart.create({});
   cmd.blocking = blocking;
   cmd.passive = passive;
   cmd.groupChannels = groupChannels;
@@ -51,13 +51,13 @@ export function processScanStatusResponse(response: Uint8Array): ESPScanStatusRe
       scanFinished: result.scanFinished,
       count: result.resultCount,
     };
-  } catch (error) {
+  } catch {
     throw new Error('Failed to decode scan status response');
   }
 }
 
 export function getScanResultRequest(index: number, count: number): Uint8Array {
-  let cmd = proto.CmdScanResult.create({});
+  const cmd = proto.CmdScanResult.create({});
   cmd.startIndex = index;
   cmd.count = count;
   const scanRequest = proto.WiFiScanPayload.create({
@@ -85,7 +85,7 @@ export function processScanResultResponse(response: Uint8Array): ESPWifiAp[] {
       };
     });
     return wifiList;
-  } catch (error) {
+  } catch {
     throw new Error('Failed to decode scan result response');
   }
 }

package/src/security/Security0.ts

@@ -16,18 +16,20 @@ export class Security0 extends Security {
   }
 
   async getSessionSetupRequest(): Promise<Uint8Array> {
-    let setupReq = proto.SessionData.create({});
+    const 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();
+    return proto.SessionData.encode(setupReq).finish();
   }
 
   async processSessionSetupResponse(response: Uint8Array): Promise<void> {
     const setupResp = proto.SessionData.decode(response);
-    if (setupResp.secVer === proto.SecSchemeVersion.SecScheme0 && setupResp.sec0) {
+    if (setupResp.secVer === proto.SecSchemeVersion.SecScheme0 &&
+        setupResp.sec0?.msg === proto.Sec0MsgType.S0_Session_Response &&
+        setupResp.sec0.sr?.status === proto.Status.Success) {
       this.established = true;
     } else {
       throw new Error('Invalid session setup response for Security0');

package/src/security/Security1.ts

@@ -0,0 +1,110 @@
+import { Security } from './Security';
+import * as proto from '../generated/proto.js';
+import { AESCTRStream, sha256, stringToBytes } from '../utils/crypto';
+
+/** ESP-IDF Security 1: X25519, optional PoP, and one continuous AES-CTR stream. */
+export class Security1 extends Security {
+  private phase: 'command0' | 'response0' | 'command1' | 'response1' | 'established' = 'command0';
+  private keyPair?: CryptoKeyPair;
+  private publicKey?: Uint8Array;
+  private devicePublicKey?: Uint8Array;
+  private cipher?: AESCTRStream;
+
+  constructor(private proofOfPossession: string, patchVersion?: number) {
+    super();
+    if ((patchVersion ?? 0) !== 0) {
+      throw new Error('Unsupported Security1 patch version');
+    }
+    if (typeof proofOfPossession !== 'string') {
+      throw new Error('Unsupported security configuration');
+    }
+  }
+
+  async getSessionSetupRequest(): Promise<Uint8Array> {
+    if (this.phase === 'command0') {
+      this.keyPair = await crypto.subtle.generateKey('X25519', false, ['deriveBits']) as CryptoKeyPair;
+      this.publicKey = new Uint8Array(await crypto.subtle.exportKey('raw', this.keyPair.publicKey));
+      this.phase = 'response0';
+      return proto.SessionData.encode({
+        secVer: proto.SecSchemeVersion.SecScheme1,
+        sec1: {
+          msg: proto.Sec1MsgType.Session_Command0,
+          sc0: { clientPubkey: this.publicKey },
+        },
+      }).finish();
+    }
+    if (this.phase === 'command1' && this.cipher && this.devicePublicKey) {
+      const clientVerifyData = await this.cipher.update(this.devicePublicKey);
+      this.phase = 'response1';
+      return proto.SessionData.encode({
+        secVer: proto.SecSchemeVersion.SecScheme1,
+        sec1: { msg: proto.Sec1MsgType.Session_Command1, sc1: { clientVerifyData } },
+      }).finish();
+    }
+    throw new Error('Invalid Security1 handshake state');
+  }
+
+  async processSessionSetupResponse(response: Uint8Array): Promise<void> {
+    const session = proto.SessionData.decode(response);
+    if (session.secVer !== proto.SecSchemeVersion.SecScheme1 || !session.sec1) {
+      throw new Error('Invalid Security1 session response');
+    }
+    const payload = session.sec1;
+    if (this.phase === 'response0' && this.keyPair) {
+      const reply = payload.sr0;
+      if (payload.msg !== proto.Sec1MsgType.Session_Response0 || !reply ||
+          reply.status !== proto.Status.Success || reply.devicePubkey?.length !== 32 ||
+          reply.deviceRandom?.length !== 16) {
+        throw new Error('Invalid Security1 key exchange response');
+      }
+      this.devicePublicKey = new Uint8Array(reply.devicePubkey);
+      const peerKey = await crypto.subtle.importKey(
+        'raw', new Uint8Array(this.devicePublicKey), 'X25519', false, []
+      );
+      const sharedKey = new Uint8Array(await crypto.subtle.deriveBits(
+        { name: 'X25519', public: peerKey }, this.keyPair.privateKey, 256
+      ));
+      this.keyPair = undefined;
+      try {
+        if (this.proofOfPossession.length > 0) {
+          const hash = await sha256(stringToBytes(this.proofOfPossession));
+          for (let i = 0; i < sharedKey.length; i++) sharedKey[i] ^= hash[i];
+          hash.fill(0);
+        }
+        this.proofOfPossession = '';
+        this.cipher = await AESCTRStream.create(sharedKey, reply.deviceRandom);
+      } finally {
+        sharedKey.fill(0);
+      }
+      this.phase = 'command1';
+      return;
+    }
+    if (this.phase === 'response1' && this.cipher && this.publicKey) {
+      const reply = payload.sr1;
+      if (payload.msg !== proto.Sec1MsgType.Session_Response1 || !reply ||
+          reply.status !== proto.Status.Success || reply.deviceVerifyData?.length !== 32) {
+        throw new Error('Security1 authentication failed');
+      }
+      const verified = await this.cipher.update(reply.deviceVerifyData);
+      let difference = 0;
+      for (let i = 0; i < this.publicKey.length; i++) difference |= verified[i] ^ this.publicKey[i];
+      if (difference !== 0) throw new Error('Security1 device verification failed');
+      this.phase = 'established';
+      return;
+    }
+    throw new Error('Unexpected Security1 handshake response');
+  }
+
+  async encrypt(data: Uint8Array): Promise<Uint8Array> {
+    if (!this.isEstablished() || !this.cipher) throw new Error('Security1 session not established');
+    return this.cipher.update(data);
+  }
+
+  async decrypt(data: Uint8Array): Promise<Uint8Array> {
+    return this.encrypt(data);
+  }
+
+  isEstablished(): boolean {
+    return this.phase === 'established';
+  }
+}

package/src/transport/SoftAPTransport.ts

@@ -14,7 +14,7 @@ export class SoftAPTransport extends Transport {
    */
   constructor(baseUrl: string) {
     super();
-    this.baseUrl = baseUrl;
+    this.baseUrl = baseUrl.replace(/\/$/, '');
   }
 
   async connect(): Promise<void> {
@@ -54,7 +54,7 @@ export class SoftAPTransport extends Transport {
           'Accept': 'text/plain',
           'Content-Type': 'application/x-www-form-urlencoded',
         },
-        body: data.buffer as ArrayBuffer,
+        body: new Uint8Array(data),
         mode: 'cors',
       });
 

package/src/types.ts

@@ -1,3 +1,19 @@
+/** Public proto-ver metadata, including application-defined capability lists. */
+export interface ESPProvisioningMetadata {
+  ver?: string;
+  cap?: string[];
+}
+
+export interface ESPProvisioningInfo {
+  prov: ESPProvisioningMetadata & { sec_ver?: number; sec_patch_ver?: number };
+  [name: string]: ESPProvisioningMetadata;
+}
+
+/** Resolve the security configuration after reading public discovery data. */
+export type ESPSecurityResolver = (
+  info: ESPProvisioningInfo
+) => ESPSecurityConfig | undefined | Promise<ESPSecurityConfig | undefined>;
+
 export type ESPSecurityConfig = ESPSecurity1Config | ESPSecurity2Config;
 
 export interface ESPSecurity1Config {
@@ -72,7 +88,7 @@ export interface ESPScanStatusResponse {
  * Device interface for ESP provisioning
  */
 export interface ESPDeviceInterface {
-  connect(security?: ESPSecurityConfig): Promise<void>;
+  connect(security?: ESPSecurityConfig | ESPSecurityResolver): Promise<void>;
 
   scanWifiList(): Promise<ESPWifiAp[]>;
 

package/src/utils/crypto.ts

@@ -49,7 +49,7 @@ export function bytesToString(bytes: Uint8Array): string {
  * SHA-256 hash function
  */
 export async function sha256(data: Uint8Array): Promise<Uint8Array> {
-  const hashBuffer = await crypto.subtle.digest('SHA-256', data.buffer as ArrayBuffer);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', new Uint8Array(data));
   return new Uint8Array(hashBuffer);
 }
 
@@ -59,12 +59,12 @@ export async function sha256(data: Uint8Array): Promise<Uint8Array> {
 export async function hmacSha256(key: Uint8Array, data: Uint8Array): Promise<Uint8Array> {
   const cryptoKey = await crypto.subtle.importKey(
     'raw',
-    key.buffer as ArrayBuffer,
+    new Uint8Array(key),
     { name: 'HMAC', hash: 'SHA-256' },
     false,
     ['sign']
   );
-  const signature = await crypto.subtle.sign('HMAC', cryptoKey, data.buffer as ArrayBuffer);
+  const signature = await crypto.subtle.sign('HMAC', cryptoKey, new Uint8Array(data));
   return new Uint8Array(signature);
 }
 
@@ -78,15 +78,15 @@ export async function aesEncrypt(
 ): Promise<Uint8Array> {
   const cryptoKey = await crypto.subtle.importKey(
     'raw',
-    key.buffer as ArrayBuffer,
+    new Uint8Array(key),
     { name: 'AES-CTR' },
     false,
     ['encrypt']
   );
   const encrypted = await crypto.subtle.encrypt(
-    { name: 'AES-CTR', counter: counter.buffer as ArrayBuffer, length: 128 },
+    { name: 'AES-CTR', counter: new Uint8Array(counter), length: 128 },
     cryptoKey,
-    data.buffer as ArrayBuffer
+    new Uint8Array(data)
   );
   return new Uint8Array(encrypted);
 }
@@ -101,15 +101,15 @@ export async function aesDecrypt(
 ): Promise<Uint8Array> {
   const cryptoKey = await crypto.subtle.importKey(
     'raw',
-    key.buffer as ArrayBuffer,
+    new Uint8Array(key),
     { name: 'AES-CTR' },
     false,
     ['decrypt']
   );
   const decrypted = await crypto.subtle.decrypt(
-    { name: 'AES-CTR', counter: counter.buffer as ArrayBuffer, length: 128 },
+    { name: 'AES-CTR', counter: new Uint8Array(counter), length: 128 },
     cryptoKey,
-    data.buffer as ArrayBuffer
+    new Uint8Array(data)
   );
   return new Uint8Array(decrypted);
 }
@@ -127,3 +127,37 @@ export function concatBytes(...arrays: Uint8Array[]): Uint8Array {
   }
   return result;
 }
+
+/** Stateful AES-CTR, preserving partial blocks across requests and responses. */
+export class AESCTRStream {
+  private offset = 0;
+
+  private constructor(private key: CryptoKey, private counter: Uint8Array<ArrayBuffer>) {}
+
+  static async create(key: Uint8Array, counter: Uint8Array): Promise<AESCTRStream> {
+    if (key.length !== 32 || counter.length !== 16) throw new Error('Invalid AES-256-CTR parameters');
+    const cryptoKey = await crypto.subtle.importKey(
+      'raw', new Uint8Array(key), 'AES-CTR', false, ['encrypt']
+    );
+    return new AESCTRStream(cryptoKey, new Uint8Array(counter));
+  }
+
+  async update(data: Uint8Array): Promise<Uint8Array> {
+    // Web Crypto restarts at a block boundary. Skip the already-consumed bytes
+    // of the current block to match mbedTLS's continuous stream in both directions.
+    const input = new Uint8Array(this.offset + data.length);
+    input.set(data, this.offset);
+    const output = await crypto.subtle.encrypt(
+      { name: 'AES-CTR', counter: this.counter, length: 128 }, this.key, input
+    );
+    const result = new Uint8Array(output).slice(this.offset);
+    let blocks = Math.floor(input.length / 16);
+    for (let i = this.counter.length - 1; i >= 0 && blocks > 0; i--) {
+      const sum = this.counter[i] + blocks;
+      this.counter[i] = sum & 0xff;
+      blocks = Math.floor(sum / 256);
+    }
+    this.offset = input.length % 16;
+    return result;
+  }
+}