release-skill 0.4.2 → 0.5.0

package/src/core/trusted-resource.mjs

@@ -1,12 +1,23 @@
 /**
  * Read package-owned runtime resources without following untrusted links.
  * Installed adapters use this for schemas and native manifests.
+ *
+ * 机制已委托 Foundation（skill-family-foundation-adoption-20260815 节点 1.6）：
+ * - 异步变体 `readTrustedPackageResource`：路径包含三层校验（词法/符号链接/
+ *   realpath 逃逸）委托 `resolveContained`，读取委托 `readFileContained`；
+ *   本地保留域策略前置校验 `assertStat`（拒绝任何符号链接、非常规文件与
+ *   硬链接），失败原因映射保持原语义。
+ * - 同步变体 `readTrustedPackageResourceSync`：Foundation 无同步路径 API，
+ *   词法分类委托同步纯函数 `classifyPathInput`，其余本地同步实现保留
+ *   （残留，见 1.6 run-report 剩余风险）。
  */
 
 import { lstatSync, readFileSync, realpathSync } from 'node:fs';
-import { lstat, readFile, realpath } from 'node:fs/promises';
+import { lstat } from 'node:fs/promises';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 
+import { classifyPathInput, readFileContained, resolveContained } from 'skill-family-harness-node';
+
 import { CONFIG_INVALID, ReleaseError } from './errors.mjs';
 import { PKG_ROOT } from './pkg-root.mjs';
 
@@ -18,6 +29,8 @@ function fail(code, resource, reason) {
   );
 }
 
+// ---- 同步变体保留的本地实现（Foundation 无同步路径 API，文档化残留） ----
+
 function lexicalPath(resource, code) {
   if (typeof resource !== 'string' || resource.length === 0 || isAbsolute(resource)) {
     fail(code, String(resource), 'INVALID_RESOURCE_PATH');
@@ -43,7 +56,44 @@ function assertPhysicalContainment(physicalRoot, physicalPath, resource, code) {
   }
 }
 
+// ---- Foundation 机制错误 → 本地失败语义映射 ----
+
+/** 把 Foundation HarnessError（SFC2004 + details.kind）映射为本地失败原因。 */
+function harnessKindToReason(kind) {
+  switch (kind) {
+    case 'path-traversal':
+      return 'RESOURCE_PATH_ESCAPE';
+    case 'symlink-escape':
+      // 本地语义：lstat 前置校验对任何符号链接一律报 SYMLINK（不区分指向）。
+      // Foundation 对指向包外的符号链接先抛 symlink-escape，映射回 SYMLINK
+      // 保持原失败原因；包内符号链接由本地 assertStat 以 SYMLINK 拦截。
+      return 'SYMLINK';
+    case 'realpath-escape':
+      return 'PHYSICAL_PATH_ESCAPE';
+    case 'missing-resource':
+      return 'MISSING';
+    case 'read-failed':
+      return 'READ_FAILED';
+    default:
+      // invalid-path / absolute-path / windows-drive-path / unc-path /
+      // windows-path / invalid-root 等统一归入无效资源路径。
+      return 'INVALID_RESOURCE_PATH';
+  }
+}
+
+function mapHarnessError(cause, resource, code) {
+  if (cause && cause.code === 'SFC2004' && cause.details && typeof cause.details.kind === 'string') {
+    fail(code, resource, harnessKindToReason(cause.details.kind));
+  }
+  throw cause;
+}
+
 export function readTrustedPackageResourceSync(resource, { code = CONFIG_INVALID } = {}) {
+  // 词法分类委托 Foundation classifyPathInput（同步纯函数；比本地词法检查
+  // 更严格地拒绝反斜杠/NUL/UNC/盘符相对等跨平台歧义输入，fail-closed）。
+  const classification = classifyPathInput(resource, process.platform);
+  if (!classification.ok) fail(code, String(resource), 'INVALID_RESOURCE_PATH');
+
   const path = lexicalPath(resource, code);
   let stat;
   try {
@@ -70,27 +120,26 @@ export function readTrustedPackageResourceSync(resource, { code = CONFIG_INVALID
 }
 
 export async function readTrustedPackageResource(resource, { code = CONFIG_INVALID } = {}) {
-  const path = lexicalPath(resource, code);
+  // 机制委托：resolveContained（词法/符号链接/realpath 三层包含校验）。
+  let target;
+  try {
+    target = await resolveContained(PKG_ROOT, resource);
+  } catch (cause) {
+    mapHarnessError(cause, resource, code);
+  }
+
+  // 本地域策略前置：拒绝任何符号链接（含指向包内目标的）、非常规文件与硬链接。
   let stat;
   try {
-    stat = await lstat(path);
+    stat = await lstat(target);
   } catch {
     fail(code, resource, 'MISSING');
   }
   assertStat(stat, resource, code);
 
-  let physicalRoot;
-  let physicalPath;
   try {
-    physicalRoot = await realpath(PKG_ROOT);
-    physicalPath = await realpath(path);
-  } catch {
-    fail(code, resource, 'REALPATH_FAILED');
-  }
-  assertPhysicalContainment(physicalRoot, physicalPath, resource, code);
-  try {
-    return await readFile(physicalPath);
-  } catch {
-    fail(code, resource, 'READ_FAILED');
+    return await readFileContained(PKG_ROOT, resource);
+  } catch (cause) {
+    mapHarnessError(cause, resource, code);
   }
 }

package/src/producers/build-adapters.mjs

@@ -21,9 +21,10 @@
 import { readdir, mkdir, lstat, realpath, open, rm } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
 import { join, dirname, relative, isAbsolute, sep, resolve, posix as pathPosix } from 'node:path';
-import { createHash } from 'node:crypto';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { digestDocument } from 'skill-family-contracts';
+import { digestBytes } from 'skill-family-harness-node';
 import { PLATFORMS as PLATFORM_REGISTRY } from '../platforms/registry.mjs';
 
 /**
@@ -186,11 +187,14 @@ async function ensureTrustedOutputDirectory(rootPath, rootIdentity, relativeDir,
  * @returns {string}
  */
 export function computeBuildAdaptersDigest(sourceBytes) {
-  const h = createHash('sha256');
-  for (const buf of sourceBytes) h.update(buf);
-  h.update(`node:${process.version}`);
-  h.update('locale:en-US timezone:UTC');
-  return `sha256:${h.digest('hex')}`;
+  // 多段哈希（源字节 + node 版本 + 固定 locale/timezone）等价于对拼接字节
+  // 的 sha256，委托 Foundation digestBytes 实现，字节逐位一致。
+  const bytes = Buffer.concat([
+    ...sourceBytes,
+    Buffer.from(`node:${process.version}`),
+    Buffer.from('locale:en-US timezone:UTC'),
+  ]);
+  return `sha256:${digestBytes(bytes)}`;
 }
 
 // Platform definitions, derived from the platform registry (the single source
@@ -488,8 +492,21 @@ async function generateAdapterFiles(platform, skills, templateJson, root, market
     });
   }
 
-  // Copy bin/ entry point and bundle (text files)
-  const binFiles = ['release-skill.mjs', 'release-skill.bundle.mjs'];
+  // Copy bin/ entry point and bundle (text files). The self-contained
+  // bundle ships runtime sidecars next to it (JSON resources read via
+  // new URL(<rel>, import.meta.url) by inlined Foundation modules, e.g.
+  // error-codes.json); enumerate the directory so every sidecar is
+  // replicated deterministically. The source CLI (release-skill-cli.mjs)
+  // is never shipped into adapters. The wrapper and the bundle are
+  // required entries: a missing one fails closed before any write.
+  const binFiles = (await readdir(join(root, 'bin')))
+    .filter((name) => name !== 'release-skill-cli.mjs')
+    .sort();
+  for (const required of ['release-skill.mjs', 'release-skill.bundle.mjs']) {
+    if (!binFiles.includes(required)) {
+      throw new Error(`SECURITY: required bundle entry is missing: bin/${required}`);
+    }
+  }
   for (const name of binFiles) {
     const srcPath = join(root, 'bin', name);
     const content = await readTrustedFile(srcPath, root, `bin/${name}`);
@@ -752,8 +769,9 @@ export async function produceBuildAdapters({ inputs, output, outputRoots, platfo
  * @returns {string}
  */
 export function digestEntryOutputs(entries) {
+  // 纯 JSON 投影（platform 条件展开 + 定字段），直接委托 Foundation digestDocument。
   const canonical = entries.map(({ platform, path, type, mode, sha256, size }) => ({
     ...(platform ? { platform } : {}), path, type, mode, size, sha256,
   }));
-  return `sha256:${sha256Hex(canonicalJson(canonical))}`;
+  return `sha256:${digestDocument(canonical)}`;
 }

package/src/producers/render-public-assets.mjs

@@ -13,9 +13,10 @@
 
 import { readFile, writeFile, readdir, stat, mkdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-import { createHash } from 'node:crypto';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { digestDocument } from 'skill-family-contracts';
+import { digestBytes } from 'skill-family-harness-node';
 
 /**
  * Compute an implementation digest from the source bytes of this module.
@@ -24,11 +25,14 @@ import { canonicalJson, sha256Hex } from '../core/digest.mjs';
  * @returns {string}
  */
 export function computeRenderDigest(sourceBytes) {
-  const h = createHash('sha256');
-  for (const buf of sourceBytes) h.update(buf);
-  h.update(`node:${process.version}`);
-  h.update('locale:en-US timezone:UTC');
-  return `sha256:${h.digest('hex')}`;
+  // 多段哈希（源字节 + node 版本 + 固定 locale/timezone）等价于对拼接字节
+  // 的 sha256，委托 Foundation digestBytes 实现，字节逐位一致。
+  const bytes = Buffer.concat([
+    ...sourceBytes,
+    Buffer.from(`node:${process.version}`),
+    Buffer.from('locale:en-US timezone:UTC'),
+  ]);
+  return `sha256:${digestBytes(bytes)}`;
 }
 
 /**
@@ -145,8 +149,9 @@ export async function produceRenderPublicAssets({ inputs, output } = {}) {
  * @returns {string}
  */
 export function digestEntryOutputs(entries) {
+  // 纯 JSON 投影（定字段），直接委托 Foundation digestDocument。
   const canonical = entries.map(({ path, type, mode, sha256, size }) => ({
     path, type, mode, size, sha256,
   }));
-  return `sha256:${sha256Hex(canonicalJson(canonical))}`;
+  return `sha256:${digestDocument(canonical)}`;
 }

package/src/producers/sync-skills.mjs

@@ -11,9 +11,10 @@
 
 import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { createHash } from 'node:crypto';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { digestDocument } from 'skill-family-contracts';
+import { digestBytes } from 'skill-family-harness-node';
 
 /**
  * Compute an implementation digest from the source bytes of this module.
@@ -22,11 +23,14 @@ import { canonicalJson, sha256Hex } from '../core/digest.mjs';
  * @returns {string}
  */
 export function computeSyncSkillsDigest(sourceBytes) {
-  const h = createHash('sha256');
-  for (const buf of sourceBytes) h.update(buf);
-  h.update(`node:${process.version}`);
-  h.update('locale:en-US timezone:UTC');
-  return `sha256:${h.digest('hex')}`;
+  // 多段哈希（源字节 + node 版本 + 固定 locale/timezone）等价于对拼接字节
+  // 的 sha256，委托 Foundation digestBytes 实现，字节逐位一致。
+  const bytes = Buffer.concat([
+    ...sourceBytes,
+    Buffer.from(`node:${process.version}`),
+    Buffer.from('locale:en-US timezone:UTC'),
+  ]);
+  return `sha256:${digestBytes(bytes)}`;
 }
 
 /**
@@ -89,8 +93,9 @@ export async function produceSyncSkills({ inputs, output } = {}) {
  * @returns {string}
  */
 export function digestEntryOutputs(entries) {
+  // 纯 JSON 投影（定字段），直接委托 Foundation digestDocument。
   const canonical = entries.map(({ path, type, mode, sha256, size }) => ({
     path, type, mode, size, sha256,
   }));
-  return `sha256:${sha256Hex(canonicalJson(canonical))}`;
+  return `sha256:${digestDocument(canonical)}`;
 }

package/src/snapshot/public-map.mjs

@@ -24,9 +24,10 @@
 import { lstat, readFile, mkdir, readdir, realpath, chmod as fsChmod } from 'node:fs/promises';
 import { open as fsOpen } from 'node:fs/promises';
 import { relative, resolve, dirname, sep as pathSep, isAbsolute } from 'node:path';
-import { posix } from 'node:path';
+import { posix, win32 } from 'node:path';
 import { constants as fsConstants } from 'node:fs';
 import { createHash } from 'node:crypto';
+import { classifyPathInput } from 'skill-family-harness-node';
 import {
   ReleaseError,
   PUBLIC_FILE_MISSING,
@@ -81,7 +82,14 @@ const MAX_PATH_LENGTH = 4096;
  */
 export function _isContainedWith(relativeFn, isAbsoluteFn, root, candidate, relPathSep = pathSep) {
   const rel = relativeFn(root, candidate);
-  return rel !== '' && rel !== '..' && !rel.startsWith(`..${relPathSep}`) && !isAbsoluteFn(rel);
+  if (rel === '' || rel === '..' || rel.startsWith(`..${relPathSep}`) || isAbsoluteFn(rel)) {
+    return false;
+  }
+  // 词法分类委托 Foundation classifyPathInput（同步纯函数）：对相对路径做
+  // 跨平台歧义输入 fail-closed（反斜杠分隔符/NUL/UNC/盘符相对/绝对路径）。
+  // 平台从注入的 relativeFn 推导，保持纯同步、无文件系统访问的既有契约。
+  const platform = relativeFn === win32.relative ? 'win32' : 'posix';
+  return classifyPathInput(rel, platform).ok === true;
 }
 
 /**