INSTALL.md

Installing Wiretype as an unpacked extension

Wiretype is not on the Chrome Web Store yet, so it is loaded manually. That takes about a minute and is the same procedure in every Chromium browser — only the address of the extensions page differs.

Get the files

Either clone the repository:

git clone https://github.com/flyhighbarney/wiretype.git

Or download wiretype-v0.1.0.zip from the releases page and unzip it.

Which folder to select matters. The browser wants the folder that directly contains manifest.json:

You have	Select this folder
a clone of the repo	wiretype/extension/
the unzipped release	the unzipped folder itself (manifest.json is at its top level)

Selecting the repository root instead of extension/ is the single most common mistake — the browser will say it cannot find a manifest.

There is a real difference between the two, and it is not just convenience:

• The repo's extension/ folder is a development build. DEBUG is on, so it logs [Wiretype] lines to the page console, exposes window.__WT_DEBUG__, and registers a localhost test vendor. The fixtures need this build.
• The release zip is a production build. DEBUG is off, so there is no console output, no __WT_DEBUG__, and no localhost test vendor. Use this for everyday browsing. The fixtures will report failures against it, correctly.

Chromium browsers

Same three steps everywhere. Only the URL changes:

Browser	Extensions page	Notes
Chrome	chrome://extensions	Full support, including the browser side panel (Chrome 114+)
Edge	edge://extensions	Developer mode is a toggle in the left sidebar, not the top right
Brave	brave://extensions	In-page panel only — see below
Opera	opera://extensions
Vivaldi	vivaldi://extensions
Arc	arc://extensions	Falls back to chrome://extensions on some builds

1. Open the extensions page from the table above.
2. Turn on Developer mode (top right in most, left sidebar in Edge).
3. Click Load unpacked and select the folder from the previous section.

Then pin the toolbar icon. Chromium hides new extensions behind the puzzle-piece button, and the badge count is one of the three places findings appear — if it is hidden you lose that surface. Click the puzzle piece, find Wiretype, click the pin.

Brave

Everything works except the browser side panel: Brave does not expose the chrome.sidePanel API. This is why the in-page panel is the primary surface — the floating tab at the bottom right of the page, which works identically in every browser. Nothing is missing in Brave; the findings are simply shown in the page rather than in browser chrome.

Brave Shields already blocks many of the vendors Wiretype looks for. That is a good thing, but it means fewer detections while browsing with Shields up — a blocked script never runs, so there is nothing to catch. To see Wiretype work on a real site, lower Shields for that site.

Firefox — not supported

Firefox will install the extension and it will do nothing useful. This is not a packaging problem and cannot be worked around with a manifest tweak.

Wiretype has to run inside the page's own JavaScript world, before any page script, in order to wrap the value getters that trackers read through. In Chromium that is "world": "MAIN" on a content script. Firefox ignores that key and runs every content script in an isolated world, where the page's own getters are simply not reachable. The sensor would install into a copy of the environment that no tracker ever touches, detect nothing, and report "nothing found" — which is the worst possible failure for this product, because silence looks like safety.

A Firefox port is possible but is a different implementation: injecting a <script> element into the page and communicating over window.postMessage, with wrappedJSObject and exportFunction for the boundary. It is real work, not a build flag, and it would need its own tamper story because a page can see and remove an injected script tag.

Safari — not supported

Safari requires the extension to be converted into an Xcode project and signed with an Apple developer account. It also does not support MAIN-world content scripts, so it has the same fundamental blocker as Firefox.

Checking that it works

Seeing nothing is the normal case. On most pages Wiretype is silent, because most pages have no known form-reading tracker on them. Silence is not evidence of a broken install, which makes a positive check worth doing once.

The reliable way: run the fixtures

Requires the development build (the repo's extension/ folder) and Python for two static servers. From the repository root, in two terminals:

python -m http.server 8010 --bind 127.0.0.1

cd fixtures/thirdparty && python -m http.server 8011 --bind 127.0.0.1

Then open:

http://127.0.0.1:8010/fixtures/ui.html

You should see red outlines on the fields that were read, a floating tab at the bottom right reading 2 fields read, and PASS results in the page. Every page under fixtures/ states what it is testing and what a pass looks like:

Fixture	Checks
ui.html	outlines, tooltip, panel, verdict
phase-a.html	the amber tier — a vendor present, nothing read
formdata.html	a whole form harvested in one FormData call
tamper.html	three real attempts to bypass detection
repaint.html	the outline surviving a page that wipes it
iframe.html	detection inside a cross-origin frame
perf.html	keystroke cost, with a baseline to compare against

On a real site

Load a page with a newsletter or SMS signup popup, or an insurance or loan quote form — those have the highest hit rate. Click into a field and type something harmless. If a known vendor is present you get an amber tab; if one reads the field you get a red one.

Use fake data. wiretype-test@example.com and 555-0100 are fine. The entire premise of the extension is that what you type may leave before you submit, so this is not the place to try it with your real address.

Updating and troubleshooting

After changing the code: click the reload arrow on the extension's card. Chromium does not pick up file changes on its own.

After moving or renaming the folder: the reload arrow will not save you. An unpacked extension is bound to its path — remove it and load it again from the new location.

"Manifest file is missing or unreadable": you selected the wrong folder. It must be the one containing manifest.json directly.

"This extension may have been corrupted": usually a partial download of the zip. Delete and re-download.

No badge and no floating tab, ever: check the extensions page for a red Errors button on the card, which shows service-worker failures. Then confirm with a fixture — if ui.html passes, the install is fine and the pages you were visiting genuinely had nothing to report.

window.__WT_DEBUG__ is undefined: you are running the production build, where that is intentional. Load the repo's extension/ folder instead.