Proposal: Refactor polaris-web functionality into signify-browser-extension, in one repo

[edeykholt]

Restructuring Highlights

Version compatibility

• Maintain the polaris-web code and signify-browser-extension in one repo. That way, the compatibility and versioning are kept in sync.
• The polaris-web portion of the code will be injected into the page as a "bridge" javascript. More on this below.
• This also simplifies web page construction and maintenance.
• Multiple extensions could be installed.

Page communications

• Each extension and version works in a separate namespace under window.signify
• All interaction between page and extension is via a bridge javascript that the extension injects
• From the page's perspective, the list of extensions that are "installed" are those that have injected the bridge javascript. That bridge javascript is specified in the manifest as running in the MAIN world.
• The page can choose which ones to talk with, and by default could talk with the first one.

Other Changes to improve security, reliability, etc.

• Communication between the content script and extension will be port-based. One reason is that port message received events can wake up a sleeping service-worker.
• Lower security risks, such as Rogue Extension Interference, Message Tampering or Injection, Cross-Extension Message Interception, Privilege Escalation, DoS.

The following issues would be addressed a side-effect of these changes

• Add website--service-worker protocol versioning signify-browser-extension#156
• Use typings from polaris-web (or common shared project) signify-browser-extension#194
• Proposal: Extending Polaris-Web for Version Compatibility and Multi-Extension Handling #29
• webpage or its components should not attempt to message an extension directly #13

ChatGPT Code

• The remainder of this is generated from ChatGPT, with some iterating of prompts. It is intended to convey the shape of the code concepts, not final.

---

Key Components:

1. page-bridge.ts:

   • Uses the port ID provided by the service worker to establish a connection.
   • Exposes an API via window.signify to the web page.

2. Isolated Content Script:

   • Communicates with the service worker via the port and securely forwards messages.

3. Service Worker:

   • Generates a random port ID, sends it to the content script, and manages communication over the established port.

---

Code Implementation

1. Manifest File (manifest.json):

This ensures that the page-bridge.js runs in the main world and that permissions are correctly configured.

{
  "name": "Signify Extension",
  "version": "1.0",
  "manifest_version": 3,
  "permissions": [
    "https://specific-site.com/*"
  ],
  "background": {
    "service_worker": "service-worker.js"
  },
  "content_scripts": [
    {
      "matches": ["https://specific-site.com/*"],
      "js": ["page-bridge.js"],
      "world": "MAIN"  // Runs page-bridge.js in the main world
    },
    {
      "matches": ["https://specific-site.com/*"],
      "js": ["isolated-content.js"]
    }
  ],
  "web_accessible_resources": [
    {
      "resources": ["page-bridge.js"],
      "matches": ["https://specific-site.com/*"]
    }
  ]
}

2. page-bridge.ts (Main World Content Script with Nested Namespace and Port Communication):

The service worker generates the port ID, which the content script uses to establish the connection for secure communication.

// Create a unique namespace using the extension ID and version
const extensionID = chrome.runtime.id;
const extensionVersion = '1.0';  // Should match the version in manifest.json
const namespace = `extensionAPI_${extensionID}_${extensionVersion}` as const;

// Ensure the "signify" namespace exists on the global window object
(window as any).signify = (window as any).signify || {};

// Define message structure types with generics
interface MessageRequest<TPayload> {
    action: 'processData';
    payload: TPayload;
}

interface MessageResponse<TResult> {
    result: TResult;
    error?: string;
}

// Communication with the service worker over a port
let port: chrome.runtime.Port | null = null;

// Establish connection with the service worker using the port ID
function establishConnection(portId: string): void {
    port = chrome.runtime.connect({ name: portId });
}

// Expose the API within the signify namespace
(window as any).signify[namespace] = {
    callExtension: <TPayload, TResult>(data: TPayload): Promise<TResult> => {
        return new Promise((resolve, reject) => {
            if (!port) {
                reject('Port not initialized');
                return;
            }

            const request: MessageRequest<TPayload> = { action: 'processData', payload: data };
            port.postMessage(request);

            port.onMessage.addListener((response: MessageResponse<TResult>) => {
                if (response.error) {
                    reject(response.error);
                } else {
                    resolve(response.result);
                }
            });
        });
    }
};

// Freeze the API object to prevent tampering
Object.freeze((window as any).signify[namespace]);

// Wait for the port ID from the service worker to establish the connection
chrome.runtime.onMessage.addListener((message, sender) => {
    if (message.action === 'setPortId') {
        establishConnection(message.portId);
    }
});

The web page can now call the API using the nested namespace under window.signify:

interface ExtensionPayload {
    key: string;
}

interface ExtensionResult {
    success: boolean;
    data: string;
}

// Calling the exposed API within the signify namespace
(window as any).signify[`extensionAPI_${extensionID}_${extensionVersion}`]
    .callExtension<ExtensionPayload, ExtensionResult>({ key: 'someValue' })
    .then(result => {
        console.log('Result from extension:', result);
    })
    .catch(error => {
        console.error('Error from extension:', error);
    });

3. isolated-content.ts (Isolated Content Script):

The isolated content script listens for messages over the port and forwards them to the service worker.

interface MessageRequest<TPayload> {
    action: 'processData';
    payload: TPayload;
}

interface MessageResponse<TResult> {
    result: TResult;
    error?: string;
}

// Validate incoming message payloads
function validateRequest<TPayload extends { key: string }>(payload: TPayload): boolean {
    return typeof payload === 'object' && 'key' in payload;
}

// Listen for port communication
chrome.runtime.onConnect.addListener((port) => {
    port.onMessage.addListener((message: MessageRequest<any>) => {
        if (validateRequest(message.payload)) {
            // Forward to the service worker
            chrome.runtime.sendMessage(message, (response: MessageResponse<any>) => {
                port.postMessage(response);
            });
        } else {
            port.postMessage({ error: 'Invalid data' });
        }
    });
});

4. service-worker.ts (Service Worker):

The service worker generates the random port ID and sends it to the content script for communication over the port.

// Generate a random port ID
function generatePortId(): string {
    return Math.random().toString(36).substr(2, 9);  // Simple random ID generator
}

// Communication over the port
let connectedPort: chrome.runtime.Port | null = null;

chrome.runtime.onConnect.addListener((port) => {
    connectedPort = port;
    port.onMessage.addListener((message) => {
        if (message.action === 'fetchData') {
            handleFetchData(message.payload, port);
        }
    });
});

// Handle fetching data
function handleFetchData(payload: any, port: chrome.runtime.Port) {
    // Validate and process the message
    if (typeof payload.key === 'string') {
        const result = { success: true, data: `Processed ${payload.key}` };
        port.postMessage({ result });
    } else {
        port.postMessage({ error: 'Invalid payload' });
    }
}

// Send the port ID to the content script
chrome.runtime.onInstalled.addListener(() => {
    const portId = generatePortId();
    // Store the portId for the extension and notify the content script
    chrome.runtime.sendMessage({ action: 'setPortId', portId });
});

---

Summary of Potential Risk Areas and Mitigations

1. Rogue Extension Interference

Rogue extensions could try to interfere with communications or expose global APIs.

Mitigations:

• Port-Based Communication: Using randomly generated port IDs ensures that only the service worker can establish communication.
• API Freezing: The window.signify object is frozen, preventing rogue scripts from tampering with it.
• Namespace Isolation: Using window.signify.extensionAPI_[extensionID]_[version] isolates the API and reduces the risk of interference.

2. Message Tampering or Injection

Rogue extensions might attempt to tamper with or inject messages.

Mitigations:

• Message Validation: All messages are validated before processing, ensuring that only valid data is acted upon.
• Port Security: Only the legitimate port ID generated by the service worker is used for communication, making it difficult for rogue extensions to inject or tamper with messages.

3. Cross-Extension Message Interception

Rogue extensions could try to intercept messages or listen in on communications between the service worker and the content script.

Mitigations:

• Port Security: Port-based communication ensures that the connection is tied to the specific port ID generated by the service worker, which makes interception by other extensions unlikely.

4. Privilege Escalation

A rogue extension may attempt to escalate privileges by triggering unauthorized actions in the service worker.

Mitigations:

• Action Whitelisting: Only specific, whitelisted actions (like fetchData) are processed by the service worker, preventing unauthorized actions.

5. Denial of Service (DoS) Attacks

A malicious page or extension could try to flood the extension with messages to degrade performance.

Mitigations:

• Rate Limiting: The service worker can implement rate limiting for the number of allowed connections and requests per minute.

[edeykholt]

I no longer think this is a good idea as it is titled, since there are and will be multiple browser extensions. Other than the concept of polaris-web and signify-browser-extension sharing the same interface definitions (for how the content-script and web page interact) somewhere ideally common, which should also be versioned.