Safari Web Extensions: Minimal Design, Trust Boundaries, and Operational Checks

Problem and Takeaway

If you need a cross-platform (macOS/iOS) browser add-on for Safari that distributes via the App Store and interacts with page DOM, the smallest suitable design is a native container app embedding a Safari Web Extension target using the WebExtensions API. This guide details the architecture, trust boundaries, and necessary operational checks.

Minimal Architecture Requirements

• Logic reuse: Use standard WebExtensions API (manifest.json, service worker, content scripts).
• Distribution: Must use App Store channels (no legacy .appex or JS injection hacks).
• Functionality: Requires access to the page DOM on both desktop and mobile.

Trust and Data Isolation

The extension runs in a sandboxed process, separate from the host container app and web pages. Content scripts operate in an isolated world; privileged APIs (e.g., tabs, storage) are only accessible from the extension's background context. Data must pass across boundaries via message passing, not shared memory.

Boundary Management

If sharing large datasets, use an App Group; otherwise, storage is strictly per-extension.

Operational Verification and Failure Modes

Verification Steps

1. Verify extension is enabled in Safari Settings (Safari ▸ Settings ▸ Extensions on macOS or Settings ▸ Safari ▸ Extensions on iOS).
2. Use Safari's Develop menu and Web Inspector to attach to the extension's background page.
3. Confirm lifecycle events (e.g., chrome.runtime.onInstalled) fire upon enabling/disabling.
4. Test persistence: Write to chrome.storage.local, quit Safari, relaunch, and verify readback.

Failure Conditions

• User disables extension or revokes host permissions: Functionality silently breaks; design must detect this (e.g., checking chrome.runtime.lastError).
• iOS throttling: Service workers can be aggressively terminated; state must be re-hydrated from storage on onStartup.
• ITP: Extension-initiated network requests to known trackers may be restricted; favor declarativeNetRequest over runtime fetch.

Design Condition Changes

The design shifts if: 1) Native macOS APIs are needed (use legacy App Extension); 2) High-performance, declarative blocking is the sole goal (use Content Blocker); 3) Cross-browser parity is unnecessary (use pure Safari implementation).

Practical Check

After any Safari update, open the extension's background page in Web Inspector and execute chrome.runtime.getManifest(). Successful parsing and version match confirm correct loading.

Limitations

• Safari Web Extensions support requires Safari 14+ (macOS) / 15+ (iOS).
• The API is a subset; do not assume Chrome/Firefox parity (e.g., chrome.tabs.captureVisibleTab is unavailable).
• All permissions are user-visible and revocable; treat state as untrusted on activation.