sourcemonkey 0.0.0-stage → 0.5.0

package/lib/run-context.d.ts

@@ -0,0 +1,2 @@
+export declare function isPageContext(): boolean;
+export declare function assertWorkerContext(what: string): void;

package/lib/run-context.js

@@ -0,0 +1,31 @@
+// Which JS context this module is running in.
+//
+// The extension's modules are shared: `script-store.ts`, `script-log.ts`
+// and the fetch helpers all run in the service worker AND in the
+// extension pages. A few of them have to behave differently in a page —
+// not as a capability check, but because the worker is the single owner
+// of something (an http read that must not leak a preload hint, a
+// session-storage key whose read-modify-writes are serialized by one
+// per-script queue). Those hop to the worker; see `http-read.ts` and
+// `script-log.ts`.
+//
+// `document` is the test: the service worker has none, every extension
+// page does. Not `window` — the worker has a global `self` that some
+// bundlers alias.
+//
+// Caveat for a future caller: the sandboxed parse page
+// (`parse-sandbox.html`) has a `document` too, but runs at an opaque
+// origin with no `chrome.runtime` — so it would answer true here and
+// then have nothing to hop to. Nothing that hops is loaded there today.
+export function isPageContext() {
+    return typeof document !== 'undefined';
+}
+// Only the service worker writes storage and places registrations
+// (docs/worker-writes.md): a page asks it, through
+// `extension/worker-client.ts`. The writers' funnels call this, so a
+// page path that reaches one fails at once rather than writing beside
+// the worker.
+export function assertWorkerContext(what) {
+    if (isPageContext())
+        throw new Error(`Internal error: An extension page tried to ${what} itself`);
+}

package/lib/runtime-messages.d.ts

@@ -0,0 +1,10 @@
+export declare const SM_START_MSG = "sm:start";
+export declare const SM_ERROR_MSG = "sm:error";
+export declare const SM_CHECK_PENDING_MSG = "sm:check-pending";
+export declare const SM_SWAPPED_MSG = "sm:swapped";
+export declare const SM_ABANDONED_MSG = "sm:abandoned";
+export declare const SM_MANUAL_MSG = "sm:manual";
+export declare const SM_GM_LOG_MSG = "sm:gm-log";
+export declare const SM_GM_DOM_BLOCKED_MSG = "sm:gm-dom-blocked";
+export declare const SM_FOCUS_MSG = "sm:focus";
+export declare const SM_MAIN_BLOCKED_MSG = "sm:main-blocked";

package/lib/runtime-messages.js

@@ -0,0 +1,34 @@
+// The `sm:*` message types injected scripts send the service worker.
+// Its own module so the harness can name them without loading the
+// injector.
+// Keep these in sync with the strings the prelude sends.
+export const SM_START_MSG = 'sm:start';
+export const SM_ERROR_MSG = 'sm:error';
+// Reload fast-path: the prelude asks the SW whether to run its baked-in
+// body, abandon, or swap in a fresher user-code body the SW will hand
+// back. sm:swapped / sm:abandoned are the follow-up reports for the
+// swap / skip branches. See docs/injection.md#reload-fast-path.
+export const SM_CHECK_PENDING_MSG = 'sm:check-pending';
+export const SM_SWAPPED_MSG = 'sm:swapped';
+export const SM_ABANDONED_MSG = 'sm:abandoned';
+// Not sent by injected scripts: the worker's report to sm-dev that a
+// manual script (`@run-at context-menu`) matches a new document, where
+// it waits to be run rather than starting. See docs/manual-scripts.md.
+export const SM_MANUAL_MSG = 'sm:manual';
+// GM_log capture: the page-side runtime sends one of these for every
+// GM_log() call so the SW can append it to the script's Log tab.
+export const SM_GM_LOG_MSG = 'sm:gm-log';
+// The runtime saw the page's CSP refuse a style a script added
+// (MAIN world only — the isolated world is exempt). One warning per
+// script per document, in the script's Log.
+export const SM_GM_DOM_BLOCKED_MSG = 'sm:gm-dom-blocked';
+// The page reporting that it just came to the front, so the SW can
+// check this tab's local scripts for edits. Chrome's own focus events
+// miss the case that matters most — see
+// docs/updates.md#focus-triggered-refresh.
+export const SM_FOCUS_MSG = 'sm:focus';
+// The bridge reporting a sandboxed document where no MAIN-world script
+// could run, so the SW runs them in USER_SCRIPT world instead. Sent by
+// the bridge itself, never relayed for the page. See
+// `runBlockedMainScripts` in background.ts.
+export const SM_MAIN_BLOCKED_MSG = 'sm:main-blocked';

package/lib/sandboxed-page.d.ts

@@ -0,0 +1,5 @@
+export declare const INJECT_INTO_CONTENT_FIX = "Add @inject-into content to run a script in the isolated context instead, unless it needs the page's own variables";
+export declare const SANDBOX_BLOCKS_PAGE_CONTEXT = "A sandboxed page stops scripts running in the page's own context";
+export declare function cspBlocksPageScripts(header: string): boolean;
+export declare function sandboxedPageNote(scripts: readonly string[]): string;
+export declare function sandboxedPageWarning(scripts: readonly string[]): string;

package/lib/sandboxed-page.js

@@ -0,0 +1,35 @@
+// A page whose CSP `sandbox` turns off script in its own world, so
+// Chrome skips MAIN-world scripts there. The Log warning
+// (missing-scripts.ts) and sm-dev's warning share these words. Its own
+// module so sm-dev can use them without the badge code.
+// The fix for such a page.
+export const INJECT_INTO_CONTENT_FIX = 'Add @inject-into content to run a script in the isolated context instead, unless it needs the page\'s own variables';
+// What a sandboxed page does to scripts in its own context.
+export const SANDBOX_BLOCKS_PAGE_CONTEXT = 'A sandboxed page stops scripts running in the page\'s own context';
+// Whether a Content-Security-Policy header value sandboxes the page
+// without `allow-scripts`. Several headers arrive comma-joined, one
+// policy each, and any one of them can sandbox. For sm-dev, which sees
+// the response; the extension only sees what its wrappers report.
+export function cspBlocksPageScripts(header) {
+    for (const policy of header.split(',')) {
+        for (const directive of policy.split(';')) {
+            const [name, ...tokens] = directive.trim().toLowerCase().split(/\s+/);
+            if (name === 'sandbox' && !tokens.includes('allow-scripts'))
+                return true;
+        }
+    }
+    return false;
+}
+// sm-dev's note for such a page under a SourceMonkey that runs the
+// run's MAIN-world scripts there isolated instead, naming them.
+export function sandboxedPageNote(scripts) {
+    return 'This page\'s Content-Security-Policy header sandboxes it without allow-scripts, ' +
+        `so SourceMonkey runs these scripts in the isolated context instead: ${scripts.join(', ')}.`;
+}
+// sm-dev's warning for such a page, naming the run's MAIN-world scripts
+// that match it, under a manager that doesn't run them there.
+export function sandboxedPageWarning(scripts) {
+    return 'This page\'s Content-Security-Policy header sandboxes it without allow-scripts. ' +
+        `${SANDBOX_BLOCKS_PAGE_CONTEXT}, so these scripts can't run here: ` +
+        `${scripts.join(', ')}. ${INJECT_INTO_CONTENT_FIX}.`;
+}

package/lib/script-build.d.ts

@@ -0,0 +1,111 @@
+import { type ParsedHeader } from './userscript-header.js';
+import { type FileFetchCache, type IconCheck, type PushedFile, type StoredRequire, type StoredResource } from './external-files.js';
+import { type LocalFileScope } from './local-file-overrides.js';
+import type { VersionProbe } from './version-probe.js';
+import type { ParseVerdict } from './parse-check-protocol.js';
+import { type DiagnosticLocation } from './diagnostic-location.js';
+export type ScriptStatus = 'ok' | 'invalid';
+export interface ScriptMatching {
+    matches: string[];
+    excludes: string[];
+    includes: string[];
+}
+export interface StartupLog {
+    level: 'log' | 'info' | 'warn' | 'error';
+    message: string;
+    location?: DiagnosticLocation;
+}
+export interface StoredScript {
+    id: string;
+    collectionId: string;
+    relativePath: string;
+    fileUrl: string;
+    status: ScriptStatus;
+    errorMessage?: string;
+    errorLocation?: DiagnosticLocation;
+    refreshError?: string;
+    size: number | null;
+    contentHash?: string;
+    parseCheckedHash?: string;
+    fsMtime?: number;
+    httpEtag?: string;
+    httpLastModified?: string;
+    leadingText?: string;
+    headerText: string;
+    bodyText: string;
+    header: ParsedHeader | null;
+    matching: ScriptMatching;
+    loadedAt: number;
+    enabled: boolean;
+    requires?: StoredRequire[];
+    resources?: StoredResource[];
+    iconCheck?: IconCheck;
+    startupLogs?: readonly StartupLog[];
+    usesUnsafeWindow?: boolean;
+    versionProbes?: VersionProbe[];
+}
+export type ScriptMeta = Omit<StoredScript, 'bodyText' | 'requires' | 'resources'> & {
+    requires?: Omit<StoredRequire, 'source'>[];
+    resources?: Omit<StoredResource, 'bytesBase64'>[];
+};
+export type FetchResult = {
+    ok: true;
+    text: string;
+    httpEtag?: string;
+    httpLastModified?: string;
+} | {
+    ok: false;
+    errorMessage: string;
+} | {
+    unchanged: true;
+};
+export declare function hashSource(text: string): Promise<string>;
+export declare function distillMatching(header: ParsedHeader | null): ScriptMatching;
+export declare function isolatedUnsafeWindowWarning(cause: string): string;
+export declare function noConnectInfo(grant: string): string;
+export declare function isManualScript(script: Pick<StoredScript, 'header'>): boolean;
+export declare function unsupportedRunAtWarning(value: string): string;
+export declare function extractStartupLogs(header: ParsedHeader | null, relativePath: string, usesUnsafeWindow?: boolean): StartupLog[];
+export interface HeaderProblem {
+    message: string;
+    line?: number;
+}
+export declare const NO_NAME = "No @name in the metadata block";
+export declare const NO_MATCH_OR_INCLUDE = "No @match or @include in the metadata block, so this script would never run on any page";
+export declare const RETIRED_CONTEXT_MENU_UNSUPPORTED = "@run-at context-menu (run from the right-click menu) is not supported, so this script can't run";
+export declare const SYNTAX_ERROR_PREFIX = "Syntax error: ";
+export declare function validateHeader(header: ParsedHeader | null): HeaderProblem | null;
+interface BuildArgs {
+    id: string;
+    collectionId: string;
+    relativePath: string;
+    fileUrl: string;
+    text: string;
+    now: number;
+    prior?: StoredScript;
+    httpEtag?: string;
+    httpLastModified?: string;
+}
+export declare function buildScriptFromText(args: BuildArgs): Promise<StoredScript>;
+export declare function applyFetchError(existing: StoredScript, errorMessage: string): StoredScript;
+export declare function setScriptError(entry: Pick<StoredScript, 'errorMessage' | 'errorLocation'>, message: string | undefined, location: DiagnosticLocation | undefined): void;
+export declare function locationIn(file: string, line: number | undefined): DiagnosticLocation;
+export declare function buildInitialInvalidEntry(args: {
+    id: string;
+    collectionId: string;
+    relativePath: string;
+    fileUrl: string;
+    errorMessage: string;
+    now: number;
+}): StoredScript;
+export declare function applyFiles(built: StoredScript, prior: StoredScript | undefined, recheck: 'all' | 'preserve', fetchCache: FileFetchCache, now: number, localFiles?: LocalFileScope, parseCheck?: ParseCheckMode, pushedFiles?: Record<string, PushedFile>): Promise<StoredScript>;
+export declare function rederivedStartupLogs(script: Pick<StoredScript, 'iconCheck' | 'header' | 'relativePath'>, usesUnsafeWindow: boolean): StartupLog[];
+export type ParseChecker = (script: StoredScript) => Promise<ParseVerdict | null>;
+export type ParseCheckMode = 'await' | 'defer';
+export declare let parseChecker: ParseChecker | null;
+export declare function setParseChecker(fn: ParseChecker | null): void;
+export declare function parseCheckKey(script: StoredScript): string;
+export declare function applyParseCheck(built: StoredScript, prior: StoredScript | undefined, mode?: ParseCheckMode): Promise<StoredScript>;
+export declare function applyVerdictFields(current: StoredScript, checked: StoredScript): StoredScript;
+export declare function describeError(err: unknown): string;
+export {};