@bota-dev/react-native-sdk 0.0.7 → 0.0.8

package/src/managers/DeviceManager.ts

@@ -11,6 +11,7 @@ import {
   SERVICE_DEVICE_INFO,
   SERVICE_BOTA_PROVISIONING,
   SERVICE_BOTA_CONTROL,
+  SERVICE_BOTA_WIFI_CONFIG,
   CHAR_SERIAL_NUMBER,
   CHAR_FIRMWARE_REVISION,
   CHAR_HARDWARE_REVISION,
@@ -22,6 +23,9 @@ import {
   CHAR_RECORDING_CONTROL,
   CHAR_RECORDING_STATUS,
   CHAR_TIME_SYNC,
+  CHAR_WIFI_GRANT,
+  CHAR_WIFI_CREDENTIAL,
+  CHAR_WIFI_STATUS,
   API_ENDPOINT_PRODUCTION,
   API_ENDPOINT_SANDBOX,
   PROVISIONING_SUCCESS,
@@ -41,6 +45,9 @@ import {
   parsePairingState,
   parseDeviceStatus,
   createTimeSyncData,
+  parseWiFiStatusInfo,
+  parseWiFiConfigResult,
+  createWiFiGrantPacket,
 } from '../ble/parsers';
 import type {
   DiscoveredDevice,
@@ -53,6 +60,10 @@ import type {
   // RecordingCommand, // TODO: Re-enable when used
   StartRecordingOptions,
   StopRecordingOptions,
+  WiFiConfigGrant,
+  WiFiCredentials,
+  WiFiConfigResult,
+  WiFiStatusInfo,
 } from '../models/Device';
 import type { DeviceManagerEvents } from '../models/Status';
 import {
@@ -60,6 +71,11 @@ import {
   ProvisioningError,
 } from '../utils/errors';
 import { logger } from '../utils/logger';
+import {
+  deriveSessionKey,
+  encryptWiFiCredentials,
+  formatWiFiCredentialPacket,
+} from '../utils/crypto';
 
 const log = logger.tag('DeviceManager');
 
@@ -776,6 +792,234 @@ export class DeviceManager extends EventEmitter<DeviceManagerEvents> {
     };
   }
 
+  // ============================================================================
+  // WiFi Upload Configuration
+  // ============================================================================
+
+  /**
+   * Configure WiFi credentials on device via BLE.
+   * Requires a WiFi configuration grant from backend.
+   *
+   * @param deviceId - Connected device ID
+   * @param credentials - WiFi network credentials
+   * @param grant - WiFi config grant from backend
+   * @returns Configuration result
+   *
+   * @example
+   * ```typescript
+   * // 1. Get grant from backend
+   * const grant = await api.createWiFiConfigGrant(deviceId);
+   *
+   * // 2. Configure device via BLE
+   * const result = await deviceManager.configureWiFi(
+   *   deviceId,
+   *   { ssid: 'MyNetwork', password: 'password123', securityType: 'WPA2' },
+   *   grant
+   * );
+   *
+   * if (result.success) {
+   *   console.log('WiFi configured successfully');
+   * }
+   * ```
+   */
+  async configureWiFi(
+    deviceId: string,
+    credentials: WiFiCredentials,
+    grant: WiFiConfigGrant
+  ): Promise<WiFiConfigResult> {
+    log.info('Configuring WiFi on device', { deviceId, ssid: credentials.ssid });
+
+    try {
+      // Step 1: Submit WiFi config grant to device
+      const grantPacket = createWiFiGrantPacket(grant.grantBlob);
+      await this.bleManager.writeCharacteristic(
+        deviceId,
+        SERVICE_BOTA_WIFI_CONFIG,
+        CHAR_WIFI_GRANT,
+        grantPacket
+      );
+
+      log.debug('WiFi grant submitted');
+
+      // Step 2: Derive K_session from grant
+      const sessionKey = deriveSessionKey(grant.grantBlob);
+
+      // Step 3: Encrypt WiFi credentials with K_session
+      const encrypted = encryptWiFiCredentials(
+        credentials.ssid,
+        credentials.password,
+        sessionKey
+      );
+
+      // Step 4: Format credential packet for BLE transmission
+      const credentialPacket = formatWiFiCredentialPacket(encrypted);
+
+      log.debug('Sending encrypted WiFi credentials', {
+        packetSize: credentialPacket.length,
+      });
+
+      // Step 5: Write encrypted credentials to device
+      await this.bleManager.writeCharacteristic(
+        deviceId,
+        SERVICE_BOTA_WIFI_CONFIG,
+        CHAR_WIFI_CREDENTIAL,
+        credentialPacket
+      );
+
+      // Step 6: Wait for configuration result
+      const result = await this.waitForWiFiConfigResult(deviceId);
+
+      if (result.success) {
+        log.info('WiFi configuration successful', { deviceId });
+      } else {
+        log.warn('WiFi configuration failed', { deviceId, error: result.error });
+      }
+
+      return result;
+    } catch (error) {
+      log.error('WiFi configuration error', error instanceof Error ? error : undefined);
+      throw new DeviceError(
+        `Failed to configure WiFi: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'WIFI_CONFIG_ERROR',
+        deviceId,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Get WiFi connection status from device.
+   *
+   * @param deviceId - Connected device ID
+   * @returns WiFi status information
+   *
+   * @example
+   * ```typescript
+   * const status = await deviceManager.getWiFiStatus(deviceId);
+   * console.log('WiFi status:', status.status);
+   * if (status.status === 'connected') {
+   *   console.log('Connected to:', status.ssid);
+   *   console.log('Signal strength:', status.signalStrength);
+   * }
+   * ```
+   */
+  async getWiFiStatus(deviceId: string): Promise<WiFiStatusInfo> {
+    log.debug('Reading WiFi status', { deviceId });
+
+    try {
+      const data = await this.bleManager.readCharacteristic(
+        deviceId,
+        SERVICE_BOTA_WIFI_CONFIG,
+        CHAR_WIFI_STATUS
+      );
+
+      const status = parseWiFiStatusInfo(data);
+
+      log.debug('WiFi status', { deviceId, status: status.status, ssid: status.ssid });
+
+      return status;
+    } catch (error) {
+      log.error('Failed to read WiFi status', error instanceof Error ? error : undefined);
+      throw new DeviceError(
+        `Failed to read WiFi status: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'WIFI_STATUS_ERROR',
+        deviceId,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Subscribe to WiFi status updates from device.
+   *
+   * @param deviceId - Connected device ID
+   * @param callback - Callback function for status updates
+   * @returns Subscription object (call .remove() to unsubscribe)
+   *
+   * @example
+   * ```typescript
+   * const subscription = deviceManager.subscribeToWiFiStatus(deviceId, (status) => {
+   *   console.log('WiFi status update:', status.status);
+   *   if (status.status === 'connected') {
+   *     console.log('Connected to:', status.ssid);
+   *   } else if (status.status === 'failed') {
+   *     console.error('Connection failed:', status.lastError);
+   *   }
+   * });
+   *
+   * // Later: unsubscribe
+   * subscription.remove();
+   * ```
+   */
+  subscribeToWiFiStatus(
+    deviceId: string,
+    callback: (status: WiFiStatusInfo) => void
+  ): Subscription {
+    log.debug('Subscribing to WiFi status', { deviceId });
+
+    return this.bleManager.subscribeToCharacteristic(
+      deviceId,
+      SERVICE_BOTA_WIFI_CONFIG,
+      CHAR_WIFI_STATUS,
+      (data) => {
+        try {
+          const status = parseWiFiStatusInfo(data);
+          callback(status);
+        } catch (error) {
+          log.error('Failed to parse WiFi status', error instanceof Error ? error : undefined);
+        }
+      },
+      (error) => {
+        log.error('WiFi status subscription error', error);
+      }
+    );
+  }
+
+  /**
+   * Wait for WiFi configuration result from device.
+   */
+  private waitForWiFiConfigResult(deviceId: string): Promise<WiFiConfigResult> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        subscription.remove();
+        reject(new DeviceError(
+          'WiFi configuration timeout',
+          'WIFI_CONFIG_TIMEOUT',
+          deviceId
+        ));
+      }, OPERATION_TIMEOUT);
+
+      const subscription = this.bleManager.subscribeToCharacteristic(
+        deviceId,
+        SERVICE_BOTA_WIFI_CONFIG,
+        CHAR_WIFI_STATUS,
+        (data) => {
+          try {
+            // Configuration result comes via status updates
+            const result = parseWiFiConfigResult(data);
+
+            clearTimeout(timeout);
+            subscription.remove();
+            resolve(result);
+          } catch (error) {
+            // Ignore parse errors, wait for valid result
+            log.debug('Ignoring invalid WiFi config result', { error: error instanceof Error ? error.message : String(error) });
+          }
+        },
+        (error) => {
+          clearTimeout(timeout);
+          subscription.remove();
+          reject(new DeviceError(
+            `WiFi config result error: ${error.message}`,
+            'WIFI_CONFIG_RESULT_ERROR',
+            deviceId,
+            error
+          ));
+        }
+      );
+    });
+  }
+
   /**
    * Clean up resources
    */

package/src/models/Device.ts

@@ -76,6 +76,20 @@ export interface DiscoveredDevice {
   discoveredAt: Date;
 }
 
+/**
+ * Device capabilities (bitmask)
+ */
+export interface DeviceCapabilities {
+  /** Supports Bluetooth Sync (BLE transfer) */
+  bleSync: boolean;
+  /** Supports WiFi Upload */
+  wifiUpload: boolean;
+  /** Supports Cellular Upload (4G/LTE) */
+  lteUpload: boolean;
+  /** Supports Remote Recording Control */
+  remoteRecord: boolean;
+}
+
 /**
  * Device after successful BLE connection
  */
@@ -96,6 +110,8 @@ export interface ConnectedDevice {
   connectionState: ConnectionState;
   /** Negotiated MTU size */
   mtu: number;
+  /** Device capabilities */
+  capabilities?: DeviceCapabilities;
 }
 
 /**
@@ -255,3 +271,63 @@ export interface RecordingState {
   /** Who initiated the recording */
   initiatedBy?: 'local' | 'remote';
 }
+
+// ============================================================================
+// WiFi Upload Configuration Types
+// ============================================================================
+
+/**
+ * WiFi security type
+ */
+export type WiFiSecurityType = 'WPA2' | 'WPA3' | 'WEP' | 'OPEN';
+
+/**
+ * WiFi connection status
+ */
+export type WiFiStatus = 'idle' | 'connecting' | 'connected' | 'failed' | 'disconnected';
+
+/**
+ * WiFi configuration grant from backend
+ */
+export interface WiFiConfigGrant {
+  /** Grant blob (JWT token) */
+  grantBlob: string;
+  /** Expiration timestamp */
+  expiresAt: Date;
+}
+
+/**
+ * WiFi credentials to configure
+ */
+export interface WiFiCredentials {
+  /** WiFi network SSID */
+  ssid: string;
+  /** WiFi password */
+  password: string;
+  /** Security type (default: WPA2) */
+  securityType?: WiFiSecurityType;
+}
+
+/**
+ * WiFi configuration result from device
+ */
+export interface WiFiConfigResult {
+  /** Whether configuration was successful */
+  success: boolean;
+  /** Error code if failed */
+  error?: 'invalid_grant' | 'grant_expired' | 'decryption_error' | 'storage_error' | 'unknown';
+}
+
+/**
+ * WiFi status information from device
+ */
+export interface WiFiStatusInfo {
+  /** Current WiFi connection status */
+  status: WiFiStatus;
+  /** Connected SSID (if connected) */
+  ssid?: string;
+  /** Signal strength (0-100) */
+  signalStrength?: number;
+  /** Last connection error (if failed) */
+  lastError?: string;
+}

package/src/utils/crypto.ts

@@ -0,0 +1,221 @@
+/**
+ * Cryptographic utilities for WiFi Upload configuration
+ *
+ * NOTE: This module requires react-native-quick-crypto to be installed.
+ * Add to your app: npm install react-native-quick-crypto
+ */
+
+import { Buffer } from 'buffer';
+
+// Type-only import to avoid runtime errors if crypto is not installed
+type CryptoModule = typeof import('crypto');
+
+/**
+ * Get crypto module (lazy loaded to avoid errors if not installed)
+ */
+function getCrypto(): CryptoModule {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require('react-native-quick-crypto') as CryptoModule;
+  } catch {
+    throw new Error(
+      'WiFi Upload requires react-native-quick-crypto. ' +
+      'Install it with: npm install react-native-quick-crypto'
+    );
+  }
+}
+
+/**
+ * Derive K_session from WiFi config grant.
+ * K_session is used by device and app to encrypt/decrypt WiFi credentials in transit.
+ *
+ * Derivation: K_session = HMAC-SHA256(grant_blob, "BOTA_WIFI_SESSION_V1")
+ *
+ * @param grantBlob - Base64-encoded JWT grant from backend
+ * @returns 32-byte K_session as hex string
+ */
+export function deriveSessionKey(grantBlob: string): string {
+  const crypto = getCrypto();
+
+  return crypto
+    .createHmac('sha256', grantBlob)
+    .update('BOTA_WIFI_SESSION_V1')
+    .digest('hex');
+}
+
+/**
+ * Encrypt WiFi credentials for BLE transmission using ChaCha20-Poly1305.
+ *
+ * Format sent to device:
+ * - 12 bytes: nonce (random)
+ * - N bytes: encrypted SSID
+ * - 16 bytes: auth tag for SSID
+ * - M bytes: encrypted password
+ * - 16 bytes: auth tag for password
+ *
+ * @param ssid - WiFi network SSID
+ * @param password - WiFi password
+ * @param sessionKey - K_session derived from grant (hex string)
+ * @returns Encrypted payload ready for BLE transmission
+ */
+export function encryptWiFiCredentials(
+  ssid: string,
+  password: string,
+  sessionKey: string
+): {
+  nonce: Buffer;
+  ssidEncrypted: Buffer;
+  ssidAuthTag: Buffer;
+  passwordEncrypted: Buffer;
+  passwordAuthTag: Buffer;
+} {
+  const crypto = getCrypto();
+
+  // Convert session key from hex to Buffer
+  const keyBuffer = Buffer.from(sessionKey, 'hex');
+
+  // Generate random nonce (12 bytes for ChaCha20-Poly1305)
+  const nonce = crypto.randomBytes(12);
+
+  // Encrypt SSID
+  const ssidCipher = crypto.createCipheriv('chacha20-poly1305', keyBuffer, nonce, {
+    authTagLength: 16,
+  });
+  const ssidEncrypted = Buffer.concat([
+    ssidCipher.update(ssid, 'utf-8'),
+    ssidCipher.final(),
+  ]);
+  const ssidAuthTag = ssidCipher.getAuthTag();
+
+  // Encrypt password (reuse same nonce with different additional data)
+  const passwordCipher = crypto.createCipheriv('chacha20-poly1305', keyBuffer, nonce, {
+    authTagLength: 16,
+  });
+  // Use different AAD to prevent nonce reuse issues
+  passwordCipher.setAAD(Buffer.from('password'), { plaintextLength: Buffer.byteLength(password, 'utf-8') });
+  const passwordEncrypted = Buffer.concat([
+    passwordCipher.update(password, 'utf-8'),
+    passwordCipher.final(),
+  ]);
+  const passwordAuthTag = passwordCipher.getAuthTag();
+
+  return {
+    nonce,
+    ssidEncrypted,
+    ssidAuthTag,
+    passwordEncrypted,
+    passwordAuthTag,
+  };
+}
+
+/**
+ * Decrypt WiFi credentials received from device (if needed for verification).
+ *
+ * @param encrypted - Encrypted SSID or password
+ * @param nonce - 12-byte nonce
+ * @param authTag - 16-byte authentication tag
+ * @param sessionKey - K_session derived from grant (hex string)
+ * @param aad - Additional authenticated data (optional, use 'password' for password field)
+ * @returns Decrypted plaintext
+ */
+export function decryptWiFiCredential(
+  encrypted: Buffer,
+  nonce: Buffer,
+  authTag: Buffer,
+  sessionKey: string,
+  aad?: string
+): string {
+  const crypto = getCrypto();
+
+  // Convert session key from hex to Buffer
+  const keyBuffer = Buffer.from(sessionKey, 'hex');
+
+  // Decrypt with ChaCha20-Poly1305
+  const decipher = crypto.createDecipheriv('chacha20-poly1305', keyBuffer, nonce, {
+    authTagLength: 16,
+  });
+
+  decipher.setAuthTag(authTag);
+
+  if (aad) {
+    decipher.setAAD(Buffer.from(aad), { plaintextLength: encrypted.length });
+  }
+
+  const decrypted = Buffer.concat([
+    decipher.update(encrypted),
+    decipher.final(),
+  ]);
+
+  return decrypted.toString('utf-8');
+}
+
+/**
+ * Format encrypted WiFi credentials for BLE transmission.
+ *
+ * Packet format:
+ * [nonce (12 bytes)][ssid_encrypted (N bytes)][ssid_tag (16 bytes)]
+ * [password_encrypted (M bytes)][password_tag (16 bytes)]
+ *
+ * @param encrypted - Result from encryptWiFiCredentials
+ * @returns Single buffer ready for BLE write
+ */
+export function formatWiFiCredentialPacket(encrypted: {
+  nonce: Buffer;
+  ssidEncrypted: Buffer;
+  ssidAuthTag: Buffer;
+  passwordEncrypted: Buffer;
+  passwordAuthTag: Buffer;
+}): Buffer {
+  return Buffer.concat([
+    encrypted.nonce,
+    encrypted.ssidEncrypted,
+    encrypted.ssidAuthTag,
+    encrypted.passwordEncrypted,
+    encrypted.passwordAuthTag,
+  ]);
+}
+
+/**
+ * Parse encrypted WiFi credential packet received from device.
+ *
+ * @param packet - Buffer received from BLE
+ * @param ssidLength - Expected SSID encrypted length
+ * @param passwordLength - Expected password encrypted length
+ * @returns Parsed components
+ */
+export function parseWiFiCredentialPacket(
+  packet: Buffer,
+  ssidLength: number,
+  passwordLength: number
+): {
+  nonce: Buffer;
+  ssidEncrypted: Buffer;
+  ssidAuthTag: Buffer;
+  passwordEncrypted: Buffer;
+  passwordAuthTag: Buffer;
+} {
+  let offset = 0;
+
+  const nonce = packet.subarray(offset, offset + 12);
+  offset += 12;
+
+  const ssidEncrypted = packet.subarray(offset, offset + ssidLength);
+  offset += ssidLength;
+
+  const ssidAuthTag = packet.subarray(offset, offset + 16);
+  offset += 16;
+
+  const passwordEncrypted = packet.subarray(offset, offset + passwordLength);
+  offset += passwordLength;
+
+  const passwordAuthTag = packet.subarray(offset, offset + 16);
+  offset += 16;
+
+  return {
+    nonce,
+    ssidEncrypted,
+    ssidAuthTag,
+    passwordEncrypted,
+    passwordAuthTag,
+  };
+}

package/src/utils/index.ts

@@ -5,3 +5,4 @@
 export * from './errors';
 export { logger } from './logger';
 export * from './retry';
+export * from './crypto';