fallow-similar-code 3.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Fallow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# fallow-similar-code
+
+Optional first-party native sidecar used by Fallow's local similar-code analysis.
+Install it through the main `fallow` package. Then run:
+
+```bash
+fallow similar-code setup --local
+```
+
+Setup downloads the exact pinned Apache-2.0 model artifacts into the user cache.
+Analysis after setup is offline. Source is passed to the native sidecar only on
+stdin and is never logged or cached by this package.
+
+The wrapper only launches an exact-version `@fallow-cli/fallow-similar-code-*`
+platform package after verifying its detached Ed25519 signature and the SHA-256
+digest embedded in that exact platform package. Missing or mismatched integrity
+metadata fails closed. The wrapper does not contain or execute a JavaScript
+model runtime.

package/bin/fallow-similar-code

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+"use strict";
+
+require("../scripts/run-binary")
+  .run(process.argv.slice(2))
+  .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`fallow-similar-code: ${message}\n`);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "fallow-similar-code",
+  "version": "3.19.0",
+  "description": "First-party local embedding sidecar for Fallow similar-code analysis",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fallow-rs/fallow.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "fallow-similar-code": "bin/fallow-similar-code"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test scripts/*.test.js"
+  },
+  "dependencies": {
+    "detect-libc": "2.1.2"
+  },
+  "optionalDependencies": {
+    "@fallow-cli/fallow-similar-code-darwin-arm64": "3.19.0",
+    "@fallow-cli/fallow-similar-code-darwin-x64": "3.19.0",
+    "@fallow-cli/fallow-similar-code-linux-x64-gnu": "3.19.0",
+    "@fallow-cli/fallow-similar-code-linux-arm64-gnu": "3.19.0",
+    "@fallow-cli/fallow-similar-code-linux-x64-musl": "3.19.0",
+    "@fallow-cli/fallow-similar-code-linux-arm64-musl": "3.19.0",
+    "@fallow-cli/fallow-similar-code-win32-x64-msvc": "3.19.0",
+    "@fallow-cli/fallow-similar-code-win32-arm64-msvc": "3.19.0"
+  }
+}

package/scripts/package-matrix.test.js

@@ -0,0 +1,18 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+const companion = require("../package.json");
+
+test("all optional native packages are exact-version compatible", () => {
+  for (const [name, version] of Object.entries(companion.optionalDependencies)) {
+    assert.equal(version, companion.version);
+    const directory = name.replace("@fallow-cli/fallow-similar-code-", "fallow-similar-code-");
+    const manifestPath = path.join(__dirname, "..", "..", directory, "package.json");
+    const native = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    assert.equal(native.name, name);
+    assert.equal(native.version, companion.version);
+  }
+});

package/scripts/platform-package.js

@@ -0,0 +1,26 @@
+"use strict";
+
+const PACKAGES = Object.freeze({
+  "darwin-arm64": "@fallow-cli/fallow-similar-code-darwin-arm64",
+  "darwin-x64": "@fallow-cli/fallow-similar-code-darwin-x64",
+  "linux-arm64-gnu": "@fallow-cli/fallow-similar-code-linux-arm64-gnu",
+  "linux-arm64-musl": "@fallow-cli/fallow-similar-code-linux-arm64-musl",
+  "linux-x64-gnu": "@fallow-cli/fallow-similar-code-linux-x64-gnu",
+  "linux-x64-musl": "@fallow-cli/fallow-similar-code-linux-x64-musl",
+  "win32-arm64-msvc": "@fallow-cli/fallow-similar-code-win32-arm64-msvc",
+  "win32-x64-msvc": "@fallow-cli/fallow-similar-code-win32-x64-msvc",
+});
+
+const getPlatformPackage = (platform, arch, libc) => {
+  const suffix =
+    platform === "linux"
+      ? `-${libc === "glibc" ? "gnu" : "musl"}`
+      : platform === "win32"
+        ? "-msvc"
+        : "";
+  return PACKAGES[`${platform}-${arch}${suffix}`];
+};
+
+const isPlatformPackage = (packageName) => Object.values(PACKAGES).includes(packageName);
+
+module.exports = { getPlatformPackage, isPlatformPackage };

package/scripts/platform-package.test.js

@@ -0,0 +1,27 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { getPlatformPackage, isPlatformPackage } = require("./platform-package");
+
+test("maps every supported target to its platform package", () => {
+  assert.equal(
+    getPlatformPackage("darwin", "arm64"),
+    "@fallow-cli/fallow-similar-code-darwin-arm64",
+  );
+  assert.equal(
+    getPlatformPackage("linux", "x64", "glibc"),
+    "@fallow-cli/fallow-similar-code-linux-x64-gnu",
+  );
+  assert.equal(
+    getPlatformPackage("linux", "arm64", "musl"),
+    "@fallow-cli/fallow-similar-code-linux-arm64-musl",
+  );
+  assert.equal(
+    getPlatformPackage("win32", "x64"),
+    "@fallow-cli/fallow-similar-code-win32-x64-msvc",
+  );
+  assert.equal(getPlatformPackage("freebsd", "x64"), undefined);
+  assert.equal(isPlatformPackage("@fallow-cli/fallow-similar-code-darwin-arm64"), true);
+  assert.equal(isPlatformPackage("@fallow-cli/darwin-arm64"), false);
+});

package/scripts/run-binary.js

@@ -0,0 +1,201 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn, spawnSync } = require("node:child_process");
+const { once } = require("node:events");
+const { getPlatformPackage, isPlatformPackage } = require("./platform-package");
+const { verifyBinary } = require("./verify-binary");
+const ownManifest = require("../package.json");
+
+const SETUP_PROCESS_TIMEOUT_MS = 55 * 60 * 1000;
+const SETUP_TERMINATE_GRACE_MS = 1000;
+const SETUP_HARD_EXIT_GRACE_MS = 1000;
+const SETUP_TIMEOUT_EXIT_CODE = 124;
+const SETUP_TIMEOUT_MESSAGE =
+  "local model setup timed out; check DNS, proxy, and network connectivity before retrying";
+const SIGNAL_EXIT_CODES = new Map([
+  ["SIGINT", 130],
+  ["SIGTERM", 143],
+]);
+
+const resolvePlatformPackage = () => {
+  if (process.platform !== "linux") {
+    return getPlatformPackage(process.platform, process.arch);
+  }
+  try {
+    const { familySync } = require("detect-libc");
+    return getPlatformPackage(process.platform, process.arch, familySync());
+  } catch {
+    return getPlatformPackage(process.platform, process.arch, "musl");
+  }
+};
+
+const resolveBinaryArtifact = (
+  packageName,
+  resolve = require.resolve,
+  readFile = fs.readFileSync,
+  stat = fs.lstatSync,
+  platform = process.platform,
+) => {
+  if (!isPlatformPackage(packageName)) {
+    throw new Error(`unsupported similar-code platform package: ${String(packageName)}`);
+  }
+  const manifestPath = resolve(`${packageName}/package.json`);
+  const manifestMetadata = stat(manifestPath);
+  if (!manifestMetadata.isFile() || manifestMetadata.isSymbolicLink()) {
+    throw new Error(`platform manifest is not a regular file: ${manifestPath}`);
+  }
+  const manifest = JSON.parse(readFile(manifestPath, "utf8"));
+  if (manifest.name !== packageName) {
+    throw new Error(
+      `platform package ownership mismatch, expected ${packageName} but manifest declares ${String(manifest.name)}`,
+    );
+  }
+  if (manifest.version !== ownManifest.version) {
+    throw new Error(
+      `version mismatch: fallow-similar-code ${ownManifest.version} requires ${packageName} ${ownManifest.version}, found ${manifest.version}`,
+    );
+  }
+  const binaryName = platform === "win32" ? "fallow-similar-code.exe" : "fallow-similar-code";
+  const binaryPath = path.join(path.dirname(manifestPath), binaryName);
+  const metadata = stat(binaryPath);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new Error(`native sidecar is not a regular file: ${binaryPath}`);
+  }
+  return Object.freeze({
+    packageName,
+    packageVersion: manifest.version,
+    manifestPath,
+    binaryName,
+    binaryPath,
+  });
+};
+
+const resolveBinary = (...args) => resolveBinaryArtifact(...args).binaryPath;
+
+const setupTimeoutFor = (args) => (args[0] === "setup" ? SETUP_PROCESS_TIMEOUT_MS : null);
+
+const spawnNative = (binaryPath, args, spawnProcess = spawnSync) => {
+  const options = { env: process.env, stdio: "inherit" };
+  const result = spawnProcess(binaryPath, args, options);
+  if (result.error) {
+    throw result.error;
+  }
+  return result;
+};
+
+const superviseSetup = async (
+  binaryPath,
+  args,
+  {
+    spawnProcess = spawn,
+    timeoutMs = SETUP_PROCESS_TIMEOUT_MS,
+    terminateGraceMs = SETUP_TERMINATE_GRACE_MS,
+    hardExitGraceMs = SETUP_HARD_EXIT_GRACE_MS,
+  } = {},
+) => {
+  const child = spawnProcess(binaryPath, args, {
+    env: process.env,
+    stdio: "inherit",
+  });
+  let forceTimer;
+  let hardExitTimer;
+  let forwardedSignal;
+  let timedOut = false;
+  let resolveHardExit;
+  const hardExit = new Promise((resolve) => {
+    resolveHardExit = resolve;
+  });
+
+  const terminate = (signal, status) => {
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    child.kill(signal);
+    if (forceTimer) return;
+    forceTimer = setTimeout(() => {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      child.kill("SIGKILL");
+      hardExitTimer = setTimeout(() => {
+        child.unref();
+        resolveHardExit([status, null]);
+      }, hardExitGraceMs);
+    }, terminateGraceMs);
+  };
+
+  const signalHandlers = new Map();
+  for (const signal of SIGNAL_EXIT_CODES.keys()) {
+    const handler = () => {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      forwardedSignal ??= signal;
+      terminate(signal, SIGNAL_EXIT_CODES.get(forwardedSignal) ?? 1);
+    };
+    signalHandlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+
+  const timeout = setTimeout(() => {
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    timedOut = true;
+    terminate("SIGTERM", SETUP_TIMEOUT_EXIT_CODE);
+  }, timeoutMs);
+
+  try {
+    const [status, signal] = await Promise.race([once(child, "exit"), hardExit]);
+    if (timedOut) {
+      return { status: SETUP_TIMEOUT_EXIT_CODE, signal: null, timedOut: true };
+    }
+    if (forwardedSignal) {
+      return {
+        status: SIGNAL_EXIT_CODES.get(forwardedSignal) ?? 1,
+        signal: forwardedSignal,
+        timedOut: false,
+      };
+    }
+    return { status: status ?? 1, signal, timedOut: false };
+  } finally {
+    clearTimeout(timeout);
+    if (forceTimer) clearTimeout(forceTimer);
+    if (hardExitTimer) clearTimeout(hardExitTimer);
+    for (const [signal, handler] of signalHandlers) process.removeListener(signal, handler);
+  }
+};
+
+const run = async (args) => {
+  try {
+    const packageName = resolvePlatformPackage();
+    const artifact = resolveBinaryArtifact(packageName);
+    const verification = verifyBinary(artifact);
+    if (!verification.ok) {
+      throw new Error(`binary verification failed: ${verification.message}`);
+    }
+    const result =
+      setupTimeoutFor(args) === null
+        ? spawnNative(artifact.binaryPath, args)
+        : await superviseSetup(artifact.binaryPath, args);
+    if (result.timedOut) {
+      throw new Error(SETUP_TIMEOUT_MESSAGE);
+    }
+    if (result.signal) {
+      process.stderr.write(`fallow-similar-code terminated by signal ${result.signal}\n`);
+      process.exit(1);
+    }
+    process.exit(result.status ?? 1);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`fallow-similar-code: ${message}\n`);
+    process.exit(1);
+  }
+};
+
+module.exports = {
+  SETUP_PROCESS_TIMEOUT_MS,
+  SETUP_TIMEOUT_EXIT_CODE,
+  SETUP_TIMEOUT_MESSAGE,
+  resolveBinary,
+  resolveBinaryArtifact,
+  resolvePlatformPackage,
+  run,
+  setupTimeoutFor,
+  spawnNative,
+  superviseSetup,
+};

package/scripts/run-binary.test.js

@@ -0,0 +1,165 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const path = require("node:path");
+const ownManifest = require("../package.json");
+const {
+  SETUP_PROCESS_TIMEOUT_MS,
+  SETUP_TIMEOUT_EXIT_CODE,
+  SETUP_TIMEOUT_MESSAGE,
+  resolveBinary,
+  resolveBinaryArtifact,
+  setupTimeoutFor,
+  spawnNative,
+  superviseSetup,
+} = require("./run-binary");
+
+const PACKAGE_NAME = "@fallow-cli/fallow-similar-code-darwin-arm64";
+const manifest = (overrides = {}) =>
+  JSON.stringify({ name: PACKAGE_NAME, version: ownManifest.version, ...overrides });
+
+test("resolves an exact-version regular native binary", () => {
+  const manifestPath = path.join("/packages", "native", "package.json");
+  const resolved = resolveBinary(
+    PACKAGE_NAME,
+    () => manifestPath,
+    () => manifest(),
+    () => ({ isFile: () => true, isSymbolicLink: () => false }),
+  );
+  assert.equal(resolved, path.join("/packages", "native", "fallow-similar-code"));
+});
+
+test("rejects a platform package from another release", () => {
+  assert.throws(
+    () =>
+      resolveBinary(
+        PACKAGE_NAME,
+        () => "/native/package.json",
+        () => manifest({ version: "0.0.0" }),
+        () => ({ isFile: () => true, isSymbolicLink: () => false }),
+      ),
+    /version mismatch/,
+  );
+});
+
+test("rejects symlinked binaries", () => {
+  assert.throws(
+    () =>
+      resolveBinary(
+        PACKAGE_NAME,
+        () => "/native/package.json",
+        () => manifest(),
+        (filePath) => ({
+          isFile: () => true,
+          isSymbolicLink: () => !filePath.endsWith("package.json"),
+        }),
+      ),
+    /not a regular file/,
+  );
+});
+
+test("rejects a symlinked platform manifest", () => {
+  assert.throws(
+    () =>
+      resolveBinaryArtifact(
+        PACKAGE_NAME,
+        () => "/native/package.json",
+        () => manifest(),
+        () => ({ isFile: () => true, isSymbolicLink: () => true }),
+      ),
+    /platform manifest is not a regular file/,
+  );
+});
+
+test("returns the exact owning manifest in the verification artifact", () => {
+  const manifestPath = path.join("/packages", "native", "package.json");
+  const artifact = resolveBinaryArtifact(
+    PACKAGE_NAME,
+    () => manifestPath,
+    () => manifest(),
+    () => ({ isFile: () => true, isSymbolicLink: () => false }),
+  );
+  assert.deepEqual(artifact, {
+    packageName: PACKAGE_NAME,
+    packageVersion: ownManifest.version,
+    manifestPath,
+    binaryName: "fallow-similar-code",
+    binaryPath: path.join("/packages", "native", "fallow-similar-code"),
+  });
+});
+
+test("rejects a manifest that does not belong to the resolved package", () => {
+  assert.throws(
+    () =>
+      resolveBinaryArtifact(
+        PACKAGE_NAME,
+        () => "/native/package.json",
+        () => manifest({ name: "@fallow-cli/other" }),
+        () => ({ isFile: () => true, isSymbolicLink: () => false }),
+      ),
+    /ownership mismatch/,
+  );
+});
+
+test("uses the Windows executable basename in the artifact", () => {
+  const artifact = resolveBinaryArtifact(
+    PACKAGE_NAME,
+    () => path.join("C:\\packages", "native", "package.json"),
+    () => manifest(),
+    () => ({ isFile: () => true, isSymbolicLink: () => false }),
+    "win32",
+  );
+  assert.equal(artifact.binaryName, "fallow-similar-code.exe");
+  assert.match(artifact.binaryPath, /fallow-similar-code\.exe$/);
+});
+
+test("bounds only the direct setup command", () => {
+  assert.equal(setupTimeoutFor(["setup", "--local"]), SETUP_PROCESS_TIMEOUT_MS);
+  assert.equal(setupTimeoutFor(["status", "--json"]), null);
+  assert.equal(setupTimeoutFor(["serve"]), null);
+});
+
+test("setup timeout guidance names the network phases a user can inspect", () => {
+  assert.match(SETUP_TIMEOUT_MESSAGE, /timed out/);
+  assert.match(SETUP_TIMEOUT_MESSAGE, /DNS/);
+  assert.match(SETUP_TIMEOUT_MESSAGE, /proxy/);
+  assert.match(SETUP_TIMEOUT_MESSAGE, /network connectivity/);
+});
+
+test("force-kills a local setup process that ignores graceful termination", async () => {
+  const result = await superviseSetup(
+    process.execPath,
+    ["-e", "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000)"],
+    { timeoutMs: 80, terminateGraceMs: 40, hardExitGraceMs: 100 },
+  );
+
+  assert.deepEqual(result, {
+    status: SETUP_TIMEOUT_EXIT_CODE,
+    signal: null,
+    timedOut: true,
+  });
+});
+
+test("returns a successful local setup process result", async () => {
+  const result = await superviseSetup(process.execPath, ["-e", "process.exit(0)"], {
+    timeoutMs: 1000,
+    terminateGraceMs: 40,
+    hardExitGraceMs: 100,
+  });
+
+  assert.deepEqual(result, { status: 0, signal: null, timedOut: false });
+});
+
+test("spawns non-setup commands without a wrapper timeout", () => {
+  let captured = null;
+  const result = spawnNative("/fixture/sidecar", ["status", "--json"], (binary, args, options) => {
+    captured = { binary, args, options };
+    return { status: 0, signal: null };
+  });
+
+  assert.equal(result.status, 0);
+  assert.equal(captured.binary, "/fixture/sidecar");
+  assert.deepEqual(captured.args, ["status", "--json"]);
+  assert.deepEqual(captured.options, { env: process.env, stdio: "inherit" });
+});

package/scripts/verify-binary.js

@@ -0,0 +1,180 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const { isPlatformPackage } = require("./platform-package");
+const ownManifest = require("../package.json");
+
+const PUBLIC_KEY = Buffer.from([
+  131, 78, 111, 215, 115, 51, 230, 238, 223, 119, 147, 71, 199, 16, 172, 180, 3, 210, 216, 35, 77,
+  85, 159, 94, 215, 200, 126, 85, 42, 222, 11, 209,
+]);
+const SPKI_HEADER = Buffer.from([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00,
+]);
+
+const failure = (code, message) => ({ ok: false, code, message });
+
+const validateArtifact = (artifact) => {
+  if (
+    !artifact ||
+    typeof artifact !== "object" ||
+    typeof artifact.packageName !== "string" ||
+    typeof artifact.packageVersion !== "string" ||
+    typeof artifact.manifestPath !== "string" ||
+    typeof artifact.binaryName !== "string" ||
+    typeof artifact.binaryPath !== "string"
+  ) {
+    return failure("artifact-invalid", "similar-code binary artifact is incomplete");
+  }
+  const expectedBinaryName = artifact.packageName.includes("-win32-")
+    ? "fallow-similar-code.exe"
+    : "fallow-similar-code";
+  if (!isPlatformPackage(artifact.packageName) || artifact.binaryName !== expectedBinaryName) {
+    return failure(
+      "package-mismatch",
+      "similar-code artifact does not identify a supported platform package and binary",
+    );
+  }
+  const manifestDirectory = path.resolve(path.dirname(artifact.manifestPath));
+  const binaryDirectory = path.resolve(path.dirname(artifact.binaryPath));
+  if (
+    manifestDirectory !== binaryDirectory ||
+    path.basename(artifact.manifestPath) !== "package.json" ||
+    path.basename(artifact.binaryPath) !== artifact.binaryName
+  ) {
+    return failure(
+      "package-mismatch",
+      "similar-code binary and package manifest do not have the same package owner",
+    );
+  }
+  return { ok: true };
+};
+
+const readManifestDigest = (artifact, readFile) => {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFile(artifact.manifestPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return failure("manifest-invalid", `cannot read platform package manifest: ${message}`);
+  }
+  if (!manifest || typeof manifest !== "object") {
+    return failure("manifest-invalid", "platform package manifest must be a JSON object");
+  }
+  if (manifest.name !== artifact.packageName) {
+    return failure(
+      "package-mismatch",
+      `platform package ownership mismatch, expected ${artifact.packageName} but got ${String(manifest.name)}`,
+    );
+  }
+  if (
+    artifact.packageVersion !== ownManifest.version ||
+    manifest.version !== artifact.packageVersion
+  ) {
+    return failure(
+      "version-mismatch",
+      `similar-code platform package must match companion version ${ownManifest.version}`,
+    );
+  }
+  if (!manifest.fallowDigests || typeof manifest.fallowDigests !== "object") {
+    return failure("digest-missing", "platform package manifest has no fallowDigests object");
+  }
+  const digest = manifest.fallowDigests[artifact.binaryName];
+  if (digest === undefined) {
+    return failure(
+      "digest-missing",
+      `platform package manifest has no SHA-256 digest for ${artifact.binaryName}`,
+    );
+  }
+  if (typeof digest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(digest)) {
+    return failure(
+      "digest-invalid",
+      `platform package manifest has a malformed SHA-256 digest for ${artifact.binaryName}`,
+    );
+  }
+  return { ok: true, digest: digest.slice("sha256:".length) };
+};
+
+const readBinary = (binaryPath, readFile) => {
+  try {
+    return { ok: true, bytes: readFile(binaryPath) };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return failure("read-error", `cannot read similar-code binary: ${message}`);
+  }
+};
+
+const readSignature = (binaryPath, readFile) => {
+  try {
+    const signature = readFile(`${binaryPath}.sig`);
+    return signature.length === 64
+      ? { ok: true, signature }
+      : failure("sig-invalid", "signature has an unexpected length");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return failure("sig-missing", `cannot read detached signature: ${message}`);
+  }
+};
+
+const verifySignature = (binary, signature, verify, createPublicKey) => {
+  try {
+    const key = createPublicKey({
+      key: Buffer.concat([SPKI_HEADER, PUBLIC_KEY]),
+      format: "der",
+      type: "spki",
+    });
+    return verify(null, binary, key, signature)
+      ? { ok: true }
+      : failure("sig-invalid", "Ed25519 signature verification failed");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return failure("sig-invalid", `Ed25519 signature verification failed: ${message}`);
+  }
+};
+
+const verifyDigest = (binary, expectedDigest) => {
+  const actual = crypto.createHash("sha256").update(binary).digest();
+  const expected = Buffer.from(expectedDigest, "hex");
+  return crypto.timingSafeEqual(actual, expected)
+    ? { ok: true }
+    : failure("digest-mismatch", "embedded SHA-256 digest does not match the binary");
+};
+
+const verifyBinary = (
+  artifact,
+  {
+    readFile = fs.readFileSync,
+    verify = crypto.verify,
+    createPublicKey = crypto.createPublicKey,
+  } = {},
+) => {
+  const artifactResult = validateArtifact(artifact);
+  if (!artifactResult.ok) return artifactResult;
+
+  const manifestResult = readManifestDigest(artifact, readFile);
+  if (!manifestResult.ok) return manifestResult;
+
+  const binaryResult = readBinary(artifact.binaryPath, readFile);
+  if (!binaryResult.ok) return binaryResult;
+
+  const signatureResult = readSignature(artifact.binaryPath, readFile);
+  if (!signatureResult.ok) return signatureResult;
+
+  const signatureVerification = verifySignature(
+    binaryResult.bytes,
+    signatureResult.signature,
+    verify,
+    createPublicKey,
+  );
+  if (!signatureVerification.ok) return signatureVerification;
+
+  return verifyDigest(binaryResult.bytes, manifestResult.digest);
+};
+
+module.exports = {
+  PUBLIC_KEY,
+  SPKI_HEADER,
+  verifyBinary,
+};

package/scripts/verify-binary.test.js

@@ -0,0 +1,129 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const test = require("node:test");
+const ownManifest = require("../package.json");
+const { verifyBinary } = require("./verify-binary");
+
+const PACKAGE_NAME = "@fallow-cli/fallow-similar-code-darwin-arm64";
+const BINARY_NAME = "fallow-similar-code";
+
+const digest = (bytes) => `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+
+const makeFixture = (t, options = {}) => {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-similar-code-verify-"));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  const binaryPath = path.join(directory, BINARY_NAME);
+  const manifestPath = path.join(directory, "package.json");
+  const binary = options.binary ?? Buffer.from("trusted binary");
+  fs.writeFileSync(binaryPath, binary);
+  fs.writeFileSync(`${binaryPath}.sig`, options.signature ?? Buffer.alloc(64));
+  const manifest = {
+    name: PACKAGE_NAME,
+    version: ownManifest.version,
+    fallowDigests: { [BINARY_NAME]: options.digest ?? digest(binary) },
+    ...options.manifest,
+  };
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest));
+  return {
+    artifact: {
+      packageName: PACKAGE_NAME,
+      packageVersion: ownManifest.version,
+      manifestPath,
+      binaryName: BINARY_NAME,
+      binaryPath,
+    },
+    manifestPath,
+  };
+};
+
+const acceptSignature = {
+  verify: () => true,
+  createPublicKey: () => ({}),
+};
+
+test("verifies Ed25519 and the exact platform manifest digest before launch", (t) => {
+  const binary = Buffer.from("signed trusted binary");
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519");
+  const { artifact } = makeFixture(t, {
+    binary,
+    signature: crypto.sign(null, binary, privateKey),
+  });
+  assert.deepEqual(verifyBinary(artifact, { createPublicKey: () => publicKey }), { ok: true });
+});
+
+test("rejects the legacy path-only call instead of falling back to signature-only", () => {
+  const result = verifyBinary("/native/fallow-similar-code", acceptSignature);
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "artifact-invalid");
+});
+
+test("rejects malformed and invalid detached signatures", (t) => {
+  const malformed = makeFixture(t, { signature: Buffer.alloc(63) });
+  assert.equal(verifyBinary(malformed.artifact).code, "sig-invalid");
+
+  const invalid = makeFixture(t);
+  assert.equal(
+    verifyBinary(invalid.artifact, {
+      verify: () => false,
+      createPublicKey: () => ({}),
+    }).code,
+    "sig-invalid",
+  );
+});
+
+test("fails closed when the embedded digest is missing or malformed", (t) => {
+  const absent = makeFixture(t, { manifest: { fallowDigests: undefined } });
+  assert.equal(verifyBinary(absent.artifact, acceptSignature).code, "digest-missing");
+
+  const missingEntry = makeFixture(t, { manifest: { fallowDigests: {} } });
+  assert.equal(verifyBinary(missingEntry.artifact, acceptSignature).code, "digest-missing");
+
+  const malformed = makeFixture(t, {
+    manifest: { fallowDigests: { [BINARY_NAME]: "not-a-digest" } },
+  });
+  assert.equal(verifyBinary(malformed.artifact, acceptSignature).code, "digest-invalid");
+});
+
+test("rejects digest tampering even when signature verification succeeds", (t) => {
+  const binary = Buffer.from("authentically signed but stale digest");
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519");
+  const fixture = makeFixture(t, {
+    binary,
+    signature: crypto.sign(null, binary, privateKey),
+    digest: `sha256:${"a".repeat(64)}`,
+  });
+  const result = verifyBinary(fixture.artifact, { createPublicKey: () => publicKey });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "digest-mismatch");
+});
+
+test("rejects a manifest owned by another package or version", (t) => {
+  const wrongOwner = makeFixture(t, { manifest: { name: "@fallow-cli/other" } });
+  assert.equal(verifyBinary(wrongOwner.artifact, acceptSignature).code, "package-mismatch");
+
+  const wrongVersion = makeFixture(t, { manifest: { version: "0.0.0" } });
+  assert.equal(verifyBinary(wrongVersion.artifact, acceptSignature).code, "version-mismatch");
+});
+
+test("rejects a digest from an adjacent manifest", (t) => {
+  const fixture = makeFixture(t);
+  const adjacent = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-similar-code-adjacent-"));
+  t.after(() => fs.rmSync(adjacent, { recursive: true, force: true }));
+  const result = verifyBinary(
+    { ...fixture.artifact, manifestPath: path.join(adjacent, "package.json") },
+    acceptSignature,
+  );
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "package-mismatch");
+});
+
+test("rejects a missing platform manifest", (t) => {
+  const fixture = makeFixture(t);
+  fs.rmSync(fixture.manifestPath);
+  assert.equal(verifyBinary(fixture.artifact, acceptSignature).code, "manifest-invalid");
+});