release-skill 0.2.6 → 0.2.7

package/src/commands/verify.mjs

@@ -63,6 +63,10 @@ import {
   shouldSkipVerification,
   INSTALLATION_CONTRACT_ALGORITHM_VERSION,
 } from '../core/installation-contract.mjs';
+import {
+  buildDirectoryFileIndex,
+  checkNpmEntryClosure,
+} from '../npm/npm-entry-closure.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -294,6 +298,30 @@ export async function runSmokeTest(plan, root, options = {}) {
       }
 
       const pkgRoot = join(installDir, 'node_modules', pkgName);
+
+      // Entry closure check: verify all declared entry points (bin, main,
+      // module, types, typings, exports) exist as regular files in the
+      // installed package. This catches incident-class tarballs where
+      // name/version are correct but distribution files are missing.
+      {
+        const dirIndex = await buildDirectoryFileIndex(pkgRoot);
+        const closureResult = checkNpmEntryClosure(installedPkg, dirIndex);
+        if (closureResult.errors.length > 0) {
+          return {
+            passed: false,
+            details: {
+              gate: 'npm-entry-closure',
+              error: `npm entry closure check failed for ${packageAtVersion}: ${closureResult.errors.map((e) => e.message).join('; ')}`,
+              packageAtVersion,
+              unitId,
+              entries: closureResult.entries,
+              errors: closureResult.errors,
+              diagnostics: closureResult.diagnostics,
+            },
+          };
+        }
+      }
+
       if (plan.skillResourceClosure) {
         const expectedUnitReceipt = plan.skillResourceClosure.unitReceipts
           .find((item) => item.unitId === unitId);
@@ -1225,7 +1253,6 @@ export async function verifyRelease(options) {
                   }
                 : {
                     HOME: resolve(runDir, 'consumers', `kimi-${action.parameters.plugin}`),
-                    KIMI_CODE_HOME: resolve(runDir, 'consumers', `kimi-${action.parameters.plugin}`),
                   },
         }));
       } else {

package/src/npm/npm-entry-closure.mjs

@@ -0,0 +1,195 @@
+import { tmpdir } from 'node:os';
+
+import {
+  buildNpmTarballFileIndex,
+  computeFrozenSnapshot,
+} from '../snapshot/frozen.mjs';
+
+const SIMPLE_FIELDS = ['main', 'module', 'types', 'typings'];
+
+function entryError(field, target, reason, message) {
+  return { field, target, reason, message };
+}
+
+function validateRelativeTarget(target, field, { requireDotSlash = false } = {}) {
+  if (typeof target !== 'string' || target.length === 0) {
+    return {
+      error: entryError(field, String(target ?? ''), 'invalid_type', `${field} target must be a non-empty string`),
+    };
+  }
+  if (target.includes('\0')) {
+    return { error: entryError(field, target, 'nul_in_path', `${field} target must not contain NUL`) };
+  }
+  if (
+    target.startsWith('/') ||
+    /^[A-Za-z]:[/\\]/.test(target) ||
+    target.startsWith('\\\\')
+  ) {
+    return { error: entryError(field, target, 'absolute_path', `${field} target must be package-relative`) };
+  }
+  if (target.includes('\\')) {
+    return { error: entryError(field, target, 'backslash_path', `${field} target must use forward slashes`) };
+  }
+  if (requireDotSlash && !target.startsWith('./')) {
+    return {
+      error: entryError(field, target, 'missing_dot_slash', `${field} target must start with "./"`),
+    };
+  }
+
+  const relativeTarget = target.startsWith('./') ? target.slice(2) : target;
+  const segments = relativeTarget.split('/');
+  if (segments.includes('..')) {
+    return {
+      error: entryError(field, target, 'path_escape', `${field} target escapes the package root`),
+    };
+  }
+  if (
+    relativeTarget.length === 0 ||
+    segments.some((segment) => segment === '' || segment === '.')
+  ) {
+    return {
+      error: entryError(field, target, 'unsafe_segment', `${field} target contains an unsafe path segment`),
+    };
+  }
+  if (requireDotSlash && segments.includes('node_modules')) {
+    return {
+      error: entryError(field, target, 'unsafe_segment', `${field} target must not contain node_modules`),
+    };
+  }
+  return { target: relativeTarget };
+}
+
+function checkTarget({ field, target, fileIndex, requireDotSlash = false }) {
+  const validated = validateRelativeTarget(target, field, { requireDotSlash });
+  if (validated.error) return { errors: [validated.error], entries: [] };
+
+  const indexed = fileIndex.get(validated.target);
+  const found = indexed?.type === 'file';
+  const entries = [{ field, target: validated.target, found }];
+  if (found) return { entries, errors: [] };
+
+  const reason = indexed === undefined ? 'entry_missing' : 'entry_not_regular_file';
+  return {
+    entries,
+    errors: [
+      entryError(
+        field,
+        validated.target,
+        reason,
+        indexed === undefined
+          ? `${field} target "${validated.target}" is missing`
+          : `${field} target "${validated.target}" is not a regular file`,
+      ),
+    ],
+  };
+}
+
+function collectExports(value, location, result) {
+  if (value === null) return;
+  if (typeof value === 'string') {
+    if (value.includes('*')) {
+      result.errors.push(
+        entryError(
+          'exports',
+          value,
+          'unsupported_entry_shape',
+          `${location} uses a wildcard target that the static gate cannot verify`,
+        ),
+      );
+    } else {
+      result.targets.push({ field: `exports ${location}`, target: value });
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    result.errors.push(
+      entryError('exports', location, 'unsupported_entry_shape', `${location} uses unsupported fallback-array semantics`),
+    );
+    return;
+  }
+  if (typeof value !== 'object' || value === undefined) {
+    result.errors.push(
+      entryError('exports', String(value), 'invalid_exports_type', `${location} has an unsupported exports value`),
+    );
+    return;
+  }
+
+  for (const [key, child] of Object.entries(value)) {
+    const childLocation = `${location}.${key}`;
+    if (key.includes('*')) {
+      result.errors.push(
+        entryError(
+          'exports',
+          key,
+          'unsupported_entry_shape',
+          `${childLocation} uses a wildcard subpath that the static gate cannot verify`,
+        ),
+      );
+      continue;
+    }
+    collectExports(child, childLocation, result);
+  }
+}
+
+export function checkNpmEntryClosure(manifest, fileIndex) {
+  const result = { entries: [], errors: [], diagnostics: [] };
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    result.errors.push(entryError('manifest', '', 'invalid_manifest', 'manifest must be an object'));
+    return result;
+  }
+  if (!(fileIndex instanceof Map)) {
+    result.errors.push(entryError('fileIndex', '', 'invalid_file_index', 'fileIndex must be a Map'));
+    return result;
+  }
+
+  if (manifest.bin !== undefined && manifest.bin !== null) {
+    if (typeof manifest.bin === 'string') {
+      const checked = checkTarget({ field: 'bin', target: manifest.bin, fileIndex });
+      result.entries.push(...checked.entries);
+      result.errors.push(...checked.errors);
+    } else if (typeof manifest.bin === 'object' && !Array.isArray(manifest.bin)) {
+      for (const [name, target] of Object.entries(manifest.bin)) {
+        const checked = checkTarget({ field: 'bin', target, fileIndex });
+        result.entries.push(...checked.entries);
+        result.errors.push(...checked.errors);
+      }
+    } else {
+      result.errors.push(entryError('bin', String(manifest.bin), 'invalid_type', 'bin must be a string or object'));
+    }
+  }
+
+  for (const field of SIMPLE_FIELDS) {
+    if (manifest[field] === undefined || manifest[field] === null) continue;
+    const checked = checkTarget({ field, target: manifest[field], fileIndex });
+    result.entries.push(...checked.entries);
+    result.errors.push(...checked.errors);
+  }
+
+  if (manifest.exports !== undefined) {
+    const exportsResult = { targets: [], errors: [], diagnostics: [] };
+    collectExports(manifest.exports, 'exports', exportsResult);
+    result.errors.push(...exportsResult.errors);
+    result.diagnostics.push(...exportsResult.diagnostics);
+    for (const target of exportsResult.targets) {
+      const checked = checkTarget({
+        field: 'exports',
+        target: target.target,
+        fileIndex,
+        requireDotSlash: true,
+      });
+      result.entries.push(...checked.entries);
+      result.errors.push(...checked.errors);
+    }
+  }
+
+  return result;
+}
+
+export async function buildTarballFileIndex(tarballBytes, tarballDir = tmpdir()) {
+  return buildNpmTarballFileIndex({ tarballBytes, tarballDir });
+}
+
+export async function buildDirectoryFileIndex(packageDir) {
+  const snapshot = await computeFrozenSnapshot(packageDir, { excludeRootEntries: ['.git'] });
+  return new Map(snapshot.entries.map((entry) => [entry.path, { type: entry.type }]));
+}

package/src/platforms/codebuddy.mjs

@@ -141,13 +141,15 @@ export async function resolveCodeBuddyBoundPlanDigest(context) {
 /**
  * Authoritative, cross-run attestation directory for a codebuddy install.
  *
- * Lives at a stable root-fixed location keyed by the verified frozen plan
- * digest and plugin id:
- *   <root>/.release-skill/codebuddy-attestations/<planDigest>/<plugin>/
+ * Lives at a stable root-fixed location keyed by the plugin id:
+ *   <root>/.release-skill/codebuddy-attestations/<plugin>/
  *
  * This survives the publish -> manual install -> reconcile -> verify chain,
  * where each command otherwise uses a fresh runDir. Both the requirement and
- * the human attestation live here. Segments are pre-validated (planDigest is
+ * the human attestation live here. The planDigest parameter is still received
+ * and validated (it binds the attestation content), but the path itself is
+ * stable across plan versions — new plan requirements can atomically replace
+ * old ones in the same directory. Segments are pre-validated (planDigest is
  * 64-hex, plugin matches SAFE_ID_RE) and the resolved path is contained within
  * the authority base, so no path escape is possible. (Path-escape validation is
  * copied verbatim from kimiAuthorityDir, with codebuddy wording.)
@@ -168,7 +170,7 @@ export function codebuddyAuthorityDir(context, planDigest, plugin) {
     throw new Error(`codebuddy attestation authority requires a safe plugin id: "${plugin}"`);
   }
   const base = resolve(context.root, '.release-skill', 'codebuddy-attestations');
-  const dir = resolve(base, planDigest, plugin);
+  const dir = resolve(base, plugin);
   const rel = relative(base, dir);
   const sep = process.platform === 'win32' ? '\\' : '/';
   if (
@@ -452,7 +454,7 @@ export async function executeCodeBuddyManualRequirement(action, context) {
 
   const ref = action.ref ?? `v${action.version}`;
 
-  // (B) Stable, plan-digest-keyed authority dir, shared across
+  // (B) Stable plugin-level authority dir, shared across
   // publish/reconcile/verify run dirs.
   let attestationDir;
   try {
@@ -556,11 +558,17 @@ export async function executeCodeBuddyManualRequirement(action, context) {
     }
     const { createdAt: _existingCreatedAt, ...existingBody } = existing;
     if (canonicalJson(existingBody) !== canonicalJson(requirement)) {
-      return createResult({
-        actionType,
-        status: ActionStatus.EXECUTE_FAILED,
-        error: 'existing codebuddy manual-install requirement conflicts with the current frozen action; refusing to overwrite',
-      });
+      // 旧 plan 的 requirement 与新 plan 不同：允许原子替换（路径不再含 planDigest）。
+      // 但如果 planDigest 相同而内容不同，说明同一 plan 内的冻结动作不一致，仍失败关闭。
+      if (existing.planDigest === planDigest) {
+        return createResult({
+          actionType,
+          status: ActionStatus.EXECUTE_FAILED,
+          error: 'existing codebuddy manual-install requirement conflicts with the current frozen action (same planDigest); refusing to overwrite',
+        });
+      }
+      // 不同 planDigest：原子替换旧 plan 的 requirement
+      await writeEvidenceAtomic(requirementPath, { ...requirement, createdAt: new Date().toISOString() });
     }
   } else {
     await writeEvidenceAtomic(requirementPath, { ...requirement, createdAt: new Date().toISOString() });

package/src/platforms/codex.mjs

@@ -85,9 +85,11 @@ export async function resolveCodexBoundPlanDigest(context) {
 /**
  * Authoritative, cross-run attestation directory for a codex fallback install.
  *
- * Lives at a stable root-fixed location keyed by the verified frozen plan
- * digest and plugin id:
- *   <root>/.release-skill/codex-attestations/<planDigest>/<plugin>/
+ * Lives at a stable root-fixed location keyed by the plugin id:
+ *   <root>/.release-skill/codex-attestations/<plugin>/
+ *
+ * The planDigest parameter is still received and validated (it binds the
+ * attestation content), but the path itself is stable across plan versions.
  *
  * @param {object} context - adapter context (needs `root`).
  * @param {string} planDigest - verified frozen plan digest (64-hex).
@@ -105,7 +107,7 @@ export function codexAuthorityDir(context, planDigest, plugin) {
     throw new Error(`codex attestation authority requires a safe plugin id: "${plugin}"`);
   }
   const base = resolve(context.root, '.release-skill', 'codex-attestations');
-  const dir = resolve(base, planDigest, plugin);
+  const dir = resolve(base, plugin);
   const rel = relative(base, dir);
   const sep = process.platform === 'win32' ? '\\' : '/';
   if (
@@ -245,7 +247,7 @@ export async function executeCodexManualRequirement(action, context) {
 
   const ref = action.ref ?? `v${action.version}`;
 
-  // Stable, plan-digest-keyed authority dir.
+  // Stable plugin-level authority dir.
   let attestationDir;
   try {
     attestationDir = codexAuthorityDir(context, planDigest, action.plugin);
@@ -341,11 +343,17 @@ export async function executeCodexManualRequirement(action, context) {
     }
     const { createdAt: _existingCreatedAt, ...existingBody } = existing;
     if (canonicalJson(existingBody) !== canonicalJson(requirement)) {
-      return createResult({
-        actionType,
-        status: ActionStatus.EXECUTE_FAILED,
-        error: 'existing codex manual-install requirement conflicts with the current frozen action; refusing to overwrite',
-      });
+      // 旧 plan 的 requirement 与新 plan 不同：允许原子替换（路径不再含 planDigest）。
+      // 但如果 planDigest 相同而内容不同，说明同一 plan 内的冻结动作不一致，仍失败关闭。
+      if (existing.planDigest === planDigest) {
+        return createResult({
+          actionType,
+          status: ActionStatus.EXECUTE_FAILED,
+          error: 'existing codex manual-install requirement conflicts with the current frozen action (same planDigest); refusing to overwrite',
+        });
+      }
+      // 不同 planDigest：原子替换旧 plan 的 requirement
+      await writeEvidenceAtomic(requirementPath, { ...requirement, createdAt: new Date().toISOString() });
     }
   } else {
     await writeEvidenceAtomic(requirementPath, { ...requirement, createdAt: new Date().toISOString() });

package/src/platforms/kimi.mjs

@@ -129,16 +129,18 @@ export function resolveBoundPlanDigest(context) {
 /**
  * Authoritative, cross-run attestation directory for a kimi install.
  *
- * Lives at a stable root-fixed location keyed by the verified frozen plan
- * digest and plugin id:
- *   <root>/.release-skill/kimi-attestations/<planDigest>/<plugin>/
+ * Lives at a stable root-fixed location keyed by the plugin id:
+ *   <root>/.release-skill/kimi-attestations/<plugin>/
  *
  * This survives the publish -> manual install -> reconcile -> verify chain,
  * where each command otherwise uses a fresh runDir (an attestation written to a
  * publish runDir would be invisible to reconcile/verify). Both the requirement
- * and the human attestation live here. The segments are pre-validated (planDigest
- * is 64-hex, plugin matches SAFE_ID_RE) and the resolved path is contained
- * within the authority base, so no path escape is possible.
+ * and the human attestation live here. The planDigest parameter is still
+ * received and validated (it binds the attestation content), but the path
+ * itself is stable across plan versions — new plan requirements can atomically
+ * replace old ones in the same directory. The segments are pre-validated
+ * (planDigest is 64-hex, plugin matches SAFE_ID_RE) and the resolved path is
+ * contained within the authority base, so no path escape is possible.
  *
  * @param {object} context - adapter context (needs `root`).
  * @param {string} planDigest - verified frozen plan digest (64-hex).
@@ -156,7 +158,7 @@ export function kimiAuthorityDir(context, planDigest, plugin) {
     throw new Error(`kimi attestation authority requires a safe plugin id: "${plugin}"`);
   }
   const base = resolve(context.root, '.release-skill', 'kimi-attestations');
-  const dir = resolve(base, planDigest, plugin);
+  const dir = resolve(base, plugin);
   const rel = relative(base, dir);
   const sep = process.platform === 'win32' ? '\\' : '/';
   if (
@@ -187,7 +189,7 @@ function buildKimiInstallUrl(repo, ref) {
 /**
  * 统一人工安装说明：面向 Kimi Code 的人工结果流程。
  *
- * @param {{installUrl:string, plugin:string, version:string, ref:string, attestationDir:string, requiresInstalledClosure:boolean, managedRoot:string|null}} p
+ * @param {{installUrl:string, plugin:string, version:string, ref:string, attestationDir:string, requiresInstalledClosure:boolean}} p
  * @returns {string[]}
  */
 function buildKimiManualInstructions({
@@ -197,16 +199,15 @@ function buildKimiManualInstructions({
   ref,
   attestationDir,
   requiresInstalledClosure,
-  managedRoot,
 }) {
   return [
     `Kimi Code 没有可脚本化的插件安装命令行工具；安装是手动交互步骤。`,
     `1) publish 完成所有远端写入后进入 PUBLISHED 状态（自动化 Git 分支/标签、npm 和 GitHub Release 写入已完成）。此 kimi 检查点标记为需要人工安装。`,
-    `2) ${requiresInstalledClosure ? `以 KIMI_CODE_HOME="${resolve(managedRoot, '..', '..')}" 启动 Kimi Code，然后` : '在 Kimi Code 中'}运行: /plugins install ${installUrl}（锁定到冻结 ref "${ref}"，版本 ${version}）。确认插件 "${plugin}" 的信任提示，然后运行 /plugins reload（或 /new）。`,
+    `2) 在 Kimi Code 中运行: /plugins install ${installUrl}（锁定到冻结 ref "${ref}"，版本 ${version}）。确认插件 "${plugin}" 的信任提示，然后运行 /plugins reload（或 /new）。`,
     `3) 将人工结果 JSON 写入: ${attestationDir}/${KIMI_ATTESTATION_FILE}`,
-    `   必填字段: platform="kimi", version, planDigest（冻结计划摘要）, result("passed" 或 "failed"), actor（确认人）, confirmedAt（ISO 8601 时间戳）${requiresInstalledClosure ? '，installPath（实际安装后的插件目录，必须位于该证明目录的 kimi-home/plugins/managed/ 内）' : ''}`,
+    `   必填字段: platform="kimi", version, planDigest（冻结计划摘要）, result("passed" 或 "failed"), actor（确认人）, confirmedAt（ISO 8601 时间戳）${requiresInstalledClosure ? '，installPath（实际安装后的插件目录的真实路径）' : ''}`,
     `   可选字段: note（备注）`,
-    `4) 运行 release-skill reconcile（对账远端状态并跳过已完成步骤），然后 release-skill verify（从同一个计划摘要索引的权威目录读取结果，成功后 -> VERIFIED）。`,
+    `4) 若发布运行是 PARTIAL，先运行 release-skill reconcile；若已是 PUBLISHED，直接运行 release-skill verify。verify 从该插件的稳定证明目录读取并校验当前 planDigest，成功后 -> VERIFIED。`,
   ];
 }
 
@@ -433,7 +434,7 @@ export async function executeKimiManualRequirement(action, context) {
   const ref = action.ref ?? `v${action.version}`;
   const installUrl = buildKimiInstallUrl(action.repo, ref);
 
-  // (B) Stable, plan-digest-keyed authority dir, shared across
+  // (B) Stable plugin-level authority dir, shared across
   // publish/reconcile/verify run dirs.
   let attestationDir;
   try {
@@ -447,9 +448,6 @@ export async function executeKimiManualRequirement(action, context) {
   }
 
   const requiresInstalledClosure = Boolean(context.plan?.skillResourceClosure);
-  const managedRoot = requiresInstalledClosure
-    ? resolve(attestationDir, 'kimi-home', 'plugins', 'managed')
-    : null;
   const instructions = buildKimiManualInstructions({
     installUrl,
     plugin: action.plugin,
@@ -457,7 +455,6 @@ export async function executeKimiManualRequirement(action, context) {
     ref,
     attestationDir,
     requiresInstalledClosure,
-    managedRoot,
   });
 
   // 统一 requirement 结构：不再包含隔离目录信息
@@ -481,7 +478,7 @@ export async function executeKimiManualRequirement(action, context) {
       actor: '<person who confirmed the install>',
       confirmedAt: '<ISO 8601 timestamp>',
       ...(requiresInstalledClosure
-        ? { installPath: resolve(managedRoot, action.plugin) }
+        ? { installPath: '<actual installed plugin directory>' }
         : {}),
       note: '<optional note>',
     },
@@ -503,22 +500,6 @@ export async function executeKimiManualRequirement(action, context) {
     }
   }
 
-  // New closure plans must scan an actual installed consumer tree. Create only
-  // the isolated KIMI_CODE_HOME container; the interactive host remains the
-  // sole owner of managed/<plugin>. Legacy plans retain the previous no-home
-  // behavior byte-for-byte.
-  if (requiresInstalledClosure) {
-    try {
-      await mkdir(managedRoot, { recursive: true, mode: 0o700 });
-    } catch (mkdirErr) {
-      return createResult({
-        actionType,
-        status: ActionStatus.EXECUTE_FAILED,
-        error: `cannot create kimi resource-closure managed root: ${mkdirErr.message}`,
-      });
-    }
-  }
-
   // Idempotent requirement write: an identical existing requirement is left
   // untouched; a divergent existing requirement fails closed (never silently
   // overwritten). `createdAt` is volatile and excluded from the comparison.
@@ -557,11 +538,17 @@ export async function executeKimiManualRequirement(action, context) {
     }
     const { createdAt: _existingCreatedAt, ...existingBody } = existing;
     if (canonicalJson(existingBody) !== canonicalJson(requirement)) {
-      return createResult({
-        actionType,
-        status: ActionStatus.EXECUTE_FAILED,
-        error: 'existing kimi manual-install requirement conflicts with the current frozen action; refusing to overwrite',
-      });
+      // 旧 plan 的 requirement 与新 plan 不同：允许原子替换（路径不再含 planDigest）。
+      // 但如果 planDigest 相同而内容不同，说明同一 plan 内的冻结动作不一致，仍失败关闭。
+      if (existing.planDigest === planDigest) {
+        return createResult({
+          actionType,
+          status: ActionStatus.EXECUTE_FAILED,
+          error: 'existing kimi manual-install requirement conflicts with the current frozen action (same planDigest); refusing to overwrite',
+        });
+      }
+      // 不同 planDigest：原子替换旧 plan 的 requirement
+      await writeEvidenceAtomic(requirementPath, { ...requirement, createdAt: new Date().toISOString() });
     }
   } else {
     await writeEvidenceAtomic(requirementPath, { ...requirement, createdAt: new Date().toISOString() });

package/src/snapshot/frozen.mjs

@@ -547,7 +547,36 @@ async function runTarFromHandle(handle, args) {
   });
 }
 
-async function verifyNpmTarballContent({ snapshotDir, tarballBytes, tarballDir, expectedSnapshotDigest }) {
+function validateNpmTarballListing(listOut) {
+  const listed = listOut.split(/\r?\n/).filter(Boolean);
+  if (listed.length === 0) {
+    throw frozenError('npm tarball contains no entries');
+  }
+
+  const seen = new Set();
+  for (const entry of listed) {
+    if (
+      entry.startsWith('/') || entry.includes('\\') ||
+      (!entry.startsWith('package/') && entry !== 'package')
+    ) {
+      throw frozenError('npm tarball contains an unsafe or unexpected path', { entry });
+    }
+    const segments = entry.split('/');
+    const pathSegments = entry.endsWith('/') ? segments.slice(0, -1) : segments;
+    if (
+      pathSegments.some((segment) => segment === '' || segment === '.' || segment === '..')
+    ) {
+      throw frozenError('npm tarball contains an unsafe or unexpected path', { entry });
+    }
+    const canonicalPath = entry.endsWith('/') ? entry.slice(0, -1) : entry;
+    if (seen.has(canonicalPath)) {
+      throw frozenError('npm tarball contains a duplicate path', { entry: canonicalPath });
+    }
+    seen.add(canonicalPath);
+  }
+}
+
+async function inspectNpmTarballContent({ tarballBytes, tarballDir }) {
   const listHandle = await createDetachedReadHandle(tarballBytes, tarballDir);
   let listOut;
   try {
@@ -555,13 +584,7 @@ async function verifyNpmTarballContent({ snapshotDir, tarballBytes, tarballDir,
   } finally {
     await listHandle.close();
   }
-  const listed = listOut.split(/\r?\n/).filter(Boolean);
-  if (listed.length === 0 || listed.some((entry) => (
-    !entry.startsWith('package/') || entry.startsWith('/') || entry.includes('\\') ||
-    entry.split('/').some((segment) => segment === '..')
-  ))) {
-    throw frozenError('npm tarball contains an unsafe or unexpected path');
-  }
+  validateNpmTarballListing(listOut);
 
   const verifyDir = await mkdtemp(join(tarballDir, '.verify-'));
   try {
@@ -571,22 +594,31 @@ async function verifyNpmTarballContent({ snapshotDir, tarballBytes, tarballDir,
     } finally {
       await extractHandle.close();
     }
-    const original = await computeFrozenSnapshot(snapshotDir);
-    if (original.digest !== expectedSnapshotDigest) {
-      throw frozenError('frozen snapshot changed while deriving npm tarball', {
-        expectedDigest: expectedSnapshotDigest,
-        observedDigest: original.digest,
-      });
-    }
-    const packed = await computeFrozenSnapshot(join(verifyDir, 'package'));
-    if (JSON.stringify(contentEntries(packed.entries)) !== JSON.stringify(contentEntries(original.entries))) {
-      throw frozenError('npm tarball bytes do not match the sealed public snapshot');
-    }
+    return await computeFrozenSnapshot(join(verifyDir, 'package'));
   } finally {
     await rm(verifyDir, { recursive: true, force: true });
   }
 }
 
+async function verifyNpmTarballContent({ snapshotDir, tarballBytes, tarballDir, expectedSnapshotDigest }) {
+  const packed = await inspectNpmTarballContent({ tarballBytes, tarballDir });
+  const original = await computeFrozenSnapshot(snapshotDir);
+  if (original.digest !== expectedSnapshotDigest) {
+    throw frozenError('frozen snapshot changed while deriving npm tarball', {
+      expectedDigest: expectedSnapshotDigest,
+      observedDigest: original.digest,
+    });
+  }
+  if (JSON.stringify(contentEntries(packed.entries)) !== JSON.stringify(contentEntries(original.entries))) {
+    throw frozenError('npm tarball bytes do not match the sealed public snapshot');
+  }
+}
+
+export async function buildNpmTarballFileIndex({ tarballBytes, tarballDir }) {
+  const packed = await inspectNpmTarballContent({ tarballBytes, tarballDir });
+  return new Map(packed.entries.map((entry) => [entry.path, { type: entry.type }]));
+}
+
 export async function buildFrozenNpmTarball({ snapshotDir, tarballDir, expectedSnapshotDigest, exec = execFile }) {
   await mkdir(tarballDir, { recursive: true });
   const { stdout } = await exec(