@vailix/mask 0.1.2

package/dist/index.mjs

@@ -0,0 +1,1058 @@
+// src/index.ts
+import { createCipheriv, randomBytes } from "react-native-quick-crypto";
+
+// src/identity.ts
+import { createHmac, randomUUID } from "react-native-quick-crypto";
+import * as SecureStore from "expo-secure-store";
+
+// src/utils.ts
+var EMOJIS = ["\u{1F43C}", "\u{1F98A}", "\u{1F428}", "\u{1F981}", "\u{1F42F}", "\u{1F438}", "\u{1F98B}", "\u{1F419}", "\u{1F984}", "\u{1F433}"];
+function generateDisplayName(rpiPrefix) {
+  const hash = rpiPrefix.split("").reduce((a, b) => a + b.charCodeAt(0), 0);
+  const emoji = EMOJIS[hash % EMOJIS.length];
+  const number = hash % 100;
+  return `${emoji} ${number}`;
+}
+
+// src/identity.ts
+var MASTER_KEY_STORE = "vailix_master_key";
+var DEFAULT_EPOCH_MS = 15 * 60 * 1e3;
+var DefaultKeyStorage = class {
+  async getKey() {
+    return SecureStore.getItemAsync(MASTER_KEY_STORE);
+  }
+  async setKey(key) {
+    await SecureStore.setItemAsync(MASTER_KEY_STORE, key);
+  }
+};
+var IdentityManager = class {
+  masterKey = null;
+  epochMs;
+  keyStorage;
+  constructor(config = {}) {
+    this.epochMs = config.rpiDurationMs ?? DEFAULT_EPOCH_MS;
+    this.keyStorage = config.keyStorage ?? new DefaultKeyStorage();
+  }
+  async initialize() {
+    try {
+      let key = await this.keyStorage.getKey();
+      if (!key) {
+        key = randomUUID();
+        await this.keyStorage.setKey(key);
+      }
+      this.masterKey = key;
+    } catch (error) {
+      throw new Error(`Failed to initialize identity: ${error}`);
+    }
+  }
+  getCurrentRPI() {
+    if (!this.masterKey) throw new Error("Not initialized");
+    return this._generateRPI(Math.floor(Date.now() / this.epochMs));
+  }
+  // Get RPI history for the past N days
+  // Note: Synchronous HMAC computation. For STD apps (24h RPI) = 14 calls.
+  // For contact tracing (15min RPI) = 1,344 calls - acceptable on modern devices.
+  getHistory(days) {
+    if (!this.masterKey) throw new Error("Not initialized");
+    const epochsPerDay = 24 * 60 * 60 * 1e3 / this.epochMs;
+    const currentEpoch = Math.floor(Date.now() / this.epochMs);
+    return Array.from(
+      { length: days * epochsPerDay },
+      (_, i) => this._generateRPI(currentEpoch - i)
+    );
+  }
+  // Generate 128-bit Rolling Proximity Identifier (RPI) for the given epoch.
+  _generateRPI(epoch) {
+    return createHmac("sha256", this.masterKey).update(epoch.toString()).digest("hex").substring(0, 32);
+  }
+  // Generate a key specifically for encrypting metadata for an RPI
+  getMetadataKey(rpi) {
+    if (!this.masterKey) throw new Error("Not initialized");
+    return createHmac("sha256", this.masterKey).update(`meta:${rpi}`).digest("hex").substring(0, 64);
+  }
+  // Get master key for database encryption (SQLCipher)
+  getMasterKey() {
+    if (!this.masterKey) throw new Error("Not initialized");
+    return this.masterKey;
+  }
+  /**
+   * Get anonymous display name derived from current RPI.
+   * Used for showing user's identity in UI without revealing master key.
+   * Format: "Emoji Number" (e.g. "🐼 42")
+   */
+  getDisplayName() {
+    const rpi = this.getCurrentRPI();
+    return generateDisplayName(rpi.substring(0, 16));
+  }
+};
+
+// src/storage.ts
+import { sqliteTable, text, integer, index } from "drizzle-orm/sqlite-core";
+import { lt, gt, inArray } from "drizzle-orm";
+import { randomUUID as randomUUID2 } from "react-native-quick-crypto";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+var SCAN_HISTORY_KEY = "vailix_scan_history";
+var scannedEvents = sqliteTable("scanned_events", {
+  id: text("id").primaryKey(),
+  rpi: text("rpi").notNull(),
+  metadataKey: text("metadata_key").notNull(),
+  timestamp: integer("timestamp").notNull()
+}, (t) => [index("rpi_idx").on(t.rpi)]);
+var StorageService = class _StorageService {
+  constructor(db, config = {}) {
+    this.db = db;
+    this.rescanIntervalMs = config.rescanIntervalMs ?? 0;
+  }
+  rescanIntervalMs;
+  lastScanByRpi = /* @__PURE__ */ new Map();
+  // Limit scan history to prevent unbounded memory growth
+  static MAX_SCAN_HISTORY_SIZE = 1e4;
+  // Load persisted scan history on init
+  async initialize() {
+    const stored = await AsyncStorage.getItem(SCAN_HISTORY_KEY);
+    if (stored) {
+      const entries = JSON.parse(stored);
+      this.lastScanByRpi = new Map(entries);
+    }
+  }
+  // Check if rescan is allowed for this RPI
+  canScan(rpi) {
+    if (this.rescanIntervalMs === 0) return true;
+    const lastScan = this.lastScanByRpi.get(rpi);
+    if (!lastScan) return true;
+    return Date.now() - lastScan >= this.rescanIntervalMs;
+  }
+  async logScan(rpi, metadataKey, timestamp) {
+    await this.db.insert(scannedEvents).values({ id: randomUUID2(), rpi, metadataKey, timestamp });
+    this.lastScanByRpi.set(rpi, Date.now());
+    if (this.lastScanByRpi.size > _StorageService.MAX_SCAN_HISTORY_SIZE) {
+      const entries2 = Array.from(this.lastScanByRpi.entries());
+      entries2.sort((a, b) => a[1] - b[1]);
+      const toRemove = entries2.slice(0, entries2.length - _StorageService.MAX_SCAN_HISTORY_SIZE);
+      for (const [key] of toRemove) {
+        this.lastScanByRpi.delete(key);
+      }
+    }
+    const entries = Array.from(this.lastScanByRpi.entries());
+    await AsyncStorage.setItem(SCAN_HISTORY_KEY, JSON.stringify(entries));
+  }
+  async cleanupOldScans() {
+    const cutoff = Date.now() - 14 * 24 * 60 * 60 * 1e3;
+    await this.db.delete(scannedEvents).where(lt(scannedEvents.timestamp, cutoff));
+    if (this.rescanIntervalMs > 0) {
+      const now = Date.now();
+      for (const [rpi, lastScan] of this.lastScanByRpi) {
+        if (now - lastScan > this.rescanIntervalMs) {
+          this.lastScanByRpi.delete(rpi);
+        }
+      }
+      const entries = Array.from(this.lastScanByRpi.entries());
+      await AsyncStorage.setItem(SCAN_HISTORY_KEY, JSON.stringify(entries));
+    }
+  }
+  // Get only scans matching the given RPIs (efficient DB-level filtering)
+  // Batches queries to respect SQLite variable limits
+  async getMatchingScans(rpiList) {
+    if (rpiList.length === 0) return [];
+    const BATCH_SIZE = 500;
+    const results = [];
+    for (let i = 0; i < rpiList.length; i += BATCH_SIZE) {
+      const batch = rpiList.slice(i, i + BATCH_SIZE);
+      const batchResults = await this.db.select().from(scannedEvents).where(inArray(scannedEvents.rpi, batch));
+      results.push(...batchResults);
+    }
+    return results;
+  }
+  async getRecentPairs(withinHours = 24) {
+    const cutoff = Date.now() - withinHours * 60 * 60 * 1e3;
+    const recent = await this.db.select().from(scannedEvents).where(gt(scannedEvents.timestamp, cutoff)).orderBy(scannedEvents.timestamp);
+    return recent;
+  }
+};
+
+// src/matcher.ts
+import AsyncStorage2 from "@react-native-async-storage/async-storage";
+import { createDecipheriv } from "react-native-quick-crypto";
+import { EventEmitter } from "eventemitter3";
+var LAST_SYNC_KEY = "vailix_last_sync";
+var MatcherService = class extends EventEmitter {
+  constructor(storage, downloadUrl, appSecret) {
+    super();
+    this.storage = storage;
+    this.downloadUrl = downloadUrl;
+    this.appSecret = appSecret;
+  }
+  async fetchAndMatch() {
+    try {
+      let lastSync = parseInt(await AsyncStorage2.getItem(LAST_SYNC_KEY) || "0", 10);
+      const allMatches = [];
+      let maxReportedAt = lastSync;
+      await this._downloadAndProcessKeys(lastSync, async (keys) => {
+        if (keys.length === 0) return;
+        const pageMax = Math.max(...keys.map((k) => k.reportedAt));
+        maxReportedAt = Math.max(maxReportedAt, pageMax);
+        const infectedMap = /* @__PURE__ */ new Map();
+        for (const key of keys) infectedMap.set(key.rpi, key);
+        const infectedRpis = Array.from(infectedMap.keys());
+        const matchingScans = await this.storage.getMatchingScans(infectedRpis);
+        for (const s of matchingScans) {
+          const serverKey = infectedMap.get(s.rpi);
+          await AsyncStorage2.setItem(`vailix_match_cache_${s.rpi}`, JSON.stringify({
+            encryptedMetadata: serverKey.metadata,
+            // Still encrypted from server
+            metadataKey: s.metadataKey,
+            // Decryption key
+            timestamp: s.timestamp,
+            reportedAt: serverKey.reportedAt
+          }));
+          allMatches.push({
+            rpi: s.rpi,
+            timestamp: s.timestamp,
+            metadata: void 0,
+            // Not decrypted yet!
+            reportedAt: serverKey.reportedAt
+          });
+        }
+      });
+      if (maxReportedAt > lastSync) {
+        await AsyncStorage2.setItem(LAST_SYNC_KEY, maxReportedAt.toString());
+      }
+      if (allMatches.length > 0) {
+        this.emit("match", allMatches);
+      }
+      await this.storage.cleanupOldScans();
+      return allMatches;
+    } catch (error) {
+      this.emit("error", error);
+      return [];
+    }
+  }
+  async _downloadAndProcessKeys(since, processor) {
+    let cursor = null;
+    do {
+      const url = new URL(`${this.downloadUrl}/v1/download`);
+      url.searchParams.set("since", since.toString());
+      if (cursor) url.searchParams.set("cursor", cursor);
+      url.searchParams.set("format", "bin");
+      const res = await fetch(url.toString(), {
+        headers: { "x-vailix-secret": this.appSecret }
+      });
+      if (!res.ok) throw new Error(`Server error: ${res.status}`);
+      const buffer = await res.arrayBuffer();
+      const keys = this._parseBinaryResponse(buffer);
+      await processor(keys);
+      cursor = res.headers.get("x-vailix-next-cursor") || null;
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    } while (cursor);
+  }
+  _parseBinaryResponse(buffer) {
+    const view = new DataView(buffer);
+    const keys = [];
+    let offset = 0;
+    if (buffer.byteLength < 4) return [];
+    const count = view.getUint32(offset);
+    offset += 4;
+    for (let i = 0; i < count; i++) {
+      if (offset + 26 > buffer.byteLength) {
+        console.warn(`Binary response truncated at key ${i}/${count}`);
+        break;
+      }
+      const rpiBytes = new Uint8Array(buffer, offset, 16);
+      const rpi = Array.from(rpiBytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+      offset += 16;
+      const reportedAt = view.getFloat64(offset);
+      offset += 8;
+      const metaLen = view.getUint16(offset);
+      offset += 2;
+      let metadata = void 0;
+      if (metaLen > 0) {
+        if (offset + metaLen > buffer.byteLength) {
+          console.warn(`Binary response truncated during metadata at key ${i}/${count}`);
+          break;
+        }
+        const metaBytes = new Uint8Array(buffer, offset, metaLen);
+        metadata = new TextDecoder("utf-8").decode(metaBytes);
+        offset += metaLen;
+      }
+      keys.push({ rpi, reportedAt, metadata });
+    }
+    return keys;
+  }
+  _decrypt(encryptedStr, keyHex) {
+    if (!encryptedStr) return void 0;
+    try {
+      const parts = encryptedStr.split(":");
+      if (parts.length !== 3) return void 0;
+      const [ivB64, authTagB64, encryptedB64] = parts;
+      const key = Buffer.from(keyHex, "hex");
+      const iv = Buffer.from(ivB64, "base64");
+      const authTag = Buffer.from(authTagB64, "base64");
+      const decipher = createDecipheriv("aes-256-gcm", key, iv);
+      decipher.setAuthTag(authTag);
+      let decrypted = decipher.update(encryptedB64, "base64", "utf8");
+      decrypted += decipher.final("utf8");
+      return JSON.parse(decrypted);
+    } catch (e) {
+      console.warn("Failed to decrypt metadata", e);
+      return void 0;
+    }
+  }
+  /**
+   * Retrieve a specific match by RPI with on-demand decryption.
+   * Used when app needs to display exposure details to user.
+   * 
+   * PRIVACY: Decrypted metadata exists ONLY in-memory (return value).
+   * Never persisted to storage.
+   * 
+   * @param rpi - The RPI (match ID) to retrieve
+   * @returns Match with decrypted metadata, or null if not found
+   */
+  async getMatchById(rpi) {
+    try {
+      const cachedData = await AsyncStorage2.getItem(`vailix_match_cache_${rpi}`);
+      if (!cachedData) {
+        console.warn(`Match ${rpi} not found in cache`);
+        return null;
+      }
+      const cached = JSON.parse(cachedData);
+      const decryptedMetadata = this._decrypt(
+        cached.encryptedMetadata,
+        cached.metadataKey
+      );
+      return {
+        rpi,
+        timestamp: cached.timestamp,
+        metadata: decryptedMetadata,
+        reportedAt: cached.reportedAt
+      };
+    } catch (error) {
+      console.error("Failed to get match by ID:", error);
+      return null;
+    }
+  }
+};
+
+// src/ble.ts
+import { BleManager, State } from "react-native-ble-plx";
+var VAILIX_SERVICE_UUID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
+var RPI_OUT_CHAR_UUID = "a1b2c3d4-e5f6-7890-abcd-ef1234567891";
+var RPI_IN_CHAR_UUID = "a1b2c3d4-e5f6-7890-abcd-ef1234567892";
+var META_OUT_CHAR_UUID = "a1b2c3d4-e5f6-7890-abcd-ef1234567893";
+var META_IN_CHAR_UUID = "a1b2c3d4-e5f6-7890-abcd-ef1234567894";
+var DEFAULT_DISCOVERY_TIMEOUT_MS = 15e3;
+var DEFAULT_PROXIMITY_THRESHOLD = -70;
+function extractRpiPrefix(device, serviceUUID) {
+  const serviceData = device.serviceData;
+  if (serviceData && serviceData[serviceUUID]) {
+    const data = serviceData[serviceUUID];
+    if (data && data.length >= 16) {
+      return data.substring(0, 16);
+    }
+  }
+  const mfgData = device.manufacturerData;
+  if (mfgData && mfgData.length >= 16) {
+    return mfgData.substring(0, 16);
+  }
+  return null;
+}
+var BleService = class {
+  manager;
+  isScanning = false;
+  nearbyUsers = /* @__PURE__ */ new Map();
+  pendingRequests = /* @__PURE__ */ new Map();
+  // Configuration
+  discoveryTimeoutMs;
+  proximityThreshold;
+  autoAccept;
+  serviceUUID;
+  // State
+  cleanupInterval;
+  scanSubscription;
+  onNearbyUpdated;
+  // Identity (set when discovery starts)
+  myRpi;
+  myMetadataKey;
+  // Storage reference for persisting pairs
+  storage;
+  constructor(config = {}) {
+    this.manager = new BleManager();
+    this.discoveryTimeoutMs = config.discoveryTimeoutMs ?? DEFAULT_DISCOVERY_TIMEOUT_MS;
+    this.proximityThreshold = config.proximityThreshold ?? DEFAULT_PROXIMITY_THRESHOLD;
+    this.autoAccept = config.autoAccept ?? true;
+    this.serviceUUID = config.serviceUUID ?? VAILIX_SERVICE_UUID;
+  }
+  /**
+   * Set storage service reference (called by SDK)
+   */
+  setStorage(storage) {
+    this.storage = storage;
+  }
+  /**
+   * Check if BLE is available and enabled
+   */
+  async initialize() {
+    return new Promise((resolve) => {
+      const subscription = this.manager.onStateChange((state) => {
+        if (state === State.PoweredOn) {
+          subscription.remove();
+          resolve(true);
+        } else if (state === State.PoweredOff || state === State.Unauthorized) {
+          subscription.remove();
+          resolve(false);
+        }
+      }, true);
+    });
+  }
+  /**
+   * Check if BLE is supported on this device
+   */
+  static async isSupported() {
+    const manager = new BleManager();
+    return new Promise((resolve) => {
+      const subscription = manager.onStateChange((state) => {
+        subscription.remove();
+        manager.destroy();
+        resolve(state !== State.Unsupported);
+      }, true);
+    });
+  }
+  /**
+   * Start advertising our RPI + scanning for others.
+   * Call when pairing screen opens.
+   */
+  async startDiscovery(myRpi, myMetadataKey) {
+    if (this.isScanning) return;
+    this.myRpi = myRpi;
+    this.myMetadataKey = myMetadataKey;
+    this.isScanning = true;
+    this.nearbyUsers.clear();
+    this.startCleanupInterval();
+    await this.startScanning();
+  }
+  /**
+   * Stop advertising and scanning.
+   * Call when leaving pairing screen.
+   */
+  async stopDiscovery() {
+    this.isScanning = false;
+    if (this.scanSubscription) {
+      this.scanSubscription.remove();
+      this.scanSubscription = void 0;
+    }
+    this.manager.stopDeviceScan();
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = void 0;
+    }
+    this.myRpi = void 0;
+    this.myMetadataKey = void 0;
+  }
+  /**
+   * Get current list of nearby users (public type without internal fields)
+   */
+  getNearbyUsers() {
+    return Array.from(this.nearbyUsers.values()).filter((u) => u.rssi >= this.proximityThreshold).map(this.toPublicUser);
+  }
+  /**
+   * Subscribe to nearby user updates.
+   * Returns cleanup function for React useEffect compatibility.
+   */
+  onNearbyUsersChanged(callback) {
+    this.onNearbyUpdated = callback;
+    return () => {
+      this.onNearbyUpdated = void 0;
+    };
+  }
+  /**
+   * Initiate pairing with a specific user.
+   * In explicit consent mode, this also accepts pending incoming requests.
+   */
+  async pairWithUser(userId) {
+    const internalUser = this.nearbyUsers.get(userId);
+    if (!internalUser) {
+      return { success: false, error: "User not found" };
+    }
+    const pendingRequest = this.pendingRequests.get(userId);
+    if (pendingRequest && !this.autoAccept) {
+      return this.acceptPendingRequest(userId, pendingRequest);
+    }
+    try {
+      const result = await this.doExchange(internalUser);
+      return result;
+    } catch (error) {
+      if (internalUser.fullRpi && this.storage) {
+        const alreadyPaired = await this.hasStoredRpi(internalUser.fullRpi);
+        if (alreadyPaired) {
+          return { success: true, partnerRpi: internalUser.fullRpi };
+        }
+      }
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  /**
+   * Unpair with a user (removes from storage and resets status)
+   */
+  async unpairUser(userId) {
+    const internalUser = this.nearbyUsers.get(userId);
+    if (internalUser) {
+      internalUser.paired = false;
+      internalUser.hasIncomingRequest = false;
+      internalUser.fullRpi = void 0;
+      internalUser.metadataKey = void 0;
+      this.pendingRequests.delete(userId);
+      this.emitUpdate();
+    }
+  }
+  /**
+   * Cleanup resources
+   */
+  destroy() {
+    this.stopDiscovery();
+    this.manager.destroy();
+  }
+  // ========================================================================
+  // Private Methods
+  // ========================================================================
+  async startScanning() {
+    this.manager.startDeviceScan(
+      [this.serviceUUID],
+      { allowDuplicates: true },
+      (error, device) => {
+        if (error) {
+          console.warn("BLE scan error:", error);
+          return;
+        }
+        if (device) {
+          this.handleDiscoveredDevice(device);
+        }
+      }
+    );
+  }
+  handleDiscoveredDevice(device) {
+    const rpiPrefix = extractRpiPrefix(device, this.serviceUUID);
+    if (!rpiPrefix) return;
+    const existingUser = this.nearbyUsers.get(device.id);
+    if (existingUser) {
+      existingUser.rssi = device.rssi ?? -100;
+      existingUser.discoveredAt = Date.now();
+    } else {
+      const newUser = {
+        id: device.id,
+        displayName: generateDisplayName(rpiPrefix),
+        rssi: device.rssi ?? -100,
+        discoveredAt: Date.now(),
+        paired: false,
+        hasIncomingRequest: false,
+        rpiPrefix
+      };
+      this.nearbyUsers.set(device.id, newUser);
+    }
+    this.emitUpdate();
+  }
+  startCleanupInterval() {
+    this.cleanupInterval = setInterval(() => {
+      const now = Date.now();
+      let changed = false;
+      for (const [id, user] of this.nearbyUsers) {
+        if (now - user.discoveredAt > this.discoveryTimeoutMs) {
+          this.nearbyUsers.delete(id);
+          this.pendingRequests.delete(id);
+          changed = true;
+        }
+      }
+      if (changed) {
+        this.emitUpdate();
+      }
+    }, 1e3);
+  }
+  async doExchange(user) {
+    if (!this.myRpi || !this.myMetadataKey) {
+      return { success: false, error: "Discovery not started" };
+    }
+    let connectedDevice = null;
+    try {
+      connectedDevice = await this.manager.connectToDevice(user.id, {
+        timeout: 1e4
+      });
+      await connectedDevice.discoverAllServicesAndCharacteristics();
+      const rpiChar = await connectedDevice.readCharacteristicForService(
+        this.serviceUUID,
+        RPI_OUT_CHAR_UUID
+      );
+      const partnerRpi = rpiChar.value ? Buffer.from(rpiChar.value, "base64").toString("hex") : null;
+      const metaChar = await connectedDevice.readCharacteristicForService(
+        this.serviceUUID,
+        META_OUT_CHAR_UUID
+      );
+      const partnerMetadataKey = metaChar.value ? Buffer.from(metaChar.value, "base64").toString("hex") : null;
+      if (!partnerRpi || !partnerMetadataKey) {
+        return { success: false, error: "Failed to read partner data" };
+      }
+      const myRpiBase64 = Buffer.from(this.myRpi, "hex").toString("base64");
+      await connectedDevice.writeCharacteristicWithResponseForService(
+        this.serviceUUID,
+        RPI_IN_CHAR_UUID,
+        myRpiBase64
+      );
+      const myMetaBase64 = Buffer.from(this.myMetadataKey, "hex").toString("base64");
+      await connectedDevice.writeCharacteristicWithResponseForService(
+        this.serviceUUID,
+        META_IN_CHAR_UUID,
+        myMetaBase64
+      );
+      if (this.storage) {
+        const canStore = this.storage.canScan(partnerRpi);
+        if (canStore) {
+          await this.storage.logScan(partnerRpi, partnerMetadataKey, Date.now());
+        }
+      }
+      user.fullRpi = partnerRpi;
+      user.metadataKey = partnerMetadataKey;
+      user.paired = true;
+      user.hasIncomingRequest = false;
+      user.pairedAt = Date.now();
+      this.emitUpdate();
+      return {
+        success: true,
+        partnerRpi,
+        partnerMetadataKey
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Connection failed";
+      return { success: false, error: message };
+    } finally {
+      if (connectedDevice) {
+        try {
+          await this.manager.cancelDeviceConnection(connectedDevice.id);
+        } catch {
+        }
+      }
+    }
+  }
+  async acceptPendingRequest(userId, request) {
+    const user = this.nearbyUsers.get(userId);
+    if (!user) {
+      return { success: false, error: "User not found" };
+    }
+    if (this.storage) {
+      const canStore = this.storage.canScan(request.fullRpi);
+      if (canStore) {
+        await this.storage.logScan(request.fullRpi, request.metadataKey, Date.now());
+      }
+    }
+    user.fullRpi = request.fullRpi;
+    user.metadataKey = request.metadataKey;
+    user.paired = true;
+    user.hasIncomingRequest = false;
+    user.pairedAt = Date.now();
+    this.pendingRequests.delete(userId);
+    this.emitUpdate();
+    return {
+      success: true,
+      partnerRpi: request.fullRpi,
+      partnerMetadataKey: request.metadataKey
+    };
+  }
+  /**
+   * Handle incoming write from another device (GATT server callback).
+   * Called when another device writes to our RPI_IN or META_IN characteristics.
+   */
+  async handleIncomingPair(deviceId, rpi, metadataKey) {
+    let user = this.nearbyUsers.get(deviceId);
+    if (!user) {
+      user = {
+        id: deviceId,
+        displayName: generateDisplayName(rpi.substring(0, 16)),
+        rssi: -50,
+        // Assume close proximity for incoming connection
+        discoveredAt: Date.now(),
+        paired: false,
+        hasIncomingRequest: false,
+        rpiPrefix: rpi.substring(0, 16)
+      };
+      this.nearbyUsers.set(deviceId, user);
+    }
+    if (this.autoAccept) {
+      if (this.storage) {
+        const canStore = this.storage.canScan(rpi);
+        if (canStore) {
+          await this.storage.logScan(rpi, metadataKey, Date.now());
+        }
+      }
+      user.fullRpi = rpi;
+      user.metadataKey = metadataKey;
+      user.paired = true;
+      user.hasIncomingRequest = false;
+      user.pairedAt = Date.now();
+    } else {
+      this.pendingRequests.set(deviceId, {
+        fullRpi: rpi,
+        metadataKey,
+        receivedAt: Date.now()
+      });
+      user.hasIncomingRequest = true;
+      user.paired = false;
+    }
+    this.emitUpdate();
+  }
+  async hasStoredRpi(rpi) {
+    if (!this.storage) return false;
+    return !this.storage.canScan(rpi);
+  }
+  toPublicUser(internal) {
+    return {
+      id: internal.id,
+      displayName: internal.displayName,
+      rssi: internal.rssi,
+      discoveredAt: internal.discoveredAt,
+      paired: internal.paired,
+      hasIncomingRequest: internal.hasIncomingRequest
+    };
+  }
+  emitUpdate() {
+    if (this.onNearbyUpdated) {
+      const publicUsers = Array.from(this.nearbyUsers.values()).filter((u) => u.rssi >= this.proximityThreshold).map((u) => this.toPublicUser(u));
+      this.onNearbyUpdated(publicUsers);
+    }
+  }
+};
+
+// src/transport.ts
+var VERSION = "v1";
+function formatQR(rpi, metadataKey) {
+  return `proto:${VERSION}:${rpi}:${Date.now()}:${metadataKey}`;
+}
+function parseQR(data) {
+  const p = data.split(":");
+  if (p.length !== 5 || p[0] !== "proto" || p[1] !== VERSION) return null;
+  const ts = parseInt(p[3], 10);
+  if (isNaN(ts)) return null;
+  return { rpi: p[2], timestamp: ts, metadataKey: p[4] };
+}
+
+// src/db.ts
+import { drizzle } from "drizzle-orm/expo-sqlite";
+import { openDatabaseSync, deleteDatabaseSync } from "expo-sqlite";
+import { sql } from "drizzle-orm";
+var DB_NAME = "vailix.db";
+async function initializeDatabase(masterKey) {
+  try {
+    return await openEncryptedDatabase(masterKey);
+  } catch (error) {
+    console.warn("Database key mismatch, recreating fresh database");
+    deleteDatabaseSync(DB_NAME);
+    return await openEncryptedDatabase(masterKey);
+  }
+}
+async function openEncryptedDatabase(masterKey) {
+  const expo = openDatabaseSync(DB_NAME);
+  const db = drizzle(expo);
+  if (!/^[0-9a-f]+$/i.test(masterKey)) {
+    throw new Error("Invalid master key format");
+  }
+  await db.run(sql.raw(`PRAGMA key = '${masterKey}'`));
+  await db.run(sql`SELECT 1`);
+  await db.run(sql`
+    CREATE TABLE IF NOT EXISTS scanned_events (
+      id TEXT PRIMARY KEY,
+      rpi TEXT NOT NULL,
+      metadata_key TEXT NOT NULL,
+      timestamp INTEGER NOT NULL
+    )
+  `);
+  await db.run(sql`
+    CREATE INDEX IF NOT EXISTS rpi_idx ON scanned_events(rpi)
+  `);
+  return db;
+}
+
+// src/index.ts
+var VailixSDK = class _VailixSDK {
+  identity;
+  storage;
+  matcher;
+  ble;
+  reportUrl;
+  appSecret;
+  reportDays;
+  rpiDurationMs;
+  constructor(identity, storage, matcher, ble, reportUrl, appSecret, reportDays, rpiDurationMs) {
+    this.identity = identity;
+    this.storage = storage;
+    this.matcher = matcher;
+    this.ble = ble;
+    this.reportUrl = reportUrl;
+    this.appSecret = appSecret;
+    this.reportDays = reportDays;
+    this.rpiDurationMs = rpiDurationMs;
+  }
+  /**
+   * Create and initialize the VailixSDK.
+   * 
+   * @param config - Unified configuration object
+   */
+  static async create(config) {
+    const rpiDuration = config.rpiDurationMs ?? 15 * 60 * 1e3;
+    if (config.rescanIntervalMs && config.rescanIntervalMs > rpiDuration) {
+      throw new Error(`rescanIntervalMs (${config.rescanIntervalMs}) cannot exceed rpiDurationMs (${rpiDuration})`);
+    }
+    const identity = new IdentityManager({
+      rpiDurationMs: config.rpiDurationMs,
+      keyStorage: config.keyStorage
+    });
+    await identity.initialize();
+    const masterKey = identity.getMasterKey();
+    const db = await initializeDatabase(masterKey);
+    const storage = new StorageService(db, {
+      rescanIntervalMs: config.rescanIntervalMs
+    });
+    await storage.initialize();
+    const matcher = new MatcherService(storage, config.downloadUrl, config.appSecret);
+    const ble = new BleService({
+      discoveryTimeoutMs: config.bleDiscoveryTimeoutMs,
+      proximityThreshold: config.proximityThreshold,
+      autoAccept: config.autoAcceptIncomingPairs,
+      serviceUUID: config.serviceUUID
+    });
+    ble.setStorage(storage);
+    await storage.cleanupOldScans();
+    return new _VailixSDK(
+      identity,
+      storage,
+      matcher,
+      ble,
+      config.reportUrl,
+      config.appSecret,
+      config.reportDays ?? 14,
+      rpiDuration
+    );
+  }
+  // ========================================================================
+  // QR Code Methods
+  // ========================================================================
+  /** Get current QR code data */
+  getQRCode() {
+    const rpi = this.identity.getCurrentRPI();
+    const metaKey = this.identity.getMetadataKey(rpi);
+    return formatQR(rpi, metaKey);
+  }
+  /**
+   * Scan another user's QR code and log it.
+   * Returns false if: QR invalid, expired (>RPI duration), rescan blocked, or error
+   */
+  async scanQR(qrData) {
+    try {
+      const parsed = parseQR(qrData);
+      if (!parsed) return false;
+      if (Date.now() - parsed.timestamp > this.rpiDurationMs) {
+        return false;
+      }
+      if (!this.storage.canScan(parsed.rpi)) {
+        return false;
+      }
+      await this.storage.logScan(parsed.rpi, parsed.metadataKey, Date.now());
+      return true;
+    } catch (error) {
+      this.matcher.emit("error", error);
+      return false;
+    }
+  }
+  // ========================================================================
+  // BLE Discovery & Pairing Methods
+  // ========================================================================
+  /**
+   * Check if BLE is supported on this device.
+   */
+  static async isBleSupported() {
+    return BleService.isSupported();
+  }
+  /**
+   * Start BLE discovery (call when pairing screen opens).
+   * Begins advertising our RPI and scanning for nearby users.
+   */
+  async startDiscovery() {
+    const rpi = this.identity.getCurrentRPI();
+    const metaKey = this.identity.getMetadataKey(rpi);
+    await this.ble.startDiscovery(rpi, metaKey);
+  }
+  /**
+   * Stop BLE discovery (call when leaving pairing screen).
+   */
+  async stopDiscovery() {
+    await this.ble.stopDiscovery();
+  }
+  /**
+   * Get current list of nearby users.
+   */
+  getNearbyUsers() {
+    return this.ble.getNearbyUsers();
+  }
+  /**
+   * Subscribe to nearby user updates.
+   * Returns cleanup function for React useEffect compatibility.
+   * 
+   * @example
+   * useEffect(() => {
+   *   const cleanup = sdk.onNearbyUsersChanged(setNearbyUsers);
+   *   return cleanup;
+   * }, []);
+   */
+  onNearbyUsersChanged(callback) {
+    return this.ble.onNearbyUsersChanged(callback);
+  }
+  /**
+   * Pair with a specific user (one-tap action).
+   * In explicit consent mode, this also accepts pending incoming requests.
+   * 
+   * @param userId - The user's ID from NearbyUser.id
+   */
+  async pairWithUser(userId) {
+    return this.ble.pairWithUser(userId);
+  }
+  /**
+   * Unpair with a user (removes from storage and resets status).
+   * Useful for "undo" functionality or rejecting requests.
+   * 
+   * @param userId - The user's ID from NearbyUser.id
+   */
+  async unpairUser(userId) {
+    return this.ble.unpairUser(userId);
+  }
+  /**
+   * Get list of recent pairings from storage (for history/recap features).
+   * Returns pairs from the last N hours (default: 24h).
+   * 
+   * @param withinHours - Look back window in hours (default: 24)
+   * @returns Array of NearbyUser objects representing recent pairs
+   */
+  async getRecentPairs(withinHours = 24) {
+    const recentScans = await this.storage.getRecentPairs(withinHours);
+    return recentScans.map((scan) => ({
+      id: scan.rpi,
+      // Use RPI as ID for history items
+      displayName: `User-${scan.rpi.substring(0, 5)}`,
+      // Generate display name from RPI
+      rssi: -50,
+      // Fixed value for history (not actively scanned)
+      discoveredAt: scan.timestamp,
+      paired: true,
+      hasIncomingRequest: false
+    }));
+  }
+  // ========================================================================
+  // Reporting Methods
+  // ========================================================================
+  /**
+   * Report positive (upload configured days of history).
+   * 
+   * @param attestToken - Optional attestation token (e.g., Firebase App Check)
+   * @param metadata - App-specific data (e.g., STD type, test date). If null, a generic positive is reported.
+   * @param overrideReportDays - Optional: Override reportDays for this specific report
+   *                             (e.g., for apps with per-condition exposure windows)
+   */
+  async report(attestToken, metadata, overrideReportDays) {
+    try {
+      const daysToReport = overrideReportDays ?? this.reportDays;
+      const keys = this.identity.getHistory(daysToReport);
+      const reports = keys.map((rpi) => ({
+        rpi,
+        encryptedMetadata: this._encrypt(metadata, this.identity.getMetadataKey(rpi))
+      }));
+      const headers = {
+        "Content-Type": "application/json",
+        "x-vailix-secret": this.appSecret
+      };
+      if (attestToken) {
+        headers["x-attest-token"] = attestToken;
+      }
+      const res = await fetch(`${this.reportUrl}/v1/report`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ reports })
+      });
+      return res.ok;
+    } catch (error) {
+      this.matcher.emit("error", error);
+      return false;
+    }
+  }
+  // ========================================================================
+  // Encryption Helpers
+  // ========================================================================
+  // Max metadata size: 8KB (leaves headroom under 64KB binary format limit)
+  static MAX_METADATA_SIZE = 8 * 1024;
+  _encrypt(metadata, keyHex) {
+    if (!metadata) return "";
+    const jsonStr = JSON.stringify(metadata);
+    if (jsonStr.length > _VailixSDK.MAX_METADATA_SIZE) {
+      throw new Error(`Metadata exceeds maximum size of ${_VailixSDK.MAX_METADATA_SIZE} bytes`);
+    }
+    const key = Buffer.from(keyHex, "hex");
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    let encrypted = cipher.update(jsonStr, "utf8", "base64");
+    encrypted += cipher.final("base64");
+    const authTag = cipher.getAuthTag().toString("base64");
+    return `${iv.toString("base64")}:${authTag}:${encrypted}`;
+  }
+  // ========================================================================
+  // Event Handlers
+  // ========================================================================
+  /**
+   * Subscribe to match events.
+   * Returns cleanup function for React useEffect compatibility.
+   */
+  onMatch(handler) {
+    this.matcher.on("match", handler);
+    return () => this.matcher.off("match", handler);
+  }
+  /**
+   * Subscribe to error events.
+   * Returns cleanup function for React useEffect compatibility.
+   */
+  onError(handler) {
+    this.matcher.on("error", handler);
+    return () => this.matcher.off("error", handler);
+  }
+  /** Explicit cleanup for match handler */
+  offMatch(handler) {
+    this.matcher.off("match", handler);
+  }
+  /** Explicit cleanup for error handler */
+  offError(handler) {
+    this.matcher.off("error", handler);
+  }
+  // ========================================================================
+  // Match Retrieval Methods (for on-demand decryption)
+  // ========================================================================
+  /**
+   * Get a specific match by ID with decrypted metadata.
+   * Used for on-demand decryption when user views exposure details.
+   * 
+   * @param matchId - RPI of the match to retrieve
+   * @returns Match with decrypted metadata, or null if not found
+   * 
+   * @example
+   * // App calls this when user taps on notification
+   * const match = await sdk.getMatchById('abc123');
+   * console.log(match.metadata.conditions); // ["HIV", "Syphilis"]
+   */
+  async getMatchById(matchId) {
+    return this.matcher.getMatchById(matchId);
+  }
+  /**
+   * Get own display name (emoji + number derived from current RPI).
+   * Used for showing user's anonymous identity in UI.
+   */
+  getOwnDisplayName() {
+    return this.identity.getDisplayName();
+  }
+};
+export {
+  VailixSDK,
+  formatQR,
+  parseQR
+};