sourcemonkey 0.0.0-stage → 0.5.0

package/dist/github-auth.js

@@ -0,0 +1,148 @@
+// GitHub personal access token storage + helper for attaching the
+// `Authorization: Bearer <token>` header onto requests that target a
+// GitHub host (so we can fetch private repos and lift the
+// unauthenticated 60/hour rate limit to 5000/hour).
+//
+// Mirrors `debug-log.ts`'s shape: one chrome.storage.local key, a
+// cached in-memory copy, a `load…` for boot-time hydration, and an
+// `install…Listener` for live updates without an SW restart.
+//
+// Hosts we attach the header to:
+//   - api.github.com           (Contents API, repo metadata)
+//   - raw.githubusercontent.com (raw bytes for blob URLs we rewrite to)
+// Any other URL passes through untouched. Sending the header to
+// non-GitHub hosts would leak the token, so the gate is strict.
+//
+// Notable omission: `github.com/<o>/<r>/raw/<ref>/<path>` (the "Raw"
+// button URL). GitHub serves a 302 to raw.githubusercontent.com on
+// that route, and the Fetch spec strips the `Authorization` header
+// on cross-origin redirects — so the auth header would never reach
+// raw, and the github.com hop itself doesn't honour our PAT for the
+// bytes either. `normalizeGithubInput` rewrites `/blob/` and bare-
+// repo URLs to the raw form at add time; users with a `/raw/` URL
+// in hand can paste either the `/blob/` form (auto-rewritten) or the
+// `raw.githubusercontent.com` form directly.
+export const GITHUB_AUTH_TOKEN_KEY = 'githubAuthToken';
+let cachedToken = '';
+export function getGithubAuthToken() {
+    return cachedToken;
+}
+// Test/debug hook. Production callers should toggle the storage key
+// instead so the change persists and is observed via onChanged.
+export function _setGithubAuthTokenForTests(value) {
+    cachedToken = value;
+}
+export async function loadGithubAuthToken() {
+    try {
+        const got = await chrome.storage.local.get(GITHUB_AUTH_TOKEN_KEY);
+        const raw = got[GITHUB_AUTH_TOKEN_KEY];
+        cachedToken = typeof raw === 'string' ? raw : '';
+    }
+    catch {
+        cachedToken = '';
+    }
+}
+// The load, memoized. A service worker that woke up to answer a fetch
+// request has a startup read in flight; a caller that needs the token
+// to be *there* awaits this instead of racing it. Subsequent changes
+// arrive through the onChanged listener below, so one load is enough.
+let loadOnce = null;
+export function ensureGithubAuthTokenLoaded() {
+    if (!loadOnce)
+        loadOnce = loadGithubAuthToken();
+    return loadOnce;
+}
+// The worker's `writeSetting` publishes the token at once, so a refresh
+// it runs next doesn't wait for the change event.
+export function setGithubAuthToken(token) {
+    cachedToken = token;
+}
+export function installGithubAuthListener() {
+    chrome.storage.onChanged.addListener((changes, areaName) => {
+        if (areaName !== 'local')
+            return;
+        const change = changes[GITHUB_AUTH_TOKEN_KEY];
+        if (!change)
+            return;
+        cachedToken = typeof change.newValue === 'string' ? change.newValue : '';
+    });
+}
+// True if the URL targets a GitHub-controlled host we'd want to
+// authenticate against. Pure function — exported for unit tests.
+export function isGithubAuthUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (host === 'api.github.com')
+        return true;
+    if (host === 'raw.githubusercontent.com')
+        return true;
+    // `github.com` itself is intentionally NOT in the gate — the only
+    // bytes-serving route on that host (`/<o>/<r>/raw/...`) 302s to
+    // raw.githubusercontent.com, and the Fetch spec strips
+    // `Authorization` on cross-origin redirects. See the module header.
+    return false;
+}
+// Return the `Authorization` header (and the `X-GitHub-Api-Version`
+// pinning header) for a GitHub URL when a token is set; an empty
+// object otherwise. Safe to spread into a `headers` object that may
+// already carry an `Accept`. Callers should ALWAYS go through this
+// helper rather than reading `cachedToken` directly so the host gate
+// can't be accidentally skipped.
+export function githubAuthHeaders(url) {
+    if (!cachedToken)
+        return {};
+    if (!isGithubAuthUrl(url))
+        return {};
+    return {
+        Authorization: `Bearer ${cachedToken}`,
+        // Pin the REST API version. Optional for the endpoints we hit
+        // today, but cheap insurance against a future shape change.
+        'X-GitHub-Api-Version': '2022-11-28',
+    };
+}
+// True when a request to this URL would actually carry the GitHub
+// auth header (URL is GitHub-eligible AND a token is configured).
+// Same predicate `githubAuthHeaders` uses; exposed so log/UI callers
+// can mirror its decision without re-running the header build.
+export function isGithubAuthInUse(url) {
+    if (!cachedToken)
+        return false;
+    return isGithubAuthUrl(url);
+}
+// True when a *collection URL* (the stored collectionPath, not a
+// per-fetch URL) describes content SourceMonkey reaches through GitHub
+// — covers the github-dir case where `collectionPath` is a
+// `github.com/<o>/<r>/tree/...` page URL but the actual scan + per-
+// script fetches go to api.github.com + raw.githubusercontent.com.
+// Returns true iff a token is configured AND the collection URL is
+// recognisably GitHub. Used by the collection-refresh log line.
+export function isGithubAuthInUseForCollection(collectionPath) {
+    if (!cachedToken)
+        return false;
+    if (isGithubAuthUrl(collectionPath))
+        return true;
+    // github.com page URLs (`/blob/`, `/tree/`, bare repo) aren't
+    // fetched directly — but a github-dir collection resolves to authed
+    // api.github.com + raw.githubusercontent.com calls. Recognise the
+    // github.com host so those collections get the suffix too.
+    try {
+        const host = new URL(collectionPath).hostname.toLowerCase();
+        return host === 'github.com';
+    }
+    catch {
+        return false;
+    }
+}
+// Log-line suffix used by the updater so the SW console makes it
+// obvious when a collection refresh / per-script check is going out
+// authenticated. Empty string when no token would apply, so callers
+// can unconditionally `${label}${githubTokenLogSuffix(url)}`.
+export function githubTokenLogSuffix(url) {
+    return isGithubAuthInUseForCollection(url) ? ' (with GitHub token)' : '';
+}

package/dist/github-urls.js

@@ -0,0 +1,46 @@
+// A GitHub raw URL's page on github.com. Its own module so code that
+// only shows links (match-targets.ts) needn't load the GitHub provider.
+// Reverse of `githubFileUrlToRaw` (github-provider.ts): take a
+// raw-content GitHub URL and return its
+// `github.com/<o>/<r>/blob/<ref>/<path>` counterpart — the
+// page a human would open in a browser. Used wherever the UI surfaces
+// a github URL for clicking (collections-page bubble, viewer Location
+// row): the raw URL is what we fetch from, but the blob URL is what
+// the user wants to see.
+//
+// "Raw" here covers both hosts GitHub serves raw bytes from:
+//   - `raw.githubusercontent.com/<o>/<r>/[refs/<type>/]<ref>/<path>`
+//   - `github.com/<o>/<r>/raw/[refs/<type>/]<ref>/<path>` (the form
+//     produced by github.com's own "Raw" button — it 302s to the
+//     `raw.githubusercontent.com` host but we may store the URL in
+//     this form when the user pastes it directly, or when a manifest
+//     entry resolves to a URL in this shape).
+//
+// The optional `/refs/<type>/` segment is the new-style raw URL.
+// `<type>` is typically `heads` (branch) but can also be `tags` or
+// `pull` — we accept any single segment there so tag URLs map
+// correctly to `blob/<tag>/<path>`. Both stripped shapes resolve to
+// the same content.
+//
+// Limitation shared with github-provider.ts: branch names
+// containing `/` (e.g. `feature/foo`) are not supported — the
+// first ref segment is taken and the rest folded into the path.
+//
+// Returns null for any URL that isn't a recognised raw URL — callers
+// fall back to the original URL.
+//
+// Query strings + fragments get stripped — they don't carry over to
+// the github.com page (a `?token=…` is raw-only; an `#L42` fragment
+// would point at the wrong viewer anchor).
+export function githubRawToBlobUrl(rawUrl) {
+    // Two regexes (rather than one with alternation) because owner/repo
+    // sit at different positions in the two shapes.
+    let m = /^https?:\/\/raw\.githubusercontent\.com\/([^\/]+)\/([^\/]+)\/(?:refs\/[^\/]+\/)?([^\/]+)\/([^?#]+)/i.exec(rawUrl);
+    if (!m) {
+        m = /^https?:\/\/github\.com\/([^\/]+)\/([^\/]+)\/raw\/(?:refs\/[^\/]+\/)?([^\/]+)\/([^?#]+)/i.exec(rawUrl);
+    }
+    if (!m)
+        return null;
+    const [, owner, repo, ref, path] = m;
+    return `https://github.com/${owner}/${repo}/blob/${ref}/${path}`;
+}

package/dist/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;
+}