security(audit): build structured sensitive domain matchers and CSP permission catalog

Author: Deekshith-goud

src/security/csp_and_permissions_audit.md

@@ -0,0 +1,60 @@
+# Security Hardening & Permissions Audit
+
+This document details the Manifest V3 privilege structure, strict Content Security Policies (CSP), and runtime isolation boundaries built into the **Web-Swap Tracker** browser extension.
+
+---
+
+## 1. Permissions Inventory (Least Privilege Compliance)
+
+To guarantee the user's data privacy and security, this extension implements a strict deny-by-default permission profile. No wildcards or open scopes are requested.
+
+| Permission | Context of Usage | Rationale & Privacy Guarantee | Alternate Designs Evaluated |
+| :--- | :--- | :--- | :--- |
+| **`storage`** | Background & Popup & Content | Required to persist the user's local custom productivity rules and Blob UI coordinates. **Guarantee**: Uses local browser storage ONLY; zero synchronization or remote telemetry. | Evaluated SQLite/FileSystem API: rejected due to unnecessary sandbox escape vectors. |
+| **`tabs`** | Background Service Worker | Used strictly in tracking tab change transitions to capture precise active sessions (e.g. `chrome.tabs.onActivated`). **Guarantee**: Never tracks page HTML content, input values, or cookie hashes. | Evaluated activeTab: rejected because background tracking must function continuously. |
+| **`activeTab`** | Dynamic Actions | Granted dynamically on user action to interact with active pages safely. | None. Standard Chrome mechanism for contextual access. |
+
+---
+
+## 2. Strict Content Security Policy (CSP)
+
+The extension employs a rigid Content Security Policy strictly aligned with the highest Chrome Web Store security standards.
+
+```json
+"content_security_policy": {
+  "extension_pages": "default-src 'self'; script-src 'self'; object-src 'none';"
+}
+```
+
+### Security Hardening Measures
+1. **No External Scripts (`script-src 'self'`)**:
+   - Strictly forbids the execution of scripts loaded from remote CDNs, third-party trackers, or servers.
+   - Prevents Man-in-the-Middle (MitM) script injection vectors.
+2. **No Dynamic Execution (`unsafe-eval` banned)**:
+   - Evaluators like `eval()`, `setTimeout(string)`, and `new Function()` are completely blocked.
+   - Prevents DOM-based cross-site scripting (XSS) via string-to-code evaluation.
+3. **No Unsafe Inline Styles (`style-src 'self'`)**:
+   - Blocks dynamic inline style injection.
+   - Prevents CSS injection attacks from spoofing the premium dashboard interface.
+
+---
+
+## 3. Strict Context Isolation Boundaries
+
+The extension interacts across three distinct runtime zones:
+```mermaid
+graph TD
+    A[Webpage Host Context] -- Isolated DOM / Shadow DOM --> B(Content Script UI)
+    B -- Runtime Messaging satisfies RuntimeMessage --> C{Deny-by-Default Gateway}
+    C -- Allowed Capabilities --> D[Privileged Background Worker]
+    C -- Block / Log --> E[Local Security Ring-Buffer]
+```
+
+### Content Script UI Isolation (`content.tsx`)
+- **Shadow DOM Isolation**: The Floating Blob UI renders inside an isolated Shadow DOM container. This shields the extension's controls and style rules from context leaks or manipulation by malicious third-party script assets on the active webpage.
+- **Protocol Verification**: Content scripts are strictly excluded from injecting inside sensitive domains (like bank sign-ins, payment gates, or identity portals) using regex match lists and configuration protocol checks.
+
+### Background Message Gateway Defense (`background.ts`)
+- **Origin derivation (`deriveSurface`)**: Validates the sender parameters on every message (`sender.id === chrome.runtime.id`). Context is classified using strict URL analysis (e.g. distinguishing `content` tab origins from privileged `popup.html` and `dashboard.html` paths).
+- **Capability Mapping (`MESSAGE_CAPABILITIES`)**: Map that associates message action keys with allowed context surfaces. For example, webpage content scripts are restricted from performing mutations such as `SAVE_PRODUCTIVITY_RULES` or `TOGGLE_TRACKING` – attempts automatically trigger high-fidelity local security incident alerts.
+- **Telemetry-Free Diagnostics (`RingBuffer`)**: All malformed structures, coordinates overruns, or spoofing vectors are recorded inside an on-device 50-entry chronologically organized Ring Buffer and atomic counter maps. Zero data is transmitted off the device.

src/security/security-fixtures.ts

@@ -0,0 +1,129 @@
+/**
+ * security-fixtures.ts
+ *
+ * Security test fixtures for manual validation and automated regression testing.
+ * Contains malformed payloads, spoofed sender context objects, and coordinate overflows
+ * to verify the robustness of validators and message dispatch firewalls.
+ */
+
+import type { RuntimeMessage } from "../types/tracking";
+import type { BlobUIState } from "./validators";
+
+/**
+ * Spoofed sender origin configurations mimicking various surfaces.
+ */
+export const SENDER_FIXTURES = Object.freeze({
+  /** authentic content script context */
+  validContentScript: Object.freeze({
+    id: "extension-id-placeholder", // Will match runtime.id in tests
+    url: "https://github.com/login",
+    tab: { id: 101, index: 0, pinned: false, windowId: 1, active: true }
+  } as unknown as chrome.runtime.MessageSender),
+
+  /** authentic privileged options tab context */
+  validDashboardTab: Object.freeze({
+    id: "extension-id-placeholder",
+    url: "chrome-extension://extension-id-placeholder/tabs/dashboard.html",
+    tab: undefined
+  } as unknown as chrome.runtime.MessageSender),
+
+  /** authentic privileged popup context */
+  validPopupTab: Object.freeze({
+    id: "extension-id-placeholder",
+    url: "chrome-extension://extension-id-placeholder/popup.html",
+    tab: undefined
+  } as unknown as chrome.runtime.MessageSender),
+
+  /** malicious external website origin trying to send extension messages */
+  maliciousExternalPage: Object.freeze({
+    id: undefined,
+    url: "https://malicious-phishing-site.com",
+    tab: { id: 202, index: 1, pinned: false, windowId: 2, active: true }
+  } as unknown as chrome.runtime.MessageSender),
+
+  /** rouge cross-extension origin attempting connection spoofing */
+  rogueCrossExtension: Object.freeze({
+    id: "some-other-hostile-extension-id",
+    url: "chrome-extension://some-other-hostile-extension-id/popup.html",
+    tab: undefined
+  } as unknown as chrome.runtime.MessageSender)
+});
+
+/**
+ * Corrupted local storage coordinates for Blob UI test validation.
+ */
+export const STORAGE_COORDINATE_FIXTURES = Object.freeze({
+  /** standard clean positions */
+  pristine: Object.freeze({
+    anchorCorner: "bottom-right",
+    offsetX: 24,
+    offsetY: 24,
+    isCollapsed: true
+  }),
+
+  /** absurd coordinate values designed to break layouts */
+  layoutOverflowGiant: Object.freeze({
+    anchorCorner: "top-left",
+    offsetX: 999999,
+    offsetY: 1234567,
+    isCollapsed: false
+  }),
+
+  /** invalid string values causing parsing errors */
+  corruptStringValues: Object.freeze({
+    anchorCorner: "invalid-corner-name",
+    offsetX: "one-hundred-pixels",
+    offsetY: NaN,
+    isCollapsed: "not-a-boolean"
+  } as unknown as BlobUIState),
+
+  /** null or undefined fields */
+  nullifiedObject: null
+});
+
+/**
+ * Payload fixtures for the runtime messaging protocol.
+ */
+export const RUNTIME_MESSAGE_FIXTURES = Object.freeze({
+  /** authentic payload containing rule updates */
+  validSaveRules: Object.freeze({
+    type: "SAVE_PRODUCTIVITY_RULES",
+    version: 1,
+    rules: [
+      {
+        domain: "distracting.com",
+        category: "distracting",
+        priority: 10,
+        createdAt: Date.now()
+      }
+    ]
+  } as unknown as RuntimeMessage),
+
+  /** payload missing vital version boundaries */
+  missingVersionPayload: Object.freeze({
+    type: "GET_TODAY_STATS"
+    // version is missing
+  } as unknown as RuntimeMessage),
+
+  /** payload referencing an obsolete or unsupported protocol version */
+  unsupportedVersionPayload: Object.freeze({
+    type: "GET_TODAY_STATS",
+    version: 99 // Strict firewall will reject this
+  } as unknown as RuntimeMessage),
+
+  /** payload holding an unknown event action type */
+  unknownMessageTypePayload: Object.freeze({
+    type: "FORMAT_HARD_DRIVE", // Unregistered event action key
+    version: 1
+  } as unknown as RuntimeMessage),
+
+  /** malformed fields on valid types */
+  malformedFieldPayload: Object.freeze({
+    type: "TOGGLE_TRACKING",
+    version: 1,
+    paused: "true-as-a-string" // should be strict boolean
+  } as unknown as RuntimeMessage),
+
+  /** empty payload structures */
+  emptyPayload: Object.freeze({})
+});

src/security/sensitive-sites.ts

@@ -1,59 +1,81 @@
+import { safeParseUrl } from "../utils/url";
+
 /**
  * sensitive-sites.ts
  *
  * Centralized checker to flag high-sensitivity URLs that should avoid
  * any content script UI injection (e.g., banking domains, login portals,
- * credential management systems, localhost auth gateways).
- *
- * RATIONALE:
- * Injecting UI elements on highly sensitive pages (such as banking sites or
- * authentication logins) can trigger security filters, looks suspicious to
- * security-conscious users, and increases risk of store rejection.
+ * credential management systems, system URLs).
  */
 
-const SENSITIVE_PATTERNS = [
+export interface SensitiveSitePattern {
+  readonly category: "auth" | "financial" | "system" | "manager";
+  readonly pattern: RegExp;
+}
+
+/**
+ * Structured sensitive site patterns catalog.
+ * Deeply frozen to prevent runtime mutation or injection.
+ */
+export const SENSITIVE_PATTERNS: readonly SensitiveSitePattern[] = Object.freeze([
   // Authentication & Core Providers
-  /accounts\.google\.com/i,
-  /login\.microsoftonline\.com/i,
-  /appleid\.apple\.com/i,
-  /github\.com\/login/i,
-  /auth\./i,
-  /oauth/i,
-  /signin/i,
-  /signup/i,
-
-  // Financial Services & Payment Gateways
-  /paypal\.com/i,
-  /stripe\.com/i,
-  /chase\.com/i,
-  /bankofamerica\.com/i,
-  /wellsfargo\.com/i,
-  /citibank\.com/i,
-  /fidelity\.com/i,
+  { category: "auth", pattern: /accounts\.google\.com/i },
+  { category: "auth", pattern: /login\.microsoftonline\.com/i },
+  { category: "auth", pattern: /appleid\.apple\.com/i },
+  { category: "auth", pattern: /github\.com\/login/i },
+  { category: "auth", pattern: /auth\./i },
+  { category: "auth", pattern: /oauth/i },
+  { category: "auth", pattern: /signin/i },
+  { category: "auth", pattern: /signup/i },
+
+  // Password Managers
+  { category: "manager", pattern: /bitwarden\.com/i },
+  { category: "manager", pattern: /1password\.com/i },
+  { category: "manager", pattern: /lastpass\.com/i },
+  { category: "manager", pattern: /dashlane\.com/i },
+
+  // Financial Services & Banking
+  { category: "financial", pattern: /paypal\.com/i },
+  { category: "financial", pattern: /stripe\.com/i },
+  { category: "financial", pattern: /chase\.com/i },
+  { category: "financial", pattern: /bankofamerica\.com/i },
+  { category: "financial", pattern: /wellsfargo\.com/i },
+  { category: "financial", pattern: /citibank\.com/i },
+  { category: "financial", pattern: /fidelity\.com/i },
+  { category: "financial", pattern: /schwab\.com/i },
+  { category: "financial", pattern: /capitalone\.com/i },
+  { category: "financial", pattern: /hsbc\.com/i },
+  { category: "financial", pattern: /barclays\.co\.uk/i },
+
+  // Web3 & Crypto Wallets
+  { category: "financial", pattern: /metamask\.io/i },
+  { category: "financial", pattern: /phantom\.app/i },
+  { category: "financial", pattern: /coinbase\.com/i },
+  { category: "financial", pattern: /binance\.com/i },
 
   // System & Internal Sites
-  /^chrome:\/\//i,
-  /^chrome-extension:\/\//i,
-  /^about:/i,
-  /^file:\/\//i
-];
+  { category: "system", pattern: /^chrome:\/\//i },
+  { category: "system", pattern: /^chrome-extension:\/\//i },
+  { category: "system", pattern: /^about:/i },
+  { category: "system", pattern: /^file:\/\//i }
+]);
 
 /**
  * Checks if a given URL is a sensitive domain/page.
  * Returns true if injection should be blocked.
+ * Leverages secure safeParseUrl for defense-in-depth scheme checks.
  */
 export function isSensitiveSite(url: string | undefined): boolean {
-  if (!url) return true;
-
-  try {
-    // Basic format check
-    if (!url.startsWith("http://") && !url.startsWith("https://")) {
-      return true; // Exclude system, file, and blank protocols
-    }
-
-    return SENSITIVE_PATTERNS.some((pattern) => pattern.test(url));
-  } catch (error) {
-    // If URL parsing or pattern matching fails, fail-safe and treat as sensitive
-    return true;
+  if (!url) {
+    return true; // Fail-safe
   }
+
+  // centralize parsing through our safety validator (which strips unsafe schemes)
+  const parsed = safeParseUrl(url);
+  if (!parsed) {
+    return true; // If parse fails or scheme is dangerous, fail-secure and treat as sensitive
+  }
+
+  const fullUrl = parsed.toString();
+  return SENSITIVE_PATTERNS.some((entry) => entry.pattern.test(fullUrl));
 }

src/utils/url.ts

@@ -1,40 +1,63 @@
 import { logger } from "./logger";
 
 /**
- * Extracts and preserves the full hostname from a URL.
- * Only allows http: and https: protocols.
- * Strips path, query, hash, etc.
- * E.g., https://docs.github.com/path?query -> docs.github.com
+ * Normalizes a domain name by removing leading and trailing dots and lowercase conversion.
  */
 export function normalizeDomain(domain: string): string {
   return domain.trim().toLowerCase().replace(/^\.+|\.+$/g, "");
 }
 
 /**
- * Extracts and preserves the full hostname from a URL.
- * Only allows http: and https: protocols.
- * Strips path, query, hash, etc.
- * E.g., https://docs.github.com/path?query -> docs.github.com
+ * Standard list of explicitly denied dangerous URL schemes.
+ * Deeply frozen to prevent mutation.
  */
-export function extractHostname(urlStr: string | undefined): string | null {
+export const DENIED_URL_SCHEMES = Object.freeze([
+  "javascript:",
+  "data:",
+  "blob:",
+  "filesystem:"
+]);
+
+/**
+ * Centralized, secure URL parser that wraps V8 instantiation.
+ * Rejects malformed strings, dangerous schemes, and non-web protocols safely.
+ */
+export function safeParseUrl(urlStr: string | undefined): URL | null {
   if (!urlStr) {
     return null;
   }
 
   try {
     const parsedUrl = new URL(urlStr);
-    
+    const protocol = parsedUrl.protocol.toLowerCase();
+
+    // Explicitly reject dangerous schemes
+    if (DENIED_URL_SCHEMES.includes(protocol)) {
+      logger.debug(`[URL Safety] Explicitly denied URL scheme rejected: ${protocol}`);
+      return null;
+    }
+
     // Strict whitelist: only HTTP and HTTPS
-    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
-      logger.debug(`[URL Util] Ignored protocol: ${parsedUrl.protocol}`);
+    if (protocol !== "http:" && protocol !== "https:") {
+      logger.debug(`[URL Safety] Ignored non-web protocol: ${protocol}`);
       return null;
     }
 
-    // Preserve the full hostname (e.g. docs.github.com)
-    return normalizeDomain(parsedUrl.hostname);
-  } catch (error) {
-    logger.debug(`[URL Util] Failed to parse URL: ${urlStr}`);
+    return parsedUrl;
+  } catch (_error) {
+    logger.debug(`[URL Safety] Failed to securely parse URL: ${urlStr}`);
     return null;
   }
 }
 
+/**
+ * Extracts and normalizes the hostname from a URL.
+ * Leverages safeParseUrl for strict scheme and security parsing.
+ */
+export function extractHostname(urlStr: string | undefined): string | null {
+  const parsed = safeParseUrl(urlStr);
+  if (!parsed) {
+    return null;
+  }
+  return normalizeDomain(parsed.hostname);
+}