Security Considerations for Local-Only Data Storage in WebSocket DevTools

WebSocket DevTools stores all user data exclusively in browser localStorage and chrome.storage.local, implementing strict size caps, defensive error handling, and minimal permissions to ensure connection histories and messages never leave the client machine.

The law-chain-hot/websocket-devtools repository addresses critical security considerations for local-only data storage by enforcing a zero-transmission architecture. All connection histories, favorite messages, and extension settings are processed entirely within the browser using scoped storage keys and aggressive limits, eliminating external data exposure risks.

Zero External Data Transmission

The extension guarantees data sovereignty by restricting all persistence to browser-native APIs. According to the privacy policy in PRIVACY.md, "All data processing occurs entirely within your browser using browser-specific local storage APIs" [PRIVACY.md†L24-L28].

In src/utils/wsHistoryService.js, the service writes exclusively via localStorage.setItem without network calls:

// From wsHistoryService.js†L12-L30
const history = JSON.parse(localStorage.getItem(HISTORY_KEY) || '[]');
// ... mutation logic ...
localStorage.setItem(HISTORY_KEY, JSON.stringify(history));

Similarly, src/utils/favoritesService.js persists favorite messages using the same pattern [favoritesService.js†L14-L31]. No telemetry, sync, or cloud APIs are invoked.

Minimal Permission Model

The extension requests only the permissions required for its core functionality. The manifest.json declares solely activeTab and storage permissions, plus host permissions for script injection [manifest.json†L17-L22].

This minimal surface area prevents:

• Network exfiltration: No webRequest or cross-origin permissions
• System access: No fileSystem or downloads permissions
• Identity leakage: No identity or cookies permissions

Data Isolation and Storage Scoping

Data is strictly compartmentalized using distinct storage keys to prevent cross-contamination. Connection history uses "websocket-connection-history" while favorites use "websocket-favorites" [wsHistoryService.js†L4-L5][favoritesService.js†L4-L5].

This key scoping ensures that:

1. History parsing errors cannot corrupt favorites data
2. Cleanup operations target specific datasets
3. Potential XSS vectors in one datastore cannot access the other

Storage Size Limits to Prevent Exhaustion

The services implement hard caps to mitigate resource exhaustion attacks and unbounded growth. In wsHistoryService.js, the constructor sets this.maxRecords = 3 [wsHistoryService.js†L6-L7], automatically truncating older entries when adding new connections.

The favorites service enforces a five-item limit within the addFavorite method:

// From favoritesService.js†L63-L68
if (favorites.length >= 5) {
  return { error: 'Maximum number of favorites (5) reached' };
}

These limits reduce the attack surface for storage flooding and ensure predictable memory usage.

Defensive Error Handling

All storage operations are wrapped in try…catch blocks to prevent extension crashes from corrupted localStorage data. The getHistory method in wsHistoryService.js safely falls back to empty arrays [wsHistoryService.js†L11-L17]:

try {
  const data = localStorage.getItem(HISTORY_KEY);
  return data ? JSON.parse(data) : [];
} catch (e) {
  console.warn('Failed to parse WebSocket history:', e);
  return [];
}

favoritesService.js implements identical safeguards [favoritesService.js†L14-L19], ensuring that malformed storage values cannot brick the extension.

User-Controlled Data Lifecycle

Users retain complete control over data retention through explicit cleanup methods. The clearHistory method in wsHistoryService.js empties storage and notifies UI listeners [wsHistoryService.js†L15-L21]:

clearHistory() {
  localStorage.removeItem(HISTORY_KEY);
  this.notifyListeners();
}

The favorites service exposes a cleanup method that clears listeners and timeout handles [favoritesService.js†L56-L65]. Additionally, the privacy policy confirms that "Uninstalling the extension will delete all locally stored data" [PRIVACY.md†L95-L98].

Sandboxed Extension Environment

As a Chrome/Edge extension, the code executes in an isolated extension world. The content_scripts configuration in manifest.json uses run_at: document_start, but storage APIs are accessible only from the extension's background and DevTools contexts. This sandboxing prevents malicious web pages from accessing the "websocket-connection-history" or "websocket-favorites" keys via standard JavaScript.

Practical Implementation Examples

Storing Connection History with Automatic Limits

import wsHistoryService from '@/utils/wsHistoryService';

// Automatically caps at 3 records
const record = wsHistoryService.addConnection('wss://example.com/socket');
console.log('Saved:', record);

This invokes the addConnection method, which deduplicates URLs and enforces the maxRecords limit before calling localStorage.setItem [wsHistoryService.js†L38-L80].

Safely Retrieving Stored Data

// Returns [] if storage is corrupted or empty
const history = wsHistoryService.getHistory();
console.table(history);

The getHistory method parses JSON safely with fallback handling [wsHistoryService.js†L10-L15].

Adding Favorites with Capacity Checks

import favoritesService from '@/utils/favoritesService';

const result = favoritesService.addFavorite({
  name: 'Auth Token',
  data: JSON.stringify({ token: 'secret' })
});

if (result?.error) {
  console.warn('Limit reached:', result.error);
}

The addFavorite method validates the five-item limit and debounces listener notifications [favoritesService.js†L63-L71].

Purging All Local Data

// Immediate removal from localStorage
wsHistoryService.clearHistory();
favoritesService.saveFavorites([]);

Both operations trigger clear events to update the UI instantly without page reloads.

Summary

• Zero transmission: All data remains in localStorage and chrome.storage.local per PRIVACY.md and service implementations.
• Minimal permissions: Only activeTab and storage declared in manifest.json.
• Strict isolation: Separate keys for history ("websocket-connection-history") and favorites ("websocket-favorites").
• Hard limits: Three connection records and five favorites maximum prevent storage abuse.
• Defensive coding: All read/write operations use try…catch blocks with empty-array fallbacks.
• User sovereignty: clearHistory and cleanup methods provide immediate data destruction.
• Sandboxed execution: Extension context isolation prevents web page access to storage keys.

Frequently Asked Questions

Does WebSocket DevTools send my connection data to external servers?

No. According to the repository's PRIVACY.md and source code in wsHistoryService.js, all data processing occurs exclusively within the browser using localStorage and chrome.storage.local APIs. The extension contains no network transmission logic for user data.

What happens to my data when I reach the storage limits?

When the three-record limit for connection history is reached, older entries are automatically removed when new connections are added via addConnection. For favorites, the addFavorite method returns an error object { error: 'Maximum number of favorites (5) reached' } and rejects the new entry until the user deletes existing items.

How does the extension handle corrupted browser storage?

Both wsHistoryService.js and favoritesService.js wrap all localStorage.getItem calls in try…catch blocks. If JSON parsing fails or storage is inaccessible, the methods return empty arrays and log warnings to the console, ensuring the extension remains functional even with corrupted data.

Will uninstalling the extension delete my saved connections?

Yes. The privacy policy explicitly states that uninstalling the extension deletes all locally stored data immediately, as the browser purges extension-specific localStorage and chrome.storage.local entries upon removal. Users can also manually clear data anytime using the clearHistory and saveFavorites([]) methods.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}