From 2eef4817154056c456463dc7bb74babc684bda94 Mon Sep 17 00:00:00 2001 From: Dijo S Benelen Date: Sun, 8 Nov 2026 22:33:55 +0530 Subject: [PATCH 1/2] Mirror 1.0.0 to GitHub Packages without rebuilding it GitHub's npm registry accepts only owner-scoped names, so disktop@1.0.0 is mirrored as @dijo-404/disktop@1.0.0. The mirror is the published npm tarball, checked against its audited SHA-256 and the registry's SHA-512, with only the name line of package.json changed; every other entry is proven byte- and mode-identical before anything is published. mirror-github-packages.yml runs a read-only prepare job on pull requests and on dispatch: download, derive, compare, install into a clean prefix and scan with the packaged helper. The publish job runs only when dispatched from main with the confirmation text, behind the protected npm-publish environment. It attests the file, publishes it with GITHUB_TOKEN, and verifies a clean install from GitHub Packages against the same digest. The manifest's repository field links the package. The tarball reader and workflow-block helper move to shared modules so the package test, release contract and mirror use one implementation. --- .github/ISSUE_TEMPLATE/test_result.yml | 2 +- .github/workflows/mirror-github-packages.yml | 173 +++++++++++++++++++ AGENTS.md | 2 +- CONTRIBUTING.md | 35 ++++ docs/release-readiness.md | 20 +++ scripts/mirror-github-package.mjs | 137 +++++++++++++++ scripts/tarball.mjs | 34 ++++ tests/package/package.test.mjs | 33 +--- tests/support/workflows.mjs | 11 ++ tests/unit/github-packages-mirror.test.mjs | 158 +++++++++++++++++ tests/unit/release-contract.test.mjs | 11 +- 11 files changed, 572 insertions(+), 44 deletions(-) create mode 100644 .github/workflows/mirror-github-packages.yml create mode 100644 scripts/mirror-github-package.mjs create mode 100644 scripts/tarball.mjs create mode 100644 tests/support/workflows.mjs create mode 100644 tests/unit/github-packages-mirror.test.mjs diff --git a/.github/ISSUE_TEMPLATE/test_result.yml b/.github/ISSUE_TEMPLATE/test_result.yml index fe25f72..3a03b0c 100644 --- a/.github/ISSUE_TEMPLATE/test_result.yml +++ b/.github/ISSUE_TEMPLATE/test_result.yml @@ -35,7 +35,7 @@ body: id: version attributes: label: Version and artifact identity - description: Include disktop --version and the installation method. For source or CI builds give the exact commit; for a tarball give its SHA-256. Identify the npm package version when installed from the registry. + description: Include disktop --version and the installation method. For source or CI builds give the exact commit; for a tarball give its SHA-256. When installed from a registry, name the package and version (disktop from npm, or @dijo-404/disktop from GitHub Packages). validations: required: true - type: textarea diff --git a/.github/workflows/mirror-github-packages.yml b/.github/workflows/mirror-github-packages.yml new file mode 100644 index 0000000..285c768 --- /dev/null +++ b/.github/workflows/mirror-github-packages.yml @@ -0,0 +1,173 @@ +name: Mirror 1.0.0 to GitHub Packages + +# Builds nothing and publishes nothing to npmjs.org. GitHub's npm registry +# accepts only owner-scoped names, so `disktop@1.0.0` is mirrored there as +# `@dijo-404/disktop@1.0.0`: the exact published tarball, checked against its +# audited SHA-256 and the registry's SHA-512, with the name line of its +# package.json changed and every other byte proven unchanged. The manifest's +# repository field links the package to this repository. +# +# A pull request runs `prepare` only. Publication is manual: dispatch from main +# with the confirmation text, then approve the npm-publish environment. GitHub +# Packages refuses a version that already exists, so a rerun cannot replace it. +on: + pull_request: + paths: + - .github/workflows/mirror-github-packages.yml + - scripts/mirror-github-package.mjs + - scripts/tarball.mjs + - scripts/verify-registry-release.mjs + workflow_dispatch: + inputs: + confirmation: + description: Type MIRROR 1.0.0 to publish @dijo-404/disktop@1.0.0 to GitHub Packages + required: true + type: string + +permissions: + contents: read + +concurrency: + group: disktop-github-packages-mirror + cancel-in-progress: false + +env: + EXPECTED_COMMIT: 3d6448560d19d75b27fce75765819d89f36be09e + EXPECTED_SHA256: a2deddd76c137e349370fb839b887baff14b3ec27c649f1ce809616bf8b39acd + +jobs: + prepare: + name: Derive and smoke test the mirror artifact + if: github.repository == 'Dijo-404/disktop' + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + outputs: + sha256: ${{ steps.mirror.outputs.sha256 }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: '24' + package-manager-cache: false + - name: Download the exact published npm artifact + run: node scripts/verify-registry-release.mjs download "$RUNNER_TEMP/npm" + - name: Rename the package and prove nothing else changed + id: mirror + run: | + set -euo pipefail + node scripts/mirror-github-package.mjs pack "$RUNNER_TEMP/npm/disktop-1.0.0.tgz" "$RUNNER_TEMP/mirror" | tee -a "$GITHUB_OUTPUT" + - name: Install the mirror into a clean prefix and scan with its helper + env: + ARCHIVE: ${{ runner.temp }}/mirror/dijo-404-disktop-1.0.0.tgz + run: | + set -euo pipefail + consumer="$RUNNER_TEMP/consumer" + mkdir -p "$consumer/home" "$consumer/tree" + npm install --global --prefix "$consumer/prefix" --ignore-scripts --no-audit --no-fund "$ARCHIVE" + disktop() { + env HOME="$consumer/home" XDG_CONFIG_HOME="$consumer/home/config" XDG_DATA_HOME="$consumer/home/data" \ + XDG_CACHE_HOME="$consumer/home/cache" XDG_STATE_HOME="$consumer/home/state" \ + "$consumer/prefix/bin/disktop" "$@" + } + test "$(disktop --version)" = '1.0.0' + disktop --help > /dev/null + printf 'disktop\n' > "$consumer/tree/file" + disktop scan "$consumer/tree" --json > "$consumer/scan.json" + node -e 'const r = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")); if (r.status !== "complete" || r.exitCode !== 0) throw new Error("scan returned " + r.status);' "$consumer/scan.json" + - name: Confirm the mirror artifact is unchanged + env: + SHA256: ${{ steps.mirror.outputs.sha256 }} + working-directory: ${{ runner.temp }}/mirror + run: echo "$SHA256 dijo-404-disktop-1.0.0.tgz" | sha256sum --check --strict + - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: disktop-github-packages + path: ${{ runner.temp }}/mirror/dijo-404-disktop-1.0.0.tgz + if-no-files-found: error + retention-days: 30 + + publish: + name: Publish @dijo-404/disktop@1.0.0 + needs: prepare + if: >- + ${{ github.event_name == 'workflow_dispatch' && + github.repository == 'Dijo-404/disktop' && + github.ref_name == github.event.repository.default_branch && + inputs.confirmation == 'MIRROR 1.0.0' }} + runs-on: ubuntu-24.04 + timeout-minutes: 20 + environment: npm-publish + permissions: + contents: read + packages: write + id-token: write + attestations: write + steps: + # Only the script that checks the clean install; nothing from the + # repository is installed or run before publication. + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + sparse-checkout: | + scripts/mirror-github-package.mjs + scripts/tarball.mjs + sparse-checkout-cone-mode: false + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: '24' + registry-url: https://npm.pkg.github.com + scope: '@dijo-404' + package-manager-cache: false + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: disktop-github-packages + path: ${{ runner.temp }}/mirror + - name: Require the artifact prepare checked + env: + SHA256: ${{ needs.prepare.outputs.sha256 }} + working-directory: ${{ runner.temp }}/mirror + run: echo "$SHA256 dijo-404-disktop-1.0.0.tgz" | sha256sum --check --strict + # npm provenance is an npmjs.org feature; a GitHub artifact attestation + # binds the mirror's digest to this workflow run instead. + - uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 + with: + subject-path: ${{ runner.temp }}/mirror/dijo-404-disktop-1.0.0.tgz + - name: Publish the mirror to GitHub Packages + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + ARCHIVE: ${{ runner.temp }}/mirror/dijo-404-disktop-1.0.0.tgz + run: npm publish "$ARCHIVE" --ignore-scripts + - name: Verify the published mirror from a clean install + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + ARCHIVE: ${{ runner.temp }}/mirror/dijo-404-disktop-1.0.0.tgz + SHA256: ${{ needs.prepare.outputs.sha256 }} + run: | + set -euo pipefail + # Newly published metadata can lag the upload. Retry only this read: + # publication above must never be repeated by this loop. + for attempt in $(seq 1 32); do + if version="$(npm view @dijo-404/disktop@1.0.0 version --fetch-retries=0 --fetch-timeout=10000)"; then + test "$version" = '1.0.0' + break + fi + if [ "$attempt" -eq 32 ]; then + echo '::error::@dijo-404/disktop@1.0.0 remained unavailable after 32 registry checks.' + exit 1 + fi + echo "GitHub Packages metadata is not available yet; retry $attempt of 32 in 10 seconds." + sleep 10 + done + check="$RUNNER_TEMP/mirror-check" + mkdir -p "$check/download" "$check/consumer" + npm pack @dijo-404/disktop@1.0.0 --ignore-scripts --pack-destination "$check/download" + echo "$SHA256 $check/download/dijo-404-disktop-1.0.0.tgz" | sha256sum --check --strict + cd "$check/consumer" + printf '%s\n' '{"name":"disktop-mirror-verification","private":true,"version":"1.0.0"}' > package.json + npm install --ignore-scripts --save-exact --no-audit --no-fund @dijo-404/disktop@1.0.0 + node "$GITHUB_WORKSPACE/scripts/mirror-github-package.mjs" installed "$ARCHIVE" "$check/consumer" + test "$("$check/consumer/node_modules/.bin/disktop" --version)" = '1.0.0' diff --git a/AGENTS.md b/AGENTS.md index 56a3844..4d84455 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Agent guide for Disktop -Read [PLAN.md](PLAN.md) before implementation. It is the product scope, target folder structure, interface map, phase gates, and acceptance checklist. **Phases 0 through 8 are complete under the release owner's dated manual-check deferral; `1.0.0` is published and independently verified.** The [release record](docs/release-readiness.md) identifies the immutable tag/artifact, the original workflow's registry-check failure and subsequent successful verification. Never move `v1.0.0`, rebuild its published artifact or republish that version. The contracts are normative and enforced: +Read [PLAN.md](PLAN.md) before implementation. It is the product scope, target folder structure, interface map, phase gates, and acceptance checklist. **Phases 0 through 8 are complete under the release owner's dated manual-check deferral; `1.0.0` is published and independently verified.** The [release record](docs/release-readiness.md) identifies the immutable tag/artifact, the original workflow's registry-check failure and subsequent successful verification. Never move `v1.0.0`, rebuild its published artifact or republish that version. The GitHub Packages mirror `@dijo-404/disktop@1.0.0` is not a rebuild: `scripts/mirror-github-package.mjs` takes the published npm tarball, changes only its package name, and proves the rest unchanged; `.github/workflows/mirror-github-packages.yml` publishes it once, behind the same protected environment. The contracts are normative and enforced: `schemas/cli/v1/` and `schemas/native/v1/` define public JSON and the helper protocol, `src/domain/paths.ts` and `src/domain/protected-paths.ts` define path bytes and the refusal policy, `src/storage/` defines configuration, `eslint.config.mjs` enforces the dependency rule, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0fa3bc3..f7ec306 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -183,6 +183,41 @@ Publication records are maintained in repository documentation after release. They do not modify the tagged source or published package. Keep every deferred environment unvalidated until a tester supplies the evidence described in the guide. +### Mirror 1.0.0 to GitHub Packages + +`mirror-github-packages.yml` publishes `@dijo-404/disktop@1.0.0`, which is the npm +tarball with only its package name changed. The +[release record](docs/release-readiness.md#github-packages-mirror) describes what it +checks. Pull requests that touch the workflow or its scripts run its read-only +`prepare` job. Publishing it takes three steps: + +1. Dispatch it from `main`: + + ```sh + gh workflow run mirror-github-packages.yml --ref main -f confirmation='MIRROR 1.0.0' + ``` + +2. Approve the `npm-publish` deployment. The job reads no npm secret. It publishes + with the repository's `GITHUB_TOKEN`, then installs the mirror from GitHub + Packages and requires the same digest. +3. GitHub makes a newly published package **private**. For anyone to install it, + open the package's settings, choose **Change visibility** and select + **Public**. GitHub cannot make a public package private again. + +GitHub Packages refuses a version that already exists, so a rerun cannot replace +the mirror. Do not delete and republish it. Installing needs a token even for a +public package: a personal access token (classic) with `read:packages`, entered +as the password here: + +```sh +npm login --scope=@dijo-404 --auth-type=legacy --registry=https://npm.pkg.github.com +npm install -g @dijo-404/disktop@1.0.0 +gh attestation verify dijo-404-disktop-1.0.0.tgz --repo Dijo-404/disktop +``` + +The last command checks a downloaded copy of the mirror tarball. Get the copy +with `npm pack @dijo-404/disktop@1.0.0`. + ## Tests that need a second filesystem `disktop clean plan --operation move` refuses a destination on the source's own diff --git a/docs/release-readiness.md b/docs/release-readiness.md index e35eae8..e963428 100644 --- a/docs/release-readiness.md +++ b/docs/release-readiness.md @@ -42,6 +42,26 @@ These are postrelease repository records. The tagged source and npm tarball reta their original documentation; later documentation commits neither move `v1.0.0` nor replace its artifact. See [the publication record and verification procedure](../CONTRIBUTING.md#publish-100). +## GitHub Packages mirror + +GitHub's npm registry accepts only owner-scoped names, so `disktop@1.0.0` is mirrored +there as `@dijo-404/disktop@1.0.0` by +[`mirror-github-packages.yml`](../.github/workflows/mirror-github-packages.yml). The +mirror is neither a rebuild nor a new release. The workflow downloads the published +tarball, requires the audited SHA-256 above and the registry's SHA-512, and changes +only the `name` line of its `package.json`. +[`scripts/mirror-github-package.mjs`](../scripts/mirror-github-package.mjs) refuses the +result unless every other entry keeps its bytes and mode. The workflow then installs +that file into a clean prefix and scans with its packaged helper. Only after these +checks does the protected `npm-publish` job attest the file and publish it with the +repository's `GITHUB_TOKEN`. The unchanged `repository` field links the package to +this repository. GitHub Packages has no npm provenance, so a GitHub artifact +attestation binds the mirror's digest to the publishing run. + +| Evidence | Recorded result | +| --- | --- | +| Mirror publication | **Not yet published.** The run, mirror digest, attestation and package visibility are recorded here once the protected job has run. | + ## Executed gates | Gate | Result | diff --git a/scripts/mirror-github-package.mjs b/scripts/mirror-github-package.mjs new file mode 100644 index 0000000..c98294c --- /dev/null +++ b/scripts/mirror-github-package.mjs @@ -0,0 +1,137 @@ +/** + * The GitHub Packages mirror of the published npm release. Never builds. + * + * GitHub's npm registry accepts only packages scoped to their owner, so + * `disktop@1.0.0` is mirrored there as `@dijo-404/disktop@1.0.0`: the exact + * tarball npm serves, with the `name` line of its package.json changed and + * nothing else. `pack` makes that tarball from the published one and proves + * every other entry is byte-for-byte unchanged; `installed` checks that a clean + * install resolved the mirror from GitHub Packages with that tarball's digest. + * Publishing is `.github/workflows/mirror-github-packages.yml`'s protected job. + */ +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { chmod, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { pathToFileURL } from "node:url"; +import { readTarball } from "./tarball.mjs"; + +export const SOURCE_NAME = "disktop"; +export const MIRROR_NAME = "@dijo-404/disktop"; +export const VERSION = "1.0.0"; +export const MIRROR_ARCHIVE = "dijo-404-disktop-1.0.0.tgz"; +/** The audited `disktop-1.0.0.tgz` npm serves; see docs/release-readiness.md. */ +export const PUBLISHED_SHA256 = "a2deddd76c137e349370fb839b887baff14b3ec27c649f1ce809616bf8b39acd"; +const MIRROR_ORIGIN = "https://npm.pkg.github.com"; +const MANIFEST = "package/package.json"; +const NAME_LINE = /^ {2}"name": "disktop",$/gm; + +const digest = (algorithm, bytes, encoding) => createHash(algorithm).update(bytes).digest(encoding); + +/** The published package.json text with only its name line changed. */ +export function mirrorManifest(text) { + const manifest = JSON.parse(text); + assert.equal(manifest.name, SOURCE_NAME, "the source must be the published disktop package"); + assert.equal(manifest.version, VERSION, "only the published 1.0.0 is mirrored"); + assert.equal(text.match(NAME_LINE)?.length, 1, "the manifest must have exactly one top-level name line"); + const mirrored = text.replace(NAME_LINE, ` "name": "${MIRROR_NAME}",`); + assert.deepEqual(JSON.parse(mirrored), { ...manifest, name: MIRROR_NAME }); + return mirrored; +} + +function byName(entries, label) { + const map = new Map(); + for (const entry of entries) { + assert.equal(entry.type, "0", `${label} ${entry.name} is not a regular file`); + assert.ok(!map.has(entry.name), `${label} repeats ${entry.name}`); + map.set(entry.name, entry); + } + return map; +} + +/** Refuses a mirror whose entries differ from the published ones anywhere but the name line. */ +export function compareMirror(published, mirror) { + const source = byName(published, "the published tarball"); + const copy = byName(mirror, "the mirror"); + assert.ok(source.has(MANIFEST), "the published tarball has no package.json"); + assert.deepEqual([...copy.keys()].sort(), [...source.keys()].sort(), "the mirror must hold exactly the published files"); + for (const [name, entry] of source) { + const other = copy.get(name); + assert.equal(other.mode, entry.mode, `${name} changed mode`); + const expected = name === MANIFEST ? Buffer.from(mirrorManifest(entry.data.toString("utf8"))) : entry.data; + assert.ok(other.data.equals(expected), `${name} differs from the published artifact`); + } +} + +/** Every path stays under the staging directory; a published name never chooses where to write. */ +export function stagedPath(stage, name) { + const segments = name.split("/"); + assert.ok( + segments.length > 1 && segments[0] === "package" && segments.every((segment) => segment !== "" && segment !== "." && segment !== ".."), + `unsafe tarball entry ${JSON.stringify(name)}`, + ); + return join(stage, ...segments); +} + +/** Writes `destination/dijo-404-disktop-1.0.0.tgz`; `destination` must not exist yet. */ +export async function packMirror(source, destination, { expectedSha256 = PUBLISHED_SHA256, npm = "npm" } = {}) { + assert.equal(digest("sha256", await readFile(source), "hex"), expectedSha256, "the source is not the audited published tarball"); + const published = readTarball(source); + const stage = await mkdtemp(join(tmpdir(), "disktop-mirror-")); + try { + for (const entry of byName(published, "the published tarball").values()) { + const path = stagedPath(stage, entry.name); + await mkdir(dirname(path), { recursive: true }); + const data = entry.name === MANIFEST ? mirrorManifest(entry.data.toString("utf8")) : entry.data; + await writeFile(path, data, { flag: "wx" }); + await chmod(path, entry.mode); + } + await mkdir(destination); + const packed = spawnSync(npm, ["pack", "--ignore-scripts", "--pack-destination", destination], { + cwd: join(stage, "package"), + encoding: "utf8", + shell: false, + }); + assert.equal(packed.error, undefined, packed.error?.message); + assert.equal(packed.status, 0, packed.stderr); + assert.deepEqual(await readdir(destination), [MIRROR_ARCHIVE], "npm pack must write exactly the mirror archive"); + } finally { + await rm(stage, { recursive: true, force: true }); + } + const archive = join(destination, MIRROR_ARCHIVE); + compareMirror(published, readTarball(archive)); + const bytes = await readFile(archive); + return { archive, sha256: digest("sha256", bytes, "hex"), integrity: `sha512-${digest("sha512", bytes, "base64")}` }; +} + +/** Checks a clean install's lockfile: the mirror, from GitHub Packages, with the archive's digest. */ +export function validateInstalledMirror(lock, archiveBytes) { + const installed = lock.packages?.[`node_modules/${MIRROR_NAME}`]; + assert.equal(installed?.version, VERSION, `the consumer must install ${MIRROR_NAME}@${VERSION}`); + assert.equal(new URL(installed.resolved).origin, MIRROR_ORIGIN, "the mirror must resolve from GitHub Packages"); + const hashes = (installed.integrity ?? "").split(/\s+/).filter(Boolean); + assert.ok(hashes.length > 0, "the installed mirror has no integrity"); + for (const hash of hashes) { + const [, algorithm, value] = /^(sha512|sha256|sha1)-([A-Za-z0-9+/]+={0,2})$/.exec(hash) ?? []; + assert.ok(algorithm !== undefined, `unrecognised integrity ${hash}`); + assert.equal(value, digest(algorithm, archiveBytes, "base64"), `${algorithm} integrity differs from the mirror archive`); + } +} + +async function main() { + const [mode, first, second] = process.argv.slice(2); + if (mode === "pack") { + const { archive, sha256, integrity } = await packMirror(first, second); + process.stdout.write(`archive=${archive}\nsha256=${sha256}\nintegrity=${integrity}\n`); + } else if (mode === "installed") { + const lock = JSON.parse(await readFile(join(second, "package-lock.json"), "utf8")); + validateInstalledMirror(lock, await readFile(first)); + process.stdout.write(`Installed ${MIRROR_NAME}@${VERSION} from GitHub Packages matches ${first}\n`); + } else { + throw new Error("usage: mirror-github-package.mjs pack | installed "); + } +} + +if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url) await main(); diff --git a/scripts/tarball.mjs b/scripts/tarball.mjs new file mode 100644 index 0000000..b03d1f3 --- /dev/null +++ b/scripts/tarball.mjs @@ -0,0 +1,34 @@ +/** A minimal reader for the gzip ustar files `npm pack` writes. */ +import { readFileSync } from "node:fs"; +import { gunzipSync } from "node:zlib"; + +/** Every entry of the tarball at `path`: regular files, with PAX headers for long names. */ +export function readTarball(path) { + const bytes = gunzipSync(readFileSync(path)); + const entries = []; + let pending = {}; + for (let offset = 0; offset + 512 <= bytes.length; ) { + const header = bytes.subarray(offset, offset + 512); + if (header.every((byte) => byte === 0)) { + break; + } + const field = (start, length) => header.subarray(start, start + length).toString("utf8").replace(/\0.*$/s, ""); + const size = Number.parseInt(field(124, 12).trim() || "0", 8); + const type = String.fromCharCode(header[156] || 48); + const data = bytes.subarray(offset + 512, offset + 512 + size); + offset += 512 + Math.ceil(size / 512) * 512; + + if (type === "x" || type === "g") { + for (const record of data.toString("utf8").split("\n").filter(Boolean)) { + const [, key, value] = /^\d+ ([^=]+)=(.*)$/s.exec(record) ?? []; + if (type === "x" && key === "path") pending.path = value; + } + continue; + } + const prefix = field(345, 155); + const name = pending.path ?? (prefix === "" ? field(0, 100) : `${prefix}/${field(0, 100)}`); + entries.push({ name, type, mode: Number.parseInt(field(100, 8).trim(), 8) & 0o7777, size, data: Buffer.from(data) }); + pending = {}; + } + return entries; +} diff --git a/tests/package/package.test.mjs b/tests/package/package.test.mjs index c121063..0390e20 100644 --- a/tests/package/package.test.mjs +++ b/tests/package/package.test.mjs @@ -26,11 +26,11 @@ import { createRequire } from "node:module"; import { tmpdir } from "node:os"; import { dirname, join, relative } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; -import { gunzipSync } from "node:zlib"; import { after, before, test } from "node:test"; import { inspectElf, targetMismatches } from "../../scripts/elf.mjs"; import { helperHello } from "../../scripts/helper-hello.mjs"; import { RELEASE_TARGETS, binaryName } from "../../scripts/release-targets.mjs"; +import { readTarball } from "../../scripts/tarball.mjs"; import { compileBundle } from "../support/schemas.mjs"; const ROOT = fileURLToPath(new URL("../../", import.meta.url)); @@ -82,37 +82,6 @@ function sha256(bytes) { return createHash("sha256").update(bytes).digest("hex"); } -/** A minimal ustar reader: npm pack writes regular files, with PAX headers for long names. */ -function readTarball(path) { - const bytes = gunzipSync(readFileSync(path)); - const entries = []; - let pending = {}; - for (let offset = 0; offset + 512 <= bytes.length; ) { - const header = bytes.subarray(offset, offset + 512); - if (header.every((byte) => byte === 0)) { - break; - } - const field = (start, length) => header.subarray(start, start + length).toString("utf8").replace(/\0.*$/s, ""); - const size = Number.parseInt(field(124, 12).trim() || "0", 8); - const type = String.fromCharCode(header[156] || 48); - const data = bytes.subarray(offset + 512, offset + 512 + size); - offset += 512 + Math.ceil(size / 512) * 512; - - if (type === "x" || type === "g") { - for (const record of data.toString("utf8").split("\n").filter(Boolean)) { - const [, key, value] = /^\d+ ([^=]+)=(.*)$/s.exec(record) ?? []; - if (type === "x" && key === "path") pending.path = value; - } - continue; - } - const prefix = field(345, 155); - const name = pending.path ?? (prefix === "" ? field(0, 100) : `${prefix}/${field(0, 100)}`); - entries.push({ name, type, mode: Number.parseInt(field(100, 8).trim(), 8) & 0o7777, size, data: Buffer.from(data) }); - pending = {}; - } - return entries; -} - function filesUnder(directory, predicate) { const found = []; for (const entry of readdirSync(directory, { withFileTypes: true })) { diff --git a/tests/support/workflows.mjs b/tests/support/workflows.mjs new file mode 100644 index 0000000..b151eb9 --- /dev/null +++ b/tests/support/workflows.mjs @@ -0,0 +1,11 @@ +import assert from "node:assert/strict"; + +/** One YAML job or step, bounded by the next declaration at its indentation. */ +export function workflowBlock(text, header, indentation) { + const start = text.indexOf(`${header}\n`); + assert.ok(start >= 0, `missing workflow declaration: ${header.trim()}`); + const afterHeader = start + header.length + 1; + const tail = text.slice(afterHeader); + const next = new RegExp(`^ {0,${indentation}}\\S`, "m").exec(tail)?.index ?? tail.length; + return text.slice(start, afterHeader + next); +} diff --git a/tests/unit/github-packages-mirror.test.mjs b/tests/unit/github-packages-mirror.test.mjs new file mode 100644 index 0000000..4127334 --- /dev/null +++ b/tests/unit/github-packages-mirror.test.mjs @@ -0,0 +1,158 @@ +/** The GitHub Packages mirror is the published npm artifact with one line renamed, and nothing else. */ +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { readFileSync } from "node:fs"; +import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { test } from "node:test"; +import { + MIRROR_ARCHIVE, + MIRROR_NAME, + PUBLISHED_SHA256, + compareMirror, + mirrorManifest, + packMirror, + stagedPath, + validateInstalledMirror, +} from "../../scripts/mirror-github-package.mjs"; +import { readTarball } from "../../scripts/tarball.mjs"; +import { workflowBlock } from "../support/workflows.mjs"; + +const MANIFEST = `${JSON.stringify({ + name: "disktop", + version: "1.0.0", + private: false, + description: "A \"name\": \"disktop\", inside a value is not the name line", + bin: { disktop: "./bin.js" }, + files: ["bin.js", "data.txt"], + repository: { type: "git", url: "git+https://github.com/Dijo-404/disktop.git" }, +}, null, 2)}\n`; + +const entry = (name, data, mode = 0o644) => ({ name, type: "0", mode, size: Buffer.byteLength(data), data: Buffer.from(data) }); +const published = () => [entry("package/package.json", MANIFEST), entry("package/bin.js", "#!/usr/bin/env node\n", 0o755), entry("package/data.txt", "bytes\n")]; +const mirrored = () => published().map((item) => (item.name === "package/package.json" ? entry(item.name, mirrorManifest(MANIFEST)) : item)); +const sha = (algorithm, bytes) => createHash(algorithm).update(bytes).digest("base64"); + +test("the mirror manifest changes the top-level name line and nothing else", () => { + const text = mirrorManifest(MANIFEST); + const before = MANIFEST.split("\n"); + const after = text.split("\n"); + assert.equal(after.length, before.length); + assert.deepEqual(after.flatMap((line, index) => (line === before[index] ? [] : [index])), [1]); + assert.equal(after[1], ` "name": "${MIRROR_NAME}",`); + assert.deepEqual(JSON.parse(text), { ...JSON.parse(MANIFEST), name: MIRROR_NAME }); +}); + +test("the mirror manifest refuses anything but the published 1.0.0 manifest", () => { + const manifest = JSON.parse(MANIFEST); + assert.throws(() => mirrorManifest(MANIFEST.replace('"name": "disktop"', '"name": "other"')), /published disktop package/); + assert.throws(() => mirrorManifest(MANIFEST.replace('"version": "1.0.0"', '"version": "1.0.1"')), /only the published 1\.0\.0/); + assert.throws(() => mirrorManifest(JSON.stringify(manifest)), /exactly one top-level name line/); + assert.throws(() => mirrorManifest(MANIFEST.replace(' "name": "disktop",\n', ' "name": "disktop",\n "name": "disktop",\n')), /exactly one top-level name line/); + const nested = `${JSON.stringify({ ...manifest, nested: { name: "disktop", other: 1 } }, null, 2)}\n`; + assert.deepEqual(JSON.parse(mirrorManifest(nested)).nested, { name: "disktop", other: 1 }, "a nested name is not the package name"); +}); + +test("a mirror differing from the published tarball anywhere else is refused", () => { + compareMirror(published(), mirrored()); + const changes = [ + [(items) => { items[2].data = Buffer.from("bytez\n"); }, /data\.txt differs/], + [(items) => { items[1].mode = 0o644; }, /bin\.js changed mode/], + [(items) => { items.push(entry("package/extra.js", "")); }, /exactly the published files/], + [(items) => { items.pop(); }, /exactly the published files/], + [(items) => { items[0] = entry("package/package.json", MANIFEST); }, /package\.json differs/], + [(items) => { items[0] = entry("package/package.json", mirrorManifest(MANIFEST).replace("1.0.0", "1.0.1")); }, /package\.json differs/], + [(items) => { items[2].type = "2"; }, /not a regular file/], + [(items) => { items.push(items[2]); }, /repeats package\/data\.txt/], + ]; + for (const [change, refusal] of changes) { + const items = mirrored(); + change(items); + assert.throws(() => compareMirror(published(), items), refusal); + } +}); + +test("a tarball entry never chooses a path outside the staging directory", () => { + assert.equal(stagedPath("/stage", "package/dist/bin/disktop.js"), "/stage/package/dist/bin/disktop.js"); + for (const name of ["package/../x", "../package/x", "/package/x", "other/x", "package", "package//x", "package/./x", "package/x/"]) { + assert.throws(() => stagedPath("/stage", name), /unsafe tarball entry/, name); + } +}); + +test("pack derives the mirror from a published tarball with npm and refuses any other source", async (context) => { + const work = await mkdtemp(join(tmpdir(), "disktop-mirror-test-")); + context.after(() => rm(work, { recursive: true, force: true })); + await mkdir(join(work, "source")); + await writeFile(join(work, "source", "package.json"), MANIFEST); + await writeFile(join(work, "source", "bin.js"), "#!/usr/bin/env node\n"); + await chmod(join(work, "source", "bin.js"), 0o755); + await writeFile(join(work, "source", "data.txt"), "bytes\n"); + const packed = spawnSync("npm", ["pack", "--ignore-scripts", "--pack-destination", work], { cwd: join(work, "source"), encoding: "utf8" }); + assert.equal(packed.status, 0, packed.stderr); + const source = join(work, "disktop-1.0.0.tgz"); + const expectedSha256 = createHash("sha256").update(readFileSync(source)).digest("hex"); + + await assert.rejects(packMirror(source, join(work, "refused")), /not the audited published tarball/); + assert.notEqual(expectedSha256, PUBLISHED_SHA256); + + const result = await packMirror(source, join(work, "mirror"), { expectedSha256 }); + assert.equal(result.archive, join(work, "mirror", MIRROR_ARCHIVE)); + const bytes = await readFile(result.archive); + assert.equal(result.sha256, createHash("sha256").update(bytes).digest("hex")); + assert.equal(result.integrity, `sha512-${sha("sha512", bytes)}`); + compareMirror(readTarball(source), readTarball(result.archive)); + assert.equal(JSON.parse(readTarball(result.archive).find((item) => item.name === "package/package.json").data).name, MIRROR_NAME); + + await assert.rejects(packMirror(source, join(work, "mirror"), { expectedSha256 }), /EEXIST/, "an existing destination is never reused"); +}); + +test("a clean install must resolve the mirror from GitHub Packages with the archive's digest", () => { + const bytes = Buffer.from("mirror archive bytes"); + const lock = (resolved, integrity) => ({ packages: { [`node_modules/${MIRROR_NAME}`]: { version: "1.0.0", resolved, integrity } } }); + const github = "https://npm.pkg.github.com/download/@dijo-404/disktop/1.0.0/0123456789abcdef"; + validateInstalledMirror(lock(github, `sha512-${sha("sha512", bytes)}`), bytes); + validateInstalledMirror(lock(github, `sha512-${sha("sha512", bytes)} sha1-${sha("sha1", bytes)}`), bytes); + const refusals = [ + [lock("https://registry.npmjs.org/disktop/-/disktop-1.0.0.tgz", `sha512-${sha("sha512", bytes)}`), /resolve from GitHub Packages/], + [lock(github, `sha512-${sha("sha512", Buffer.from("other"))}`), /sha512 integrity differs/], + [lock(github, `sha512-${sha("sha512", bytes)} sha1-${sha("sha1", Buffer.from("other"))}`), /sha1 integrity differs/], + [lock(github, `md5-${createHash("md5").update(bytes).digest("base64")}`), /unrecognised integrity/], + [lock(github, undefined), /has no integrity/], + [{ packages: { "node_modules/disktop": { version: "1.0.0", resolved: github } } }, /must install @dijo-404\/disktop@1\.0\.0/], + ]; + for (const [document, refusal] of refusals) assert.throws(() => validateInstalledMirror(document, bytes), refusal); +}); + +test("only the protected, dispatched job can publish, and only to GitHub Packages", async () => { + const workflow = await readFile(new URL("../../.github/workflows/mirror-github-packages.yml", import.meta.url), "utf8"); + const verify = await readFile(new URL("../../.github/workflows/verify-release.yml", import.meta.url), "utf8"); + assert.match(workflow, /^permissions:\n {2}contents: read$/m); + assert.match(workflow, new RegExp(`^ {2}EXPECTED_SHA256: ${PUBLISHED_SHA256}$`, "m")); + const commit = /^ {2}EXPECTED_COMMIT: ([0-9a-f]{40})$/m.exec(workflow)?.[1]; + assert.ok(commit !== undefined && verify.includes(`'${commit}'`), "the mirror checks the same tagged commit as release verification"); + assert.match(workflow, /pull_request:\n {4}paths:/); + + const prepare = workflowBlock(workflow, " prepare:", 2); + const publish = workflowBlock(workflow, " publish:", 2); + assert.doesNotMatch(workflow.replace(publish, ""), /\bsecrets\s*[.[]|NODE_AUTH_TOKEN|packages: write|id-token:|attestations:|npm publish\b|environment:/); + assert.match(prepare, /verify-registry-release\.mjs download/); + assert.match(prepare, /mirror-github-package\.mjs pack/); + + assert.match(publish, /^ {4}needs: prepare$/m); + assert.match(publish, /^ {4}environment: npm-publish$/m); + assert.match(publish, /github\.event_name == 'workflow_dispatch'/); + assert.match(publish, /github\.ref_name == github\.event\.repository\.default_branch/); + assert.match(publish, /inputs\.confirmation == 'MIRROR 1\.0\.0'/); + assert.match(publish, /^ {6}packages: write$/m); + assert.match(publish, /^ {10}registry-url: https:\/\/npm\.pkg\.github\.com$/m); + assert.match(publish, /^ {10}scope: '@dijo-404'$/m); + assert.doesNotMatch(publish, /registry\.npmjs\.org|--provenance|--registry/); + assert.deepEqual([...publish.matchAll(/\bsecrets\.([A-Za-z_][A-Za-z_0-9]*)/g)].map((match) => match[1]), ["GITHUB_TOKEN", "GITHUB_TOKEN"]); + assert.deepEqual([...publish.matchAll(/npm publish\b.*$/gm)].map((match) => match[0]), ['npm publish "$ARCHIVE" --ignore-scripts']); + const attest = publish.indexOf("uses: actions/attest@"); + const publication = publish.indexOf("npm publish "); + const verification = publish.indexOf("mirror-github-package.mjs\" installed"); + assert.ok(publish.indexOf("sha256sum --check --strict") < attest && attest < publication && publication < verification, "check, attest, publish, then verify"); +}); diff --git a/tests/unit/release-contract.test.mjs b/tests/unit/release-contract.test.mjs index 290be9b..b643dea 100644 --- a/tests/unit/release-contract.test.mjs +++ b/tests/unit/release-contract.test.mjs @@ -13,6 +13,7 @@ import { test } from "node:test"; import { CHECKSUM_FILE, HELPER_TARGETS, helperBinaryName } from "../../dist/native/locator.js"; import { publishRefusal, repositorySlug } from "../../scripts/prepublish-guard.mjs"; import * as release from "../../scripts/release-targets.mjs"; +import { workflowBlock } from "../support/workflows.mjs"; const read = (path) => readFileSync(path, "utf8"); const manifest = JSON.parse(read("package.json")); @@ -23,16 +24,6 @@ function namedHelpers(text) { return [...new Set(text.match(HELPER_NAME) ?? [])].sort(); } -/** One YAML job or step, bounded by the next declaration at its indentation. */ -function workflowBlock(text, header, indentation) { - const start = text.indexOf(`${header}\n`); - assert.ok(start >= 0, `missing workflow declaration: ${header.trim()}`); - const afterHeader = start + header.length + 1; - const tail = text.slice(afterHeader); - const next = new RegExp(`^ {0,${indentation}}\\S`, "m").exec(tail)?.index ?? tail.length; - return text.slice(start, afterHeader + next); -} - test("the locator and the release build name the same four helpers and checksum file", () => { assert.deepEqual([...HELPER_TARGETS].sort(), release.RELEASE_TARGETS.map((target) => target.name).sort()); assert.deepEqual(release.RELEASE_TARGETS.map(release.binaryName).sort(), BINARIES); From a3a9c5ba16903b9eb62da0cd946cecc739337573 Mon Sep 17 00:00:00 2001 From: Dijo S Benelen Date: Sun, 8 Nov 2026 22:41:18 +0530 Subject: [PATCH 2/2] Record the zstd advisories open when 1.0.0 is mirrored --- docs/release-readiness.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/release-readiness.md b/docs/release-readiness.md index e963428..1141dc2 100644 --- a/docs/release-readiness.md +++ b/docs/release-readiness.md @@ -61,6 +61,7 @@ attestation binds the mirror's digest to the publishing run. | Evidence | Recorded result | | --- | --- | | Mirror publication | **Not yet published.** The run, mirror digest, attestation and package visibility are recorded here once the protected job has run. | +| Open advisories at mirroring | RustSec published RUSTSEC-2026-0391, -0398, -0403 and -0410 (plus unsoundness warnings) against `zstd` 0.14.0, `zstd-safe` 8.0.0 and `zstd-sys` 2.1.0 on 2026-10-16, after `1.0.0` passed its advisory gate. The helper in both the npm package and the mirror is that `1.0.0` build. It creates one encoder or decoder per operation over files it wrote itself, and does not use the seekable, dictionary, training, `StableInBuffer` or WebAssembly paths the advisories name. The release owner approved mirroring the unchanged artifact on 2026-11-08; a fix needs a separately authorised maintenance release. npm's open advisories at that date affected development dependencies only. | ## Executed gates