@rightkit/release 0.6.13 → 0.6.15

package/native-tool-planning.mjs

@@ -0,0 +1,94 @@
+// GB-51 (GATE Mac/Dell broker-only; commit output identity): the native build tools an app config declares (xcodegen and xcodebuild for iOS, Gradle for Android, CMake for a sidecar)
+// each have a constrained broker adapter (native-adapters.mjs: capability `adapter:rightkit-xcodegen|xcodebuild|gradle|cmake`) and a launch route onto it (build-launch.mjs). This module decides at PLANNING, from the
+// commit's own config, whether a stage that uses them can run, so the route (and `--route`) refuses before anything builds, naming the missing capability or the unsupported command:
+//   - a tool whose adapter capability the broker does not advertise (or whose capability query failed) is refused naming the missing capability (one of the four above);
+//   - a declared build step (a dev target's `build` list) whose argv the tool's registration would refuse (an output override, an unregistered flag, a release task, a signing identity) is
+//     refused naming the capability and the reason: an unsupported custom command never reaches the broker;
+//   - a Gradle step needs the committed wrapper's distribution pinned (`distributionSha256Sum`), the adapter's pinned executable identity.
+// There is no direct-session exemption: a tool leaves the refusal only when its adapter is advertised.
+import path from "node:path";
+import { NATIVE_ADAPTERS, gradleWrapperPinProblem, nativeToolLaunch } from "./native-adapters.mjs";
+import { validateAndroidNdk } from "./android-ndk.mjs";
+
+/**
+ * GB-62: `cargo ndk` is a pinned EXTERNAL tool: RustRight's `externalCommands` entry (shim cargo, command ndk, a toolId and the tool's digest; policy BUILD). The broker advertises it
+ * as this capability; a stage that builds JNI libraries is planned only when it is advertised.
+ */
+export const NDK_EXTERNAL_CAPABILITY = "external:cargo-ndk";
+/** The ABIs RustRight's ndk grammar accepts (`parse_ndk_argv`: arm64-v8a, x86_64); the gate's own validator also knows armeabi-v7a and x86, which the broker would refuse. */
+export const BROKER_NDK_ABIS = Object.freeze(["arm64-v8a", "x86_64"]);
+
+/** The tools that run through a constrained adapter, by the capability name a refusal reports (xcodegen, xcodebuild, gradle and its wrapper, cmake). */
+export const NATIVE_TOOLS_WITHOUT_ADAPTER = Object.freeze({ xcodegen: NATIVE_ADAPTERS.xcodegen.capability, xcodebuild: NATIVE_ADAPTERS.xcodebuild.capability, gradle: NATIVE_ADAPTERS.gradle.capability, gradlew: NATIVE_ADAPTERS.gradle.capability, cmake: NATIVE_ADAPTERS.cmake.capability });
+
+const base = (command) => path.basename(String(command ?? "").replaceAll("\\", "/")).replace(/\.(exe|cmd|bat)$/i, "").toLowerCase();
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * The native-tool uses of a stage, `[{ tool, capability, where }]`, from the commit's own config. `devPlatform` is the dev target's platform for a dev or
+ * test run (its declared build steps and, for iOS, the xcodegen/xcodebuild steps the gate itself generates are in play); a `cmake` sidecar is in play for
+ * every stage that stages sidecars.
+ */
+export function nativeToolUses({ config, to, devPlatform = null, platform = null }) {
+  const uses = [];
+  const add = (command, where, args = null, cwd = ".") => { const tool = base(command); if (Object.hasOwn(NATIVE_TOOLS_WITHOUT_ADAPTER, tool)) uses.push({ tool, capability: NATIVE_TOOLS_WITHOUT_ADAPTER[tool], where, ...(args ? { args, cwd } : {}) }); };
+  if (!isObject(config)) return uses;
+  const addNdk = (ndk, where, kind) => { if (ndk !== undefined) uses.push({ tool: "cargo-ndk", capability: NDK_EXTERNAL_CAPABILITY, where, ndk, kind }); };
+  if ((to === "dev" || to === "test") && (platform ?? devPlatform) === "android") addNdk(config.development?.targets?.android?.ndk, "development.targets.android.ndk", "dev");
+  if ((to === "package" || to === "release") && (platform ?? devPlatform) === "android") addNdk(config.targets?.android?.ndk, "targets.android.ndk", "release");
+  if (to === "dev" || to === "test") {
+    const target = config.development?.targets?.[devPlatform];
+    if (isObject(target)) {
+      for (const [i, step] of (Array.isArray(target.build) ? target.build : []).entries()) if (isObject(step)) add(step.cmd, `development.targets.${devPlatform}.build[${i}]`, Array.isArray(step.args) ? step.args.map(String) : [], typeof step.cwd === "string" ? step.cwd : ".");
+      if (devPlatform === "ios") {
+        if (target.projectSpec) add("xcodegen", `development.targets.ios.projectSpec ${target.projectSpec} (xcodegen generate)`);
+        add("xcodebuild", "development.targets.ios (xcodebuild build)");
+      }
+    }
+  }
+  for (const [i, entry] of (Array.isArray(config.sidecars?.sidecars) ? config.sidecars.sidecars : Array.isArray(config.sidecars) ? config.sidecars : []).entries()) {
+    if (isObject(entry) && entry.kind === "cmake") add("cmake", `sidecars[${i}] ${entry.name ?? ""} (kind cmake)`);
+  }
+  return uses;
+}
+
+/**
+ * The refusal message for a stage's native-tool uses, or null. `capabilities` is the broker's advertised state (`{ ok, capabilities }` from `rustright doctor --json`, or null when it was not
+ * queried: every use is then unsupported). `readFile(relative)` reads the COMMIT's bytes (a Gradle wrapper's properties).
+ */
+export function nativeToolRefusal(uses, { capabilities = null, readFile = null, listFiles = null } = {}) {
+  if (!uses.length) return null;
+  const advertised = capabilities?.ok === true && Array.isArray(capabilities.capabilities) ? new Set(capabilities.capabilities) : new Set();
+  const problems = [];
+  for (const use of uses) {
+    if (!advertised.has(use.capability)) { problems.push(`${use.tool} at ${use.where}: the broker does not advertise ${use.capability}${capabilities?.ok === true ? "" : ` (${capabilities?.problem ?? "its capabilities were not queried"})`}`); continue; }
+    if (use.tool === "cargo-ndk") { const problem = ndkBlockProblem(use, listFiles); if (problem) problems.push(`${use.tool} at ${use.where}: ${problem}`); continue; }
+    if (use.args) {
+      const launch = nativeToolLaunch(use.tool === "gradlew" ? "gradle" : use.tool, use.args, { cwd: path.posix.resolve("/", use.cwd ?? ".") });
+      if (launch.refusal) { problems.push(`${use.tool} at ${use.where}: ${launch.refusal.message}`); continue; }
+    }
+    if ((use.tool === "gradle" || use.tool === "gradlew") && typeof readFile === "function") {
+      const pin = gradleWrapperPinProblem(readFile, use.cwd ?? ".");
+      if (pin) problems.push(`${use.tool} at ${use.where}: ${pin}`);
+    }
+  }
+  if (!problems.length) return null;
+  return `${problems.join("; ")} (a broker-managed host never runs a build tool around the broker, rightkit#1241; the capability names are in docs/GATE-CONTRACT.md "Native tool adapters"); nothing ran`;
+}
+
+/**
+ * GB-62: the reason a declared ndk block cannot run through the pinned cargo-ndk registration, or null. The gate's own validator names a malformed block; the ABIs must be ones RustRight's
+ * ndk grammar accepts; and `jniLibs`, the controlled generated output (emptied before every build and bound as the run's output ledger), must hold no committed file.
+ */
+function ndkBlockProblem(use, listFiles) {
+  let ndk;
+  try { ndk = validateAndroidNdk(use.ndk, { root: "/app", kind: use.kind }); } catch (error) { return error.message; }
+  const refused = ndk.abis.filter((abi) => !BROKER_NDK_ABIS.includes(abi));
+  if (refused.length) return `ndk.abis names ${refused.join(", ")}, which the registered cargo-ndk grammar refuses (only ${BROKER_NDK_ABIS.join(", ")}; ${NDK_EXTERNAL_CAPABILITY})`;
+  if (typeof listFiles === "function") {
+    let tracked = null;
+    try { tracked = listFiles(ndk.jniLibsRelative); } catch { tracked = null; }
+    if (Array.isArray(tracked) && tracked.length) return `ndk.jniLibs ${ndk.jniLibsRelative} commits ${tracked.length} file(s) (${tracked.slice(0, 3).join(", ")}): it is the generated output directory (emptied before every build) and must hold no committed file`;
+  }
+  return null;
+}

package/ownership-mark.mjs

@@ -0,0 +1,182 @@
+// The build-ownership record's broker-submit mark and the constants every process under an ownership shares. A LEAF module: it imports
+// only node builtins, so snapshot-broker.mjs (carried sends, in the gate and in its children) and build-ownership.mjs can both use it
+// without an import cycle.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import { LOCK_SAME_START_MS, lockBootId, lockProcessIdentity, selfLockIdentity } from "./lock-identity.mjs";
+
+export const OWNERSHIP_ENV = "RIGHTKIT_BUILD_OWNERSHIP";
+/** The owner record's path, exported beside the handle so every process under the ownership records detached children there. */
+export const OWNERSHIP_FILE_ENV = "RIGHTKIT_BUILD_OWNERSHIP_FILE";
+
+export class OwnershipBusy extends Error {
+  constructor(message, detail = {}) { super(message); this.code = "busy"; this.detail = detail; }
+}
+
+const readText = (file) => { try { return fs.readFileSync(file, "utf8"); } catch (e) { if (e.code === "ENOENT") return null; throw e; } };
+
+export function holds(file, handle) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")).handle === handle; } catch { return false; }
+}
+
+/**
+ * Records, immediately before ONE snapshot-bound (carried) request is sent, that broker work may exist under this handle: sets
+ * `broker.submitted` and appends the request's sub-handle (`<handle>#<uuid>`) to `broker.handles`. From then on the record is
+ * reclaimed only on the broker's REAPED for the bare handle. Nothing else marks it: installing a carrier map, an uncarried probe
+ * (`rustc -vV`, `--version`, doctor) and a request that was never sent leave `submitted` false, because the broker has no lease
+ * for a handle it never saw a snapshot-bound request under and could never answer REAPED. Replaces the record atomically, only
+ * while it is still this handle's, under a short lock beside the record (carried calls of parallel children, in other
+ * processes, mark the same record).
+ */
+export function markBrokerSubmit(file, handle, callHandle, options = {}) {
+  if (typeof callHandle !== "string" || callHandle.length <= handle.length + 1 || !callHandle.startsWith(`${handle}#`) || !/^[A-Za-z0-9._-]+$/.test(callHandle.slice(handle.length + 1))) {
+    throw new OwnershipBusy(`build ownership ${file}: a broker submit is recorded only for a carried request's sub-handle of ${handle} (<handle>#<id>), not ${JSON.stringify(callHandle ?? null)}`);
+  }
+  return withMarkLock(file, () => {
+    const text = readText(file);
+    let owner = null; try { owner = JSON.parse(text ?? ""); } catch { owner = null; }
+    if (owner?.handle !== handle) throw new OwnershipBusy(`build ownership ${file} is no longer held by ${handle}; no broker request may be submitted`);
+    const seen = Array.isArray(owner.broker?.handles) ? owner.broker.handles : [];
+    if (owner.broker?.submitted && seen.includes(callHandle)) return owner;
+    const next = { ...owner, broker: { ...(owner.broker ?? {}), submitted: true, at: owner.broker?.at ?? new Date().toISOString(), handles: [...seen, callHandle] } };
+    const tmp = `${file}.${crypto.randomUUID()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next), { flag: "wx", mode: 0o600 });
+    try { fs.renameSync(tmp, file); } finally { fs.rmSync(tmp, { force: true }); }
+    if (!holds(file, handle)) throw new OwnershipBusy(`build ownership ${file} changed while recording a broker submit`);
+    return next;
+  }, options);
+}
+
+/**
+ * GB-21: records, under the same lock, that the carried request `callHandle` was PROVEN never to have started: the gate could not even start the RustRight client
+ * (no such executable, not executable, a refused spawn), so no byte reached the broker. Only a sub-handle already marked as sent can be marked unsent (the mark
+ * preceded the attempt); the record keeps `submitted` and the handle, and adds `broker.unsent[callHandle] = { reason, at }`. A reclaim then accepts the sub-handle as
+ * settled only when the broker also holds no lease or completion for it (it answers UNKNOWN with no members: it never saw it). An ambiguous send (a timeout, a lost
+ * connection after the client started) is never marked unsent: its uncertainty is reconciled by the request id, never erased.
+ */
+export function markBrokerUnsent(file, handle, callHandle, reason, options = {}) {
+  if (typeof callHandle !== "string" || callHandle.length <= handle.length + 1 || !callHandle.startsWith(`${handle}#`) || !/^[A-Za-z0-9._-]+$/.test(callHandle.slice(handle.length + 1))) {
+    throw new OwnershipBusy(`build ownership ${file}: only a sub-handle of ${handle} (<handle>#<id>) can be marked unsent, not ${JSON.stringify(callHandle ?? null)}`);
+  }
+  if (typeof reason !== "string" || reason === "") throw new OwnershipBusy(`build ownership ${file}: an unsent mark names the local proof that nothing was sent`);
+  return withMarkLock(file, () => {
+    let owner = null; try { owner = JSON.parse(readText(file) ?? ""); } catch { owner = null; }
+    if (owner?.handle !== handle) throw new OwnershipBusy(`build ownership ${file} is no longer held by ${handle}`);
+    if (!Array.isArray(owner.broker?.handles) || !owner.broker.handles.includes(callHandle)) throw new OwnershipBusy(`build ownership ${file}: ${callHandle} was never marked as sent, so it cannot be marked unsent`);
+    const next = { ...owner, broker: { ...owner.broker, unsent: { ...(owner.broker.unsent ?? {}), [callHandle]: { reason, at: new Date().toISOString() } } } };
+    const tmp = `${file}.${crypto.randomUUID()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next), { flag: "wx", mode: 0o600 });
+    try { fs.renameSync(tmp, file); } finally { fs.rmSync(tmp, { force: true }); }
+    if (!holds(file, handle)) throw new OwnershipBusy(`build ownership ${file} changed while recording an unsent mark`);
+    return next;
+  }, options);
+}
+
+const MARK_LOCK_WAIT_MS = 15_000;
+export const MARK_LOCK_SCHEMA = "rightkit.build-ownership-mark-lock/1";
+/** The lock beside the record that serializes `broker.handles` updates. Removed with the record (release, reclaim). */
+export const markLockFile = (file) => `${file}.mark.lock`;
+const stealClaimFile = (file, nonce) => `${markLockFile(file)}.steal-${nonce}`;
+
+const defaultSleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const parseLock = (text) => { try { const rec = JSON.parse(text); return rec && typeof rec === "object" && rec.schema === MARK_LOCK_SCHEMA && typeof rec.nonce === "string" && /^[0-9a-f-]{36}$/.test(rec.nonce) ? rec : null; } catch { return null; } };
+const readLockText = (lock) => { try { return fs.readFileSync(lock, "utf8"); } catch (e) { if (e.code === "ENOENT") return null; throw e; } };
+
+/**
+ * Whether the holder recorded in a lock is `"dead"` (proven), `"live"`, or `"unknown"`. Only `"dead"` ever allows a steal: age proves nothing
+ * (a suspended live holder can resume), so a lock is taken from its holder only on proof, the same proofs the ownership record uses
+ * (build-ownership.mjs judgeOwner): the host rebooted (boot ids differ), the pid is gone, or the pid now runs a process that started at another
+ * time. Anything unreadable, another host, or an identity that cannot be read is not proof.
+ */
+export function judgeLockHolder(rec, { identity, host = os.hostname() }) {
+  if (!rec || !Number.isInteger(rec.pid) || rec.pid <= 0) return "unknown";
+  if (rec.host !== host) return "unknown";
+  let boot = null; try { boot = identity.bootId(); } catch { boot = null; }
+  if (typeof rec.bootId === "string" && rec.bootId && typeof boot === "string" && boot && rec.bootId !== boot) return "dead";
+  let now;
+  try { now = identity.probe(rec.pid); } catch { return "unknown"; }
+  if (!now.alive) return "dead";
+  if (!Number.isFinite(rec.startedMs) || !Number.isFinite(now.startedMs)) return "unknown";
+  return Math.abs(now.startedMs - rec.startedMs) <= LOCK_SAME_START_MS ? "live" : "dead";
+}
+
+/** Creates `target` holding `record` atomically and exclusively: the content is complete the moment the name exists (write a temp file, hard-link it). */
+function createExclusive(target, record) {
+  const tmp = `${target}.${record.nonce}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(record), { flag: "wx", mode: 0o600 });
+  try { fs.linkSync(tmp, target); return true; }
+  catch (e) { if (e.code === "EEXIST") return false; throw e; }
+  finally { fs.rmSync(tmp, { force: true }); }
+}
+
+/**
+ * Runs `fn` under the lock beside the record. The lock names its holder (pid, start time, boot id) and carries a random nonce:
+ *   - a holder that is alive is never displaced, however long it holds (it may be suspended and resume);
+ *   - a holder PROVEN dead is displaced by one claimant per observed lock (a claim file named by the dead lock's nonce), which removes
+ *     the lock only while it is still the exact one it judged;
+ *   - when liveness is uncertain the caller waits, and past the deadline fails closed with OwnershipBusy (no request is sent);
+ *   - release removes the lock only while it still carries this holder's nonce, so a holder that somehow lost it never removes a successor's.
+ * `options` are seams for tests: `identity` ({ self(), probe(pid), bootId() }), `sleep`, `waitMs`.
+ */
+export function withMarkLock(file, fn, options = {}) {
+  const lock = markLockFile(file);
+  const identity = options.identity ?? { self: () => selfLockIdentity(), probe: (pid) => lockProcessIdentity(pid), bootId: () => lockBootId() };
+  const sleep = options.sleep ?? defaultSleep;
+  const deadline = Date.now() + (options.waitMs ?? MARK_LOCK_WAIT_MS);
+  let me;
+  try { me = identity.self(); } catch (e) { throw new OwnershipBusy(`build ownership ${file}: this process's identity cannot be read (${e.message}), so it cannot take the submit lock`); }
+  const record = { schema: MARK_LOCK_SCHEMA, pid: me.pid, startedMs: me.startedMs, bootId: me.bootId ?? null, host: os.hostname(), nonce: crypto.randomUUID(), at: new Date().toISOString() };
+  const take = (target) => {
+    try { return createExclusive(target, record); }
+    catch (e) { throw new OwnershipBusy(`build ownership ${file}: the submit lock cannot be taken (${e.code ?? e.message})`); }
+  };
+  let lastVerdict = "unknown";
+  for (;;) {
+    if (take(lock)) break;
+    let text;
+    try { text = readLockText(lock); } catch (e) { throw new OwnershipBusy(`build ownership ${file}: the submit lock cannot be read (${e.code ?? e.message})`); }
+    if (text === null) continue; // it was released between the create and the read
+    const observed = parseLock(text);
+    lastVerdict = observed ? judgeLockHolder(observed, { identity }) : "unknown";
+    if (lastVerdict === "dead" && stealDeadLock({ file, lock, text, observed, record, identity, take })) continue;
+    if (Date.now() > deadline) throw new OwnershipBusy(`build ownership ${file}: the submit lock ${lock} is held${observed ? ` by pid ${observed.pid}` : " by a holder that cannot be read"} and ${lastVerdict === "live" ? "is alive" : "its liveness cannot be proven"}; no broker request is sent`, { holder: observed, verdict: lastVerdict });
+    sleep(10);
+  }
+  try { return fn(); } finally {
+    try { const held = parseLock(readLockText(lock) ?? ""); if (held?.nonce === record.nonce) fs.rmSync(lock, { force: true }); } catch { /* the lock stays; a later caller proves its holder dead */ }
+  }
+}
+
+/** Removes the lock `text`/`observed`, whose holder is proven dead, if this process wins the one claim for that lock. Returns whether the retry should go straight on. */
+function stealDeadLock({ file, lock, text, observed, record, identity, take }) {
+  const claim = stealClaimFile(file, observed.nonce);
+  if (!take(claim)) {
+    // Another process is stealing the same dead lock, or died doing it: a claim whose holder is proven dead is dropped, anything else waits.
+    const claimText = readLockText(claim);
+    if (claimText !== null && judgeLockHolder(parseLock(claimText), { identity }) === "dead") fs.rmSync(claim, { force: true });
+    return false;
+  }
+  try {
+    if (readLockText(lock) === text) fs.rmSync(lock, { force: true });
+  } finally {
+    try { if (parseLock(readLockText(claim) ?? "")?.nonce === record.nonce) fs.rmSync(claim, { force: true }); } catch { /* a dead claim is dropped by the next claimant */ }
+  }
+  return true;
+}
+
+/**
+ * Marks the record at `file` as having sent the carried request `callHandle`, for a caller that holds no ownership object (a
+ * right-release child of the gate, in another process, which inherits the handle and file in its environment). Throws
+ * OwnershipBusy unless `handle` is still the record's owner.
+ */
+export function markCarriedSend({ file, handle, callHandle }) {
+  if (typeof file !== "string" || !file || typeof handle !== "string" || !handle) throw new OwnershipBusy("a carried request is marked only under a build ownership file and handle");
+  return markBrokerSubmit(file, handle, callHandle);
+}
+
+/** The caller that holds no ownership object (a right-release child): the same unsent mark under the inherited handle and file. */
+export function markCarriedUnsent({ file, handle, callHandle, reason }) {
+  if (typeof file !== "string" || !file || typeof handle !== "string" || !handle) throw new OwnershipBusy("an unsent mark is recorded only under a build ownership file and handle");
+  return markBrokerUnsent(file, handle, callHandle, reason);
+}

package/pack-digest.mjs

@@ -0,0 +1,122 @@
+// The content digest of an npm archive: sha256 over the sorted list of (path, type, exec bit, sha256 of the content) of its entries.
+// The archive's own bytes depend on gzip, entry order and mtimes; this digest depends only on what the package ships, so two packs of
+// one commit compare equal whatever produced them. It is read with node:zlib and a strict ustar/pax reader (no system tar: the listing
+// `tar -tzf` carries no mode or type, and the hosted runner and the local host must agree on one reading).
+//
+// Exclusions are code constants, never input (rightkit#1301 B2): the one binary whose bytes differ between a local pack and the hosted
+// one is @rightkit/release's Developer-ID-signed `bin/darwin/rightkit-swap`, which is re-signed with a timestamp on every signing, and
+// its `.sign.json` receipt. `exclusionsFor` returns them for that one package; every other unit has an empty set. The hosted side binds
+// the excluded helper separately (publish-admission.mjs bindPackedToQualification: its sha256 equals the sign-swap job's).
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import zlib from "node:zlib";
+import { canonicalJson } from "./provenance-verify.mjs";
+import { SWAP_HELPER_BIN, SWAP_HELPER_PACKAGE, SWAP_HELPER_RECEIPT } from "./swap-helper-bundle.mjs";
+
+export const CONTENT_DIGEST_DOMAIN = "rightkit-npm-content-v1";
+/** An npm tarball's entries all live under `package/`. */
+const ROOT = "package";
+export const SWAP_HELPER_ARCHIVE_BIN = `${ROOT}/${SWAP_HELPER_BIN.join("/")}`;
+export const SWAP_HELPER_ARCHIVE_RECEIPT = `${ROOT}/${SWAP_HELPER_RECEIPT.join("/")}`;
+
+/** The archive paths left out of a unit's content digest: the swap helper and its receipt for @rightkit/release, nothing for any other unit. */
+export function exclusionsFor(unitName) {
+  return unitName === SWAP_HELPER_PACKAGE ? [SWAP_HELPER_ARCHIVE_BIN, SWAP_HELPER_ARCHIVE_RECEIPT] : [];
+}
+
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+const MAX_ARCHIVE_BYTES = 1024 * 1024 * 1024;
+const TYPES = { 0: "file", "\0": "file", 1: "hardlink", 2: "symlink", 5: "directory" };
+
+const field = (block, start, length) => { const end = block.indexOf(0, start); return block.toString("utf8", start, end === -1 || end > start + length ? start + length : end); };
+const octal = (block, start, length, what) => {
+  // A size or mode field is octal ASCII, or base-256 (high bit of the first byte) for a size beyond 8 GiB.
+  if (block[start] & 0x80) { let n = 0n; for (let i = 1; i < length; i += 1) n = (n << 8n) | BigInt(block[start + i]); return Number(n); }
+  const text = block.toString("ascii", start, start + length).replace(/[\0 ]+$/g, "").trim();
+  if (text === "") return 0;
+  if (!/^[0-7]+$/.test(text)) throw new Error(`the archive has a malformed ${what} field`);
+  return Number.parseInt(text, 8);
+};
+
+function paxRecords(data) {
+  const out = {};
+  let at = 0;
+  while (at < data.length) {
+    const space = data.indexOf(0x20, at);
+    const length = Number.parseInt(data.toString("ascii", at, space), 10);
+    if (!Number.isInteger(length) || space < 0 || length < space - at + 2 || at + length > data.length) throw new Error("the archive has a malformed pax header");
+    const record = data.toString("utf8", space + 1, at + length - 1);
+    const eq = record.indexOf("=");
+    if (eq > 0) out[record.slice(0, eq)] = record.slice(eq + 1);
+    at += length;
+  }
+  return out;
+}
+
+/** The entries of a gunzipped tar: `[{ path, type, mode, data }]`, in archive order. Refuses what it cannot read exactly. */
+export function parseTar(tar) {
+  const entries = [];
+  let at = 0;
+  let pending = {}; // pax/GNU overrides for the next entry
+  let ended = false;
+  while (at + 512 <= tar.length) {
+    const header = tar.subarray(at, at + 512);
+    if (header.every((b) => b === 0)) { ended = true; break; }
+    const stored = octal(header, 148, 8, "checksum");
+    let sum = 0;
+    for (let i = 0; i < 512; i += 1) sum += i >= 148 && i < 156 ? 0x20 : header[i];
+    if (sum !== stored) throw new Error("the archive has a header with a bad checksum");
+    const size = octal(header, 124, 12, "size");
+    const flag = String.fromCharCode(header[156]);
+    const bodyStart = at + 512;
+    const bodyEnd = bodyStart + size;
+    if (bodyEnd > tar.length) throw new Error("the archive is truncated");
+    const body = tar.subarray(bodyStart, bodyEnd);
+    at = bodyStart + Math.ceil(size / 512) * 512;
+    if (flag === "x") {
+      const records = paxRecords(body);
+      if (records.size !== undefined) throw new Error("the archive overrides an entry size in a pax header");
+      pending = { ...pending, ...records };
+      continue;
+    }
+    if (flag === "g") throw new Error("the archive carries a global pax header");
+    if (flag === "L") { pending.path = body.toString("utf8").replace(/\0+$/, ""); continue; }
+    if (flag === "K") { pending.linkpath = body.toString("utf8").replace(/\0+$/, ""); continue; }
+    const type = TYPES[flag];
+    if (!type) throw new Error(`the archive has an entry of unsupported type ${JSON.stringify(flag)}`);
+    const ustar = header.toString("ascii", 257, 262) === "ustar";
+    const prefix = ustar ? field(header, 345, 155) : "";
+    const name = pending.path ?? (prefix ? `${prefix}/${field(header, 0, 100)}` : field(header, 0, 100));
+    const linkpath = pending.linkpath ?? field(header, 157, 100);
+    pending = {};
+    entries.push({ path: name.replace(/\/+$/, ""), type, mode: octal(header, 100, 8, "mode"), data: type === "file" ? body : type === "directory" ? Buffer.alloc(0) : Buffer.from(linkpath, "utf8") });
+  }
+  if (!ended) throw new Error("the archive is truncated: it has no end marker");
+  if (Object.keys(pending).length) throw new Error("the archive ends after a header with no entry");
+  return entries;
+}
+
+/**
+ * `{ contentSha256, entries, excluded }` of an npm archive. `exclude` lists archive paths (`package/...`) left out of the digest; each one
+ * present is reported in `excluded` as `{ type, exec, sha256 }`, so a caller binds it by another route. Two entries of one path, an
+ * unreadable header or an unsupported entry type refuse (an archive that reads two ways has no one digest).
+ */
+export function npmContentDigest(tgz, { exclude = [] } = {}) {
+  let tar;
+  try { tar = zlib.gunzipSync(Buffer.isBuffer(tgz) ? tgz : fs.readFileSync(tgz), { maxOutputLength: MAX_ARCHIVE_BYTES }); }
+  catch (error) { throw new Error(`the archive is not a readable gzip (${error.message})`); }
+  const skip = new Set(exclude);
+  const rows = [];
+  const excluded = {};
+  const seen = new Set();
+  for (const entry of parseTar(tar)) {
+    if (seen.has(entry.path)) throw new Error(`the archive holds ${entry.path} twice`);
+    seen.add(entry.path);
+    const row = { path: entry.path, type: entry.type, exec: (entry.mode & 0o111) !== 0, sha256: sha256(entry.data) };
+    if (skip.has(entry.path)) excluded[entry.path] = { type: row.type, exec: row.exec, sha256: row.sha256 };
+    else rows.push(row);
+  }
+  rows.sort((a, b) => Buffer.compare(Buffer.from(a.path, "utf8"), Buffer.from(b.path, "utf8")));
+  const contentSha256 = sha256(`${CONTENT_DIGEST_DOMAIN}\n${canonicalJson(rows.map((r) => [r.path, r.type, r.exec, r.sha256]))}`);
+  return { contentSha256, entries: rows.length, excluded };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "Portable release CLI/SDK with fail-closed public GitHub Releases and private R2 + RightApps distribution.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -45,9 +45,7 @@
   },
   "rightkit": {
     "publishCheck": {
-      "skipImport": [
-        "./sign-windows.mjs"
-      ],
+      "skipImport": [],
       "binSmoke": {
         "right-release": [
           "--version"
@@ -82,6 +80,14 @@
     "!provenance-real-receipt.fixture.json"
   ],
   "sideEffects": false,
+  "scripts": {
+    "test": "node test-support/run-test-shards.mjs",
+    "test:registry-parity": "node registry-parity.mjs --allow-unpublished",
+    "test:signer:windows": "node sign-release-manifest.integration.mjs",
+    "prepublishOnly": "pnpm test && pnpm test:signer:windows && pnpm test:registry-parity",
+    "doctor:all": "node --test right-suite-contract.test.mjs",
+    "verify:standalone": "node standalone-clone-verify.mjs"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -91,15 +97,9 @@
     "url": "git+https://github.com/bogusyogi/rightkit.git",
     "directory": "packages/release"
   },
+  "packageManager": "pnpm@12.16.1",
   "dependencies": {
     "@rightkit/outdated": "0.3.0",
     "smol-toml": "1.9.1"
-  },
-  "scripts": {
-    "test": "node --import ./test-support/broker-guard.mjs --test --test-concurrency=1 --test-force-exit *.test.mjs cli/*.test.mjs",
-    "test:registry-parity": "node registry-parity.mjs --allow-unpublished",
-    "test:signer:windows": "node sign-release-manifest.integration.mjs",
-    "doctor:all": "node --test right-suite-contract.test.mjs",
-    "verify:standalone": "node standalone-clone-verify.mjs"
   }
-}
+}