roxxie-proxy-u-prod 0.1.0

package/source/packages/chrome/src/adblock/AdBlockPlugin.test.ts

@@ -0,0 +1,159 @@
+/* SPDX-License-Identifier: AGPL-3.0-only */
+
+import { Document, Element } from "domhandler";
+import { describe, expect, it, vi } from "vitest";
+
+type HookCallback = (...args: unknown[]) => unknown;
+
+vi.mock("@mercuryworkshop/scramjet/bundled", () => ({
+	Plugin: class {
+		constructor(
+			public name: string,
+			public tapOrder: object = {}
+		) {}
+
+		tap(hook: { callbacks: HookCallback[] }, callback: HookCallback): void {
+			hook.callbacks.push(callback);
+		}
+	},
+	ScramjetHeaders: class {
+		private values = new Map<string, string>();
+
+		set(name: string, value: string): void {
+			this.values.set(name.toLowerCase(), value);
+		}
+
+		get(name: string): string | undefined {
+			return this.values.get(name.toLowerCase());
+		}
+	},
+}));
+
+import { AdBlockPlugin, destinationToRequestType } from "./AdBlockPlugin";
+import type { AdBlockService } from "./AdBlockService";
+
+type TestHook = { callbacks: HookCallback[] };
+
+function createHandler() {
+	const hook = (): TestHook => ({ callbacks: [] });
+	return {
+		hooks: {
+			fetch: { intercept: hook(), request: hook() },
+			rewriter: { html: { post: hook() } },
+		},
+	};
+}
+
+describe("AdBlockPlugin", () => {
+	it("maps browser request destinations to filter-list resource types", () => {
+		expect(destinationToRequestType("document")).toBe("main_frame");
+		expect(destinationToRequestType("script", true)).toBe("sub_frame");
+		expect(destinationToRequestType("audioworklet")).toBe("script");
+		expect(destinationToRequestType("")).toBe("xmlhttprequest");
+	});
+
+	it("short-circuits blocked requests and applies URL rewrites", () => {
+		const matchRequest = vi
+			.fn()
+			.mockReturnValueOnce({ action: "block" })
+			.mockReturnValueOnce({
+				action: "rewrite",
+				url: "https://site.example/article",
+			});
+		const service = {
+			getCosmeticStyles: vi.fn(() => ""),
+			matchRequest,
+		} as unknown as AdBlockService;
+		const handler = createHandler();
+		new AdBlockPlugin(service).install({ fetchHandler: handler as never });
+
+		const blockedRequest = {};
+		const blockedProps: { response?: { status: number } } = {};
+		handler.hooks.fetch.intercept.callbacks[0]!(
+			{
+				request: blockedRequest,
+				parsed: {
+					clientUrl: new URL("https://site.example/"),
+					destination: "script",
+					isIframe: false,
+					url: new URL("https://ads.example/ad.js"),
+				},
+			},
+			blockedProps
+		);
+		expect(blockedProps.response?.status).toBe(200);
+		expect(matchRequest).toHaveBeenNthCalledWith(1, {
+			sourceUrl: "https://site.example/",
+			type: "script",
+			url: "https://ads.example/ad.js",
+		});
+
+		const rewrittenRequest = {};
+		handler.hooks.fetch.intercept.callbacks[0]!(
+			{
+				request: rewrittenRequest,
+				parsed: {
+					destination: "document",
+					isIframe: false,
+					url: new URL("https://site.example/article?utm_source=ad"),
+				},
+			},
+			{}
+		);
+		const requestProps = {
+			url: new URL("https://site.example/article?utm_source=ad"),
+		};
+		handler.hooks.fetch.request.callbacks[0]!(
+			{ request: rewrittenRequest },
+			requestProps
+		);
+		expect(requestProps.url.href).toBe("https://site.example/article");
+	});
+
+	it("injects standard cosmetic CSS into fetched documents", () => {
+		const getCosmeticStyles = vi.fn(() => ".advert{display:none!important}");
+		const service = {
+			getCosmeticStyles,
+			matchRequest: vi.fn(() => ({ action: "allow" })),
+		} as unknown as AdBlockService;
+		const handler = createHandler();
+		new AdBlockPlugin(service).install({ fetchHandler: handler as never });
+
+		const head = new Element("head", {}, []);
+		const body = new Element("body", {}, [
+			new Element("a", {
+				class: "advert card",
+				href: "https://ads.example/",
+				id: "slot",
+			}),
+		]);
+		const root = new Document([new Element("html", {}, [head, body])]);
+		handler.hooks.rewriter.html.post.callbacks[0]!(
+			{
+				handler: { root },
+				htmlcontext: {
+					headers: [],
+					inline: true,
+					loadScripts: true,
+				},
+				meta: { origin: new URL("https://site.example/article") },
+			},
+			{}
+		);
+
+		expect(getCosmeticStyles).toHaveBeenCalledWith(
+			"https://site.example/article",
+			{
+				classes: ["advert", "card"],
+				hrefs: ["https://ads.example/"],
+				ids: ["slot"],
+			}
+		);
+		const link = head.childNodes[0] as Element;
+		expect(link.name).toBe("link");
+		expect(link.attribs["data-roxxie-adblock"]).toBe("");
+		expect(decodeURIComponent(link.attribs.href.split(",")[1]!)).toBe(
+			".advert{display:none!important}"
+		);
+	});
+});

package/source/packages/chrome/src/adblock/AdBlockPlugin.ts

@@ -0,0 +1,232 @@
+/*
+ * Roxxie Proxy U ad-blocking integration.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See NOTICE.md for third-party filtering-engine and list attribution.
+ */
+
+import {
+	Plugin,
+	ScramjetHeaders,
+	type ScramjetFetchHandler,
+	type ScramjetFetchRequest,
+	type ScramjetFetchResponse,
+} from "@mercuryworkshop/scramjet/bundled";
+import { Element, type ChildNode, type ParentNode } from "domhandler";
+import type { RequestType } from "@ghostery/adblocker";
+import { AdBlockService, type CosmeticFeatures } from "./AdBlockService";
+
+const BLOCKED_HEADER = "X-Roxxie-Blocked";
+
+export function destinationToRequestType(
+	destination: RequestDestination,
+	isIframe = false
+): RequestType {
+	if (isIframe || destination === "iframe" || destination === "frame") {
+		return "sub_frame";
+	}
+
+	switch (destination) {
+		case "document":
+			return "main_frame";
+		case "style":
+			return "stylesheet";
+		case "script":
+		case "image":
+		case "font":
+		case "object":
+		case "manifest":
+			return destination;
+		case "audio":
+		case "video":
+		case "track":
+			return "media";
+		case "embed":
+			return "object";
+		case "report":
+			return "csp_report";
+		case "audioworklet":
+		case "paintworklet":
+		case "worker":
+		case "sharedworker":
+			return "script";
+		case "xslt":
+			return "stylesheet";
+		default:
+			return "xmlhttprequest";
+	}
+}
+
+function responseHeaders(contentType: string): ScramjetHeaders {
+	const headers = new ScramjetHeaders();
+	headers.set("Cache-Control", "no-store");
+	headers.set("Content-Type", contentType);
+	headers.set(BLOCKED_HEADER, "1");
+	return headers;
+}
+
+export function createBlockedResponse(
+	destination: RequestDestination,
+	isIframe = false
+): ScramjetFetchResponse {
+	if (destination === "document" && !isIframe) {
+		return {
+			body: "<!doctype html><meta charset=utf-8><title>Blocked</title><p>Blocked by Roxxie Proxy U.</p>",
+			headers: responseHeaders("text/html; charset=utf-8"),
+			status: 403,
+			statusText: "Blocked by Client",
+		};
+	}
+
+	const contentType =
+		destination === "script" || destination.endsWith("worker")
+			? "application/javascript; charset=utf-8"
+			: destination === "style"
+				? "text/css; charset=utf-8"
+				: isIframe || destination === "iframe" || destination === "frame"
+					? "text/html; charset=utf-8"
+					: "text/plain; charset=utf-8";
+
+	return {
+		body: "",
+		headers: responseHeaders(contentType),
+		// Empty executable/frame responses avoid noisy parse errors while still
+		// guaranteeing that no upstream bytes are requested or executed.
+		status:
+			destination === "script" ||
+			destination === "style" ||
+			destination.endsWith("worker") ||
+			isIframe ||
+			destination === "iframe" ||
+			destination === "frame"
+				? 200
+				: 403,
+		statusText: "Blocked by Client",
+	};
+}
+
+function collectCosmeticFeatures(root: ParentNode): CosmeticFeatures {
+	const classes = new Set<string>();
+	const hrefs = new Set<string>();
+	const ids = new Set<string>();
+
+	const visit = (node: ChildNode) => {
+		if ("attribs" in node) {
+			if (node.attribs.id) ids.add(node.attribs.id);
+			if (node.attribs.class) {
+				for (const cls of node.attribs.class.split(/\s+/)) {
+					if (cls) classes.add(cls);
+				}
+			}
+			const href = node.attribs["scramjet-attr-href"] ?? node.attribs.href;
+			if (href) hrefs.add(href);
+		}
+		if ("childNodes" in node) {
+			for (const child of node.childNodes) visit(child);
+		}
+	};
+
+	for (const child of root.childNodes) visit(child);
+	return {
+		classes: [...classes],
+		hrefs: [...hrefs],
+		ids: [...ids],
+	};
+}
+
+function findElement(root: ParentNode, name: string): Element | null {
+	for (const child of root.childNodes) {
+		if (child instanceof Element) {
+			if (child.name === name) return child;
+			const nested = findElement(child, name);
+			if (nested) return nested;
+		}
+	}
+	return null;
+}
+
+function prependChild(parent: ParentNode, child: ChildNode): void {
+	const previous = parent.childNodes[0] ?? null;
+	child.parent = parent;
+	child.prev = null;
+	child.next = previous;
+	if (previous) previous.prev = child;
+	parent.childNodes.unshift(child);
+}
+
+function injectCosmeticStyles(root: ParentNode, styles: string): void {
+	if (!styles) return;
+
+	// A data stylesheet avoids dom-serializer entity-escaping CSS combinators
+	// such as `>` when a Text node is added to a synthetic <style> element.
+	const link = new Element("link", {
+		"data-roxxie-adblock": "",
+		href: `data:text/css;charset=utf-8,${encodeURIComponent(styles)}`,
+		rel: "stylesheet",
+	});
+	const parent = findElement(root, "head") ?? findElement(root, "html") ?? root;
+	prependChild(parent, link);
+}
+
+export class AdBlockPlugin extends Plugin {
+	private readonly rewrites = new WeakMap<ScramjetFetchRequest, string>();
+
+	constructor(private readonly service: AdBlockService) {
+		super("roxxie-adblock", { before: ["scramjet-http-cache"] });
+	}
+
+	install(target: { fetchHandler: ScramjetFetchHandler }): void {
+		const handler = target.fetchHandler;
+
+		this.tap(handler.hooks.fetch.intercept, (context, props) => {
+			const sourceUrl =
+				context.parsed.clientUrl?.href ??
+				context.parsed.referrerSourceUrl?.href ??
+				context.request.rawReferrer ??
+				context.parsed.url.href;
+			const decision = this.service.matchRequest({
+				url: context.parsed.url.href,
+				sourceUrl,
+				type: destinationToRequestType(
+					context.parsed.destination,
+					context.parsed.isIframe
+				),
+			});
+
+			if (decision.action === "redirect") {
+				props.response = {
+					body: decision.body,
+					headers: responseHeaders(decision.contentType),
+					status: 200,
+					statusText: "OK",
+				};
+			} else if (decision.action === "block") {
+				props.response = createBlockedResponse(
+					context.parsed.destination,
+					context.parsed.isIframe
+				);
+			} else if (decision.action === "rewrite") {
+				this.rewrites.set(context.request, decision.url);
+			}
+		});
+
+		this.tap(handler.hooks.fetch.request, (context, props) => {
+			const rewritten = this.rewrites.get(context.request);
+			if (!rewritten) return;
+			this.rewrites.delete(context.request);
+			props.url = new URL(rewritten);
+		});
+
+		this.tap(handler.hooks.rewriter.html.post, (context) => {
+			// Scramjet currently marks network-fetched documents as `inline`, too.
+			// Response headers reliably distinguish those documents from an
+			// innerHTML/document.write fragment.
+			if (!context.htmlcontext.loadScripts || !context.htmlcontext.headers)
+				return;
+			const features = collectCosmeticFeatures(context.handler.root);
+			injectCosmeticStyles(
+				context.handler.root,
+				this.service.getCosmeticStyles(context.meta.origin.href, features)
+			);
+		});
+	}
+}

package/source/packages/chrome/src/adblock/AdBlockService.test.ts

@@ -0,0 +1,148 @@
+/* SPDX-License-Identifier: AGPL-3.0-only */
+
+import { FiltersEngine } from "@ghostery/adblocker";
+import { describe, expect, it } from "vitest";
+import { AdBlockService } from "./AdBlockService";
+
+function createService(filters: string, enabled = () => true): AdBlockService {
+	return new AdBlockService(enabled, FiltersEngine.parse(filters));
+}
+
+describe("AdBlockService", () => {
+	it("blocks matching network and WebSocket requests", () => {
+		const service = createService(`
+			||ads.example^$script
+			||socket.example^$websocket
+		`);
+
+		expect(
+			service.matchRequest({
+				url: "https://ads.example/ad.js",
+				sourceUrl: "https://site.example/",
+				type: "script",
+			})
+		).toEqual({ action: "block" });
+		expect(
+			service.matchWebSocket(
+				"wss://socket.example/events",
+				"https://site.example/"
+			)
+		).toEqual({ action: "block" });
+	});
+
+	it("honors exceptions and the persistent enabled callback", () => {
+		let enabled = true;
+		const service = createService(
+			"||ads.example^\n@@||ads.example/allowed.js$script",
+			() => enabled
+		);
+
+		expect(
+			service.matchRequest({
+				url: "https://ads.example/allowed.js",
+				sourceUrl: "https://site.example/",
+				type: "script",
+			})
+		).toEqual({ action: "allow" });
+
+		enabled = false;
+		expect(
+			service.matchRequest({
+				url: "https://ads.example/blocked.js",
+				sourceUrl: "https://site.example/",
+				type: "script",
+			})
+		).toEqual({ action: "allow" });
+	});
+
+	it("applies URL rewrites without blocking the request", () => {
+		const service = createService("*$removeparam=utm_source");
+		expect(
+			service.matchRequest({
+				url: "https://site.example/?utm_source=ad&article=1",
+				sourceUrl: "https://site.example/",
+				type: "main_frame",
+			})
+		).toEqual({
+			action: "rewrite",
+			url: "https://site.example/?article=1",
+		});
+	});
+
+	it("returns embedded uBlock redirect resources", () => {
+		const engine = FiltersEngine.parse("||ads.example^$script,redirect=noopjs");
+		engine.updateResources(
+			JSON.stringify({
+				redirects: [
+					{
+						aliases: ["noopjs"],
+						body: "stub();",
+						contentType: "application/javascript",
+						name: "noop.js",
+					},
+				],
+				scriptlets: [],
+			}),
+			"test-resources"
+		);
+		const service = new AdBlockService(() => true, engine);
+
+		expect(
+			service.matchRequest({
+				url: "https://ads.example/ad.js",
+				sourceUrl: "https://site.example/",
+				type: "script",
+			})
+		).toEqual({
+			action: "redirect",
+			body: "stub();",
+			contentType: "application/javascript",
+		});
+	});
+
+	it("decodes base64 redirect resources into binary response bodies", () => {
+		const engine = FiltersEngine.parse(
+			"||pixel.example^$image,redirect=transparent"
+		);
+		engine.updateResources(
+			JSON.stringify({
+				redirects: [
+					{
+						aliases: [],
+						body: "AQID",
+						contentType: "application/octet-stream;base64",
+						name: "transparent",
+					},
+				],
+				scriptlets: [],
+			}),
+			"binary-test-resources"
+		);
+		const service = new AdBlockService(() => true, engine);
+		const decision = service.matchRequest({
+			url: "https://pixel.example/pixel.gif",
+			sourceUrl: "https://site.example/",
+			type: "image",
+		});
+
+		expect(decision.action).toBe("redirect");
+		if (decision.action !== "redirect") return;
+		expect(decision.contentType).toBe("application/octet-stream");
+		expect([...new Uint8Array(decision.body as ArrayBuffer)]).toEqual([
+			1, 2, 3,
+		]);
+	});
+
+	it("returns standard cosmetic CSS for matching page features", () => {
+		const service = createService("site.example##.advert\n###global-ad");
+		const styles = service.getCosmeticStyles("https://site.example/page", {
+			classes: ["advert"],
+			hrefs: [],
+			ids: ["global-ad"],
+		});
+
+		expect(styles).toContain(".advert");
+		expect(styles).toContain("#global-ad");
+		expect(styles).toContain("display: none !important");
+	});
+});

package/source/packages/chrome/src/adblock/AdBlockService.ts

@@ -0,0 +1,166 @@
+/*
+ * Roxxie Proxy U ad-blocking integration.
+ * SPDX-License-Identifier: AGPL-3.0-only
+ *
+ * Filtering is provided by @ghostery/adblocker (MPL-2.0), whose parser is
+ * compatible with uBlock Origin and EasyList filter syntax. See NOTICE.md.
+ */
+
+import { FiltersEngine, Request, type RequestType } from "@ghostery/adblocker";
+import * as tldts from "tldts";
+
+export type AdBlockRequest = {
+	url: string;
+	sourceUrl?: string;
+	type: RequestType;
+};
+
+export type AdBlockDecision =
+	| { action: "allow" }
+	| { action: "block" }
+	| { action: "rewrite"; url: string }
+	| {
+			action: "redirect";
+			body: string | ArrayBuffer;
+			contentType: string;
+	  };
+
+export type CosmeticFeatures = {
+	classes: string[];
+	hrefs: string[];
+	ids: string[];
+};
+
+function normalizeRedirectResource(
+	body: string,
+	contentType: string
+): { body: string | ArrayBuffer; contentType: string } {
+	const base64Suffix = ";base64";
+	if (!contentType.toLowerCase().endsWith(base64Suffix)) {
+		return { body, contentType };
+	}
+
+	const binary = atob(body);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) {
+		bytes[index] = binary.charCodeAt(index);
+	}
+	return {
+		body: bytes.buffer,
+		contentType: contentType.slice(0, -base64Suffix.length),
+	};
+}
+
+/**
+ * Owns the immutable, build-generated filtering engine shared by every tab.
+ * Loading failures deliberately fail open so a damaged optional asset cannot
+ * make the browser unusable.
+ */
+export class AdBlockService {
+	private engine: FiltersEngine | null;
+	private loadPromise: Promise<void> | null = null;
+	loadError: Error | null = null;
+
+	constructor(
+		private readonly enabled: () => boolean,
+		engine: FiltersEngine | null = null
+	) {
+		this.engine = engine;
+	}
+
+	get ready(): boolean {
+		return this.engine !== null;
+	}
+
+	async initialize(engineUrl: string): Promise<void> {
+		if (this.engine || this.loadPromise) return this.loadPromise ?? undefined;
+
+		this.loadPromise = (async () => {
+			try {
+				const response = await fetch(engineUrl);
+				if (!response.ok) {
+					throw new Error(
+						`ad-block engine request failed: ${response.status} ${response.statusText}`
+					);
+				}
+				this.engine = FiltersEngine.deserialize(
+					new Uint8Array(await response.arrayBuffer())
+				);
+				this.loadError = null;
+			} catch (error) {
+				this.loadError =
+					error instanceof Error ? error : new Error(String(error));
+				console.error("Roxxie ad blocker failed to initialize", this.loadError);
+			}
+		})();
+
+		return this.loadPromise;
+	}
+
+	private isActive(): boolean {
+		if (!this.engine) return false;
+		try {
+			return this.enabled();
+		} catch {
+			return false;
+		}
+	}
+
+	matchRequest({ url, sourceUrl, type }: AdBlockRequest): AdBlockDecision {
+		if (!this.isActive()) return { action: "allow" };
+
+		try {
+			const result = this.engine!.match(
+				Request.fromRawDetails({
+					url,
+					sourceUrl: sourceUrl || url,
+					type,
+				})
+			);
+
+			if (result.redirect) {
+				return {
+					action: "redirect",
+					...normalizeRedirectResource(
+						result.redirect.body,
+						result.redirect.contentType
+					),
+				};
+			}
+			if (result.match) return { action: "block" };
+			if (result.rewrite?.url) {
+				return { action: "rewrite", url: result.rewrite.url };
+			}
+		} catch (error) {
+			console.warn("Roxxie ad blocker failed open for", url, error);
+		}
+
+		return { action: "allow" };
+	}
+
+	matchWebSocket(url: string, sourceUrl?: string): AdBlockDecision {
+		return this.matchRequest({ url, sourceUrl, type: "websocket" });
+	}
+
+	getCosmeticStyles(url: string, features: CosmeticFeatures): string {
+		if (!this.isActive()) return "";
+
+		try {
+			const parsed = tldts.parse(url);
+			const result = this.engine!.getCosmeticsFilters({
+				url,
+				hostname: parsed.hostname ?? new URL(url).hostname,
+				domain: parsed.domain,
+				...features,
+				// Scriptlets and procedural selectors require a content-script
+				// executor. Standard CSS cosmetics are safe to inject at rewrite time.
+				getInjectionRules: false,
+				getExtendedRules: false,
+			});
+			return result.active ? result.styles : "";
+		} catch (error) {
+			console.warn("Roxxie cosmetic filtering failed open for", url, error);
+			return "";
+		}
+	}
+}