Skip to content
Trazum

1.9.1

The preflight

A release whose point is that the next one publishes itself. 1.8.0 and 1.9.0 both went out by hand — the first because the packages did not exist yet, the second because the trusted publisher had not been configured — so neither carries provenance. Nothing in the repository could tell you in advance which way a tag would go.

It can now, with one caveat stated in the entry below: the endpoint it asks is undocumented, so a refusal can be the check being wrong rather than the settings. It says so, and it never gates.

Fixed#

A token claim could have rearranged the summary it was written into. CodeQL's third finding on this script, and the same class as the first two: a value that arrives over the network reaching somewhere it can do more than be read. The job summary is rendered markdown, and the claims are decoded from a JWT fetched from the runner's token endpoint — so a claim carrying a backtick fence would close the code block it was meant to sit inside, and everything after it would render as page rather than as data.

A garbled summary is the mild version. One that reads as though it says something it does not is the reason to bother.

The first fix was the shallow one. Sanitising the claim strings addressed how they could rearrange a rendered document and left the plainer fact underneath: a value fetched over HTTP was being written to a file, and CodeQL said so again.

So the block does not quote the token any more. The values printed come from this run's own environment — GITHUB_REPOSITORY, GITHUB_WORKFLOW_REF — which is the authority on what this job is, while the token is a statement about it made elsewhere. The token is reduced to one computed word per field: agrees, DIFFERS, absent. A disagreement is still visible, which was the whole point, and nothing this process did not author reaches the file. The HTTP status in each verdict is narrowed to a known integer for the same reason.

It is also a better diagnosis. It prints what to type into npm rather than what the token happened to say, which is the question somebody reading a refusal actually has.

One value still slipped through: the HTTP status. rejected (${res.status}) put a number npm invented into a string that ends up in the file, and narrowing it to an integer was not enough — the flow is the finding, not the shape of the value. The status selects one of five labels this file chose, and the unknown case keeps its number on stdout only, because a status nobody can see is a dead end for whoever has to work out what happened, and a log is not a document this script is composing.

And a test was asserting one spelling of one payload. It checked the summary did not contain <script>, which CodeQL correctly called a bad filter: it would pass against <SCRIPT> and against everything else a hostile value could open. It asserts the property now — no markup characters in the summary at all — which is what the code guarantees.

The auth preflight asked about one package and reported on one package, and the first real run showed why that is not enough. It checked the first name alphabetically — @trazum/cli — on the reasoning that a misconfiguration is all-or-nothing. It is not. The trusted publisher is a setting on three separate pages, one per package, so configuring two of them is the easiest mistake available. And the release publishes @trazum/core first, so the package that actually stops a release need not be the one that was asked about.

It asks about every published package now and prints a line for each, so a partial configuration reads as one:

  configured            @trazum/cli
  rejected (404)        @trazum/core
  configured            @trazum/mcp

And "a claim does not match" now says which claim. That sentence names a category rather than a field and leaves the reader comparing four settings against nothing. On a refusal the step prints the four claims npm matches on — repository, workflow ref, environment, ref — beside the failure. environment: (absent) is the answer whenever it appears: the claim exists only when the job declares an environment, so an npm rule requiring release can never match a token without it.

The claims are an allow-list and the token itself is never printed. Those values are public metadata about the run; the token beside them is a bearer credential npm would accept, and a public log is forever. Two tests hold that line — one fails if the payload is dumped wholesale, one fails if the token is printed at all.

Added#

The release workflow can now tell you whether a tag will publish, before you push the tag. 1.9.0 was tagged, passed every check, and failed on the last step with E404 Not Found - PUT because the trusted publisher had not been configured. Nothing was published — but the tag was spent and the release went out by hand for the second time running, which means no provenance for the second time running.

Both of the things that went wrong were knowable in advance, and neither was checked. scripts/npm-publish-preflight.mjs asks them now.

Can this workflow authenticate? It puts a GitHub-signed OIDC token to npm's token-exchange endpoint — the same question the upload steps ask — and answers configured, rejected or could not verify. It runs on workflow_dispatch too, so a dry run finally settles this: before, a dry run proved the environment gate existed and nothing at all about npm, and the only way to test a trusted publisher was to spend a version number on it.

This one never fails the job, deliberately. The exchange endpoint is npm's own plumbing rather than a documented API, and a gate built on it would one day block a release that would have worked — worse than the failure it prevents. It reports; the upload is still the authority. A test pins that, because "it only warns" is the kind of property that quietly becomes "it fails on Tuesdays".

Is any of these versions already spent? npm never reuses a version, and the packages publish in dependency order, so the expensive shape is core uploading, the CLI failing, and core's number being gone. Checking all three against the public registry before the first upload turns that into a clean abort. This one does fail the job — it reads a documented API, and a version that already exists is not a maybe. An unreachable registry fails it too: not answering is not evidence a version is free.

And npm's 404 no longer names the wrong problem. Any publish failure now prints what E404 Not Found - PUT actually means, with the four fields to check and which one people leave blank. That diagnosis existed in docs/releasing.md and was no use to anyone who did not already know to look there.

All five guards are mutation-tested: reporting a taken version as free, treating an unreachable registry as free, making the auth check fail the job, dropping the version preflight from the workflow, and tag-gating the auth check so a dry run cannot answer it. Each one fails the suite.

CodeQL raised three alerts on the first version of it, and all three were right. Both halves of every URL here come out of a file, and a manifest is trusted by convention rather than by anything enforced — it is whatever is on disk when the release runs, and this script turns it into a request to a host that holds publish rights.

So the values are checked at the boundary now, on the same principle as checkedEndpoint in net.ts: a name that is not a package name and a version that is not a version stop the release rather than being sent to a registry to find out. Every URL is built through one helper that encodes its segments and then asserts the result is still on the registry's own origin — if a value ever did reach the path structure, the request does not leave rather than leaving for somewhere else.

The high-severity one was name.replace('/', '%2f'), which encodes the first slash and leaves any others. A scoped name has exactly one, so it worked; it is the same shape as the regex release-notes.mjs built out of a version string, and hand-rolled encoding that happens to be right is still hand-rolled encoding. encodeURIComponent now, verified against the live registry to accept the encoded @.

Putting the incomplete escape back fails no test, which is the honest outcome rather than a gap: the name validation makes the two forms equivalent for anything that reaches them, so a test failing on one would enforce a preference instead of a requirement. CodeQL is what guards it, and it runs on every pull request.

Changed#

The README's action pin advanced to the 1.9.0 commit, from a 1.0.0 commit it had been sitting on since that release. The pin can only move after the merge it names exists, which is why this is a separate change from the release that made it correct — security.test.js asks git what version the pinned commit declares in its own manifest, so a pin cannot be advanced in the commit it points at, and cannot be labelled with a version that commit does not carry.