reverseport 0.0.0-stage → 1.2.0

package/dist/serverIdentity.js

@@ -0,0 +1,69 @@
+import { dirname, basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CATALOG_IDENTITY } from "./catalogIdentity.js";
+import { PRODUCT_IDENTITY, SDK_IDENTITY } from "./identity.js";
+const packageRoot = () => {
+    const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+    return basename(moduleDirectory) === "src" &&
+        basename(dirname(moduleDirectory)) === "dist"
+        ? resolve(moduleDirectory, "../..")
+        : resolve(moduleDirectory, "..");
+};
+/** Build one runtime identity without claiming alignment from absent observations. */
+export const createServerIdentity = (input) => {
+    const serverPath = resolve(process.argv[1] ?? "unknown");
+    const reasons = [];
+    if (input.expected?.package_version !== undefined &&
+        input.expected.package_version !== PRODUCT_IDENTITY.packageVersion)
+        reasons.push("package_version_mismatch");
+    if (input.expected?.catalog_digest !== undefined &&
+        input.expected.catalog_digest !== CATALOG_IDENTITY.digests.combined_sha256)
+        reasons.push("catalog_digest_mismatch");
+    if (input.expected?.server_path !== undefined &&
+        resolve(input.expected.server_path) !== serverPath)
+        reasons.push("registration_path_mismatch");
+    const observedExpectation = input.expected !== undefined &&
+        Object.values(input.expected).some((value) => value !== undefined);
+    return {
+        package: {
+            name: PRODUCT_IDENTITY.packageName,
+            version: PRODUCT_IDENTITY.packageVersion,
+            root_path: packageRoot(),
+            build_commit: process.env.REA_BUILD_COMMIT ?? null,
+        },
+        server: {
+            name: PRODUCT_IDENTITY.mcpServerKey,
+            version: PRODUCT_IDENTITY.packageVersion,
+            started_at: input.startedAt,
+            command_path: serverPath,
+        },
+        sdk: SDK_IDENTITY,
+        negotiated_protocol_version: input.protocolVersion ?? null,
+        client: input.client === undefined
+            ? null
+            : { name: input.client.name, version: input.client.version },
+        skill: {
+            name: PRODUCT_IDENTITY.skillName,
+            expected_version: PRODUCT_IDENTITY.skillVersion,
+        },
+        catalog: CATALOG_IDENTITY,
+        protocol_features: {
+            progress: true,
+            cancellation: true,
+            elicitation: false,
+        },
+        alignment: {
+            state: reasons.length > 0
+                ? "mcp_server_restart_required"
+                : observedExpectation
+                    ? "aligned"
+                    : "unknown",
+            reasons,
+            remediation: reasons.length > 0
+                ? "Restart the registered MCP server/client, then compare identity again."
+                : observedExpectation
+                    ? null
+                    : "Supply expected package, catalog, or registration identity to compare the live server.",
+        },
+    };
+};

package/dist/wasm/WabtArtifactProvider.js

@@ -0,0 +1,313 @@
+import { randomUUID, createHash } from "node:crypto";
+import { access, realpath, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { createAnalysisExecution } from "../application/AnalysisProvider.js";
+import { readStableArtifact } from "../artifacts/readStableArtifact.js";
+import { AnalysisCancelledError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { createEvidence } from "../domain/evidence.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { wasmArtifactSchema, } from "../domain/wasm/wasmArtifact.js";
+import { err, ok } from "../domain/result.js";
+import { runOwnedCommand } from "../process/OwnedCommand.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { WABT_PROVIDER_IDENTITY, WABT_LIMITS } from "./WabtRelease.js";
+import { wabtFailure } from "./WabtFailures.js";
+import { parseWabtOutput } from "./WabtOutput.js";
+import { parseWabtWat } from "./WabtWat.js";
+import { associateWasmGlue } from "./WasmGlueAdapter.js";
+const OPERATION = "inspect_wasm_artifact";
+const digest = (text) => createHash("sha256").update(text).digest("hex");
+/** Run caller-supplied WABT against private copies of exactly selected bytes. */
+export class WabtArtifactProvider {
+    environment;
+    launcher;
+    createRuntime;
+    #pendingRoots = new Set();
+    constructor(environment = process.env, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-wabt-" })) {
+        this.environment = environment;
+        this.launcher = launcher;
+        this.createRuntime = createRuntime;
+    }
+    /** Retry retained cleanup without discarding roots that still cannot be removed. */
+    async close() {
+        const failures = [];
+        for (const root of this.#pendingRoots) {
+            try {
+                await root.close();
+                this.#pendingRoots.delete(root);
+            }
+            catch (cause) {
+                failures.push({
+                    path: root.path,
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                });
+            }
+        }
+        if (failures.length > 0)
+            throw new ProviderCleanupError(WABT_PROVIDER_IDENTITY.id, failures.map(({ path }) => path), { failures }, { operation: OPERATION });
+    }
+    async inspect(input, options) {
+        let root;
+        let phase = "configuration";
+        let result;
+        let capturedOutput;
+        try {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION);
+            await this.close();
+            const directory = this.environment.REA_WABT_BIN_DIRECTORY ?? "";
+            if (!isAbsolute(directory))
+                throw new Error("REA_WABT_BIN_DIRECTORY must be an absolute tool directory.");
+            const commands = [];
+            for (const tool of ["wasm-validate", "wasm-objdump", "wasm2wat"]) {
+                const path = await realpath(join(directory, `${tool}${process.platform === "win32" ? ".exe" : ""}`));
+                await access(path, constants.X_OK);
+                const binary = await readStableArtifact(path, WABT_LIMITS.toolBytes, options?.signal);
+                commands.push({
+                    tool,
+                    path,
+                    sha256: binary.sha256,
+                    version_banner: "",
+                    arguments: tool === "wasm-objdump"
+                        ? ["-h", "-x", "module.wasm"]
+                        : ["--enable-all", "module.wasm"],
+                });
+            }
+            root = await this.createRuntime();
+            const snapshotPath = join(root.path, "module.wasm");
+            let snapshotHash;
+            const verifySnapshot = async () => {
+                if (snapshotHash === undefined)
+                    return;
+                try {
+                    const bytes = await readStableArtifact(snapshotPath, WABT_LIMITS.inputBytes, options?.signal);
+                    if (bytes.sha256 !== snapshotHash)
+                        throw new Error("Private WASM snapshot bytes changed.");
+                }
+                catch (cause) {
+                    if (options?.signal?.aborted)
+                        throw new AnalysisCancelledError(OPERATION);
+                    throw new AnalysisArtifactChangedError(OPERATION, input.path, "Private WASM snapshot no longer matches selected byte identity.", { cause });
+                }
+            };
+            const execute = async (command, args, acceptNonZeroExit = false) => {
+                await verifySnapshot();
+                const snapshot = await runOwnedCommand({
+                    command: command.path,
+                    arguments: args,
+                    ...(root === undefined ? {} : { cwd: root.path }),
+                    expectedCommand: command.path,
+                    runId: `rea-wabt-${randomUUID()}`,
+                    hostEnvironment: this.environment,
+                }, {
+                    timeoutMs: WABT_LIMITS.timeoutMs,
+                    diagnosticBytes: WABT_LIMITS.outputBytes,
+                    acceptNonZeroExit,
+                }, {
+                    ...(options?.signal === undefined
+                        ? {}
+                        : { signal: options.signal }),
+                    ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+                });
+                const current = await readStableArtifact(command.path, WABT_LIMITS.toolBytes, options?.signal);
+                if (current.sha256 !== command.sha256)
+                    throw new AnalysisOutputError(OPERATION, "Configured WABT executable changed during inspection.");
+                await verifySnapshot();
+                return snapshot;
+            };
+            for (const command of commands) {
+                const version = await execute(command, ["--version"]);
+                if (version.stdout.text.trim() !== "1.0.42" ||
+                    version.stderr.text !== "")
+                    throw new Error(`Unsupported ${command.tool} version banner; expected 1.0.42.`);
+                command.version_banner = version.stdout.text;
+            }
+            phase = "artifact";
+            const selected = await readStableArtifact(input.path, WABT_LIMITS.inputBytes, options?.signal);
+            const artifact = {
+                path: input.path,
+                sha256: selected.sha256,
+                bytes: selected.bytes.length,
+            };
+            const candidates = [];
+            for (const path of new Set([input.path, ...input.candidate_paths])) {
+                const bytes = path === input.path
+                    ? selected
+                    : await readStableArtifact(path, WABT_LIMITS.inputBytes, options?.signal);
+                candidates.push({
+                    path,
+                    sha256: bytes.sha256,
+                    bytes: bytes.bytes.length,
+                });
+            }
+            const glue = [];
+            for (const path of input.glue_paths) {
+                const bytes = await readStableArtifact(path, WABT_LIMITS.inputBytes, options?.signal);
+                const source = new TextDecoder("utf-8", { fatal: true }).decode(bytes.bytes);
+                glue.push({
+                    artifact: { path, sha256: bytes.sha256, bytes: bytes.bytes.length },
+                    ...associateWasmGlue(source, path, candidates.map((candidate) => candidate.path)),
+                });
+            }
+            await writeFile(snapshotPath, selected.bytes, {
+                flag: "wx",
+                mode: 0o400,
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            });
+            snapshotHash = selected.sha256;
+            phase = "producer";
+            const [validate, objdump, decode] = commands;
+            if (validate === undefined ||
+                objdump === undefined ||
+                decode === undefined)
+                throw new Error("Incomplete WABT tool profile.");
+            const validation = await execute(validate, validate.arguments, true);
+            if (validation.exitCode !== 0)
+                throw new AnalysisInputError(OPERATION, {
+                    partialObservation: createEvidence({ path: input.path, format: "file", sha256: selected.sha256 }, WABT_PROVIDER_IDENTITY, {
+                        operation: OPERATION,
+                        parameters: input,
+                        result: {
+                            artifact,
+                            validation: "rejected-by-selected-profile",
+                            tool_profile: {
+                                source: "https://github.com/WebAssembly/wabt",
+                                release: "1.0.42",
+                                source_commit: "ff0ef7e0009402740c805a9744c09b05be063e48",
+                                commands,
+                            },
+                            exit_code: validation.exitCode ?? null,
+                            stdout: validation.stdout.text,
+                            stderr: validation.stderr.text,
+                        },
+                        confidence: "observed",
+                        locations: [{ kind: "artifact-path", path: input.path }],
+                        limitations: [
+                            "WABT rejected these exact selected bytes with --enable-all; no complete inspection or target execution occurred.",
+                        ],
+                    }),
+                    capturedOutput: {
+                        stdout: validation.stdout.text,
+                        stderr: validation.stderr.text,
+                        truncated: false,
+                    },
+                }, [
+                    {
+                        path: ["path"],
+                        reason: "invalid_format",
+                        message: "Selected bytes failed WABT validation with --enable-all; inspect retained upstream diagnostics.",
+                    },
+                ]);
+            const dump = await execute(objdump, objdump.arguments);
+            capturedOutput = {
+                stdout: dump.stdout.text,
+                stderr: dump.stderr.text,
+                truncated: false,
+            };
+            if (dump.stderr.text !== "")
+                throw new AnalysisOutputError(OPERATION, "Unexpected WABT section output.");
+            const wat = await execute(decode, decode.arguments);
+            capturedOutput = {
+                stdout: wat.stdout.text,
+                stderr: wat.stderr.text,
+                truncated: false,
+            };
+            if (!wat.stdout.text.startsWith("(module") || wat.stderr.text !== "")
+                throw new AnalysisOutputError(OPERATION, "Unexpected WABT decoding output.");
+            const { imports, exports, customSectionNames, debugModuleNames } = parseWabtWat(wat.stdout.text);
+            capturedOutput = {
+                stdout: dump.stdout.text,
+                stderr: dump.stderr.text,
+                truncated: false,
+            };
+            const { sections, headers, details } = parseWabtOutput(dump.stdout.text, artifact.bytes, customSectionNames, debugModuleNames);
+            const limitations = [
+                "WAT is a decoded representation, not original source or proof of runtime behavior. Custom annotations may retain payloads, but WAT does not establish original binary layout or round-trip byte identity. Original bytes and objdump output remain authoritative.",
+                "Imports and exports retain exact top-level WABT WAT forms. Names remain escaped producer text; unescaped objdump display names are not parsed as unambiguous identifiers.",
+                "JavaScript references are AST-observed static literals only. Candidate matches are associations, not proven data flow, URL-to-file identity or runtime loading. Computed references and aliases are not resolved.",
+                "No target execution or implicit fetch. WABT tools are trusted caller-supplied executables; SHA-256 identifies their bytes, not publisher authenticity. No OS memory sandbox is claimed.",
+                "Each subprocess has a 30-second deadline and 32 MiB combined output budget. Oversized output fails instead of producing truncated success.",
+            ];
+            const report = wasmArtifactSchema.parse({
+                artifact,
+                validation: "valid",
+                sections,
+                imports,
+                exports,
+                headers,
+                details,
+                wat: {
+                    text: wat.stdout.text,
+                    sha256: digest(wat.stdout.text),
+                    representation: "decoded-wat",
+                },
+                tool_profile: {
+                    source: "https://github.com/WebAssembly/wabt",
+                    release: "1.0.42",
+                    source_commit: "ff0ef7e0009402740c805a9744c09b05be063e48",
+                    commands,
+                    timeout_ms: WABT_LIMITS.timeoutMs,
+                    output_budget_bytes: WABT_LIMITS.outputBytes,
+                },
+                candidates,
+                glue,
+                runtime_execution: "not-performed",
+                network_fetch: "not-performed",
+                limitations,
+            });
+            result = ok(createAnalysisExecution(report, WABT_PROVIDER_IDENTITY, {
+                subject: {
+                    path: input.path,
+                    format: "file",
+                    sha256: selected.sha256,
+                },
+                locations: [{ kind: "artifact-path", path: input.path }],
+                limitations,
+            }));
+        }
+        catch (cause) {
+            const failure = wabtFailure(cause, phase, input.path);
+            result = err(failure instanceof AnalysisOutputError &&
+                failure.capturedOutput === undefined &&
+                capturedOutput !== undefined
+                ? new AnalysisOutputError(OPERATION, failure.reason, {
+                    cause,
+                    capturedOutput,
+                })
+                : failure);
+        }
+        if (root !== undefined) {
+            try {
+                await root.close();
+            }
+            catch (cause) {
+                this.#pendingRoots.add(root);
+                const partialObservation = result.ok
+                    ? createEvidence(result.value.subject ?? undefined, result.value.provider, {
+                        operation: OPERATION,
+                        parameters: input,
+                        result: result.value.result,
+                        confidence: "observed",
+                        locations: result.value.locations,
+                        limitations: result.value.limitations,
+                    })
+                    : result.error.partialObservation;
+                result = err(new ProviderCleanupError(WABT_PROVIDER_IDENTITY.id, [root.path], {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    previous_error: result.ok
+                        ? null
+                        : projectAnalysisError(result.error),
+                }, {
+                    operation: OPERATION,
+                    cause,
+                    ...(partialObservation === undefined
+                        ? {}
+                        : { partialObservation }),
+                }));
+            }
+        }
+        return result;
+    }
+}

package/dist/wasm/WabtFailures.js

@@ -0,0 +1,62 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisArtifactChangedError, AnalysisAccessDeniedError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { OwnedCommandFailure } from "../process/OwnedCommand.js";
+import { WABT_LIMITS, WABT_PROVIDER_IDENTITY } from "./WabtRelease.js";
+/** Preserve lifecycle failures and diagnostic bytes instead of returning partial success. */
+export const wabtFailure = (cause, phase, path) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    if ((cause instanceof ArtifactReaderFailure && cause.reason === "cancelled") ||
+        (cause instanceof Error && cause.name === "AbortError"))
+        return new AnalysisCancelledError("inspect_wasm_artifact", { cause });
+    if (cause instanceof OwnedCommandFailure) {
+        const capturedOutput = cause.snapshot === null
+            ? undefined
+            : {
+                stdout: cause.snapshot.stdout.text,
+                stderr: cause.snapshot.stderr.text,
+                truncated: cause.snapshot.diagnosticTruncated ?? false,
+            };
+        const options = capturedOutput === undefined ? { cause } : { cause, capturedOutput };
+        if (cause.cleanupFailure !== null)
+            return new ProviderCleanupError(WABT_PROVIDER_IDENTITY.id, cause.resources, {
+                reason: cause.cleanupFailure,
+                previous_error: reason,
+                ...(capturedOutput === undefined
+                    ? {}
+                    : { captured_output: capturedOutput }),
+            }, { operation: "inspect_wasm_artifact", cause });
+        if (cause.reason === "cancelled")
+            return new AnalysisCancelledError("inspect_wasm_artifact", options);
+        if (cause.reason === "timeout")
+            return new AnalysisTimeoutError("inspect_wasm_artifact", WABT_LIMITS.timeoutMs, options);
+        if (phase === "configuration" && cause.reason === "process")
+            return new AnalysisCapabilityUnavailableError(WABT_PROVIDER_IDENTITY.id, "inspect_wasm_artifact", reason, {
+                ...options,
+                userMessage: "Configured WABT could not start. Check executable/interpreter access and WABT 1.0.42 profile; inspect retained diagnostics.",
+            });
+        return new AnalysisOutputError("inspect_wasm_artifact", reason, options);
+    }
+    if (phase === "configuration")
+        return new AnalysisCapabilityUnavailableError(WABT_PROVIDER_IDENTITY.id, "inspect_wasm_artifact", reason, {
+            cause,
+            userMessage: `${reason} Supply WABT 1.0.42 via absolute REA_WABT_BIN_DIRECTORY; REA does not install tools.`,
+        });
+    if (phase === "artifact" &&
+        cause instanceof ArtifactReaderFailure &&
+        cause.reason === "integrity")
+        return new AnalysisArtifactChangedError("inspect_wasm_artifact", path, reason, { cause });
+    if (phase === "artifact" &&
+        cause instanceof Error &&
+        "code" in cause &&
+        (cause.code === "EACCES" || cause.code === "EPERM"))
+        return new AnalysisAccessDeniedError("inspect_wasm_artifact", path, cause.code, { cause });
+    if (phase === "artifact")
+        return new AnalysisInputError("inspect_wasm_artifact", { cause }, [
+            { path: ["path"], reason: "invalid_value", message: reason },
+        ]);
+    return new AnalysisOutputError("inspect_wasm_artifact", reason, { cause });
+};

package/dist/wasm/WabtOutput.js

@@ -0,0 +1,60 @@
+/** WABT prints names with %.*s, so an embedded NUL ends their display. */
+const wabtDisplayedName = (name) => name?.split("\0", 1)[0];
+/** Frame WABT's raw custom names using the ordered names from its escaped WAT output. */
+export const parseWabtOutput = (text, artifactBytes, customSectionNames, debugModuleNames = []) => {
+    const preamble = "\nmodule.wasm:\tfile format wasm 0x1\n" +
+        debugModuleNames
+            .map((name) => `module name: <${wabtDisplayedName(name)}>\n`)
+            .join("");
+    const prefix = `${preamble}\nSections:\n\n`;
+    if (!text.startsWith(prefix))
+        throw new Error("Unsupported WABT section header format.");
+    let offset = prefix.length;
+    let customIndex = 0;
+    const sections = [];
+    while (!text.startsWith("\nSection Details:\n", offset)) {
+        const match = /^[ \t]*(\w+) start=0x([\da-f]+) end=0x([\da-f]+) \(size=0x([\da-f]+)\) /u.exec(text.slice(offset));
+        if (match === null)
+            throw new Error("Unrecognized WABT section row.");
+        offset += match[0].length;
+        let description;
+        if (match[1] === "Custom") {
+            const name = wabtDisplayedName(customSectionNames[customIndex++]);
+            if (name === undefined || !text.startsWith(`"${name}"\n`, offset))
+                throw new Error("WABT custom-section header does not match decoded WAT.");
+            description = `"${name}"`;
+            offset += description.length + 1;
+        }
+        else {
+            const end = text.indexOf("\n", offset);
+            if (end < 0)
+                throw new Error("Incomplete WABT section row.");
+            description = text.slice(offset, end).trim();
+            offset = end + 1;
+        }
+        const section = {
+            kind: match[1] ?? "",
+            start: Number.parseInt(match[2] ?? "", 16),
+            end: Number.parseInt(match[3] ?? "", 16),
+            bytes: Number.parseInt(match[4] ?? "", 16),
+            description,
+        };
+        const sectionHeaderBytes = section.start - (sections.at(-1)?.end ?? 8);
+        if (section.end > artifactBytes ||
+            section.end - section.start !== section.bytes ||
+            sectionHeaderBytes < 2 ||
+            sectionHeaderBytes > 6)
+            throw new Error("WABT section ranges do not match selected artifact.");
+        sections.push(section);
+    }
+    if (customIndex !== customSectionNames.length)
+        throw new Error("WABT custom-section inventory does not match decoded WAT.");
+    if ((sections.at(-1)?.end ?? 8) !== artifactBytes)
+        throw new Error("WABT section output does not cover the selected artifact.");
+    const separator = offset + 1;
+    return {
+        sections,
+        headers: text.slice(0, separator),
+        details: `${preamble.slice(1)}\n${text.slice(separator)}`,
+    };
+};

package/dist/wasm/WabtRelease.js

@@ -0,0 +1,12 @@
+/** Exact upstream release whose producer output is admitted by this adapter. */
+export const WABT_PROVIDER_IDENTITY = {
+    id: "wabt-artifact",
+    name: "REA WABT artifact adapter",
+    version: "wabt@1.0.42",
+};
+export const WABT_LIMITS = {
+    inputBytes: 8 * 1024 * 1024,
+    toolBytes: 64 * 1024 * 1024,
+    outputBytes: 32 * 1024 * 1024,
+    timeoutMs: 30_000,
+};