@vailix/mask 0.1.2

package/src/storage.ts

@@ -0,0 +1,110 @@
+import { sqliteTable, text, integer, index } from 'drizzle-orm/sqlite-core';
+import { lt, gt, inArray } from 'drizzle-orm';
+import { randomUUID } from 'react-native-quick-crypto';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { VailixDB } from './types';
+
+const SCAN_HISTORY_KEY = 'vailix_scan_history';
+
+export const 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)]);
+
+/** Type for a scanned event row */
+export type ScannedEvent = typeof scannedEvents.$inferSelect;
+
+export class StorageService {
+    private rescanIntervalMs: number;
+    private lastScanByRpi = new Map<string, number>();
+
+    // Limit scan history to prevent unbounded memory growth
+    private static readonly MAX_SCAN_HISTORY_SIZE = 10000;
+
+    constructor(private db: VailixDB, config: { rescanIntervalMs?: number } = {}) {
+        this.rescanIntervalMs = config.rescanIntervalMs ?? 0;
+    }
+
+    // Load persisted scan history on init
+    async initialize(): Promise<void> {
+        const stored = await AsyncStorage.getItem(SCAN_HISTORY_KEY);
+        if (stored) {
+            const entries: [string, number][] = JSON.parse(stored);
+            this.lastScanByRpi = new Map(entries);
+        }
+    }
+
+    // Check if rescan is allowed for this RPI
+    canScan(rpi: string): boolean {
+        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: string, metadataKey: string, timestamp: number): Promise<void> {
+        await this.db.insert(scannedEvents).values({ id: randomUUID(), rpi, metadataKey, timestamp });
+        this.lastScanByRpi.set(rpi, Date.now());
+
+        // Prune oldest entries if exceeding max size (prevents unbounded growth)
+        if (this.lastScanByRpi.size > StorageService.MAX_SCAN_HISTORY_SIZE) {
+            const entries = Array.from(this.lastScanByRpi.entries());
+            entries.sort((a, b) => a[1] - b[1]); // Sort by timestamp ascending
+            const toRemove = entries.slice(0, entries.length - StorageService.MAX_SCAN_HISTORY_SIZE);
+            for (const [key] of toRemove) {
+                this.lastScanByRpi.delete(key);
+            }
+        }
+
+        // Persist scan history
+        const entries = Array.from(this.lastScanByRpi.entries());
+        await AsyncStorage.setItem(SCAN_HISTORY_KEY, JSON.stringify(entries));
+    }
+
+    async cleanupOldScans(): Promise<void> {
+        const cutoff = Date.now() - 14 * 24 * 60 * 60 * 1000;
+        await this.db.delete(scannedEvents).where(lt(scannedEvents.timestamp, cutoff));
+        // Also cleanup old RPI entries
+        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: string[]): Promise<ScannedEvent[]> {
+        if (rpiList.length === 0) return [];
+
+        // SQLite limit is often 999 or 32766 variables. 
+        // We stick to a safe 500 batch size to be conservative across devices.
+        const BATCH_SIZE = 500;
+        const results: ScannedEvent[] = [];
+
+        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: number = 24): Promise<ScannedEvent[]> {
+        const cutoff = Date.now() - (withinHours * 60 * 60 * 1000);
+        const recent = await this.db.select()
+            .from(scannedEvents)
+            .where(gt(scannedEvents.timestamp, cutoff))
+            .orderBy(scannedEvents.timestamp);
+        return recent;
+    }
+}

package/src/transport.ts

@@ -0,0 +1,20 @@
+const VERSION = 'v1';
+
+// Format: proto:v1:rpi:timestamp:metadataKey
+export function formatQR(rpi: string, metadataKey: string): string {
+    return `proto:${VERSION}:${rpi}:${Date.now()}:${metadataKey}`;
+}
+
+export function parseQR(data: string): ParsedQR | null {
+    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] };
+}
+
+interface ParsedQR {
+    rpi: string;
+    timestamp: number;
+    metadataKey: string;
+}

package/src/types.ts

@@ -0,0 +1,100 @@
+import type { ExpoSQLiteDatabase } from 'drizzle-orm/expo-sqlite';
+
+// Optional metadata apps can attach when reporting
+export interface ReportMetadata {
+    [key: string]: string | number | boolean | (string | number | boolean)[] | undefined;
+}
+
+// Match result with optional reporter metadata
+export interface Match {
+    rpi: string;
+    timestamp: number;
+    metadata?: ReportMetadata;
+    reportedAt?: number;
+}
+
+export interface ScanEvent {
+    id: string;
+    rpi: string;
+    timestamp: number;
+}
+
+// Key storage interface — allows apps to provide custom storage (e.g., iCloud sync)
+export interface KeyStorage {
+    getKey(): Promise<string | null>;
+    setKey(key: string): Promise<void>;
+}
+
+export type MatchHandler = (matches: Match[]) => void;
+export type VailixDB = ExpoSQLiteDatabase<Record<string, never>>;
+
+// ============================================================================
+// BLE Types
+// ============================================================================
+
+/**
+ * Represents a nearby user discovered via BLE.
+ * 
+ * Design: Internal details (RPI, metadataKey) are hidden from the public API.
+ * The app only needs: something to display, something to pair with, and status flags.
+ * RPIs and keys are managed internally by the package for contact tracing.
+ */
+export interface NearbyUser {
+    /** Opaque identifier for pairing (pass to pairWithUser) */
+    id: string;
+    /** Generated emoji + number for UI display */
+    displayName: string;
+    /** Signal strength (for proximity filtering) */
+    rssi: number;
+    /** Timestamp of last advertisement received */
+    discoveredAt: number;
+    /** true if we have securely stored their data */
+    paired: boolean;
+    /** true if they sent us data but we haven't accepted yet (explicit mode) */
+    hasIncomingRequest: boolean;
+    /** Timestamp when pairing occurred (optional, populated after successful pair) */
+    pairedAt?: number;
+}
+
+/** Result of a pairing attempt */
+export interface PairResult {
+    success: boolean;
+    partnerRpi?: string;
+    partnerMetadataKey?: string;
+    error?: string;
+}
+
+/**
+ * Unified SDK Configuration Interface
+ */
+export interface VailixConfig {
+    // --- Backend & Auth ---
+    /** The live API endpoint for submitting reports */
+    reportUrl: string;
+    /** The endpoint for downloading keys (can be the same as reportUrl or a CDN) */
+    downloadUrl: string;
+    /** Application secret for API authentication */
+    appSecret: string;
+
+    // --- Storage ---
+    /** Custom key storage adapter (default: expo-secure-store) */
+    keyStorage?: KeyStorage;
+    /** Number of days of history to include in reports (default: 14) */
+    reportDays?: number;
+
+    // --- Contact Tracing Protocol ---
+    /** How long RPI persists in ms (default: 15min, can be 24h for STD apps) */
+    rpiDurationMs?: number;
+    /** Minimum time between scans of same RPI in ms (default: 0 = no limit) */
+    rescanIntervalMs?: number;
+
+    // --- BLE Proximity & Pairing ---
+    /** Timeout before removing a user from nearby list in ms (default: 15000) */
+    bleDiscoveryTimeoutMs?: number;
+    /** Minimum RSSI to consider a user "nearby" (default: -70) */
+    proximityThreshold?: number;
+    /** If true, automatically pair when receiving a write (default: true) */
+    autoAcceptIncomingPairs?: boolean;
+    /** Custom BLE Service UUID (default: a1b2c3d4-e5f6-7890-abcd-ef1234567890) */
+    serviceUUID?: string;
+}

package/src/utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared utilities for @vailix/mask
+ */
+
+// Display name generation constants
+export const EMOJIS = ['🐼', '🦊', '🐨', '🦁', '🐯', '🐸', '🦋', '🐙', '🦄', '🐳'];
+
+/**
+ * Generate deterministic display name from truncated RPI (or full RPI).
+ * Ensures all scanners see the same name for the same user.
+ * 
+ * @param rpiPrefix - RPI or RPI prefix (at least 8 chars recommended)
+ * @returns Emoji + Number string (e.g., "🐼 42")
+ */
+export function generateDisplayName(rpiPrefix: string): string {
+    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}`;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "ESNext",
+        "jsx": "react-native",
+        "moduleResolution": "bundler",
+        "lib": [
+            "ESNext"
+        ]
+    },
+    "include": [
+        "src"
+    ]
+}