release-skill 0.7.6 → 0.7.7

package/src/core/config.mjs

@@ -504,6 +504,37 @@ export async function loadProjectConfig({ root, configPath } = {}) {
   // inferred at execution time. A gate must name one existing unit and, for
   // consumer verification, one distribution that the unit actually ships.
   const unitsById = new Map(config.releaseUnits.map((unit) => [unit.id, unit]));
+  const publicReceipt = config.publicSourceAuthorityReceipt;
+  if (publicReceipt) {
+    if (!config.project?.sourceRepository) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        'publicSourceAuthorityReceipt requires project.sourceRepository',
+      );
+    }
+    if (!unitsById.has(publicReceipt.coordinatorUnitId)) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        `publicSourceAuthorityReceipt references unknown coordinator unit "${publicReceipt.coordinatorUnitId}"`,
+      );
+    }
+    for (const unitId of publicReceipt.subjectUnitIds) {
+      const unit = unitsById.get(unitId);
+      if (!unit) {
+        throw new ReleaseError(
+          CONFIG_INVALID,
+          `publicSourceAuthorityReceipt references unknown subject unit "${unitId}"`,
+        );
+      }
+      const npmDistributions = (unit.distributions ?? []).filter((distribution) => distribution.type === 'npm');
+      if (npmDistributions.length !== 1) {
+        throw new ReleaseError(
+          CONFIG_INVALID,
+          `publicSourceAuthorityReceipt subject unit "${unitId}" must declare exactly one npm distribution`,
+        );
+      }
+    }
+  }
   const gateIds = new Set();
   for (const gate of config.verificationGates ?? []) {
     if (gateIds.has(gate.id)) {

package/src/core/plan.mjs

@@ -26,6 +26,8 @@ import { canonicalJson, sha256Hex } from './digest.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
 import { computeInstallationContractDigest, INSTALLATION_CONTRACT_ALGORITHM_VERSION } from './installation-contract.mjs';
+import { createPublicSourceAuthorityReceipt } from './source-authority.mjs';
+import { digestReleaseAssetIdentities, normalizeReleaseAssets } from './release-assets.mjs';
 // NOTE (T2.2 step 3): plan.mjs and the platform registry form a module cycle
 // (plan -> registry -> platforms/kimi -> plan, because the kimi strategies
 // bind computePlanDigest). PLATFORMS is therefore only ever read inside
@@ -450,6 +452,57 @@ export function validatePlanActionCompleteness(plan, options = {}) {
   const units = Array.isArray(plan.units) ? plan.units : [];
   const actions = Array.isArray(plan.externalActions) ? plan.externalActions : [];
   const expectedAdapterMap = buildExpectedAdapterMap();
+  let publicReceiptBinding = null;
+  if (plan.publicSourceAuthorityReceipt) {
+    try {
+      if (plan.production?.mode !== 'github-npm-v1') {
+        failures.push('publicSourceAuthorityReceipt requires a production plan');
+      }
+      if (!plan.sourceAuthority?.sourceRepository || !plan.baseline?.headCommit) {
+        failures.push('publicSourceAuthorityReceipt requires sourceAuthority.sourceRepository and baseline.headCommit');
+      }
+      const descriptor = plan.publicSourceAuthorityReceipt;
+      const coordinator = units.find((unit) => unit.id === descriptor.coordinatorUnitId);
+      if (!coordinator) failures.push(`publicSourceAuthorityReceipt references unknown coordinator unit "${descriptor.coordinatorUnitId}"`);
+      const subjectIds = descriptor.subjectUnitIds ?? [];
+      if (new Set(subjectIds).size !== subjectIds.length) {
+        failures.push('publicSourceAuthorityReceipt subjectUnitIds must be unique');
+      }
+      const subjects = subjectIds.map((unitId) => {
+        const unit = units.find((candidate) => candidate.id === unitId);
+        if (!unit) throw new Error(`unknown subject unit "${unitId}"`);
+        const npmDistributions = (unit.distributions ?? []).filter((distribution) => distribution.type === 'npm');
+        if (npmDistributions.length !== 1 || !unit.frozenSnapshot?.npm) {
+          throw new Error(`subject unit "${unitId}" must bind exactly one frozen npm tarball`);
+        }
+        return {
+          packageName: npmDistributions[0].package,
+          version: unit.targetVersion,
+          filename: basename(unit.frozenSnapshot.npm.tarballPath),
+          sha256: unit.frozenSnapshot.npm.tarballSha256,
+        };
+      });
+      const rebuilt = createPublicSourceAuthorityReceipt({
+        sourceRepository: plan.sourceAuthority?.sourceRepository,
+        sourceBaseCommit: plan.baseline?.headCommit,
+        subjects,
+      });
+      const assets = normalizeReleaseAssets([descriptor.asset]);
+      if (descriptor.asset.name !== 'source-authority-receipt.json') {
+        failures.push('publicSourceAuthorityReceipt asset name must be source-authority-receipt.json');
+      }
+      if (descriptor.asset.sha256 !== rebuilt.sha256) {
+        failures.push('publicSourceAuthorityReceipt asset SHA-256 does not match the mechanically derived receipt bytes');
+      }
+      publicReceiptBinding = {
+        coordinatorUnitId: descriptor.coordinatorUnitId,
+        assets,
+        assetsDigest: digestReleaseAssetIdentities(assets),
+      };
+    } catch (error) {
+      failures.push(`publicSourceAuthorityReceipt is invalid: ${error.message}`);
+    }
+  }
 
   // --- Must have at least one action ---
   if (actions.length === 0) {
@@ -666,6 +719,31 @@ export function validatePlanActionCompleteness(plan, options = {}) {
             _checkRequired(action, 'parameters.notes', action.parameters?.notes, productionConfig.releaseNotes ?? `Release ${expectedTag}`, unitId, failures);
             _checkRequired(action, 'expected.tag', action.expected?.tag, expectedTag, unitId, failures);
             _checkRequired(action, 'expected.commit', action.expected?.commit, frozen?.commit, unitId, failures);
+            if (publicReceiptBinding?.coordinatorUnitId === unitId) {
+              try {
+                const actualAssets = normalizeReleaseAssets(action.parameters?.releaseAssets);
+                if (canonicalJson(actualAssets) !== canonicalJson(publicReceiptBinding.assets)) {
+                  failures.push(`unit "${unitId}", action "${action.id}": parameters.releaseAssets do not match publicSourceAuthorityReceipt.asset`);
+                }
+              } catch (error) {
+                failures.push(`unit "${unitId}", action "${action.id}": invalid parameters.releaseAssets: ${error.message}`);
+              }
+              _checkRequired(
+                action,
+                'expected.releaseAssetsDigest',
+                action.expected?.releaseAssetsDigest,
+                publicReceiptBinding.assetsDigest,
+                unitId,
+                failures,
+              );
+            } else {
+              if (action.parameters?.releaseAssets !== undefined) {
+                failures.push(`unit "${unitId}", action "${action.id}": unexpected parameters.releaseAssets`);
+              }
+              if (action.expected?.releaseAssetsDigest !== undefined) {
+                failures.push(`unit "${unitId}", action "${action.id}": unexpected expected.releaseAssetsDigest`);
+              }
+            }
           }
         }
       }

package/src/core/release-assets.mjs

@@ -0,0 +1,54 @@
+/**
+ * Frozen GitHub Release asset identities.
+ *
+ * This module owns only release-domain mapping: a plan freezes local asset
+ * paths and their already-computed SHA-256 values, while remote observation
+ * reduces the downloaded bytes to the same name/digest identity list.
+ */
+
+import { basename } from 'node:path';
+
+import { canonicalJson, sha256Hex } from './digest.mjs';
+
+const SHA256_RE = /^[a-f0-9]{64}$/u;
+const SAFE_ASSET_NAME_RE = /^(?!\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+
+/** Validate and normalize a plan's optional frozen Release assets. */
+export function normalizeReleaseAssets(assets) {
+  if (assets === undefined) return [];
+  if (!Array.isArray(assets) || assets.length === 0) {
+    throw new TypeError('releaseAssets must be a non-empty array when present');
+  }
+  const names = new Set();
+  const normalized = assets.map((asset, index) => {
+    if (!asset || typeof asset !== 'object' || Array.isArray(asset)) {
+      throw new TypeError(`releaseAssets[${index}] must be an object`);
+    }
+    const keys = Object.keys(asset).sort();
+    if (canonicalJson(keys) !== canonicalJson(['name', 'path', 'sha256'])) {
+      throw new TypeError(`releaseAssets[${index}] must contain only name, path, and sha256`);
+    }
+    if (typeof asset.path !== 'string' || asset.path.length === 0) {
+      throw new TypeError(`releaseAssets[${index}].path must be a non-empty project-relative path`);
+    }
+    if (!SAFE_ASSET_NAME_RE.test(asset.name ?? '') || basename(asset.path) !== asset.name) {
+      throw new TypeError(`releaseAssets[${index}].name must be a safe basename matching path`);
+    }
+    if (!SHA256_RE.test(asset.sha256 ?? '')) {
+      throw new TypeError(`releaseAssets[${index}].sha256 must be a lowercase SHA-256 digest`);
+    }
+    if (names.has(asset.name)) {
+      throw new TypeError(`releaseAssets contains duplicate asset name "${asset.name}"`);
+    }
+    names.add(asset.name);
+    return Object.freeze({ name: asset.name, path: asset.path, sha256: asset.sha256 });
+  });
+  normalized.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  return Object.freeze(normalized);
+}
+
+/** Digest only public remote identity, never local paths. */
+export function digestReleaseAssetIdentities(assets) {
+  const identities = normalizeReleaseAssets(assets).map(({ name, sha256 }) => ({ name, sha256 }));
+  return sha256Hex(canonicalJson(identities));
+}

package/src/core/source-authority.mjs

@@ -27,9 +27,115 @@ import {
 const execFile = promisify(execFileCb);
 const REPOSITORY_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/u;
 const GIT_MODE_RE = /^(?:100644|100755)$/u;
+const COMMIT_RE = /^[a-f0-9]{40,64}$/u;
+const SHA256_RE = /^[a-f0-9]{64}$/u;
+const NPM_PACKAGE_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/u;
+const TARBALL_FILENAME_RE = /^(?!\.{1,2}$)[A-Za-z0-9@][A-Za-z0-9._@+-]*\.tgz$/u;
 
 export const SOURCE_INPUT_ALGORITHM_VERSION = 1;
 
+/**
+ * Build the intentionally small public source-authority receipt.
+ *
+ * The receipt is an external release asset. It contains no plan/run fields
+ * and no self digest; the frozen action binds the canonical bytes instead.
+ */
+export function createPublicSourceAuthorityReceipt({
+  sourceRepository,
+  sourceBaseCommit,
+  subjects,
+}) {
+  if (!REPOSITORY_RE.test(sourceRepository ?? '')) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt requires an explicit GitHub owner/repo');
+  }
+  if (!COMMIT_RE.test(sourceBaseCommit ?? '')) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt requires a full hexadecimal source base commit');
+  }
+  if (!Array.isArray(subjects) || subjects.length === 0) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt requires at least one npm tarball subject');
+  }
+  const packageNames = new Set();
+  const normalizedSubjects = subjects.map((subject, index) => {
+    const keys = Object.keys(subject ?? {}).sort();
+    if (canonicalJson(keys) !== canonicalJson(['filename', 'packageName', 'sha256', 'version'])) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject ${index} has an invalid field set`);
+    }
+    if (!NPM_PACKAGE_RE.test(subject.packageName ?? '')) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject ${index} has an invalid packageName`);
+    }
+    if (packageNames.has(subject.packageName)) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority receipt has duplicate packageName "${subject.packageName}"`);
+    }
+    packageNames.add(subject.packageName);
+    if (typeof subject.version !== 'string' || subject.version.length === 0) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject "${subject.packageName}" has an invalid version`);
+    }
+    if (!TARBALL_FILENAME_RE.test(subject.filename ?? '')) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject "${subject.packageName}" has an invalid tarball filename`);
+    }
+    if (!SHA256_RE.test(subject.sha256 ?? '')) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject "${subject.packageName}" has an invalid SHA-256`);
+    }
+    return {
+      packageName: subject.packageName,
+      version: subject.version,
+      filename: subject.filename,
+      sha256: subject.sha256,
+    };
+  });
+  normalizedSubjects.sort((left, right) => (
+    left.packageName < right.packageName ? -1 : left.packageName > right.packageName ? 1 : 0
+  ));
+  const receipt = {
+    schemaVersion: 1,
+    kind: 'skill-family.source-authority-receipt',
+    sourceRepository,
+    sourceBaseCommit,
+    subjects: normalizedSubjects,
+  };
+  const bytes = Buffer.from(canonicalJson(receipt), 'utf8');
+  return Object.freeze({ receipt: Object.freeze(receipt), bytes, sha256: sha256Hex(bytes) });
+}
+
+/** Parse public bytes and verify them against actual offline tarball facts. */
+export function consumePublicSourceAuthorityReceipt(bytes, actualSubjects) {
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.isBuffer(bytes) ? bytes.toString('utf8') : String(bytes));
+  } catch (error) {
+    throw new ReleaseError(CONFIG_INVALID, `public source-authority receipt is not valid JSON: ${error.message}`);
+  }
+  const topKeys = Object.keys(parsed ?? {}).sort();
+  if (canonicalJson(topKeys) !== canonicalJson([
+    'kind', 'schemaVersion', 'sourceBaseCommit', 'sourceRepository', 'subjects',
+  ])) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt has an invalid field set');
+  }
+  if (parsed.schemaVersion !== 1 || parsed.kind !== 'skill-family.source-authority-receipt') {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt kind or schemaVersion is unsupported');
+  }
+  const rebuilt = createPublicSourceAuthorityReceipt(parsed);
+  if (!Buffer.from(bytes).equals(rebuilt.bytes)) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt bytes are not canonical JSON');
+  }
+  if (actualSubjects !== undefined) {
+    const actual = createPublicSourceAuthorityReceipt({
+      sourceRepository: parsed.sourceRepository,
+      sourceBaseCommit: parsed.sourceBaseCommit,
+      subjects: actualSubjects,
+    }).receipt.subjects;
+    if (canonicalJson(actual) !== canonicalJson(rebuilt.receipt.subjects)) {
+      throw new ReleaseError(CONTENT_MISMATCH, 'public source-authority receipt subjects do not match actual tarballs');
+    }
+  }
+  return Object.freeze({
+    sourceRepository: rebuilt.receipt.sourceRepository,
+    sourceBaseCommit: rebuilt.receipt.sourceBaseCommit,
+    subjects: rebuilt.receipt.subjects,
+    sha256: rebuilt.sha256,
+  });
+}
+
 /**
  * Compute the deterministic source-input closure for release units.
  *
@@ -325,6 +431,7 @@ async function verifyWithInjectedReader({
   sourceRepository,
 }) {
   const mismatchedPaths = [];
+  let observedCommit;
   for (const entry of closure.entries) {
     let result;
     try {
@@ -334,6 +441,12 @@ async function verifyWithInjectedReader({
     }
     const classified = classifyRemoteStatus(result, sourceRepository, defaultBranch);
     if (classified) return classified;
+    if (result.observedCommit !== undefined) {
+      if (observedCommit !== undefined && observedCommit !== result.observedCommit) {
+        return failure(REMOTE_UNAVAILABLE, 'remote source reader returned inconsistent observed commits');
+      }
+      observedCommit = result.observedCommit;
+    }
     if (
       sha256Hex(Buffer.isBuffer(result.content) ? result.content : Buffer.from(result.content))
         !== entry.digest
@@ -349,6 +462,7 @@ async function verifyWithInjectedReader({
         observation: {
           defaultBranch,
           entryCount: closure.entries.length,
+          ...(observedCommit ? { observedCommit } : {}),
           sourceRepository,
         },
       };
@@ -515,12 +629,22 @@ export function verifySourceAuthorityReceipt({ plan, run }) {
     && receipt.planDigest === plan.digest
     && receipt.result === 'CONSISTENT'
   ));
-  return matching
-    ? { passed: true, receipt: matching }
-    : {
+  if (!matching) {
+    return {
         passed: false,
         reason: 'publish run has no CONSISTENT source-authority receipt bound to this plan digest',
       };
+  }
+  if (
+    plan.publicSourceAuthorityReceipt
+    && matching.observedCommit !== plan.baseline?.headCommit
+  ) {
+    return {
+      passed: false,
+      reason: 'publish source-authority receipt observedCommit does not match the public receipt sourceBaseCommit',
+    };
+  }
+  return { passed: true, receipt: matching };
 }
 
 /** Create the digest-bound receipt persisted by publish. */