@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/host/dotli/src/interception.js

@@ -0,0 +1,115 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { decideRequest, decideWebSocket } from "./routing.js";
+export const FORCE_RPC_BACKEND = `try { localStorage.setItem("dotli:chain-backend", "rpc-gateway"); } catch { /* storage may be blocked; the request interceptor still enforces local routes */ }`;
+export async function installDotliInterception(context, table, options = {}) {
+    const t0 = Date.now();
+    const events = [];
+    const frames = {};
+    const record = (event) => {
+        const full = { ...event, at: Date.now() - t0 };
+        events.push(full);
+        if (full.decision === "deny")
+            options.onDeny?.(full);
+    };
+    const closePageSocket = (ws, url, decision, close) => ws.close(close).catch((error) => {
+        events.push({ at: Date.now() - t0, kind: "websocket", url, decision, detail: `closing the page's socket failed: ${error instanceof Error ? error.message : String(error)}` });
+    });
+    const fallbackTimeoutMs = options.publicFallbackTimeoutMs ?? 60_000;
+    await context.addInitScript({ content: FORCE_RPC_BACKEND });
+    await context.routeWebSocket(() => true, (ws) => {
+        const url = ws.url();
+        const decision = decideWebSocket(table, url);
+        if (decision.action === "bridge-websocket") {
+            record({ kind: "websocket", url, decision: decision.action, detail: `${decision.chain} → ${decision.target}` });
+            const counts = (frames[decision.chain] ??= { toLocal: 0, toPage: 0 });
+            const local = new WebSocket(decision.target);
+            local.binaryType = "arraybuffer";
+            const buffered = [];
+            local.onopen = () => {
+                for (const message of buffered)
+                    local.send(message);
+                buffered.length = 0;
+            };
+            local.onmessage = (event) => {
+                counts.toPage++;
+                ws.send(typeof event.data === "string" ? event.data : Buffer.from(event.data));
+            };
+            local.onclose = (event) => void closePageSocket(ws, url, decision.action, { code: event.code === 1000 ? 1000 : 4000, reason: event.reason });
+            ws.onMessage((message) => {
+                counts.toLocal++;
+                if (local.readyState === WebSocket.OPEN)
+                    local.send(message);
+                else
+                    buffered.push(message);
+            });
+            ws.onClose(() => local.close());
+            return;
+        }
+        if (decision.action === "allow") {
+            record({ kind: "websocket", url, decision: decision.action, detail: decision.reason });
+            ws.connectToServer();
+            return;
+        }
+        record({ kind: "websocket", url, decision: "deny", detail: decision.action === "deny" ? decision.reason : decision.action });
+        void closePageSocket(ws, url, "deny", { code: 4403, reason: "denied by product-lab" });
+    });
+    await context.route("**/*", async (route) => {
+        const request = route.request();
+        const url = request.url();
+        const decision = decideRequest(table, url);
+        if (decision.action === "allow") {
+            record({ kind: "http", url, decision: decision.action, detail: decision.reason });
+            return route.continue();
+        }
+        if (decision.action === "serve-content" && options.content && decision.format === "car" && decision.path === "/") {
+            try {
+                const result = await options.content.archive(decision.cid);
+                record({ kind: "http", url, decision: decision.action, detail: `CAR ${result.blocks} blocks, ${result.bytes} bytes, ${result.verified} verified` });
+                return route.fulfill({
+                    status: 200,
+                    headers: { "content-type": "application/vnd.ipld.car", "access-control-allow-origin": "*" },
+                    body: Buffer.from(result.car),
+                });
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                if (options.publicContentFallback) {
+                    try {
+                        const signal = AbortSignal.timeout(fallbackTimeoutMs);
+                        const response = await fetch(url, { headers: { accept: "application/vnd.ipld.car" }, signal });
+                        if (!response.ok)
+                            throw new Error(`public gateway HTTP ${response.status}`);
+                        const car = new Uint8Array(await response.arrayBuffer());
+                        const result = await options.content.reverify(decision.cid, car);
+                        record({
+                            kind: "http", url, decision: decision.action, publicContact: true,
+                            detail: `local failed (${reason}); public gateway CAR re-verified: ${result.blocks} blocks, ${result.bytes} bytes, ${result.verified} sha2-256 verified, ${result.unverified} unverified`,
+                        });
+                        return route.fulfill({
+                            status: 200,
+                            headers: { "content-type": "application/vnd.ipld.car", "access-control-allow-origin": "*" },
+                            body: Buffer.from(result.car),
+                        });
+                    }
+                    catch (fallbackError) {
+                        record({ kind: "http", url, decision: "deny", publicContact: true, detail: `local failed (${reason}); public fallback failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}` });
+                        return route.fulfill({ status: 502, body: "content unavailable" });
+                    }
+                }
+                record({ kind: "http", url, decision: "deny", detail: `local content failed: ${reason}` });
+                return route.fulfill({ status: 502, body: "local content unavailable" });
+            }
+        }
+        const detail = decision.action === "deny" ? decision.reason : `no local handler for ${decision.action} ${decision.action === "serve-content" ? decision.format : ""}`;
+        record({ kind: "http", url, decision: "deny", detail: `${request.method()} ${request.resourceType()}: ${detail}` });
+        return route.abort("blockedbyclient");
+    });
+    return {
+        events,
+        frames,
+        denied: () => events.filter((event) => event.decision === "deny"),
+        bridged: () => events.filter((event) => event.decision === "bridge-websocket"),
+        served: () => events.filter((event) => event.decision === "serve-content"),
+    };
+}

package/adapters/host/dotli/src/page-console.d.ts

@@ -0,0 +1,40 @@
+import type { BrowserTab } from "@parity/product-lab/ports/browser";
+export interface DotliConsoleEntry {
+    /** When the message arrived (Unix ms). */
+    readonly at: number;
+    /** The browser's type (`log`, `warning`, `error`, …), or `pageerror` for an uncaught script error. */
+    readonly type: string;
+    /** The message, redacted. */
+    readonly text: string;
+}
+export interface DotliConsoleRecord {
+    /** False when the browser reports no console: nothing was seen, which is not nothing printed. */
+    readonly watched: boolean;
+    /** What the record cannot contain. */
+    readonly gaps: readonly string[];
+    readonly messages: readonly DotliConsoleEntry[];
+    /** Messages past `limit`, counted and not kept. */
+    readonly dropped: number;
+}
+/**
+ * dot.li's own diagnostics: every line under one of its `[dot.li <part>]` prefixes (protocol, perf, provider, broker,
+ * truapi-chain, …; the parts changed between builds), its init failures, and truAPI's own `[truapi…]` lines (a wire
+ * mismatch shows there first).
+ */
+export declare const DOTLI_DIAGNOSTIC: RegExp;
+/** The messages among `record`'s that are dot.li's diagnostics (`DOTLI_DIAGNOSTIC`). */
+export declare function dotliDiagnostics(record: DotliConsoleRecord): DotliConsoleEntry[];
+/** The adapter's own redaction: a value written after a secret-named key (`mnemonic: …`, `"seed":"…"`). */
+export declare function scrubConsoleText(text: string): string;
+/**
+ * Keep `tab`'s console messages and script errors from now on, each text through `scrubConsoleText` and then `redact`.
+ * `stop()` detaches; the record stays readable.
+ */
+export declare function watchDotliConsole(tab: Pick<BrowserTab, "onConsole" | "onPageError">, options?: {
+    redact?: (text: string) => string;
+    limit?: number;
+    now?: () => number;
+}): {
+    readonly record: DotliConsoleRecord;
+    stop(): void;
+};

package/adapters/host/dotli/src/page-console.js

@@ -0,0 +1,44 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const DOTLI_DIAGNOSTIC = /\[dot\.li(?: [a-z-]+)?\]|init-failed|\[truapi[a-z -]*\]/;
+export function dotliDiagnostics(record) {
+    return record.messages.filter((message) => DOTLI_DIAGNOSTIC.test(message.text));
+}
+const SECRET_FIELD = /\b(mnemonic|seed|secret|private[_ -]?key|password|passphrase|token|suri|phrase|entropy)(["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;}]+)/gi;
+export function scrubConsoleText(text) {
+    return text.replace(SECRET_FIELD, (_match, key, separator) => `${key}${separator}[redacted]`);
+}
+const SHARED_WORKER_GAP = "dot.li's SharedWorker prints to its own console, which the page's does not include";
+export function watchDotliConsole(tab, options = {}) {
+    const redact = (text) => (options.redact ? options.redact(scrubConsoleText(text)) : scrubConsoleText(text));
+    const limit = options.limit ?? 5_000;
+    const now = options.now ?? Date.now;
+    const messages = [];
+    let dropped = 0;
+    const keep = (message) => {
+        if (messages.length >= limit)
+            dropped++;
+        else
+            messages.push({ at: message.at, type: message.type, text: redact(message.text) });
+    };
+    const stops = [
+        ...(tab.onConsole ? [tab.onConsole(keep)] : []),
+        ...(tab.onPageError ? [tab.onPageError((text) => keep({ type: "pageerror", text, at: now() }))] : []),
+    ];
+    const watched = !!tab.onConsole;
+    const gaps = watched ? [SHARED_WORKER_GAP] : ["This browser reports no page console", SHARED_WORKER_GAP];
+    return {
+        record: {
+            watched,
+            gaps,
+            messages,
+            get dropped() {
+                return dropped;
+            },
+        },
+        stop() {
+            for (const stop of stops.splice(0))
+                stop();
+        },
+    };
+}

package/adapters/host/dotli/src/routing.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Interception table for running the dot.li browser host against a local fork.
+ *
+ * The fork keeps the public genesis hashes, so a transaction signed for the fork is
+ * also valid on the public network. Every request is therefore decided explicitly:
+ * known public chain endpoints are bridged to the local nodes, the public IPFS
+ * gateway is answered from local Bulletin, the dot.li origins are allowed, and
+ * everything else is denied and recorded.
+ *
+ * Endpoints below were read from dot.li `packages/config/src/network.ts`
+ * (dotli-community d91104b) and observed in the spike
+ * (docs/verification/2026-09-24-spike-browser.md).
+ */
+import { HostNetworkRoutes, NetworkPolicy, type NetworkException } from "@parity/product-lab/domain";
+export type ChainRole = "people" | "asset-hub" | "bulletin" | "relay";
+export interface LocalEndpoints {
+    people: string;
+    assetHub: string;
+    bulletin: string;
+    /** Optional: the fork's relay RPC. Unset means relay connections are denied. */
+    relay?: string;
+}
+/**
+ * The interception table's local endpoints from the domain's routing (refactor
+ * step 7 part b): People, Asset Hub and Bulletin are required, the relay is
+ * bridged when routed (else relay connections are denied).
+ */
+export declare function localEndpoints(routes: HostNetworkRoutes): LocalEndpoints;
+export interface DotliNetworkEndpoints {
+    /** dot.li network name, e.g. "paseo-next-v2" */
+    network: string;
+    /** DotNS TLD for this network, e.g. "paseo" */
+    tld: string;
+    chains: Record<ChainRole, readonly string[]>;
+    /**
+     * The genesis hash dot.li compiles in for each chain. It serves a product no other chain: its provider returns none
+     * for a genesis the network does not define ("Unsupported chain"), so a chain made from scratch is never served,
+     * while a fork of the network keeps these hashes (dotli-community packages/config/src/network.ts and
+     * packages/resolver/src/provider.ts, d91104b).
+     */
+    genesis: Readonly<Record<ChainRole, string>>;
+    ipfsGateways: readonly string[];
+}
+/** Public endpoints compiled into dot.li for paseo-next-v2. */
+export declare const paseoNextV2: DotliNetworkEndpoints;
+/** A routed chain dot.li will not serve: its genesis is not the one dot.li compiles in for that chain. */
+export interface UnservedChain {
+    role: ChainRole;
+    genesis: string;
+    served: string;
+}
+/**
+ * The chains among `roles` that `routes` gives a genesis dot.li does not serve (`DotliNetworkEndpoints.genesis`).
+ * `roles`: the chains the caller relies on (a chain routed to a closed port on purpose carries a placeholder genesis).
+ * A route without a genesis is not judged.
+ */
+export declare function unservedChains(routes: HostNetworkRoutes, roles: readonly ChainRole[], network?: DotliNetworkEndpoints): UnservedChain[];
+/** Why dot.li cannot run on these chains, in words, with what to use instead. */
+export declare function unservedReason(unserved: readonly UnservedChain[], network?: DotliNetworkEndpoints): string;
+export interface InterceptionTable {
+    network: DotliNetworkEndpoints;
+    local: LocalEndpoints;
+    /** Origins the dot.li build is served from, e.g. http://*.localhost:15100 (hostname suffix + port). */
+    hostOrigins: {
+        hostnameSuffix: string;
+        port: number;
+    }[];
+    /** Extra local origins that may be contacted directly (e.g. a local gateway). */
+    allowOrigins: readonly string[];
+    /**
+     * The domain's deny-by-default policy (`NetworkPolicy`): the environment's
+     * routes, the dot.li build origins and `allowOrigins` as app origins, and any
+     * declared exceptions. Everything the table does not translate (bridged
+     * public chain endpoints, the public IPFS gateway) is decided by it.
+     */
+    policy: NetworkPolicy;
+}
+export type Decision = {
+    action: "allow";
+    reason: string;
+} | {
+    action: "bridge-websocket";
+    chain: ChainRole;
+    target: string;
+} | {
+    action: "serve-content";
+    cid: string;
+    format: "car" | "raw" | "file";
+    path: string;
+} | {
+    action: "deny";
+    reason: string;
+};
+/**
+ * Build the table. `routes` (the environment's `HostNetworkRoutes`) names the
+ * local endpoints; `local` alone is accepted for callers without a routing and
+ * becomes one (network and namespace from `network`).
+ */
+export declare function createInterceptionTable(options: {
+    network?: DotliNetworkEndpoints;
+    routes?: HostNetworkRoutes;
+    local?: LocalEndpoints;
+    hostPort: number;
+    hostnameSuffix?: string;
+    allowOrigins?: readonly string[];
+    /** Origins off this machine the page may reach, each with its recorded reason. */
+    exceptions?: readonly NetworkException[];
+}): InterceptionTable;
+/** Loopback (the domain's `LoopbackUrl`), plus `*.localhost` names, which serve the dot.li build here. */
+export declare function isLoopback(url: string): boolean;
+/** Decide a WebSocket connection. */
+export declare function decideWebSocket(table: InterceptionTable, url: string): Decision;
+/** Decide an HTTP(S) request. */
+export declare function decideRequest(table: InterceptionTable, url: string): Decision;
+/** Chromium --host-resolver-rules value that makes every public hostname unresolvable
+ * (the domain policy's `hostResolverRules()`; pass the table to keep its exceptions
+ * resolvable). Backstop for traffic Playwright routing cannot see (shared workers,
+ * dedicated workers' sockets). */
+export declare function hostResolverBackstop(table?: InterceptionTable): string;

package/adapters/host/dotli/src/routing.js

@@ -0,0 +1,157 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { HostNetworkRoutes, LoopbackUrl, NetworkPolicy } from "@parity/product-lab/domain";
+export function localEndpoints(routes) {
+    const needed = "The dot.li interception table";
+    return {
+        people: routes.chain("people", needed).ws,
+        assetHub: routes.chain("asset-hub", needed).ws,
+        bulletin: routes.chain("bulletin", needed).ws,
+        ...(routes.chains.relay ? { relay: routes.chains.relay.ws } : {}),
+    };
+}
+export const paseoNextV2 = {
+    network: "paseo-next-v2",
+    tld: "paseo",
+    chains: {
+        people: ["wss://paseo-people-next-system-rpc.polkadot.io"],
+        "asset-hub": ["wss://paseo-asset-hub-next-rpc.polkadot.io"],
+        bulletin: ["wss://paseo-bulletin-next-rpc.polkadot.io"],
+        relay: [
+            "wss://paseo-rpc.n.dwellir.com",
+            "wss://paseo.dotters.network",
+            "wss://paseo.ibp.network",
+            "wss://paseo.rpc.amforc.com",
+        ],
+    },
+    genesis: {
+        people: "0x4a2b5b737de1da59e209b0000a876ec2fa20035dc34fd292a848da32d255ad48",
+        "asset-hub": "0x4349b00e54897e21196fd331015fc5be0f14e118beb0375ed2bb1793737bb57a",
+        bulletin: "0x8cfe6717dc4becfda2e13c488a1e2061ff2dfee96e7d031157f72d36716c0a22",
+        relay: "0x374057be67b355151f271ff70c3db98308c62c8adc48dc6724b6a009a1a014fd",
+    },
+    ipfsGateways: ["https://paseo-bulletin-next-ipfs.polkadot.io"],
+};
+export function unservedChains(routes, roles, network = paseoNextV2) {
+    return roles.flatMap((role) => {
+        const genesis = routes.chains[role]?.genesis;
+        const served = network.genesis[role];
+        return genesis && genesis.toLowerCase() !== served.toLowerCase() ? [{ role, genesis, served }] : [];
+    });
+}
+export function unservedReason(unserved, network = paseoNextV2) {
+    const chains = unserved.map((chain) => `${chain.role} here has genesis ${chain.genesis.slice(0, 10)}…, ${network.network}'s is ${chain.served.slice(0, 10)}…`).join("; ");
+    return `dot.li serves only ${network.network}'s own chains (it compares each with the genesis compiled into its build, and a chain made from scratch has its own): ${chains}. Run it on a copy of the network, whose fork keeps those hashes (a lab's Paseo copy), not on a chain made from scratch`;
+}
+export function createInterceptionTable(options) {
+    const network = options.network ?? paseoNextV2;
+    if (!options.routes === !options.local)
+        throw new Error("Give the interception table either routes or local endpoints");
+    for (const [role, url] of Object.entries(options.local ?? {})) {
+        if (url !== undefined && !isLoopback(url))
+            throw new Error(`Local ${role} endpoint must be loopback: ${url}`);
+    }
+    for (const origin of options.allowOrigins ?? []) {
+        if (!isLoopback(origin))
+            throw new Error(`Allowed origin must be loopback: ${origin}`);
+    }
+    const routes = options.routes ?? routesFor(network, options.local);
+    const hostnameSuffix = options.hostnameSuffix ?? "localhost";
+    const allowOrigins = options.allowOrigins ?? [];
+    const policy = NetworkPolicy.from({
+        routes,
+        appOrigins: [`http://*.${hostnameSuffix}:${options.hostPort}`, ...allowOrigins.map((origin) => new URL(origin).origin)],
+        ...(options.exceptions ? { exceptions: options.exceptions } : {}),
+    });
+    return {
+        network,
+        local: options.local ?? localEndpoints(routes),
+        hostOrigins: [{ hostnameSuffix, port: options.hostPort }],
+        allowOrigins,
+        policy,
+    };
+}
+function routesFor(network, local) {
+    return HostNetworkRoutes.from({
+        network: network.network,
+        namespace: network.tld,
+        chains: {
+            people: { ws: local.people },
+            "asset-hub": { ws: local.assetHub },
+            bulletin: { ws: local.bulletin },
+            ...(local.relay ? { relay: { ws: local.relay } } : {}),
+        },
+    });
+}
+export function isLoopback(url) {
+    if (LoopbackUrl.test(url))
+        return true;
+    try {
+        return new URL(url).hostname.endsWith(".localhost");
+    }
+    catch {
+        return false;
+    }
+}
+function sameEndpoint(requested, configured) {
+    const target = new URL(configured);
+    const strip = (path) => path.replace(/\/+$/, "");
+    return (requested.protocol === target.protocol &&
+        requested.host === target.host &&
+        strip(requested.pathname) === strip(target.pathname));
+}
+const localFor = (table, chain) => chain === "people" ? table.local.people
+    : chain === "asset-hub" ? table.local.assetHub
+        : chain === "bulletin" ? table.local.bulletin
+            : table.local.relay;
+export function decideWebSocket(table, url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { action: "deny", reason: `unparseable WebSocket URL ${url}` };
+    }
+    for (const [chain, endpoints] of Object.entries(table.network.chains)) {
+        if (!endpoints.some((endpoint) => sameEndpoint(parsed, endpoint)))
+            continue;
+        const target = localFor(table, chain);
+        if (!target)
+            return { action: "deny", reason: `${chain} endpoint ${url} has no local mapping` };
+        return { action: "bridge-websocket", chain, target };
+    }
+    return byPolicy(table, url, "websocket");
+}
+function byPolicy(table, url, kind) {
+    const decision = table.policy.decide(url, kind);
+    return decision.verdict === "allow" ? { action: "allow", reason: decision.reason } : { action: "deny", reason: decision.reason };
+}
+const CID_PATTERN = /^[A-Za-z0-9]{10,}$/;
+export function decideRequest(table, url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { action: "deny", reason: `unparseable URL ${url}` };
+    }
+    for (const gateway of table.network.ipfsGateways) {
+        const base = new URL(gateway);
+        if (parsed.origin !== base.origin)
+            continue;
+        const match = /^\/ipfs\/([^/?#]+)(\/[^?#]*)?$/.exec(parsed.pathname);
+        if (!match || !CID_PATTERN.test(match[1]))
+            return { action: "deny", reason: `unsupported gateway path ${parsed.pathname}` };
+        const format = parsed.searchParams.get("format");
+        return {
+            action: "serve-content",
+            cid: match[1],
+            path: match[2] ?? "/",
+            format: format === "car" ? "car" : format === "raw" ? "raw" : "file",
+        };
+    }
+    return byPolicy(table, url, "http");
+}
+export function hostResolverBackstop(table) {
+    return table ? table.policy.hostResolverRules() : NetworkPolicy.hostResolverRules();
+}