crowd-funder-for-time-pwa/doc/secure-storage-implementation.md

Secure Storage Implementation Guide for TimeSafari App

Overview

This document outlines the implementation of secure storage for the TimeSafari app. The implementation focuses on:

1. Platform-Specific Storage Solutions:

   • Web: SQLite with IndexedDB backend (absurd-sql)
   • Electron: SQLite with Node.js backend
   • Native: (Planned) SQLCipher with platform-specific secure storage

2. Key Features:

   • SQLite-based storage using absurd-sql for web
   • Platform-specific service factory pattern
   • Consistent API across platforms
   • Migration support from Dexie.js

Quick Start

1. Installation

# Core dependencies
npm install @jlongster/sql.js
npm install absurd-sql

# Platform-specific dependencies (for future native support)
npm install @capacitor/preferences
npm install @capacitor-community/biometric-auth

2. Basic Usage

// Using the platform service
import { PlatformServiceFactory } from '../services/PlatformServiceFactory';

// Get platform-specific service instance
const platformService = PlatformServiceFactory.getInstance();

// Example database operations
async function example() {
  try {
    // Query example
    const result = await platformService.dbQuery(
      "SELECT * FROM accounts WHERE did = ?",
      [did]
    );

    // Execute example
    await platformService.dbExec(
      "INSERT INTO accounts (did, public_key_hex) VALUES (?, ?)",
      [did, publicKeyHex]
    );

  } catch (error) {
    console.error('Database operation failed:', error);
  }
}

3. Platform Detection

// src/services/PlatformServiceFactory.ts
export class PlatformServiceFactory {
  static getInstance(): PlatformService {
    if (process.env.ELECTRON) {
      // Electron platform
      return new ElectronPlatformService();
    } else {
      // Web platform (default)
      return new AbsurdSqlDatabaseService();
    }
  }
}

4. Current Implementation Details

Web Platform (AbsurdSqlDatabaseService)

The web platform uses absurd-sql with IndexedDB backend:

// src/services/AbsurdSqlDatabaseService.ts
export class AbsurdSqlDatabaseService implements PlatformService {
  private static instance: AbsurdSqlDatabaseService | null = null;
  private db: AbsurdSqlDatabase | null = null;
  private initialized: boolean = false;

  // Singleton pattern
  static getInstance(): AbsurdSqlDatabaseService {
    if (!AbsurdSqlDatabaseService.instance) {
      AbsurdSqlDatabaseService.instance = new AbsurdSqlDatabaseService();
    }
    return AbsurdSqlDatabaseService.instance;
  }

  // Database operations
  async dbQuery(sql: string, params: unknown[] = []): Promise<QueryExecResult[]> {
    await this.waitForInitialization();
    return this.queueOperation<QueryExecResult[]>("query", sql, params);
  }

  async dbExec(sql: string, params: unknown[] = []): Promise<void> {
    await this.waitForInitialization();
    await this.queueOperation<void>("run", sql, params);
  }
}

Key features:

• Uses absurd-sql for SQLite in the browser
• Implements operation queuing for thread safety
• Handles initialization and connection management
• Provides consistent API across platforms

5. Migration from Dexie.js

The current implementation supports gradual migration from Dexie.js:

// Example of dual-storage pattern
async function getAccount(did: string): Promise<Account | undefined> {
  // Try SQLite first
  const platform = PlatformServiceFactory.getInstance();
  let account = await platform.dbQuery(
    "SELECT * FROM accounts WHERE did = ?",
    [did]
  );

  // Fallback to Dexie if needed
  if (USE_DEXIE_DB && !account) {
    account = await db.accounts.get(did);
  }

  return account;
}

Success Criteria

1. Functionality

   • Basic CRUD operations work correctly
   • Platform service factory pattern implemented
   • Error handling in place
   • Native platform support (planned)

2. Performance

   • Database operations complete within acceptable time
   • Operation queuing for thread safety
   • Proper initialization handling
   • Performance monitoring (planned)

3. Security

   • Basic data integrity
   • Encryption (planned for native platforms)
   • Secure key storage (planned)
   • Platform-specific security features (planned)

4. Testing

   • Basic unit tests
   • Comprehensive integration tests (planned)
   • Platform-specific tests (planned)
   • Migration tests (planned)

Next Steps

1. Native Platform Support

   • Implement SQLCipher for iOS/Android
   • Add platform-specific secure storage
   • Implement biometric authentication

2. Enhanced Security

   • Add encryption for sensitive data
   • Implement secure key storage
   • Add platform-specific security features

3. Testing and Monitoring

   • Add comprehensive test coverage
   • Implement performance monitoring
   • Add error tracking and analytics

4. Documentation

   • Add API documentation
   • Create migration guides
   • Document security measures