sourcemonkey 0.0.0-stage → 0.5.0

package/dist/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/dist/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/dist/http-read.js

@@ -0,0 +1,142 @@
+// One http(s) read, made where it is safe to make it.
+//
+// ---------- Why this module exists ----------
+//
+// A `fetch()` issued by a DOCUMENT hands that document the response's
+// `Link: <…>; rel=preload; as=script` headers, and Chrome acts on them
+// — it tries to preload the named script into the page that asked. Our
+// pages are extension pages, whose CSP is `script-src 'self'`, so the
+// preload is refused, and Chrome files the refusal under
+// `chrome://extensions/?errors`: an uncatchable error, about a script
+// the page never asked for, that reads as SourceMonkey being broken.
+//
+// Nothing exotic triggers it. Any site that preloads its own bundles
+// sends the header on every page, and we fetch site HTML (the site-icon
+// probe) and arbitrary script URLs (Add / Refresh / the install
+// preview) from pages all the time. A response that turns out to be a
+// login page — the case `fetchHttpText` already has a branch for — is
+// among the most likely of all to carry one.
+//
+// A service worker has no document for a hint to apply to, so the same
+// read there is inert. Hence this module: pages hand the read to the
+// worker and get the response back over `chrome.runtime`. Both
+// directions are pinned by `tests/e2e/preload-hints.spec.ts`.
+//
+// ---------- Shape ----------
+//
+// The worker performs the fetch and reports what came back; every
+// caller keeps its own rules about what the response MEANS (which
+// statuses are failures, which content types are acceptable, how a 304
+// is reported). That split is deliberate: the two callers
+// (`fetchResourceBytes` for bytes, `fetchHttpText` for script and
+// manifest text) disagree about all of it, and a handler that tried to
+// decide for both would have to grow their union.
+//
+// `as: 'text'` decodes in the worker via `Response.text()` rather than
+// shipping bytes for the page to decode, so a response's charset is
+// honoured exactly as it was before the hop existed.
+import { base64ToBytes, bytesToBase64 } from './bytes.js';
+import { isPageContext } from './run-context.js';
+import { ensureGithubAuthTokenLoaded, githubAuthHeaders } from './github-auth.js';
+export const HTTP_READ_MESSAGE = 'sm:http-read';
+// Service-worker side. `background.ts` owns the listener (and the
+// sender check that keeps this from being an open fetch proxy — the
+// extension holds `<all_urls>`).
+export async function handleHttpReadRequest(req) {
+    // The worker may have woken up to answer this, with its startup token
+    // read still in flight — a private GitHub raw URL would 404 on a race
+    // the page-side fetch never had.
+    await ensureGithubAuthTokenLoaded();
+    const headers = { ...(req.headers ?? {}), ...githubAuthHeaders(req.url) };
+    const controller = new AbortController();
+    const timer = req.timeoutMs != null
+        ? setTimeout(() => controller.abort(), req.timeoutMs)
+        : null;
+    let response;
+    try {
+        response = await fetch(req.url, {
+            cache: 'no-store',
+            redirect: 'follow',
+            referrerPolicy: 'no-referrer',
+            signal: controller.signal,
+            headers,
+        });
+    }
+    catch (err) {
+        // Our own timer is the only thing that aborts this request, so an
+        // aborted signal identifies the timeout exactly rather than leaving
+        // it merged with a network failure.
+        return controller.signal.aborted
+            ? { kind: 'error', reason: 'timeout' }
+            : { kind: 'error', reason: 'no-response', message: errorText(err) };
+    }
+    finally {
+        if (timer != null)
+            clearTimeout(timer);
+    }
+    // Size checks are for a body we are about to read. A 304 has none —
+    // its `Content-Length`, where a server sends one at all, describes the
+    // entity that WOULD have been sent. Rejecting on it would fail a
+    // conditional read as "too large" for a file that didn't change, and
+    // only on this leg: the local path tests 304 before any size check, so
+    // the two would disagree about the same response.
+    const contentLength = response.headers.get('content-length');
+    if (response.status !== 304 &&
+        req.maxBytes != null && contentLength && Number(contentLength) > req.maxBytes) {
+        return { kind: 'error', reason: 'oversize' };
+    }
+    const base = {
+        kind: 'response',
+        status: response.status,
+        // Verbatim, not lowercased: callers quote it back as evidence of
+        // what the server actually sent.
+        contentType: response.headers.get('content-type') ?? '',
+        etag: response.headers.get('ETag'),
+        lastModified: response.headers.get('Last-Modified'),
+        finalUrl: response.url || req.url,
+    };
+    try {
+        if (req.as === 'text')
+            return { ...base, text: await response.text() };
+        const body = await response.arrayBuffer();
+        if (req.maxBytes != null && body.byteLength > req.maxBytes) {
+            return { kind: 'error', reason: 'oversize' };
+        }
+        return { ...base, bodyBase64: bytesToBase64(new Uint8Array(body)) };
+    }
+    catch (err) {
+        // The body never finished arriving (connection dropped mid-read).
+        return { kind: 'error', reason: 'no-response', message: errorText(err) };
+    }
+}
+// True when this context must not fetch http(s) itself — i.e. it is a
+// page rather than the service worker.
+export function mustHopToWorker() {
+    return isPageContext();
+}
+// Page side. Returns null — not an error — when the request got no
+// answer at all, so the caller can fall back to fetching locally. That
+// reopens the preload leak for that one read, which beats failing a
+// read the user asked for.
+export async function readHttpViaWorker(req) {
+    let reply;
+    try {
+        reply = await chrome.runtime.sendMessage({
+            type: HTTP_READ_MESSAGE,
+            ...req,
+        });
+    }
+    catch {
+        return null; // no receiving end
+    }
+    return reply ?? null;
+}
+// The bytes of a `kind: 'response'` reply, whichever form it arrived in.
+export function replyBytes(reply) {
+    if (reply.bodyBase64 != null)
+        return base64ToBytes(reply.bodyBase64);
+    return new TextEncoder().encode(reply.text ?? '').buffer;
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}