How-to › Release and secure packages

How to verify a generated SDK is reproducible from its spec#

Build one commit twice in empty directories, compare what each would publish by hash, and name the field that varied, so a consumer can rebuild the SDK and check it.

Audience
API producer
Level
advanced
Topic
Secure the supply chain
Languages
TypeScript and Go
Verified

Read first: Generate an SBOM for a generated SDK

A consumer checks out the tag of your SDK, runs the build, and gets a tarball whose SHA-256 is not the one on npm. Nothing on the release says which generator, compiler, or packaging step made the published file, so the package is a binary nobody but your CI can vouch for.

What you get

You will end up with two clean builds of one commit, a hash comparison of what each would publish, and a tool that names the varying field when the hashes differ. This is for you if you publish generated SDKs and want consumers to rebuild them.

Short answer

Pin the generator, the toolchain, and the lockfiles, record them beside the release, and build the commit twice in empty directories. Compare the tarball hashes, and the h1 hash for a Go module. Two sdkgen builds a minute apart gave byte-identical npm tarballs and Go trees, and so did Hey API’s client. A mismatch is most often the packaging step: plain tar records each file’s modification time.

You will need

An SDK generated from an OpenAPI 3 document, Node 22 or later, and GNU tar and gzip, which pack.mjs runs. The document here is the five-operation Bookshelf API. record.sh made the two builds and ran diffoscope once, and the page’s commands read what it committed under builds/, so nothing is generated or downloaded when they run.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
diffoscope on a mismatchTwo artifacts differ and you need the field that movedA Python tool whose site advises installing external tools for meaningful results, all in your CI imageThe hashes already match
Fern fern.config.json and generatorVersion pinsFern generates the SDK and you pin the CLI and every target’s generatorSelf-hosted generation is an Enterprise feature, so a build on a runner you own needs that planYou want both builds on runners you own
Hey API exact version pinA TypeScript client from @hey-api/openapi-ts, pinned with -EIts postProcess tools run from your project, so their versions are inputs tooYou need clients in more than TypeScript
npm provenance attestationYou publish from GitHub Actions or GitLab CI/CD and want the source commit on the packageIt names the build, but proves nothing about whether a rebuild matchesA consumer wants to rebuild and compare
sdkgen deterministic generationAn sdkgen SDK, where one model feeds a TypeScript and a Go targetRanges in the generated ts/package.json, so the compiler floats until you commit a lockfileA generator you already run passes the same check

Voxgig maintains sdkgen, one of the five rows in the table, and this page does not rank it over the other four.

Pins and an attestation record what a build should use, and the two-build hash shows what it produced. The pins are cheap and come first. diffoscope costs an install and earns it on the first mismatch. Provenance pairs well with all of them, and replaces none.

Build the same commit twice from empty directories

record.sh runs each build in a fresh temporary directory, a minute apart, so the files of the second build carry other modification times. The generator and the client generator are pinned on the command line, and .sdk/package-lock.json, which the scaffold writes, pins the toolchain behind them.

    npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target ts --target go > scaffold.log 2>&1
    (cd bookshelf-sdk/.sdk && npm ci --no-audit --no-fund > /dev/null 2>&1 && npm run generate > /dev/null 2>&1)
    (cd bookshelf-sdk/ts && npm install --no-audit --no-fund > /dev/null 2>&1 && npm run build > /dev/null 2>&1)
    (cd bookshelf-sdk/ts && npm pack --silent --pack-destination "$dir" > /dev/null)
    npx --yes -p typescript@5.9.3 -p @hey-api/openapi-ts@0.99.0 openapi-ts -i api.json -o heyapi > /dev/null 2>&1

Each build also writes the versions it ran and the hash of the toolchain’s lockfile. Publish that file with the release, so a consumer knows what to install before rebuilding.

{
  "node": "v22.23.5",
  "@voxgig/create-sdkgen": "0.31.9",
  "@voxgig/sdkgen": "4.44.3",
  "@voxgig/apidef": "8.32.4",
  "typescript": "5.9.3",
  "@hey-api/openapi-ts": "0.99.0",
  "sdk package-lock.json sha256": "9ad5433fcffd85d5d3b1afe465fa5d3c35f95d2c3442a85c8236210b102abaf3"
}

Compare what each build would publish

Compare the file you publish, not the tree it came from. compare.mjs reads both tarballs entry by entry, and exits 1 when their bytes differ.

node compare.mjs builds/a/bookshelf-sdk-0.0.1.npm.tar.gz builds/b/bookshelf-sdk-0.0.1.npm.tar.gz
builds/a/bookshelf-sdk-0.0.1.npm.tar.gz: 210 entries, sha256 e5a8391b2c6d839f5058ab5a82347b34713809d7908009fe1e8382468b0929b7
builds/b/bookshelf-sdk-0.0.1.npm.tar.gz: 210 entries, sha256 e5a8391b2c6d839f5058ab5a82347b34713809d7908009fe1e8382468b0929b7
same bytes: yes

A minute apart, the two tarballs are the same 210 entries and the same hash. sdkgen’s documentation says that generating again from the same model gives byte-stable output, and this run bears it out for the packaged artifact as well as the tree.

A Go module has no tarball to compare. Consumers check it against the h1 hash in go.sum, which dirhash computes from filenames and contents only, so no mtime or owner goes in. manifests.mjs computes it from each build’s manifest and checks it against the hash Go’s own package wrote.

node manifests.mjs
heyapi.sha256  build a 16 files, build b 16, identical 16, in one only 0
go.sha256      build a 82 files, build b 82, identical 82, in one only 0
go module, build a: h1:hEJScSR0hl95/qOl8neHqoWnL+hGZ5RwepxaXu6aSx8=, the same as Go's dirhash wrote: yes
go module, build b: h1:hEJScSR0hl95/qOl8neHqoWnL+hGZ5RwepxaXu6aSx8=, the same as Go's dirhash wrote: yes

Find what varied when the hashes differ

The generator is rarely the cause. The 16 files of the Hey API client, with a package.json beside them and checked out twice an hour apart, give three different results depending on how they are packed.

node pack.mjs
the same Hey API client, checked out twice an hour apart, packed three ways
  tar -czf, as it comes         differ: mtime in 20 entries
  tar normalized, then gzip -n  same bytes
  npm pack                      same bytes

Plain tar writes each file’s mtime into its header, and diffoscope, run once by record.sh, shows exactly that:

--- client-1.tar.gz
+++ client-2.tar.gz
│   --- client-1.tar
├── +++ client-2.tar
│ ├── file list
│ │ @@ -1,19 +1,19 @@
│ │ -drwxr-xr-x   0 root         (0) root         (0)        0 2026-11-21 10:00:00.000000 client/

The fix is the one the Reproducible Builds archive guide gives: sort the entries, set one mtime from SOURCE_DATE_EPOCH, drop the owner, and tell gzip not to store a name or time.

    const tarball = execFileSync('tar', [
      '--sort=name',
      `--mtime=@${SOURCE_DATE_EPOCH}`,
      '--owner=0',
      '--group=0',
      '--numeric-owner',
      '--format=gnu',

npm pack needed no fix. npm 10.9.9 dated every entry 1985-10-26 and wrote owner 0, whatever the files carried.1

Run the same check on Fern and Hey API

Hey API ran here, twice, and its 16 files matched. Its get started page asks you to pin an exact version, because the package is in initial development. Its output options empty the output folder on every run, and postProcess runs tools such as prettier or biome over it afterwards. Those commands run whatever version your environment provides, so pin them in the same lockfile.

Fern was not run. Its fern generate reference generates on Fern’s cloud after a login, on a guest session, or with --local in Docker or Podman. In the sdk-config.yml format, targets run the newest generator unless you pin one. The reference calls targets[].generatorVersion “the exact generator version used for this target” in its entry. The project structure page says that pinning the CLI version in fern.config.json provides deterministic builds. Fern’s self-hosted versioning page shows each generated SDK recording cliVersion, generatorVersion, and originGitCommit in .fern/metadata.json, the inputs file this page writes by hand. The self-hosted page marks --local generation as an Enterprise feature.

Check it worked

The suite checks the two committed builds, packs the client three ways, and tests that the comparison catches what it should.

test('the comparison names a one-byte change in one entry', (t) => {
  const dir = scratch(t)
  for (const n of [1, 2]) {
    mkdirSync(join(dir, `b${n}`, 'client'), { recursive: true })
    writeFileSync(join(dir, `b${n}`, 'client', 'a.ts'), 'export const a = 1\n')
    writeFileSync(join(dir, `b${n}`, 'client', 'b.ts'), `export const b = ${n}\n`)
    STEPS['tar normalized, then gzip -n'](join(dir, `b${n}`, 'client'), join(dir, `out${n}.tar.gz`))
  }
  const d = diffTarballs(readTarball(join(dir, 'out1.tar.gz')), readTarball(join(dir, 'out2.tar.gz')))
  assert.equal(d.same, false)
  assert.deepEqual(d.differ, { sha256: 1 })
})
node --test repro.test.mjs | tail -8
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1316.255845

When it goes wrong

The hashes differ even though every file’s content matches. The archive carries modification times, an owner, or directory order. Run compare.mjs, or diffoscope, to name the field, then fix the packaging step, not the generator.

A rebuild months later differs where a rebuild the next minute did not. The generated ts/package.json asks for typescript ^5.9.3, and the generator writes no lockfile for it. Commit the package-lock.json the first npm install writes, and build with npm ci.

The release is signed, but a rebuild still differs. A signature or a provenance statement says who built the file and from which commit. It does not say that the file is what the commit builds, which is the question the two-build check answers.2

When not to do this

Do not stop at two runs on one machine. They share a kernel, a filesystem, and a host name, so a difference in any of the three cannot show. Put the second build on another runner image before you promise consumers a match.

Reproducibility alone is no reason to move to sdkgen. Hey API passed the same check on its TypeScript client with one pin, and it is the smaller adoption for a TypeScript-only SDK. Fern records its inputs in .fern/metadata.json without a script of yours, which suits a team that already generates on Fern’s cloud.

Do not carry this result over to an SDK a coding agent writes. The two builds here are two runs of fixed generators, and this page measured no agent run. Run the same comparison on two agent runs from one prompt before you publish either.

Last verified

Verified 2026-11-21 against Node 22.23.5, npm 10.9.9, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @hey-api/openapi-ts 0.99.0, golang.org/x/mod v0.30.0, GNU tar 1.35, and Go 1.24.7. Every output block is what the command preceding it printed. Both builds ran in one sandbox, one minute apart. diffoscope 339 ran once, inside record.sh, so the commands on the page do without it. Fern’s part comes from its sdk-config.yml reference, its fern generate reference, and its project structure and self-hosting pages, read but not run.

Footnotes

  1. The date is set in pacote, the library npm packs with. Its source gives every entry 1985-10-26T08:15:00Z. The comment beside it asks for a date in the 1980s because zip “is confounded by files dated at the Unix epoch 0” otherwise. The same options force gzip level 9, which, the comment says, seems to avoid some platform-specific optimizations that cause integrity mismatch errors. ↩︎ Back to text

  2. npm’s provenance page says a provenance statement lets you publicly establish where a package was built and who published it. Both are facts about the publishing run, while a consumer who rebuilds is asking about the bytes. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.