solarch-tauri

Official desktop runtime SDK for Solarch applications built with Tauri.

solarch-tauri provides native desktop capabilities, local encrypted credential storage, local SQLite persistence, offline mutation queuing, conflict reconciliation, safe filesystem management, and administrative dashboard integration for Solarch applications.

Architecture

Tauri Desktop Application (Webview)
            |
            |
      solarch-tauri
      ├── Runtime & Lifecycle
      ├── Secure Storage (Keyring)
      ├── Local Database (SQLite)
      ├── Offline Sync Engine
      ├── Filesystem & Attachments
      └── Dashboard Management
            |
            |
    @solarch/core-client (Canonical Protocol)
            |
            | (TLS / HTTPS / WSS)
       Solarch Server

Features

• 🚀 Desktop Runtime & Lifecycle: Native environment detection, desktop events, window management, and application lifecycle tracking (startup, resume, pause, shutdown).
• 🔐 Secure Session Persistence: Encrypted token and identity vaulting backed by native operating system keychains with token leakage prevention.
• 💾 Local Database & Migrations: Embedded SQLite local storage, structured JSON entity CRUD, and forward/backward schema migration management.
• 🔄 Offline-First Synchronization: Persistent mutation queuing, automatic recovery, conflict detection, and customizable reconciliation strategies (server-wins, client-wins, custom resolvers).
• 📁 Safe Filesystem & Attachments: Sandboxed file access with path traversal protection, MIME inference, and seamless attachment upload/download preparation.
• 📊 Dashboard & Administration: Typed administrative facade for inspecting project metadata, collection schemas, user accounts, operational logs, and system health metrics.
• 🛡️ Hardened Security: Parameterized queries, zero-token error logging, and full OWASP Top 10 mitigation.

Installation

npm i solarch-tauri

Quick Start

1. Initialize Client

import { SolarchTauriClient } from 'solarch-tauri';

export const client = new SolarchTauriClient({
  projectId: 'my-project-id',
  url: 'https://api.solarch.io',
  desktop: {
    database: {
      name: 'app_storage.db',
    },
    offline: {
      enabled: true,
      autoSyncOnResume: true,
    },
  },
});

2. Session Management

import { SessionManager, DefaultTauriSecureStorageAdapter } from 'solarch-tauri';

const secureStorage = new DefaultTauriSecureStorageAdapter();
const sessionManager = new SessionManager(secureStorage);

// Save authenticated session
await sessionManager.save({
  token: 'bearer_token_xyz',
  model: { id: 'usr_1', email: '[email protected]' },
});

// Check session state
const hasSession = await sessionManager.hasSession();

3. Local Storage & Offline Mutations

import { LocalStore, MutationQueue, SyncEngine, DefaultTauriDatabaseAdapter } from 'solarch-tauri';

const db = new DefaultTauriDatabaseAdapter('app_storage.db');
await db.connect();

const store = new LocalStore(db);
const queue = new MutationQueue(store);
const syncEngine = new SyncEngine(client, store, { queue });

// Queue offline mutation
await queue.enqueue({
  collection: 'notes',
  operation: 'create',
  payload: { title: 'Offline Note', body: 'Will sync when online.' },
});

// Run synchronization
const processedCount = await syncEngine.sync();

4. Desktop File & Attachment Handling

import { AttachmentManager, DefaultTauriFileSystemAdapter } from 'solarch-tauri';

const fs = new DefaultTauriFileSystemAdapter();
const attachments = new AttachmentManager(fs, store, client);

// Register a local file attachment
const attachment = await attachments.register({
  collection: 'documents',
  recordId: 'doc_101',
  localPath: 'invoices/august.pdf',
});

// Prepare binary upload payload
const uploadPayload = await attachments.prepareUpload(attachment.id);

5. Administrative Dashboard

import { DashboardClient } from 'solarch-tauri';

const dashboard = new DashboardClient(client, { sessionManager });

// Query collection schemas
const collections = await dashboard.collections.list();

// Inspect health metrics
const health = await dashboard.monitoring.getHealth();

Feature Matrix

| Subsystem | Module | Status | Security Level | | :--- | :--- | :--- | :--- | | Connection & Protocol | client | Stable | Sanitized errors, Core Client delegation | | Desktop Runtime | desktop | Stable | Quarantined in adapters/tauri/ | | Secure Storage | auth | Stable | OS Keychain vaulting | | Local Database | storage | Stable | Parameterized SQLite, Migrations | | Offline Sync Engine | sync | Stable | Replay defense, Reconciler | | Filesystem & Attachments | filesystem | Stable | Path traversal protection | | Dashboard Management | dashboard | Stable | Role isolated, Token protected | | CLI Scaffolding | cli | Stable | Zero-secret generation guarantee |

Security

Please see SECURITY.md for our detailed security policy, threat model, and vulnerability disclosure process.

License

MIT © Solarch