@vailix/mask 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @vailix/mask
 
+## 0.2.3
+
+### Patch Changes
+
+- c1ca263: fix: prevent race condition in SDK initialization
+  - Implement singleton pattern for `VailixSDK.create()` to prevent concurrent database connections
+  - Ensure database is properly closed before deletion on key mismatch errors
+  - Add missing internal BLE types (`InternalNearbyUser`, `PendingPairRequest`, `BleServiceConfig`)
+  - Add `VailixSDK.destroy()` for cleanup and `VailixSDK.isInitialized()` for status checking
+
+## 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

package/README.md

@@ -62,6 +62,16 @@ const unsubscribe = sdk.onNearbyUsersChanged((users) => {
 });
 ```
 
+> **Note:** `VailixSDK.create()` returns a singleton instance. Multiple calls return the same instance, and the config is only used on the first call. Use `VailixSDK.destroy()` to reset the SDK if needed.
+
+### Static Methods
+
+| Method | Description |
+|--------|-------------|
+| `VailixSDK.create(config)` | Create or return the singleton SDK instance |
+| `VailixSDK.destroy()` | Release resources and reset the singleton |
+| `VailixSDK.isInitialized()` | Check if the SDK has been initialized |
+
 ## Compatibility
 
 - **Expo**: SDK 52+ (Development Build required, **Expo Go not supported**)

package/dist/index.d.mts

@@ -227,6 +227,8 @@ interface ParsedQR {
 }
 
 declare class VailixSDK {
+    private static instance;
+    private static initPromise;
     identity: IdentityManager;
     storage: StorageService;
     matcher: MatcherService;
@@ -237,11 +239,27 @@ declare class VailixSDK {
     private rpiDurationMs;
     private constructor();
     /**
-     * Create and initialize the VailixSDK.
+     * Create or return the singleton SDK instance.
      *
-     * @param config - Unified configuration object
+     * Thread-safe: concurrent calls will wait for the first initialization to complete
+     * and return the same instance. Config is only used on first initialization.
+     *
+     * @param config - Unified configuration object (used only on first call)
      */
     static create(config: VailixConfig): Promise<VailixSDK>;
+    /**
+     * Internal initialization logic (extracted for singleton pattern).
+     */
+    private static doCreate;
+    /**
+     * Destroy the singleton instance and release all resources.
+     * Use for testing or when the app needs to fully reset the SDK.
+     */
+    static destroy(): Promise<void>;
+    /**
+     * Check if the SDK has been initialized.
+     */
+    static isInitialized(): boolean;
     /** Get current QR code data */
     getQRCode(): string;
     /**

package/dist/index.d.ts

@@ -227,6 +227,8 @@ interface ParsedQR {
 }
 
 declare class VailixSDK {
+    private static instance;
+    private static initPromise;
     identity: IdentityManager;
     storage: StorageService;
     matcher: MatcherService;
@@ -237,11 +239,27 @@ declare class VailixSDK {
     private rpiDurationMs;
     private constructor();
     /**
-     * Create and initialize the VailixSDK.
+     * Create or return the singleton SDK instance.
      *
-     * @param config - Unified configuration object
+     * Thread-safe: concurrent calls will wait for the first initialization to complete
+     * and return the same instance. Config is only used on first initialization.
+     *
+     * @param config - Unified configuration object (used only on first call)
      */
     static create(config: VailixConfig): Promise<VailixSDK>;
+    /**
+     * Internal initialization logic (extracted for singleton pattern).
+     */
+    private static doCreate;
+    /**
+     * Destroy the singleton instance and release all resources.
+     * Use for testing or when the app needs to fully reset the SDK.
+     */
+    static destroy(): Promise<void>;
+    /**
+     * Check if the SDK has been initialized.
+     */
+    static isInitialized(): boolean;
     /** Get current QR code data */
     getQRCode(): string;
     /**

package/dist/index.js

@@ -775,38 +775,60 @@ 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 {
+  // Singleton instance and initialization promise for thread-safety
+  static instance = null;
+  static initPromise = null;
   identity;
   storage;
   matcher;
@@ -826,11 +848,33 @@ var VailixSDK = class _VailixSDK {
     this.rpiDurationMs = rpiDurationMs;
   }
   /**
-   * Create and initialize the VailixSDK.
+   * Create or return the singleton SDK instance.
+   * 
+   * Thread-safe: concurrent calls will wait for the first initialization to complete
+   * and return the same instance. Config is only used on first initialization.
    * 
-   * @param config - Unified configuration object
+   * @param config - Unified configuration object (used only on first call)
    */
   static async create(config) {
+    if (_VailixSDK.instance) {
+      return _VailixSDK.instance;
+    }
+    if (_VailixSDK.initPromise) {
+      return _VailixSDK.initPromise;
+    }
+    _VailixSDK.initPromise = _VailixSDK.doCreate(config);
+    try {
+      _VailixSDK.instance = await _VailixSDK.initPromise;
+      return _VailixSDK.instance;
+    } catch (error) {
+      _VailixSDK.initPromise = null;
+      throw error;
+    }
+  }
+  /**
+   * Internal initialization logic (extracted for singleton pattern).
+   */
+  static async doCreate(config) {
     const rpiDuration = config.rpiDurationMs ?? 15 * 60 * 1e3;
     if (config.rescanIntervalMs && config.rescanIntervalMs > rpiDuration) {
       throw new Error(`rescanIntervalMs (${config.rescanIntervalMs}) cannot exceed rpiDurationMs (${rpiDuration})`);
@@ -866,6 +910,23 @@ var VailixSDK = class _VailixSDK {
       rpiDuration
     );
   }
+  /**
+   * Destroy the singleton instance and release all resources.
+   * Use for testing or when the app needs to fully reset the SDK.
+   */
+  static async destroy() {
+    if (_VailixSDK.instance) {
+      _VailixSDK.instance.ble.destroy();
+      _VailixSDK.instance = null;
+    }
+    _VailixSDK.initPromise = null;
+  }
+  /**
+   * Check if the SDK has been initialized.
+   */
+  static isInitialized() {
+    return _VailixSDK.instance !== null;
+  }
   // ========================================================================
   // QR Code Methods
   // ========================================================================

package/dist/index.mjs

@@ -739,38 +739,60 @@ 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 {
+  // Singleton instance and initialization promise for thread-safety
+  static instance = null;
+  static initPromise = null;
   identity;
   storage;
   matcher;
@@ -790,11 +812,33 @@ var VailixSDK = class _VailixSDK {
     this.rpiDurationMs = rpiDurationMs;
   }
   /**
-   * Create and initialize the VailixSDK.
+   * Create or return the singleton SDK instance.
+   * 
+   * Thread-safe: concurrent calls will wait for the first initialization to complete
+   * and return the same instance. Config is only used on first initialization.
    * 
-   * @param config - Unified configuration object
+   * @param config - Unified configuration object (used only on first call)
    */
   static async create(config) {
+    if (_VailixSDK.instance) {
+      return _VailixSDK.instance;
+    }
+    if (_VailixSDK.initPromise) {
+      return _VailixSDK.initPromise;
+    }
+    _VailixSDK.initPromise = _VailixSDK.doCreate(config);
+    try {
+      _VailixSDK.instance = await _VailixSDK.initPromise;
+      return _VailixSDK.instance;
+    } catch (error) {
+      _VailixSDK.initPromise = null;
+      throw error;
+    }
+  }
+  /**
+   * Internal initialization logic (extracted for singleton pattern).
+   */
+  static async doCreate(config) {
     const rpiDuration = config.rpiDurationMs ?? 15 * 60 * 1e3;
     if (config.rescanIntervalMs && config.rescanIntervalMs > rpiDuration) {
       throw new Error(`rescanIntervalMs (${config.rescanIntervalMs}) cannot exceed rpiDurationMs (${rpiDuration})`);
@@ -830,6 +874,23 @@ var VailixSDK = class _VailixSDK {
       rpiDuration
     );
   }
+  /**
+   * Destroy the singleton instance and release all resources.
+   * Use for testing or when the app needs to fully reset the SDK.
+   */
+  static async destroy() {
+    if (_VailixSDK.instance) {
+      _VailixSDK.instance.ble.destroy();
+      _VailixSDK.instance = null;
+    }
+    _VailixSDK.initPromise = null;
+  }
+  /**
+   * Check if the SDK has been initialized.
+   */
+  static isInitialized() {
+    return _VailixSDK.instance !== null;
+  }
   // ========================================================================
   // QR Code Methods
   // ========================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vailix/mask",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Privacy-preserving proximity tracing SDK for React Native & Expo",
   "author": "Gil Eyni",
   "keywords": [

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;
 }

package/src/index.ts

@@ -16,6 +16,10 @@ import type {
 } from './types';
 
 export class VailixSDK {
+    // Singleton instance and initialization promise for thread-safety
+    private static instance: VailixSDK | null = null;
+    private static initPromise: Promise<VailixSDK> | null = null;
+
     public identity: IdentityManager;
     public storage: StorageService;
     public matcher: MatcherService;
@@ -46,11 +50,41 @@ export class VailixSDK {
     }
 
     /**
-     * Create and initialize the VailixSDK.
+     * Create or return the singleton SDK instance.
+     * 
+     * Thread-safe: concurrent calls will wait for the first initialization to complete
+     * and return the same instance. Config is only used on first initialization.
      * 
-     * @param config - Unified configuration object
+     * @param config - Unified configuration object (used only on first call)
      */
     static async create(config: VailixConfig): Promise<VailixSDK> {
+        // Already initialized - return existing instance
+        if (VailixSDK.instance) {
+            return VailixSDK.instance;
+        }
+
+        // Initialization in progress - wait for it (prevents race condition)
+        if (VailixSDK.initPromise) {
+            return VailixSDK.initPromise;
+        }
+
+        // First call - start initialization
+        VailixSDK.initPromise = VailixSDK.doCreate(config);
+
+        try {
+            VailixSDK.instance = await VailixSDK.initPromise;
+            return VailixSDK.instance;
+        } catch (error) {
+            // Clear promise on failure so retry is possible
+            VailixSDK.initPromise = null;
+            throw error;
+        }
+    }
+
+    /**
+     * Internal initialization logic (extracted for singleton pattern).
+     */
+    private static async doCreate(config: VailixConfig): Promise<VailixSDK> {
         // Validate: rescanInterval cannot exceed rpiDuration
         const rpiDuration = config.rpiDurationMs ?? 15 * 60 * 1000; // Default 15 min
         if (config.rescanIntervalMs && config.rescanIntervalMs > rpiDuration) {
@@ -99,6 +133,27 @@ export class VailixSDK {
         );
     }
 
+    /**
+     * Destroy the singleton instance and release all resources.
+     * Use for testing or when the app needs to fully reset the SDK.
+     */
+    static async destroy(): Promise<void> {
+        if (VailixSDK.instance) {
+            // Cleanup BLE resources
+            VailixSDK.instance.ble.destroy();
+            // Note: Database connection cleanup is handled by expo-sqlite
+            VailixSDK.instance = null;
+        }
+        VailixSDK.initPromise = null;
+    }
+
+    /**
+     * Check if the SDK has been initialized.
+     */
+    static isInitialized(): boolean {
+        return VailixSDK.instance !== null;
+    }
+
     // ========================================================================
     // QR Code Methods
     // ========================================================================