Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

build(zip): protect canonical archive publication

sunsunsuneed82c9ebd51
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 3560d5f9..0590f2d7 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -57,19 +57,16 @@ jobs:
echo "make_latest=true" >> "$GITHUB_OUTPUT"
fi
- name: Build skill archive
- run: scripts/build-zip.sh
+ run: scripts/build-zip.sh /tmp/archify-built.zip
- name: Validate the exact release archive without installing dependencies
run: |
set -euo pipefail
package_root="$RUNNER_TEMP/archify-release-package"
mkdir -p "$package_root"
- unzip -q archify.zip -d "$package_root"
+ unzip -q /tmp/archify-built.zip -d "$package_root"
node scripts/package-smoke.mjs "$package_root/archify"
- name: Committed zip must match the build (same gate as CI)
- run: |
- cp archify.zip /tmp/archify-built.zip
- git checkout HEAD -- archify.zip
- cmp -s /tmp/archify-built.zip archify.zip
+ run: cmp -s /tmp/archify-built.zip archify.zip
- name: Create GitHub Release with the zip attached
uses: softprops/action-gh-release@v2
with:
diff --git a/archify/test/release-package-gates.test.mjs b/archify/test/release-package-gates.test.mjs
index 90813fda..a8774832 100644
--- a/archify/test/release-package-gates.test.mjs
+++ b/archify/test/release-package-gates.test.mjs
@@ -35,16 +35,15 @@ test('release smokes the exact archive built for the release before freshness an
assert.ok(workflow.indexOf(tagGate) < workflow.indexOf(build), 'tag/version gate must precede the release build');
assert.ok(workflow.indexOf(build) < workflow.indexOf(smoke), 'release smoke must follow the archive build');
- assert.ok(workflow.indexOf(smoke) < workflow.indexOf(freshness), 'release smoke must inspect the built archive before it is restored');
+ assert.ok(workflow.indexOf(smoke) < workflow.indexOf(freshness), 'release smoke must inspect the built archive before comparison');
assert.ok(workflow.indexOf(freshness) < workflow.indexOf(upload), 'freshness must pass before release upload');
assert.match(tagGate, /require\('\.\/archify\/package\.json'\)\.version/);
assert.match(tagGate, /GITHUB_REF_NAME#v/);
- assert.match(build, /run: scripts\/build-zip\.sh/);
- assert.match(smoke, /unzip -q archify\.zip -d "\$package_root"/);
+ assert.match(build, /run: scripts\/build-zip\.sh \/tmp\/archify-built\.zip/);
+ assert.match(smoke, /unzip -q \/tmp\/archify-built\.zip -d "\$package_root"/);
assert.match(smoke, /node scripts\/package-smoke\.mjs "\$package_root\/archify"/);
assert.doesNotMatch(smoke, /\bnpm\s+(?:ci|install)\b/);
- assert.match(freshness, /git checkout HEAD -- archify\.zip/);
assert.match(freshness, /cmp -s \/tmp\/archify-built\.zip archify\.zip/);
assert.match(upload, /files: archify\.zip/);
});
@@ -175,6 +174,59 @@ test('archive build excludes untracked files and external symlinks from the live
}
});
+test('archive build rejects an unmerged index and preserves an existing archive', () => {
+ const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-unmerged-'));
+ const scripts = path.join(fixture, 'scripts');
+ const skill = path.join(fixture, 'archify');
+ const license = path.join(skill, 'LICENSE');
+ const archive = path.join(fixture, 'trusted.zip');
+ const trusted = Buffer.from('trusted archive bytes');
+ const git = (args, options = {}) => spawnSync('git', args, {
+ cwd: fixture,
+ encoding: 'utf8',
+ ...options,
+ });
+
+ try {
+ fs.mkdirSync(path.join(skill, 'renderers', 'shared'), { recursive: true });
+ fs.mkdirSync(scripts);
+ fs.copyFileSync(path.join(repoRoot, 'scripts', 'build-zip.sh'), path.join(scripts, 'build-zip.sh'));
+ fs.copyFileSync(
+ path.join(repoRoot, 'scripts', 'write-deterministic-zip.mjs'),
+ path.join(scripts, 'write-deterministic-zip.mjs'),
+ );
+ fs.writeFileSync(path.join(skill, 'renderers', 'shared', 'generated-validators.mjs'), 'export default {};\n');
+ fs.writeFileSync(path.join(skill, 'package.json'), '{"name":"archify"}\n');
+ fs.writeFileSync(license, 'base\n');
+ assert.equal(git(['init']).status, 0);
+ assert.equal(git(['add', '.']).status, 0);
+
+ const base = git(['hash-object', '-w', '--stdin'], { input: 'base\n' });
+ const ours = git(['hash-object', '-w', '--stdin'], { input: 'ours\n' });
+ const theirs = git(['hash-object', '-w', '--stdin'], { input: 'theirs\n' });
+ for (const result of [base, ours, theirs]) assert.equal(result.status, 0, result.stderr);
+ const indexInfo = [
+ `100644 ${base.stdout.trim()} 1\tarchify/LICENSE`,
+ `100644 ${ours.stdout.trim()} 2\tarchify/LICENSE`,
+ `100644 ${theirs.stdout.trim()} 3\tarchify/LICENSE`,
+ '',
+ ].join('\n');
+ assert.equal(git(['update-index', '--index-info'], { input: indexInfo }).status, 0);
+ fs.writeFileSync(license, '<<<<<<< ours\n=======\n>>>>>>> theirs\n');
+ fs.writeFileSync(archive, trusted);
+
+ const build = spawnSync('bash', [path.join(scripts, 'build-zip.sh'), archive], {
+ cwd: fixture,
+ encoding: 'utf8',
+ });
+ assert.notEqual(build.status, 0, `${build.stdout}\n${build.stderr}`);
+ assert.match(build.stderr, /refusing to package unmerged index entry/);
+ assert.deepEqual(fs.readFileSync(archive), trusted, 'a failed build must preserve the trusted archive');
+ } finally {
+ fs.rmSync(fixture, { recursive: true, force: true });
+ }
+});
+
test('archive build is byte-for-byte reproducible across caller time zones without system zip', () => {
const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-package-reproducible-'));
const utcArchive = path.join(outputRoot, 'utc.zip');
@@ -203,9 +255,11 @@ test('archive build is byte-for-byte reproducible across caller time zones witho
fs.readFileSync(path.join(repoRoot, 'archify.zip')),
'the canonical archive toolchain must reproduce the committed archive bytes',
);
- const buildScript = fs.readFileSync(path.join(repoRoot, 'scripts', 'build-zip.sh'), 'utf8');
- assert.match(buildScript, /write-deterministic-zip\.mjs/);
- assert.doesNotMatch(buildScript, /(?:^|\s)zip\s/);
+ assert.deepEqual(
+ fs.readdirSync(outputRoot).sort(),
+ ['honolulu.zip', 'utc.zip'],
+ 'successful archive publication must not leave temporary files behind',
+ );
} finally {
fs.rmSync(outputRoot, { recursive: true, force: true });
}
@@ -228,5 +282,4 @@ test('CI tests the declared Node floor plus every maintained current lane', () =
const packageSmokeJob = workflowJob(workflow, 'package-smoke');
assert.match(packageSmokeJob, /os:\s*\[ubuntu-latest, macos-latest, windows-latest\]/);
assert.match(packageSmokeJob, /node-version:\s*22/);
- assert.doesNotMatch(packageSmokeJob, /compare exact bytes/);
});
diff --git a/integrations/deepseek-harness/scripts/distribution-acceptance.mjs b/integrations/deepseek-harness/scripts/distribution-acceptance.mjs
index 2d9af956..36fd4298 100644
--- a/integrations/deepseek-harness/scripts/distribution-acceptance.mjs
+++ b/integrations/deepseek-harness/scripts/distribution-acceptance.mjs
@@ -22,7 +22,7 @@ const receipt = {
dsh: { spec: DSH_SPEC },
node: process.version,
platform: process.platform,
- zipContainerNote: 'Fresh builder ZIP vs committed ZIP: unzip contents match; ZIP container bytes do not. Existing baseline behavior, not a DSH regression.',
+ zipContainerNote: 'Canonical Linux CI verifies ZIP container bytes; cross-platform DSH acceptance verifies extracted package content.',
stages: [],
};
@@ -413,8 +413,9 @@ const skipFreshZipRebuild = process.platform === 'win32';
const committedZip = path.join(repoRoot, 'archify.zip');
const packedSkill = path.join(inspectRoot, 'package', 'skills', 'archify');
let unzipContentsIdentical = false;
+let canonicalZipBytes = 'not-asserted';
if (skipFreshZipRebuild) {
- receipt.zipContainerNote = 'Fresh ZIP rebuild skipped on Windows (rsync/zip are not on GitHub Windows runners). Used committed archify.zip for content comparison; known text files normalize checkout CRLF while all other files remain byte-exact. ZIP container bytes are already known non-reproducible.';
+ receipt.zipContainerNote = 'Windows validates committed ZIP contents with checkout text EOL normalization; canonical container-byte reproduction is owned by Linux CI.';
const checkedDir = path.join(scratch, 'checked');
fs.mkdirSync(checkedDir);
fs.copyFileSync(committedZip, path.join(checkedDir, 'committed.zip'));
@@ -437,6 +438,12 @@ if (skipFreshZipRebuild) {
if (unzipDiff.status !== 0) {
fail('zero-regression', 'fresh ZIP contents drifted from the committed ZIP', { diff: unzipDiff.stdout });
}
+ if (process.platform === 'linux') {
+ if (!fs.readFileSync(freshZip).equals(fs.readFileSync(committedZip))) {
+ fail('zero-regression', 'canonical Linux ZIP bytes drifted from the committed archive');
+ }
+ canonicalZipBytes = 'verified';
+ }
unzipContentsIdentical = true;
}
const skillsList = run('npx', ['-y', 'skills', 'add', repoRoot, '--list', '--full-depth'], { cwd: repoRoot, timeout: 120_000 });
@@ -445,7 +452,8 @@ pass('zero-regression', {
archifyZipBlob: zipBlob.stdout.trim(),
archifyPackageBlob: pkgBlob.stdout.trim(),
unzipContentsIdentical,
- zipContainerBytesReproducible: false,
+ canonicalZipBytes,
+ crossPlatformZipCheck: 'extracted-content',
...(skipFreshZipRebuild ? { freshZipRebuildSkipped: true, checkoutTextEolNormalized: true } : {}),
skillsCli: skillsList.stdout.trim().slice(0, 500),
});
diff --git a/integrations/deepseek-harness/test/package-contract.test.mjs b/integrations/deepseek-harness/test/package-contract.test.mjs
index f9a08e15..5043ca34 100644
--- a/integrations/deepseek-harness/test/package-contract.test.mjs
+++ b/integrations/deepseek-harness/test/package-contract.test.mjs
@@ -80,3 +80,14 @@ test('distribution acceptance reserves stdout for its machine-readable JSON rece
assert.doesNotMatch(source, /stdio:\s*['"]inherit['"]/);
assert.equal([...source.matchAll(/process\.stdout\.write/g)].length, 2);
});
+
+test('distribution receipt separates canonical ZIP bytes from cross-platform content checks', () => {
+ const source = fs.readFileSync(
+ path.join(integrationRoot, 'scripts', 'distribution-acceptance.mjs'),
+ 'utf8',
+ );
+ assert.match(source, /canonicalZipBytes/);
+ assert.match(source, /crossPlatformZipCheck:\s*'extracted-content'/);
+ assert.doesNotMatch(source, /zipContainerBytesReproducible/);
+ assert.doesNotMatch(source, /rsync\/zip are not on GitHub Windows runners/);
+});
diff --git a/scripts/build-zip.sh b/scripts/build-zip.sh
index 127dd185..ad402bc1 100755
--- a/scripts/build-zip.sh
+++ b/scripts/build-zip.sh
@@ -9,9 +9,11 @@ if [[ "$out" != /* ]]; then
out="$(pwd)/$out"
fi
-# Stage only files tracked by Git. This keeps untracked working-tree content out
-# of the archive, and rejecting tracked paths that are symlinks prevents an
-# archive build from reading through links to content outside the repository.
+# Stage only files tracked by Git. Paths and modes come from the index, while
+# bytes intentionally come from the working tree so contributors can package
+# tracked edits before committing them. A conflicted index is never publishable.
+# Rejecting tracked paths that are symlinks prevents an archive build from
+# reading through links to content outside the repository.
# test/ is repo-only (the golden harness compares against ../examples at the
# repo root, which does not exist in an installed skill). The npm scripts and
# build-only dependencies are stripped from the shipped package.json. Runtime
@@ -27,6 +29,11 @@ while IFS= read -r -d '' record; do
metadata="${record%%$'\t'*}"
tracked="${record#*$'\t'}"
tracked_mode="${metadata%% *}"
+ tracked_stage="${metadata##* }"
+ if [[ "$tracked_stage" != 0 ]]; then
+ echo "refusing to package unmerged index entry (stage $tracked_stage): $tracked" >&2
+ exit 1
+ fi
case "$tracked" in
archify/test | archify/test/* | \
archify/package-lock.json | \
@@ -68,7 +75,6 @@ node -e "
"
rm -f "$stage/archify/package-lock.json"
-rm -f "$out"
node "$repo_root/scripts/write-deterministic-zip.mjs" "$stage/archify" "$out"
echo "built $out"
diff --git a/scripts/write-deterministic-zip.mjs b/scripts/write-deterministic-zip.mjs
index c9d6c319..d392a880 100644
--- a/scripts/write-deterministic-zip.mjs
+++ b/scripts/write-deterministic-zip.mjs
@@ -2,6 +2,7 @@
import fs from 'node:fs';
import path from 'node:path';
+import { randomBytes } from 'node:crypto';
import { constants as zlibConstants, deflateRawSync } from 'node:zlib';
const [rootArg, outputArg] = process.argv.slice(2);
@@ -16,6 +17,13 @@ const UTF8_FLAG = 0x0800;
const DEFLATE_METHOD = 8;
const DOS_TIME = 0;
const DOS_DATE = 0x0021; // 1980-01-01, the earliest ZIP timestamp.
+const ZIP32_MAX_ENTRIES = 0xffff;
+const ZIP32_MAX_NAME_BYTES = 0xffff;
+const ZIP32_MAX_VALUE = 0xffffffff;
+
+function requireZip32(condition, detail) {
+ if (!condition) throw new Error(`ZIP64 is not supported: ${detail}`);
+}
function crc32(buffer) {
let crc = 0xffffffff;
@@ -84,8 +92,10 @@ function centralHeader({ name, crc, compressedSize, uncompressedSize, offset, mo
const localParts = [];
const centralParts = [];
let offset = 0;
+const files = sortedEntries(root);
+requireZip32(files.length <= ZIP32_MAX_ENTRIES, `entry count ${files.length} exceeds ${ZIP32_MAX_ENTRIES}`);
-for (const file of sortedEntries(root)) {
+for (const file of files) {
const name = Buffer.from(`${path.basename(root)}/${file.relative}`, 'utf8');
const content = fs.readFileSync(file.absolute);
const compressed = deflateRawSync(content, {
@@ -93,6 +103,10 @@ for (const file of sortedEntries(root)) {
memLevel: 9,
strategy: zlibConstants.Z_FIXED,
});
+ requireZip32(name.length <= ZIP32_MAX_NAME_BYTES, `file name is too long: ${file.relative}`);
+ requireZip32(content.length <= ZIP32_MAX_VALUE, `file is too large: ${file.relative}`);
+ requireZip32(compressed.length <= ZIP32_MAX_VALUE, `compressed file is too large: ${file.relative}`);
+ requireZip32(offset <= ZIP32_MAX_VALUE, `local header offset is too large: ${file.relative}`);
const checksum = crc32(content);
const mode = fs.statSync(file.absolute).mode & 0o111 ? 0o755 : 0o644;
const local = localHeader({
@@ -118,10 +132,9 @@ for (const file of sortedEntries(root)) {
const centralOffset = offset;
const centralSize = centralParts.reduce((total, part) => total + part.length, 0);
-const entryCount = centralParts.length / 2;
-if (entryCount > 0xffff || centralOffset > 0xffffffff || centralSize > 0xffffffff) {
- throw new Error('ZIP64 is not supported by the deterministic package writer');
-}
+const entryCount = files.length;
+requireZip32(centralOffset <= ZIP32_MAX_VALUE, `central directory offset ${centralOffset} is too large`);
+requireZip32(centralSize <= ZIP32_MAX_VALUE, `central directory size ${centralSize} is too large`);
const end = Buffer.alloc(22);
end.writeUInt32LE(0x06054b50, 0);
@@ -133,5 +146,21 @@ end.writeUInt32LE(centralSize, 12);
end.writeUInt32LE(centralOffset, 16);
end.writeUInt16LE(0, 20);
-fs.writeFileSync(output, Buffer.concat([...localParts, ...centralParts, end]));
+const archive = Buffer.concat([...localParts, ...centralParts, end]);
+const temporary = path.join(
+ path.dirname(output),
+ `.${path.basename(output)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`,
+);
+let descriptor;
+try {
+ descriptor = fs.openSync(temporary, 'wx', 0o666);
+ fs.writeFileSync(descriptor, archive);
+ fs.fsyncSync(descriptor);
+ fs.closeSync(descriptor);
+ descriptor = undefined;
+ fs.renameSync(temporary, output);
+} finally {
+ if (descriptor !== undefined) fs.closeSync(descriptor);
+ fs.rmSync(temporary, { force: true });
+}
console.log(`built ${output} (${entryCount} files)`);