@x8r/sapphire 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+<h1 align="center">
+  <img src="sapphire.png" width=500>
+</h1>
+
+A Scramjet plugin that emulates the `chrome.*` extension APIs inside proxied frames, so
+Chrome extensions (Vencord-style userscripts, ad blockers, etc.) can run against sites
+loaded through Scramjet. Originally forked from
+[carbonicality/amethyst](https://github.com/carbonicality/amethyst); this version is a
+full TypeScript rewrite built directly around Scramjet's plugin API instead of a
+standalone postMessage-bridged iframe runtime, and ships no UI of its own — it's a
+library, the host app builds whatever extension-manager UI it wants on top.
+
+## Architecture
+
+- `Sapphire` (`src/sapphire.ts`) — orchestrator owning installed-extension state
+  (IndexedDB-backed), background contexts, and content-script registrations. Create one
+  per app.
+- `SapphireContentScriptPlugin` (`src/SapphirePlugin.ts`) — a Scramjet `ManagedPlugin`.
+  Create one per `Frame` (matching Scramjet's own convention, see
+  `@mercuryworkshop/scramjet-controller`'s `createFrame({ plugins: [...] })`), passing it
+  the shared `Sapphire` instance and that frame's tab id.
+- `chromeApi.ts` — builds a *live* `chrome.*`/`browser.*` object directly on the target
+  realm's real `Window` (obtained from Scramjet's `frame.hooks.init.pre` context). No
+  postMessage bridge: `addListener` captures real function references from that realm, so
+  dispatch is a direct call, not a serialized round-trip. This fixes real bugs the old
+  amethyst design had (e.g. `chrome.runtime.getManifest()` returning `undefined` because
+  it was silently async under the hood) and removes a class of injection-timing races.
+- Background pages/scripts/service-workers all run in one persistent, invisible iframe
+  per extension (not tied to any tab's lifecycle) — a deliberate simplification over
+  spec-faithful Worker-based MV3 semantics; see the doc comment in `background.ts`.
+- `dnr.ts` exports a pure `checkDeclarativeNetRequest()` matcher; it is *not* wired into
+  Scramjet's fetch path (that hook is undocumented/unstable — see project notes), so wire
+  it into your own request routing if you want extension-driven blocking.
+
+## Usage
+
+```ts
+import { Sapphire, SapphireContentScriptPlugin } from "@x8r/sapphire";
+
+const sapphire = new Sapphire({
+  host: {
+    getTabId: (win) => /* map a proxied window back to your tab id */,
+    getTab: (id) => /* { id, windowId, url, title, active } */,
+    getAllTabs: () => /* TabInfo[] */,
+    getTabWindow: (id) => /* live Window for tabs.executeScript/cookies.* */,
+    navigateTab: (id, url) => /* your router */,
+  },
+});
+await sapphire.init(); // loads previously-installed extensions
+
+// per tab, when creating its Scramjet frame:
+controller.createFrame(iframeEl, {
+  plugins: [new SapphireContentScriptPlugin(sapphire, tabId)],
+});
+
+// installing an extension (host owns the file picker / drag-drop UI):
+const extId = await sapphire.installExtension(await file.arrayBuffer(), file.name);
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@x8r/sapphire",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Scramjet plugin that emulates the chrome.* extension APIs inside proxied frames",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.worker.json"
+  },
+  "dependencies": {
+    "@mercuryworkshop/scramjet": "^2.0.67-alpha.1",
+    "jszip": "^3.10.1"
+  },
+  "peerDependencies": {
+    "@mercuryworkshop/scramjet-controller": "^0.0.13"
+  }
+}

package/src/SapphirePlugin.ts

@@ -0,0 +1,23 @@
+import { ManagedPlugin } from "@mercuryworkshop/scramjet-controller";
+import type { Frame } from "@mercuryworkshop/scramjet-controller";
+import { injectContentScripts } from "./contentScripts";
+import type { Sapphire } from "./sapphire";
+
+export class SapphireContentScriptPlugin extends ManagedPlugin {
+  private readonly sapphire: Sapphire;
+  private readonly tabId: number;
+
+  constructor(sapphire: Sapphire, tabId: number) {
+    super("sapphire-content-scripts", []);
+    this.sapphire = sapphire;
+    this.tabId = tabId;
+  }
+
+  install(frame: Frame): void {
+    this.tap(frame.hooks.init.pre, (ctx) => {
+      if (!ctx?.window) return;
+      const url = ctx.window.location.href;
+      void injectContentScripts(ctx.window, this.tabId, url, ctx.isTopLevel, this.sapphire.registry, this.sapphire.host);
+    });
+  }
+}

package/src/autoStub.ts

@@ -0,0 +1,58 @@
+const wrapCache = new WeakMap<object, object>();
+
+export function withMissingMemberFallback<T extends object>(real: T): T {
+  const cached = wrapCache.get(real);
+  if (cached) return cached as T;
+  const proxy = new Proxy(real, {
+    get(target, prop, receiver) {
+      if (prop in target) {
+        const value = Reflect.get(target, prop, receiver);
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+          return withMissingMemberFallback(value as object);
+        }
+        return value;
+      }
+      if (typeof prop !== "string") return undefined;
+      return createAutoStub();
+    },
+  });
+  wrapCache.set(real, proxy);
+  return proxy as T;
+}
+
+function createAutoStub(): unknown {
+  const cache = new Map<string, unknown>();
+  const target = () => {};
+  return new Proxy(target, {
+    get(_t, prop) {
+      if (prop === Symbol.toPrimitive) {
+        return (hint: string) => (hint === "number" ? 0 : "");
+      }
+      if (typeof prop !== "string") return undefined;
+      if (prop === "toJSON") return undefined;
+      if (prop === "valueOf") return () => 0;
+      if (prop === "toString") return () => "";
+      if (prop === "then") {
+        return (resolve?: (v: unknown) => void) => resolve?.(undefined);
+      }
+      const cached = cache.get(prop);
+      if (cached !== undefined) return cached;
+      let value: unknown;
+      if (prop === "addListener" || prop === "removeListener") value = () => {};
+      else if (prop === "hasListener") value = () => false;
+      else value = createAutoStub();
+      cache.set(prop, value);
+      return value;
+    },
+    apply(_t, _thisArg, args) {
+      const cb = args[args.length - 1];
+      if (typeof cb === "function") {
+        try {
+          cb(undefined);
+        } catch {
+        }
+      }
+      return createAutoStub();
+    },
+  });
+}

package/src/background.ts

@@ -0,0 +1,67 @@
+import { installChromeApi } from "./chromeApi";
+import { readExtFileText } from "./fileStore";
+import { bootstrapExtensionFrame, injectScriptFromUrl, rewriteExtHtml, writeDocument } from "./htmlInject";
+import { getBackgroundInfo } from "./manifest";
+import type { ExtensionState, SapphireRegistry } from "./registry";
+import type { SapphireHostBindings } from "./types";
+import { buildExtensionUrl, chromeExtensionUrl } from "./urlScheme";
+
+export function stopBackground(ext: ExtensionState): void {
+  if (ext.background?.kind === "frame") ext.background.frame?.remove();
+  if (ext.background?.kind === "worker") ext.background.worker?.terminate();
+  ext.background = null;
+}
+
+export async function startBackground(
+  ext: ExtensionState,
+  registry: SapphireRegistry,
+  host: SapphireHostBindings,
+  rootEl: HTMLElement,
+): Promise<void> {
+  const bgInfo = getBackgroundInfo(ext.manifest);
+  if (!bgInfo) return;
+  stopBackground(ext);
+
+  const frame = document.createElement("iframe");
+  frame.style.cssText = "position:fixed;width:0;height:0;border:none;opacity:0;pointer-events:none;z-index:-1;";
+  frame.setAttribute("sandbox", "allow-scripts allow-same-origin");
+  frame.setAttribute("aria-hidden", "true");
+  rootEl.appendChild(frame);
+
+  let win: Window;
+  try {
+    win = await bootstrapExtensionFrame(frame, ext.id);
+  } catch (e) {
+    console.error(`[sapphire] failed to bootstrap background frame for ${ext.manifest.name}`, e);
+    frame.remove();
+    return;
+  }
+
+  const backgroundPath = bgInfo.type === "page" ? bgInfo.page : bgInfo.type === "worker" ? bgInfo.script : bgInfo.scripts[0];
+
+  const events = installChromeApi(win, {
+    extId: ext.id,
+    tabId: null,
+    isBackground: true,
+    registry,
+    host,
+    senderUrl: backgroundPath ? chromeExtensionUrl(ext.id, backgroundPath) : undefined,
+  });
+  ext.background = { kind: "frame", frame, events };
+
+  if (bgInfo.type === "page") {
+    const raw = await readExtFileText(ext.id, bgInfo.page);
+    const html = raw !== null ? await rewriteExtHtml(ext.id, raw, bgInfo.page) : "<!DOCTYPE html><html><head></head><body></body></html>";
+    writeDocument(win, html);
+  } else {
+    writeDocument(win, "<!DOCTYPE html><html><head></head><body></body></html>");
+    const scriptPaths = bgInfo.type === "worker" ? [bgInfo.script] : bgInfo.scripts;
+    const isModule = bgInfo.type === "worker" && bgInfo.isModule;
+    for (const path of scriptPaths) {
+      await injectScriptFromUrl(win, buildExtensionUrl(ext.id, path), isModule);
+    }
+  }
+
+  events.runtimeOnInstalled.fire({ reason: "install" });
+  events.runtimeOnStartup.fire();
+}