sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/gm-values.js

@@ -0,0 +1,176 @@
+// SW-side persistent storage for `GM_setValue` / `GM_getValue` /
+// `GM_deleteValue` / `GM_listValues` and their GM4 aliases.
+//
+// Layout. Each `(scriptId, key)` lives at its own
+// `gmval:<scriptId>:<key>` row in chrome.storage.local. Rows are
+// independent of `script:<id>` rows so a write doesn't churn the
+// match-index cache; conversely, deleting a script doesn't lose its
+// stored values without an explicit sweep.
+//
+// Why per-key rows (not a per-script object): chrome.storage.local
+// rejects values larger than ~8 KB per row in some Chrome builds,
+// but the per-row quota is much higher than the per-extension quota.
+// Per-key rows let a single 64 KB value land without forcing the
+// whole script's storage into one row that bumps against the
+// per-row limit; they also let us write a single key delta without
+// rewriting siblings.
+//
+// Type tagging happens PAGE-SIDE, not here. chrome.storage
+// round-trips via JSON, which is lossy for Date / Map / Set / NaN /
+// undefined — but so is `chrome.runtime.sendMessage`, so by the time
+// a value reaches this module the damage would already be done. The
+// codec therefore lives in `wrapper-gm-runtime.js`, which tags a
+// value before it goes on the wire and revives it after the snapshot
+// comes back. This module stores whatever it is handed, opaquely.
+//
+// The tagged form is a plain `{ __smv__: 1, v: … }` object, and only
+// values JSON would have mangled get wrapped at all — so rows this
+// module wrote before the codec existed are byte-identical to what
+// it writes for the same values now. See
+// docs/GM-APIs-storage.md#value-type-fidelity.
+//
+// Reading one script's values. chrome.storage has no prefix query, so
+// the shape is `getKeys()` → filter → `get(thoseKeys)`. That matters
+// more than it looks: the alternative, `get(null)`, returns every row
+// the extension owns and is paid for on the reload fast path. See
+// `loadAllValues`.
+import { scanAllStorage, timeStorageRead } from './storage-scan.js';
+export const VALUE_PREFIX = 'gmval:';
+// Compose / parse the storage key shape: `gmval:<scriptId>:<key>`.
+// `scriptId` is a UUID so no `:` in it; `key` may contain `:`. We
+// only split on the FIRST two colons to preserve any colons in the
+// user-supplied key.
+export function valueKey(scriptId, key) {
+    return `${VALUE_PREFIX}${scriptId}:${key}`;
+}
+export function valueKeyPrefix(scriptId) {
+    return `${VALUE_PREFIX}${scriptId}:`;
+}
+// Extract the user-supplied key from a `gmval:<scriptId>:<key>` row
+// name. Returns `null` for rows that don't belong to this script.
+export function parseValueKey(rowKey, scriptId) {
+    const prefix = valueKeyPrefix(scriptId);
+    if (!rowKey.startsWith(prefix))
+        return null;
+    return rowKey.slice(prefix.length);
+}
+// Load every stored value for a script as a plain object. The value
+// store calls it the first time it needs a script's values.
+//
+// There is no prefix query, so the shape has to be "narrow the key set,
+// then read only those rows". `getKeys()` (Chrome 130+) returns names
+// without values, which is the cheap half; the fallback reads
+// everything the way this always did.
+//
+// Why it matters that this is narrow: the caller on the reload fast
+// path runs it INSIDE the 500 ms swap window, and a full-namespace
+// read is not merely bigger — deserializing it occupies the worker's
+// single thread, so it delays the swap decision and every unrelated
+// callback waiting alongside it. Measured on a 266-row profile: ~155 ms
+// for the whole namespace versus a handful of `gmval:` rows.
+// See docs/diagnostics.md#storage-scans.
+export async function loadAllValues(scriptId) {
+    const prefix = valueKeyPrefix(scriptId);
+    const out = {};
+    // Timed around BOTH legs — the key listing is part of what the narrow
+    // path costs, and the line exists to be compared against the full
+    // scan it replaced.
+    const narrow = await timeStorageRead('gm snapshot (narrow)', async () => {
+        const keys = await listValueKeys(prefix);
+        if (!keys)
+            return null;
+        return keys.length === 0 ? {} : await chrome.storage.local.get(keys);
+    });
+    if (narrow) {
+        for (const [k, v] of Object.entries(narrow))
+            out[k.slice(prefix.length)] = v;
+        return out;
+    }
+    const all = await scanAllStorage('gm snapshot');
+    for (const [k, v] of Object.entries(all)) {
+        if (k.startsWith(prefix))
+            out[k.slice(prefix.length)] = v;
+    }
+    return out;
+}
+// How many values a script has stored, read without the values.
+export async function countStoredValues(scriptId) {
+    const prefix = valueKeyPrefix(scriptId);
+    const keys = await listValueKeys(prefix)
+        ?? Object.keys(await scanAllStorage('gm value count')).filter((k) => k.startsWith(prefix));
+    return keys.length;
+}
+// Every stored key starting with `prefix`, or null when the browser has
+// no `getKeys` — in which case the caller falls back to a full scan.
+// A throw is treated the same as absence: this is an optimisation, and
+// nothing about it should be able to fail a value read.
+async function listValueKeys(prefix) {
+    const area = chrome.storage.local;
+    if (typeof area.getKeys !== 'function')
+        return null;
+    try {
+        return (await area.getKeys()).filter((k) => k.startsWith(prefix));
+    }
+    catch {
+        return null;
+    }
+}
+// The deletion sentinel. Compared by reference in the SW handler so a
+// userscript that happens to set the value to the same string literal
+// is not treated as a delete.
+export const DELETED_SENTINEL = Object.freeze({ __sm_deleted__: true });
+export function isDeletionSentinel(v) {
+    return v === DELETED_SENTINEL;
+}
+// Apply a batched mixed set/delete operation. Returns the changed
+// keys so a future broadcast phase can ship the delta to other tabs.
+//
+// Pure semantics: if the same key appears multiple times in the
+// batch, the LAST write wins (matches what a sequence of GM_setValue
+// + GM_deleteValue calls would do).
+export async function applyBatchValues(scriptId, writes) {
+    if (writes.length === 0)
+        return { setKeys: [], deletedKeys: [] };
+    // Resolve last-write-wins per key.
+    const finalSets = new Map();
+    const finalDeletes = new Set();
+    for (const w of writes) {
+        if (isDeletionSentinel(w.value)) {
+            finalDeletes.add(w.key);
+            finalSets.delete(w.key);
+        }
+        else {
+            finalDeletes.delete(w.key);
+            finalSets.set(w.key, w.value);
+        }
+    }
+    // chrome.storage.local.set + remove are independent calls; do them
+    // in parallel. We never want a partial application — if either
+    // rejects, the caller should re-try the whole batch. We don't
+    // attempt rollback because chrome.storage doesn't expose that.
+    const setObj = {};
+    for (const [k, v] of finalSets)
+        setObj[valueKey(scriptId, k)] = v;
+    const removeKeys = [...finalDeletes].map((k) => valueKey(scriptId, k));
+    const ops = [];
+    if (Object.keys(setObj).length > 0)
+        ops.push(chrome.storage.local.set(setObj));
+    if (removeKeys.length > 0)
+        ops.push(chrome.storage.local.remove(removeKeys));
+    await Promise.all(ops);
+    return {
+        setKeys: [...finalSets.keys()],
+        deletedKeys: [...finalDeletes],
+    };
+}
+// Sweep every `gmval:<scriptId>:*` row. Called only through the value
+// store's `wipeValues`, which also drops the store's own copy.
+export async function wipeScriptValues(scriptId) {
+    const prefix = valueKeyPrefix(scriptId);
+    const keys = await listValueKeys(prefix)
+        ?? Object.keys(await scanAllStorage('gm value wipe')).filter((k) => k.startsWith(prefix));
+    if (keys.length === 0)
+        return 0;
+    await chrome.storage.local.remove(keys);
+    return keys.length;
+}

package/dist/extension/gm-window-control.js

@@ -0,0 +1,104 @@
+// SW-side driver for `@grant window.close` and `@grant window.focus`.
+//
+// Why the service worker is involved: both methods exist in the page
+// already, and both are hobbled there.
+//
+//   - `window.close()` is refused for any tab the script didn't open
+//     itself with `window.open` ("Scripts may close only the windows
+//     that were opened by them").
+//   - `window.focus()` on a background tab does nothing; nothing in a
+//     page can select another tab or raise the OS window.
+//
+// An extension is not bound by either rule, so the granted call is
+// routed here and re-issued as `chrome.tabs.remove` /
+// `chrome.tabs.update` + `chrome.windows.update`. That is also how TM
+// implements the same two grants — the page-side override is a thin
+// shim over the extension's own tab/window control.
+//
+// Wire protocol (page → SW, `chrome.runtime.sendMessage`):
+//   `{ type: 'sm:gm-window-close' | 'sm:gm-window-focus', scriptId }`
+//   → `{ ok: true }` or `{ ok: false, error }`.
+//
+// The target is never named in the payload: it is always the sender's
+// own tab. A script can only close/focus the tab it is running in, so
+// there is nothing to spoof — unlike GM_openInTab, whose URL comes
+// from the page.
+export const SM_WINDOW_CLOSE_MSG = 'sm:gm-window-close';
+export const SM_WINDOW_FOCUS_MSG = 'sm:gm-window-focus';
+function reason(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // Capitalized because it lands after a `: ` — see the error-message
+    // rules in CLAUDE.md.
+    return msg === '' ? 'The browser gave no reason' : msg;
+}
+// The last tab standing is not closable. Chrome would allow it — and
+// take the whole browser down with it, since closing the final tab
+// quits. Handing a userscript the ability to quit the browser is a
+// different order of capability from closing a tab, so it is refused.
+// TM 5.5.0 refuses it the same way (`fp` in its `background.js`:
+// `tabs.query({windowType:'normal'})`, then "refused to close last
+// tab!" when one or fewer come back).
+export const LAST_TAB_NOT_CLOSABLE = 'The last open tab cannot be closed';
+// `window.close()` → close the sender's tab.
+//
+// Nothing is reported back on success: the document that asked is gone
+// by then. The tab count is read across every normal window, not just
+// the sender's, so closing the last tab of one window while another is
+// open still works.
+export async function closeGmWindow(tabId) {
+    try {
+        const tabs = await chrome.tabs.query({ windowType: 'normal' });
+        if (tabs.length <= 1) {
+            return { ok: false, error: LAST_TAB_NOT_CLOSABLE };
+        }
+        await chrome.tabs.remove(tabId);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: `This tab could not be closed: ${reason(err)}` };
+    }
+}
+// `window.focus()` → bring the sender's tab to the front: select it
+// within its window, and raise (and un-minimize) that window.
+//
+// Both halves are needed for the call to mean anything. Raising alone
+// is invisible in the common single-window case — the window is
+// already frontmost and the user is simply looking at another tab —
+// and selecting alone leaves the tab hidden behind another window.
+//
+// A minimized window has to be restored explicitly — `focused: true`
+// alone leaves it minimized — so the current state is read first.
+// `chrome.windows.update` rejects `{ focused: true, state:
+// 'minimized' }`, which is why the two are never combined.
+//
+// This is step-for-step what TM 5.5.0 does (`focusTab` in its
+// `background.js`): `tabs.update({active:true})`, then `windows.get`,
+// then `windows.update({focused:true, state})` with `state` set to
+// `'normal'` only for a minimized window.
+//
+// Whether the window actually comes forward is ultimately the OS
+// window manager's call: several Linux WMs answer a programmatic
+// raise by flashing the taskbar entry instead. Nothing an extension
+// can do about that, and Chrome reports no error for it.
+export async function focusGmWindow(tabId, windowId) {
+    if (!chrome.windows) {
+        return { ok: false, error: 'Window focus is not available in this browser' };
+    }
+    try {
+        await chrome.tabs.update(tabId, { active: true });
+        let minimized = false;
+        try {
+            const win = await chrome.windows.get(windowId);
+            minimized = win.state === 'minimized';
+        }
+        catch {
+            // Non-fatal: worst case we skip the un-minimize and the plain
+            // `focused: true` below still runs.
+        }
+        await chrome.windows.update(windowId, minimized ? { focused: true, state: 'normal' } : { focused: true });
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: `This tab could not be focused: ${reason(err)}` };
+    }
+}

package/dist/extension/gm-xhr-headers.js

@@ -0,0 +1,333 @@
+// Request-header surgery for `GM_xmlhttpRequest`.
+//
+// The problem: `fetch()` silently drops any header the Fetch Standard
+// (the web standard defining `fetch`, at fetch.spec.whatwg.org) calls
+// a *forbidden request header* — `Origin`, `Referer`, `Cookie`,
+// `Host`, `User-Agent`, and everything with a `Sec-` or `Proxy-`
+// prefix. A userscript that needs one of those (and userscripts do:
+// sites gate APIs on `Sec-Fetch-Site`, `Referer`, or a hand-built
+// `Cookie`) has no way to set it from JS at all — the restriction
+// applies in the service worker exactly as it does on a page.
+//
+// The fix, and why it looks like this:
+//
+//   - Manifest V3 has no blocking `webRequest`, so headers can only be
+//     rewritten by `declarativeNetRequest` (DNR — Chrome's rule-based
+//     request-rewriting API). Rules are data, evaluated by the browser
+//     after our `fetch` call has already handed the request over.
+//   - So the caller's forbidden headers are *not* passed to `fetch`.
+//     They're compiled into a short-lived DNR session rule that sets
+//     them on the way out, and the rule is torn down when the request
+//     settles.
+//   - DNR cannot match on a request header, so the rule can't be
+//     targeted by a header tag. It's targeted by a tag in the URL's
+//     *fragment* instead: the request goes out as `<url>#sm-xhr-<id>`
+//     and the rule matches that exact string. A fragment is never
+//     transmitted, so the server still sees the URL the script asked
+//     for, byte for byte — and `Response.url` drops it again, so
+//     `finalUrl` is unaffected.
+//   - Measured, not assumed: for a service-worker `fetch`, DNR matches
+//     the fragment literally. A fragment'd rule does not match a
+//     fragment-less request, a fragment-less rule does not match a
+//     fragment'd one, and two different fragments never match each
+//     other. The full table is in docs/xhr-header-surgery.md.
+//   - So the tag is a genuine per-request discriminator, which is what
+//     makes the rule apply to exactly the request that installed it.
+//     Two same-URL requests in flight at once — the case that would
+//     otherwise have one picking up the other's `Cookie` — differ in
+//     their tag and so in their rule.
+//   - `tabIds: [-1]` ("no tab", true of every extension request and no
+//     page load) and `initiatorDomains: [<our id>]` stay on as defence
+//     in depth. Violentmonkey's MV3 path uses the same fragment trick
+//     with `tabIds` alone.
+//
+// Tags are *not* globally unique: `nextRuleId` restarts at
+// XHR_RULE_ID_MIN in every worker life, so a rule stranded by a killed
+// worker holds a tag the next worker will hand out again. What keeps
+// that harmless is the install path, and both halves of it matter:
+// `installHeaderRule` waits for `clearStaleHeaderRules` (so the
+// stranded rule is normally gone before any tagged request exists) and
+// then adds its rule in the same `updateSessionRules` call that clears
+// its own id (so a sweep that failed can't leave a colliding rule
+// live). Don't drop either as redundant.
+// Headers `fetch()` refuses to send. Close to the Fetch Standard's
+// forbidden-request-header list, but the authority here is what Chrome
+// actually drops, which is not the same set: `user-agent` came off the
+// spec list and Chrome still drops it, so it stays. Prefix rules
+// (`Sec-`, `Proxy-`) are handled separately in `isForbiddenHeader`.
+//
+// Routing a header here means a script can now genuinely set it —
+// including framing headers like `content-length` and
+// `transfer-encoding`, which `fetch` used to swallow harmlessly. That
+// is the same latitude Tampermonkey gives, and the script asked.
+//
+// `Cookie` is on the list but deliberately absent here — see
+// `COOKIE_HEADER` below.
+const FORBIDDEN_HEADERS = new Set([
+    'accept-charset',
+    'accept-encoding',
+    'access-control-request-headers',
+    'access-control-request-method',
+    'connection',
+    'content-length',
+    'cookie2',
+    'date',
+    'dnt',
+    'expect',
+    'host',
+    'keep-alive',
+    'origin',
+    'permissions-policy',
+    'referer',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+    'user-agent',
+    'via',
+    // Forbidden only when the value names a forbidden method, but
+    // `fetch` won't carry them dependably either way, so they take the
+    // rule path unconditionally.
+    'x-http-method',
+    'x-http-method-override',
+    'x-method-override',
+]);
+// `Cookie` needs the same surgery but has an extra consequence: a
+// script-supplied Cookie replaces what the browser would have sent, so
+// setting it is also a way to *drop* the user's session. Kept separate
+// so callers can reason about it on its own.
+const COOKIE_HEADER = 'cookie';
+// Whether `fetch()` would refuse to send this header, so it has to go
+// through a DNR rule instead.
+export function isForbiddenHeader(name) {
+    const lower = name.toLowerCase();
+    if (FORBIDDEN_HEADERS.has(lower) || lower === COOKIE_HEADER)
+        return true;
+    // Prefix rules. `Sec-` is the one that matters most in practice:
+    // `Sec-Fetch-Site` is how a server tells a page request from an
+    // extension one, and a service worker always sends `none` — a value
+    // no page can produce, which some WAFs (web application firewalls —
+    // the filtering layer in front of a site) reject outright.
+    return lower.startsWith('sec-') || lower.startsWith('proxy-');
+}
+// Header names are case-insensitive, so a caller passing both `Origin`
+// and `origin` collapses to one surgical entry and the last one wins.
+// Object key order is the caller's own, and either value is a thing
+// they asked for, so there's nothing better to pick.
+export function splitHeaders(headers) {
+    const passthrough = {};
+    const surgical = {};
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        if (isForbiddenHeader(name))
+            surgical[name.toLowerCase()] = value;
+        else
+            passthrough[name] = value;
+    }
+    return { passthrough, surgical };
+}
+// The one header we change without being asked: `Origin`, which
+// `fetch` from the service worker stamps as `chrome-extension://<id>`.
+// That tells the target nothing it should act on and advertises that
+// the user runs SourceMonkey, so it comes off.
+//
+// Only on methods that would carry one. Measured: a SW `fetch` sends
+// `Origin` on POST and not on GET, so defaulting it for every request
+// would install a rule per request to remove a header that isn't
+// there — a declarativeNetRequest round trip each way, on the most
+// common shape of request there is.
+//
+// Nothing else is defaulted. In particular `Sec-Fetch-Site` is left at
+// the `none` the browser supplies: setting it to `same-origin` defeats
+// a site's cross-origin check, and that is a thing a script should have
+// to ask for rather than something every request quietly does. A script
+// that needs it passes it in `headers` like any other.
+const ORIGIN_LESS_METHODS = new Set(['GET', 'HEAD']);
+function defaultRemovedHeaders(method) {
+    return ORIGIN_LESS_METHODS.has(method.toUpperCase()) ? [] : ['origin'];
+}
+// `urlFilter` is a pattern language, not a literal: `*` matches any
+// run of characters and `^` matches any URL separator. A URL carrying
+// either — legal in a query string — would silently widen the rule to
+// other URLs, and the headers meant for one request would be applied
+// to somebody else's. `|` is special only at the ends, where we put
+// our own anchors, so an embedded one is already literal.
+//
+// URLs with a metacharacter go through `regexFilter` instead, where
+// everything can be escaped exactly. Ordinary URLs keep the cheaper
+// `urlFilter` path.
+function hasUrlFilterMetacharacter(url) {
+    return url.includes('*') || url.includes('^');
+}
+// Escape for DNR's regexFilter (RE2). Every character that could be
+// regex syntax is backslash-escaped, so the pattern matches the URL and
+// nothing else. `/` is deliberately absent — it isn't syntax in RE2
+// (there are no delimiters to close) and `\/` is what a stricter engine
+// would reject.
+function escapeForRegexFilter(url) {
+    return url.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// Fragment tag that makes a request identifiable to its own rule. The
+// rule id doubles as the tag: it is already unique among live rules,
+// and tying the two together means a request and its rule can't
+// disagree about which one it is. Prefixed so a tagged URL is
+// recognizable in DevTools.
+const XHR_URL_TAG_PREFIX = 'sm-xhr-';
+// The URL as the browser will actually request it, which is what DNR
+// matches against — not the string the script passed. `fetch`
+// canonicalizes first: a space becomes `%20`, a bare origin gains its
+// `/`, scheme and host lowercase, a default port drops, non-ASCII is
+// percent-encoded or punycoded. Matching the raw string means the rule
+// silently fails to apply, which for a `Cookie` override is worse than
+// an error — the user's real session goes out in place of the one the
+// script asked for.
+//
+// The fragment carries this request's tag, which is what makes the rule
+// match one request rather than every request to that URL. Whatever the
+// script put there is replaced: a fragment is never sent, and
+// `Response.url` strips it again, so nothing the script can observe
+// depends on it.
+//
+// A URL `new URL()` can't parse is handed back unchanged, untagged.
+// Unreachable in practice — the `@connect` check rejects such a URL
+// before `runXhr` is entered — and harmless if it were reached: the
+// rule and the fetch still name the same string.
+export function taggedRequestUrl(url, ruleId) {
+    try {
+        const parsed = new URL(url);
+        parsed.hash = `${XHR_URL_TAG_PREFIX}${ruleId}`;
+        return parsed.href;
+    }
+    catch {
+        return url;
+    }
+}
+// This extension's id, which is the "domain" of a request it starts.
+// Guarded because the rule builder is also exercised outside an
+// extension (unit tests); without an id the rule keeps the broader
+// `tabIds` condition alone rather than failing to build.
+function selfInitiatorDomain() {
+    return typeof chrome !== 'undefined' ? chrome.runtime?.id : undefined;
+}
+// DNR session-rule ids. XHR rules start well above zero and climb,
+// leaving the low ids free for any other subsystem that wants one.
+//
+// Everything from XHR_RULE_ID_MIN up is this module's band —
+// `clearStaleHeaderRules` deletes any session rule in it at startup, so
+// a future subsystem that wants its own session rule must stay below.
+//
+// Ids only have to be unique among *live* rules and each is released
+// when its request settles, so the counter wraps. A collision needs
+// ~999,000 requests in flight at once, or a stranded rule the sweep
+// never reached; `installHeaderRule` clears the id before reusing it so
+// neither turns into a failed install. That clear is not free of
+// consequence, though: if the id really were still live, its request
+// loses its overrides silently — so the band is sized to keep the wrap
+// unreachable rather than to make the collision survivable.
+const XHR_RULE_ID_MIN = 1000;
+const XHR_RULE_ID_MAX = 1_000_000;
+let nextRuleId = XHR_RULE_ID_MIN;
+export function allocateRuleId() {
+    const id = nextRuleId;
+    nextRuleId = id >= XHR_RULE_ID_MAX ? XHR_RULE_ID_MIN : id + 1;
+    return id;
+}
+// Drop any XHR header rule left over from a previous service-worker
+// life. Rules come off in `runXhr`'s `finally`, but a worker killed
+// mid-request never reaches it, and a session rule outlives the worker
+// — it would go on rewriting requests to that URL for the rest of the
+// browser session. Called once at startup, when no XHR can be in
+// flight yet.
+let staleSweep = null;
+// Resolves once the startup sweep has finished (immediately if it was
+// never started). `installHeaderRule` waits on this so the sweep can't
+// delete a rule added while it was reading the rule list.
+export function whenStaleRulesCleared() {
+    return staleSweep ?? Promise.resolve();
+}
+export function clearStaleHeaderRules() {
+    staleSweep = runStaleSweep();
+    return staleSweep;
+}
+async function runStaleSweep() {
+    const dnr = chrome.declarativeNetRequest;
+    if (!dnr)
+        return;
+    try {
+        const rules = await dnr.getSessionRules();
+        const stale = rules.filter((r) => r.id >= XHR_RULE_ID_MIN).map((r) => r.id);
+        if (stale.length > 0)
+            await dnr.updateSessionRules({ removeRuleIds: stale });
+    }
+    catch (err) {
+        console.info('[SourceMonkey] could not clear stale GM_xmlhttpRequest header rules', err);
+    }
+}
+// Build the session rule that applies `surgical` to the request for
+// `url`. Returns null when there's nothing to do — no overrides and
+// nothing to remove — so the common request costs no rule at all.
+export function buildHeaderRule(url, surgical, method = 'GET') {
+    const requestHeaders = [];
+    for (const [header, value] of Object.entries(surgical)) {
+        requestHeaders.push({
+            header,
+            value,
+            operation: 'set',
+        });
+    }
+    for (const header of defaultRemovedHeaders(method)) {
+        // A caller-supplied value wins over the default removal.
+        if (header in surgical)
+            continue;
+        requestHeaders.push({
+            header,
+            operation: 'remove',
+        });
+    }
+    if (requestHeaders.length === 0)
+        return null;
+    const initiator = selfInitiatorDomain();
+    const id = allocateRuleId();
+    // The id is also the URL tag, so the rule and the request it belongs
+    // to name each other. Everything else about the URL is canonicalized
+    // by `new URL()` on the way through, which is what `fetch` will do to
+    // it as well — a rule built from the raw string would match nothing.
+    const target = taggedRequestUrl(url, id);
+    return {
+        id,
+        target,
+        rule: {
+            id,
+            // Constant. Priority never has to arbitrate between our own
+            // rules: the URL tag means at most one of them matches any given
+            // request.
+            priority: 1,
+            action: {
+                type: 'modifyHeaders',
+                requestHeaders,
+            },
+            condition: {
+                // `|` anchors mean "the whole URL, exactly"; `^…$` is the
+                // regex equivalent for URLs that can't use urlFilter safely.
+                ...(hasUrlFilterMetacharacter(target)
+                    ? { regexFilter: `^${escapeForRegexFilter(target)}$` }
+                    : { urlFilter: `|${target}|` }),
+                isUrlFilterCaseSensitive: true,
+                // The tag alone already picks out one request, since nothing
+                // else asks for that URL. These narrow it anyway, so a rule
+                // can't reach beyond this extension even if a tag ever escaped:
+                // `tabIds: [-1]` is "not associated with a tab", which every
+                // extension request is and no page load is, and
+                // `initiatorDomains` pins it to requests this extension
+                // started. `tabIds` is allowed only on session rules, which is
+                // what these are.
+                //
+                // Verified rather than assumed: with a bogus initiator the
+                // header e2e tests fail, so the condition really is evaluated
+                // and really does match us.
+                tabIds: [-1],
+                ...(initiator ? { initiatorDomains: [initiator] } : {}),
+                resourceTypes: ['xmlhttprequest'],
+            },
+        },
+    };
+}