sourcemonkey 0.0.0-stage → 0.5.0

package/lib/gm-api-catalog.js

@@ -0,0 +1,217 @@
+// Catalog of GM_* / GM.* APIs that SourceMonkey supports (or has slots
+// for). This is the single source of truth that:
+//
+//   - The injector consults to decide which GM_* function definitions
+//     to compile into a given script's wrapper, based on its @grant
+//     lines. This is where @grant is actually enforced: an ungranted
+//     API is simply never bound into the script's scope.
+//   - The permission-test e2e spec consults to assert that ungranted
+//     APIs are not bound in the script's scope.
+//
+// NOTE: the SW-side async handlers do NOT re-validate @grant against
+// this catalog. Enforcement is binding-time only (above). Re-checking
+// in the SW would add no security: the per-message `scriptId` is
+// wrapper-supplied and spoofable, so a script that wanted to bypass
+// the grant would just claim the id of a script that has it. See the
+// "trust caveat" notes in docs/GM-APIs.md.
+//
+// Each API entry says:
+//   - The canonical `GM_x` name and the GM4-style `GM.x` alias (if
+//     any). Scripts can @grant either form and we honor both.
+//   - Whether the call resolves in-page (`sync`) — runs in
+//     USER_SCRIPT world via the shared GM runtime — or makes a
+//     SW round-trip (`async`).
+//   - The subsystem the body delegates to. Drives both the wrapper-side
+//     stub and the SW-side message routing.
+//
+// Adding a new API: append an entry, then either (a) implement the
+// sync body in src/wrapper-gm-runtime.js if `kind === 'sync'` or (b)
+// add an SW-side handler if `kind === 'async'`.
+import { getValues } from './userscript-header.js';
+// What a request that reads or writes a script's stored values has to
+// have granted: any storage API, or a value-change listener (its
+// snapshot seeds the listener's remote-change detection). Used by the
+// bridge gate in background.ts.
+export const STORAGE_SUBSYSTEMS = ['storage', 'storage-listener'];
+// The refusal a bridge-relayed request gets when the page may not act
+// for the script it names. Shared by the same two gates.
+export const BRIDGE_DENIED = 'This page is not allowed to act for that userscript';
+// IMPORTANT: when adding entries here keep the order stable — emit
+// order in the wrapper isn't load-bearing but stable order makes
+// stack traces and diffed wrapper bodies easier to compare across
+// runs.
+export const GM_APIS = Object.freeze([
+    // ----- Compile-time / in-page constants -----
+    { name: 'GM_info', gmDotName: 'info', kind: 'sync', subsystem: 'info' },
+    { name: 'unsafeWindow', kind: 'sync', subsystem: 'unsafe-window' },
+    // ----- Non-GM_* window features (TM's `@grant window.x` family) -----
+    // `window.onurlchange` is not a callable and not a valid JS
+    // identifier, so it emits no `const` binding at all. What the grant
+    // buys is an eager `__smReg.gm.urlchange.enable(scriptId)` call that
+    // installs the `urlchange` event surface on the world's `window`.
+    // See docs/GM-APIs.md#windowonurlchange.
+    { name: 'window.onurlchange', kind: 'sync', subsystem: 'url-change' },
+    // `window.close` / `window.focus` are callables, but `window.close`
+    // is not a legal binding name either — so, like the grant above,
+    // they emit no `GM_*`-style binding. The grant's effect is an eager
+    // `__smReg.gm.windowControl` call that REPLACES the method the script
+    // sees (on its sandbox `window` in the page's world, on the world's
+    // `window` when isolated) with one that routes through the SW (`chrome.tabs.remove` / `chrome.windows.update`),
+    // which is what lets it work where the page's own call is a no-op.
+    // `async` for that SW round-trip; the script still sees the void,
+    // synchronous return TM gives it. See docs/GM-APIs.md#windowclose--windowfocus.
+    { name: 'window.close', kind: 'async', subsystem: 'window-control' },
+    { name: 'window.focus', kind: 'async', subsystem: 'window-control' },
+    // ----- Logging -----
+    { name: 'GM_log', gmDotName: 'log', kind: 'sync', subsystem: 'log' },
+    // ----- Storage (sync return; GM. form returns Promise per GM4) -----
+    { name: 'GM_setValue', gmDotName: 'setValue', gmDotPromised: true, kind: 'sync', subsystem: 'storage' },
+    { name: 'GM_getValue', gmDotName: 'getValue', gmDotPromised: true, kind: 'sync', subsystem: 'storage' },
+    { name: 'GM_deleteValue', gmDotName: 'deleteValue', gmDotPromised: true, kind: 'sync', subsystem: 'storage' },
+    { name: 'GM_listValues', gmDotName: 'listValues', gmDotPromised: true, kind: 'sync', subsystem: 'storage' },
+    // ----- Value-change listeners (sync register/unregister) -----
+    { name: 'GM_addValueChangeListener', gmDotName: 'addValueChangeListener', kind: 'sync', subsystem: 'storage-listener' },
+    { name: 'GM_removeValueChangeListener', gmDotName: 'removeValueChangeListener', kind: 'sync', subsystem: 'storage-listener' },
+    // ----- DOM injection -----
+    { name: 'GM_addStyle', gmDotName: 'addStyle', kind: 'sync', subsystem: 'dom' },
+    { name: 'GM_addElement', gmDotName: 'addElement', kind: 'sync', subsystem: 'dom' },
+    // ----- @resource lookups (require @resource header support) -----
+    // GM4 spelling is `GM.getResourceUrl` (lowercase 'u') — keep the
+    // casing mismatch with GM_getResourceURL, it's deliberate.
+    { name: 'GM_getResourceText', gmDotName: 'getResourceText', kind: 'sync', subsystem: 'resource', requires: ['resource'] },
+    { name: 'GM_getResourceURL', gmDotName: 'getResourceUrl', kind: 'sync', subsystem: 'resource', requires: ['resource'] },
+    // ----- Menu commands (stub: register/unregister) -----
+    { name: 'GM_registerMenuCommand', gmDotName: 'registerMenuCommand', kind: 'sync', subsystem: 'menu' },
+    { name: 'GM_unregisterMenuCommand', gmDotName: 'unregisterMenuCommand', kind: 'sync', subsystem: 'menu' },
+    // ----- Async APIs (cross-world, SW round-trip) -----
+    // Note: GM_xmlhttpRequest returns a sync control object, but the
+    // request itself is async. We classify by SW round-trip — `async` —
+    // because the wrapper has to message the SW to start the request.
+    { name: 'GM_xmlhttpRequest', gmDotName: 'xmlHttpRequest', kind: 'async', subsystem: 'xhr', requires: ['connect'] },
+    // GM_setClipboard is handled in-page via navigator.clipboard.writeText
+    // — no SW round-trip — so it's classified `sync` even though the
+    // underlying browser call is async (returns Promise<void>). Page-
+    // handled vs SW-handled is what `kind` actually means in this
+    // catalog. TM/VM use an offscreen document via execCommand('copy');
+    // we may revisit later if real users hit "navigator.clipboard
+    // requires focus" failures.
+    { name: 'GM_setClipboard', gmDotName: 'setClipboard', kind: 'sync', subsystem: 'clipboard' },
+    { name: 'GM_notification', gmDotName: 'notification', kind: 'async', subsystem: 'notification' },
+    { name: 'GM_openInTab', gmDotName: 'openInTab', kind: 'async', subsystem: 'tab' },
+    // Per-tab objects kept by the SW while the tab is open. Each takes an
+    // optional callback, as in TM, and returns a Promise when given none,
+    // which is what the `GM.` form passes through.
+    { name: 'GM_getTab', gmDotName: 'getTab', kind: 'async', subsystem: 'tab-data' },
+    { name: 'GM_saveTab', gmDotName: 'saveTab', kind: 'async', subsystem: 'tab-data' },
+    { name: 'GM_getTabs', gmDotName: 'getTabs', kind: 'async', subsystem: 'tab-data' },
+    // Like GM_xmlhttpRequest, GM_download hands back a sync `{abort}`
+    // control object while the transfer itself runs in the SW — `async`
+    // classifies the SW round-trip, not the return value. It is NOT
+    // `requires: ['connect']`: download URLs are runtime-discovered CDN
+    // hosts that scripts can't enumerate in a header, and the bytes go
+    // to disk rather than back to the script, so the exfiltration risk
+    // `@connect` guards doesn't apply. See docs/GM-APIs.md.
+    { name: 'GM_download', gmDotName: 'download', kind: 'async', subsystem: 'download' },
+]);
+// Quick lookup. Built lazily so unit tests that only import types or
+// constants don't pay the Map cost; callers that hit this in a hot
+// loop should cache the result of `findApi` themselves.
+let byName = null;
+function ensureIndex() {
+    if (byName !== null)
+        return byName;
+    const m = new Map();
+    for (const a of GM_APIS) {
+        m.set(a.name, a);
+        if (a.gmDotName)
+            m.set(`GM.${a.gmDotName}`, a);
+    }
+    byName = m;
+    return m;
+}
+// Look up an API spec by either its `GM_x` name OR its `GM.x` form.
+// Returns undefined for unknown names (e.g. APIs we don't support
+// yet — `GM_webRequest`, `GM_audio`, etc.).
+export function findApi(name) {
+    return ensureIndex().get(name);
+}
+// Normalize a single `@grant` line to its canonical `GM_x` name.
+//
+// Cases:
+//   - `GM_setValue` → `'GM_setValue'`
+//   - `GM.setValue` → `'GM_setValue'` (canonicalized to the legacy form)
+//   - unknown / blank → `null`
+//
+// Does NOT handle the `none` sentinel — that's a per-script policy,
+// not a per-name canonicalization. `resolveGrants` is where `none`
+// gets recognized and propagated.
+export function canonicalizeGrant(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return null;
+    if (trimmed.toLowerCase() === 'none')
+        return null;
+    const spec = findApi(trimmed);
+    return spec ? spec.name : null;
+}
+// Resolve the set of granted GM_* names for a script, given its raw
+// @grant lines.
+//
+// Rules:
+//   - A `none` line anywhere wins — the script is treated as ungranted.
+//     Matches TM/VM behavior: a script with `@grant none` and `@grant
+//     GM_setValue` is treated as `@grant none`. The granted set is
+//     returned empty in this case; `unknown` is still populated so the
+//     caller can warn.
+//   - Unknown names are dropped from `granted` and surfaced in
+//     `unknown`. The wrapper simply won't emit a binding for them, and
+//     the script gets a natural ReferenceError at call time.
+//   - Duplicate names collapse to one (Set semantics).
+export function resolveGrants(rawGrants) {
+    const granted = new Set();
+    let hasNone = false;
+    const unknown = [];
+    for (const raw of rawGrants) {
+        const trimmed = raw.trim();
+        if (trimmed === '')
+            continue;
+        if (trimmed.toLowerCase() === 'none') {
+            hasNone = true;
+            continue;
+        }
+        const canonical = canonicalizeGrant(trimmed);
+        if (canonical === null) {
+            unknown.push(trimmed);
+            continue;
+        }
+        granted.add(canonical);
+    }
+    // @grant none wins — even if other granted lines were also present.
+    if (hasNone)
+        granted.clear();
+    return { granted, hasNone, unknown };
+}
+// True iff the named API is part of the supported surface. Used by the
+// SW-side message router to reject unknown method calls (a misbehaving
+// or stale wrapper that asks for `GM_audio.play` shouldn't be able to
+// drive any handler).
+export function isSupportedApi(name) {
+    return findApi(name) !== undefined;
+}
+// The catalog subsystems the script's `@grant` lines reach — the set the
+// SW's bridge gate (`bridgeMayActAs` in background.ts) checks a relayed
+// request against, so a page can only act for a script through APIs
+// that script actually has. `@grant none` and unknown names contribute
+// nothing.
+export function grantedSubsystems(header) {
+    const out = new Set();
+    if (!header)
+        return out;
+    const { granted } = resolveGrants(getValues(header, 'grant'));
+    for (const name of granted) {
+        const spec = findApi(name);
+        if (spec)
+            out.add(spec.subsystem);
+    }
+    return out;
+}

package/lib/gm-connect.d.ts

@@ -0,0 +1,34 @@
+import { type ParsedHeader } from './userscript-header.js';
+export interface ConnectRule {
+    kind: 'wildcard' | 'self' | 'host' | 'subdomain';
+    host?: string;
+}
+export declare function parseConnectEntry(raw: string): ConnectRule | null;
+export declare function parseConnectRules(header: ParsedHeader): ConnectRule[];
+export declare function hostMatchesRule(host: string, rule: ConnectRule, selfHosts: ReadonlySet<string>): boolean;
+export declare function hasNoConnectRules(header: ParsedHeader): boolean;
+export declare function extractSelfHosts(header: ParsedHeader): Set<string>;
+export type ConnectDecision = {
+    verdict: 'allow';
+} | {
+    verdict: 'ask';
+    host: string;
+} | {
+    verdict: 'deny';
+    reason: string;
+} | {
+    verdict: 'invalid';
+    reason: string;
+};
+export declare function decideConnect(url: string, rules: readonly ConnectRule[], selfHosts: ReadonlySet<string>, pageOrigin?: string): ConnectDecision;
+export declare function gmXhrError(problem: string): string;
+export declare function headerRuleFailedMessage(): string;
+export declare function headerStallMessage(stallMs: number): string;
+export declare function redirectRefusedMessage(): string;
+export declare function unreachableMessage(host: string): string;
+export declare function connectBlockedMessage(reason: string): string;
+export declare function connectDeniedMessage(host: string): string;
+export declare function connectCancelledMessage(host: string): string;
+export declare function connectPromptFailedMessage(host: string, cause: string): string;
+export declare function connectTooManyPromptsMessage(host: string, open: number): string;
+export declare function connectUnansweredMessage(host: string, waitMs: number): string;

package/lib/gm-connect.js

@@ -0,0 +1,273 @@
+// `@connect` URL gating for `GM_xmlhttpRequest`.
+//
+// @connect grammar (following Tampermonkey's docs):
+//   - `*` — wildcard, allow any host.
+//   - `self` — allow same-origin requests (matched against the
+//     script's @match / @include hosts).
+//   - `example.com` — that host OR any subdomain of it
+//     (`api.example.com`), as Tampermonkey documents. A label-boundary
+//     match: `evilexample.com` does not match. IP addresses and
+//     single-label names (`127.0.0.1`, `localhost`, `com`) match only
+//     exactly, so a bare rule can't stand for a whole TLD or IP range.
+//     Multi-label public suffixes (`co.uk`) are not special-cased.
+//   - `*.example.com` — `example.com` itself OR any subdomain.
+//
+// SW-side validation: when a script issues `GM_xmlhttpRequest`, the
+// SW pulls the script's stored header, parses out the `@connect`
+// lines, and rejects the request if the URL's host doesn't satisfy
+// any of them.
+//
+// A host no rule covers isn't refused outright: the extension asks the
+// user, as Tampermonkey does, and remembers the answer per script (see
+// `decideConnect` and docs/connect-permissions.md). Violentmonkey doesn't enforce
+// @connect at all.
+import { getValues } from './userscript-header.js';
+// Lower-case, normalize, classify a single raw @connect value.
+// Returns null for empty / malformed entries.
+export function parseConnectEntry(raw) {
+    const t = raw.trim().toLowerCase();
+    if (t === '')
+        return null;
+    if (t === '*')
+        return { kind: 'wildcard' };
+    if (t === 'self')
+        return { kind: 'self' };
+    if (t.startsWith('*.')) {
+        const host = t.slice(2);
+        if (!host)
+            return null;
+        return { kind: 'subdomain', host };
+    }
+    // Strip a leading scheme if the user pasted a URL by mistake — TM
+    // accepts both `example.com` and `https://example.com` in @connect
+    // lines; we normalize to the host.
+    try {
+        if (/^[a-z]+:\/\//.test(t)) {
+            const u = new URL(t);
+            return { kind: 'host', host: u.hostname };
+        }
+    }
+    catch {
+        // Fall through — treat the raw value as a host.
+    }
+    return { kind: 'host', host: t };
+}
+// Parse every `@connect` line from a header, dropping empties.
+export function parseConnectRules(header) {
+    const out = [];
+    for (const raw of getValues(header, 'connect')) {
+        const rule = parseConnectEntry(raw);
+        if (rule)
+            out.push(rule);
+    }
+    return out;
+}
+// Match `host` (lowercased; no port) against one rule. The `self`
+// rule is matched against the union of `selfHosts` — the set of
+// hostnames the script declared via @match / @include.
+export function hostMatchesRule(host, rule, selfHosts) {
+    const h = host.toLowerCase();
+    switch (rule.kind) {
+        case 'wildcard':
+            return true;
+        case 'self':
+            // TM/VM both treat `self` as "the script's own origins or
+            // their subdomains". We're conservative: exact match only.
+            // See TODO.md "@connect self subdomain handling" — known
+            // cross-manager divergence pending a real compat report.
+            return selfHosts.has(h);
+        case 'host':
+            // A bare `example.com` covers its subdomains too, as Tampermonkey
+            // documents. But not a bare IP or single label: `@connect 0.0.1`
+            // must not reach `127.0.0.1`, nor `@connect com` all of `.com`.
+            if (!rule.host)
+                return false;
+            if (h === rule.host)
+                return true;
+            return !isExactOnlyHost(rule.host) && h.endsWith('.' + rule.host);
+        case 'subdomain':
+            // The `.` prefix keeps it to whole labels, so `evilexample.com`
+            // doesn't match `*.example.com`.
+            if (!rule.host)
+                return false;
+            return h === rule.host || h.endsWith('.' + rule.host);
+        default:
+            return false;
+    }
+}
+// A bare `@connect` host that has no subdomains to cover: an IP
+// address (all-numeric dotted, or IPv6 with `:`), or a single label
+// (`localhost`, `com`).
+function isExactOnlyHost(host) {
+    return /^[\d.]+$/.test(host) || host.includes(':') || !host.includes('.');
+}
+// True when the header has no usable `@connect` rule, so all its
+// `GM_xmlhttpRequest` calls to other sites need the user's say-so. The
+// same parse enforcement uses, so a header whose `@connect` lines are
+// all malformed counts.
+export function hasNoConnectRules(header) {
+    return parseConnectRules(header).length === 0;
+}
+// Extract the set of "self" hosts from a script header's match/
+// include lines. Used to resolve the `self` @connect token.
+// Patterns we don't understand (regex includes, malformed globs)
+// are skipped — they don't contribute to "self".
+export function extractSelfHosts(header) {
+    const out = new Set();
+    const all = [...getValues(header, 'match'), ...getValues(header, 'include')];
+    for (const pat of all) {
+        const host = extractHostFromPattern(pat);
+        if (host)
+            out.add(host.toLowerCase());
+    }
+    return out;
+}
+// Pull a hostname out of a `@match` / `@include` glob if it has one.
+// `<all_urls>`, regex literals, and host-less patterns return null.
+function extractHostFromPattern(pat) {
+    if (pat === '<all_urls>')
+        return null;
+    if (pat.startsWith('/') && pat.endsWith('/'))
+        return null; // regex literal
+    // Match an URL-like glob: <scheme>://<host>/...
+    const m = /^[\w*]+:\/\/([^/]+)\//.exec(pat);
+    if (!m)
+        return null;
+    const host = m[1];
+    // A pure `*` host doesn't tell us anything useful for "self".
+    if (host === '*')
+        return null;
+    // `*.example.com` → use `example.com` as the self host.
+    if (host.startsWith('*.'))
+        return host.slice(2);
+    return host;
+}
+export function decideConnect(url, rules, selfHosts, pageOrigin) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { verdict: 'invalid', reason: `${url} is not a valid URL` };
+    }
+    const web = parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    const page = webOrigin(pageOrigin);
+    if (web && page && parsed.origin === page.origin)
+        return { verdict: 'allow' };
+    const host = parsed.hostname.toLowerCase();
+    const selfs = page ? new Set([...selfHosts, page.hostname]) : selfHosts;
+    for (const rule of rules) {
+        // A host-less URL has nothing for a host rule to match, but `*`
+        // means any URL at all.
+        if (!host && rule.kind !== 'wildcard')
+            continue;
+        if (hostMatchesRule(host, rule, selfs))
+            return { verdict: 'allow' };
+    }
+    if (web && host)
+        return { verdict: 'ask', host };
+    return {
+        verdict: 'deny',
+        reason: host
+            ? `Only http(s) sites can be allowed, so only @connect * covers a ${parsed.protocol} URL.`
+            : `A ${parsed.protocol} URL has no host to allow, so only @connect * covers it.`,
+    };
+}
+// The page's origin when it is an http(s) one, else null.
+function webOrigin(origin) {
+    if (!origin)
+        return null;
+    try {
+        const u = new URL(origin);
+        return u.protocol === 'http:' || u.protocol === 'https:' ? u : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Every error `GM_xmlhttpRequest` hands back to a userscript starts
+// here, so the three paths that can fail it — the pre-flight check, the
+// post-redirect re-check (`gm-xhr.ts`), and a policy we couldn't even
+// load (`background.ts`) — read the same way.
+export function gmXhrError(problem) {
+    return `[SourceMonkey] GM_xmlhttpRequest: ${problem}`;
+}
+// The one phrasing for "we could not set the headers you asked for".
+// Says the request was not sent, because the alternative a reader would
+// assume — sent without them — is exactly what we refuse to do: the
+// headers here are the ones the browser won't let a script set, and
+// dropping a `Cookie` override would send the user's own session
+// instead.
+export function headerRuleFailedMessage() {
+    return gmXhrError('The headers this request asked for could not be applied, so it was not sent');
+}
+// The one phrasing for a request the server never started answering.
+// Says "no response headers" rather than "timed out" because the script
+// may have set no timeout at all — this is the worker's own backstop,
+// and a request left waiting forever would hold its header rule and
+// block later requests to the same URL.
+export function headerStallMessage(stallMs) {
+    const minutes = Math.round(stallMs / 60000);
+    const howLong = minutes === 1 ? '1 minute' : `${minutes} minutes`;
+    return gmXhrError(`The server sent no response headers within ${howLong}, so this request was given up on`);
+}
+// For a request the script asked to fail on a redirect
+// (`redirect: 'error'`), which got one.
+export function redirectRefusedMessage() {
+    return gmXhrError('The server redirected the request, and the script asked to fail on a redirect (redirect: "error")');
+}
+// For a request that never got a response: Chrome's `fetch` rejects
+// with a bare "Failed to fetch" for a name that doesn't resolve, a
+// refused or dropped connection, a failed TLS handshake, and a request
+// another extension blocked alike, so the causes are listed rather than
+// one guessed (see TODO.md for telling them apart). The host is the
+// request's own; a redirect `fetch` followed to a dead host lands here
+// too, with nothing to tell us which hop failed, so the message covers
+// a site the host redirected to.
+export function unreachableMessage(host) {
+    return gmXhrError(`Could not reach ${host} or a site it redirected to. The name may not resolve, or the connection was refused, failed or blocked.`);
+}
+// The one phrasing for a request the script's own header forbids: it
+// names whose rules blocked the call rather than a "policy" object the
+// reader can't see. `reason` is a sentence of its own.
+//
+// Only for a real denial. A URL we couldn't parse, or a failure to
+// *evaluate* the rules, is not the header's doing and goes through
+// `gmXhrError` directly.
+export function connectBlockedMessage(reason) {
+    return gmXhrError(`This script's @connect rules don't allow this request. ${reason}`);
+}
+// The one phrasing for a host the user refused this script in the
+// prompt. Says where the refusal can be undone, since it lasts until
+// reset.
+export function connectDeniedMessage(host) {
+    return gmXhrError(`Connecting to ${host} was denied for this script. `
+        + 'Manage permissions on the script\'s page in SourceMonkey.');
+}
+// The one phrasing for a request whose prompt the user cancelled (or
+// closed). Nothing is kept, so the next request asks again, which goes
+// without saying.
+export function connectCancelledMessage(host) {
+    return gmXhrError(`SourceMonkey's permission prompt for connecting to ${host} was cancelled, so this request was blocked`);
+}
+// The one phrasing for a prompt that couldn't be shown. `cause` is
+// Chrome's reason.
+export function connectPromptFailedMessage(host, cause) {
+    // Chrome's reason, capitalized as a tail after `: ` is.
+    const tail = cause.charAt(0).toUpperCase() + cause.slice(1);
+    return gmXhrError(`SourceMonkey could not open its permission prompt for connecting to ${host}: ${tail}`);
+}
+// The one phrasing for a request refused because the script already has
+// as many prompts open as it may (`MAX_PROMPTS_PER_SCRIPT`).
+export function connectTooManyPromptsMessage(host, open) {
+    return gmXhrError(`SourceMonkey is already asking about ${open} other sites for this script, so this request to ${host} was blocked. `
+        + 'Answer those permission prompts, then try again.');
+}
+// The one phrasing for a request whose prompt went unanswered too long.
+// The prompt closes with it, so the next request asks again.
+export function connectUnansweredMessage(host, waitMs) {
+    const minutes = Math.round(waitMs / 60000);
+    const howLong = minutes === 1 ? '1 minute' : `${minutes} minutes`;
+    return gmXhrError(`SourceMonkey's permission prompt for connecting to ${host} had no answer within ${howLong}, `
+        + 'so this request was stopped');
+}

package/lib/gm-xhr-types.d.ts

@@ -0,0 +1,68 @@
+export interface GmXhrRequestPayload {
+    method?: string;
+    url: string;
+    headers?: Record<string, string>;
+    data?: string;
+    body?: GmXhrBody;
+    timeout?: number;
+    responseType?: string;
+    anonymous?: boolean;
+    nocache?: boolean;
+    revalidate?: boolean;
+    redirect?: string;
+}
+export type GmXhrBody = {
+    kind: 'bytes';
+    data: string;
+    type: string;
+} | {
+    kind: 'form';
+    entries: GmXhrFormEntry[];
+} | {
+    kind: 'params';
+    data: string;
+};
+export type GmXhrFormEntry = {
+    name: string;
+    value: string;
+} | {
+    name: string;
+    data: string;
+    filename: string;
+    type: string;
+};
+export interface GmXhrResponse {
+    status: number;
+    statusText: string;
+    responseURL: string;
+    responseText: string;
+    response: unknown;
+    responseMimeType?: string;
+    responseHeaders: string;
+    finalUrl: string;
+}
+export type GmXhrEvent = {
+    kind: 'load';
+    response: GmXhrResponse;
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'timeout';
+} | {
+    kind: 'abort';
+};
+export type GmXhrStreamEvent = {
+    kind: 'headers';
+    status: number;
+    statusText: string;
+    finalUrl: string;
+    responseHeaders: string;
+    mimeType: string;
+    total: number | null;
+} | {
+    kind: 'progress';
+    data: string;
+    loaded: number;
+    total: number | null;
+};

package/lib/gm-xhr-types.js

@@ -0,0 +1,5 @@
+// The `GM_xmlhttpRequest` wire types, between the page and the
+// service worker's handler (gm-xhr.ts). Their own module so the
+// harness, whose request fakes speak them, can use them without the
+// handler.
+export {};

package/lib/harness/browser-extensions.d.ts

@@ -0,0 +1,73 @@
+import { type ManagerName } from './managers.js';
+/** One manager extension in the browser. */
+export interface InstalledManager {
+    manager: ManagerName;
+    /** Its extension id. */
+    id: string;
+    /** As the extension names itself (`Tampermonkey BETA`). */
+    name: string;
+    version: string;
+    enabled: boolean;
+    /** "Allow User Scripts" is on, which a manager needs to run scripts. */
+    userScripts: boolean;
+    /** The folder it was loaded from, when loaded unpacked, as Chrome says. */
+    path?: string;
+    /** Installed from the Chrome Web Store, as Chrome says. */
+    fromStore?: boolean;
+}
+/** Runs JavaScript in a page, and gives back its value. */
+export type Evaluate = <R>(expression: string) => Promise<R>;
+/** A hidden page kept open over its own connection, until `close`. */
+export interface HiddenPage {
+    /** Fails when the page doesn't answer within `timeoutMs`. */
+    evaluate<R>(expression: string, timeoutMs?: number): Promise<R>;
+    close(): Promise<void>;
+}
+/**
+ * Opens a hidden page at `url` in the browser at `endpoint`, once
+ * `ready` (an expression) is true there, for several calls. Throws when
+ * it isn't ready within `timeoutMs`.
+ */
+export declare function openHiddenPage(endpoint: string, url: string, ready: string, timeoutMs?: number): Promise<HiddenPage>;
+/**
+ * The managers installed in the browser at `endpoint`, enabled or not:
+ * SourceMonkey first, then Tampermonkey, then Violentmonkey. Throws when
+ * it can't tell.
+ */
+export declare function installedManagers(endpoint: string, timeoutMs?: number): Promise<InstalledManager[]>;
+/** `installedManagers`, or null when it can't tell, for what only reports. */
+export declare function managersIn(endpoint: string): Promise<InstalledManager[] | null>;
+/** Turns an extension on or off, as its toggle in `chrome://extensions` does. */
+export declare function setExtensionEnabled(endpoint: string, id: string, enabled: boolean): Promise<void>;
+/** Turns on an extension's "Allow User Scripts", as its details page does. */
+export declare function allowUserScripts(endpoint: string, id: string): Promise<void>;
+/**
+ * Loads the unpacked extension in `dir` into the browser, or reloads it
+ * from there when it's loaded already. Returns its id.
+ */
+export declare function loadUnpacked(endpoint: string, dir: string): Promise<string>;
+/**
+ * Warns of each manager enabled beside `chosen`, whose scripts run in
+ * the run's tabs too, with how to turn it off. For a run's first lines,
+ * `status`, and the commands that connect without a run. `browserArg`:
+ * the flags that name the browser in the advice (see `browserArg` in
+ * run.ts).
+ */
+export declare function otherManagersWarning(managers: InstalledManager[], chosen: ManagerName, browserArg?: string): string[];
+/**
+ * The managers in the browser, for `status`: `SourceMonkey 0.0.1 (in
+ * use), Tampermonkey 5.5.1 (disabled)`. Each copy is listed, with what
+ * keeps it from running scripts. `None` when there are none. `mark`:
+ * what the chosen one is, when enabled.
+ */
+export declare function managersText(managers: InstalledManager[], chosen: ManagerName, mark?: string): string;
+/** Whether a manager is in a browser: enabled, there but turned off, or not there. */
+export type ManagerState = 'installed' | 'disabled' | 'absent';
+export declare function managerState(managers: InstalledManager[], name: ManagerName): ManagerState;
+/** How a run's first line says the chosen manager's state: `has Tampermonkey`. */
+export declare function stateLabel(state: ManagerState, name: ManagerName): string;
+/** The browser at `endpoint`: Chrome's version, and whether it's headless. Null when nothing answers. */
+export declare function browserVersion(endpoint: string): Promise<{
+    version: string;
+    headless: boolean;
+} | null>;