holosphere 2.0.0-alpha13 → 2.0.0-alpha15

package/src/storage/nostr-async.js

@@ -3,11 +3,13 @@
  *
  * Provides Promise-based wrappers and async patterns for Nostr operations.
  * Includes local-first data access, query deduplication, subscription management,
- * and background refresh capabilities for optimal performance.
+ * background refresh capabilities, and symmetric encryption for secure federation.
  *
  * @module storage/nostr-async
  */
 
+import { encryptWithKey, decryptWithKey, isEncrypted } from '../crypto/lens-keys.js';
+
 /**
  * Global subscription manager to prevent duplicate subscriptions.
  * Maps: subscriptionKey -> subscription object
@@ -36,6 +38,40 @@ const pendingQueries = new Map();
  */
 const QUERY_DEDUP_WINDOW = 2000;
 
+/**
+ * Parse event content, handling decryption if needed.
+ *
+ * @private
+ * @param {Object} event - Nostr event with content and tags
+ * @param {Buffer|null} lensKey - Symmetric key for decryption (optional)
+ * @returns {Object|null} Parsed data or null if parsing/decryption fails
+ */
+function _parseEventContent(event, lensKey = null) {
+  if (!event || !event.content) return null;
+
+  try {
+    // Check if event is encrypted (has ['encrypted', 'symmetric'] tag)
+    const encryptedTag = event.tags?.find(t => t[0] === 'encrypted');
+    const isSymmetricEncrypted = encryptedTag && encryptedTag[1] === 'symmetric';
+
+    if (isSymmetricEncrypted) {
+      if (!lensKey) {
+        // Encrypted but no key provided - can't decrypt
+        return null;
+      }
+      // Decrypt and parse
+      const decrypted = decryptWithKey(lensKey, event.content);
+      return JSON.parse(decrypted);
+    } else {
+      // Not encrypted, parse directly
+      return JSON.parse(event.content);
+    }
+  } catch (error) {
+    // Parsing or decryption failed
+    return null;
+  }
+}
+
 /**
  * Write data as Nostr event (parameterized replaceable event).
  *
@@ -45,10 +81,14 @@ const QUERY_DEDUP_WINDOW = 2000;
  * @param {number|Object} [kindOrOptions=30000] - Event kind (number) or options object
  * @param {number} [kindOrOptions.kind=30000] - Event kind
  * @param {string} [kindOrOptions.signingKey] - Private key to sign with (hex format)
+ * @param {Buffer} [kindOrOptions.lensKey] - Symmetric key for encryption (32-byte Buffer)
  * @returns {Promise<Object>} Published event result with relay responses
  * @example
  * const result = await nostrPut(client, 'myapp/holon123/items/item1', { name: 'Test' });
  * console.log(result.event.id); // Event ID
+ *
+ * // With encryption:
+ * const result = await nostrPut(client, 'myapp/holon123/items/item1', { name: 'Test' }, { lensKey: key });
  */
 export async function nostrPut(client, path, data, kindOrOptions = 30000) {
   // Support both old signature (kind as number) and new signature (options object)
@@ -56,17 +96,32 @@ export async function nostrPut(client, path, data, kindOrOptions = 30000) {
     ? { kind: kindOrOptions }
     : kindOrOptions;
   const kind = options.kind || 30000;
+  const { lensKey } = options;
+
+  // Prepare content - encrypt if lensKey is provided
+  let content;
+  const tags = [['d', path]];
+
+  if (lensKey) {
+    // Encrypt data with symmetric key
+    content = encryptWithKey(lensKey, JSON.stringify(data));
+    // Add encryption marker tag
+    tags.push(['encrypted', 'symmetric']);
+  } else {
+    content = JSON.stringify(data);
+  }
 
   const dataEvent = {
     kind,
     created_at: Math.floor(Date.now() / 1000),
-    tags: [
-      ['d', path], // d-tag for parameterized replaceable events
-    ],
-    content: JSON.stringify(data),
+    tags,
+    content,
   };
 
-  const publishOptions = options.signingKey ? { signingKey: options.signingKey } : {};
+  const publishOptions = {
+    ...(options.signingKey && { signingKey: options.signingKey }),
+    ...(options.waitForRelays && { waitForRelays: options.waitForRelays }),
+  };
   const result = await client.publish(dataEvent, publishOptions);
   return result;
 }
@@ -76,6 +131,7 @@ export async function nostrPut(client, path, data, kindOrOptions = 30000) {
  *
  * LOCAL-FIRST: Checks persistent storage first, never blocks on network.
  * Uses query deduplication to prevent duplicate relay queries within a time window.
+ * Supports decryption of encrypted content when lensKey is provided.
  *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path identifier
@@ -85,16 +141,21 @@ export async function nostrPut(client, path, data, kindOrOptions = 30000) {
  * @param {boolean} [options.includeAuthor=false] - If true, adds _author field to returned data
  * @param {boolean} [options.skipPersistent=false] - If true, skip persistent storage check
  * @param {number} [options.timeout=30000] - Query timeout in milliseconds
+ * @param {Buffer} [options.lensKey] - Symmetric key for decryption (32-byte Buffer)
  * @returns {Promise<Object|null>} Data or null if not found
  * @example
  * const data = await nostrGet(client, 'myapp/holon1/items/item1');
  * if (data) {
  *   console.log(data.name);
  * }
+ *
+ * // With decryption:
+ * const data = await nostrGet(client, 'myapp/holon1/items/item1', 30000, { lensKey: key });
  */
 export async function nostrGet(client, path, kind = 30000, options = {}) {
   const timeout = options.timeout !== undefined ? options.timeout : 30000;
   const authors = options.authors || [client.publicKey];
+  const { lensKey } = options;
 
   // CHECK LRU CACHE FIRST (always up-to-date, even before batched persist)
   // This ensures immediate reads after writes return fresh data
@@ -103,23 +164,19 @@ export async function nostrGet(client, path, kind = 30000, options = {}) {
     if (cachedEvent && cachedEvent.content) {
       // Verify author is in requested authors list
       if (authors.includes(cachedEvent.pubkey)) {
-        try {
-          const data = JSON.parse(cachedEvent.content);
-
-          // Skip null/undefined or deleted items
-          if (!data || data._deleted) {
-            return null;
-          }
+        const data = _parseEventContent(cachedEvent, lensKey);
 
-          // Optionally include author information
-          if (options.includeAuthor) {
-            data._author = cachedEvent.pubkey;
-          }
+        // Skip null/undefined or deleted items
+        if (!data || data._deleted) {
+          return null;
+        }
 
-          return data;
-        } catch (error) {
-          // Fall through if parsing fails
+        // Optionally include author information
+        if (options.includeAuthor) {
+          data._author = cachedEvent.pubkey;
         }
+
+        return data;
       }
     }
   }
@@ -132,29 +189,30 @@ export async function nostrGet(client, path, kind = 30000, options = {}) {
       if (!authors.includes(persistedEvent.pubkey)) {
         // Author mismatch - fall through to relay query
       } else {
-        try {
-          const data = JSON.parse(persistedEvent.content);
+        const data = _parseEventContent(persistedEvent, lensKey);
 
-          // Skip null/undefined or deleted items
-          if (!data || data._deleted) {
+        // Skip null/undefined or deleted items or decryption failures
+        if (!data || data._deleted) {
+          // If data is null due to missing key, fall through to relay query
+          // (might have a different version of the event)
+          if (persistedEvent.tags?.find(t => t[0] === 'encrypted') && !lensKey) {
+            // Encrypted but no key - can't read, return null
             return null;
           }
+          return null;
+        }
 
-          // Optionally include author information
-          if (options.includeAuthor) {
-            data._author = persistedEvent.pubkey;
-          }
-
-          // Trigger background refresh from relays (fire-and-forget)
-          if (client.refreshPathInBackground) {
-            client.refreshPathInBackground(path, kind, { authors, timeout });
-          }
+        // Optionally include author information
+        if (options.includeAuthor) {
+          data._author = persistedEvent.pubkey;
+        }
 
-          return data;
-        } catch (error) {
-          // Fall through to relay query if parsing fails
-          console.warn('[nostrGet] Failed to parse persisted event:', error);
+        // Trigger background refresh from relays (fire-and-forget)
+        if (client.refreshPathInBackground) {
+          client.refreshPathInBackground(path, kind, { authors, timeout });
         }
+
+        return data;
       }
     }
   }
@@ -203,6 +261,7 @@ export async function nostrGet(client, path, kind = 30000, options = {}) {
  * @returns {Promise<Object|null>} Data or null
  */
 async function _executeNostrGet(client, path, kind, authors, timeout, options) {
+  const { lensKey } = options;
   const filter = {
     kinds: [kind],
     authors: authors, // Support multiple authors for cross-holosphere queries
@@ -210,7 +269,7 @@ async function _executeNostrGet(client, path, kind, authors, timeout, options) {
     limit: authors.length, // Increase limit to get events from all authors
   };
 
-  const events = await client.query(filter, { timeout });
+  const events = await client.query(filter, { timeout, forceRelay: options.forceRelay });
 
   // Filter by author (relays may not respect authors filter)
   const authoredEvents = events.filter(event => authors.includes(event.pubkey));
@@ -222,21 +281,18 @@ async function _executeNostrGet(client, path, kind, authors, timeout, options) {
   // Get most recent event (across allowed authors)
   const event = authoredEvents.sort((a, b) => b.created_at - a.created_at)[0];
 
-  try {
-    const data = JSON.parse(event.content);
-    // Skip null/undefined or deleted items
-    if (!data || data._deleted) {
-      return null;
-    }
-    // Optionally include author information
-    if (options.includeAuthor) {
-      data._author = event.pubkey;
-    }
-    return data;
-  } catch (error) {
-    // Silent - return null for unparseable events
+  const data = _parseEventContent(event, lensKey);
+
+  // Skip null/undefined or deleted items
+  if (!data || data._deleted) {
     return null;
   }
+
+  // Optionally include author information
+  if (options.includeAuthor) {
+    data._author = event.pubkey;
+  }
+  return data;
 }
 
 /**
@@ -244,6 +300,7 @@ async function _executeNostrGet(client, path, kind, authors, timeout, options) {
  *
  * LOCAL-FIRST: Checks persistent storage first, never blocks on network.
  * Uses query deduplication to prevent duplicate relay queries within a time window.
+ * Supports decryption of encrypted content when lensKey is provided.
  *
  * @param {Object} client - NostrClient instance
  * @param {string} pathPrefix - Path prefix to match
@@ -254,6 +311,7 @@ async function _executeNostrGet(client, path, kind, authors, timeout, options) {
  * @param {boolean} [options.skipPersistent=false] - If true, skip persistent storage check
  * @param {number} [options.timeout=30000] - Query timeout in milliseconds
  * @param {number} [options.limit=1000] - Maximum number of events to retrieve
+ * @param {Buffer} [options.lensKey] - Symmetric key for decryption (32-byte Buffer)
  * @returns {Promise<Array>} Array of data objects
  * @example
  * const items = await nostrGetAll(client, 'myapp/holon1/items/');
@@ -263,6 +321,7 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
   const timeout = options.timeout !== undefined ? options.timeout : 30000;
   const limit = options.limit || 1000; // Increased limit to get more events
   const authors = options.authors || [client.publicKey];
+  const { lensKey } = options;
 
   // LOCAL-FIRST: Check persistent storage FIRST (never blocks on network)
   if (!options.skipPersistent && client.persistentGetAll) {
@@ -283,23 +342,19 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
         const existing = byPath.get(path);
 
         if (!existing || event.created_at > existing.created_at) {
-          try {
-            const data = JSON.parse(event.content);
-
-            // Handle null/undefined or deleted items - remove from map if this is newer
-            if (!data || data._deleted) {
-              byPath.delete(path);
-              continue;
-            }
-
-            // Optionally include author information
-            if (options.includeAuthor) {
-              data._author = event.pubkey;
-            }
-            byPath.set(path, { data, created_at: event.created_at });
-          } catch (error) {
-            // Skip invalid events
+          const data = _parseEventContent(event, lensKey);
+
+          // Handle null/undefined or deleted items - remove from map if this is newer
+          if (!data || data._deleted) {
+            byPath.delete(path);
+            continue;
           }
+
+          // Optionally include author information
+          if (options.includeAuthor) {
+            data._author = event.pubkey;
+          }
+          byPath.set(path, { data, created_at: event.created_at });
         }
       }
 
@@ -357,6 +412,7 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
  * @returns {Promise<Array>} Array of data objects
  */
 async function _executeNostrGetAll(client, pathPrefix, kind, authors, timeout, limit, options) {
+  const { lensKey } = options;
   const filter = {
     kinds: [kind],
     authors: authors,
@@ -380,23 +436,19 @@ async function _executeNostrGetAll(client, pathPrefix, kind, authors, timeout, l
     const existing = byPath.get(dTag);
 
     if (!existing || event.created_at > existing.created_at) {
-      try {
-        const data = JSON.parse(event.content);
+      const data = _parseEventContent(event, lensKey);
 
-        // Handle null/undefined or deleted items - remove from map if this is newer
-        if (!data || data._deleted) {
-          byPath.delete(dTag);
-          continue;
-        }
+      // Handle null/undefined or deleted items - remove from map if this is newer
+      if (!data || data._deleted) {
+        byPath.delete(dTag);
+        continue;
+      }
 
-        // Optionally include author information
-        if (options.includeAuthor) {
-          data._author = event.pubkey;
-        }
-        byPath.set(dTag, { data, created_at: event.created_at });
-      } catch (error) {
-        // Silent - skip unparseable events
+      // Optionally include author information
+      if (options.includeAuthor) {
+        data._author = event.pubkey;
       }
+      byPath.set(dTag, { data, created_at: event.created_at });
     }
   }
 
@@ -805,8 +857,13 @@ export async function nostrSubscribe(client, path, callback, options = {}) {
 export async function nostrSubscribeMany(client, pathPrefix, callback, options = {}) {
   const kind = options.kind || 30000;
 
-  // Create unique key for this subscription
-  const subscriptionKey = `${client.publicKey}:${kind}:${pathPrefix}`;
+  // Extract the holon ID (author pubkey) from the path
+  // Path format: appName/holonId/lensName/
+  const pathParts = pathPrefix.split('/');
+  const targetAuthor = pathParts[1] || client.publicKey;
+
+  // Create unique key for this subscription (use target author, not client pubkey)
+  const subscriptionKey = `${targetAuthor}:${kind}:${pathPrefix}`;
 
   // Check if we already have an active subscription for this path
   const existingSub = globalSubscriptions.get(subscriptionKey);
@@ -849,7 +906,7 @@ export async function nostrSubscribeMany(client, pathPrefix, callback, options =
     seenEventIds.add(event.id);
 
     // Check if event is from a different author (relay not respecting filter)
-    if (event.pubkey !== client.publicKey) {
+    if (event.pubkey !== targetAuthor) {
       rejectedCount++;
 
       // Only log periodically to avoid spam
@@ -858,7 +915,7 @@ export async function nostrSubscribeMany(client, pathPrefix, callback, options =
         console.warn('[nostrSubscribeMany] ⚠️ Relay not respecting authors filter!', {
           rejectedCount,
           acceptedCount,
-          expected: client.publicKey,
+          expected: targetAuthor,
           message: 'Consider using a different relay or implementing private relay'
         });
         lastLogTime = now;
@@ -896,9 +953,10 @@ export async function nostrSubscribeMany(client, pathPrefix, callback, options =
   const subscriptionStartTime = Math.floor(Date.now() / 1000);
   const dataFilter = {
     kinds: [kind],
-    authors: [client.publicKey],
+    authors: [targetAuthor],  // Use target author (holon ID), not client pubkey
     since: subscriptionStartTime  // Only get new events after subscription
   };
+  console.log('[nostrSubscribeMany] Subscribing to:', { pathPrefix, targetAuthor: targetAuthor.slice(0, 12), clientPubKey: client.publicKey.slice(0, 12) });
   const dataSubscription = await client.subscribe(dataFilter, handleDataEvent);
 
   // Use Page Visibility API to refresh when tab becomes visible

package/src/storage/nostr-client.js

@@ -406,7 +406,13 @@ export class NostrClient {
       this.relays.forEach(r => globalNDKRelays.add(r));
 
       // Connect to relays
-      await this.ndk.connect();
+      console.log('[NostrClient] Connecting to relays:', this.relays);
+      try {
+        await this.ndk.connect();
+        console.log('[NostrClient] NDK connect() completed. Pool stats:', this.ndk.pool?.stats?.());
+      } catch (err) {
+        console.error('[NostrClient] NDK connect() FAILED:', err.message);
+      }
 
       // Note: publicKey is already set synchronously in constructor using nostr-tools
     } else {
@@ -647,7 +653,16 @@ export class NostrClient {
    * @returns {Promise<Object|null>} The event or null if not found
    */
   async persistentGet(path) {
-    await this._initReady;
+    // Add timeout to prevent hanging if initialization stalls
+    try {
+      await Promise.race([
+        this._initReady,
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Init timeout')), 10000))
+      ]);
+    } catch (err) {
+      console.warn('[NostrClient] persistentGet: Init timeout, returning null');
+      return null;
+    }
     if (!this.persistentStorage) return null;
     try {
       const event = await this.persistentStorage.get(path);
@@ -745,8 +760,15 @@ export class NostrClient {
    * });
    */
   async publish(event, options = {}) {
-    // Ensure initialization is complete
-    await this._initReady;
+    // Ensure initialization is complete, with timeout to prevent hanging
+    try {
+      await Promise.race([
+        this._initReady,
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Init timeout')), 15000))
+      ]);
+    } catch (err) {
+      console.warn('[NostrClient] publish: Init timeout, continuing with available state');
+    }
 
     const waitForRelays = options.waitForRelays || false;
 
@@ -943,12 +965,18 @@ export class NostrClient {
     const formattedResults = [];
 
     try {
-      // Publish using NDK
-      const publishedRelays = await ndkEvent.publish();
+      // Publish using NDK with timeout to prevent hanging
+      const publishPromise = ndkEvent.publish();
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('Publish timeout')), 30000)
+      );
+
+      const publishedRelays = await Promise.race([publishPromise, timeoutPromise]);
 
       // Track results
       for (const relay of relays) {
-        const wasPublished = publishedRelays.has(this.ndk.pool.getRelay(relay));
+        const ndkRelay = this.ndk.pool.getRelay(relay);
+        const wasPublished = publishedRelays.has(ndkRelay);
         if (wasPublished) {
           successful.push(relay);
           formattedResults.push({
@@ -966,6 +994,7 @@ export class NostrClient {
         }
       }
     } catch (error) {
+      // Publish failed - event is cached locally and queued for retry
       // All failed
       for (const relay of relays) {
         failed.push(relay);
@@ -1015,10 +1044,18 @@ export class NostrClient {
    * });
    */
   async query(filter, options = {}) {
-    // Ensure initialization is complete
-    await this._initReady;
+    // Ensure initialization is complete, with timeout to prevent hanging
+    const queryTimeout = options.timeout !== undefined ? options.timeout : 30000;
+    try {
+      await Promise.race([
+        this._initReady,
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Init timeout')), Math.min(queryTimeout, 10000)))
+      ]);
+    } catch (err) {
+      console.warn('[NostrClient] query: Init timeout, continuing with available state');
+    }
 
-    const timeout = options.timeout !== undefined ? options.timeout : 30000;
+    const timeout = queryTimeout;
     const localFirst = options.localFirst !== false; // Default to true for speed
     const forceRelay = options.forceRelay === true;
 
@@ -1042,8 +1079,8 @@ export class NostrClient {
       return matchingEvents;
     }
 
-    // For first query before subscription initializes, wait briefly
-    if (isOwnDataQuery && subInfo && !subInfo.initialized) {
+    // For first query before subscription initializes, wait briefly (unless forceRelay)
+    if (!forceRelay && isOwnDataQuery && subInfo && !subInfo.initialized) {
       // Wait for subscription to initialize (up to timeout)
       await Promise.race([
         subInfo.initPromise,
@@ -1106,13 +1143,28 @@ export class NostrClient {
         let events = [];
 
         if (this.ndk) {
-          // Use NDK to fetch events
-          const fetchedEvents = await this.ndk.fetchEvents(filter, {
+          // Use NDK to fetch events with timeout to prevent hanging on disconnected relays
+          const fetchPromise = this.ndk.fetchEvents(filter, {
             closeOnEose: true,
           });
 
-          // Convert NDKEvent Set to raw event array
-          events = Array.from(fetchedEvents).map(e => e.rawEvent());
+          // Add timeout wrapper to prevent infinite hang when no relays are connected
+          const timeoutPromise = new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Relay query timeout')), timeout || 30000)
+          );
+
+          try {
+            const fetchedEvents = await Promise.race([fetchPromise, timeoutPromise]);
+            // Convert NDKEvent Set to raw event array
+            events = Array.from(fetchedEvents).map(e => e.rawEvent());
+          } catch (err) {
+            if (err.message === 'Relay query timeout') {
+              console.warn('[NostrClient] Relay query timed out, returning empty results');
+              events = [];
+            } else {
+              throw err;
+            }
+          }
         }
 
         // CRITICAL: Filter out events from other authors (relay may not respect filter)
@@ -1352,12 +1404,19 @@ export class NostrClient {
       return localEvents;
     }
 
-    // Step 2: Query relays
+    // Step 2: Query relays with timeout
     let relayEvents = [];
     try {
-      const fetchedEvents = await this.ndk.fetchEvents(filter, {
+      const fetchPromise = this.ndk.fetchEvents(filter, {
         closeOnEose: true,
       });
+
+      // Add timeout to prevent hanging on disconnected relays
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('Relay query timeout')), timeout)
+      );
+
+      const fetchedEvents = await Promise.race([fetchPromise, timeoutPromise]);
       relayEvents = Array.from(fetchedEvents).map(e => e.rawEvent());
 
       // Filter out events from other authors

package/src/storage/nostr-wrapper.js

@@ -59,7 +59,10 @@ function encodePathComponent(component) {
  */
 export async function write(client, path, data, options = {}) {
   try {
-    const putOptions = options.signingKey ? { signingKey: options.signingKey } : {};
+    const putOptions = {
+      ...(options.signingKey && { signingKey: options.signingKey }),
+      ...(options.waitForRelays && { waitForRelays: options.waitForRelays }),
+    };
     const result = await nostrPut(client, path, data, putOptions);
     // Check if at least one relay accepted the event
     // If no relays (testing mode), consider it successful if event was created

package/src/storage/unified-storage.js

@@ -29,19 +29,20 @@ export function buildPath(appName, holonId, lensName, key = null) {
  * @param {Object} client - Client instance (nostr client or gun-compatible client)
  * @param {string} path - Storage path
  * @param {Object} data - Data to write
+ * @param {Object} [options={}] - Write options
  * @returns {Promise<boolean>} Success indicator
  */
-export async function write(client, path, data) {
+export async function write(client, path, data, options = {}) {
   // Check if this is a GunDB client with backend methods (preferred - has write cache)
   if (client.write && client.gun) {
-    return client.write(path, data);
+    return client.write(path, data, options);
   }
   // Fallback to direct gunWrapper (no write cache)
   if (client.gun) {
-    return gunWrapper.write(client.gun, path, data);
+    return gunWrapper.write(client.gun, path, data, options);
   }
   // Default to Nostr
-  return nostrWrapper.write(client, path, data);
+  return nostrWrapper.write(client, path, data, options);
 }
 
 /**

package/src/subscriptions/manager.js

@@ -38,7 +38,7 @@ export async function createSubscription(client, path, callback, options = {}) {
 
     // Skip if already seen (prevent duplicates)
     // Include timestamp in unique key to allow updates to same item
-    const uniqueKey = `${key}-${data?.id || ''}-${data?._meta?.timestamp || Date.now()}`;
+    const uniqueKey = `${key}-${data?.id || ''}-${data?._meta?.lastUpdated || data?._meta?.timestamp || Date.now()}`;
     if (seenKeys.has(uniqueKey)) {
       return;
     }

package/vitest.config.js

@@ -1,5 +1,9 @@
 import { defineConfig } from 'vitest/config';
 
+// Dynamic timeout based on USE_REAL_RELAYS environment variable
+const isRealRelayMode = process.env.USE_REAL_RELAYS === 'true';
+const testTimeout = isRealRelayMode ? 60000 : 10000;
+
 export default defineConfig({
   test: {
     include: ['tests/**/*.test.js'],
@@ -15,6 +19,7 @@ export default defineConfig({
     },
     environment: 'node',
     globals: false,
-    testTimeout: 10000,
+    testTimeout,
+    setupFiles: ['./tests/utils/relay-config.js'],
   },
 });