@affectively/dash 5.3.0 → 5.4.0

package/dist/src/engine/sqlite.d.ts

@@ -1,4 +1,5 @@
 import { LensEngine } from '../schema/lens.js';
+import type { RelayDiscoveryConfig, RelayPerformanceConfig, RelayPrivacyConfig } from '../sync/hybrid-provider.js';
 /**
  * Cloud sync configuration - enables automatic D1/R2 AND Relay sync
  *
@@ -20,6 +21,12 @@ export interface CloudConfig {
     relayRoom?: string;
     /** Enable high-frequency mode for Relay (uses WebTransport if available) */
     relayHighFrequency?: boolean;
+    /** Optional peer discovery settings for Relay endpoint routing */
+    relayDiscovery?: RelayDiscoveryConfig;
+    /** Optional performance settings (adaptive compression + batching) */
+    relayPerformance?: RelayPerformanceConfig;
+    /** Optional privacy settings (room-scoped payload encryption) */
+    relayPrivacy?: RelayPrivacyConfig;
     /** Auth token getter - called before each sync */
     getAuthToken?: () => Promise<string | null>;
     /** User ID for relay room naming */

package/dist/src/engine/sqlite.js

@@ -589,6 +589,9 @@ export class DashEngine {
                     maxOfflineQueueSize: 1000,
                     maxOfflineRetries: 5,
                 },
+                relayDiscovery: config.relayDiscovery,
+                relayPerformance: config.relayPerformance,
+                relayPrivacy: config.relayPrivacy,
             });
             // Listen for remote changes and apply to local SQLite
             this.relayDoc.on('update', (update, origin) => {

package/dist/src/index.d.ts

@@ -6,6 +6,12 @@ export { YjsSqliteProvider } from './sync/provider.js';
 export { backup, restore, generateKey, exportKey, importKey } from './sync/backup.js';
 export type { CloudStorageAdapter } from './sync/backup.js';
 export { HybridProvider } from './sync/hybrid-provider.js';
+export type { RelayDiscoveryConfig, RelayPerformanceConfig, RelayPrivacyConfig, ConnectionStatus, ProviderStatus, } from './sync/hybrid-provider.js';
+export { AutomergeProvider } from './sync/AutomergeProvider.js';
+export type { AutomergeProviderOptions } from './sync/AutomergeProvider.js';
+export type { AutomergeProviderConfig } from './sync/types.js';
+export { AeonDurableSyncRuntime } from './sync/AeonDurableSync.js';
+export type { AeonDurableSyncConfig } from './sync/AeonDurableSync.js';
 export { D1SyncProvider, getD1SyncProvider, resetD1SyncProvider } from './sync/d1-provider.js';
 export type { D1SyncConfig, SyncResult, SyncQueueEntry } from './sync/d1-provider.js';
 export * as firebase from './api/firebase/index.js';

package/dist/src/index.js

@@ -5,6 +5,8 @@ export { mcpServer } from './mcp/server.js';
 export { YjsSqliteProvider } from './sync/provider.js';
 export { backup, restore, generateKey, exportKey, importKey } from './sync/backup.js';
 export { HybridProvider } from './sync/hybrid-provider.js';
+export { AutomergeProvider } from './sync/AutomergeProvider.js';
+export { AeonDurableSyncRuntime } from './sync/AeonDurableSync.js';
 // D1 HTTP Sync (legacy - prefer dash.enableCloudSync())
 export { D1SyncProvider, getD1SyncProvider, resetD1SyncProvider } from './sync/d1-provider.js';
 // Firebase Compatibility API exports

package/dist/src/sync/AeonDurableSync.d.ts

@@ -0,0 +1,26 @@
+/**
+ * AeonDurableSync - Durable telemetry runtime for sync operations
+ *
+ * Records transport selection, discovery events, and sync protocol messages
+ * using Aeon's OfflineOperationQueue, SyncProtocol, and ReplicationManager.
+ *
+ * Operates in-memory by default. Persistence requires @affectively/aeon/persistence
+ * (available in a future release).
+ */
+type TransportType = 'websocket' | 'webtransport' | null;
+export interface AeonDurableSyncConfig {
+    enabled?: boolean;
+    roomName: string;
+    persistenceKeyPrefix?: string;
+}
+export declare class AeonDurableSyncRuntime {
+    private readonly queue;
+    private readonly protocol;
+    private readonly replication;
+    constructor(config: AeonDurableSyncConfig);
+    initialize(): Promise<void>;
+    recordTransportSelection(roomName: string, transport: TransportType, relay: string | null): void;
+    recordDiscovery(roomName: string, relays: string[]): void;
+    getPendingOperations(): number;
+}
+export {};

package/dist/src/sync/AeonDurableSync.js

@@ -0,0 +1,67 @@
+/**
+ * AeonDurableSync - Durable telemetry runtime for sync operations
+ *
+ * Records transport selection, discovery events, and sync protocol messages
+ * using Aeon's OfflineOperationQueue, SyncProtocol, and ReplicationManager.
+ *
+ * Operates in-memory by default. Persistence requires @affectively/aeon/persistence
+ * (available in a future release).
+ */
+import { OfflineOperationQueue, SyncProtocol, ReplicationManager, } from '@affectively/aeon';
+export class AeonDurableSyncRuntime {
+    queue;
+    protocol;
+    replication;
+    constructor(config) {
+        // Construct without persistence options — in-memory only until
+        // @affectively/aeon/persistence ships.
+        this.queue = new OfflineOperationQueue();
+        this.protocol = new SyncProtocol();
+        this.replication = new ReplicationManager();
+    }
+    async initialize() {
+        // No-op until persistence module is available.
+        // When @affectively/aeon/persistence ships, this will hydrate from storage.
+    }
+    recordTransportSelection(roomName, transport, relay) {
+        if (!transport) {
+            return;
+        }
+        try {
+            this.queue.enqueue('update', {
+                roomName,
+                event: 'transport-selected',
+                transport,
+                relay,
+                ts: Date.now(),
+            }, roomName, 'normal');
+            this.protocol.createSyncRequestMessage(roomName, relay ?? 'unknown-relay', `transport-${Date.now()}`, '0.0.0', '1.1.0', {
+                transport,
+                relay,
+            });
+        }
+        catch {
+            // Telemetry durability must never impact foreground sync operations.
+        }
+    }
+    recordDiscovery(roomName, relays) {
+        const sanitizedRelays = relays
+            .filter((relay) => typeof relay === 'string' && relay.length > 0)
+            .slice(0, 32);
+        try {
+            this.queue.enqueue('sync', {
+                roomName,
+                event: 'relay-discovery',
+                count: sanitizedRelays.length,
+                relays: sanitizedRelays,
+                ts: Date.now(),
+            }, roomName, 'low');
+        }
+        catch {
+            // Telemetry durability must never impact foreground sync operations.
+        }
+    }
+    getPendingOperations() {
+        return this.queue.getPendingCount();
+    }
+}

package/dist/src/sync/AutomergeProvider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * AutomergeProvider - Automerge sync over WebSocket relay
+ *
+ * Mirrors HybridProvider's transport selection and discovery logic
+ * but uses Automerge's built-in sync protocol instead of Yjs.
+ * The relay server is CRDT-agnostic — it relays opaque binary frames.
+ *
+ * @automerge/automerge is dynamically imported so users who only use
+ * Yjs never pay the bundle cost.
+ */
+import type { AutomergeProviderConfig } from './types.js';
+export interface AutomergeProviderOptions<T> {
+    onChange?: (doc: T) => void;
+}
+export declare class AutomergeProvider<T = unknown> {
+    private config;
+    private _doc;
+    private _onChange?;
+    private _ws;
+    private _syncState;
+    private _automerge;
+    private _ready;
+    private _destroyed;
+    private _reconnectTimer;
+    private _reconnectDelayMs;
+    private readonly _maxReconnectDelayMs;
+    constructor(doc: T, config: AutomergeProviderConfig, options?: AutomergeProviderOptions<T>);
+    private initialize;
+    private getRelayUrl;
+    private connectWebSocket;
+    private scheduleReconnect;
+    private sendSyncMessage;
+    private handleMessage;
+    /**
+     * Update the local document. Required because Automerge documents are immutable —
+     * after calling Automerge.change(), pass the new doc here to sync it.
+     */
+    updateDoc(newDoc: T): void;
+    get doc(): T;
+    get ready(): Promise<void>;
+    get roomName(): string;
+    get connected(): boolean;
+    disconnect(): void;
+    destroy(): Promise<void>;
+}

package/dist/src/sync/AutomergeProvider.js

@@ -0,0 +1,153 @@
+/**
+ * AutomergeProvider - Automerge sync over WebSocket relay
+ *
+ * Mirrors HybridProvider's transport selection and discovery logic
+ * but uses Automerge's built-in sync protocol instead of Yjs.
+ * The relay server is CRDT-agnostic — it relays opaque binary frames.
+ *
+ * @automerge/automerge is dynamically imported so users who only use
+ * Yjs never pay the bundle cost.
+ */
+export class AutomergeProvider {
+    config;
+    _doc;
+    _onChange;
+    _ws = null;
+    _syncState = null;
+    _automerge = null;
+    _ready;
+    _destroyed = false;
+    _reconnectTimer = null;
+    _reconnectDelayMs = 1000;
+    _maxReconnectDelayMs = 30_000;
+    constructor(doc, config, options) {
+        this._doc = doc;
+        this.config = config;
+        this._onChange = options?.onChange;
+        this._ready = this.initialize();
+    }
+    async initialize() {
+        const am = await import('@automerge/automerge');
+        this._automerge = am;
+        this._syncState = am.initSyncState();
+        this.connectWebSocket();
+    }
+    getRelayUrl() {
+        if (this.config.websocket?.url) {
+            return toWsUrl(this.config.websocket.url);
+        }
+        if (this.config.webtransport?.url) {
+            return toWsUrl(this.config.webtransport.url);
+        }
+        return null;
+    }
+    connectWebSocket() {
+        if (this._destroyed)
+            return;
+        const relayUrl = this.getRelayUrl();
+        if (!relayUrl)
+            return;
+        const separator = relayUrl.includes('?') ? '&' : '?';
+        const params = new URLSearchParams({ room: this.config.roomName });
+        if (this.config.apiKey) {
+            params.set('apiKey', this.config.apiKey);
+        }
+        const url = `${relayUrl}${separator}${params.toString()}`;
+        try {
+            this._ws = new WebSocket(url);
+            this._ws.binaryType = 'arraybuffer';
+        }
+        catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this._ws.addEventListener('open', () => {
+            this._reconnectDelayMs = 1000;
+            this.sendSyncMessage();
+        });
+        this._ws.addEventListener('message', (event) => {
+            this.handleMessage(event.data);
+        });
+        this._ws.addEventListener('close', () => {
+            this._ws = null;
+            this.scheduleReconnect();
+        });
+        this._ws.addEventListener('error', () => {
+            // close event will follow and trigger reconnect
+        });
+    }
+    scheduleReconnect() {
+        if (this._destroyed || this._reconnectTimer)
+            return;
+        this._reconnectTimer = setTimeout(() => {
+            this._reconnectTimer = null;
+            this.connectWebSocket();
+        }, this._reconnectDelayMs);
+        this._reconnectDelayMs = Math.min(this._reconnectDelayMs * 2, this._maxReconnectDelayMs);
+    }
+    sendSyncMessage() {
+        const am = this._automerge;
+        if (!am || !this._ws || this._ws.readyState !== WebSocket.OPEN)
+            return;
+        const [nextSyncState, message] = am.generateSyncMessage(this._doc, this._syncState);
+        this._syncState = nextSyncState;
+        if (message) {
+            this._ws.send(message);
+        }
+    }
+    handleMessage(data) {
+        const am = this._automerge;
+        if (!am)
+            return;
+        const message = new Uint8Array(data);
+        const [nextDoc, nextSyncState] = am.receiveSyncMessage(this._doc, this._syncState, message);
+        this._doc = nextDoc;
+        this._syncState = nextSyncState;
+        this._onChange?.(this._doc);
+        // After receiving, we may need to send our own changes
+        this.sendSyncMessage();
+    }
+    /**
+     * Update the local document. Required because Automerge documents are immutable —
+     * after calling Automerge.change(), pass the new doc here to sync it.
+     */
+    updateDoc(newDoc) {
+        this._doc = newDoc;
+        this.sendSyncMessage();
+    }
+    get doc() {
+        return this._doc;
+    }
+    get ready() {
+        return this._ready;
+    }
+    get roomName() {
+        return this.config.roomName;
+    }
+    get connected() {
+        return this._ws !== null && this._ws.readyState === WebSocket.OPEN;
+    }
+    disconnect() {
+        if (this._reconnectTimer) {
+            clearTimeout(this._reconnectTimer);
+            this._reconnectTimer = null;
+        }
+        if (this._ws) {
+            this._ws.close();
+            this._ws = null;
+        }
+    }
+    async destroy() {
+        this._destroyed = true;
+        this.disconnect();
+    }
+}
+function toWsUrl(url) {
+    if (url.startsWith('wss://') || url.startsWith('ws://'))
+        return url;
+    if (url.startsWith('https://'))
+        return `wss://${url.slice('https://'.length)}`;
+    if (url.startsWith('http://'))
+        return `ws://${url.slice('http://'.length)}`;
+    return url;
+}

package/dist/src/sync/d1-provider.d.ts

@@ -9,7 +9,11 @@
  * Architecture:
  * - Local changes are tracked in a sync_queue table
  * - Sync runs periodically or on-demand
- * - Conflicts are resolved using last-write-wins with timestamps
+ * - Conflicts are resolved using last-write-wins with _lastModified timestamps
+ *
+ * Security:
+ * - Table/column names are validated against allowed patterns
+ * - All user data uses parameterized queries
  */
 export interface D1SyncConfig {
     /** Base URL for the sync endpoint (e.g., 'https://example.com/api') */
@@ -53,6 +57,7 @@ export declare class D1SyncProvider {
     initialize(): Promise<void>;
     /**
      * Set up SQLite triggers to track changes for a table
+     * Uses validated identifiers to prevent SQL injection
      */
     private setupTableTriggers;
     /**
@@ -68,7 +73,8 @@ export declare class D1SyncProvider {
      */
     sync(): Promise<SyncResult>;
     /**
-     * Apply changes received from the server
+     * Apply changes received from the server with Last-Write-Wins (LWW) conflict resolution
+     * Server changes only win if their _lastModified is newer than local
      */
     private applyServerChanges;
     /**

package/dist/src/sync/d1-provider.js

@@ -9,9 +9,26 @@
  * Architecture:
  * - Local changes are tracked in a sync_queue table
  * - Sync runs periodically or on-demand
- * - Conflicts are resolved using last-write-wins with timestamps
+ * - Conflicts are resolved using last-write-wins with _lastModified timestamps
+ *
+ * Security:
+ * - Table/column names are validated against allowed patterns
+ * - All user data uses parameterized queries
  */
 import { dash } from '../engine/sqlite.js';
+// Valid identifier pattern (prevents SQL injection)
+const VALID_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Validate and escape a SQL identifier (table or column name)
+ * Throws if the identifier is invalid
+ */
+function escapeIdentifier(name) {
+    if (!VALID_IDENTIFIER.test(name)) {
+        throw new Error(`Invalid SQL identifier: ${name}`);
+    }
+    // Double-quote the identifier for safety
+    return `"${name}"`;
+}
 export class D1SyncProvider {
     config;
     syncTimer = null;
@@ -72,42 +89,69 @@ export class D1SyncProvider {
     }
     /**
      * Set up SQLite triggers to track changes for a table
+     * Uses validated identifiers to prevent SQL injection
      */
     setupTableTriggers(tableName) {
+        // Validate table name to prevent SQL injection
+        const safeTableName = escapeIdentifier(tableName);
+        const triggerSuffix = tableName.replace(/[^a-zA-Z0-9_]/g, '_');
         // Clean up existing triggers first
         try {
-            dash.execute(`DROP TRIGGER IF EXISTS dash_sync_${tableName}_insert`);
-            dash.execute(`DROP TRIGGER IF EXISTS dash_sync_${tableName}_update`);
-            dash.execute(`DROP TRIGGER IF EXISTS dash_sync_${tableName}_delete`);
+            dash.execute(`DROP TRIGGER IF EXISTS dash_sync_${triggerSuffix}_insert`);
+            dash.execute(`DROP TRIGGER IF EXISTS dash_sync_${triggerSuffix}_update`);
+            dash.execute(`DROP TRIGGER IF EXISTS dash_sync_${triggerSuffix}_delete`);
         }
         catch {
             // Ignore errors from dropping non-existent triggers
         }
-        // Create INSERT trigger
+        // Create INSERT trigger with parameterized table name in data
         dash.execute(`
-      CREATE TRIGGER IF NOT EXISTS dash_sync_${tableName}_insert
-      AFTER INSERT ON ${tableName}
+      CREATE TRIGGER IF NOT EXISTS dash_sync_${triggerSuffix}_insert
+      AFTER INSERT ON ${safeTableName}
       BEGIN
         INSERT INTO dash_sync_queue (table_name, row_id, operation, data)
-        VALUES ('${tableName}', NEW.id, 'create', json(NEW));
+        VALUES (
+          '${tableName.replace(/'/g, "''")}',
+          NEW.id,
+          'create',
+          json_object(
+            'id', NEW.id,
+            '_lastModified', strftime('%s', 'now') * 1000,
+            '_data', json(NEW)
+          )
+        );
       END
     `);
-        // Create UPDATE trigger
+        // Create UPDATE trigger with timestamp for LWW
         dash.execute(`
-      CREATE TRIGGER IF NOT EXISTS dash_sync_${tableName}_update
-      AFTER UPDATE ON ${tableName}
+      CREATE TRIGGER IF NOT EXISTS dash_sync_${triggerSuffix}_update
+      AFTER UPDATE ON ${safeTableName}
       BEGIN
         INSERT INTO dash_sync_queue (table_name, row_id, operation, data)
-        VALUES ('${tableName}', NEW.id, 'update', json(NEW));
+        VALUES (
+          '${tableName.replace(/'/g, "''")}',
+          NEW.id,
+          'update',
+          json_object(
+            'id', NEW.id,
+            '_lastModified', strftime('%s', 'now') * 1000,
+            '_data', json(NEW)
+          )
+        );
       END
     `);
         // Create DELETE trigger
         dash.execute(`
-      CREATE TRIGGER IF NOT EXISTS dash_sync_${tableName}_delete
-      AFTER DELETE ON ${tableName}
+      CREATE TRIGGER IF NOT EXISTS dash_sync_${triggerSuffix}_delete
+      AFTER DELETE ON ${safeTableName}
       BEGIN
         INSERT INTO dash_sync_queue (table_name, row_id, operation, data)
-        VALUES ('${tableName}', OLD.id, 'delete', NULL);
+        VALUES (
+          '${tableName.replace(/'/g, "''")}',
+          OLD.id,
+          'delete',
+          json_object('id', OLD.id, '_lastModified', strftime('%s', 'now') * 1000)
+        );
       END
     `);
     }
@@ -253,21 +297,49 @@ export class D1SyncProvider {
         return result;
     }
     /**
-     * Apply changes received from the server
+     * Apply changes received from the server with Last-Write-Wins (LWW) conflict resolution
+     * Server changes only win if their _lastModified is newer than local
      */
     async applyServerChanges(tableName, changes) {
+        const safeTableName = escapeIdentifier(tableName);
         for (const change of changes) {
             try {
+                const serverTimestamp = change._lastModified || 0;
+                const rowId = change.id;
                 // Check if this is a delete (marked by a flag or null data)
                 if (change.deleted || change._deleted) {
-                    dash.execute(`DELETE FROM ${tableName} WHERE id = ?`, [change.id]);
+                    // For deletes, check if local row exists and is older
+                    const local = dash.execute(`SELECT _lastModified FROM ${safeTableName} WHERE id = ?`, [rowId]);
+                    if (local.length === 0 || (local[0]._lastModified || 0) < serverTimestamp) {
+                        dash.execute(`DELETE FROM ${safeTableName} WHERE id = ?`, [rowId]);
+                        console.log(`[D1SyncProvider] LWW: Applied server delete for ${tableName}:${rowId}`);
+                    }
+                    else {
+                        console.log(`[D1SyncProvider] LWW: Skipped server delete (local is newer) for ${tableName}:${rowId}`);
+                    }
                     continue;
                 }
-                // Get column names from the change object
-                const columns = Object.keys(change).filter(k => !k.startsWith('_'));
+                // Check local record timestamp for LWW
+                const local = dash.execute(`SELECT _lastModified FROM ${safeTableName} WHERE id = ?`, [rowId]);
+                const localTimestamp = local.length > 0 ? (local[0]._lastModified || 0) : 0;
+                // Only apply if server is newer (or record doesn't exist locally)
+                if (localTimestamp >= serverTimestamp && local.length > 0) {
+                    console.log(`[D1SyncProvider] LWW: Skipped server change (local is newer) for ${tableName}:${rowId}`);
+                    continue;
+                }
+                // Get column names from the change object, excluding internal fields
+                const data = change._data || change;
+                const columns = Object.keys(data).filter(k => !k.startsWith('_'));
+                // Add _lastModified column for tracking
+                if (!columns.includes('_lastModified')) {
+                    columns.push('_lastModified');
+                }
+                const escapedColumns = columns.map(c => escapeIdentifier(c));
                 const placeholders = columns.map(() => '?').join(', ');
                 const values = columns.map(k => {
-                    const v = change[k];
+                    if (k === '_lastModified')
+                        return serverTimestamp;
+                    const v = data[k];
                     // Serialize objects/arrays to JSON
                     if (v !== null && typeof v === 'object') {
                         return JSON.stringify(v);
@@ -275,8 +347,9 @@ export class D1SyncProvider {
                     return v;
                 });
                 // Use INSERT OR REPLACE to handle both new and updated records
-                const sql = `INSERT OR REPLACE INTO ${tableName} (${columns.join(', ')}) VALUES (${placeholders})`;
+                const sql = `INSERT OR REPLACE INTO ${safeTableName} (${escapedColumns.join(', ')}) VALUES (${placeholders})`;
                 dash.execute(sql, values);
+                console.log(`[D1SyncProvider] LWW: Applied server change for ${tableName}:${rowId}`);
             }
             catch (err) {
                 console.error(`[D1SyncProvider] Failed to apply change to ${tableName}:`, err, change);