@deeeed/metamask-harness 0.36.0 → 0.38.0

package/dist/adapters/extension/release-artifact.js

@@ -0,0 +1,386 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { inflateRawSync } from "node:zlib";
+import { extensionTreeSha256 } from "./artifact-integrity.js";
+const MAX_ARCHIVE_BYTES = 768 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 512 * 1024 * 1024;
+const MAX_EXPANDED_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_ENTRIES = 1e5;
+async function acquireExtensionReleaseArtifact(options) {
+  const source = localSource(options.file);
+  const expectedVersion = expectedArtifactVersion(options.expectedVersion);
+  const expectedSha256 = expectedArtifactSha256(options.expectedSha256);
+  const requestedCacheRoot = path.resolve(
+    options.cacheRoot ?? path.join(os.homedir(), ".cache", "mm-harness", "extension-artifacts")
+  );
+  await fsp.mkdir(requestedCacheRoot, { recursive: true, mode: 448 });
+  const cacheRoot = await fsp.realpath(requestedCacheRoot);
+  const acquired = await inspectLocalArchive(source.path, cacheRoot);
+  if (acquired.sha256 !== expectedSha256) {
+    if (acquired.temporary) await fsp.rm(path.dirname(acquired.archivePath), { recursive: true });
+    throw new Error(`Extension artifact SHA-256 ${acquired.sha256} does not match expected ${expectedSha256}.`);
+  }
+  const artifactRoot = path.join(cacheRoot, expectedVersion, acquired.sha256);
+  const provenancePath = path.join(artifactRoot, "provenance.json");
+  const cached = await readCachedArtifact(artifactRoot, provenancePath, acquired.sha256, expectedVersion);
+  if (cached) {
+    if (acquired.temporary) {
+      await fsp.rm(path.dirname(acquired.archivePath), { recursive: true });
+    }
+    return {
+      ...cached,
+      source,
+      archiveBytes: acquired.bytes,
+      cache: "hit"
+    };
+  }
+  if (await pathExists(artifactRoot)) {
+    await assertRegularTree(artifactRoot);
+    await assertContainedDirectory(artifactRoot, cacheRoot);
+    await fsp.rm(artifactRoot, { recursive: true });
+  }
+  const versionRoot = path.dirname(artifactRoot);
+  await fsp.mkdir(versionRoot, { recursive: true, mode: 448 });
+  await assertContainedDirectory(versionRoot, cacheRoot);
+  const temporaryRoot = await fsp.mkdtemp(path.join(versionRoot, ".extract-"));
+  try {
+    const contentRoot = path.join(temporaryRoot, "content");
+    await fsp.mkdir(contentRoot, { mode: 448 });
+    const extensionDir = await extractExtensionArchive(acquired.archivePath, contentRoot);
+    const manifestVersion = await validateManifestVersion(extensionDir, expectedVersion);
+    const treeSha256 = extensionTreeSha256(extensionDir);
+    const relativeExtensionDir = path.relative(temporaryRoot, extensionDir) || ".";
+    const provenance = {
+      schemaVersion: 1,
+      source,
+      expectedVersion,
+      manifestVersion,
+      sha256: acquired.sha256,
+      treeSha256,
+      archiveBytes: acquired.bytes,
+      extensionDir: relativeExtensionDir,
+      acquiredAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await fsp.writeFile(
+      path.join(temporaryRoot, "provenance.json"),
+      `${JSON.stringify(provenance, null, 2)}
+`,
+      { mode: 384 }
+    );
+    try {
+      await fsp.rename(temporaryRoot, artifactRoot);
+    } catch (error) {
+      if (!isAlreadyExists(error)) throw error;
+      await fsp.rm(temporaryRoot, { recursive: true });
+    }
+    const ready = await readCachedArtifact(artifactRoot, provenancePath, acquired.sha256, expectedVersion);
+    if (!ready) throw new Error(`Extension artifact cache could not be validated at ${artifactRoot}.`);
+    return {
+      ...ready,
+      source,
+      archiveBytes: acquired.bytes,
+      cache: "miss"
+    };
+  } catch (error) {
+    if (await pathExists(temporaryRoot)) await fsp.rm(temporaryRoot, { recursive: true });
+    throw error;
+  } finally {
+    if (acquired.temporary) {
+      await fsp.rm(path.dirname(acquired.archivePath), { recursive: true });
+    }
+  }
+}
+function expectedArtifactSha256(requested) {
+  if (!/^[a-f0-9]{64}$/u.test(requested)) {
+    throw new Error("--artifact-sha256 must be 64 lowercase hexadecimal characters.");
+  }
+  return requested;
+}
+async function inspectLocalArchive(archive, cacheRoot) {
+  const sourcePath = path.resolve(archive);
+  const downloadRoot = path.join(cacheRoot, ".downloads");
+  await fsp.mkdir(downloadRoot, { recursive: true, mode: 448 });
+  const temporaryRoot = await fsp.mkdtemp(path.join(downloadRoot, "artifact-"));
+  const archivePath = path.join(temporaryRoot, "artifact.zip");
+  let source;
+  try {
+    source = await fsp.open(sourcePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const stat = await source.stat();
+    if (!stat.isFile()) throw new Error(`Extension artifact archive must be a regular file: ${sourcePath}`);
+    if (stat.size > MAX_ARCHIVE_BYTES) {
+      throw new Error(`Extension artifact exceeds the ${MAX_ARCHIVE_BYTES}-byte archive limit.`);
+    }
+    const destination = await fsp.open(archivePath, "wx", 384);
+    const digest = createHash("sha256");
+    let bytes = 0;
+    try {
+      const stream = source.createReadStream({ autoClose: false });
+      for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > MAX_ARCHIVE_BYTES) {
+          throw new Error(`Extension artifact exceeds the ${MAX_ARCHIVE_BYTES}-byte archive limit.`);
+        }
+        digest.update(buffer);
+        await destination.write(buffer);
+      }
+    } finally {
+      await destination.close();
+    }
+    return { archivePath, sha256: digest.digest("hex"), bytes, temporary: true };
+  } catch (error) {
+    await fsp.rm(temporaryRoot, { recursive: true });
+    throw error;
+  } finally {
+    await source?.close();
+  }
+}
+function localSource(archive) {
+  return { kind: "local", path: path.resolve(archive) };
+}
+function expectedArtifactVersion(requested) {
+  if (!/^\d+\.\d+\.\d+$/u.test(requested)) {
+    throw new Error("--artifact-version must use X.Y.Z.");
+  }
+  return requested;
+}
+async function extractExtensionArchive(archivePath, outputRoot) {
+  const archive = await fsp.readFile(archivePath);
+  const entries = readZipEntries(archive);
+  const manifestEntries = entries.filter((entry) => !entry.directory && path.posix.basename(entry.name) === "manifest.json");
+  if (manifestEntries.length !== 1) {
+    throw new Error(`Extension artifact must contain exactly one manifest.json; found ${manifestEntries.length}.`);
+  }
+  const extensionPrefix = path.posix.dirname(manifestEntries[0].name);
+  if (extensionPrefix !== ".") {
+    const prefix = `${extensionPrefix}/`;
+    const outside = entries.find((entry) => entry.name !== extensionPrefix && !entry.name.startsWith(prefix));
+    if (outside) {
+      throw new Error(`Extension artifact has content outside its manifest root: ${outside.name}.`);
+    }
+  }
+  for (const entry of entries) {
+    const destination = path.join(outputRoot, ...entry.name.split("/"));
+    if (entry.directory) {
+      await fsp.mkdir(destination, { recursive: true, mode: 493 });
+      continue;
+    }
+    await fsp.mkdir(path.dirname(destination), { recursive: true, mode: 493 });
+    const compressedStart = localEntryDataOffset(archive, entry);
+    const compressed = archive.subarray(compressedStart, compressedStart + entry.compressedSize);
+    const content = entry.method === 0 ? compressed : inflateRawSync(compressed, { maxOutputLength: entry.uncompressedSize });
+    if (content.length !== entry.uncompressedSize || crc32(content) !== entry.crc32) {
+      throw new Error(`Extension artifact entry failed integrity validation: ${entry.name}.`);
+    }
+    await fsp.writeFile(destination, content, { flag: "wx", mode: 420 });
+  }
+  return extensionPrefix === "." ? outputRoot : path.join(outputRoot, ...extensionPrefix.split("/"));
+}
+function readZipEntries(archive) {
+  const eocdOffset = findEndOfCentralDirectory(archive);
+  const disk = archive.readUInt16LE(eocdOffset + 4);
+  const centralDisk = archive.readUInt16LE(eocdOffset + 6);
+  const entriesOnDisk = archive.readUInt16LE(eocdOffset + 8);
+  const entryCount = archive.readUInt16LE(eocdOffset + 10);
+  const centralSize = archive.readUInt32LE(eocdOffset + 12);
+  const centralOffset = archive.readUInt32LE(eocdOffset + 16);
+  if (disk !== 0 || centralDisk !== 0 || entriesOnDisk !== entryCount) {
+    throw new Error("Multi-disk ZIP archives are not supported.");
+  }
+  if (entryCount === 65535 || centralSize === 4294967295 || centralOffset === 4294967295) {
+    throw new Error("ZIP64 extension artifacts are not supported.");
+  }
+  if (entryCount === 0 || entryCount > MAX_ENTRIES || centralOffset + centralSize > eocdOffset) {
+    throw new Error("Extension artifact has an invalid central directory.");
+  }
+  const entries = [];
+  const names = /* @__PURE__ */ new Set();
+  const offsets = /* @__PURE__ */ new Set();
+  let expandedBytes = 0;
+  let offset = centralOffset;
+  for (let index = 0; index < entryCount; index += 1) {
+    if (offset + 46 > archive.length || archive.readUInt32LE(offset) !== 33639248) {
+      throw new Error("Extension artifact has a malformed central directory entry.");
+    }
+    const flags = archive.readUInt16LE(offset + 8);
+    const method = archive.readUInt16LE(offset + 10);
+    const crc = archive.readUInt32LE(offset + 16);
+    const compressedSize = archive.readUInt32LE(offset + 20);
+    const uncompressedSize = archive.readUInt32LE(offset + 24);
+    const nameLength = archive.readUInt16LE(offset + 28);
+    const extraLength = archive.readUInt16LE(offset + 30);
+    const commentLength = archive.readUInt16LE(offset + 32);
+    const madeBy = archive.readUInt16LE(offset + 4) >>> 8;
+    const externalAttributes = archive.readUInt32LE(offset + 38);
+    const localOffset = archive.readUInt32LE(offset + 42);
+    const nextOffset = offset + 46 + nameLength + extraLength + commentLength;
+    if (nextOffset > archive.length) throw new Error("Extension artifact has a truncated central directory entry.");
+    const name = archive.subarray(offset + 46, offset + 46 + nameLength).toString("utf8");
+    validateEntryName(name);
+    const directory = name.endsWith("/");
+    const unixMode = madeBy === 3 ? externalAttributes >>> 16 : 0;
+    if ((unixMode & 61440) === 40960) {
+      throw new Error(`Extension artifact contains a symbolic link: ${name}.`);
+    }
+    if ((flags & 1) !== 0 || method !== 0 && method !== 8) {
+      throw new Error(`Extension artifact entry uses unsupported ZIP features: ${name}.`);
+    }
+    if (names.has(name) || offsets.has(localOffset)) {
+      throw new Error(`Extension artifact contains a duplicate entry: ${name}.`);
+    }
+    if (uncompressedSize > MAX_ENTRY_BYTES || compressedSize > MAX_ENTRY_BYTES) {
+      throw new Error(`Extension artifact entry is too large: ${name}.`);
+    }
+    if (compressedSize > 0 && uncompressedSize / compressedSize > 1e3) {
+      throw new Error(`Extension artifact entry has an unsafe compression ratio: ${name}.`);
+    }
+    expandedBytes += uncompressedSize;
+    if (expandedBytes > MAX_EXPANDED_BYTES) {
+      throw new Error(`Extension artifact exceeds the ${MAX_EXPANDED_BYTES}-byte expansion limit.`);
+    }
+    names.add(name);
+    offsets.add(localOffset);
+    entries.push({ name, directory, method, compressedSize, uncompressedSize, crc32: crc, localOffset });
+    offset = nextOffset;
+  }
+  if (offset !== centralOffset + centralSize) throw new Error("Extension artifact central directory size does not match.");
+  return entries;
+}
+function validateEntryName(name) {
+  const withoutSlash = name.endsWith("/") ? name.slice(0, -1) : name;
+  const segments = withoutSlash.split("/");
+  if (!withoutSlash || name.includes("\\") || name.includes("\0") || name.includes("\uFFFD") || name.startsWith("/") || /^[A-Za-z]:/u.test(name) || segments.some((segment) => !segment || segment === "." || segment === "..") || path.posix.normalize(withoutSlash) !== withoutSlash) {
+    throw new Error(`Extension artifact contains an unsafe path: ${JSON.stringify(name)}.`);
+  }
+}
+function localEntryDataOffset(archive, entry) {
+  const offset = entry.localOffset;
+  if (offset + 30 > archive.length || archive.readUInt32LE(offset) !== 67324752) {
+    throw new Error(`Extension artifact has a malformed local entry: ${entry.name}.`);
+  }
+  const flags = archive.readUInt16LE(offset + 6);
+  const method = archive.readUInt16LE(offset + 8);
+  const nameLength = archive.readUInt16LE(offset + 26);
+  const extraLength = archive.readUInt16LE(offset + 28);
+  const localName = archive.subarray(offset + 30, offset + 30 + nameLength).toString("utf8");
+  const dataOffset = offset + 30 + nameLength + extraLength;
+  if (localName !== entry.name || method !== entry.method || (flags & 1) !== 0 || dataOffset + entry.compressedSize > archive.length) {
+    throw new Error(`Extension artifact local entry does not match its directory record: ${entry.name}.`);
+  }
+  return dataOffset;
+}
+function findEndOfCentralDirectory(archive) {
+  const start = Math.max(0, archive.length - 65557);
+  for (let offset = archive.length - 22; offset >= start; offset -= 1) {
+    if (archive.readUInt32LE(offset) === 101010256) {
+      const commentLength = archive.readUInt16LE(offset + 20);
+      if (offset + 22 + commentLength === archive.length) return offset;
+    }
+  }
+  throw new Error("Extension artifact is not a valid ZIP archive.");
+}
+async function validateManifestVersion(extensionDir, expectedVersion) {
+  await assertRegularTree(extensionDir);
+  const manifestPath = path.join(extensionDir, "manifest.json");
+  const manifestStat = await fsp.lstat(manifestPath).catch(() => null);
+  if (!manifestStat?.isFile() || manifestStat.isSymbolicLink() || manifestStat.size > 2 * 1024 * 1024) {
+    throw new Error("Extension artifact manifest.json must be a regular file smaller than 2 MiB.");
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(await fsp.readFile(manifestPath, "utf8"));
+  } catch {
+    throw new Error("Extension artifact manifest.json is not valid JSON.");
+  }
+  const version = typeof manifest === "object" && manifest !== null && "version" in manifest ? manifest.version : void 0;
+  if (typeof version !== "string" || normalizeManifestVersion(version) !== expectedVersion) {
+    throw new Error(`Extension artifact manifest version ${String(version ?? "missing")} does not match expected ${expectedVersion}.`);
+  }
+  return version;
+}
+function normalizeManifestVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:\.\d+)?$/u.test(version)) return null;
+  const parts = version.split(".");
+  if (parts.length === 4 && parts[3] !== "0") return null;
+  return parts.slice(0, 3).join(".");
+}
+async function assertRegularTree(root) {
+  const rootStat = await fsp.lstat(root).catch(() => null);
+  if (!rootStat?.isDirectory() || rootStat.isSymbolicLink()) {
+    throw new Error(`Extension artifact root must be a regular directory: ${root}`);
+  }
+  const entries = await fsp.readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const child = path.join(root, entry.name);
+    const stat = await fsp.lstat(child);
+    if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile()) {
+      throw new Error(`Extension artifact cache contains an unsupported entry: ${child}`);
+    }
+    if (stat.isDirectory()) await assertRegularTree(child);
+  }
+}
+async function assertContainedDirectory(directory, root) {
+  const resolvedRoot = await fsp.realpath(root);
+  const resolvedDirectory = await fsp.realpath(directory);
+  if (resolvedDirectory !== resolvedRoot && !resolvedDirectory.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error(`Extension artifact cache path escapes its root: ${directory}`);
+  }
+  let current = resolvedDirectory;
+  while (current !== resolvedRoot) {
+    const stat = await fsp.lstat(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new Error(`Extension artifact cache path is not a regular directory: ${current}`);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error(`Extension artifact cache path escapes its root: ${directory}`);
+    current = parent;
+  }
+}
+async function readCachedArtifact(artifactRoot, provenancePath, sha256, expectedVersion) {
+  try {
+    const provenanceStat = await fsp.lstat(provenancePath);
+    if (!provenanceStat.isFile() || provenanceStat.isSymbolicLink() || provenanceStat.size > 64 * 1024) return null;
+    const provenance = JSON.parse(await fsp.readFile(provenancePath, "utf8"));
+    if (provenance.schemaVersion !== 1 || provenance.sha256 !== sha256 || provenance.expectedVersion !== expectedVersion || typeof provenance.treeSha256 !== "string" || !/^[a-f0-9]{64}$/u.test(provenance.treeSha256) || typeof provenance.extensionDir !== "string" || path.isAbsolute(provenance.extensionDir) || provenance.extensionDir.split(path.sep).includes("..")) return null;
+    const extensionDir = path.resolve(artifactRoot, provenance.extensionDir);
+    if (extensionDir !== artifactRoot && !extensionDir.startsWith(`${artifactRoot}${path.sep}`)) return null;
+    const manifestVersion = await validateManifestVersion(extensionDir, expectedVersion);
+    const treeSha256 = extensionTreeSha256(extensionDir);
+    if (treeSha256 !== provenance.treeSha256) return null;
+    return {
+      schemaVersion: 1,
+      expectedVersion,
+      manifestVersion,
+      sha256,
+      treeSha256,
+      extensionDir,
+      provenancePath
+    };
+  } catch {
+    return null;
+  }
+}
+function isAlreadyExists(error) {
+  return Boolean(
+    error && typeof error === "object" && "code" in error && ["EEXIST", "ENOTEMPTY"].includes(String(error.code))
+  );
+}
+async function pathExists(file) {
+  return fsp.access(file).then(() => true, () => false);
+}
+const CRC_TABLE = Array.from({ length: 256 }, (_, initial) => {
+  let value = initial;
+  for (let bit = 0; bit < 8; bit += 1) value = (value & 1) !== 0 ? 3988292384 ^ value >>> 1 : value >>> 1;
+  return value >>> 0;
+});
+function crc32(buffer) {
+  let value = 4294967295;
+  for (const byte of buffer) value = CRC_TABLE[(value ^ byte) & 255] ^ value >>> 8;
+  return (value ^ 4294967295) >>> 0;
+}
+export {
+  acquireExtensionReleaseArtifact
+};

package/dist/adapters/extension/runtime-decision.js

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { extensionTreeSha256 } from "./artifact-integrity.js";
 import {
   depsCheck,
   INSTALL_MARKERS
@@ -151,21 +152,109 @@ function latestDistMtime(target) {
   walk2(distDir);
   return latest;
 }
-function runtimeDistCheck(target) {
-  const dist = path.join(target, "dist/chrome");
+function releaseArtifactState(target) {
+  const runtimeRoot = path.join(target, recipeRuntimeDir());
+  const statePath = path.join(runtimeRoot, "extension-release-artifact.json");
+  if (!fs.existsSync(statePath)) return { status: "none" };
+  try {
+    const stateStat = fs.lstatSync(statePath);
+    if (!stateStat.isFile() || stateStat.isSymbolicLink() || stateStat.size <= 0 || stateStat.size > 64 * 1024) {
+      return { status: "invalid", reason: "artifact runtime identity is not a regular bounded file" };
+    }
+    const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    const sourceDir = typeof state.sourceDir === "string" ? path.resolve(state.sourceDir) : "";
+    const runtimeDist = typeof state.runtimeDist === "string" ? path.resolve(state.runtimeDist) : "";
+    const provenancePath = typeof state.provenancePath === "string" ? path.resolve(state.provenancePath) : "";
+    const chromeUserDataDir = typeof state.chromeUserDataDir === "string" ? path.resolve(state.chromeUserDataDir) : "";
+    const expectedRuntimeDist = path.join(
+      runtimeRoot,
+      process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist"
+    );
+    const profileStat = chromeUserDataDir ? fs.lstatSync(chromeUserDataDir, { throwIfNoEntry: false }) : void 0;
+    if (state.schemaVersion !== 2 || !sourceDir || runtimeDist !== expectedRuntimeDist || !provenancePath || !chromeUserDataDir.startsWith(`${runtimeRoot}${path.sep}`) || !profileStat?.isDirectory() || profileStat.isSymbolicLink()) {
+      return { status: "invalid", reason: "artifact runtime identity has invalid paths or schema" };
+    }
+    const provenanceStat = fs.lstatSync(provenancePath);
+    if (!provenanceStat.isFile() || provenanceStat.isSymbolicLink() || provenanceStat.size <= 0 || provenanceStat.size > 64 * 1024) {
+      return { status: "invalid", reason: "artifact provenance is not a regular bounded file" };
+    }
+    const provenance = JSON.parse(fs.readFileSync(provenancePath, "utf8"));
+    const relativeExtensionDir = typeof provenance.extensionDir === "string" ? provenance.extensionDir : "";
+    const boundSource = relativeExtensionDir && !path.isAbsolute(relativeExtensionDir) && !relativeExtensionDir.split(/[\\/]+/u).includes("..") ? path.resolve(path.dirname(provenancePath), relativeExtensionDir) : "";
+    const sha256 = typeof provenance.sha256 === "string" ? provenance.sha256 : "";
+    const expectedVersion = typeof provenance.expectedVersion === "string" ? provenance.expectedVersion : "";
+    const manifestVersion = typeof provenance.manifestVersion === "string" ? provenance.manifestVersion : "";
+    const treeSha256 = typeof provenance.treeSha256 === "string" ? provenance.treeSha256 : "";
+    if (provenance.schemaVersion !== 1 || boundSource !== sourceDir || !/^[a-f0-9]{64}$/u.test(sha256) || !/^[a-f0-9]{64}$/u.test(treeSha256) || !/^\d+\.\d+\.\d+$/u.test(expectedVersion) || state.sha256 !== sha256 || state.treeSha256 !== treeSha256 || state.expectedVersion !== expectedVersion || state.manifestVersion !== manifestVersion) {
+      return { status: "invalid", reason: "artifact runtime identity does not match its provenance" };
+    }
+    const manifest = JSON.parse(fs.readFileSync(path.join(runtimeDist, "manifest.json"), "utf8"));
+    const runtimeVersion = typeof manifest.version === "string" ? manifest.version : "";
+    if (normalizeReleaseVersion(runtimeVersion) !== expectedVersion || runtimeVersion !== manifestVersion) {
+      return { status: "invalid", reason: "artifact runtime manifest does not match its provenance" };
+    }
+    if (extensionTreeSha256(sourceDir) !== treeSha256 || extensionTreeSha256(runtimeDist) !== treeSha256) {
+      return { status: "invalid", reason: "artifact source or runtime tree does not match its provenance" };
+    }
+    return {
+      status: "valid",
+      sourceDir,
+      runtimeDist,
+      provenancePath,
+      chromeUserDataDir,
+      sha256,
+      treeSha256,
+      expectedVersion,
+      manifestVersion
+    };
+  } catch (error) {
+    return {
+      status: "invalid",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function normalizeReleaseVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:\.\d+)?$/u.test(version)) return null;
+  const parts = version.split(".");
+  if (parts.length === 4 && parts[3] !== "0") return null;
+  return parts.slice(0, 3).join(".");
+}
+function releaseArtifactDistCheck(artifact) {
+  return {
+    status: "fresh",
+    source: "release-artifact",
+    manifestPath: path.join(artifact.runtimeDist, "manifest.json"),
+    manifestVersion: artifact.manifestVersion,
+    artifactSha256: artifact.sha256
+  };
+}
+function runtimeDistCheck(target, artifact = releaseArtifactState(target)) {
+  if (artifact.status === "invalid") {
+    return {
+      status: "stale",
+      source: "release-artifact",
+      artifactError: artifact.reason,
+      modified: ["<artifact identity invalid>"]
+    };
+  }
+  const dist = artifact.status === "valid" ? artifact.sourceDir : path.join(target, "dist/chrome");
   const runtimeDist = path.join(
     target,
     recipeRuntimeDir(),
     process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist"
   );
-  if (!fs.existsSync(path.join(runtimeDist, "manifest.json"))) return { status: "missing" };
+  const identity = artifact.status === "valid" ? {
+    source: "release-artifact",
+    artifactSha256: artifact.sha256,
+    provenancePath: artifact.provenancePath
+  } : {};
+  if (!fs.existsSync(path.join(runtimeDist, "manifest.json"))) return { status: "missing", ...identity };
   let output;
   try {
-    output = execFileSync("rsync", [
+    const rsyncArgs = [
       "-rnic",
       "--exclude",
-      "_metadata",
-      "--exclude",
       "home.html",
       "--exclude",
       "sidepanel.html",
@@ -174,21 +263,34 @@ function runtimeDistCheck(target) {
       "--out-format=%n",
       `${dist}${path.sep}`,
       `${runtimeDist}${path.sep}`
-    ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    ];
+    if (artifact.status !== "valid") rsyncArgs.splice(1, 0, "--exclude", "_metadata");
+    output = execFileSync("rsync", rsyncArgs, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
   } catch {
-    return { status: "stale", modified: ["<snapshot comparison failed>"] };
+    return { status: "stale", modified: ["<snapshot comparison failed>"], ...identity };
   }
   const modified = output.split("\n").map((line) => line.trim()).filter(Boolean);
-  for (const name of ["home.html", "sidepanel.html"]) {
-    const source = path.join(dist, name);
-    const loaded = path.join(runtimeDist, name);
-    if (normalizedRuntimeHtml(source) !== normalizedRuntimeHtml(loaded)) modified.push(name);
-  }
-  if (normalizedRuntimeManifest(path.join(dist, "manifest.json")) !== normalizedRuntimeManifest(path.join(runtimeDist, "manifest.json"))) {
-    modified.push("manifest.json");
+  if (artifact.status === "valid") {
+    for (const name of ["home.html", "sidepanel.html", "manifest.json"]) {
+      const source = path.join(dist, name);
+      const loaded = path.join(runtimeDist, name);
+      if (fileDigest(source) !== fileDigest(loaded)) modified.push(name);
+    }
+  } else {
+    for (const name of ["home.html", "sidepanel.html"]) {
+      const source = path.join(dist, name);
+      const loaded = path.join(runtimeDist, name);
+      if (normalizedRuntimeHtml(source) !== normalizedRuntimeHtml(loaded)) modified.push(name);
+    }
+    if (normalizedRuntimeManifest(path.join(dist, "manifest.json")) !== normalizedRuntimeManifest(path.join(runtimeDist, "manifest.json"))) {
+      modified.push("manifest.json");
+    }
   }
   const boundedModified = [...new Set(modified)].slice(0, 10);
-  return boundedModified.length > 0 ? { status: "stale", modified: boundedModified } : { status: "fresh" };
+  return boundedModified.length > 0 ? { status: "stale", modified: boundedModified, ...identity } : { status: "fresh", ...identity };
+}
+function fileDigest(file) {
+  return fs.existsSync(file) ? crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") : null;
 }
 function normalizedRuntimeHtml(file) {
   if (!fs.existsSync(file)) return null;
@@ -269,10 +371,11 @@ async function decideExtensionReadiness(target, options = {}) {
   const deps = depsCheck(resolved);
   const webpackCache = webpackCacheCheck(resolved);
   const buildLog = buildLogCheck(resolved, options.watchLog);
-  const dist = distCheck(resolved);
-  const runtimeDist = runtimeDistCheck(resolved);
+  const releaseArtifact = releaseArtifactState(resolved);
+  const dist = releaseArtifact.status === "valid" ? releaseArtifactDistCheck(releaseArtifact) : distCheck(resolved);
+  const runtimeDist = runtimeDistCheck(resolved, releaseArtifact);
   const cdp = await cdpCheck(resolved, options.cdpPort, options.pageMode);
-  const checks = { deps, webpackCache, buildLog, dist, runtimeDist, cdp };
+  const checks = { deps, webpackCache, buildLog, dist, runtimeDist, releaseArtifact, cdp };
   const install = [{ id: "yarn-install", argv: ["yarn", "install", "--immutable"], cwd: resolved }];
   const relaunch = [{ id: "relaunch-browser" }];
   const cacheStale = buildLog.reason === "stale-cache";
@@ -355,7 +458,47 @@ async function decideExtensionReadiness(target, options = {}) {
     reasons: ["Build is fresh; browser liveness unverified (pass --cdp-port to confirm `ready`)."],
     actions: relaunch
   };
-  const core = rules.find((rule) => rule.when) ?? fallback;
+  let core;
+  if (releaseArtifact.status === "invalid") {
+    core = {
+      decision: "blocked",
+      reasonCode: "release-artifact-identity-invalid",
+      reasons: [`The loaded release artifact identity is invalid: ${releaseArtifact.reason ?? "unknown reason"}.`],
+      actions: []
+    };
+  } else if (releaseArtifact.status === "valid") {
+    const artifactRules = [
+      {
+        when: runtimeDist.status !== "fresh",
+        decision: "relaunch",
+        reasonCode: runtimeDist.status === "missing" ? "release-artifact-runtime-missing" : "release-artifact-runtime-stale",
+        reasons: [runtimeDist.status === "missing" ? "The loaded release artifact snapshot is missing." : `The loaded runtime snapshot differs from release artifact ${releaseArtifact.sha256?.slice(0, 12)}.`],
+        actions: relaunch
+      },
+      {
+        when: cdp.status === "pass",
+        decision: "ready",
+        reasonCode: "release-artifact-healthy",
+        reasons: [`Release artifact ${releaseArtifact.expectedVersion} is intact and healthy over CDP.`],
+        actions: []
+      },
+      {
+        when: cdp.status === "fail",
+        decision: "relaunch",
+        reasonCode: "runtime-unhealthy",
+        reasons: ["The release artifact is intact but the live extension is unhealthy.", ...cdp.findings?.slice(0, 3) ?? []],
+        actions: relaunch
+      }
+    ];
+    core = artifactRules.find((rule) => rule.when) ?? {
+      decision: "relaunch",
+      reasonCode: "cdp-unknown",
+      reasons: [`Release artifact ${releaseArtifact.expectedVersion} is intact; browser liveness is unverified.`],
+      actions: relaunch
+    };
+  } else {
+    core = rules.find((rule) => rule.when) ?? fallback;
+  }
   return {
     schemaVersion: 1,
     adapter: "extension",
@@ -378,5 +521,6 @@ export {
   decideExtensionReadiness,
   isExtensionDistStale,
   recordWebpackBaseline,
+  releaseArtifactState,
   runtimeDistCheck
 };