@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/host/truapi-cli/src/cli-identity.js

@@ -0,0 +1,31 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { mnemonicToEntropy } from "@polkadot-labs/hdkd-helpers";
+import { assertBip39Entropy } from "@parity/product-lab/domain";
+export function readTruapiCliIdentity(options) {
+    const networkDir = join(options.basePath, "v2", options.network);
+    const session = options.session ??
+        readFileSync(join(networkDir, "signing-host", "current-session"), "utf8").trim();
+    if (!/^[a-z0-9]+(?:\.[a-z0-9]+)*$/.test(session)) {
+        throw new Error(`invalid truAPI CLI session name ${JSON.stringify(session)}`);
+    }
+    const store = JSON.parse(readFileSync(join(networkDir, `${session}_signing_host`, "accounts.json"), "utf8"));
+    if (store.version !== 1)
+        throw new Error(`unsupported CLI account store version ${store.version}`);
+    const record = store.accounts.find((entry) => entry.network === options.network && entry.lite_username === session);
+    if (!record)
+        throw new Error(`no account for session ${session} on ${options.network}`);
+    if (!record.attested || !/\.\d+$/.test(record.lite_username)) {
+        throw new Error(`account ${record.name} is not an attested lite person yet`);
+    }
+    const entropy = mnemonicToEntropy(record.mnemonic.trim().normalize("NFKD"));
+    assertBip39Entropy(entropy);
+    return {
+        entropy,
+        liteUsername: record.lite_username,
+        identityAddress: record.address,
+        source: `truapi-cli:${options.basePath}`,
+    };
+}

package/adapters/host/truapi-cli/src/cli-session.d.ts

@@ -0,0 +1,12 @@
+import { type ProvisionedIdentity } from "@parity/product-lab/domain";
+import type { HostActor, HostApp, SessionApprovals } from "@parity/product-lab/ports/host";
+import { type HostRuntime } from "./host-process.js";
+import type { CliHostSession } from "./host-types.js";
+/** Start a session's host process and open its app (createSession, after its checks). */
+export declare function openCliSession(runtime: HostRuntime, actor: HostActor, app: HostApp, identity: ProvisionedIdentity, approvals: SessionApprovals, path: string | undefined, 
+/** Backlog 31: the identity's conditions will be set (HostSessionRequest.conditions): open its links. */
+conditions?: boolean): Promise<CliHostSession>;
+/** The identity swap of a running session (importIdentity), or undefined for a session this module did not open. */
+export declare function hostOf(session: CliHostSession): {
+    swap(identity: ProvisionedIdentity): Promise<void>;
+} | undefined;

package/adapters/host/truapi-cli/src/cli-session.js

@@ -0,0 +1,245 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { UnsupportedHostOperation, appUrl, appUrlAt, NetworkPolicy } from "@parity/product-lab/domain";
+import { createNetworkLog, gateBlocks } from "./network-guard.js";
+import { watchNavigations } from "./navigation.js";
+import { decideNext, pendingDecisions } from "./host-requests.js";
+import { scriptAccountRead } from "./script-account-read.js";
+import { sharedState, signerMnemonic, startHostProcess } from "./host-process.js";
+import { openConditionedRouting, sessionConditions } from "./conditioned-routing.js";
+import { watchHostLink } from "./host-link.js";
+import { readSigningEvidence } from "./signing-evidence.js";
+export async function openCliSession(runtime, actor, app, identity, approvals, path, 
+conditions = false) {
+    const runDir = join(runtime.options.stateRoot, "actors", actor.id, "apps", app.id, "runs", new Date().toISOString().replace(/[:.]/g, "-"));
+    const linked = conditions && runtime.conditionedLinks && runtime.routes ? await openConditionedRouting(runtime.conditionedLinks, runtime.routes, runtime.allocate) : undefined;
+    let running;
+    try {
+        running = await startHostProcess(runtime, actor, app, identity, approvals, runDir, linked?.routes);
+    }
+    catch (error) {
+        await linked?.close().catch((cleanup) => {
+            throw new AggregateError([error, cleanup], `The session did not start (${error instanceof Error ? error.message : String(error)}), and its links did not close`);
+        });
+        throw error;
+    }
+    const logs = [running.log];
+    const bridgeUrls = new Set();
+    const recordBridge = () => { bridgeUrls.add(`http://127.0.0.1:${running.port}/bootstrap.js`); bridgeUrls.add(`ws://127.0.0.1:${running.port}/`); };
+    recordBridge();
+    let signedInAs = identity;
+    const abort = new AbortController();
+    let page;
+    let link;
+    let pageConditions;
+    const currentUrl = () => appUrl(app, { hostBridgeUrl: `http://127.0.0.1:${running.port}/bootstrap.js` });
+    const appOrigin = new URL(appUrl(app, { hostBridgeUrl: null })).origin;
+    const localLinks = () => [appOrigin, `http://127.0.0.1:${running.port}`];
+    const evidence = {
+        host: "truapi-cli",
+        version: runtime.resolved()?.version ?? "unknown",
+        sha256: runtime.resolved()?.sha256 ?? "unknown",
+        origin: runtime.acquired()?.origin ?? "unpinned",
+        label: runtime.acquired()?.label ?? "unknown",
+        archiveSha256: runtime.acquired()?.archiveSha256 ?? null,
+        attestation: runtime.acquired()?.attestation ?? { status: "none", reason: "not resolved" },
+        patches: runtime.acquired()?.patches ?? runtime.patches,
+        coverage: "faithful",
+        routing: runtime.publicNetwork ? "public" : "local-network",
+        dataDir: running.dataDir,
+        runDir,
+        hostPort: running.port,
+        pid: running.pid,
+        identity: running.fingerprint,
+        approvals,
+        startMs: running.startMs,
+        ...(runtime.productConfigs().length ? { productConfigs: runtime.productConfigs() } : {}),
+        ...(runtime.options.actorStateRoot ? { sharedState: sharedState(actor.id, running.dataDir) } : {}),
+        ...(runtime.denyByDefaultNetwork
+            ? {
+                network: {
+                    browserLayer: "reported (NetworkPolicy; session.network.blocked())",
+                    nativeProcessLayer: runtime.options.system.sandbox.mechanism ?? "denied by the platform's process sandbox (loopback outbound only), not reported",
+                },
+            }
+            : {}),
+    };
+    const stopHost = async () => {
+        try {
+            await running.stop();
+        }
+        finally {
+            running.release();
+        }
+    };
+    let context;
+    const networkLog = runtime.denyByDefaultNetwork ? createNetworkLog() : undefined;
+    try {
+        if (networkLog) {
+            context = await runtime.options.browser.newContext();
+            const policy = NetworkPolicy.from({
+                routes: runtime.lab,
+                appOrigins: [new URL(currentUrl()).origin, `http://127.0.0.1:${running.port}`],
+                exceptions: runtime.options.networkExceptions ?? [],
+                hostOnlyRoutes: true,
+            });
+            await networkLog.apply(context, policy);
+            page = await context.newPage();
+        }
+        else {
+            page = await runtime.options.browser.newPage();
+        }
+        link = watchHostLink(page);
+        if (linked)
+            pageConditions = page.conditions?.(localLinks);
+        await page.goto(path ? appUrlAt(currentUrl(), path) : currentUrl(), { timeout: runtime.readyTimeoutMs });
+    }
+    catch (error) {
+        await page?.close().catch(() => undefined);
+        await context?.close().catch(() => undefined);
+        await linked?.close().catch(() => undefined);
+        await stopHost().catch((cleanup) => {
+            throw new AggregateError([error, cleanup], `The session did not start (${error instanceof Error ? error.message : String(error)}), and its host did not stop`);
+        });
+        throw error;
+    }
+    let stopped = false;
+    const decisions = () => {
+        const file = join(runDir, "approvals.log");
+        return existsSync(file) ? readFileSync(file, "utf8").split("\n").filter(Boolean) : [];
+    };
+    const session = {
+        actor,
+        app,
+        approvalPolicy: approvals,
+        evidence,
+        logs: () => logs.map((path, index) => ({ label: index ? `truapi-host-${index + 1}` : "truapi-host", path })),
+        async networkEvidence() {
+            if (!page?.networkEvidence)
+                return { observations: [], coverage: { beforeNavigation: false, pages: false, workers: false, gaps: ["This browser provides no passive app network observation"] } };
+            const observed = await page.networkEvidence();
+            const observations = observed.observations.map((item) => bridgeUrls.has(item.endpoint) ? { ...item, purpose: "host-bridge" } : item);
+            return { ...observed, observations, coverage: { ...observed.coverage, gaps: observed.coverage.gaps.filter((gap) => ![...bridgeUrls].some((url) => gap.startsWith(`${url}: `))) } };
+        },
+        async page() {
+            return page;
+        },
+        async account(index = 0, query = {}) {
+            const missing = [];
+            if (!query.source || query.source === "identity") {
+                const derivation = runtime.options.accounts;
+                if (derivation)
+                    return { ...derivation.productAccount(signedInAs.entropy, app.productId, index), productId: app.productId, derivationIndex: index, source: "identity" };
+                missing.push("no product-account derivation was given to this host (deps.accounts; the composition root supplies one)");
+            }
+            if (!query.source || query.source === "host") {
+                const binary = runtime.acquired()?.binary;
+                if (!binary)
+                    throw new Error("call prepare() before reading the product account from the host");
+                const read = await scriptAccountRead({
+                    hostBin: binary,
+                    basePath: running.hostState,
+                    network: runtime.lab.network,
+                    productId: app.productId,
+                    index,
+                    signer: { mnemonic: signerMnemonic(signedInAs) },
+                    ...(running.routingFile ? { routingFile: running.routingFile } : {}),
+                    runDir,
+                    commands: runtime.options.system.commands,
+                    ...(runtime.denyByDefaultNetwork && running.routes ? { sandbox: { sandbox: runtime.options.system.sandbox, routes: running.routes } } : {}),
+                    timeoutMs: runtime.readyTimeoutMs,
+                    signal: abort.signal,
+                });
+                return { ...read, source: "host" };
+            }
+            if (query.source === "app")
+                missing.push("this host adapter takes no reader of the app's page");
+            throw new UnsupportedHostOperation("truapi-cli", "Telling the product account", missing.join("; "));
+        },
+        ...(runtime.options.accounts?.resourceAccounts
+            ? { resourceAccounts: async () => runtime.options.accounts.resourceAccounts(signedInAs.entropy, app.productId).map(({ publicKey, resource }) => ({ account: publicKey, resource, ...(resource === "bulletin" ? { signs: true } : {}) })) }
+            : {}),
+        ...(link ? { connection: () => link.connection(running.port) } : {}),
+        localLinks,
+        ...(linked && pageConditions ? { conditions: sessionConditions(linked, pageConditions) } : {}),
+        approvals: {
+            async approve() {
+                if (approvals === "per-request")
+                    return decideNext(running.decisionsDir, true, { timeoutMs: runtime.pendingTimeoutMs, signal: abort.signal });
+                if (approvals !== "approve-all")
+                    throw new UnsupportedHostOperation("truapi-cli", "Approving one request in a deny-all session", "approvals are one policy per host process");
+            },
+            async deny() {
+                if (approvals === "per-request")
+                    return decideNext(running.decisionsDir, false, { timeoutMs: runtime.pendingTimeoutMs, signal: abort.signal });
+                if (approvals !== "deny-all")
+                    throw new UnsupportedHostOperation("truapi-cli", "Denying one request", "approvals are one policy per host process (--auto-accept or none); create the session per-request (request-decisions patch)");
+            },
+            async pending() {
+                return approvals === "per-request" ? pendingDecisions(running.decisionsDir) : [];
+            },
+            async decisions() {
+                return decisions();
+            },
+            async signing() {
+                return readSigningEvidence(join(runDir, "approvals.log"), join(runDir, "signatures.jsonl"), runDir, (runtime.acquired()?.patches ?? runtime.patches).includes("signature-evidence"));
+            },
+        },
+        ...(runtime.capabilities.navigationEvents
+            ? {
+                navigations: {
+                    [Symbol.asyncIterator]: () => watchNavigations(join(runDir, "navigations.jsonl"), { signal: abort.signal })[Symbol.asyncIterator](),
+                },
+            }
+            : {}),
+        ...(networkLog
+            ? { network: { blocked: async () => [...(await networkLog.blocked()), ...gateBlocks(runtime.gated(), [new URL(currentUrl()).origin], networkLog.startedAt)] } }
+            : {}),
+        async open(target) {
+            link?.renew();
+            await page.goto(appUrlAt(currentUrl(), target), { timeout: runtime.readyTimeoutMs });
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            runtime.sessions.delete(session);
+            abort.abort();
+            const errors = [];
+            await page.close().catch((error) => errors.push(error));
+            await context?.close().catch((error) => errors.push(error));
+            await stopHost().catch((error) => errors.push(error));
+            await linked?.close().catch((error) => errors.push(error));
+            if (errors.length)
+                throw new AggregateError(errors, `Stopping ${actor.id}/${app.id} failed`);
+        },
+    };
+    hosts.set(session, {
+        swap: async (identity) => {
+            const started = performance.now();
+            await stopHost();
+            running = await startHostProcess(runtime, actor, app, identity, approvals, runDir, linked?.routes);
+            if (!logs.includes(running.log))
+                logs.push(running.log);
+            recordBridge();
+            signedInAs = identity;
+            evidence.dataDir = running.dataDir;
+            if (evidence.sharedState)
+                evidence.sharedState = sharedState(actor.id, running.dataDir);
+            evidence.hostPort = running.port;
+            evidence.pid = running.pid;
+            evidence.identity = running.fingerprint;
+            link?.renew();
+            await page.goto(currentUrl(), { timeout: runtime.readyTimeoutMs });
+            evidence.importMs = Math.round(performance.now() - started);
+        },
+    });
+    runtime.sessions.add(session);
+    return session;
+}
+export function hostOf(session) {
+    return hosts.get(session);
+}
+const hosts = new WeakMap();

package/adapters/host/truapi-cli/src/conditioned-routing.d.ts

@@ -0,0 +1,17 @@
+import { type NetworkCondition } from "@parity/product-lab/domain/conditions";
+import type { ConditionControl } from "@parity/product-lab/ports/browser";
+import type { ConditionedLinks } from "@parity/product-lab/ports/system";
+import type { TruapiCliNetworkConfig } from "./network-config.js";
+export interface ConditionedRouting {
+    /** The routing file the session's host is given: every endpoint names its link. */
+    readonly routes: TruapiCliNetworkConfig;
+    network(condition: NetworkCondition): void;
+    close(): Promise<void>;
+}
+/** Open one link per endpoint of `routes`; on a failure the links already open are closed. */
+export declare function openConditionedRouting(links: ConditionedLinks, routes: TruapiCliNetworkConfig, reserve: () => Promise<number>): Promise<ConditionedRouting>;
+/**
+ * The session's conditions: the network on its links and on its page (the app's own requests outside its link to the
+ * host), the CPU on its page. The native host's own work runs at full speed: a slower device slows the app's page.
+ */
+export declare function sessionConditions(routing: ConditionedRouting, page: ConditionControl): ConditionControl;

package/adapters/host/truapi-cli/src/conditioned-routing.js

@@ -0,0 +1,48 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ONLINE } from "@parity/product-lab/domain/conditions";
+export async function openConditionedRouting(links, routes, reserve) {
+    const opened = [];
+    const close = async () => {
+        const results = await Promise.allSettled(opened.map((link) => link.close()));
+        const failed = results.flatMap((result) => (result.status === "rejected" ? [result.reason] : []));
+        if (failed.length)
+            throw new AggregateError(failed, "Closing the session's conditioned links failed");
+    };
+    const through = async (target) => {
+        const link = await links.open({ port: await reserve(), target });
+        opened.push(link);
+        return link.url;
+    };
+    try {
+        const chain = async (route) => ({ ...route, ws: await through(route.ws) });
+        const linked = {
+            ...routes,
+            identity_backend_base: await through(routes.identity_backend_base),
+            people: await chain(routes.people),
+            asset_hub: await chain(routes.asset_hub),
+            bulletin: await chain(routes.bulletin),
+        };
+        return { routes: linked, network: (condition) => opened.forEach((link) => link.network(condition)), close };
+    }
+    catch (error) {
+        await close().catch((cleanup) => {
+            throw new AggregateError([error, cleanup], `The session's conditioned links did not open (${error instanceof Error ? error.message : String(error)}), and some did not close`);
+        });
+        throw error;
+    }
+}
+export function sessionConditions(routing, page) {
+    return {
+        ...(page.unavailable ? { unavailable: page.unavailable } : {}),
+        async network(condition) {
+            routing.network(condition);
+            await page.network(condition);
+        },
+        cpu: (slowdown) => page.cpu(slowdown),
+        async reset() {
+            routing.network(ONLINE);
+            await page.reset();
+        },
+    };
+}

package/adapters/host/truapi-cli/src/host-cache.d.ts

@@ -0,0 +1,25 @@
+import type { CommandRunner } from "@parity/product-lab/ports/system";
+import type { AcquiredRecord, AcquiredTruapiHost } from "./host-records.js";
+/** The published archive target for this machine (host-rust-core's installer mapping). */
+export declare function hostTarget(platform?: string, arch?: string): string;
+export declare function cacheRoot(env?: NodeJS.ProcessEnv): string;
+export declare function hostsCacheDir(cacheDir?: string): string;
+/** An exclusive cache-entry lock (a directory), so two runs never install one label at once. */
+export declare function withLock<T>(dir: string, action: () => Promise<T>): Promise<T>;
+export declare function readRecord(dir: string): AcquiredRecord | undefined;
+export declare function fromRecord(dir: string, record: AcquiredRecord, cached: boolean): AcquiredTruapiHost;
+/**
+ * Install a verified archive into the cache as `label` (atomic: extracted to a
+ * temporary directory, checked, then renamed into place).
+ */
+export declare function installArchive(options: {
+    cacheDir: string;
+    dirName: string;
+    archivePath: string;
+    record: Omit<AcquiredRecord, "binary" | "versionOutput" | "acquiredAt" | "schemaVersion">;
+    expectVersion: string;
+    commands: CommandRunner;
+    signal?: AbortSignal;
+}): Promise<AcquiredTruapiHost>;
+/** Every cached host with its provenance record (for `product-lab host fetch --list`). */
+export declare function listCachedHosts(cacheDir?: string): AcquiredRecord[];

package/adapters/host/truapi-cli/src/host-cache.js

@@ -0,0 +1,131 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { randomBytes } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { sha256File, extract, versionOf } from "./host-verification.js";
+import { insideProductLabCheckout, PRODUCT_WASM_INSTEAD } from "./checkout.js";
+const TARGETS = {
+    "darwin arm64": "aarch64-apple-darwin",
+    "linux x64": "x86_64-unknown-linux-musl",
+    "linux arm64": "aarch64-unknown-linux-musl",
+};
+export function hostTarget(platform = process.platform, arch = process.arch) {
+    const target = TARGETS[`${platform} ${arch}`];
+    if (!target)
+        throw new Error(insideProductLabCheckout()
+            ? `No published truapi-host archive for ${platform} ${arch}. Build it from source: ` +
+                "product-lab host build --patches local-network --target <rust target triple> " +
+                "(needs Rust; see adapters/host/truapi-cli/README.md)"
+            : `No published truapi-host archive for ${platform} ${arch}, so the truAPI CLI host does not run on this machine in a product. ${PRODUCT_WASM_INSTEAD}`);
+    return target;
+}
+export function cacheRoot(env = process.env) {
+    if (env.PRODUCT_LAB_CACHE_DIR) {
+        if (!isAbsolute(env.PRODUCT_LAB_CACHE_DIR))
+            throw new Error("PRODUCT_LAB_CACHE_DIR must be absolute");
+        return env.PRODUCT_LAB_CACHE_DIR;
+    }
+    return join(env.XDG_CACHE_HOME && isAbsolute(env.XDG_CACHE_HOME) ? env.XDG_CACHE_HOME : join(homedir(), ".cache"), "product-lab");
+}
+export function hostsCacheDir(cacheDir = cacheRoot()) {
+    return join(cacheDir, "hosts", "truapi-cli");
+}
+export async function withLock(dir, action) {
+    const lock = `${dir}.lock`;
+    mkdirSync(dirname(lock), { recursive: true, mode: 0o700 });
+    for (let attempt = 0;; attempt++) {
+        try {
+            mkdirSync(lock);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const age = Date.now() - (existsSync(lock) ? statSync(lock).mtimeMs : Date.now());
+            if (age > 10 * 60_000) {
+                rmSync(lock, { recursive: true, force: true });
+                continue;
+            }
+            if (attempt > 600)
+                throw new Error(`Timed out waiting for ${lock}`);
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+    }
+    try {
+        return await action();
+    }
+    finally {
+        rmSync(lock, { recursive: true, force: true });
+    }
+}
+export function readRecord(dir) {
+    const file = join(dir, "acquired.json");
+    if (!existsSync(file))
+        return undefined;
+    return JSON.parse(readFileSync(file, "utf8"));
+}
+export function fromRecord(dir, record, cached) {
+    const binary = join(dir, record.binary.path);
+    const actual = sha256File(binary);
+    if (actual !== record.binary.sha256)
+        throw new Error(`Cached ${record.label} was modified: ${binary} has sha256 ${actual}, recorded ${record.binary.sha256}. Delete ${dir} and fetch again.`);
+    return {
+        binary,
+        label: record.label,
+        origin: record.origin,
+        version: record.version,
+        target: record.target,
+        archiveSha256: record.archive.sha256,
+        binarySha256: record.binary.sha256,
+        patches: record.patches,
+        patchset: record.patchset ?? null,
+        attestation: record.attestation,
+        dir,
+        cached,
+        source: record.archive.url ?? (record.build ? `local build (${join(dir, "acquired.json")})` : dir),
+    };
+}
+export async function installArchive(options) {
+    const root = hostsCacheDir(options.cacheDir);
+    const dir = join(root, options.dirName);
+    const staging = join(root, `.staging-${options.dirName}-${randomBytes(4).toString("hex")}`);
+    mkdirSync(join(staging, "archive"), { recursive: true, mode: 0o755 });
+    try {
+        const archiveCopy = join(staging, "archive", options.record.archive.name);
+        copyFileSync(options.archivePath, archiveCopy);
+        if (sha256File(archiveCopy) !== options.record.archive.sha256)
+            throw new Error("The archive changed while it was installed");
+        const binary = await extract(archiveCopy, join(staging, "bin"), options.commands, options.signal);
+        const versionOutput = await versionOf(binary, options.commands, options.signal);
+        if (versionOutput !== `truapi-host ${options.expectVersion}`)
+            throw new Error(`The archive's binary reports "${versionOutput}", expected "truapi-host ${options.expectVersion}"`);
+        const record = {
+            schemaVersion: 1,
+            ...options.record,
+            binary: { path: "bin/truapi-host", sha256: sha256File(binary) },
+            versionOutput,
+            acquiredAt: new Date().toISOString(),
+        };
+        writeFileSync(join(staging, "acquired.json"), JSON.stringify(record, null, 2) + "\n", { mode: 0o644 });
+        rmSync(dir, { recursive: true, force: true });
+        renameSync(staging, dir);
+        return fromRecord(dir, record, false);
+    }
+    catch (error) {
+        rmSync(staging, { recursive: true, force: true });
+        throw error;
+    }
+}
+export function listCachedHosts(cacheDir = cacheRoot()) {
+    const root = hostsCacheDir(cacheDir);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .filter((entry) => !entry.startsWith("."))
+        .flatMap((entry) => {
+        const record = readRecord(join(root, entry));
+        return record ? [record] : [];
+    });
+}

package/adapters/host/truapi-cli/src/host-link.d.ts

@@ -0,0 +1,16 @@
+import type { HostConnection, SigningDecision } from "@parity/product-lab/ports/host";
+import type { BrowserTab } from "@parity/product-lab/ports/browser";
+export interface HostLink {
+    /** What the adapter saw of the product's connection to the host whose frame port is `port` now. */
+    connection(port: number): Promise<HostConnection>;
+    /** The session is about to load the app again: what was seen before belongs to the document that is going away. */
+    renew(): void;
+}
+/** Watch `page`'s sockets to loopback ports from now on; call before the page first navigates. Undefined when the browser cannot observe sockets. */
+export declare function watchHostLink(page: Pick<BrowserTab, "onWebSocket" | "evaluate">): HostLink | undefined;
+/**
+ * The signing requests among the host's decided confirmations (`<approved|denied> <action>` lines, in order). A
+ * wording this adapter does not know (a newer host, or a confirmation after which the host itself submits something,
+ * such as `submit preimage`) is kept as `unknown`, which callers treat as a possible transaction.
+ */
+export declare function signingDecisions(lines: readonly string[]): SigningDecision[];

package/adapters/host/truapi-cli/src/host-link.js

@@ -0,0 +1,87 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function watchHostLink(page) {
+    if (!page.onWebSocket)
+        return undefined;
+    const links = new Map();
+    page.onWebSocket((socket) => {
+        let url;
+        try {
+            url = new URL(socket.url());
+        }
+        catch {
+            return;
+        }
+        if (url.hostname !== "127.0.0.1" || !url.port)
+            return;
+        const link = { sent: 0, received: 0, closed: false };
+        const port = Number(url.port);
+        links.set(port, [...(links.get(port) ?? []), link]);
+        socket.onSent(() => void link.sent++);
+        socket.onReceived(() => void link.received++);
+        socket.onClose(() => void (link.closed = true));
+    });
+    return {
+        renew() {
+            for (const all of links.values())
+                for (const link of all)
+                    link.closed = true;
+            links.clear();
+        },
+        async connection(port) {
+            const all = links.get(port) ?? [];
+            const link = all.findLast((item) => !item.closed) ?? all.at(-1);
+            if (!link) {
+                const script = `http://127.0.0.1:${port}/bootstrap.js`;
+                const seen = page.evaluate((src) => {
+                    if ("__HOST_API_PORT__" in globalThis)
+                        return { kind: "bridge" };
+                    if (typeof document === "undefined")
+                        return { kind: "none" };
+                    const named = [...document.scripts].find((item) => {
+                        if (item.src === src)
+                            return true;
+                        const url = new URL(item.src, document.baseURI);
+                        return url.origin === new URL(document.baseURI).origin && /^\/\.product-lab\/bridge\/[0-9a-f-]{36}\.js$/.test(url.pathname);
+                    });
+                    return named ? { kind: "tag", src: named.src } : { kind: "none" };
+                }, script);
+                const bridge = await seen.catch(() => undefined);
+                return {
+                    connected: false,
+                    detail: bridge?.kind === "bridge"
+                        ? "the page has the host's bridge, and no connection to the host was opened from it: the app's connect-src policy or the network may have refused its socket"
+                        : bridge?.kind === "tag"
+                            ? `the page's document names the host's bridge script (${bridge.src}) and the script did not run: the app's own policy (a Content-Security-Policy script-src) or the network refused it`
+                            : bridge?.kind === "none"
+                                ? `the page never loaded the host's bridge script (${script}): its document has no such script. The lab's proxy in front of the app's dev server adds it to the HTML documents it serves, so the page was not loaded through the proxy or its document is not HTML`
+                                : "the page could not be asked (it is loading or closed)",
+                };
+            }
+            const counts = `${link.sent} message${link.sent === 1 ? "" : "s"} sent, ${link.received} received`;
+            if (link.closed)
+                return { connected: false, detail: `the connection to the host closed (${counts})` };
+            if (link.sent === 0)
+                return { connected: false, detail: "the page opened a connection to the host, and the app has not called the host (0 messages sent)" };
+            if (link.received === 0)
+                return { connected: false, detail: `the app called the host and the host has not answered (${counts})` };
+            return { connected: true, detail: `the app and the host are talking (${counts})` };
+        },
+    };
+}
+const TRANSACTION = new Set(["sign payload", "create transaction"]);
+const MESSAGE = new Set(["sign raw data", "sign VRF transcript", "sign statement proof", "create account proof"]);
+const NOT_SIGNING = new Set(["remote permission", "device permission", "share identity", "derive account alias", "access another product account", "resolve account subtree"]);
+export function signingDecisions(lines) {
+    const decisions = [];
+    for (const line of lines) {
+        const match = /^(approved|denied) (.+)$/.exec(line.trim());
+        if (!match)
+            continue;
+        const action = match[2];
+        if (NOT_SIGNING.has(action))
+            continue;
+        decisions.push({ approved: match[1] === "approved", payload: TRANSACTION.has(action) ? "transaction" : MESSAGE.has(action) ? "message" : "unknown", action });
+    }
+    return decisions;
+}