chainlesschain 0.165.6 → 0.165.8

package/src/lib/plugin-runtime/hooks.js

@@ -215,7 +215,9 @@ export function collectPluginHooks(opts = {}) {
   }
   // A hook runs a shell command — gate it behind trust so a cloned repo's
   // project plugin can't run commands the moment the agent starts.
-  const { trusted, skipped } = partitionByTrust(plugins);
+  const { trusted, skipped } = partitionByTrust(plugins, {
+    workspaceRoot: opts.cwd,
+  });
   warnUntrustedOnce(
     skipped.filter((p) => p.manifest?.components?.hooks).map((p) => p.name),
     "hooks",

package/src/lib/plugin-runtime/install.js

@@ -326,6 +326,10 @@ export function installFromDirectory(srcDir, opts = {}) {
     // and may ship its own `.plugin-lock.json` or provenance metadata.
     _deps.rmSync(path.join(staged, LOCK_FILENAME), { force: true });
     _deps.rmSync(path.join(staged, SOURCE_METADATA_FILENAME), { force: true });
+    assertStagedRegistryCommandPayload(
+      staged,
+      opts[SOURCE_POLICY_PREFLIGHT]?.registryAuthority,
+    );
 
     const remoteSbomPayloadComparison = buildRemoteSbomPayloadComparison({
       remoteArtifactEvidence:
@@ -657,6 +661,19 @@ function preflightManagedSource(source, opts, action, options = {}) {
         );
       }
     }
+    if (registryAuthority.sourceType === "command") {
+      const command = opts.sourceMetadata.catalogAuthority?.commandSource;
+      if (
+        !command ||
+        command.descriptorIdentity !== registryAuthority.declaredSource ||
+        command.payloadSha256 !== registryAuthority.payloadSha256 ||
+        command.mode !== registryAuthority.commandMode
+      ) {
+        throw new Error(
+          "registry source authority does not match command source authority",
+        );
+      }
+    }
   }
   // Resolve managed identity before exists/clone/cache/process work. The
   // manifest name is checked again by installFromDirectory after materializing
@@ -693,6 +710,7 @@ function preflightManagedSource(source, opts, action, options = {}) {
     decision,
     materialized,
     sourceAuthority,
+    registryAuthority,
   };
   const boundSourceMetadata = opts.sourceMetadata
     ? bindSourcePolicyAuthority(opts.sourceMetadata, {
@@ -3638,7 +3656,16 @@ function normalizeSourceMetadata(value) {
             value.resolvedSource,
             catalogAuthority.archiveSource,
           )
-        : pluginSourceAuthorityDigest(value.resolvedSource, "git", value.ref)
+        : catalogAuthority?.commandSource
+          ? commandSourceAuthorityDigest(
+              value.resolvedSource,
+              catalogAuthority.commandSource,
+            )
+          : pluginSourceAuthorityDigest(
+              value.resolvedSource,
+              "git",
+              value.ref,
+            )
       : null);
   const policyDigest = normalizeSourceAuthorityDigest(value.policyDigest);
   if (resolvedSourceDigest) {
@@ -3650,6 +3677,7 @@ function normalizeSourceMetadata(value) {
   if (catalogAuthority) metadata.catalogAuthority = catalogAuthority;
   assertCatalogRemoteArtifactBindings(metadata);
   assertCatalogArchiveSourceBindings(metadata);
+  assertCatalogCommandSourceBindings(metadata);
   return metadata;
 }
 
@@ -3681,6 +3709,20 @@ function assertCatalogArchiveSourceBindings(metadata) {
   }
 }
 
+function assertCatalogCommandSourceBindings(metadata) {
+  const command = metadata.catalogAuthority?.commandSource;
+  if (!command) return;
+  if (
+    metadata.type !== "registry" ||
+    !metadata.registry ||
+    metadata.resolvedSource !== command.descriptorIdentity
+  ) {
+    throw new Error(
+      "marketplace command authority requires matching registry source metadata",
+    );
+  }
+}
+
 function normalizeSourceAuthorityDigest(value) {
   const normalized = cleanBounded(value, 64)?.toLowerCase() || null;
   return normalized && /^[a-f0-9]{64}$/u.test(normalized) ? normalized : null;
@@ -3718,11 +3760,28 @@ function archiveSourceAuthorityDigest(source, archive) {
     .digest("hex");
 }
 
+function commandSourceAuthorityDigest(source, command) {
+  return crypto
+    .createHash("sha256")
+    .update(
+      canonicalJson({
+        kind: "command",
+        descriptorIdentity: sanitizeSource(source),
+        mode: command.mode || command.commandMode || null,
+        payloadSha256: command.payloadSha256 || null,
+      }),
+    )
+    .digest("hex");
+}
+
 function registryResolvedSourceAuthorityDigest(authority) {
   if (!authority) return null;
   if (authority.sourceType === "archive") {
     return archiveSourceAuthorityDigest(authority.declaredSource, authority);
   }
+  if (authority.sourceType === "command") {
+    return commandSourceAuthorityDigest(authority.declaredSource, authority);
+  }
   return pluginSourceAuthorityDigest(
     authority.declaredSource,
     "git",
@@ -4030,6 +4089,12 @@ function normalizeCatalogAuthority(value) {
     value.remoteArtifactEvidence,
   );
   const archiveSource = normalizeArchiveSourceAuthority(value.archiveSource);
+  const commandSource = normalizeCommandSourceAuthority(value.commandSource);
+  if (archiveSource && commandSource) {
+    throw new Error(
+      "catalogAuthority cannot combine archive and command source authority",
+    );
+  }
   const remoteSbomPayloadComparison = assertRemoteSbomPayloadComparison(
     value.remoteSbomPayloadComparison,
     {
@@ -4137,6 +4202,7 @@ function normalizeCatalogAuthority(value) {
     ...(artifactExpectations ? { artifactExpectations } : {}),
     ...(remoteArtifactEvidence ? { remoteArtifactEvidence } : {}),
     ...(archiveSource ? { archiveSource } : {}),
+    ...(commandSource ? { commandSource } : {}),
     ...(remoteSbomPayloadComparison ? { remoteSbomPayloadComparison } : {}),
     ...(publisherDeclaration ? { publisherDeclaration } : {}),
     ...(publisherAuthority ? { publisherAuthority } : {}),
@@ -4213,6 +4279,42 @@ function normalizeArchiveSourceAuthority(value) {
   };
 }
 
+function normalizeCommandSourceAuthority(value) {
+  if (value == null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("catalogAuthority.commandSource must be an object");
+  }
+  const descriptorIdentity = cleanBounded(value.descriptorIdentity, 128);
+  const payloadSha256 = cleanBounded(value.payloadSha256, 64)?.toLowerCase();
+  const mode = value.mode;
+  const fileCount = Number(value.fileCount);
+  const totalBytes = Number(value.totalBytes);
+  if (
+    value.schemaVersion !== "cc-plugin-marketplace-command-source/v1" ||
+    value.status !== "descriptor-executed-and-verified" ||
+    !/^command:[a-f0-9]{32}$/u.test(descriptorIdentity || "") ||
+    !/^[a-f0-9]{64}$/u.test(payloadSha256 || "") ||
+    !["copy", "link"].includes(mode) ||
+    !Number.isSafeInteger(fileCount) ||
+    fileCount <= 0 ||
+    fileCount > 10_000 ||
+    !Number.isSafeInteger(totalBytes) ||
+    totalBytes <= 0 ||
+    totalBytes > 256 * 1024 * 1024
+  ) {
+    throw new Error("catalogAuthority.commandSource authority is invalid");
+  }
+  return {
+    schemaVersion: value.schemaVersion,
+    status: value.status,
+    descriptorIdentity,
+    mode,
+    payloadSha256,
+    fileCount,
+    totalBytes,
+  };
+}
+
 function normalizeArtifactExpectations(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const digest = (candidate, label) => {
@@ -4618,6 +4720,20 @@ function writeDurableFileAtomic(directory, target, value) {
   }
 }
 
+function assertStagedRegistryCommandPayload(staged, authority) {
+  if (authority?.sourceType !== "command") return;
+  const payload = buildMarketplacePayloadSbom(staged);
+  if (
+    payload.digest !== authority.payloadSha256 ||
+    payload.fileCount !== authority.fileCount ||
+    payload.totalBytes !== authority.totalBytes
+  ) {
+    throw new Error(
+      "registry command source payload changed before immutable installation",
+    );
+  }
+}
+
 /**
  * Copy `src` → `dst`, refusing to write outside `root` and skipping symlinks
  * (which could later resolve outside the plugin sandbox). Directories recurse.

package/src/lib/plugin-runtime/lsp.js

@@ -63,7 +63,9 @@ export function ensurePluginLspServers(opts = {}) {
 
   // An LSP server spawns a binary — gate it behind trust. Untrusted project
   // plugins (e.g. from a cloned repo) don't get to launch processes silently.
-  const { trusted, skipped } = partitionByTrust(plugins);
+  const { trusted, skipped } = partitionByTrust(plugins, {
+    workspaceRoot: cwd,
+  });
   warnUntrustedOnce(
     skipped
       .filter((p) => (p.manifest?.components?.lsp || []).length > 0)
@@ -95,9 +97,7 @@ export function ensurePluginLspServers(opts = {}) {
           pluginId: p.name,
           pluginVersion: p.version,
           pluginSource: s.absPath || p.manifest.manifestPath,
-          ...(s.sandboxPolicy
-            ? { sandboxPolicy: s.sandboxPolicy }
-            : {}),
+          ...(s.sandboxPolicy ? { sandboxPolicy: s.sandboxPolicy } : {}),
         });
         registered.push({ plugin: p.name, languageId: s.languageId, id: s.id });
       } catch {

package/src/lib/plugin-runtime/marketplace-archive-source.js

@@ -7,6 +7,7 @@ import {
   assertSafeInstalledPluginStructure,
   buildMarketplacePayloadSbom,
 } from "./marketplace-artifact-readback.js";
+import { createSameOriginMarketplaceHeaderFetch } from "./marketplace-command-source.js";
 import { createMarketplaceNetworkTransport } from "./marketplace-network.js";
 import { fetchMarketplaceRemoteArtifact } from "./marketplace-remote-artifacts.js";
 
@@ -96,11 +97,28 @@ function parsePax(data) {
   return values;
 }
 
-function extractVerifiedTgz(bytes, destination) {
+function extractionLimits(limits = MARKETPLACE_ARCHIVE_LIMITS) {
+  const expandedBytes = Number(limits?.expandedBytes);
+  const entries = Number(limits?.entries);
+  if (
+    !Number.isSafeInteger(expandedBytes) ||
+    expandedBytes <= 0 ||
+    expandedBytes > MARKETPLACE_ARCHIVE_LIMITS.expandedBytes ||
+    !Number.isSafeInteger(entries) ||
+    entries <= 0 ||
+    entries > MARKETPLACE_ARCHIVE_LIMITS.entries
+  ) {
+    throw new Error("Marketplace archive extraction limits are invalid");
+  }
+  return { expandedBytes, entries };
+}
+
+function extractVerifiedTgz(bytes, destination, limits = MARKETPLACE_ARCHIVE_LIMITS) {
+  const bounded = extractionLimits(limits);
   let tar;
   try {
     tar = gunzipSync(bytes, {
-      maxOutputLength: MARKETPLACE_ARCHIVE_LIMITS.expandedBytes,
+      maxOutputLength: bounded.expandedBytes,
     });
   } catch {
     throw new Error("Marketplace archive is not a bounded valid gzip stream");
@@ -129,7 +147,7 @@ function extractVerifiedTgz(bytes, destination) {
     const data = tar.subarray(dataStart, dataEnd);
     offset = dataStart + Math.ceil(size / 512) * 512;
     records += 1;
-    if (records > MARKETPLACE_ARCHIVE_LIMITS.entries) {
+    if (records > bounded.entries) {
       throw new Error("archive contains too many entries");
     }
 
@@ -176,7 +194,7 @@ function extractVerifiedTgz(bytes, destination) {
       continue;
     }
     extractedBytes += data.length;
-    if (extractedBytes > MARKETPLACE_ARCHIVE_LIMITS.expandedBytes) {
+    if (extractedBytes > bounded.expandedBytes) {
       throw new Error("archive expanded payload exceeds its byte limit");
     }
     fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o755 });
@@ -188,6 +206,14 @@ function extractVerifiedTgz(bytes, destination) {
   return buildMarketplacePayloadSbom(destination);
 }
 
+// Kept deliberately private-by-convention: production callers always use the
+// immutable limits above, while focused security tests can exercise the same
+// parser with a tiny bounded fixture instead of allocating a 256 MiB bomb.
+export const _marketplaceArchiveTest = Object.freeze({
+  extractVerifiedTgz: (bytes, destination, limits) =>
+    extractVerifiedTgz(bytes, destination, limits),
+});
+
 function cacheRoot(configured) {
   return (
     configured || path.join(getElectronUserDataDir(), "plugin-archive-sources")
@@ -240,6 +266,15 @@ export async function fetchAndMaterializeMarketplaceArchive(options = {}) {
     (options.proxyUrl || options.pacFile || options.caFile)
       ? createMarketplaceNetworkTransport(options)
       : null;
+  const transportFetch =
+    options.fetchImpl || networkTransport?.fetch || globalThis.fetch?.bind(globalThis);
+  const fetchImpl = options.requestHeaders
+    ? createSameOriginMarketplaceHeaderFetch(
+        transportFetch,
+        new URL(options.registryUrl).origin,
+        options.requestHeaders,
+      )
+    : transportFetch;
   let artifact;
   try {
     artifact = await fetchMarketplaceRemoteArtifact({
@@ -253,7 +288,7 @@ export async function fetchAndMaterializeMarketplaceArchive(options = {}) {
       offline: options.offline === true,
       cacheDir: options.artifactCacheDir,
       timeoutMs: options.timeoutMs,
-      fetchImpl: options.fetchImpl || networkTransport?.fetch,
+      fetchImpl,
       resolveHostname: options.resolveHostname,
     });
   } finally {

package/src/lib/plugin-runtime/marketplace-catalog.js

@@ -480,7 +480,9 @@ function normalizeCandidate(entry, context) {
       ? packageSource.url
       : packageSource?.type === "git"
         ? packageSource.source
-        : "";
+        : packageSource?.type === "command"
+          ? packageSource.identity
+          : "";
   const sourceUrl = sanitizeUrl(sourceValue) || sourceValue || null;
   const ref = packageSource?.type === "git" ? packageSource.ref : null;
 
@@ -639,7 +641,16 @@ function normalizeCandidate(entry, context) {
             archiveSha256: packageSource.sha256,
             format: packageSource.format,
           }
-        : packageSource?.type === "dynamic-disabled"
+        : packageSource?.type === "command"
+          ? {
+              type: "command",
+              // The descriptor itself may carry local credentials. Catalog
+              // output binds only its non-secret canonical identity.
+              source: packageSource.identity,
+              ref: null,
+              mode: packageSource.mode,
+            }
+          : packageSource?.type === "dynamic-disabled"
           ? {
               type: "dynamic-disabled",
               source: null,

package/src/lib/plugin-runtime/marketplace-command-descriptor.js

@@ -0,0 +1,343 @@
+import crypto from "node:crypto";
+import path from "node:path";
+
+export const MARKETPLACE_COMMAND_DESCRIPTOR_ERROR = Object.freeze({
+  INVALID: "CC_MARKETPLACE_COMMAND_DESCRIPTOR_INVALID",
+  SHELL_REJECTED: "CC_MARKETPLACE_COMMAND_DESCRIPTOR_SHELL_REJECTED",
+  LINK_UNSUPPORTED: "CC_MARKETPLACE_COMMAND_LINK_UNSUPPORTED",
+});
+
+export const MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS = Object.freeze({
+  maxArgs: 128,
+  maxArgumentBytes: 8 * 1024,
+  maxTotalArgumentBytes: 32 * 1024,
+  maxEnvironmentEntries: 32,
+  maxEnvironmentValueBytes: 8 * 1024,
+  minTimeoutMs: 100,
+  maxTimeoutMs: 30_000,
+  defaultTimeoutMs: 10_000,
+  minOutputBytes: 1024,
+  maxSourceOutputBytes: 4 * 1024 * 1024,
+  maxHeadersOutputBytes: 64 * 1024,
+});
+
+const CONTROL = /[\u0000-\u001f\u007f]/u;
+const ENVIRONMENT_KEY = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/u;
+export const MARKETPLACE_COMMAND_SAFE_ENVIRONMENT_KEYS = Object.freeze([
+  "COMSPEC",
+  "HOME",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "LC_MESSAGES",
+  "NODE_EXTRA_CA_CERTS",
+  "PATH",
+  "PATHEXT",
+  "SSL_CERT_DIR",
+  "SSL_CERT_FILE",
+  "SYSTEMROOT",
+  "TEMP",
+  "TMP",
+  "TMPDIR",
+  "USERPROFILE",
+  "WINDIR",
+  "XDG_CACHE_HOME",
+  "XDG_CONFIG_HOME",
+]);
+const SAFE_ENVIRONMENT_KEYS = new Set(
+  MARKETPLACE_COMMAND_SAFE_ENVIRONMENT_KEYS,
+);
+const SHELL_EXECUTABLES = new Set([
+  "bash",
+  "busybox",
+  "cmd",
+  "command",
+  "dash",
+  "env",
+  "fish",
+  "ksh",
+  "nu",
+  "powershell",
+  "pwsh",
+  "sh",
+  "zsh",
+]);
+
+function descriptorError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function plainObject(value, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.getPrototypeOf(value) !== Object.prototype
+  ) {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+      `${label} must be a JSON object`,
+    );
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (typeof key !== "string" || !("value" in descriptors[key])) {
+      throw descriptorError(
+        MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+        `${label} must contain only own data properties`,
+      );
+    }
+  }
+  return descriptors;
+}
+
+function exactKeys(descriptors, allowed, label) {
+  for (const key of Object.keys(descriptors)) {
+    if (!allowed.has(key)) {
+      throw descriptorError(
+        MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+        `${label} contains unsupported field: ${key}`,
+      );
+    }
+  }
+}
+
+function boundedString(value, label, maxBytes) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.trim() !== value ||
+    CONTROL.test(value) ||
+    Buffer.byteLength(value, "utf8") > maxBytes
+  ) {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+      `${label} must be a non-empty bounded string`,
+    );
+  }
+  return value;
+}
+
+function normalizeAbsolutePath(value, label) {
+  const text = boundedString(value, label, 4096);
+  if (!path.isAbsolute(text)) {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+      `${label} must be an absolute path`,
+    );
+  }
+  return path.normalize(text);
+}
+
+function executableBasename(value) {
+  return path
+    .basename(value)
+    .replace(/\.(?:cmd|com|exe|bat)$/iu, "")
+    .toLowerCase();
+}
+
+function normalizeExecutable(value) {
+  const executable = normalizeAbsolutePath(
+    value,
+    "Marketplace command executable",
+  );
+  if (SHELL_EXECUTABLES.has(executableBasename(executable))) {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.SHELL_REJECTED,
+      "Marketplace command descriptors must not invoke a shell",
+    );
+  }
+  return executable;
+}
+
+function normalizeArguments(value) {
+  if (value === undefined) return Object.freeze([]);
+  if (
+    !Array.isArray(value) ||
+    value.length > MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxArgs
+  ) {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+      "Marketplace command args must be a bounded string array",
+    );
+  }
+  let totalBytes = 0;
+  const args = value.map((argument) => {
+    const normalized = boundedString(
+      argument,
+      "Marketplace command argument",
+      MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxArgumentBytes,
+    );
+    totalBytes += Buffer.byteLength(normalized, "utf8");
+    return normalized;
+  });
+  if (
+    totalBytes > MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxTotalArgumentBytes
+  ) {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+      "Marketplace command arguments exceed the byte limit",
+    );
+  }
+  return Object.freeze(args);
+}
+
+function normalizeEnvironment(value) {
+  if (value === undefined) return Object.freeze({});
+  const descriptors = plainObject(value, "Marketplace command env");
+  const keys = Object.keys(descriptors);
+  if (
+    keys.length > MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxEnvironmentEntries
+  ) {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+      "Marketplace command env has too many entries",
+    );
+  }
+  const environment = {};
+  for (const key of keys.sort()) {
+    const normalizedKey = key.toUpperCase();
+    if (
+      !ENVIRONMENT_KEY.test(key) ||
+      key !== normalizedKey ||
+      !SAFE_ENVIRONMENT_KEYS.has(normalizedKey)
+    ) {
+      throw descriptorError(
+        MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+        "Marketplace command env contains a disallowed key",
+      );
+    }
+    environment[key] = boundedString(
+      descriptors[key].value,
+      "Marketplace command env value",
+      MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxEnvironmentValueBytes,
+    );
+  }
+  return Object.freeze(environment);
+}
+
+function normalizeBoundedInteger(value, fallback, minimum, maximum, label) {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+      `${label} must be an integer between ${minimum} and ${maximum}`,
+    );
+  }
+  return value;
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, canonicalize(value[key])]),
+  );
+}
+
+/**
+ * Parse the intentionally narrow Marketplace process descriptor. The
+ * descriptor is JSON-serializable, has no shell-string field, and contains
+ * the complete executable/argv/cwd/environment plan that the runner consumes.
+ */
+export function normalizeMarketplaceCommandDescriptor(raw, options = {}) {
+  const label = options.label || "Marketplace command descriptor";
+  const kind = options.kind || "source";
+  const descriptors = plainObject(raw, label);
+  const allowMode = kind === "source";
+  exactKeys(
+    descriptors,
+    new Set([
+      ...(options.allowType === true ? ["type"] : []),
+      "executable",
+      "args",
+      "cwd",
+      "env",
+      "timeoutMs",
+      "maxOutputBytes",
+      ...(allowMode ? ["mode"] : []),
+    ]),
+    label,
+  );
+  if (options.allowType === true && descriptors.type?.value !== "command") {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+      `${label}.type must be command`,
+    );
+  }
+
+  const maxOutputBytes = normalizeBoundedInteger(
+    descriptors.maxOutputBytes?.value,
+    kind === "headers"
+      ? MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxHeadersOutputBytes
+      : MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxSourceOutputBytes,
+    MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.minOutputBytes,
+    kind === "headers"
+      ? MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxHeadersOutputBytes
+      : MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxSourceOutputBytes,
+    `${label}.maxOutputBytes`,
+  );
+  const mode = allowMode ? descriptors.mode?.value || "copy" : null;
+  if (allowMode && !new Set(["copy", "link"]).has(mode)) {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.INVALID,
+      `${label}.mode must be copy or link`,
+    );
+  }
+  return Object.freeze({
+    executable: normalizeExecutable(descriptors.executable?.value),
+    args: normalizeArguments(descriptors.args?.value),
+    cwd: normalizeAbsolutePath(
+      descriptors.cwd?.value,
+      "Marketplace command cwd",
+    ),
+    env: normalizeEnvironment(descriptors.env?.value),
+    timeoutMs: normalizeBoundedInteger(
+      descriptors.timeoutMs?.value,
+      MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.defaultTimeoutMs,
+      MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.minTimeoutMs,
+      MARKETPLACE_COMMAND_DESCRIPTOR_LIMITS.maxTimeoutMs,
+      `${label}.timeoutMs`,
+    ),
+    maxOutputBytes,
+    ...(allowMode ? { mode } : {}),
+  });
+}
+
+/** A non-secret stable projection suitable for catalog identity only. */
+export function marketplaceCommandDescriptorIdentity(descriptor) {
+  const normalized = normalizeMarketplaceCommandDescriptor(descriptor, {
+    kind: "source",
+    allowType: Object.prototype.hasOwnProperty.call(descriptor || {}, "type"),
+  });
+  const projection = {
+    executable: normalized.executable,
+    args: normalized.args,
+    cwd: normalized.cwd,
+    envKeys: Object.keys(normalized.env).sort(),
+    timeoutMs: normalized.timeoutMs,
+    maxOutputBytes: normalized.maxOutputBytes,
+    mode: normalized.mode,
+  };
+  return `command:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonicalize(projection)))
+    .digest("hex")
+    .slice(0, 32)}`;
+}
+
+export function assertMarketplaceCommandModeSupported(
+  mode,
+  platform = process.platform,
+) {
+  if (mode === "link" && platform === "win32") {
+    throw descriptorError(
+      MARKETPLACE_COMMAND_DESCRIPTOR_ERROR.LINK_UNSUPPORTED,
+      "Marketplace command source mode link is not supported on Windows",
+    );
+  }
+}