# How Archify Ensures Reproducible Builds Without External Dependencies

> Archify guarantees reproducible builds using Node.js core modules for byte-for-byte identical ZIP archives. Eliminate external dependencies and ensure consistent output across all environments.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-30

---

**Archify achieves fully reproducible builds by generating deterministic ZIP archives using only Node.js core modules, ensuring byte-for-byte identical output regardless of environment, timezone, or operating system.**

The tt-a1i/archify repository demonstrates how to build portable software artifacts without relying on external build tools or package managers. By implementing a custom deterministic ZIP generator that uses only Node.js standard library modules, Archify guarantees that every build produces identical binary output. This approach enables cryptographic verification and trustworthy distribution across heterogeneous environments.

## Core Deterministic ZIP Implementation

At the heart of Archify’s reproducibility guarantee sits `scripts/write-deterministic-zip.mjs`, a purpose-built archive generator that eliminates every source of non-determinism inherent in conventional ZIP utilities.

### Normalized Metadata and Timestamps

The deterministic writer eliminates timestamp variability by setting a **fixed DOS timestamp of `1980-01-01`** for every entry in the archive. Entries are sorted alphabetically before processing to ensure consistent ordering, and the script writes both local file headers and the central directory using identical metadata for every build.

Compression strategy is locked to **`Z_FIXED`** in Node.js’s zlib module, preventing compression algorithm variations from affecting output. CRC32 checksums are computed manually using Node’s `crypto` module rather than relying on platform-specific implementations, ensuring the same input bytes always produce the same archive structure.

### Zero External Runtime Dependencies

`scripts/write-deterministic-zip.mjs` imports only four Node.js core modules: `fs`, `path`, `crypto`, and `zlib`. This constraint means the build pipeline runs on any **Node.js ≥ 18** environment without executing `npm install` or pulling third-party packages. By avoiding external binaries, the system eliminates variability introduced by different `zip` utility versions across macOS, Linux, or Windows environments.

## Build Scripts Without System Dependencies

The [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) wrapper script provides a thin abstraction over the deterministic writer. Unlike conventional build pipelines that invoke the system `zip` command or require build-time dependency resolution, this script directly executes `write-deterministic-zip.mjs` to package the skill.

Because the entire pipeline operates without external tools, Archify delivers a **"no-install" build path**. The shell script never calls `npm install`, `git archive`, or platform-specific packaging utilities, guaranteeing that the only requirement for generating a release artifact is a standard Node.js runtime.

## CI Gating and Reproducibility Verification

Reproducibility is enforced programmatically in `archify/test/release-package-gates.test.mjs`, which implements strict validation gates that must pass before any release.

### Cross-Timezone Byte-For-Byte Validation

The test suite specifically validates that **"archive build is byte-for-byte reproducible across caller time zones without system zip"**. The CI pipeline builds the archive twice—once with `TZ=UTC` and once with `TZ=Pacific/Honolulu`—then asserts that the resulting files are identical using byte-level comparison. This proves that the fixed timestamp implementation successfully neutralizes timezone-related variability.

### Canonical Archive Integrity

Beyond cross-timezone validation, the same test verifies that the freshly built archive matches the committed `archify.zip` stored in the repository. This check ensures that no uncommitted changes or environment-specific artifacts have contaminated the build output, creating a cryptographic chain of trust between source code and distributed binary.

### Strict Content Boundaries

The builder refuses to include files that could introduce non-determinism or security risks. As validated by the "archive build excludes untracked files and external symlinks" test, the generator halts if it encounters:
- Untracked files (ensuring only committed content is packaged)
- External symlinks (preventing file system traversal outside the repository)
- Conflicted git index entries (blocking builds with unresolved merge states)

These safety checks guarantee that the archive contains exactly the repository-tracked content, nothing more and nothing less.

## Generating Reproducible Archives Locally

You can verify Archify’s reproducibility guarantees on your local machine using the deterministic writer directly.

Generate a reproducible ZIP from the repository root:

```bash
node scripts/write-deterministic-zip.mjs archify archify.zip

```

The resulting `archify.zip` will be byte-identical to the repository’s committed archive. To explicitly test timezone independence:

```bash

# Build in UTC

TZ=UTC node scripts/write-deterministic-zip.mjs archify utc.zip

# Build in Honolulu time

TZ=Pacific/Honolulu node scripts/write-deterministic-zip.mjs archify honolulu.zip

# Verify identical output

cmp -s utc.zip honolulu.zip && echo "✅ reproducible"

```

For standard packaging without any dependency installation:

```bash
scripts/build-zip.sh archify.zip

```

This produces `archify.zip` containing only tracked files and the embedded notifier runtime, suitable for distribution.

## Summary

- **Deterministic ZIP generation**: `scripts/write-deterministic-zip.mjs` creates archives with fixed timestamps (`1980-01-01`), sorted entries, and `Z_FIXED` compression to guarantee identical output.
- **Zero external dependencies**: The build uses only Node.js core modules (`fs`, `path`, `crypto`, `zlib`) and runs on Node ≥ 18 without `npm install` or system `zip` binaries.
- **CI-enforced reproducibility**: `archify/test/release-package-gates.test.mjs` validates byte-for-byte identity across timezones and against the canonical committed archive.
- **Content sanitization**: The builder excludes untracked files, external symlinks, and conflicted index entries to ensure hermetic builds.
- **Cross-platform consistency**: Identical archive bytes are produced regardless of operating system, timezone, or build environment.

## Frequently Asked Questions

### Why does Archify use 1980-01-01 as the fixed timestamp?

Archify uses the DOS epoch date of `1980-01-01` because it is the earliest valid timestamp in the ZIP file format specification. By fixing all entries to this specific date, the system eliminates modification-time variability that would otherwise cause different archive hashes across builds, while remaining compliant with ZIP standards.

### Can I run the build without installing npm dependencies?

Yes. Because `scripts/write-deterministic-zip.mjs` imports only Node.js built-in modules and [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) invokes it directly, you can generate `archify.zip` on any system with Node.js ≥ 18 installed without running `npm install` or downloading external packages.

### How does Archify prevent non-deterministic content from entering the archive?

The deterministic writer in `scripts/write-deterministic-zip.mjs` performs strict safety checks validated by `archify/test/release-package-gates.test.mjs`. It refuses to package untracked files, external symlinks, or repositories with conflicted git index entries, ensuring that only the exact committed state of the repository is archived.

### What Node.js version is required for reproducible builds?

Archify requires **Node.js 18 or higher**. The build script relies on modern Node.js standard library APIs, particularly the `zlib` module’s `Z_FIXED` compression strategy and the `crypto` module’s CRC32 capabilities, which are stable and consistent across all supported Node.js versions.