@vailix/mask 0.1.2

package/src/identity.ts

@@ -0,0 +1,91 @@
+import { createHmac, randomUUID } from 'react-native-quick-crypto';
+import * as SecureStore from 'expo-secure-store';
+import type { KeyStorage } from './types';
+import { generateDisplayName } from './utils';
+
+const MASTER_KEY_STORE = 'vailix_master_key';
+const DEFAULT_EPOCH_MS = 15 * 60 * 1000; // 15 minutes default
+
+// Default key storage using expo-secure-store (device-only)
+class DefaultKeyStorage implements KeyStorage {
+    async getKey(): Promise<string | null> {
+        return SecureStore.getItemAsync(MASTER_KEY_STORE);
+    }
+    async setKey(key: string): Promise<void> {
+        await SecureStore.setItemAsync(MASTER_KEY_STORE, key);
+    }
+}
+
+export class IdentityManager {
+    private masterKey: string | null = null;
+    private epochMs: number;
+    private keyStorage: KeyStorage;
+
+    constructor(config: { rpiDurationMs?: number; keyStorage?: KeyStorage } = {}) {
+        this.epochMs = config.rpiDurationMs ?? DEFAULT_EPOCH_MS;
+        this.keyStorage = config.keyStorage ?? new DefaultKeyStorage();
+    }
+
+    async initialize(): Promise<void> {
+        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(): string {
+        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: number): string[] {
+        if (!this.masterKey) throw new Error('Not initialized');
+        const epochsPerDay = (24 * 60 * 60 * 1000) / 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.
+    private _generateRPI(epoch: number): string {
+        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: string): string {
+        if (!this.masterKey) throw new Error('Not initialized');
+        return createHmac('sha256', this.masterKey!)
+            .update(`meta:${rpi}`)
+            .digest('hex')
+            .substring(0, 64); // 32 bytes for AES-256
+    }
+
+    // Get master key for database encryption (SQLCipher)
+    getMasterKey(): string {
+        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(): string {
+        const rpi = this.getCurrentRPI();
+        return generateDisplayName(rpi.substring(0, 16));
+    }
+}

package/src/index.ts

@@ -0,0 +1,375 @@
+import { createCipheriv, randomBytes } from 'react-native-quick-crypto';
+import { IdentityManager } from './identity';
+import { StorageService } from './storage';
+import { MatcherService } from './matcher';
+import { BleService } from './ble';
+import { formatQR, parseQR } from './transport';
+import { initializeDatabase } from './db';
+import type {
+    Match,
+    MatchHandler,
+    ReportMetadata,
+    KeyStorage,
+    VailixConfig,
+    NearbyUser,
+    PairResult
+} from './types';
+
+export class VailixSDK {
+    public identity: IdentityManager;
+    public storage: StorageService;
+    public matcher: MatcherService;
+    private ble: BleService;
+    private reportUrl: string;
+    private appSecret: string;
+    private reportDays: number;
+    private rpiDurationMs: number;
+
+    private constructor(
+        identity: IdentityManager,
+        storage: StorageService,
+        matcher: MatcherService,
+        ble: BleService,
+        reportUrl: string,
+        appSecret: string,
+        reportDays: number,
+        rpiDurationMs: number
+    ) {
+        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: VailixConfig): Promise<VailixSDK> {
+        // Validate: rescanInterval cannot exceed rpiDuration
+        const rpiDuration = config.rpiDurationMs ?? 15 * 60 * 1000; // Default 15 min
+        if (config.rescanIntervalMs && config.rescanIntervalMs > rpiDuration) {
+            throw new Error(`rescanIntervalMs (${config.rescanIntervalMs}) cannot exceed rpiDurationMs (${rpiDuration})`);
+        }
+
+        // Initialize identity first to get master key for database encryption
+        const identity = new IdentityManager({
+            rpiDurationMs: config.rpiDurationMs,
+            keyStorage: config.keyStorage,
+        });
+        await identity.initialize();
+
+        // Initialize encrypted database (SQLCipher) using master key
+        const masterKey = identity.getMasterKey();
+        const db = await initializeDatabase(masterKey);
+
+        const storage = new StorageService(db, {
+            rescanIntervalMs: config.rescanIntervalMs
+        });
+        await storage.initialize();  // Load persisted scan history
+
+        const matcher = new MatcherService(storage, config.downloadUrl, config.appSecret);
+
+        // Initialize BLE service with config options
+        const ble = new BleService({
+            discoveryTimeoutMs: config.bleDiscoveryTimeoutMs,
+            proximityThreshold: config.proximityThreshold,
+            autoAccept: config.autoAcceptIncomingPairs,
+            serviceUUID: config.serviceUUID,
+        });
+        ble.setStorage(storage);
+
+        // Cleanup old scans on init
+        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(): string {
+        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: string): Promise<boolean> {
+        try {
+            const parsed = parseQR(qrData);
+            if (!parsed) return false;
+
+            // Reject QR codes older than RPI duration (QR is only valid while RPI is valid)
+            if (Date.now() - parsed.timestamp > this.rpiDurationMs) {
+                return false; // Expired QR
+            }
+
+            // Check rescan protection (returns false if scanned too recently)
+            if (!this.storage.canScan(parsed.rpi)) {
+                return false; // Rescan blocked
+            }
+
+            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(): Promise<boolean> {
+        return BleService.isSupported();
+    }
+
+    /**
+     * Start BLE discovery (call when pairing screen opens).
+     * Begins advertising our RPI and scanning for nearby users.
+     */
+    async startDiscovery(): Promise<void> {
+        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(): Promise<void> {
+        await this.ble.stopDiscovery();
+    }
+
+    /**
+     * Get current list of nearby users.
+     */
+    getNearbyUsers(): NearbyUser[] {
+        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: (users: NearbyUser[]) => void): () => void {
+        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: string): Promise<PairResult> {
+        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: string): Promise<void> {
+        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: number = 24): Promise<NearbyUser[]> {
+        const recentScans = await this.storage.getRecentPairs(withinHours);
+
+        // Map ScannedEvent to NearbyUser format for UI compatibility
+        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?: string,
+        metadata?: ReportMetadata,
+        overrideReportDays?: number
+    ): Promise<boolean> {
+        try {
+            // Use override if provided, else fall back to global config
+            const daysToReport = overrideReportDays ?? this.reportDays;
+            const keys = this.identity.getHistory(daysToReport);
+
+            // Encrypt metadata individually for each key in history
+            const reports = keys.map(rpi => ({
+                rpi,
+                encryptedMetadata: this._encrypt(metadata, this.identity.getMetadataKey(rpi))
+            }));
+
+            const headers: Record<string, string> = {
+                '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)
+    private static readonly MAX_METADATA_SIZE = 8 * 1024;
+
+    private _encrypt(metadata: ReportMetadata | undefined, keyHex: string): string {
+        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); // 96-bit IV for GCM
+        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');
+
+        // Format: iv:authTag:encryptedData
+        return `${iv.toString('base64')}:${authTag}:${encrypted}`;
+    }
+
+    // ========================================================================
+    // Event Handlers
+    // ========================================================================
+
+    /**
+     * Subscribe to match events.
+     * Returns cleanup function for React useEffect compatibility.
+     */
+    onMatch(handler: MatchHandler): () => void {
+        this.matcher.on('match', handler);
+        return () => this.matcher.off('match', handler);
+    }
+
+    /**
+     * Subscribe to error events.
+     * Returns cleanup function for React useEffect compatibility.
+     */
+    onError(handler: (error: Error) => void): () => void {
+        this.matcher.on('error', handler);
+        return () => this.matcher.off('error', handler);
+    }
+
+    /** Explicit cleanup for match handler */
+    offMatch(handler: MatchHandler): void {
+        this.matcher.off('match', handler);
+    }
+
+    /** Explicit cleanup for error handler */
+    offError(handler: (error: Error) => void): void {
+        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: string): Promise<Match | null> {
+        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(): string {
+        return this.identity.getDisplayName();
+    }
+}
+
+// Re-exports
+export { formatQR, parseQR };
+export type {
+    Match,
+    MatchHandler,
+    ReportMetadata,
+    KeyStorage,
+    VailixConfig,
+    NearbyUser,
+    PairResult
+};

package/src/matcher.ts

@@ -0,0 +1,224 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { createDecipheriv } from 'react-native-quick-crypto';
+import { EventEmitter } from 'eventemitter3';
+import type { StorageService } from './storage';
+import type { Match, ReportMetadata } from './types';
+
+const LAST_SYNC_KEY = 'vailix_last_sync';
+
+interface ServerKey {
+    rpi: string;
+    metadata?: string;
+    reportedAt: number;
+}
+
+export class MatcherService extends EventEmitter {
+    constructor(
+        private storage: StorageService,
+        private downloadUrl: string,
+        private appSecret: string
+    ) { super(); }
+
+    async fetchAndMatch(): Promise<Match[]> {
+        try {
+            let lastSync = parseInt(await AsyncStorage.getItem(LAST_SYNC_KEY) || '0', 10);
+            const allMatches: Match[] = [];
+            let maxReportedAt = lastSync;
+
+            // Stream keys page by page to avoid OOM
+            // Process each page immediately and discard from memory
+            await this._downloadAndProcessKeys(lastSync, async (keys) => {
+                if (keys.length === 0) return;
+
+                // Track max timestamp for sync cursor
+                const pageMax = Math.max(...keys.map(k => k.reportedAt));
+                maxReportedAt = Math.max(maxReportedAt, pageMax);
+
+                // Map for O(1) lookup
+                const infectedMap = new Map<string, ServerKey>();
+                for (const key of keys) infectedMap.set(key.rpi, key);
+
+                // Match current batch against DB
+                const infectedRpis = Array.from(infectedMap.keys());
+                const matchingScans = await this.storage.getMatchingScans(infectedRpis);
+
+                // Process matches
+                for (const s of matchingScans) {
+                    const serverKey = infectedMap.get(s.rpi)!;
+
+                    // PRIVACY: Store ENCRYPTED metadata for on-demand decryption
+                    // Never persist decrypted data to storage
+                    await AsyncStorage.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
+                    }));
+
+                    // Return match with empty metadata (will be decrypted on-demand)
+                    allMatches.push({
+                        rpi: s.rpi,
+                        timestamp: s.timestamp,
+                        metadata: undefined,  // Not decrypted yet!
+                        reportedAt: serverKey.reportedAt,
+                    });
+                }
+            });
+
+            // Update sync checkpoint only after successful processing
+            if (maxReportedAt > lastSync) {
+                await AsyncStorage.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 [];
+        }
+    }
+
+    private async _downloadAndProcessKeys(since: number, processor: (keys: ServerKey[]) => Promise<void>): Promise<void> {
+        let cursor: string | null = 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);
+
+            // Process chunk immediately
+            await processor(keys);
+
+            cursor = res.headers.get('x-vailix-next-cursor') || null;
+
+            // Yield to event loop to free memory/prevent UI freeze
+            await new Promise(resolve => setTimeout(resolve, 0));
+        } while (cursor);
+    }
+
+    private _parseBinaryResponse(buffer: ArrayBuffer): ServerKey[] {
+        const view = new DataView(buffer);
+        const keys: ServerKey[] = [];
+        let offset = 0;
+
+        // Header: Count (4 bytes)
+        if (buffer.byteLength < 4) return [];
+        const count = view.getUint32(offset);
+        offset += 4;
+
+        for (let i = 0; i < count; i++) {
+            // Bounds check: minimum key size is 16 (RPI) + 8 (timestamp) + 2 (metaLen) = 26 bytes
+            if (offset + 26 > buffer.byteLength) {
+                console.warn(`Binary response truncated at key ${i}/${count}`);
+                break;
+            }
+
+            // RPI: 16 bytes (Bin) -> 32 hex chars
+            const rpiBytes = new Uint8Array(buffer, offset, 16);
+            const rpi = Array.from(rpiBytes).map(b => b.toString(16).padStart(2, '0')).join('');
+            offset += 16;
+
+            // Timestamp: 8 bytes (Double)
+            const reportedAt = view.getFloat64(offset);
+            offset += 8;
+
+            // Metadata: Len (2 bytes) + Bytes
+            const metaLen = view.getUint16(offset);
+            offset += 2;
+
+            let metadata: string | undefined = undefined;
+            if (metaLen > 0) {
+                // Bounds check for metadata
+                if (offset + metaLen > buffer.byteLength) {
+                    console.warn(`Binary response truncated during metadata at key ${i}/${count}`);
+                    break;
+                }
+                const metaBytes = new Uint8Array(buffer, offset, metaLen);
+                // TextDecoder correctly handles multi-byte UTF-8 (available in Hermes)
+                metadata = new TextDecoder('utf-8').decode(metaBytes);
+                offset += metaLen;
+            }
+
+            keys.push({ rpi, reportedAt, metadata });
+        }
+        return keys;
+    }
+
+    private _decrypt(encryptedStr: string | undefined | null, keyHex: string): ReportMetadata | undefined {
+        if (!encryptedStr) return undefined;
+        try {
+            const parts = encryptedStr.split(':');
+            if (parts.length !== 3) return undefined;
+
+            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 as any);
+
+            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 undefined;
+        }
+    }
+
+    /**
+     * 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: string): Promise<Match | null> {
+        try {
+            // Retrieve encrypted match from cache
+            const cachedData = await AsyncStorage.getItem(`vailix_match_cache_${rpi}`);
+            if (!cachedData) {
+                console.warn(`Match ${rpi} not found in cache`);
+                return null;
+            }
+
+            const cached = JSON.parse(cachedData);
+
+            // Decrypt metadata ON-DEMAND (result only in memory)
+            const decryptedMetadata = this._decrypt(
+                cached.encryptedMetadata,
+                cached.metadataKey
+            );
+
+            // Return ephemeral result (lives only in caller's memory)
+            return {
+                rpi: rpi,
+                timestamp: cached.timestamp,
+                metadata: decryptedMetadata,
+                reportedAt: cached.reportedAt
+            };
+        } catch (error) {
+            console.error('Failed to get match by ID:', error);
+            return null;
+        }
+    }
+}