@parity/product-lab 0.0.1-placeholder → 0.1.0

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

@@ -0,0 +1,75 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { randomBytes } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+export const DECISIONS_DIR_ENV = "TRUAPI_DECISIONS_DIR";
+export const DECISIONS_TIMEOUT_ENV = "TRUAPI_DECISIONS_TIMEOUT_MS";
+const POLL_MS = 20;
+export function writeAtomically(path, text) {
+    const temporary = `${path}.${randomBytes(4).toString("hex")}.tmp`;
+    writeFileSync(temporary, text, { mode: 0o600 });
+    renameSync(temporary, path);
+}
+function readJson(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function toPending(value) {
+    if (!value)
+        return undefined;
+    const { id, action, kind, at } = value;
+    if (typeof id !== "number" || typeof action !== "string" || (kind !== "action" && kind !== "permission"))
+        return undefined;
+    return { id: String(id), action, kind, at: typeof at === "number" ? at : 0 };
+}
+export function pendingDecisions(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => /^\d+\.request\.json$/.test(name))
+        .map((name) => toPending(readJson(join(dir, name))))
+        .filter((request) => !!request)
+        .sort((a, b) => Number(a.id) - Number(b.id));
+}
+export function decisionAnswer(request, approve) {
+    if (!approve)
+        return "n";
+    return request.kind === "permission" ? "o" : "y";
+}
+async function pause(signal) {
+    await delay(POLL_MS, undefined, signal ? { signal } : undefined);
+    signal?.throwIfAborted();
+}
+export async function decideNext(dir, approve, { timeoutMs, signal }) {
+    signal?.throwIfAborted();
+    const deadline = Date.now() + timeoutMs;
+    let request;
+    while (!(request = pendingDecisions(dir)[0])) {
+        if (Date.now() > deadline)
+            throw new Error(`No confirmation was waiting for a decision within ${timeoutMs} ms (${dir})`);
+        await pause(signal);
+    }
+    signal?.throwIfAborted();
+    writeAtomically(join(dir, `${request.id}.decision`), `${decisionAnswer(request, approve)}\n`);
+    const decided = join(dir, `${request.id}.decided.json`);
+    for (;;) {
+        signal?.throwIfAborted();
+        const record = readJson(decided);
+        if (record) {
+            const took = record.decision !== "denied";
+            if (took !== approve)
+                throw new Error(`The host ${String(record.decision)} ${request.action} (#${request.id}, ${String(record.reason)}) instead of ${approve ? "approving" : "denying"} it`);
+            return request;
+        }
+        if (Date.now() > deadline)
+            throw new Error(`The host did not take the decision on ${request.action} (#${request.id}) within ${timeoutMs} ms`);
+        await pause(signal);
+    }
+}

package/adapters/host/truapi-cli/src/host-temp-dir.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `sockaddr_un.sun_path` in bytes: 104 on macOS and the BSDs, 108 on Linux. The host is Rust: its standard library's
+ * `UnixListener::bind` refuses a path of that many bytes or more, so one byte less is the longest it binds.
+ */
+export declare const SUN_PATH_BYTES: Readonly<Record<string, number>>;
+/** The host's frame socket under its TMPDIR: `truapi-host-<6 random characters>/frames.sock`. */
+export declare const FRAMES_SOCKET: string;
+/** The longest socket path the host binds on `platform`; an unknown platform gets the smaller BSD size. */
+export declare function socketPathLimit(platform: string): number;
+/** Whether the host's frame socket fits under `tmp` on `platform`. */
+export declare function framesSocketFits(tmp: string, platform: string): boolean;
+/** The short temp directory of the host process kept in `processDir`. */
+export declare function hostTempDirPath(processDir: string): string;
+export interface HostTempDir {
+    /** What the host process's environment gains: `TMPDIR` when the inherited one is too long, else nothing. */
+    readonly env: Readonly<Record<string, string>>;
+    /** Why the host got a temp directory of its own (one line for the start's log), when it did. */
+    readonly reason?: string;
+    /** Remove the directory (when the host stops); safe to call more than once. */
+    remove(): void;
+}
+/**
+ * The temp directory of the host process kept in `processDir`. `inherited` is the TMPDIR it would inherit (unset: the
+ * system's). A stale directory of this process is removed first, whichever way it goes.
+ */
+export declare function hostTempDir(processDir: string, inherited: string | undefined, platform?: string): HostTempDir;

package/adapters/host/truapi-cli/src/host-temp-dir.js

@@ -0,0 +1,31 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const SUN_PATH_BYTES = { darwin: 104, freebsd: 104, openbsd: 104, netbsd: 104, linux: 108 };
+export const FRAMES_SOCKET = `truapi-host-${"x".repeat(6)}/frames.sock`;
+export function socketPathLimit(platform) {
+    return (SUN_PATH_BYTES[platform] ?? 104) - 1;
+}
+export function framesSocketFits(tmp, platform) {
+    return Buffer.byteLength(join(tmp, FRAMES_SOCKET)) <= socketPathLimit(platform);
+}
+export function hostTempDirPath(processDir) {
+    return join("/tmp", `pl-host-${createHash("sha256").update(processDir).digest("hex").slice(0, 12)}`);
+}
+export function hostTempDir(processDir, inherited, platform = process.platform) {
+    const path = hostTempDirPath(processDir);
+    rmSync(path, { recursive: true, force: true });
+    const tmp = inherited || tmpdir();
+    if (framesSocketFits(tmp, platform))
+        return { env: {}, remove() { } };
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const bytes = Buffer.byteLength(join(tmp, FRAMES_SOCKET));
+    return {
+        env: { TMPDIR: path },
+        reason: `TMPDIR ${tmp} would give the truAPI host a ${bytes}-byte frame socket path, over ${platform}'s ${socketPathLimit(platform)}: the host uses ${path}`,
+        remove: () => rmSync(path, { recursive: true, force: true }),
+    };
+}

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

@@ -0,0 +1,115 @@
+import type { VersionResolution } from "@parity/product-lab/domain/versions";
+import type { ChainGateSource, CommandRunner, ConditionedLinks, EnvironmentVariables, LockManager, PortAllocator, ProcessRunner, ProcessSandbox } from "@parity/product-lab/ports/system";
+import type { HostNetworkRoutes } from "@parity/product-lab/domain";
+import type { HostConnection, HostSession, HostSessionEvidence, PendingApproval, SessionApprovals, SigningDecision } from "@parity/product-lab/ports/host";
+import type { ProductAccountDerivation } from "@parity/product-lab/ports/identity";
+import type { Browser } from "@parity/product-lab/ports/browser";
+import type { AttestationRecord, HostOrigin } from "./acquire.js";
+import type { TruapiCliHostConfig } from "./host-options.js";
+import type { SeededProductConfig } from "./product-config.js";
+/** What the provider needs from the machine (Node implementations: @product-lab/system-node). */
+export interface TruapiCliSystem {
+    /** One owned-process registry under `<stateRoot>/processes`. */
+    processes: ProcessRunner;
+    /** Bounded host contract probes. */
+    commands: CommandRunner;
+    /** The per-identity data-directory lock. */
+    locks: LockManager;
+    /** Host ports from the `ports` range. */
+    ports: PortAllocator;
+    /** The run's variables: `PRODUCT_LAB_HOST_RUST_LOG` (the hosts' `RUST_LOG`, opt-in). Without it none is read. */
+    environment?: Pick<EnvironmentVariables, "get">;
+    /** Wraps the native host process so it can reach loopback only
+     * (`denyByDefault`). Required only when `denyByDefault` is set; without it
+     * (or when unsupported on this machine) `denyByDefaultNetwork` stays false. */
+    sandbox?: ProcessSandbox;
+    /** Backlog 31: each session's links to the routing's endpoints. Without it (or on a public network) the host
+     * declares no conditions: its own connections cannot be conditioned. */
+    conditionedLinks?: ConditionedLinks;
+}
+/** What a truAPI CLI host runs with: its options (see host-options.ts) and its dependencies. */
+export interface TruapiCliHostDeps {
+    /** The browser sessions open their app in (the Browser port; the caller
+     * launches it, for example `PlaywrightBrowser` from
+     * `@parity/product-lab/browser-playwright`). Every session gets its own page, and
+     * so its own browser context. */
+    browser: Browser;
+    /** How the host reaches the environment (for example `RunningEnvironment.routes`): People, Asset Hub,
+     * Bulletin and the identity backend; an environment without them routes the absent ones to closed
+     * loopback ports (see `truapiCliNetworkConfig`). */
+    routes: HostNetworkRoutes;
+    system: TruapiCliSystem;
+    /**
+     * The run's version resolution (Phase 6), when the run resolved versions.
+     * Its `host:truapi-cli` entry becomes the acquisition's `resolved` release
+     * (host.lock.json is then not read); the factory takes it from here.
+     */
+    versions?: VersionResolution;
+    /**
+     * Derives a session's product account from the identity it signs in as (backlog item 62), so `session.account()`
+     * needs neither the app's page nor a host read. The composition root supplies it; without it `session.account()`
+     * asks the host (a `signing-host --script` read, script-account-read.ts).
+     */
+    accounts?: ProductAccountDerivation;
+    /**
+     * Backlog 92: origin gates in front of the routing's local nodes (the composition root opens them once per session).
+     * Under `denyByDefault` the native host is routed through them and admits no browser origin (it sends none), so an
+     * app that opens a node itself, from its page or a worker, is refused and reported; otherwise ignored.
+     */
+    chainGates?: ChainGateSource;
+}
+export type TruapiCliHostOptions = TruapiCliHostConfig & TruapiCliHostDeps;
+export interface CliSessionEvidence extends HostSessionEvidence {
+    host: "truapi-cli";
+    /** Binary digest. */
+    sha256: string;
+    /** Where the binary came from: official, framework-ci, local-build or unpinned. */
+    origin: HostOrigin;
+    label: string;
+    archiveSha256: string | null;
+    attestation: AttestationRecord;
+    dataDir: string;
+    runDir: string;
+    hostPort: number;
+    pid: number;
+    identity: string;
+    approvals: SessionApprovals;
+    startMs: number;
+    importMs?: number;
+    /** Product configs the host was seeded with (`--product-config`): file digests, products, grants, any opt-in. */
+    productConfigs?: readonly SeededProductConfig[];
+    /**
+     * How the host reached the environment (backlog A4): `local-network`, the lab's routing file; `public`, the host's
+     * own endpoints for the network (every route public, no routing file).
+     */
+    routing?: "local-network" | "public";
+    /** Set when the data directory is the actor's, shared by all its apps one after the other (`actorStateRoot`). */
+    sharedState?: SharedActorState;
+    /** Set only under `denyByDefault`: what each layer of deny-by-default
+     * networking can and cannot report (docs/verification/2026-09-25-cli-deny.md). */
+    network?: {
+        browserLayer: string;
+        nativeProcessLayer: string;
+    };
+}
+/** A data directory shared by every app of one actor (`actorStateRoot`), used by one session at a time. */
+export interface SharedActorState {
+    actor: string;
+    dataDir: string;
+    /** Sessions of the actor never run at the same time: the data directory's session lock refuses the second. */
+    rule: "sequential";
+}
+export interface CliHostSession extends HostSession {
+    readonly evidence: CliSessionEvidence;
+    open(path: string): Promise<void>;
+    approvals: HostSession["approvals"] & {
+        /** `<approved|denied> <action>` lines the host recorded (TRUAPI_APPROVALS_LOG). */
+        decisions(): Promise<string[]>;
+        /** Confirmations waiting for a decision (`per-request` sessions; empty otherwise). */
+        pending(): Promise<PendingApproval[]>;
+        /** The signing requests among `decisions()` (host-link.ts). */
+        signing(): Promise<readonly SigningDecision[]>;
+    };
+    /** Present when the session's browser can observe the page's sockets (host-link.ts). */
+    connection?(): Promise<HostConnection>;
+}

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

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export {};

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

@@ -0,0 +1,20 @@
+import type { CommandRunner } from "@parity/product-lab/ports/system";
+import type { AttestationPolicy, AttestationRecord } from "./host-records.js";
+/** `<sha256>  <name>` as written by sha256sum / shasum. */
+export declare function parseChecksumFile(text: string, archiveName: string): string;
+export declare function sha256File(file: string): string;
+/** Verify a release archive's GitHub build attestation with `gh attestation verify`. */
+export declare function verifyAttestation(archive: string, { policy, repository, signerWorkflow, commands, signal }: {
+    policy: AttestationPolicy;
+    repository?: string;
+    signerWorkflow?: string;
+    commands?: CommandRunner;
+    signal?: AbortSignal;
+}): Promise<AttestationRecord>;
+/**
+ * Extract a release archive. Members change between releases (0.20.0 added
+ * `script-types.d.ts`), so any relative path is accepted, but never an
+ * absolute path, a `..` component, or a link: everything lands inside `into`.
+ */
+export declare function extract(archive: string, into: string, commands: CommandRunner, signal?: AbortSignal): Promise<string>;
+export declare function versionOf(binary: string, commands: CommandRunner, signal?: AbortSignal): Promise<string>;

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

@@ -0,0 +1,101 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { ATTESTING_REPOSITORIES } from "./official-release.js";
+async function runChecked(commands, request) {
+    const result = await commands.run(request);
+    if (result.code !== 0)
+        throw Object.assign(new Error(`${request.command} exited ${result.code}: ${result.stderr.trim()}`), { code: result.code, stderr: result.stderr });
+    return result;
+}
+export function parseChecksumFile(text, archiveName) {
+    const [digest, name] = text.trim().split(/\s+/);
+    if (!digest || !/^[a-f0-9]{64}$/.test(digest))
+        throw new Error("The published checksum file holds no sha256");
+    if (name && basename(name.replace(/^\*/, "")) !== archiveName)
+        throw new Error(`The published checksum names ${name}, not ${archiveName}`);
+    return digest;
+}
+export function sha256File(file) {
+    return createHash("sha256").update(readFileSync(file)).digest("hex");
+}
+export async function verifyAttestation(archive, { policy, repository, signerWorkflow, commands, signal }) {
+    const signers = repository ? [{ repository, signerWorkflow: signerWorkflow ?? `${repository}/.github/workflows/release-cli.yml` }] : ATTESTING_REPOSITORIES;
+    if (policy === "skip")
+        return { status: "skipped", reason: "attestation check disabled" };
+    if (!commands)
+        throw new Error("Attestation verification needs the command runner port");
+    const unavailable = (reason) => {
+        if (policy === "required")
+            throw new Error(`Attestation required but not verifiable: ${reason}`);
+        return { status: "unavailable", reason };
+    };
+    try {
+        await runChecked(commands, { command: "gh", args: ["auth", "status"], timeoutMs: 20_000, signal });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return unavailable("the GitHub CLI (gh) is not installed");
+        if (typeof code === "number")
+            return unavailable("the GitHub CLI (gh) is not authenticated");
+        throw error;
+    }
+    let stdout;
+    const failures = [];
+    for (const signer of signers) {
+        try {
+            ({ stdout } = await runChecked(commands, {
+                command: "gh",
+                args: ["attestation", "verify", archive, "--repo", signer.repository, "--signer-workflow", signer.signerWorkflow, "--format", "json"],
+                timeoutMs: 120_000, maxOutputBytes: 32 * 1024 * 1024, signal,
+            }));
+            break;
+        }
+        catch (error) {
+            failures.push(`${signer.repository}: ${String(error.stderr ?? error).trim().split("\n").slice(-2).join(" ")}`);
+        }
+    }
+    if (stdout === undefined)
+        throw new Error(`Attestation verification failed for ${basename(archive)}: ${failures.join("; ")}`);
+    const [first] = JSON.parse(stdout);
+    if (!first)
+        throw new Error(`gh returned no attestation for ${basename(archive)}`);
+    const digest = sha256File(archive);
+    if (!first.verificationResult.statement.subject.some((subject) => subject.digest.sha256 === digest))
+        throw new Error(`The attestation does not name ${basename(archive)}'s digest`);
+    const cert = first.verificationResult.signature.certificate;
+    return {
+        status: "verified",
+        signerWorkflow: cert.buildSignerURI,
+        sourceCommit: cert.sourceRepositoryDigest,
+        sourceRef: cert.sourceRepositoryRef,
+        runUrl: cert.runInvocationURI,
+    };
+}
+export async function extract(archive, into, commands, signal) {
+    const { stdout: names } = await runChecked(commands, { command: "tar", args: ["-tzf", archive], maxOutputBytes: 16 * 1024 * 1024, timeoutMs: 120_000, signal });
+    const { stdout: long } = await runChecked(commands, { command: "tar", args: ["-tvzf", archive], maxOutputBytes: 16 * 1024 * 1024, timeoutMs: 120_000, signal });
+    const members = names.split("\n").filter(Boolean);
+    for (const member of members)
+        if (member.startsWith("/") || member.split("/").includes(".."))
+            throw new Error(`Unexpected archive member ${JSON.stringify(member)}`);
+    for (const line of long.split("\n").filter(Boolean))
+        if (!/^[-d]/.test(line))
+            throw new Error(`The archive holds a link or special file: ${line.trim()}`);
+    if (!members.some((member) => member.replace(/^\.\//, "") === "truapi-host"))
+        throw new Error("The archive holds no truapi-host binary");
+    mkdirSync(into, { recursive: true, mode: 0o755 });
+    await runChecked(commands, { command: "tar", args: ["-xzf", archive, "-C", into], timeoutMs: 120_000, signal });
+    const binary = join(into, "truapi-host");
+    if (!statSync(binary).isFile())
+        throw new Error("truapi-host in the archive is not a regular file");
+    chmodSync(binary, 0o755);
+    return binary;
+}
+export async function versionOf(binary, commands, signal) {
+    const { stdout } = await runChecked(commands, { command: binary, args: ["--version"], timeoutMs: 15_000, env: { PATH: process.env.PATH, TRUAPI_HOST_NO_UPDATE: "1" }, signal });
+    return stdout.trim();
+}

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

@@ -0,0 +1,14 @@
+import { type ActorHost } from "@parity/product-lab/domain";
+import type { HostProvider } from "@parity/product-lab/ports/host";
+import type { CliHostSession, TruapiCliHostOptions } from "./host-types.js";
+export type { TruapiCliPatch } from "./host-options.js";
+export type { CliHostSession, CliSessionEvidence, SharedActorState, TruapiCliHostDeps, TruapiCliHostOptions, TruapiCliSystem } from "./host-types.js";
+export { signerMnemonic } from "./host-process.js";
+/** A truAPI CLI host: its options are validated (once, by the adapter's schema), then the host is created. */
+export declare function truapiCliHost(options: TruapiCliHostOptions): HostProvider<CliHostSession>;
+/** This host as the lab window names it (`ActorSession.host`): for sessions opened without its `HostProvider` too. */
+export declare const TRUAPI_CLI_HOST: ActorHost & {
+    readonly color: string;
+};
+/** The host for options its schema already accepted (the factory and `truapiCliHost` validate first). */
+export declare function createTruapiCliHost(given: TruapiCliHostOptions): HostProvider<CliHostSession>;

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

@@ -0,0 +1,186 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { UnsupportedHostOperation, parseAdapterOptions } from "@parity/product-lab/domain";
+import { obtainHost, resolvedHost } from "./acquire.js";
+import { effectiveTruapiCliOptions, truapiCliHostOptionsSchema } from "./host-options.js";
+import { checkHost } from "./launch.js";
+import { describeBehaviour, lockedRelease, officialProvides, patchedBaseProvides } from "./official-behaviours.js";
+import { truapiCliNetworkConfig } from "./network-config.js";
+import { verifyResolverBackstop } from "./network-guard.js";
+import { readProductConfigs } from "./product-config.js";
+import { isolatedEnv } from "./host-process.js";
+import { hostOf, openCliSession } from "./cli-session.js";
+export { signerMnemonic } from "./host-process.js";
+const ID = /^[a-z0-9][a-z0-9-]{0,62}$/i;
+function releaseName(selection = {}) {
+    if (selection.resolved)
+        return `@parity/truapi@${selection.resolved.version}`;
+    if (selection.version && selection.version !== "locked")
+        return `@parity/truapi@${selection.version}`;
+    return lockedRelease(selection.lockFile).release;
+}
+export function truapiCliHost(options) {
+    const { browser: _browser, routes: _routes, system: _system, accounts: _accounts, chainGates: _chainGates, ...config } = options;
+    parseAdapterOptions(truapiCliHostOptionsSchema, config, "truapi-cli host");
+    return createTruapiCliHost(options);
+}
+export const TRUAPI_CLI_HOST = { id: "truapi-cli", label: "truAPI CLI", color: "#2f6fec" };
+export function createTruapiCliHost(given) {
+    const options = effectiveTruapiCliOptions(given);
+    const { stateRoot } = options;
+    let lab = options.routes;
+    const patches = [...options.patches];
+    lab.locality().assertNotMixed("The truAPI CLI host's routing");
+    const publicNetwork = lab.locality().kind === "public";
+    if (publicNetwork && options.denyByDefault)
+        throw new Error(`denyByDefault confines the native host to this machine, and this routing is the public ${lab.network} network: a host on it must reach the network. Drop denyByDefault for a public environment.`);
+    const official = !patches.length && !options.hostBin;
+    const provided = options.hostBin ? [] : official ? officialProvides(options.host) : patchedBaseProvides(options.host);
+    const carries = (behaviour, patch) => patches.includes(patch) || provided.includes(behaviour);
+    if (!publicNetwork && !carries("localNetwork", "local-network"))
+        throw new Error(official
+            ? `The truAPI CLI host's official release ${releaseName(options.host)} does not take ${lab.network}'s local endpoints: it lacks ${describeBehaviour("localNetwork")}. Add "local-network" to its patches (product-lab's checkout), or run it on a live network`
+            : `The truAPI CLI host needs the local-network patch to stay on ${lab.network}'s local endpoints, and this host declares ${patches.length ? patches.join(", ") : "no patches"}: add "local-network" to its patches, or run it on a live network`);
+    let routes = publicNetwork ? undefined : truapiCliNetworkConfig(lab);
+    let gated;
+    const allocate = () => {
+        if (options.ports)
+            return options.system.ports.reserve(options.ports);
+        if (options.system.ports.next)
+            return options.system.ports.next();
+        throw new Error("The truAPI CLI host has no ports: declare its ports ({ from, to }) or run it in a lab that hands out its own");
+    };
+    const readyTimeoutMs = options.readyTimeoutMs ?? 60_000;
+    const pendingTimeoutMs = options.pendingTimeoutMs ?? 60_000;
+    const sessions = new Set();
+    let supervisor;
+    let resolved;
+    let acquired;
+    let counter = 0;
+    let productConfigs = [];
+    const denyByDefault = !!options.denyByDefault;
+    const sandboxSupported = !!options.system.sandbox?.supported;
+    const denyByDefaultNetwork = denyByDefault && sandboxSupported;
+    const conditionedLinks = routes ? options.system.conditionedLinks : undefined;
+    const capabilities = {
+        localNetwork: !publicNetwork,
+        localApps: true,
+        navigationEvents: carries("navigationEvents", "navigation-events"),
+        identityImport: !denyByDefaultNetwork,
+        productAccountRead: true,
+        approvalPolicies: ["approve-all", "deny-all"],
+        perRequestApproval: carries("perRequestApproval", "request-decisions"),
+        denyByDefaultNetwork,
+        openPath: true,
+        signing: "scripted",
+        sessionsPerProcess: 1,
+        ...(conditionedLinks ? { conditions: {} } : {}),
+    };
+    const runtime = {
+        options,
+        get lab() {
+            return lab;
+        },
+        get routes() {
+            return routes;
+        },
+        gated: () => gated,
+        publicNetwork,
+        conditionedLinks,
+        capabilities,
+        denyByDefaultNetwork,
+        readyTimeoutMs,
+        pendingTimeoutMs,
+        patches,
+        sessions,
+        allocate,
+        supervisor: () => supervisor,
+        acquired: () => acquired,
+        resolved: () => resolved,
+        productConfigs: () => productConfigs,
+        nextId: () => ++counter,
+    };
+    async function resolve() {
+        acquired = await obtainHost({ ...options.host, hostBin: options.hostBin, commands: options.system.commands }, patches);
+        const cleanEnv = Object.fromEntries(Object.keys(process.env).map((key) => [key, undefined]));
+        const versionResult = await options.system.commands.run({
+            command: acquired.binary, args: ["--version"], timeoutMs: 10_000,
+            env: { ...cleanEnv, PATH: process.env.PATH, TRUAPI_HOST_NO_UPDATE: "1" },
+        });
+        if (versionResult.code !== 0)
+            throw new Error(`truapi-host --version exited ${versionResult.code}: ${versionResult.stderr.trim()}`);
+        const version = versionResult.stdout.trim();
+        resolved = resolvedHost(acquired, version);
+        return resolved;
+    }
+    function supervisorDir() {
+        return join(stateRoot, "processes");
+    }
+    return {
+        id: TRUAPI_CLI_HOST.id,
+        label: TRUAPI_CLI_HOST.label,
+        color: TRUAPI_CLI_HOST.color,
+        capabilities,
+        resolve,
+        async prepare() {
+            if (supervisor)
+                return;
+            if (denyByDefault && !sandboxSupported)
+                throw new Error(`denyByDefault was requested but process network sandboxing is not supported here${options.system.sandbox?.unsupportedReason ? `: ${options.system.sandbox.unsupportedReason}` : " (no ProcessSandbox was provided in system.sandbox)"}`);
+            if (denyByDefaultNetwork && routes && options.chainGates && !gated) {
+                gated = await options.chainGates.gated();
+                lab = gated.routes;
+                routes = truapiCliNetworkConfig(lab);
+            }
+            productConfigs = readProductConfigs(options.productConfigs ?? [], lab, options.productConfigOptIn);
+            mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+            if (!resolved)
+                await resolve();
+            if (routes) {
+                const routing = join(stateRoot, "host-network.json");
+                writeFileSync(routing, JSON.stringify(routes, null, 2) + "\n", { mode: 0o600 });
+                await checkHost(acquired.binary, lab, { ...isolatedEnv(), HOST_CLI_LOCAL_NETWORK_CONFIG: routing }, options.system.commands);
+            }
+            mkdirSync(supervisorDir(), { recursive: true, mode: 0o700 });
+            await options.system.processes.reapAbandoned?.(supervisorDir(), { maxDepth: 0 });
+            supervisor = options.system.processes.open(supervisorDir());
+            if (denyByDefaultNetwork)
+                await verifyResolverBackstop(options.browser);
+        },
+        async createSession({ actor, app, approvals = "approve-all", path, conditions }) {
+            if (!ID.test(actor.id) || !ID.test(app.id))
+                throw new Error("Actor and app ids must be short slugs");
+            if (approvals === "per-request" ? !capabilities.perRequestApproval : !capabilities.approvalPolicies.includes(approvals))
+                throw new Error(approvals === "per-request"
+                    ? `per-request approvals need a host built with the request-decisions patch (declare it in patches), or a release that provides ${describeBehaviour("perRequestApproval")}`
+                    : `Unsupported approval policy ${approvals}`);
+            if (!actor.identity)
+                throw new UnsupportedHostOperation("truapi-cli", "Starting a session without an identity", "the lab signs as the actor's wallet; provision an identity first (IdentityProvisioner)");
+            if ([...sessions].some((s) => s.actor.id === actor.id && s.app.id === app.id))
+                throw new Error(`${actor.id} already has a session for ${app.id}; one host process per actor and app`);
+            return openCliSession(runtime, actor, app, actor.identity, approvals, path, !!conditions || options.conditionLinks === "always");
+        },
+        async importIdentity(session, identity) {
+            const host = hostOf(session);
+            if (!host || !sessions.has(session))
+                throw new Error("Not a running session of this provider");
+            if (denyByDefaultNetwork)
+                throw new UnsupportedHostOperation("truapi-cli", "Importing an identity under denyByDefault", "the swap restarts the native host on a new port, which the session's browser-context policy was not built for; not proven here (docs/verification/2026-09-25-cli-deny.md)");
+            await host.swap(identity);
+        },
+        async dispose() {
+            const errors = [];
+            for (const session of [...sessions].reverse())
+                await session.stop().catch((error) => errors.push(error));
+            if (supervisor) {
+                await supervisor.stopAll().catch((error) => errors.push(error));
+                supervisor.close();
+                supervisor = undefined;
+            }
+            if (errors.length)
+                throw new AggregateError(errors, "truapi-cli sessions did not all stop");
+        },
+    };
+}

package/adapters/host/truapi-cli/src/identity-fingerprint.d.ts

@@ -0,0 +1,3 @@
+import type { ProvisionedIdentity } from "@parity/product-lab/domain";
+/** The first 6 bytes of SHA-256 over the identity's entropy, as hex; never the entropy itself. */
+export declare function identityFingerprint(identity: Pick<ProvisionedIdentity, "entropy">): string;

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

@@ -0,0 +1,6 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+export function identityFingerprint(identity) {
+    return createHash("sha256").update(Uint8Array.from(identity.entropy)).digest().subarray(0, 6).toString("hex");
+}

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

@@ -0,0 +1,26 @@
+export { routesFromTruapiCliNetworkConfig, truapiCliNetworkConfig, type TruapiCliChainRoute, type TruapiCliNetworkConfig, } from "./network-config.js";
+export { readTruapiCliIdentity } from "./cli-identity.js";
+export { servePersistedTruapiHost, type ServePersistedTruapiHostRequest, type ServedPersistedTruapiHost } from "./serve-persisted.js";
+export { baseForVersion, HOST_PATCH_DIRECTORY, HOST_PATCH_UPSTREAM, HOST_PATCHES_REPOSITORY_ONLY, HostPatchesNotInstalled, NoPatchForBaseError, patchBases, patchCatalogue, patchVariant, readHostPatchManifest, resolveHostPatch, type HostPatchEntry, type RebasedHostPatch, } from "./patch-manifest.js";
+export { launch, launchPlan, checkHost, npmWorkspaceDevServer, type AppCommand, type AppEnvironmentContext, type LaunchOptions, } from "./launch.js";
+export { hostPatches, localNetworkPatch, navigationEventsPatch } from "./patches.js";
+export { HOST_PATCH_CATALOGUE, type HostPatchFacts } from "./patch-catalogue.js";
+export { productConfigArgs, readProductConfigs, type SeededProductConfig } from "./product-config.js";
+export { NAVIGATIONS_LOG_ENV, DOTNS_TLDS, parseProductUrl, parseNavigationLine, watchNavigations, readNavigations, resolveNavigation, type NavigationRequested, type NavigationTarget, type ProductDestination, type RegisteredApp, type ResolveOptions, type WatchOptions, } from "./navigation.js";
+export { acquireTruapiHost, obtainHost, unpinnedHost, listCachedHosts, readHostLock, orderedPatches, patchsetHash, hostTarget, cacheRoot, hostsCacheDir, officialArchiveUrl, verifyAttestation, buildCommand, DEFAULT_BUILD_PATCHES, MissingHostError, DEFAULT_LOCK_FILE, type AcquireOptions, type AcquiredTruapiHost, type AcquiredRecord, type AttestationPolicy, type AttestationRecord, type HostLock, type HostOrigin, type HostSelection, type TruapiResolvedHost, } from "./acquire.js";
+export { TRUAPI_CLI_COMPONENT, resolvedHostVersion, type ResolvedHostVersion } from "./resolved-host.js";
+export { findRoutedBuild, hostNeeds, readRouteSelection, routedPatchset, routeTruapiRelease, type RouteReleaseSteps, type TruapiRouteSelection } from "./route-release.js";
+export { buildPatchedHost, type BuildOptions, type BuildResult } from "./build.js";
+export { truapiCliProvisioner, readProvisionedIdentity, defaultUsernamePrefix, type TruapiCliProvisioner, type TruapiCliProvisionerOptions, type CliProvisionedIdentity, type ProvisionEvidence, } from "./provision.js";
+export { truapiCliHost, TRUAPI_CLI_HOST, createTruapiCliHost, signerMnemonic, type TruapiCliHostDeps, type TruapiCliHostOptions, type TruapiCliPatch, type TruapiCliSystem, type CliHostSession, type CliSessionEvidence, type SharedActorState, } from "./host.js";
+export { TruapiCliHostFactory, TRUAPI_CLI_FLAGS, TRUAPI_HOST_UPSTREAM, type TruapiCliFactorySettings, type TruapiRebaseCheckResult } from "./truapi-cli-host-factory.js";
+export { checkPatchesFrom, checkPatchesOnto, probeOfficialLocalNetwork, providesHint, rebaseCheckText, retirementBehaviour, RebaseCheckInputError, type CheckPatch, type OfficialBehaviour, type OfficialProbe, type PatchResult, type PatchStatus, type ProvidesHint, type RebaseCheckOptions, type RebaseCheckReport, type RetirementBehaviour, type RetirementRow, } from "./rebase-check.js";
+export { ACTOR_STATE_FOLDER, effectiveTruapiCliOptions, TRUAPI_CLI_HOST_OPTIONS, TRUAPI_CLI_KIND, TRUAPI_CLI_PATCHES, truapiCliHostOptionsSchema, type TruapiCliHostConfig } from "./host-options.js";
+export { PROBED_CAPABILITIES, PROBE_PRODUCT, probeHostCapabilities, probeVerdict, type CapabilityProbeResult, type HostProbeOptions, type HostProbeReport, type Observed, type ProbedCapability, type ProbeVerdict, } from "./capability-probes.js";
+export { PROBE_MARKER, probeLines, probeScript, type ProbeScriptParams, type ProbeStep } from "./probe-script.js";
+export { readSigningEvidence, SIGNATURES_LOG_ENV } from "./signing-evidence.js";
+export { freePorts, readFrames, startChainStub, type ChainStub, type ChainStubOptions, type StubRequest } from "./probe-stub.js";
+export { PRODUCT_ACCOUNT_SCRIPT, SCRIPT_INDEX_ENV, scriptAccountKey, scriptAccountRead, scriptReadSandboxSpec, type ScriptAccountReadRequest, type ScriptAccountSigner } from "./script-account-read.js";
+export { behaviourUpstream, describeBehaviour, knownBehaviours, lockedRelease, officialProvides, type LockedRelease, type OfficialSelection } from "./official-behaviours.js";
+export { productCliHostDetail, productCliHostLocalGap, releaseTakesLocalEndpoints } from "./checkout.js";
+export { truapiCliAttestProvisioner, readAttestedIdentity, type TruapiCliAttestProvisionerOptions, type TruapiCliAttestProvisioner, type CliAttestedIdentity, type AttestProvisionEvidence } from "./attest-provision.js";