sourcemonkey 0.0.0-stage → 0.5.0

package/lib/stack-link.js

@@ -0,0 +1,138 @@
+// Pure helpers used by the userscript viewer to turn stack-trace
+// references into clickable, readable links: `parseStackRefs` finds
+// them, `displayRefText` decides how they read.
+//
+// References look like
+//   sourcemonkey://<scriptId>/<file>:<line>:<col>
+//   https://cdn.example.com/jquery.js?v=3:97:11
+// inside the Log tab's entries into clickable links that jump to
+// the matching code tab.
+//
+// We extract any URL with a recognized scheme followed by `:L:C`.
+// The caller filters by matching the URL against tabs it has open;
+// refs whose URL doesn't match render as plain text. That keeps the
+// parser ignorant of script identity — the same code linkifies both
+// main-body refs (`sourcemonkey://<id>/<name>.user.js`) and
+// `@require` refs (their real CDN URLs, query string and all).
+import { decodeForDisplay } from './script-display.js';
+import { ROOT } from './script-source-url.js';
+import { remapStackRef } from './source-map.js';
+// Find every `<scheme>://…:<line>:<col>` ref in `text` and return
+// runs the caller can paint as text or anchors. Recognized schemes:
+// `sourcemonkey`, `http`, `https`, `file`. The URL portion may
+// contain anything except whitespace and parens (V8's named-frame
+// shape is `at fn (URL:L:C)` — without excluding parens the trailing
+// `)` would greedily attach to the URL).
+//
+// Query strings and fragments work fine — they live in the URL part
+// and only the final `:digits:digits` is split off. Port numbers in
+// the authority are also fine for the same reason: the path comes
+// after the port, so the final `:L:C` is always the line:col.
+//
+// IPv6 hosts in `[…]` brackets would parse OK because the brackets
+// don't contain `:digits:digits` at the end — not currently exercised
+// but worth noting if it ever comes up.
+export function parseStackRefs(text) {
+    if (!text)
+        return [];
+    // Greedy `[^\s()]+` plus `:(\d+):(\d+)` at the end — the engine
+    // backtracks so the FINAL `:digits:digits` becomes line:col even
+    // when the URL contains its own `:digit` runs (port numbers in the
+    // authority, etc.).
+    const re = /(?:sourcemonkey|https?|file):\/\/[^\s()]+:(\d+):(\d+)/g;
+    const runs = [];
+    let lastIndex = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        if (m.index > lastIndex) {
+            runs.push({ kind: 'text', text: text.slice(lastIndex, m.index) });
+        }
+        // Split off the trailing `:line:col` to recover the bare URL.
+        const full = m[0];
+        const line = parseInt(m[1], 10);
+        const col = parseInt(m[2], 10);
+        const url = full.slice(0, full.length - (m[1].length + m[2].length + 2));
+        runs.push({ kind: 'ref', text: full, url, line, col });
+        lastIndex = re.lastIndex;
+    }
+    if (lastIndex < text.length) {
+        runs.push({ kind: 'text', text: text.slice(lastIndex) });
+    }
+    return runs;
+}
+// Text to paint for a ref, as opposed to the URL used to find its tab.
+//
+// `script-source-url.ts` percent-encodes the script's log label into
+// `//# sourceURL=` — a bare `#` would start a fragment and a space or
+// paren would end the run `parseStackRefs` matches — so script 4's
+// `foo.user.js` arrives as `foo%23E4`. Right on the wire, unreadable in
+// the log. Decoding here is the viewer's usual display-decodes /
+// functional-stays-encoded split (docs/names-and-paths.md).
+//
+// **Only our own URLs decode**, and the reason is not that decoding
+// them is unsafe elsewhere — `displayLocation` decodes any absolute
+// URL and accepts the same `%2F`-reads-as-`/` ambiguity. It is that a
+// stack ref is a *coordinate*, not a name: the user compares it
+// against devtools, pastes it into a Sources-panel search, or matches
+// it to a `@require` line, and all of those want the bytes that were
+// actually in the URL. Our own synthetic URLs are the exception
+// because their encoding is an artifact we introduced, not part of any
+// address the user could go look up.
+//
+// Matched against the full `sourcemonkey://SourceMonkey` prefix rather
+// than the scheme: the scheme is unregistered and a hostile script can
+// put `sourcemonkey://elsewhere/…` in its own log message.
+export function displayRefText(text, url) {
+    return url.startsWith(`${ROOT}/`) ? decodeForDisplay(text) : text;
+}
+// Rewrite every ref in `text` (an `Error.stack`, or a console line that
+// carries one) that points into a script's concatenated entry, so it
+// names the `@require` or the script at its own line. For plain-text
+// readers of stacks, such as sm-dev's output; the Log tab maps refs one
+// at a time as it paints them (`resolveLogRef` in userscript.ts).
+//
+// `layouts` are the scripts that may have logged it. A ref stays as it
+// was when it matches none of their entry URLs, or an entry URL that
+// scripts with different layouts share: two `foo.user.js` files run by
+// sm-dev both get `.../foo/foo.user.js`, and mapping with the wrong
+// one's layout would name a confidently wrong file and line.
+//
+// A ref on a line of our own wrap (the head, which holds the GM
+// bindings, a `// @require` marker, a seam, the closing brace) has no
+// original line. Left alone it would read as that line of the user's
+// file, so it is renamed to the script's `__wrapper.js` instead, at
+// the generated line.
+export function remapStackText(text, layouts) {
+    if (!text.includes(`${ROOT}/`))
+        return text;
+    const byUrl = new Map();
+    for (const layout of layouts) {
+        const seen = byUrl.get(layout.entryUrl);
+        if (seen === undefined)
+            byUrl.set(layout.entryUrl, layout);
+        else if (seen && !sameSegments(seen, layout))
+            byUrl.set(layout.entryUrl, null);
+    }
+    return parseStackRefs(text).map((run) => {
+        if (run.kind === 'text')
+            return run.text;
+        const layout = byUrl.get(run.url);
+        if (!layout || layout.segments.length === 0)
+            return run.text;
+        const ref = remapStackRef(run, layout.entryUrl, layout.segments);
+        if (ref)
+            return `${ref.url}:${ref.line}:${ref.col}`;
+        const folder = layout.entryUrl.slice(0, layout.entryUrl.lastIndexOf('/'));
+        return `${folder}/${WRAPPER_FILE}:${run.line}:${run.col}`;
+    }).join('');
+}
+// The name `remapStackText` gives frames on our own wrap's lines.
+export const WRAPPER_FILE = '__wrapper.js';
+// Two copies of one script (sm-dev's `copy`) share a URL and a layout,
+// so they don't make the URL ambiguous.
+function sameSegments(a, b) {
+    return a.segments.length === b.segments.length && a.segments.every((s, i) => {
+        const t = b.segments[i];
+        return s.url === t.url && s.generatedLine === t.generatedLine && s.lineCount === t.lineCount;
+    });
+}

package/lib/unsafe-window-use.d.ts

@@ -0,0 +1 @@
+export declare function sourceUsesUnsafeWindow(bodyText: string | null | undefined): boolean;

package/lib/unsafe-window-use.js

@@ -0,0 +1,229 @@
+// Does a script's own source reference `unsafeWindow` without granting
+// it?
+//
+// `@grant unsafeWindow` is how a script is *supposed* to ask for the
+// page's window, and it is what gets the script the binding. Plenty of
+// real scripts never declare it: `unsafeWindow` is implicitly available under Tampermonkey and
+// Violentmonkey — neither keys it off a grant line, measured under TM
+// 5.5.0 and VM 2.49.0 by `tests/examples/unsafe-window/ungranted.user.js`
+// — so an author who only ever tested there has no reason to add one.
+//
+// Measured over the GreasyFork top 2000: 112 scripts use `unsafeWindow`
+// with no grant for it. Without the binding, the identifier is a
+// `ReferenceError`, so honoring the reference is what makes those
+// scripts run at all.
+//
+// This is a text scan, not a parse. We have no JS parser in the
+// extension (the install-time check compiles with `new Function` in a
+// sandboxed page and reports only a verdict — see docs/parse-check.md),
+// and the answer is needed on the storage row. So:
+//
+//   - Comments and string / template literals are stripped first, so a
+//     mention in a comment or a log message gets no binding. That was
+//     13 of the 126 ungranted mentions in the corpus.
+//   - A property key, a `#private` member and a `foo.unsafeWindow`
+//     access don't count. A false positive only adds an unused
+//     `window` alias.
+//   - A regex literal is NOT recognized. `/['"]/` therefore opens a
+//     string state that runs to the next quote, and a literal ending in
+//     `\/\/` reads as a line comment — either can swallow real code.
+//     Normally that costs a missed reference, so the script gets no
+//     binding. If it swallows a DECLARATION while leaving a use
+//     visible, the script gets a binding it shadows anyway, which is
+//     harmless. No corpus script hits it.
+//   - A script that DECLARES the name — `const unsafeWindow =
+//     window.wrappedJSObject || window;`, a real cross-browser idiom —
+//     answers false, including in a declarator list or a destructuring
+//     pattern. Its references read its own binding, never ours. (Our binding would be
+//     harmless beside it: the user program runs in a nested scope, so
+//     the script's declaration shadows it. See wrapCombinedEntry in
+//     injector.ts.) The check is scope-blind, so a declaration inside a
+//     function suppresses the whole script: that direction only costs
+//     the feature.
+//
+// Only the script's own body is scanned, not its `@require` bodies: the
+// requires arrive on a later pipeline step (`attachFiles`). See
+// TODO.md.
+const IDENT = /[$\w]/;
+// Strip comments and quoted text, leaving a space in their place so
+// adjacent tokens can't merge into a new identifier.
+//
+// Written to jump between interesting positions rather than walk every
+// character: this runs on every script body that mentions the name, at
+// load time, beside the row's SHA-256. On the corpus's largest body
+// (1.8 MB) the per-character form cost ~200 ms, more than 20x that hash.
+function stripQuotedAndComments(src) {
+    // A fresh regex per call — `lastIndex` is state, and this function
+    // recurses into template substitutions.
+    const delim = /\/\/|\/\*|["'`]/g;
+    const parts = [];
+    const n = src.length;
+    let kept = 0;
+    for (let m = delim.exec(src); m !== null; m = delim.exec(src)) {
+        const from = m.index;
+        let after;
+        let replacement = ' ';
+        if (m[0] === '//') {
+            const nl = src.indexOf('\n', from);
+            after = nl === -1 ? n : nl;
+        }
+        else if (m[0] === '/*') {
+            const close = src.indexOf('*/', from + 2);
+            after = close === -1 ? n : close + 2;
+        }
+        else {
+            const quote = m[0];
+            // The code found inside this template's `${ ... }` substitutions.
+            const inner = [];
+            let i = from + 1;
+            while (i < n) {
+                if (src[i] === '\\') {
+                    i += 2;
+                    continue;
+                }
+                if (src[i] === quote) {
+                    i += 1;
+                    break;
+                }
+                // A substitution holds real code, so scan it as code rather
+                // than as text.
+                if (quote === '`' && src[i] === '$' && src[i + 1] === '{') {
+                    let depth = 1;
+                    i += 2;
+                    const innerStart = i;
+                    while (i < n && depth > 0) {
+                        if (src[i] === '{')
+                            depth += 1;
+                        else if (src[i] === '}')
+                            depth -= 1;
+                        i += 1;
+                    }
+                    inner.push(stripQuotedAndComments(src.slice(innerStart, i - 1)));
+                    continue;
+                }
+                i += 1;
+            }
+            after = i;
+            if (inner.length > 0)
+                replacement = ` ${inner.join(' ')} `;
+        }
+        if (from > kept)
+            parts.push(src.slice(kept, from));
+        parts.push(replacement);
+        kept = after;
+        delim.lastIndex = after;
+    }
+    if (n > kept)
+        parts.push(src.slice(kept, n));
+    return parts.join('');
+}
+// A free `unsafeWindow` — not `foo.unsafeWindow`, not `unsafeWindows`,
+// not a member the source happens to have named that.
+function hasFreeReference(code) {
+    let from = 0;
+    for (;;) {
+        const at = code.indexOf('unsafeWindow', from);
+        if (at === -1)
+            return false;
+        from = at + 'unsafeWindow'.length;
+        if (IDENT.test(code[from] ?? ''))
+            continue;
+        // Immediately preceded by an identifier character → the tail of a
+        // longer name (`myunsafeWindow`). Whitespace in between means a
+        // separate token, which `typeof unsafeWindow` needs to pass.
+        if (IDENT.test(code[at - 1] ?? ''))
+            continue;
+        // Walk back over whitespace: `foo\n  .unsafeWindow` is a property,
+        // and `#unsafeWindow` is a private class member.
+        let before = at - 1;
+        while (before >= 0 && /\s/.test(code[before]))
+            before -= 1;
+        if (code[before] === '.' || code[before] === '#')
+            continue;
+        // Followed by `:` → a property key (`{ unsafeWindow: window }`) or a
+        // label, which declares a name rather than reading the page's. This
+        // also skips `cond ? unsafeWindow : other`, and that is the trade we
+        // want: a script using the name in a ternary almost always uses it
+        // somewhere else too, while a key is the whole mention.
+        let next = from;
+        while (next < code.length && /\s/.test(code[next]))
+            next += 1;
+        if (code[next] === ':')
+            continue;
+        return true;
+    }
+}
+// `function unsafeWindow(` / `class unsafeWindow`.
+const DECLARES_AS_CALLABLE = /(?:^|[^$\w.])(?:function|class)\s+unsafeWindow(?![$\w])/;
+const KEYWORD = /(?:^|[^$\w.])(?:var|let|const)(?![$\w])/g;
+// How far past a `var` / `let` / `const` to keep looking for the end of
+// its declarator list. A statement without a `;` (ASI) would otherwise
+// run the scan into the rest of the file; over-running only ever
+// over-suppresses, but there is no reason to pay for it.
+const DECLARATOR_SPAN = 2000;
+// Is `unsafeWindow` a NAME BEING BOUND anywhere in this source, rather
+// than a value being read? A script that binds the name reads its own
+// value, so it gets neither our binding nor the move to MAIN world.
+//
+// Walks each `var` / `let` / `const` declarator list, tracking bracket
+// depth and whether the current declarator has passed its `=`:
+//
+//   const unsafeWindow = window      → bound (before any `=`)
+//   let uw = window, unsafeWindow=uw → bound (the `,` starts a declarator)
+//   const { unsafeWindow } = window  → bound (pattern, before the `=`)
+//   const app = unsafeWindow.thing   → read (after the `=`) — by far the
+//                                      commonest real use, and the one
+//                                      thing this must not claim
+//   const xs = [1, unsafeWindow]     → read (bracketed, after the `=`)
+//
+// Scope-blind on purpose: a declaration inside a function suppresses the
+// whole script. That direction only costs the feature.
+function declaresBinding(code) {
+    if (DECLARES_AS_CALLABLE.test(code))
+        return true;
+    KEYWORD.lastIndex = 0;
+    for (let m = KEYWORD.exec(code); m !== null; m = KEYWORD.exec(code)) {
+        const limit = Math.min(code.length, m.index + DECLARATOR_SPAN);
+        let depth = 0;
+        let afterEquals = false;
+        let i = KEYWORD.lastIndex;
+        while (i < limit) {
+            const c = code[i];
+            if (c === '(' || c === '[' || c === '{')
+                depth += 1;
+            else if (c === ')' || c === ']' || c === '}') {
+                if (depth === 0)
+                    break;
+                depth -= 1;
+            }
+            else if (c === ';' && depth === 0)
+                break;
+            else if (c === ',' && depth === 0)
+                afterEquals = false;
+            else if (c === '=' && code[i + 1] !== '=' && !'=!<>'.includes(code[i - 1] ?? '')) {
+                afterEquals = true;
+            }
+            else if (c === 'u' && code.startsWith('unsafeWindow', i)) {
+                const after = code[i + 'unsafeWindow'.length] ?? '';
+                const prev = code[i - 1] ?? '';
+                if (!IDENT.test(after) && !IDENT.test(prev) && prev !== '.') {
+                    if (!afterEquals)
+                        return true;
+                    i += 'unsafeWindow'.length;
+                    continue;
+                }
+            }
+            i += 1;
+        }
+    }
+    return false;
+}
+export function sourceUsesUnsafeWindow(bodyText) {
+    // The overwhelmingly common answer, without paying for the scan.
+    if (!bodyText || bodyText.indexOf('unsafeWindow') === -1)
+        return false;
+    const code = stripQuotedAndComments(bodyText);
+    if (declaresBinding(code))
+        return false;
+    return hasFreeReference(code);
+}

package/lib/url-match.d.ts

@@ -0,0 +1,40 @@
+export interface UrlMatching {
+    matches: string[];
+    includes: string[];
+    excludes: string[];
+}
+export declare function isPublicSuffix(name: string): boolean;
+export declare function hostEndsInTld(pattern: string): boolean;
+export declare function tldCoarseGlob(pattern: string, isMatch: boolean): string;
+export declare function canonicalMatchPatterns(pattern: string): string[];
+export declare function matchPattern(pattern: string, url: string): boolean;
+export declare const MATCH_SCHEMES: string[];
+export interface MatchPatternProblem {
+    pattern: string;
+    what: string;
+    fix?: string;
+}
+export declare function matchPatternProblem(pattern: string): MatchPatternProblem | null;
+export declare function ignoredMatchMessage(problem: MatchPatternProblem): string;
+export declare function unusableMatchMessage(problem: MatchPatternProblem): string;
+export declare function unusableMatchGroupKey(message: string): string | null;
+export declare function includePattern(pattern: string, url: string): boolean;
+export declare function chromeIncludeGlob(glob: string): string;
+export type PageRegex = [source: string, flags: string];
+export interface PageMatcher {
+    include: PageRegex[];
+    exclude: PageRegex[];
+    tld?: true;
+}
+export declare function pageMatcher(matching: UrlMatching): PageMatcher;
+export declare function urlMatchesScript(url: string, matching: UrlMatching): boolean;
+export interface UrlMatchExplanation {
+    matches: boolean;
+    /** Which header line decided, e.g. `@exclude *://example.com/admin*`. */
+    rule: string | null;
+    /** Every `@match` / `@include` line that covers the URL, excluded or not. */
+    matchedBy: string[];
+    /** Every `@exclude` line that covers it. Any one keeps the script off. */
+    excludedBy: string[];
+}
+export declare function explainUrlMatch(url: string, matching: UrlMatching): UrlMatchExplanation;