release-skill 0.6.3 → 0.7.0

package/src/core/postpublish-approval.mjs

@@ -13,15 +13,39 @@
  * plan digest, so approvals invalidate naturally with the plan; `runId` is
  * audit-only and never participates in binding.
  *
+ * F-02 (architecture gap remediation T2): consumption is bound to the
+ * immutable authority minted by commands/approve.mjs
+ * `approvePostPublishHook`:
+ *
+ *     <plan owning .release-skill>/approvals/postpublish/<planDigest>/<approvalDigest>.json
+ *
+ * `assertPostPublishApprovalAuthority` recomputes planDigest from the
+ * current plan and approvalDigest from the consumed raw bytes, requires the
+ * consumption path to EQUAL that authority path byte-for-byte (identical
+ * content anywhere else is not an approval), and strictly re-reads the file
+ * through Foundation `readFileStrict` (existence, containment against every
+ * root-escape class, no-follow regular-file identity, digest receipt bound
+ * to the recomputed approvalDigest). Symbolic-link semantics are fully
+ * delegated to Foundation: anything escaping the root is rejected, a leaf
+ * symbolic link is never an authority, and a root-internal ancestor alias
+ * is not an independent security failure (2026-08-21 handoff ruling C). The
+ * check is strictly read-only: it never creates a directory. After the
+ * authority passes, the existing schema/hook/grading/time-window validation
+ * continues unchanged.
+ *
  * @module core/postpublish-approval
  */
 
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 
+import { readFileStrict } from 'skill-family-harness-node';
+
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { computePlanDigest } from './plan.mjs';
-import { validateApprovalTimeWindow } from './approval.mjs';
+import { computeApprovalDigest, validateApprovalTimeWindow } from './approval.mjs';
 import { resolvePresetRequiresApproval } from './presets.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
 
@@ -108,3 +132,110 @@ export function validatePostPublishApproval(plan, approval, options = {}) {
 
   return hook;
 }
+
+/**
+ * Derive the immutable checkpoint-approval authority location for a plan.
+ *
+ * This is the SINGLE source of truth for the authority layout, shared by the
+ * minter (commands/approve.mjs `approvePostPublishHook`) and the consumers
+ * (`assertPostPublishApprovalAuthority` below): the record lives at
+ *
+ *     <releaseDir>/approvals/postpublish/<planDigest>/<approvalDigest>.json
+ *
+ * where `releaseDir` is the directory owning the frozen plan — the
+ * `.release-skill` authority root when the plan uses the canonical
+ * `plans/<planDigest>.json` naming, otherwise the plan's own directory
+ * (non-production aliases), mirroring the minter exactly.
+ *
+ * @param {string} planPath - Absolute path of the frozen plan.
+ * @param {string} planDigest - Plan digest recomputed from the current plan.
+ * @param {string} approvalDigest - Digest recomputed from the approval bytes.
+ * @returns {{releaseDir: string, authorityPath: string}}
+ */
+export function derivePostPublishApprovalAuthorityPath(planPath, planDigest, approvalDigest) {
+  const absolutePlanPath = resolve(planPath);
+  const planDir = dirname(absolutePlanPath);
+  const releaseDir = basename(planDir) === 'plans' && basename(absolutePlanPath) === `${planDigest}.json`
+    ? dirname(planDir)
+    : planDir;
+  return {
+    releaseDir,
+    authorityPath: resolve(releaseDir, 'approvals', 'postpublish', planDigest, `${approvalDigest}.json`),
+  };
+}
+
+/**
+ * Assert that a checkpoint approval is consumed from its immutable authority.
+ *
+ * Fail-closed checks, in order (all GATE_FAILED):
+ * 1. `planDigest` is recomputed from the CURRENT plan;
+ * 2. `approvalDigest` is recomputed from the consumed raw approval bytes;
+ * 3. the consumption path must EQUAL the expected absolute authority path —
+ *    the same bytes copied anywhere else are never an approval;
+ * 4. Foundation `readFileStrict` re-reads the record through the authority
+ *    root: containment rejects every escape class (lexical traversal, a
+ *    final-component symlink pointing out, and any ancestor chain whose
+ *    canonical target leaves the root), the record must be one ordinary
+ *    file, never a symbolic link (no-follow, O_NOFOLLOW open, dev/ino
+ *    identity re-stat), and its bytes must digest to the recomputed
+ *    approvalDigest (binding the consumed bytes to the authoritative bytes).
+ *    A root-internal ancestor alias is a path alias, not an escape, and is
+ *    not an independent security failure (2026-08-21 handoff ruling C).
+ *
+ * The check is strictly read-only: it never creates a directory or file.
+ * Callers continue with `validatePostPublishApproval` (schema, hook,
+ * grading, time window) only after this assertion passes.
+ *
+ * @param {string} planPath - Absolute path of the frozen plan.
+ * @param {string} approvalPath - Path the consumer read the approval from.
+ * @param {object} plan - Parsed frozen plan (schema-valid).
+ * @param {string|Buffer} approvalRaw - Raw approval bytes the consumer read.
+ * @returns {Promise<{planDigest: string, approvalDigest: string, authorityPath: string}>}
+ * @throws {ReleaseError} GATE_FAILED on any violation.
+ */
+export async function assertPostPublishApprovalAuthority(planPath, approvalPath, plan, approvalRaw) {
+  if (!plan || typeof plan !== 'object') {
+    throw new ReleaseError(GATE_FAILED, 'postpublish approval authority check requires the parsed plan');
+  }
+  if (typeof approvalPath !== 'string' || approvalPath.length === 0) {
+    throw new ReleaseError(GATE_FAILED, 'postpublish approval authority check requires a consumption path');
+  }
+
+  const planDigest = computePlanDigest(plan);
+  const approvalDigest = computeApprovalDigest(approvalRaw);
+  const { releaseDir, authorityPath } = derivePostPublishApprovalAuthorityPath(
+    planPath,
+    planDigest,
+    approvalDigest,
+  );
+
+  // Exact consumption-path equality: copying the bytes elsewhere never mints
+  // an approval. The comparison is lexical on resolve()d paths (no realpath
+  // normalization), so aliased spellings fail closed too.
+  const consumedPath = resolve(approvalPath);
+  if (consumedPath !== authorityPath) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `postpublish checkpoint approval must be consumed from its immutable authority path; expected ${authorityPath}, got ${consumedPath}`,
+      { planDigest, approvalDigest, expectedAuthorityPath: authorityPath, consumedPath },
+    );
+  }
+
+  // Strict authority read through Foundation (FG-1 semantics, never local):
+  // containment (every root-escape class), no-follow leaf, regular-file
+  // identity, digest receipt. The expected digest binds the authoritative
+  // bytes to the consumed bytes.
+  const relPath = relative(releaseDir, authorityPath).split(sep).join('/');
+  try {
+    await readFileStrict(releaseDir, relPath, { expectedSha256: approvalDigest });
+  } catch (cause) {
+    if (cause instanceof ReleaseError) throw cause;
+    throw new ReleaseError(
+      GATE_FAILED,
+      `postpublish checkpoint approval authority read failed: ${cause?.message ?? cause}`,
+      { authorityPath, kind: cause?.details?.kind },
+    );
+  }
+
+  return Object.freeze({ planDigest, approvalDigest, authorityPath });
+}

package/src/core/postpublish-bundle.mjs

@@ -0,0 +1,342 @@
+/**
+ * Post-publish private execution bundle (F-01 / T1).
+ *
+ * Release-domain orchestration ONLY. Path classification, containment,
+ * digesting, strict reads, exclusive publication, and temporary workspaces
+ * all come from `skill-family-harness-node` (0.6.0) by package import; this
+ * module never reimplements a hash, a containment check, an atomic writer,
+ * or a temporary-workspace algorithm. It supplies exactly the release
+ * semantics the Foundation mechanisms do not own:
+ *
+ * - WHERE the frozen bytes live: digest-addressed under the SAME
+ *   `.release-skill` that owns the plan authority — mechanically derived,
+ *   never a caller-supplied arbitrary root:
+ *
+ *       <plan authority .release-skill>/postpublish-bundles/<closure.digest>/<resource.path>
+ *
+ * - WHAT gets frozen: the closed-world `postPublish.executionFiles` manifest
+ *   (parent-workspace files that post-publish commands need but the frozen
+ *   tag tree does not contain; helpers must be declared explicitly). The
+ *   closure is the verbatim return of `computeResourceClosure()` — sorted,
+ *   deduplicated, containment-read, digested by Foundation. The frozen plan
+ *   (`postPublish.executionBundle`) is the ONLY source of truth for the
+ *   bundle; there is no parallel manifest and no second bundle digest —
+ *   `publicFiles` ride the plan digest with everything else.
+ *
+ * - HOW the bytes return at execution time: distribute/postVerify strictly
+ *   re-read every bundle file (frozen sha256 content guard + publication
+ *   mode guard), recompute the closure through Foundation in a disposable
+ *   workspace, compare it with the plan's frozen closure, and only then
+ *   install the verified bytes into the detached tag worktree — exclusively,
+ *   so a bundle entry can never shadow a frozen tag file. Any mismatch
+ *   fails closed BEFORE any hook or external write.
+ *
+ * Private files execute through the tag's interpreter and never depend on
+ * live executable modes; the bundle publishes and re-verifies one fixed
+ * regular-file mode.
+ *
+ * @module core/postpublish-bundle
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+
+import {
+  HARNESS_ERROR_KINDS,
+  classifyPathInput,
+  computeResourceClosure,
+  publishFileExclusive,
+  readFileStrict,
+  withTemporaryWorkspace,
+} from 'skill-family-harness-node';
+
+import { ReleaseError, GATE_FAILED } from './errors.mjs';
+
+/** Foundation mechanism identity frozen into every executionBundle. */
+export const EXECUTION_BUNDLE_MECHANISM = 'foundation.harness.resource-closure';
+
+/** Bundle store directory name under the plan authority `.release-skill`. */
+export const POSTPUBLISH_BUNDLES_DIRNAME = 'postpublish-bundles';
+
+/** Authority directory that owns plans, approvals, runs — and bundles. */
+export const RELEASE_SKILL_DIRNAME = '.release-skill';
+
+/**
+ * The single regular-file mode every bundle byte is published with and must
+ * still carry at execution time. A mode deviation is tamper evidence: the
+ * frozen closure binds content, and publication mode is this fixed policy
+ * constant — no per-file mode manifest exists.
+ */
+export const EXECUTION_BUNDLE_FILE_MODE = 0o644;
+
+function fail(message, details = {}) {
+  throw new ReleaseError(GATE_FAILED, `execution bundle: ${message}`, details);
+}
+
+/**
+ * Mechanically derive the bundle store root from the `.release-skill`
+ * authority directory that owns the plan. The caller never supplies an
+ * arbitrary root: the store is a fixed child of the plan's own authority
+ * directory.
+ *
+ * @param {string} releaseSkillDir - Absolute path of a `.release-skill` dir.
+ * @returns {string} Absolute bundle store root (may not exist yet).
+ */
+export function bundleRootForAuthorityDir(releaseSkillDir) {
+  const absolute = resolve(releaseSkillDir);
+  if (basename(absolute) !== RELEASE_SKILL_DIRNAME) {
+    fail('bundle root must be derived from a .release-skill authority directory', { releaseSkillDir: absolute });
+  }
+  return join(absolute, POSTPUBLISH_BUNDLES_DIRNAME);
+}
+
+/**
+ * Mechanically derive the bundle store root from a plan authority path:
+ * anchor on the nearest `.release-skill` ancestor of the plan file.
+ *
+ * @param {string} planPath - Absolute path of the frozen plan.
+ * @returns {string} Absolute bundle store root.
+ */
+export function deriveBundleRoot(planPath) {
+  const absolute = resolve(planPath);
+  const segments = absolute.split(sep).filter(Boolean);
+  const anchorIndex = segments.lastIndexOf(RELEASE_SKILL_DIRNAME);
+  if (anchorIndex < 0) {
+    fail('plan path has no .release-skill ancestor; cannot derive the bundle store root', { planPath: absolute });
+  }
+  const prefix = absolute.startsWith(sep) ? sep : '';
+  const releaseSkillDir = prefix + join(...segments.slice(0, anchorIndex + 1));
+  return bundleRootForAuthorityDir(releaseSkillDir);
+}
+
+/**
+ * Freeze the private execution bundle for one postPublish declaration.
+ *
+ * Order of operations (all before the plan is written):
+ * 1. Foundation path classification for every declared entry (no parallel
+ *    path regex; ambiguous inputs never reach the filesystem);
+ * 2. `computeResourceClosure()` — Foundation sorts, deduplicates,
+ *    containment-reads (every root-escape class rejected, root-internal
+ *    ancestor aliases are path aliases, not escapes), and digests; the
+ *    return value is frozen VERBATIM;
+ * 3. strict re-read of every entry bound to its frozen sha256 (any
+ *    concurrent drift fails closed; a symbolic-link entry is never readable
+ *    — Foundation no-follow), then exclusive publication of the exact bytes
+ *    under `<bundleRoot>/<closure.digest>/<resource.path>`. Re-preparing
+ *    identical bytes is idempotent; divergent bytes on an occupied
+ *    digest-addressed slot fail closed.
+ *
+ * Symbolic-link policy is fully delegated to Foundation (2026-08-21 handoff
+ * ruling C): anything escaping the workspace root is rejected by closure
+ * containment, a leaf symbolic link is rejected by `readFileStrict`
+ * (no-follow), and ordinary-file identity and digests stay bound.
+ *
+ * @param {object} params
+ * @param {string} params.workspaceRoot - Release workspace root.
+ * @param {string} params.releaseSkillDir - `.release-skill` authority dir
+ *   that will own the frozen plan (mechanical bundle-root anchor).
+ * @param {string[]} [params.executionFiles] - Closed-world manifest.
+ * @param {object[]} [params.publicFiles] - Release-unit public projection
+ *   frozen into the plan alongside the closure.
+ * @returns {Promise<{foundationMechanism: string, closure: object, publicFiles: object[]}>}
+ */
+export async function freezeExecutionBundle({ workspaceRoot, releaseSkillDir, executionFiles = [], publicFiles = [] } = {}) {
+  if (!workspaceRoot || typeof workspaceRoot !== 'string') {
+    throw new TypeError('freezeExecutionBundle: workspaceRoot must be a directory path string');
+  }
+  if (!Array.isArray(executionFiles)) {
+    throw new TypeError('freezeExecutionBundle: executionFiles must be an array');
+  }
+  for (const relPath of executionFiles) {
+    const classification = classifyPathInput(relPath);
+    if (!classification.ok) {
+      fail(`executionFiles entry is not a safe workspace-relative path (kind: ${classification.kind})`, {
+        path: typeof relPath === 'string' ? relPath : typeof relPath,
+        kind: classification.kind,
+      });
+    }
+  }
+
+  // Foundation closure: sort, dedupe, containment reads, sha256 — verbatim.
+  // Thin adapter mapping only: Foundation mechanism errors (lexical
+  // traversal, symlink/realpath escapes, missing inputs) surface as
+  // release-domain GATE_FAILED without reimplementing any mechanism.
+  let closure;
+  try {
+    closure = await computeResourceClosure({
+      root: workspaceRoot,
+      resources: executionFiles.map((path) => ({ path, role: 'input' })),
+    });
+  } catch (cause) {
+    if (cause instanceof ReleaseError) throw cause;
+    fail(`cannot compute the executionFiles closure: ${cause?.message ?? cause}`, {
+      kind: cause?.details?.kind,
+    });
+  }
+
+  const bundleRoot = bundleRootForAuthorityDir(releaseSkillDir);
+  await mkdir(bundleRoot, { recursive: true });
+
+  for (const resource of closure.resources) {
+    // Strict re-read bound to the frozen digest: any byte drift between the
+    // closure computation and the publication fails closed.
+    let receipt;
+    try {
+      receipt = await readFileStrict(workspaceRoot, resource.path, { expectedSha256: resource.sha256 });
+    } catch (cause) {
+      fail(`cannot strictly read executionFiles entry for publication: ${cause?.message ?? cause}`, {
+        path: resource.path,
+        kind: cause?.details?.kind,
+      });
+    }
+    const relTarget = join(closure.digest, resource.path);
+    try {
+      await publishFileExclusive(bundleRoot, relTarget, receipt.content, {
+        mode: EXECUTION_BUNDLE_FILE_MODE,
+        createParents: true,
+      });
+    } catch (cause) {
+      if (cause?.details?.kind === HARNESS_ERROR_KINDS.EXCLUSIVE_PUBLISH_CONFLICT) {
+        // Idempotent same-bytes re-prepare: the existing slot must carry the
+        // exact frozen bytes at the publication mode, verified strictly.
+        try {
+          const existing = await readFileStrict(bundleRoot, relTarget, { expectedSha256: resource.sha256 });
+          if (existing.mode !== EXECUTION_BUNDLE_FILE_MODE) {
+            fail('existing bundle file carries an unexpected mode', { path: resource.path, mode: existing.mode });
+          }
+          continue;
+        } catch (verifyCause) {
+          fail(`bundle slot already exists with divergent bytes: ${verifyCause?.message ?? verifyCause}`, {
+            path: resource.path,
+            kind: verifyCause?.details?.kind,
+          });
+        }
+      }
+      fail(`cannot publish bundle bytes: ${cause?.message ?? cause}`, {
+        path: resource.path,
+        kind: cause?.details?.kind,
+      });
+    }
+  }
+
+  return {
+    foundationMechanism: EXECUTION_BUNDLE_MECHANISM,
+    closure,
+    publicFiles: structuredClone(publicFiles),
+  };
+}
+
+/**
+ * Field-by-field closure comparison (the recomputed Foundation closure must
+ * equal the frozen plan closure; the digest alone is compared first).
+ */
+function sameClosureResources(actual, expected) {
+  if (!Array.isArray(actual) || !Array.isArray(expected) || actual.length !== expected.length) return false;
+  for (let index = 0; index < expected.length; index += 1) {
+    const left = actual[index] ?? {};
+    const right = expected[index] ?? {};
+    if (left.path !== right.path || left.role !== right.role
+      || left.exists !== right.exists || left.sha256 !== right.sha256) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Re-verify the frozen execution bundle and install ONLY the verified bytes
+ * into the detached tag worktree. Runs BEFORE any hook or external write.
+ *
+ * Steps:
+ * 1. Strictly read every frozen resource from the digest-addressed store
+ *    (`readFileStrict` with the frozen sha256 content guard); the file mode
+ *    must still equal the publication mode — any deviation is tamper;
+ * 2. recompute the closure through Foundation in a disposable workspace and
+ *    compare it (digest + resources) with the plan's frozen closure;
+ * 3. exclusively publish the verified bytes into the worktree — an occupied
+ *    target means the bundle would shadow a frozen tag file and fails closed.
+ *
+ * @param {object} params
+ * @param {object} params.plan - Frozen plan (postPublish.executionBundle).
+ * @param {string} params.planPath - Absolute plan authority path (mechanical
+ *   bundle-root anchor).
+ * @param {string} params.worktreePath - Detached tag worktree root.
+ * @returns {Promise<{installed: string[]}>} Installed relative paths.
+ */
+export async function verifyAndInstallExecutionBundle({ plan, planPath, worktreePath } = {}) {
+  const bundle = plan?.postPublish?.executionBundle;
+  if (!bundle) return { installed: [] };
+  const closure = bundle.closure;
+  if (!closure || !Array.isArray(closure.resources) || typeof closure.digest !== 'string') {
+    fail('plan carries a malformed executionBundle closure');
+  }
+
+  const bundleRoot = deriveBundleRoot(planPath);
+  const bytesByPath = new Map();
+  for (const resource of closure.resources) {
+    if (!resource || resource.role !== 'input' || resource.exists !== true || typeof resource.sha256 !== 'string') {
+      fail('executionBundle closure resources must be existing input resources with frozen digests', {
+        path: resource?.path,
+      });
+    }
+    let receipt;
+    try {
+      receipt = await readFileStrict(bundleRoot, join(closure.digest, resource.path), {
+        expectedSha256: resource.sha256,
+      });
+    } catch (cause) {
+      fail(`bundle resource is missing or drifted from the frozen closure: ${cause?.message ?? cause}`, {
+        path: resource.path,
+        kind: cause?.details?.kind,
+      });
+    }
+    if (receipt.mode !== EXECUTION_BUNDLE_FILE_MODE) {
+      fail(`bundle resource mode was tampered (expected ${EXECUTION_BUNDLE_FILE_MODE.toString(8)}, got ${receipt.mode.toString(8)})`, {
+        path: resource.path,
+      });
+    }
+    bytesByPath.set(resource.path, receipt.content);
+  }
+
+  // Foundation recomputation in a disposable workspace: any inconsistency
+  // fails before a hook or an external write.
+  try {
+    await withTemporaryWorkspace(async (workspace) => {
+      for (const resource of closure.resources) {
+        await workspace.writeFile(resource.path, bytesByPath.get(resource.path));
+      }
+      const recomputed = await computeResourceClosure({
+        root: workspace.root,
+        resources: closure.resources.map((resource) => ({ path: resource.path, role: resource.role })),
+      });
+      if (recomputed.digest !== closure.digest || !sameClosureResources(recomputed.resources, closure.resources)) {
+        fail('recomputed bundle closure differs from the frozen plan closure');
+      }
+    }, { prefix: 'rs-execution-bundle-verify-' });
+  } catch (cause) {
+    if (cause instanceof ReleaseError) throw cause;
+    fail(`bundle closure recomputation failed: ${cause?.message ?? cause}`, { kind: cause?.details?.kind });
+  }
+
+  // Install verified bytes into the tag worktree — exclusively: the bundle
+  // must never overwrite (shadow) a file that already belongs to the tag.
+  const installed = [];
+  for (const resource of closure.resources) {
+    try {
+      await publishFileExclusive(worktreePath, resource.path, bytesByPath.get(resource.path), {
+        mode: EXECUTION_BUNDLE_FILE_MODE,
+        createParents: true,
+      });
+    } catch (cause) {
+      if (cause?.details?.kind === HARNESS_ERROR_KINDS.EXCLUSIVE_PUBLISH_CONFLICT) {
+        fail(`execution bundle would overwrite a frozen tag file: ${resource.path}`, { path: resource.path });
+      }
+      fail(`cannot install bundle bytes into the tag worktree: ${cause?.message ?? cause}`, {
+        path: resource.path,
+        kind: cause?.details?.kind,
+      });
+    }
+    installed.push(resource.path);
+  }
+  return { installed };
+}