@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/host/truapi-cli/host.lock.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "official": {
+    "version": "0.26.0",
+    "release": "@parity/truapi@0.26.0",
+    "archives": {
+      "aarch64-apple-darwin": "4931540e187b4c29877729186c19ae0fd50cce6ca26b738fb0d8d086936599e3",
+      "x86_64-unknown-linux-musl": "3f084f75edfde0eb357f1caf759e28c26aee43c638f17576b5114bcc3668079d",
+      "aarch64-unknown-linux-musl": "b9acd2cace42e96df5f3e6bb038bdc783d55bad27b8f1a01448566fcb7df8b86"
+    },
+    "provides": [
+      "localNetwork",
+      "navigationEvents"
+    ]
+  },
+  "patched": {
+    "repository": "https://github.com/paritytech/host-rust-core",
+    "base": "14b1e2a499c606363340d02702b35c63a8c0a0c7",
+    "baseVersion": "0.26.0",
+    "patches": [
+      "request-decisions",
+      "chain-reconnect",
+      "signature-evidence"
+    ],
+    "patchset": "335d3bb47d4c",
+    "archives": {},
+    "provides": [
+      "localNetwork",
+      "navigationEvents"
+    ],
+    "providesBase": "14b1e2a499c606363340d02702b35c63a8c0a0c7"
+  }
+}

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

@@ -0,0 +1,81 @@
+import type { CommandRunner } from "@parity/product-lab/ports/system";
+import type { ResolvedHostVersion } from "./resolved-host.js";
+import type { AcquiredTruapiHost, AttestationPolicy } from "./host-records.js";
+import { type HostLock } from "./host-lock.js";
+import { type TruapiRouteSelection } from "./route-release.js";
+import { type Fetch } from "./official-release.js";
+import { verifyAttestation } from "./host-verification.js";
+export { resolvedHost, type AcquiredRecord, type AcquiredTruapiHost, type AttestationPolicy, type AttestationRecord, type HostOrigin, type TruapiResolvedHost, } from "./host-records.js";
+export { DEFAULT_LOCK_FILE, orderedPatches, patchsetHash, readHostLock, type HostLock, type OrderedPatch } from "./host-lock.js";
+export { HOST_REPOSITORY, RELEASE_BASE_URL, RELEASE_SIGNER_WORKFLOW, officialArchiveName, officialArchiveUrl } from "./official-release.js";
+export { cacheRoot, hostTarget, hostsCacheDir, installArchive, listCachedHosts } from "./host-cache.js";
+export { parseChecksumFile, sha256File, verifyAttestation } from "./host-verification.js";
+export interface AcquireOptions {
+    /** Bounded one-shot archive and attestation commands, supplied by the composition root. */
+    commands?: CommandRunner;
+    /** `locked` (default) or an explicit `x.y.z` release. Ignored for patched hosts (keyed by base). */
+    version?: string;
+    /** Patches the host must carry. Empty: the official release. */
+    patches?: readonly string[];
+    /** Base commit for a patched host (default: the lock's patched base). */
+    base?: string;
+    cacheDir?: string;
+    target?: string;
+    lockFile?: string;
+    /** Release download base (default GitHub); https, or loopback http for tests. */
+    releaseBaseUrl?: string;
+    attestation?: AttestationPolicy;
+    /** Never download: fail unless the host is cached. */
+    offline?: boolean;
+    log?: (line: string) => void;
+    signal?: AbortSignal;
+    fetch?: Fetch;
+    /** Test seam for the attestation check. */
+    verifyAttestation?: typeof verifyAttestation;
+    /**
+     * A host version from the run's version resolution (`resolvedHostVersion`,
+     * Phase 6) instead of host.lock.json: that release, and its archive must
+     * have exactly this sha256, downloaded or cached, before anything in it
+     * runs. host.lock.json is not read. Official releases only (no `patches`,
+     * no `version`).
+     */
+    resolved?: ResolvedHostVersion;
+    /**
+     * Backlog 27: how a suite row runs the release it resolved (its route file, PRODUCT_LAB_HOST_ROUTE). Official: that
+     * release's archive, by its digest, with `patches` kept as what the host claims (the route's probes showed the
+     * release does it). Patched: exactly the build the route made (its base and patch set), from the cache.
+     */
+    routed?: TruapiRouteSelection;
+}
+/** The patches `product-lab host build` and `bun run setup` build by default: every lab session's
+ * Request decisions, bounded transport shutdown and native signature evidence; routing and navigation are in the base. */
+export declare const DEFAULT_BUILD_PATCHES: readonly ["request-decisions", "chain-reconnect", "signature-evidence"];
+export declare class MissingHostError extends Error {
+    readonly command: string;
+    /** `checkout`: product-lab's own checkout, where the patched host is built; a product is never told to build one. */
+    constructor(message: string, command: string, checkout?: boolean);
+}
+/** Resolve the requested truAPI CLI host and make sure a verified copy is cached. */
+export declare function acquireTruapiHost(options?: AcquireOptions): Promise<AcquiredTruapiHost>;
+/** The build command a missing patched host needs. */
+export declare function buildCommand(patches: readonly string[], base: string, target: string): string;
+export declare function findPatched({ cacheDir, target, patches, base, version, lock, }: {
+    cacheDir: string;
+    target: string;
+    patches: readonly string[];
+    base: string;
+    version?: string;
+    lock: HostLock;
+}): AcquiredTruapiHost;
+/** A caller-supplied binary (`--host-bin`): reported as an unpinned host. */
+export declare function unpinnedHost(binary: string, patches: readonly string[]): AcquiredTruapiHost;
+export interface HostSelection extends Omit<AcquireOptions, "patches"> {
+    /** Escape hatch for developing the host itself; reported as an unpinned host. */
+    hostBin?: string;
+}
+/**
+ * The host binary a session or a provisioner runs: the caller's `hostBin` (unpinned) or an acquired, verified host. In a
+ * product (outside product-lab's checkout) only the official release: a patched host already cached on the machine, or
+ * one given by path, never runs for a product (`productCliHostRefusal`).
+ */
+export declare function obtainHost(selection: HostSelection, patches: readonly string[], checkout?: boolean): Promise<AcquiredTruapiHost>;

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

@@ -0,0 +1,213 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
+import { DEFAULT_LOCK_FILE, orderedPatches, patchesNeededOnBase, patchsetHash, readHostLock } from "./host-lock.js";
+import { NoPatchForBaseError } from "./patch-manifest.js";
+import { findRoutedBuild } from "./route-release.js";
+import { download, fetchText, officialArchiveName, officialArchiveUrl } from "./official-release.js";
+import { cacheRoot, fromRecord, hostTarget, hostsCacheDir, installArchive, readRecord, withLock } from "./host-cache.js";
+import { parseChecksumFile, sha256File, verifyAttestation } from "./host-verification.js";
+import { insideProductLabCheckout, PRODUCT_RELEASED_ONLY, productCliHostRefusal } from "./checkout.js";
+export { resolvedHost, } from "./host-records.js";
+export { DEFAULT_LOCK_FILE, orderedPatches, patchsetHash, readHostLock } from "./host-lock.js";
+export { HOST_REPOSITORY, RELEASE_BASE_URL, RELEASE_SIGNER_WORKFLOW, officialArchiveName, officialArchiveUrl } from "./official-release.js";
+export { cacheRoot, hostTarget, hostsCacheDir, installArchive, listCachedHosts } from "./host-cache.js";
+export { parseChecksumFile, sha256File, verifyAttestation } from "./host-verification.js";
+export const DEFAULT_BUILD_PATCHES = ["request-decisions", "chain-reconnect", "signature-evidence"];
+export class MissingHostError extends Error {
+    command;
+    constructor(message, command, checkout = insideProductLabCheckout()) {
+        super(checkout
+            ? `${message}\nFix: run \`bun run setup\` in the product-lab checkout (it builds the patched host once and caches it; needs Rust and about 15 GB of free disk for the build), ` +
+                `or build it yourself:\n  ${command}\nOr point PRODUCT_LAB_HOST_BIN at a truapi-host you built with these patches.`
+            : `${message}\n${PRODUCT_RELEASED_ONLY}`);
+        this.command = command;
+        this.name = "MissingHostError";
+    }
+}
+export async function acquireTruapiHost(options = {}) {
+    if (options.routed)
+        return acquireRouted(options.routed, options);
+    const cacheDir = options.cacheDir ?? cacheRoot();
+    if (!isAbsolute(cacheDir))
+        throw new Error("The host cache directory must be absolute");
+    const target = options.target ?? hostTarget();
+    const patches = options.patches ?? [];
+    const log = options.log ?? (() => { });
+    const { resolved } = options;
+    if (resolved) {
+        if (patches.length)
+            throw new Error(`A resolved host version (${resolved.source}) names an official release; patched hosts are found by patch set`);
+        if (options.version !== undefined)
+            throw new Error(`Pass either a resolved host version (${resolved.source}) or version ${options.version}, not both`);
+        if (resolved.target !== target)
+            throw new Error(`The resolved host digest is for ${resolved.target}; this machine needs ${target}`);
+        if (!/^[a-f0-9]{64}$/.test(resolved.archiveSha256))
+            throw new Error(`The resolved host digest ${resolved.archiveSha256} is not a sha256`);
+    }
+    const lock = resolved ? undefined : readHostLock(options.lockFile ?? DEFAULT_LOCK_FILE);
+    if (patches.length)
+        return findPatched({ cacheDir, target, patches, base: options.base ?? lock.patched.base, version: options.version, lock: lock });
+    const requested = resolved ? resolved.version : (options.version ?? "locked");
+    const version = requested === "locked" ? lock.official.version : requested;
+    if (!/^\d+\.\d+\.\d+$/.test(version))
+        throw new Error(`Host version must be "locked" or x.y.z, got ${requested}`);
+    const lockDigest = resolved ? resolved.archiveSha256 : version === lock.official.version ? lock.official.archives[target] : undefined;
+    const lockSource = resolved ? `the resolved version (${resolved.source})` : "host.lock.json";
+    const dir = join(hostsCacheDir(cacheDir), version);
+    return withLock(dir, async () => {
+        const existing = readRecord(dir);
+        if (existing) {
+            if (lockDigest && existing.archive.sha256 !== lockDigest)
+                throw new Error(`Cached ${existing.label} has archive digest ${existing.archive.sha256}, ${resolved ? lockSource : "the lock"} says ${lockDigest}. Delete ${dir} and fetch again.`);
+            const host = fromRecord(dir, existing, true);
+            log(`cached ${existing.label} (${target}) at ${dir}`);
+            return host;
+        }
+        if (options.offline)
+            throw new Error(`truapi-host ${version} is not cached at ${dir} and downloads are disabled`);
+        if (!options.commands)
+            throw new Error("Host acquisition needs the command runner port to verify and install an archive");
+        const fetchImpl = options.fetch ?? fetch;
+        const url = officialArchiveUrl(version, target, options.releaseBaseUrl);
+        const name = officialArchiveName(version, target);
+        mkdirSync(hostsCacheDir(cacheDir), { recursive: true, mode: 0o755 });
+        const partial = join(hostsCacheDir(cacheDir), `.download-${name}-${randomBytes(4).toString("hex")}`);
+        try {
+            log(`downloading ${url}`);
+            const started = performance.now();
+            const published = parseChecksumFile(await fetchText(`${url}.sha256`, fetchImpl, options.signal), name);
+            const actual = await download(url, partial, fetchImpl, options.signal);
+            log(`downloaded ${name} in ${Math.round(performance.now() - started)} ms, sha256 ${actual}`);
+            if (actual !== published)
+                throw new Error(`Checksum mismatch for ${name}: the published .sha256 says ${published}, the download is ${actual}`);
+            if (lockDigest && actual !== lockDigest)
+                throw new Error(`Checksum mismatch for ${name}: ${lockSource} says ${lockDigest}, the download is ${actual}`);
+            const attestation = await (options.verifyAttestation ?? verifyAttestation)(partial, { policy: options.attestation ?? "when-available", commands: options.commands, signal: options.signal });
+            log(`attestation: ${attestation.status}${attestation.reason ? ` (${attestation.reason})` : ""}${attestation.sourceCommit ? ` from ${attestation.sourceCommit}` : ""}`);
+            return await installArchive({
+                cacheDir,
+                dirName: version,
+                archivePath: partial,
+                expectVersion: version,
+                commands: options.commands,
+                signal: options.signal,
+                record: {
+                    label: `truapi-host-${version}`,
+                    origin: "official",
+                    version,
+                    target,
+                    archive: { name, sha256: actual, url },
+                    checksums: { published, ...(lockDigest ? { lock: lockDigest, lockSource } : {}) },
+                    attestation,
+                    patches: [],
+                },
+            });
+        }
+        finally {
+            rmSync(partial, { force: true });
+        }
+    });
+}
+async function acquireRouted(routed, options) {
+    if (options.version !== undefined || options.resolved)
+        throw new Error("A routed host comes from its route only: pass no version or resolved release with it");
+    const cacheDir = options.cacheDir ?? cacheRoot();
+    const target = options.target ?? hostTarget();
+    if (routed.route === "official") {
+        if (routed.target !== target)
+            throw new Error(`The route's archive digest is for ${routed.target}; this machine needs ${target}`);
+        const official = { ...options, resolved: { version: routed.version, target, archiveSha256: routed.archiveSha256, source: `the suite row's route (official ${routed.version})` } };
+        delete official.routed;
+        delete official.patches;
+        return acquireTruapiHost(official);
+    }
+    const found = findRoutedBuild(cacheDir, target, routed.base, routed.patchset);
+    if (found)
+        return found;
+    throw new MissingHostError(`No truapi-host built for the suite row's route (patches ${routed.patches.join(", ")}, patch set ${routed.patchset}, base ${routed.base.slice(0, 8)}) is cached for ${target} under ${hostsCacheDir(cacheDir)}.`, buildCommand(routed.patches, routed.base, target));
+}
+export function buildCommand(patches, base, target) {
+    return `product-lab host build --patches ${patches.join(",")} --base ${base} --target ${target}`;
+}
+export function findPatched({ cacheDir, target, patches, base, version, lock, }) {
+    if (version && version !== "locked")
+        throw new Error("Patched hosts are keyed by their base commit, not a release version; pass a base commit instead");
+    patches = patchesNeededOnBase(patches, base, lock);
+    let selected;
+    try {
+        selected = orderedPatches(patches, base);
+    }
+    catch (error) {
+        if (error instanceof NoPatchForBaseError)
+            throw new Error(`${error.message}; refresh the patch for that base (patches/truapi-host/manifest.json \`rebased\`) or use the lock's base ${lock.patched.base}`, { cause: error });
+        throw error;
+    }
+    const usesLock = base === lock.patched.base && patches.every((patch) => lock.patched.patches.includes(patch));
+    const ordered = usesLock ? orderedPatches(lock.patched.patches, base) : selected;
+    const hash = patchsetHash(base, ordered);
+    if (usesLock && hash !== lock.patched.patchset)
+        throw new Error(`host.lock.json records patch set ${lock.patched.patchset}, the manifest gives ${hash}; update the lock with the patches`);
+    const root = hostsCacheDir(cacheDir);
+    const entries = existsSync(root) ? readdirSync(root) : [];
+    const requested = ordered.map((patch) => patch.name);
+    const matches = (record) => {
+        if (!record || record.target !== target || record.base !== base || record.origin === "official")
+            return false;
+        if (!requested.every((patch) => record.patches.includes(patch)))
+            return false;
+        try {
+            return record.patchset === patchsetHash(base, orderedPatches(record.patches, base));
+        }
+        catch {
+            return false;
+        }
+    };
+    for (const kind of ["lab", "local"])
+        for (const name of entries.filter((entry) => entry.endsWith(`+${kind}.${hash}`)).sort()) {
+            const record = readRecord(join(root, name));
+            if (!matches(record) || record.patchset !== hash)
+                continue;
+            return fromRecord(join(root, name), record, true);
+        }
+    for (const kind of ["lab", "local"])
+        for (const name of entries.filter((entry) => entry.includes(`+${kind}.`)).sort()) {
+            const record = readRecord(join(root, name));
+            if (!matches(record))
+                continue;
+            return fromRecord(join(root, name), record, true);
+        }
+    throw new MissingHostError(`No truapi-host with patches ${ordered.map((p) => p.name).join(", ")} (patch set ${hash}, base ${base.slice(0, 8)}) is cached for ${target} under ${root}. ` +
+        "Framework-CI patched archives are not published yet (extraction plan, step 4).", buildCommand(ordered.map((p) => p.name), base, target));
+}
+export function unpinnedHost(binary, patches) {
+    if (!isAbsolute(binary))
+        throw new Error("hostBin must be an absolute path");
+    if (!existsSync(binary))
+        throw new Error(`No truapi-host at ${binary}`);
+    const path = resolvePath(binary);
+    return {
+        binary: path,
+        label: "unpinned",
+        origin: "unpinned",
+        version: "unknown",
+        target: "unknown",
+        archiveSha256: null,
+        binarySha256: sha256File(path),
+        patches: [...patches],
+        patchset: null,
+        attestation: { status: "none", reason: "caller-supplied binary (--host-bin)" },
+        dir: dirname(path),
+        cached: true,
+        source: path,
+    };
+}
+export async function obtainHost(selection, patches, checkout = insideProductLabCheckout()) {
+    if (!checkout && (patches.length || selection.hostBin))
+        throw productCliHostRefusal();
+    if (selection.hostBin)
+        return unpinnedHost(selection.hostBin, patches);
+    return acquireTruapiHost({ ...selection, patches });
+}

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

@@ -0,0 +1,49 @@
+import { type HostNetworkRoutes, type ProvisionedIdentity } from "@parity/product-lab/domain";
+import type { IdentityProvisioner, ProductAccountDerivation, ProvisionRequest } from "@parity/product-lab/ports/identity";
+import type { CommandRunner, ProcessSandbox } from "@parity/product-lab/ports/system";
+import { type AcquiredTruapiHost, type HostSelection } from "./acquire.js";
+import { type ProvisionEvidence } from "./provision.js";
+export interface TruapiCliAttestProvisionerOptions {
+    /** Official released host by default; no patches are acquired by this provisioner. */
+    readonly host?: HostSelection;
+    /** The owned local environment. Public backend onboarding is not part of this provisioner. */
+    readonly routes: HostNetworkRoutes;
+    readonly dataRoot: string;
+    readonly usernamePrefix?: string | ((actor: ProvisionRequest["actor"]) => string);
+    /** Independent RFC-0022 derivation used to reject a CLI answer for a different wallet. */
+    readonly accounts: ProductAccountDerivation;
+    /** Default 240 seconds, including the CLI's username and ring wait. */
+    readonly readyTimeoutMs?: number;
+    /** Opt-in confinement; refuses an unavailable sandbox instead of running unconfined. */
+    readonly denyByDefault?: boolean;
+    readonly system: {
+        readonly commands: CommandRunner;
+        readonly sandbox?: ProcessSandbox;
+    };
+    readonly log?: (line: string) => void;
+}
+export interface AttestProvisionEvidence extends ProvisionEvidence {
+    readonly mode: "attest";
+    readonly namespace: string;
+    readonly identityPublicKey: string;
+    readonly sandbox: {
+        readonly used: boolean;
+        readonly mechanism?: string;
+    };
+}
+/** No CLI auto-account store/session is created by `attest`. */
+export interface CliAttestedIdentity extends ProvisionedIdentity {
+    readonly liteUsername: string;
+    readonly evidence: AttestProvisionEvidence;
+}
+export interface TruapiCliAttestProvisioner extends IdentityProvisioner {
+    provision(request: ProvisionRequest): Promise<CliAttestedIdentity>;
+    host(): Promise<AcquiredTruapiHost>;
+}
+/**
+ * Keep `truapiCliProvisioner`'s auto mode unchanged. Call this factory explicitly to attest caller-chosen entropy.
+ * `attest` waits for real backend onboarding, dotNS identity and People ring inclusion before returning.
+ */
+export declare function truapiCliAttestProvisioner(options: TruapiCliAttestProvisionerOptions): TruapiCliAttestProvisioner;
+/** Reopen a successful chosen-wallet onboarding; incomplete records are deliberately not treated as ready. */
+export declare function readAttestedIdentity(dir: string, accounts: ProductAccountDerivation, namespace: string): CliAttestedIdentity;

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

@@ -0,0 +1,181 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { entropyToMnemonic, ss58Decode } from "@polkadot-labs/hdkd-helpers";
+import { z } from "zod";
+import { assertBip39Entropy } from "@parity/product-lab/domain";
+import { obtainHost } from "./acquire.js";
+import { checkHost } from "./launch.js";
+import { truapiCliNetworkConfig } from "./network-config.js";
+import { identityFingerprint } from "./identity-fingerprint.js";
+import { defaultUsernamePrefix } from "./provision.js";
+import { hostTempDir } from "./host-temp-dir.js";
+import { scriptReadSandboxSpec } from "./script-account-read.js";
+const ISOLATED = /^(HOST_|TRUAPI_|VITE_|PPN_|PRODUCT_LAB_|RUST_LOG$)/;
+const resultSchema = z.strictObject({
+    address: z.string().min(1),
+    publicKey: z.string().regex(/^0x[0-9a-f]{64}$/i),
+    liteUsername: z.string().regex(/^[a-z]{6,29}\.(?:0?[1-9]|[1-9][0-9])$/),
+});
+const evidenceSchema = z.strictObject({
+    provisioner: z.literal("truapi-cli"), mode: z.literal("attest"), namespace: z.string().regex(/^[a-z]+$/),
+    actor: z.string().min(1), liteUsername: resultSchema.shape.liteUsername,
+    identityAddress: resultSchema.shape.address, identityPublicKey: resultSchema.shape.publicKey,
+    fingerprint: z.string().regex(/^[a-f0-9]{12}$/), entropyBytes: z.number().int().positive(), dir: z.string().min(1),
+    host: z.strictObject({ label: z.string(), origin: z.string(), binarySha256: z.string().regex(/^[a-f0-9]{64}$/),
+        archiveSha256: z.string().regex(/^[a-f0-9]{64}$/).nullable(), patches: z.array(z.string()) }),
+    network: z.string().min(1), people: z.url(), identityBackend: z.url(),
+    sandbox: z.strictObject({ used: z.boolean(), mechanism: z.string().optional() }),
+    startedAt: z.string().datetime(), provisionMs: z.number().int().nonnegative(),
+});
+const walletSchema = z.strictObject({ version: z.literal(1), entropy: z.string().regex(/^(?:[0-9a-f]{2})+$/) });
+function isolatedEnvironment() {
+    return Object.fromEntries(Object.keys(process.env).filter((key) => ISOLATED.test(key)).map((key) => [key, undefined]));
+}
+function validateAnswer(answer, entropy, namespace, accounts) {
+    const expected = accounts.productAccount(entropy, `uid.${namespace}`, 0);
+    if (answer.publicKey.toLowerCase() !== expected.publicKey.toLowerCase())
+        throw new Error("CLI attestation returned a public key for a different wallet");
+    let publicKey, prefix;
+    try {
+        [publicKey, prefix] = ss58Decode(answer.address);
+    }
+    catch {
+        throw new Error("CLI attestation returned an invalid identity address");
+    }
+    if (prefix !== 42)
+        throw new Error("CLI attestation identity address must use SS58 prefix 42");
+    if (`0x${Buffer.from(publicKey).toString("hex")}` !== answer.publicKey.toLowerCase())
+        throw new Error("CLI attestation identity address does not match its public key");
+}
+export function truapiCliAttestProvisioner(options) {
+    if (!isAbsolute(options.dataRoot))
+        throw new Error("dataRoot must be an absolute path");
+    if (options.routes.locality().kind !== "loopback")
+        throw new Error("CLI attest provisioning requires an owned local environment");
+    const routes = truapiCliNetworkConfig(options.routes);
+    const timeoutMs = options.readyTimeoutMs ?? 240_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
+        throw new Error("readyTimeoutMs must be a positive integer");
+    if (options.denyByDefault && !options.system.sandbox?.supported)
+        throw new Error("CLI attest provisioning requires a supported process network sandbox when denyByDefault is set");
+    let acquired;
+    const host = () => acquired ??= obtainHost({ ...options.host, commands: options.system.commands }, []);
+    return {
+        id: "truapi-cli-attest",
+        capabilities: { registersUsername: true, acceptsEntropy: true, needsIdentityBackend: true },
+        host,
+        async provision({ actor, entropy: requested, signal }) {
+            if (!requested)
+                throw new Error("CLI attest provisioning requires caller-chosen BIP-39 entropy");
+            assertBip39Entropy(requested);
+            const entropy = Uint8Array.from(requested);
+            const mnemonic = entropyToMnemonic(entropy);
+            if (!/^[a-z0-9][a-z0-9-]{0,62}$/i.test(actor.id))
+                throw new Error("Actor ids must be short slugs");
+            const prefix = typeof options.usernamePrefix === "function" ? options.usernamePrefix(actor) : options.usernamePrefix ?? defaultUsernamePrefix(actor);
+            if (!/^[a-z]{6,29}$/.test(prefix))
+                throw new Error("Lite-username prefix must be 6 to 29 lowercase ASCII letters");
+            signal?.throwIfAborted();
+            const binary = await host();
+            const env = isolatedEnvironment();
+            const help = await options.system.commands.run({ command: binary.binary, args: ["attest", "--help"], env, timeoutMs: 10_000, signal });
+            if (help.code !== 0 || !help.stdout.includes("HOST_CLI_SIGNER_MNEMONIC") || !["mnemonic", "username", "network"].every((flag) => new RegExp(`(^|\\s)--${flag}[\\s=]`).test(help.stdout)))
+                throw new Error("Selected truAPI CLI has no supported attest command for caller-chosen entropy");
+            const startedAt = new Date().toISOString(), started = performance.now();
+            const parent = join(options.dataRoot, "identities", actor.id);
+            mkdirSync(parent, { recursive: true, mode: 0o700 });
+            const dir = mkdtempSync(join(parent, "attest-"));
+            const routingFile = join(dir, "host-network.json");
+            writeFileSync(routingFile, JSON.stringify(routes, null, 2) + "\n", { mode: 0o600 });
+            const routedEnv = { ...env, HOST_CLI_LOCAL_NETWORK_CONFIG: routingFile, TRUAPI_HOST_NO_UPDATE: "1" };
+            try {
+                await checkHost(binary.binary, options.routes, routedEnv, options.system.commands, signal);
+            }
+            catch (error) {
+                rmSync(dir, { recursive: true, force: true });
+                throw error;
+            }
+            writeFileSync(join(dir, "wallet.json"), JSON.stringify({ version: 1, entropy: Buffer.from(entropy).toString("hex") }) + "\n", { mode: 0o600 });
+            const temp = hostTempDir(dir, process.env.TMPDIR);
+            const unwrapped = {
+                command: binary.binary,
+                args: ["attest", "--network", options.routes.network, "--username", prefix],
+                cwd: dir,
+                env: { ...routedEnv, ...temp.env, HOST_CLI_SIGNER_MNEMONIC: mnemonic },
+            };
+            const sandbox = options.denyByDefault ? options.system.sandbox : undefined;
+            options.log?.(`attesting ${actor.id} with ${binary.label}; private state ${dir}`);
+            let output, exitCode;
+            try {
+                const plan = sandbox ? sandbox.denyNetworkExceptLoopback(unwrapped, scriptReadSandboxSpec(routes, join(dir, "sandbox"))) : unwrapped;
+                const result = await options.system.commands.run({ ...plan, timeoutMs, maxOutputBytes: 1024 * 1024, signal });
+                exitCode = result.code;
+                if (result.code !== 0)
+                    throw new Error("attest exited unsuccessfully");
+                output = result.stdout;
+            }
+            catch {
+                if (signal?.aborted) {
+                    const error = new Error(`CLI attestation aborted; private wallet retained at ${dir}`);
+                    error.name = "AbortError";
+                    throw error;
+                }
+                throw new Error(`CLI attestation failed or timed out${exitCode === undefined ? "" : ` (exit ${exitCode})`}; private wallet retained at ${dir}`);
+            }
+            finally {
+                temp.remove();
+            }
+            let answer;
+            try {
+                const last = output.trim().split(/\r?\n/).at(-1);
+                answer = resultSchema.parse(JSON.parse(last ?? ""));
+            }
+            catch {
+                throw new Error(`CLI attestation returned an invalid public result; private wallet retained at ${dir}`);
+            }
+            if (!answer.liteUsername.startsWith(`${prefix}.`))
+                throw new Error("CLI attestation returned a different username base");
+            validateAnswer(answer, entropy, options.routes.namespace, options.accounts);
+            const identity = { entropy, liteUsername: answer.liteUsername, identityAddress: answer.address };
+            const evidence = {
+                provisioner: "truapi-cli", mode: "attest", namespace: options.routes.namespace, actor: actor.id,
+                liteUsername: answer.liteUsername, identityAddress: answer.address, identityPublicKey: answer.publicKey.toLowerCase(),
+                fingerprint: identityFingerprint(identity), entropyBytes: entropy.length, dir,
+                host: { label: binary.label, origin: binary.origin, binarySha256: binary.binarySha256, archiveSha256: binary.archiveSha256, patches: binary.patches },
+                network: options.routes.network, people: routes.people.ws, identityBackend: routes.identity_backend_base,
+                sandbox: { used: !!sandbox, ...(sandbox?.mechanism ? { mechanism: sandbox.mechanism } : {}) },
+                startedAt, provisionMs: Math.round(performance.now() - started),
+            };
+            writeFileSync(join(dir, "provisioned.json"), JSON.stringify(evidence, null, 2) + "\n", { mode: 0o600 });
+            return { ...identity, evidence, source: `truapi-cli-attest:${dir}` };
+        },
+    };
+}
+export function readAttestedIdentity(dir, accounts, namespace) {
+    const directory = resolve(dir);
+    let wallet, evidence;
+    try {
+        if (process.platform !== "win32" && (statSync(directory).mode & 0o777) !== 0o700)
+            throw new Error("private directory permissions");
+        for (const file of ["wallet.json", "provisioned.json"]) {
+            if (process.platform !== "win32" && (statSync(join(directory, file)).mode & 0o777) !== 0o600)
+                throw new Error("private file permissions");
+        }
+        wallet = walletSchema.parse(JSON.parse(readFileSync(join(directory, "wallet.json"), "utf8")));
+        evidence = evidenceSchema.parse(JSON.parse(readFileSync(join(directory, "provisioned.json"), "utf8")));
+    }
+    catch {
+        throw new Error("Invalid CLI attestation record or private state permissions");
+    }
+    const entropy = Uint8Array.from(Buffer.from(wallet.entropy, "hex"));
+    assertBip39Entropy(entropy);
+    if (evidence.namespace !== namespace || resolve(evidence.dir) !== directory || evidence.fingerprint !== identityFingerprint({ entropy }) || evidence.entropyBytes !== entropy.length)
+        throw new Error("CLI attestation record does not match its private wallet");
+    const answer = resultSchema.safeParse({ address: evidence.identityAddress, publicKey: evidence.identityPublicKey, liteUsername: evidence.liteUsername });
+    if (!answer.success)
+        throw new Error("Invalid public identity in CLI attestation record");
+    validateAnswer(answer.data, entropy, namespace, accounts);
+    return { entropy, liteUsername: answer.data.liteUsername, identityAddress: answer.data.address, evidence, source: `truapi-cli-attest:${directory}` };
+}

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

@@ -0,0 +1,45 @@
+import type { CommandRunner } from "@parity/product-lab/ports/system";
+import { type AcquiredTruapiHost } from "./acquire.js";
+export interface BuildOptions {
+    /** Bounded one-shot commands for archive installation and build checks. */
+    commands?: CommandRunner;
+    patches: readonly string[];
+    /** host-rust-core commit to build (default: the manifest base of the patches). */
+    base?: string;
+    /** A local host-rust-core clone to add a worktree from (its working tree is never touched). */
+    repo?: string;
+    /** Where the checkout is created; must not exist (default: a new directory in the system's temporary directory). */
+    workdir?: string;
+    target?: string;
+    cacheDir?: string;
+    /** Run `cargo test -p truapi-host-cli` (default true). */
+    runTests?: boolean;
+    /** Keep the checkout and its cargo target directory (default false). */
+    keepWorkdir?: boolean;
+    /** Refuse to start below this much free disk space (default 15 GB). */
+    minFreeGb?: number;
+    log?: (line: string) => void;
+    signal?: AbortSignal;
+}
+export interface BuildStep {
+    name: string;
+    command: string;
+    ms: number;
+}
+export interface BuildResult {
+    host: AcquiredTruapiHost;
+    label: string;
+    patchset: string;
+    base: string;
+    steps: BuildStep[];
+    totalMs: number;
+    tests: {
+        ran: boolean;
+        summary?: string;
+    };
+    logFile: string;
+    targetDirBytes?: number;
+    workdirRemoved: boolean;
+}
+/** Build a patched truapi-host locally and install it into the cache. */
+export declare function buildPatchedHost(options: BuildOptions): Promise<BuildResult>;