@vailix/mask 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @vailix/mask
 
+## 0.2.2
+
+### Patch Changes
+
+- 4b6a9d5: fix: ensure database is closed before deletion on key mismatch and add missing internal types
+
+## 0.2.1
+
+### Patch Changes
+
+- b3be912: docs: fix repository URLs and update README documentation
+
 ## 0.2.0
 
 ### Minor Changes

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Gil Eyni
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Gil Eyni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,365 +1,68 @@
 # @vailix/mask
 
-Privacy-preserving proximity tracing SDK for React Native + Expo.
+**Privacy-preserving proximity tracing SDK for React Native & Expo.**
+
+Part of the **Vailix Core Framework**. This package handles:
+- **Identity**: Rolling Proximity Identifier (RPI) generation/rotation.
+- **BLE**: Broadcasting and scanning for nearby devices.
+- **Matching**: Matching downloaded keys against local history.
+- **Storage**: Securely storing keys and metadata.
 
 ## Installation
 
+This package relies on several native modules which must be installed as **peer dependencies** in your application.
+
 ```bash
+# 1. Install the SDK
 npm install @vailix/mask
-```
-
-> **Note:** This package requires Expo Development Builds (not Expo Go) due to native dependencies.
 
-```bash
-npx expo prebuild
-npx expo run:android  # or run:ios
+# 2. Install required native peer dependencies
+npx expo install react-native-quick-crypto expo-secure-store expo-sqlite react-native-ble-plx
 ```
 
-**Required:** Add SQLCipher to your `app.json`:
+### Expo Configuration (`app.json`)
+
+You must add the config plugin for BLE permissions:
 
 ```json
 {
   "expo": {
     "plugins": [
-      ["expo-sqlite", { "useSQLCipher": true }]
+      [
+        "@config-plugins/react-native-ble-plx",
+        {
+          "isBackgroundEnabled": false,
+          "modes": ["central", "peripheral"],
+          "bluetoothAlwaysPermission": "Allow app to scan for nearby devices."
+        }
+      ]
     ]
   }
 }
 ```
 
-## Quick Start
+## Basic Usage
 
 ```typescript
 import { VailixSDK } from '@vailix/mask';
 
-// Initialize SDK
+// Initialize
 const sdk = await VailixSDK.create({
-  reportUrl: process.env.VAILIX_REPORT_URL!,
-  downloadUrl: process.env.VAILIX_DOWNLOAD_URL!,
-  appSecret: process.env.VAILIX_APP_SECRET!,
-});
-
-// Set up event handlers
-const cleanup = sdk.onMatch((matches) => {
-  console.log('Exposure detected:', matches);
-});
-
-// Start background sync
-await sdk.matcher.fetchAndMatch();
-```
-
-## Configuration
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `reportUrl` | string | required | API endpoint for submitting reports |
-| `downloadUrl` | string | required | API endpoint for downloading infected keys |
-| `appSecret` | string | required | Shared secret for API authentication |
-| `rpiDurationMs` | number | 900000 (15min) | How long each RPI persists. Use 86400000 (24h) for STD apps |
-| `rescanIntervalMs` | number | 0 | Minimum time between scans of same RPI. 0 = no limit |
-| `reportDays` | number | 14 | Days of history to upload when reporting |
-| `keyStorage` | KeyStorage | SecureStore | Custom key storage adapter (for cloud backup) |
-| `bleDiscoveryTimeoutMs` | number | 15000 | Timeout before removing user from nearby list |
-| `proximityThreshold` | number | -70 | Minimum RSSI to consider a user "nearby" |
-| `autoAcceptIncomingPairs` | boolean | true | Auto-accept incoming pair requests |
-
-### Example Configuration
-
-```typescript
-const sdk = await VailixSDK.create({
-  reportUrl: 'https://api.yourapp.com',
-  downloadUrl: 'https://api.yourapp.com',
-  appSecret: 'your-secret-key',
-  rpiDurationMs: 24 * 60 * 60 * 1000,    // 24 hours
-  rescanIntervalMs: 24 * 60 * 60 * 1000, // Block rescan for 24h
-  reportDays: 14,
-  bleDiscoveryTimeoutMs: 15000,          // 15 seconds
-  proximityThreshold: -70,               // ~1-2 meters
-  autoAcceptIncomingPairs: true,         // Instant mutual exchange
-});
-```
-
-## Pairing Methods
-
-Both methods result in **mutual notification** — if either user reports positive, the other is notified.
-
-### BLE Pairing (Recommended)
-
-One-tap proximity-based pairing via Bluetooth Low Energy:
-
-```typescript
-import { useState, useEffect } from 'react';
-import { NearbyUser } from '@vailix/mask';
-
-function PairingScreen({ sdk }) {
-  const [nearbyUsers, setNearbyUsers] = useState<NearbyUser[]>([]);
-
-  useEffect(() => {
-    // Start discovery when screen opens
-    sdk.startDiscovery();
-
-    // Subscribe to nearby user updates
-    const cleanup = sdk.onNearbyUsersChanged(setNearbyUsers);
-
-    return () => {
-      cleanup();
-      sdk.stopDiscovery();
-    };
-  }, []);
-
-  const handlePair = async (user: NearbyUser) => {
-    const result = await sdk.pairWithUser(user.id);
-    if (result.success) {
-      console.log('Paired successfully with', user.displayName);
-    }
-  };
-
-  return (
-    <FlatList
-      data={nearbyUsers}
-      renderItem={({ item }) => (
-        <View>
-          <Text>{item.displayName}</Text>
-          {item.paired ? (
-            <Text>✓ Paired</Text>
-          ) : (
-            <Button title="Pair" onPress={() => handlePair(item)} />
-          )}
-        </View>
-      )}
-    />
-  );
-}
-```
-
-**User Flow:**
-1. Both users open the pairing screen
-2. They see each other in the nearby users list (e.g., "🐼 42", "🦊 17")
-3. Either user taps to pair
-4. Both phones exchange data automatically
-
-### QR Code Pairing (Fallback)
-
-Both users must scan each other's QR code:
-
-```typescript
-// User A shows QR
-const qrData = sdk.getQRCode();
-// Display qrData as QR code
-
-// User B scans
-const success = await sdk.scanQR(scannedData);
-
-// Then swap: B shows, A scans
-```
-
-## BLE Configuration
-
-### iOS Configuration
-
-Add to `ios/[AppName]/Info.plist`:
-
-```xml
-<key>NSBluetoothAlwaysUsageDescription</key>
-<string>Used to discover and pair with nearby users</string>
-<key>NSBluetoothPeripheralUsageDescription</key>
-<string>Used to allow other users to discover you</string>
-```
-
-### Android Configuration
-
-Add to `android/app/src/main/AndroidManifest.xml`:
-
-```xml
-<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
-<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
-<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
-<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
-```
-
-## Explicit Consent Mode
-
-By default, pair requests are auto-accepted. For apps requiring explicit consent:
-
-```typescript
-const sdk = await VailixSDK.create({
-  ...config,
-  autoAcceptIncomingPairs: false, // Require explicit acceptance
-});
-
-// In your pairing screen:
-{item.hasIncomingRequest ? (
-  <Button title="Accept" onPress={() => sdk.pairWithUser(item.id)} />
-) : item.paired ? (
-  <Text>✓ Paired</Text>
-) : (
-  <Button title="Pair" onPress={() => handlePair(item)} />
-)}
-```
-
-## Reporting Positive
-
-When a user tests positive:
-
-```typescript
-const success = await sdk.report(
-  attestToken,  // Optional: Firebase App Check token
-  {             // Optional: metadata (encrypted per-contact)
-    condition: 'chlamydia',
-    testDate: '2025-01-05',
-  }
-);
-```
-
-This uploads the user's last 14 days of RPIs (configurable via `reportDays`).
-
-## Receiving Notifications
-
-```typescript
-// Subscribe to matches
-const cleanup = sdk.onMatch((matches) => {
-  for (const match of matches) {
-    console.log('Exposure on:', new Date(match.timestamp));
-    console.log('Reported at:', new Date(match.reportedAt));
-    console.log('Details:', match.metadata); // Decrypted per-contact
-  }
+  appSecret: "YOUR_SECRET",
+  reportUrl: "https://your-drop-server.com",
+  downloadUrl: "https://your-drop-server.com",
 });
 
-// Trigger sync (call this in background fetch)
-await sdk.matcher.fetchAndMatch();
-
-// Cleanup when component unmounts (React)
-useEffect(() => {
-  return sdk.onMatch(handler); // Returns cleanup function
-}, []);
-```
-
-## Error Handling
+// Start Scanning
+await sdk.startDiscovery();
 
-```typescript
-const cleanup = sdk.onError((error) => {
-  console.error('SDK error:', error);
-});
-```
-
-## Data Recovery
-
-The SDK uses SQLCipher AES-256 encryption for all stored data. Recovery behavior depends on whether you implement `keyStorage`.
-
-### Without keyStorage (Default)
-
-Master key stored locally only. On reinstall:
-- New master key generated → new identity
-- Old scan history unreadable (wrong key)
-- SDK automatically deletes corrupted database
-
-### With keyStorage (Recommended)
-
-Enable cross-device recovery by syncing the master key:
-
-```typescript
-// Custom storage for iCloud/Google Drive sync
-// Recommended library: react-native-cloud-storage
-import { CloudStorage } from 'react-native-cloud-storage';
-
-const sdk = await VailixSDK.create({
-  ...config,
-  keyStorage: {
-    getKey: () => CloudStorage.getItem('vailix_key'),
-    setKey: (k) => CloudStorage.setItem('vailix_key', k),
-  },
+// Listen for updates
+const unsubscribe = sdk.onNearbyUsersChanged((users) => {
+  console.log("Nearby:", users);
 });
 ```
 
-### User Experience Flow
-
-1. **First install:** SDK generates key → `setKey()` saves to cloud
-2. **Normal use:** Scans saved locally, OS backs up database
-3. **Phone lost:** Key in cloud, database in iCloud/Google backup
-4. **New phone:** User signs into same Apple ID/Google Account
-5. **Reinstall:** SDK calls `getKey()` → returns existing key → opens database
-
-**No user action required** except signing into the same cloud account.
-
-### Recovery Scenarios
-
-| Scenario | Master Key | Database | Result |
-|----------|------------|----------|--------|
-| Both recovered | ✅ From cloud | ✅ From backup | Full restore |
-| Key only | ✅ From cloud | ❌ Empty | Fresh DB, can still report |
-| New key, old DB | ❌ New | ⚠️ Wrong key | SDK deletes old DB, starts fresh |
-| Neither | ❌ New | ❌ Empty | New identity |
-
-### KeyStorage Interface
-
-```typescript
-interface KeyStorage {
-  getKey(): Promise<string | null>;
-  setKey(key: string): Promise<void>;
-}
-```
-
-> [!IMPORTANT]
-> The SDK does NOT require app-level login. Cloud sync uses device-level Apple ID / Google Account.
-
-## API Reference
-
-### VailixSDK
-
-| Method | Description |
-|--------|-------------|
-| `VailixSDK.create(config)` | Initialize SDK with VailixConfig |
-| `VailixSDK.isBleSupported()` | Check if device supports BLE |
-| `sdk.getQRCode()` | Get QR code data for display |
-| `sdk.scanQR(data)` | Scan and store another user's QR |
-| `sdk.startDiscovery()` | Start BLE discovery (call when pairing screen opens) |
-| `sdk.stopDiscovery()` | Stop BLE discovery (call when leaving pairing screen) |
-| `sdk.getNearbyUsers()` | Get current list of nearby users |
-| `sdk.onNearbyUsersChanged(handler)` | Subscribe to nearby user updates |
-| `sdk.pairWithUser(userId)` | Pair with a specific user |
-| `sdk.unpairUser(userId)` | Unpair/reject a user |
-| `sdk.report(token?, metadata?)` | Report positive |
-| `sdk.onMatch(handler)` | Subscribe to exposure matches |
-| `sdk.offMatch(handler)` | Unsubscribe from matches |
-| `sdk.onError(handler)` | Subscribe to errors |
-| `sdk.offError(handler)` | Unsubscribe from errors |
-| `sdk.matcher.fetchAndMatch()` | Sync and check for matches |
-
-### NearbyUser Object
-
-```typescript
-interface NearbyUser {
-  id: string;              // Opaque identifier for pairing
-  displayName: string;     // Generated emoji + number (e.g., "🐼 42")
-  rssi: number;            // Signal strength
-  discoveredAt: number;    // Timestamp of last advertisement
-  paired: boolean;         // true if already paired
-  hasIncomingRequest: boolean; // true if they sent a pair request (explicit mode)
-}
-```
-
-### PairResult Object
-
-```typescript
-interface PairResult {
-  success: boolean;
-  partnerRpi?: string;
-  partnerMetadataKey?: string;
-  error?: string;
-}
-```
-
-### Match Object
-
-```typescript
-interface Match {
-  rpi: string;           // The matched identifier
-  timestamp: number;     // When the contact occurred
-  metadata?: object;     // Decrypted reporter metadata
-  reportedAt?: number;   // When the report was submitted
-}
-```
-
-## License
+## Compatibility
 
-MIT
+- **Expo**: SDK 52+ (Development Build required, **Expo Go not supported**)
+- **React Native**: 0.76+

package/dist/index.js

@@ -775,35 +775,54 @@ var import_expo_sqlite2 = require("expo-sqlite");
 var import_drizzle_orm2 = require("drizzle-orm");
 var DB_NAME = "vailix.db";
 async function initializeDatabase(masterKey) {
+  const result = await tryOpenEncryptedDatabase(masterKey);
+  if (result.success) {
+    return result.db;
+  }
+  console.warn("Database key mismatch, recreating fresh database");
+  if (result.expo) {
+    result.expo.closeSync();
+  }
+  (0, import_expo_sqlite2.deleteDatabaseSync)(DB_NAME);
+  const retryResult = await tryOpenEncryptedDatabase(masterKey);
+  if (!retryResult.success) {
+    if (retryResult.expo) {
+      retryResult.expo.closeSync();
+    }
+    throw retryResult.error;
+  }
+  return retryResult.db;
+}
+async function tryOpenEncryptedDatabase(masterKey) {
+  let expo = null;
   try {
-    return await openEncryptedDatabase(masterKey);
+    expo = (0, import_expo_sqlite2.openDatabaseSync)(DB_NAME);
+    const db = (0, import_expo_sqlite.drizzle)(expo);
+    if (!/^[0-9a-f]+$/i.test(masterKey)) {
+      throw new Error("Invalid master key format");
+    }
+    await db.run(import_drizzle_orm2.sql.raw(`PRAGMA key = '${masterKey}'`));
+    await db.run(import_drizzle_orm2.sql`SELECT 1`);
+    await db.run(import_drizzle_orm2.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(import_drizzle_orm2.sql`
+            CREATE INDEX IF NOT EXISTS rpi_idx ON scanned_events(rpi)
+        `);
+    return { success: true, db, expo };
   } catch (error) {
-    console.warn("Database key mismatch, recreating fresh database");
-    (0, import_expo_sqlite2.deleteDatabaseSync)(DB_NAME);
-    return await openEncryptedDatabase(masterKey);
+    return {
+      success: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+      expo
+    };
   }
 }
-async function openEncryptedDatabase(masterKey) {
-  const expo = (0, import_expo_sqlite2.openDatabaseSync)(DB_NAME);
-  const db = (0, import_expo_sqlite.drizzle)(expo);
-  if (!/^[0-9a-f]+$/i.test(masterKey)) {
-    throw new Error("Invalid master key format");
-  }
-  await db.run(import_drizzle_orm2.sql.raw(`PRAGMA key = '${masterKey}'`));
-  await db.run(import_drizzle_orm2.sql`SELECT 1`);
-  await db.run(import_drizzle_orm2.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(import_drizzle_orm2.sql`
-    CREATE INDEX IF NOT EXISTS rpi_idx ON scanned_events(rpi)
-  `);
-  return db;
-}
 
 // src/index.ts
 var VailixSDK = class _VailixSDK {

package/dist/index.mjs

@@ -739,35 +739,54 @@ import { openDatabaseSync, deleteDatabaseSync } from "expo-sqlite";
 import { sql } from "drizzle-orm";
 var DB_NAME = "vailix.db";
 async function initializeDatabase(masterKey) {
+  const result = await tryOpenEncryptedDatabase(masterKey);
+  if (result.success) {
+    return result.db;
+  }
+  console.warn("Database key mismatch, recreating fresh database");
+  if (result.expo) {
+    result.expo.closeSync();
+  }
+  deleteDatabaseSync(DB_NAME);
+  const retryResult = await tryOpenEncryptedDatabase(masterKey);
+  if (!retryResult.success) {
+    if (retryResult.expo) {
+      retryResult.expo.closeSync();
+    }
+    throw retryResult.error;
+  }
+  return retryResult.db;
+}
+async function tryOpenEncryptedDatabase(masterKey) {
+  let expo = null;
   try {
-    return await openEncryptedDatabase(masterKey);
+    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 { success: true, db, expo };
   } catch (error) {
-    console.warn("Database key mismatch, recreating fresh database");
-    deleteDatabaseSync(DB_NAME);
-    return await openEncryptedDatabase(masterKey);
+    return {
+      success: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+      expo
+    };
   }
 }
-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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vailix/mask",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Privacy-preserving proximity tracing SDK for React Native & Expo",
   "author": "Gil Eyni",
   "keywords": [
@@ -13,13 +13,13 @@
     "contact-tracing",
     "sdk"
   ],
-  "homepage": "https://github.com/vailix/core/tree/main/packages/mask#readme",
+  "homepage": "https://github.com/vailix-dev/vailix/tree/main/packages/mask#readme",
   "bugs": {
-    "url": "https://github.com/vailix/core/issues"
+    "url": "https://github.com/vailix-dev/vailix/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vailix/core.git",
+    "url": "git+https://github.com/vailix-dev/vailix.git",
     "directory": "packages/mask"
   },
   "license": "MIT",

package/src/ble.ts

@@ -21,6 +21,50 @@ const DEFAULT_PROXIMITY_THRESHOLD = -70;
 
 import { generateDisplayName } from './utils';
 
+// ============================================================================
+// Internal Types (not exported - implementation details)
+// ============================================================================
+
+/**
+ * Internal representation of a nearby user with additional fields for BLE management.
+ * The public NearbyUser type hides these implementation details.
+ */
+interface InternalNearbyUser {
+    id: string;
+    displayName: string;
+    rssi: number;
+    discoveredAt: number;
+    paired: boolean;
+    hasIncomingRequest: boolean;
+    pairedAt?: number;
+    /** First 8 bytes (16 hex chars) of RPI from advertisement */
+    rpiPrefix: string;
+    /** Full RPI (received via GATT exchange) */
+    fullRpi?: string;
+    /** Metadata key (received via GATT exchange) */
+    metadataKey?: string;
+}
+
+/**
+ * Pending incoming pair request (explicit consent mode).
+ * Holds data in memory until user accepts.
+ */
+interface PendingPairRequest {
+    fullRpi: string;
+    metadataKey: string;
+    receivedAt: number;
+}
+
+/**
+ * Configuration options for BleService constructor.
+ */
+interface BleServiceConfig {
+    discoveryTimeoutMs?: number;
+    proximityThreshold?: number;
+    autoAccept?: boolean;
+    serviceUUID?: string;
+}
+
 /**
  * Extract RPI prefix from advertisement manufacturer data or service data.
  */

package/src/db.ts

@@ -1,5 +1,5 @@
 import { drizzle } from 'drizzle-orm/expo-sqlite';
-import { openDatabaseSync, deleteDatabaseSync } from 'expo-sqlite';
+import { openDatabaseSync, deleteDatabaseSync, type SQLiteDatabase } from 'expo-sqlite';
 import { sql } from 'drizzle-orm';
 import type { VailixDB } from './types';
 
@@ -13,45 +13,83 @@ const DB_NAME = 'vailix.db';
  * @param masterKey The user's master key, used to derive encryption password
  */
 export async function initializeDatabase(masterKey: string): Promise<VailixDB> {
-    try {
-        return await openEncryptedDatabase(masterKey);
-    } catch (error) {
-        // Key mismatch: "file is not a database" or similar SQLCipher error
-        // This happens when DB was restored from backup but key is different
-        console.warn('Database key mismatch, recreating fresh database');
-        deleteDatabaseSync(DB_NAME);
-        return await openEncryptedDatabase(masterKey);
+    const result = await tryOpenEncryptedDatabase(masterKey);
+    
+    if (result.success) {
+        return result.db;
+    }
+    
+    // Key mismatch: "file is not a database" or similar SQLCipher error
+    // This happens when DB was restored from backup but key is different
+    console.warn('Database key mismatch, recreating fresh database');
+    
+    // Close the connection before deletion (required by SQLite)
+    if (result.expo) {
+        result.expo.closeSync();
+    }
+    
+    deleteDatabaseSync(DB_NAME);
+    
+    // Retry - if this fails, let it throw (unrecoverable error)
+    const retryResult = await tryOpenEncryptedDatabase(masterKey);
+    if (!retryResult.success) {
+        if (retryResult.expo) {
+            retryResult.expo.closeSync();
+        }
+        throw retryResult.error;
     }
+    
+    return retryResult.db;
 }
 
-async function openEncryptedDatabase(masterKey: string): Promise<VailixDB> {
-    const expo = openDatabaseSync(DB_NAME);
-    const db = drizzle(expo);
+type OpenResult = 
+    | { success: true; db: VailixDB; expo: SQLiteDatabase }
+    | { success: false; error: Error; expo: SQLiteDatabase | null };
 
-    // Enable SQLCipher encryption using master key as password
-    // This encrypts the entire database at rest (AES-256)
-    // Validate key is hex to prevent SQL injection
-    if (!/^[0-9a-f]+$/i.test(masterKey)) {
-        throw new Error('Invalid master key format');
+/**
+ * Attempt to open and configure the encrypted database.
+ * Returns a result object that includes the raw expo connection for cleanup.
+ */
+async function tryOpenEncryptedDatabase(masterKey: string): Promise<OpenResult> {
+    let expo: SQLiteDatabase | null = null;
+    
+    try {
+        expo = openDatabaseSync(DB_NAME);
+        const db = drizzle(expo);
+
+        // Validate key is hex to prevent SQL injection
+        if (!/^[0-9a-f]+$/i.test(masterKey)) {
+            throw new Error('Invalid master key format');
+        }
+        
+        // Enable SQLCipher encryption using master key as password
+        // This encrypts the entire database at rest (AES-256)
+        await db.run(sql.raw(`PRAGMA key = '${masterKey}'`));
+
+        // Verify key works by attempting a read operation
+        // SQLCipher will throw if key is wrong
+        await db.run(sql`SELECT 1`);
+
+        // Create schema
+        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 { success: true, db, expo };
+    } catch (error) {
+        return { 
+            success: false, 
+            error: error instanceof Error ? error : new Error(String(error)),
+            expo 
+        };
     }
-    await db.run(sql.raw(`PRAGMA key = '${masterKey}'`));
-
-    // Verify key works by attempting a read operation
-    // SQLCipher will throw if key is wrong
-    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;
 }