reverseport 0.0.0-stage → 1.2.0

package/dist/process/ProcessOwnershipObservation.js

@@ -0,0 +1,407 @@
+import { readFile } from "node:fs/promises";
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import { launcherIdentityFailure } from "./ProcessOwnershipIdentity.js";
+import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
+import { execFileOutput } from "./ExecFileOutput.js";
+import { createDarwinProcessRunTokenReader } from "./DarwinProcessRunTokenReader.js";
+import { readProcessRunTokens } from "./ProcessRunTokenObservations.js";
+/** Observe multiple groups from one process snapshot and one token batch. */
+export const observeOwnedProcessGroups = async (runId, processGroupIds, host = systemProcessOwnershipHost, signal) => {
+    signal?.throwIfAborted();
+    const groupIds = [...new Set(processGroupIds)];
+    if (groupIds.length === 0)
+        return new Map();
+    let processes;
+    try {
+        processes = liveProcesses(await host.listProcesses(signal));
+    }
+    catch (cause) {
+        signal?.throwIfAborted();
+        const failure = {
+            state: "unverifiable",
+            reason: `process group could not be inspected: ${errorMessage(cause)}`,
+        };
+        return new Map(groupIds.map((groupId) => [groupId, failure]));
+    }
+    signal?.throwIfAborted();
+    const membersByGroup = new Map(groupIds.map((groupId) => [groupId, []]));
+    for (const process of processes)
+        membersByGroup.get(process.processGroupId)?.push(process);
+    const observations = new Map(groupIds.map((groupId) => [
+        groupId,
+        (membersByGroup.get(groupId)?.length ?? 0) > 0
+            ? { state: "alive" }
+            : { state: "empty" },
+    ]));
+    const liveMembers = groupIds.flatMap((groupId) => membersByGroup.get(groupId) ?? []);
+    const pendingGroups = new Set(groupIds.filter((groupId) => (membersByGroup.get(groupId)?.length ?? 0) > 0));
+    for await (const { process: member, observation } of readProcessRunTokens(host, liveMembers, signal)) {
+        if (!pendingGroups.has(member.processGroupId))
+            continue;
+        if (observation.state === "readable") {
+            if (observation.runId !== runId) {
+                observations.set(member.processGroupId, {
+                    state: "unverifiable",
+                    reason: "process ownership did not match",
+                });
+                pendingGroups.delete(member.processGroupId);
+            }
+        }
+        else {
+            const gone = await processIsGone(host, member.pid);
+            signal?.throwIfAborted();
+            if (!gone) {
+                observations.set(member.processGroupId, {
+                    state: "unverifiable",
+                    reason: `process ownership could not be revalidated for PID ${member.pid}: ${observation.reason}`,
+                });
+                pendingGroups.delete(member.processGroupId);
+            }
+        }
+        if (pendingGroups.size === 0)
+            break;
+    }
+    signal?.throwIfAborted();
+    return observations;
+};
+/**
+ * Record the live launcher and descendant lineage after run-token validation.
+ *
+ * The observation is intentionally point-in-time. A verified empty descendant
+ * list means no descendants were live during this observation, not that the
+ * run never created a short-lived child.
+ */
+export const observeOwnedProcessLineage = async (ownership, host = systemProcessOwnershipHost) => {
+    let processes;
+    try {
+        processes = liveProcesses(await host.listProcesses());
+    }
+    catch (cause) {
+        return unavailableLineage(ownership, `process table could not be inspected: ${errorMessage(cause)}`);
+    }
+    const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
+    if (launcher === undefined)
+        return unavailableLineage(ownership, "owned launcher is not live");
+    const identityFailure = launcherIdentityFailure(launcher, ownership);
+    if (identityFailure !== null)
+        return unavailableLineage(ownership, identityFailure);
+    const descendants = descendantsOf([launcher.pid], processes);
+    const verifiedDescendants = [];
+    for await (const { process: member, observation } of readProcessRunTokens(host, [launcher, ...descendants])) {
+        if (observation.state === "readable") {
+            if (observation.runId !== ownership.runId)
+                return unavailableLineage(ownership, "process lineage contains an unowned or PID-reused process");
+            if (member.pid !== launcher.pid)
+                verifiedDescendants.push(member);
+        }
+        else {
+            if (await processIsGone(host, member.pid)) {
+                if (member.pid === launcher.pid)
+                    return unavailableLineage(ownership, "owned launcher exited during lineage validation");
+                continue;
+            }
+            return unavailableLineage(ownership, `process ownership could not be revalidated for PID ${member.pid}: ${observation.reason}`);
+        }
+    }
+    return {
+        status: "verified",
+        observedAt: new Date().toISOString(),
+        lineage: {
+            runId: ownership.runId,
+            launcherPid: launcher.pid,
+            launcherParentPid: launcher.parentPid,
+            processGroupId: launcher.processGroupId,
+            descendants: verifiedDescendants
+                .sort((left, right) => left.pid - right.pid)
+                .map(({ pid, parentPid, processGroupId }) => ({
+                pid,
+                parentPid,
+                processGroupId,
+            })),
+        },
+    };
+};
+const unavailableLineage = (ownership, reason) => ({
+    status: "unavailable",
+    observedAt: new Date().toISOString(),
+    runId: ownership.runId,
+    launcherPid: ownership.leaderPid,
+    processGroupId: ownership.processGroupId,
+    reason,
+});
+/** Parse the NUL-delimited Linux process environment without nameless keys. */
+export const parseProcessEnvironment = (value) => Object.fromEntries(value
+    .split("\0")
+    .filter((entry) => entry.indexOf("=") > 0)
+    .map((entry) => {
+    const separator = entry.indexOf("=");
+    return [entry.slice(0, separator), entry.slice(separator + 1)];
+}));
+/** Read Linux stat field 22, tolerating spaces and closing parentheses in comm. */
+export const parseLinuxProcessStartTime = (value) => {
+    const commandEnd = value.lastIndexOf(")");
+    if (commandEnd < 0)
+        return undefined;
+    const fields = value
+        .slice(commandEnd + 1)
+        .trim()
+        .split(/\s+/u);
+    const startTime = fields[19];
+    return startTime !== undefined && /^\d+$/u.test(startTime)
+        ? startTime
+        : undefined;
+};
+const isExpectedAbort = (cause, signal) => signal?.aborted === true &&
+    (cause === signal.reason ||
+        (cause instanceof Error && cause.name === "AbortError"));
+/** Create the operating-system process inspector for an explicit host context. */
+export const createSystemProcessOwnershipHost = (platform = process.platform, hostEnvironment = process.env, options = {}) => {
+    const darwinTokens = platform === "darwin"
+        ? createDarwinProcessRunTokenReader(options.darwinXcrun === undefined
+            ? {}
+            : { xcrun: options.darwinXcrun })
+        : undefined;
+    const listProcesses = async (signal) => {
+        if (platform === "win32")
+            return [];
+        const { stdout } = await execFileOutput("ps", ["-axo", "pid=,ppid=,pgid=,uid=,stat=,command="], { env: hostEnvironment, ...(signal === undefined ? {} : { signal }) });
+        return stdout
+            .split("\n")
+            .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)/u.exec(line))
+            .filter((match) => match !== null)
+            .map((match) => ({
+            pid: Number(match[1]),
+            parentPid: Number(match[2]),
+            processGroupId: Number(match[3]),
+            uid: Number(match[4]),
+            state: match[5] ?? "",
+            command: match[6] ?? "",
+        }));
+    };
+    const processIdentities = async (processes, signal) => {
+        if (processes.length === 0)
+            return new Map();
+        if (platform === "linux")
+            return new Map(await Promise.all(processes.map(async ({ pid }) => {
+                try {
+                    const stat = await readFile(`/proc/${String(pid)}/stat`, {
+                        encoding: "utf8",
+                        ...(signal === undefined ? {} : { signal }),
+                    });
+                    const identity = parseLinuxProcessStartTime(stat);
+                    return [
+                        pid,
+                        identity === undefined
+                            ? {
+                                state: "unavailable",
+                                reason: "malformed_proc_stat",
+                            }
+                            : {
+                                state: "readable",
+                                identity: `linux-starttime:${identity}`,
+                            },
+                    ];
+                }
+                catch (cause) {
+                    if (isExpectedAbort(cause, signal))
+                        throw cause;
+                    return [
+                        pid,
+                        { state: "unavailable", reason: errorMessage(cause) },
+                    ];
+                }
+            })));
+        if (darwinTokens === undefined)
+            return new Map();
+        try {
+            return await darwinTokens.identities(processes, signal);
+        }
+        catch (cause) {
+            if (isExpectedAbort(cause, signal))
+                throw cause;
+            const reason = errorMessage(cause);
+            return new Map(processes.map(({ pid }) => [
+                pid,
+                { state: "unavailable", reason },
+            ]));
+        }
+    };
+    const captureBaseline = async (signal) => {
+        if (platform !== "linux" && darwinTokens === undefined)
+            return [];
+        const processes = liveProcesses(await listProcesses(signal));
+        let identities = await processIdentities(processes, signal);
+        const unreadable = processes.filter(({ pid }) => identities.get(pid)?.state !== "readable");
+        if (unreadable.length > 0) {
+            const stillLive = liveProcesses(await listProcesses(signal)).filter(({ pid }) => unreadable.some((entry) => entry.pid === pid));
+            const retried = await processIdentities(stillLive, signal);
+            identities = new Map([...identities, ...retried]);
+            const unresolved = stillLive.filter(({ pid }) => identities.get(pid)?.state !== "readable");
+            const liveAfterRetry = liveProcesses(await listProcesses(signal));
+            const stillUnresolved = unresolved.filter(({ pid }) => liveAfterRetry.some((entry) => entry.pid === pid));
+            if (stillUnresolved.length > 0)
+                throw new Error(`process identity snapshot is unavailable for ${String(stillUnresolved.length)} live processes`);
+        }
+        return processes.map(({ pid }) => {
+            const observation = identities.get(pid);
+            return {
+                pid,
+                identity: observation?.state === "readable" ? observation.identity : null,
+            };
+        });
+    };
+    return {
+        platform,
+        prepare: async (signal) => {
+            await darwinTokens?.prepare(signal);
+            if (platform === "linux") {
+                try {
+                    const processes = await listProcesses(signal);
+                    if (!processes.some(({ pid }) => pid === process.pid))
+                        throw new Error("ps did not report REA's current process");
+                }
+                catch (cause) {
+                    if (isExpectedAbort(cause, signal))
+                        throw cause;
+                    const reason = `Linux process ownership inspection requires a procps-compatible ps on REA's PATH before launching a child: ${errorMessage(cause)}`;
+                    throw new AnalysisCapabilityUnavailableError("process-ownership", "prepare_owned_process", reason, { cause, userMessage: reason });
+                }
+            }
+        },
+        listProcesses,
+        async environment(pid, signal) {
+            signal?.throwIfAborted();
+            if (platform === "linux")
+                return parseProcessEnvironment(await readFile(`/proc/${pid}/environ`, { encoding: "utf8", signal }));
+            if (platform === "darwin") {
+                const process = (await listProcesses(signal)).find((entry) => entry.pid === pid);
+                if (process === undefined)
+                    throw new Error(`process ${String(pid)} is not live`);
+                const observation = (await darwinTokens?.read([process], signal))?.get(pid);
+                if (observation === undefined || observation.state === "unavailable")
+                    throw new Error(observation?.reason ?? "process run token could not be read");
+                return observation.runId === undefined
+                    ? {}
+                    : { REA_PROCESS_RUN_ID: observation.runId };
+            }
+            const { stdout } = await execFileOutput("ps", ["eww", "-p", String(pid)], {
+                env: hostEnvironment,
+                ...(signal === undefined ? {} : { signal }),
+            });
+            const observedEnvironment = {};
+            for (const match of stdout.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s]*)/gu)) {
+                const name = match[1];
+                if (name !== undefined)
+                    observedEnvironment[name] = match[2] ?? "";
+            }
+            return observedEnvironment;
+        },
+        async runTokens(processes, signal) {
+            signal?.throwIfAborted();
+            if (platform !== "darwin" || processes.length === 0)
+                return new Map();
+            try {
+                return (await darwinTokens?.read(processes, signal)) ?? new Map();
+            }
+            catch (cause) {
+                if (isExpectedAbort(cause, signal))
+                    throw cause;
+                void cause;
+                return new Map(processes.map(({ pid }) => [
+                    pid,
+                    { state: "unavailable", reason: "reader_failure" },
+                ]));
+            }
+        },
+        ...(platform !== "linux" && darwinTokens === undefined
+            ? {}
+            : {
+                processIdentities,
+                captureBaseline,
+                ...(darwinTokens === undefined ? {} : { close: darwinTokens.close }),
+            }),
+        signalGroup(processGroupId, signal) {
+            process.kill(-processGroupId, signal);
+        },
+    };
+};
+export const systemProcessOwnershipHost = createSystemProcessOwnershipHost();
+/**
+ * Observe a live PID's start identity, optionally binding it to an owned run.
+ * Token validation is bracketed by identity reads so PID reuse cannot supply
+ * the first identity of a different process for an owned launch.
+ */
+export const observeProcessStartIdentity = async (pid, host = systemProcessOwnershipHost, expectedRunId) => {
+    const process = (await host.listProcesses()).find((entry) => entry.pid === pid);
+    if (process === undefined || liveProcesses([process]).length === 0)
+        return undefined;
+    if (host.processIdentities === undefined)
+        return { state: "unavailable", reason: "process identity is unsupported" };
+    const identity = (await host.processIdentities([process])).get(pid) ?? {
+        state: "unavailable",
+        reason: "process identity was not returned",
+    };
+    if (expectedRunId === undefined || identity.state !== "readable")
+        return identity;
+    let owned = false;
+    for await (const { observation } of readProcessRunTokens(host, [process])) {
+        if (observation.state === "unavailable")
+            return {
+                state: "unavailable",
+                reason: `process ownership token could not be read for PID ${String(pid)}: ${observation.reason}`,
+            };
+        if (observation.runId !== expectedRunId)
+            return {
+                state: "unavailable",
+                reason: `process ownership token did not match the captured run for PID ${String(pid)}`,
+            };
+        owned = true;
+    }
+    if (!owned)
+        return {
+            state: "unavailable",
+            reason: `process ownership token was not returned for PID ${String(pid)}`,
+        };
+    const confirmed = await observeProcessStartIdentity(pid, host);
+    if (confirmed === undefined || confirmed.state !== "readable")
+        return confirmed;
+    return confirmed.identity === identity.identity
+        ? identity
+        : {
+            state: "unavailable",
+            reason: `process identity changed while validating the captured run token for PID ${String(pid)}`,
+        };
+};
+/** Revalidate a launch-time start identity immediately before signaling a PID. */
+export const signalProcessWithStartIdentity = async (pid, expectedIdentity, signal, options = {}) => {
+    const host = options.host ?? systemProcessOwnershipHost;
+    try {
+        const observed = await observeProcessStartIdentity(pid, host);
+        if (observed === undefined)
+            return "gone";
+        if (observed.state !== "readable")
+            return "unverified";
+        if (observed.identity !== expectedIdentity)
+            return "identity-changed";
+        (options.sendSignal ?? process.kill)(pid, signal);
+        return "signaled";
+    }
+    catch {
+        return "unverified";
+    }
+};
+/** Prepare native token inspection before REA launches a captured child. */
+export const prepareProcessOwnershipInspection = async (signal) => {
+    await systemProcessOwnershipHost.prepare?.(signal);
+};
+const processIsGone = async (host, pid) => {
+    try {
+        return !liveProcesses(await host.listProcesses()).some((process) => process.pid === pid);
+    }
+    catch (cause) {
+        // best-effort cleanup: optional liveness probing; failure means not gone.
+        void cause;
+        return false;
+    }
+};
+export const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/process/ProcessOwnershipProcessTree.js

@@ -0,0 +1,35 @@
+/** Exclude process-table entries that the operating system has already reaped. */
+export const liveProcesses = (members) => members.filter(({ state }) => !state.startsWith("Z"));
+/** Return every live-table descendant of the selected roots in breadth-first order. */
+export const descendantsOf = (rootPids, processes) => {
+    const childrenByParent = new Map();
+    for (const process of processes) {
+        const siblings = childrenByParent.get(process.parentPid) ?? [];
+        siblings.push(process);
+        childrenByParent.set(process.parentPid, siblings);
+    }
+    const descendants = [];
+    const pending = rootPids.flatMap((pid) => childrenByParent.get(pid) ?? []);
+    const visited = new Set(rootPids);
+    for (const process of pending) {
+        if (visited.has(process.pid))
+            continue;
+        visited.add(process.pid);
+        descendants.push(process);
+        pending.push(...(childrenByParent.get(process.pid) ?? []));
+    }
+    return descendants;
+};
+/** Select the PTY root group and groups led by an observed captured process. */
+export const selectCapturedProcessGroupIds = (rootPid, samples) => {
+    const processGroupIds = new Set([rootPid]);
+    for (const sample of samples) {
+        // A sampled member may transiently inherit an unrelated group. POSIX group
+        // leaders have pid === pgid, so only that observation establishes that the
+        // group leader itself belonged to the captured tree. Token checks below
+        // remain the final authority immediately before observation or signaling.
+        if (sample.pid === sample.process_group_id)
+            processGroupIds.add(sample.pid);
+    }
+    return [...processGroupIds];
+};

package/dist/process/ProcessRunTokenObservations.js

@@ -0,0 +1,48 @@
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Read only ownership tokens, using per-process fallback for missing batch rows. */
+export async function* readProcessRunTokens(host, processes, signal) {
+    signal?.throwIfAborted();
+    if (processes.length === 0)
+        return;
+    let batch;
+    let batchFailure;
+    if (host.runTokens !== undefined) {
+        try {
+            batch =
+                signal === undefined
+                    ? await host.runTokens(processes)
+                    : await host.runTokens(processes, signal);
+        }
+        catch (cause) {
+            signal?.throwIfAborted();
+            batchFailure = errorMessage(cause);
+        }
+    }
+    for (const process of processes) {
+        signal?.throwIfAborted();
+        let observation = batch?.get(process.pid);
+        if (observation === undefined) {
+            try {
+                const environment = signal === undefined
+                    ? await host.environment(process.pid)
+                    : await host.environment(process.pid, signal);
+                observation = {
+                    state: "readable",
+                    runId: environment.REA_PROCESS_RUN_ID,
+                };
+            }
+            catch (cause) {
+                signal?.throwIfAborted();
+                const reason = errorMessage(cause);
+                observation = {
+                    state: "unavailable",
+                    reason: batchFailure === undefined
+                        ? reason
+                        : `${reason}; run-token batch failed: ${batchFailure}`,
+                };
+            }
+        }
+        signal?.throwIfAborted();
+        yield { process, observation };
+    }
+}

package/dist/process/ProviderDeadline.js

@@ -0,0 +1,91 @@
+/** Wait for an interval while removing the supplied abort listener on settle. */
+export const waitForAbortableDelay = (milliseconds, signal) => {
+    if (signal?.aborted === true)
+        return Promise.resolve("aborted");
+    return new Promise((resolve) => {
+        const settle = (result) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
+        const onAbort = () => settle("aborted");
+        const timer = setTimeout(() => settle("elapsed"), Math.max(0, milliseconds));
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+};
+/**
+ * One absolute deadline shared by every phase of a provider startup handshake.
+ *
+ * The deadline owns its timer and the listener attached to an optional caller
+ * signal. Adapters must dispose it after startup succeeds or fails.
+ */
+export class ProviderStartupDeadline {
+    timeoutMs;
+    #controller = new AbortController();
+    #deadlineAt;
+    #externalSignal;
+    #onExternalAbort;
+    #timer;
+    #interruption;
+    constructor(timeoutMs, signal) {
+        this.timeoutMs = timeoutMs;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new RangeError("Provider startup timeout must be positive");
+        this.#deadlineAt = Date.now() + timeoutMs;
+        this.#externalSignal = signal;
+        this.#onExternalAbort = () => {
+            if (this.#controller.signal.aborted)
+                return;
+            if (Date.now() >= this.#deadlineAt) {
+                this.#interruption = "timeout";
+                this.#abort(new DOMException("Provider startup deadline elapsed", "TimeoutError"));
+                return;
+            }
+            this.#interruption = "cancelled";
+            this.#abort(signal?.reason);
+        };
+        if (signal?.aborted === true) {
+            this.#onExternalAbort();
+            return;
+        }
+        signal?.addEventListener("abort", this.#onExternalAbort, { once: true });
+        this.#timer = setTimeout(() => {
+            if (this.#controller.signal.aborted)
+                return;
+            this.#interruption = "timeout";
+            this.#abort(new DOMException("Provider startup deadline elapsed", "TimeoutError"));
+        }, timeoutMs);
+    }
+    /** Composite signal aborted by either the caller or the absolute deadline. */
+    get signal() {
+        return this.#controller.signal;
+    }
+    /** First control path that interrupted startup, if any. */
+    get interruption() {
+        return (this.#interruption ??
+            (Date.now() >= this.#deadlineAt ? "timeout" : undefined));
+    }
+    /** Milliseconds still available to the next startup phase. */
+    remainingMs() {
+        return Math.max(0, this.#deadlineAt - Date.now());
+    }
+    /** Wait for at most one polling interval under the shared deadline signal. */
+    wait(milliseconds) {
+        return waitForAbortableDelay(Math.min(milliseconds, this.remainingMs()), this.signal);
+    }
+    /** Release the deadline timer and external abort listener. */
+    dispose() {
+        this.#clearTimer();
+        this.#externalSignal?.removeEventListener("abort", this.#onExternalAbort);
+    }
+    #abort(reason) {
+        this.#clearTimer();
+        this.#externalSignal?.removeEventListener("abort", this.#onExternalAbort);
+        this.#controller.abort(reason);
+    }
+    #clearTimer() {
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+}

package/dist/process/ProviderDiagnosticRedaction.js

@@ -0,0 +1,17 @@
+/** Redact explicit transport credentials from complete and budget-cut output. */
+export const redactCapturedTransportCredential = (stream, token, replacement) => {
+    if (token === undefined || token.length === 0)
+        return stream.text;
+    const { text } = stream;
+    const cutOff = stream.observedBytes > stream.bytes;
+    if (cutOff && !text.endsWith(token)) {
+        const maximumPrefixLength = Math.min(text.length, token.length - 1);
+        for (let prefixLength = maximumPrefixLength; prefixLength > 0; prefixLength -= 1) {
+            if (text.endsWith(token.slice(0, prefixLength)))
+                return `${text
+                    .slice(0, text.length - prefixLength)
+                    .replaceAll(token, replacement)}${replacement}`;
+        }
+    }
+    return text.replaceAll(token, replacement);
+};