@macula-io/martha 0.0.0 → 1.0.1

package/package.json

@@ -1,11 +1,65 @@
 {
   "name": "@macula-io/martha",
-  "version": "0.0.0",
-  "description": "Name reservation only. The Martha installer is published from macula-io/martha.",
+  "version": "1.0.1",
+  "description": "Install Martha from its signed public package: verifies the release's sigstore signature, then installs it",
+  "type": "module",
   "license": "Apache-2.0",
+  "author": "macula.io",
+  "homepage": "https://github.com/macula-io/martha",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/macula-io/martha.git",
     "directory": "installer"
+  },
+  "bin": {
+    "martha-install": "bin/martha-install.mjs"
+  },
+  "files": [
+    "bin/martha-install.mjs",
+    "keep_the_names_in_one_place/names.mjs",
+    "check_the_node_version/check_the_node_version.mjs",
+    "read_the_release_registry/read_the_release_registry.mjs",
+    "verify_the_release_signature/verify_the_release_signature.mjs",
+    "unpack_the_release_layer/unpack_the_release_layer.mjs",
+    "place_the_release/place_the_release.mjs",
+    "install_a_release/install_a_release.mjs",
+    "refuse_in_words/refuse_in_words.mjs",
+    "signers.txt",
+    "npm-shrinkwrap.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.18.1"
+  },
+  "dependencies": {
+    "sigstore": "5.0.0"
+  },
+  "bundleDependencies": [
+    "sigstore"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "glob": "14.0.4",
+    "minimatch": "11.0.5"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node ../prove_the_core/no_test_output_carries_the_environment.ts node --test --test-timeout=60000 --test-force-exit --import=../prove_the_core/fail_a_test_file_that_leaves_something_running.ts '*/*.node-test.mjs'"
+  },
+  "martha": {
+    "image": "ghcr.io/macula-io/martha",
+    "sourceRepository": "https://github.com/macula-io/martha",
+    "signerWorkflow": "https://github.com/macula-io/macula-ci-images/.github/workflows/attest-image.yml",
+    "issuer": "https://token.actions.githubusercontent.com",
+    "command": "martha",
+    "releaseTagPrefix": "v",
+    "installerTagPrefix": "installer-v",
+    "releaseFolder": "martha",
+    "dryRunTagPrefix": "dry-run-",
+    "installerPublishWorkflow": ".github/workflows/installer.yml"
   }
 }

package/place_the_release/place_the_release.mjs

@@ -0,0 +1,132 @@
+// Where a verified release lives, and how the command finds it (martha#21). Each release has its own read-only
+// directory, <data>/martha/releases/<version>-sha256-<hex>, staged inside releases/ and renamed into place; then
+// <data>/martha/current is swapped to it by one rename (the old release or the new one, never neither); then the
+// command on PATH, <bin>/martha, is linked through current, so it follows every install.
+//
+// One downgrade rule: a version lower than the one current points at is refused unless the user passes
+// --downgrade and names that exact version. A version is published once, so a second digest for a version this
+// machine holds is always refused. Anything at a link's place that is not a link is someone else's: it is named,
+// never replaced.
+import { chmod, lstat, mkdir, mkdtemp, readdir, readlink, rename, rm, symlink, unlink } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+
+import { NAMES } from '../keep_the_names_in_one_place/names.mjs'
+import { compareVersions, isVersion } from '../read_the_release_registry/read_the_release_registry.mjs'
+import { refuse } from '../refuse_in_words/refuse_in_words.mjs'
+import { TOP } from '../unpack_the_release_layer/unpack_the_release_layer.mjs'
+
+/**
+ * @typedef {{ releases: string, current: string, binDir: string }} Places
+ *   releases: where each release has its directory; current: the link to the one in use; binDir: where the command
+ *   is linked.
+ */
+
+/** @param {string} version @param {string} digest */
+export const releaseName = (version, digest) => `${version}-${digest.replace(':', '-')}`
+
+/** @param {string} path */
+const there = async (path) => { try { return await lstat(path) } catch { return undefined } }
+
+/**
+ * The version current points at, when it points at a release in `releases`; undefined when nothing is installed.
+ * @param {Places} places
+ */
+export async function installedVersion ({ releases, current }) {
+  const at = await there(current)
+  if (!at) return undefined
+  if (!at.isSymbolicLink()) refuse(`${current} is not a link; move it aside and install again`)
+  const target = await readlink(current)
+  if (dirname(target) !== releases) return undefined
+  const version = basename(target).split('-sha256-')[0]
+  return isVersion(version) ? version : undefined
+}
+
+/**
+ * The one downgrade rule, and no second digest for a version this machine holds.
+ * @param {{ version: string, digest: string, downgrade: boolean, named: boolean, places: Places }} request
+ */
+export async function checkAgainstInstalled ({ version, digest, downgrade, named, places }) {
+  if (downgrade && !named) refuse('--downgrade installs only the version you name; name it')
+  const have = await installedVersion(places)
+  if (have && compareVersions(version, have) < 0 && !downgrade) {
+    refuse(`${version} is lower than the installed ${have}; refused. To go back on purpose: ${NAMES.command}-install ${version} --downgrade`)
+  }
+  const held = (await readdir(places.releases).catch(() => [])).filter((n) => n.startsWith(`${version}-sha256-`))
+  const other = held.find((n) => n !== releaseName(version, digest))
+  if (other) {
+    refuse(`${version} is installed as ${other.slice(version.length + 1)} and the package now names ${digest} for it; a version is published once, refused`)
+  }
+}
+
+/**
+ * `link` made to point at `target` by one rename.
+ * @param {string} target
+ * @param {string} link
+ */
+export async function swapLink (target, link) {
+  const at = await there(link)
+  if (at && !at.isSymbolicLink()) {
+    refuse(`${link} is ${at.isDirectory() ? 'a directory' : 'a file'}, not a link; move it aside and install again`)
+  }
+  await mkdir(dirname(link), { recursive: true })
+  const temporary = join(dirname(link), `.${basename(link)}.${process.pid}`)
+  await unlink(temporary).catch(() => {})
+  await symlink(target, temporary)
+  await rename(temporary, link)
+}
+
+/**
+ * A tree this run made, removed even when it is read-only.
+ * @param {string} path
+ */
+async function removeTree (path) {
+  /** @param {string} dir */
+  const walk = async (dir) => {
+    await chmod(dir, 0o700).catch(() => {})
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+      if (entry.isDirectory()) await walk(join(dir, entry.name))
+    }
+  }
+  await walk(path)
+  await rm(path, { recursive: true, force: true })
+}
+
+/**
+ * The release unpacked into its own directory, unless it is already there: staged inside `releases`, so it
+ * arrives by a rename on one filesystem, and removed when anything fails.
+ * @param {{ releases: string, name: string, unpack: (stage: string) => Promise<void> }} request
+ * @returns {Promise<string>} the release directory
+ */
+export async function placeRelease ({ releases, name, unpack }) {
+  const final = join(releases, name)
+  if (await there(final)) return final
+  await mkdir(releases, { recursive: true })
+  const stage = await mkdtemp(join(releases, '.work-'))
+  try {
+    await unpack(stage)
+    await rename(stage, final)
+  } catch (error) {
+    await removeTree(stage)
+    throw error
+  }
+  await chmod(final, 0o555)
+  return final
+}
+
+/**
+ * The command on PATH, <bin>/martha -> <current>/martha/bin/martha, when the release carries one; otherwise a line
+ * saying there is no command to link. A <bin>/martha that is not a link is left alone and named.
+ * @param {{ release: string, places: Places }} request
+ * @returns {Promise<string>} what happened, in words
+ */
+export async function linkCommand ({ release, places }) {
+  const inRelease = join(release, TOP, 'bin', NAMES.command)
+  if (!(await there(inRelease))?.isFile()) return `this release carries no ${TOP}/bin/${NAMES.command}, so there is no command to link`
+  const link = join(places.binDir, NAMES.command)
+  const target = join(places.current, TOP, 'bin', NAMES.command)
+  const at = await there(link)
+  if (at && !at.isSymbolicLink()) return `${link} is not a link, so it was left alone; the command is ${target}`
+  if (at && (await readlink(link)) === target) return `${link} -> ${target}`
+  await swapLink(target, link)
+  return `${link} -> ${target}`
+}

package/read_the_release_registry/read_the_release_registry.mjs

@@ -0,0 +1,255 @@
+// The Martha release on its registry, read anonymously (martha#21). A tag is read once, to find the manifest; from
+// then on the release is that manifest's sha256, computed here from the bytes and never taken from a header.
+//
+// Every read is capped, whatever the server says its length is: anyone who can push to the package can pile tags,
+// signatures and bytes into it, and a capped read refuses what it cannot afford instead of exhausting the machine.
+import { createHash } from 'node:crypto'
+
+import { couldNotCheck, refuse } from '../refuse_in_words/refuse_in_words.mjs'
+
+export const LIMITS = Object.freeze({
+  manifestBytes: 64 * 1024,
+  tagListBytes: 1024 * 1024,
+  bundles: 16,
+  bundleBytes: 64 * 1024,
+  layerBytes: 64 * 1024 * 1024
+})
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+// The one manifest type a release is pushed as. An image index is refused: the release job pushes one image, and
+// the digest it signs is that image's manifest, never an index over several.
+export const IMAGE_MANIFEST = 'application/vnd.oci.image.manifest.v1+json'
+const GZIP_LAYER = 'application/vnd.oci.image.layer.v1.tar+gzip'
+const INDEX = 'application/vnd.oci.image.index.v1+json'
+const BUNDLE = 'application/vnd.dev.sigstore.bundle.v0.3+json'
+// cosign labels each bundle's manifest with what it attests. The label is not trusted, only used to pass over the
+// SBOM and provenance bundles (large, and not what an install checks); the signature itself is checked in full.
+const COSIGN_SIGN = 'https://sigstore.dev/cosign/sign/v1'
+
+/** @param {Uint8Array} bytes */
+export const sha256 = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`
+/** @param {unknown} v @returns {v is string} */
+export const isVersion = (v) => typeof v === 'string' && SEMVER.test(v)
+/** @param {unknown} d @returns {d is string} */
+export const isDigest = (d) => typeof d === 'string' && DIGEST.test(d)
+
+/**
+ * -1, 0 or 1, as a sort comparator, for two X.Y.Z versions.
+ * @param {string} a
+ * @param {string} b
+ */
+export const compareVersions = (a, b) => {
+  const numbers = (/** @type {string} */ v) => (v.match(SEMVER) ?? []).slice(1).map(Number)
+  const x = numbers(a)
+  const y = numbers(b)
+  const at = x.findIndex((n, i) => n !== y[i])
+  return at < 0 ? 0 : Math.sign((x[at] ?? 0) - (y[at] ?? 0))
+}
+
+/**
+ * Refuses an answer without reading it. Its body is cancelled first, or its connection stays open behind the
+ * refusal (martha#112).
+ * @param {Response} response
+ * @param {string} message
+ * @returns {Promise<never>}
+ */
+async function refusedUnread (response, message) {
+  await response.body?.cancel()
+  return refuse(message)
+}
+
+/**
+ * The body, refused once it passes `limit` bytes, whether or not the server said how long it is.
+ * @param {Response} response
+ * @param {number} limit
+ * @param {string} what
+ */
+async function readCapped (response, limit, what) {
+  const declared = Number(response.headers.get('content-length') ?? 0)
+  if (declared > limit) await refusedUnread(response, `${what} is ${declared} bytes, over the ${limit} a release may carry; refused`)
+  /** @type {Buffer[]} */
+  const chunks = []
+  let total = 0
+  if (!response.body) return Buffer.concat(chunks)
+  for await (const chunk of response.body) {
+    total += chunk.length
+    if (total > limit) refuse(`${what} is over the ${limit} bytes a release may carry; refused`)
+    chunks.push(Buffer.from(chunk))
+  }
+  return Buffer.concat(chunks)
+}
+
+/**
+ * @param {Buffer} bytes
+ * @param {string} what
+ * @returns {any}
+ */
+const parsed = (bytes, what) => {
+  try { return JSON.parse(bytes.toString('utf8')) } catch { return refuse(`${what} is not JSON; refused`) }
+}
+
+/**
+ * The manifest is the one image manifest a release pushes; an index, or any other type, is named and refused
+ * before anything looks for a signature.
+ * @param {any} manifest
+ * @param {string} where
+ */
+export function checkManifestType (manifest, where) {
+  const type = manifest?.mediaType
+  if (type === INDEX) refuse(`${where} is an image index, not the one image manifest a release is; refused`)
+  if (type !== IMAGE_MANIFEST) refuse(`${where} is a ${typeof type === 'string' ? type : 'manifest of no type'}, not ${IMAGE_MANIFEST}; refused`)
+}
+
+/**
+ * The one gzip layer of the image manifest, as {digest, size}.
+ * @param {any} manifest
+ * @param {string} where
+ * @returns {{ digest: string, size: number }}
+ */
+export function layerOf (manifest, where) {
+  checkManifestType(manifest, where)
+  const layers = Array.isArray(manifest.layers) ? manifest.layers : []
+  const layer = layers[0]
+  const ok = layers.length === 1 && layer?.mediaType === GZIP_LAYER && isDigest(layer.digest) &&
+    Number.isInteger(layer.size) && layer.size > 0
+  if (!ok) refuse(`${where} is not one image with one gzip layer; refused`)
+  if (layer.size > LIMITS.layerBytes) refuse(`${where} has a ${layer.size}-byte layer, over the ${LIMITS.layerBytes} a release may carry; refused`)
+  return { digest: layer.digest, size: layer.size }
+}
+
+/**
+ * @typedef {(path: string, accept: string, what: string) => Promise<Response>} Get
+ */
+
+/**
+ * A blob by digest, exactly `size` bytes, hashing to that digest.
+ * @param {Get} get
+ * @param {{ digest: string, size: number }} blob
+ * @param {string} what
+ */
+async function blobOf (get, { digest, size }, what) {
+  const bytes = await readCapped(await get(`blobs/${digest}`, '', what), size, what)
+  if (bytes.length !== size) refuse(`${what} is ${bytes.length} bytes, not the ${size} its manifest names; refused`)
+  if (sha256(bytes) !== digest) refuse(`${what} hashes to ${sha256(bytes)}, not ${digest}; refused`)
+  return bytes
+}
+
+/**
+ * The sigstore bundle a signature manifest holds, or undefined for a manifest that is no cosign signature.
+ * @param {Get} get
+ * @param {string} manifestDigest
+ */
+async function bundleAt (get, manifestDigest) {
+  const response = await get(`manifests/${manifestDigest}`, IMAGE_MANIFEST, 'a signature manifest')
+  const bytes = await readCapped(response, LIMITS.manifestBytes, 'a signature manifest')
+  if (sha256(bytes) !== manifestDigest) refuse(`a signature manifest hashes to ${sha256(bytes)}, not ${manifestDigest}; refused`)
+  const manifest = parsed(bytes, 'a signature manifest')
+  if (manifest.annotations?.['dev.sigstore.bundle.predicateType'] !== COSIGN_SIGN) return undefined
+  const layer = (manifest.layers ?? [])[0] ?? {}
+  if (layer.mediaType !== BUNDLE || !isDigest(layer.digest) || !(layer.size <= LIMITS.bundleBytes)) {
+    refuse(`signature ${manifestDigest} is not one sigstore bundle of at most ${LIMITS.bundleBytes} bytes; refused`)
+  }
+  return parsed(await blobOf(get, layer, `signature bundle ${layer.digest}`), `signature bundle ${layer.digest}`)
+}
+
+/**
+ * A reader for one package. `image` is <registry host>/<owner>/<name>; `base` the registry's URL, a test's own
+ * server or the real one.
+ * @param {{ image: string, base?: string, fetch?: typeof globalThis.fetch }} options
+ */
+export function registry ({ image, base = `https://${image.split('/')[0]}`, fetch = globalThis.fetch }) {
+  const name = image.slice(image.indexOf('/') + 1)
+  let token = ''
+
+  /**
+   * A network failure is no answer: the check could not be made.
+   * @param {string} url
+   * @param {RequestInit} init
+   * @param {string} what
+   */
+  const ask = async (url, init, what) => {
+    try { return await fetch(url, init) } catch (error) {
+      return couldNotCheck(`${what}: ${base} did not answer (${error instanceof Error ? error.message : String(error)})`)
+    }
+  }
+
+  /**
+   * @param {string} path
+   * @param {string} accept
+   * @param {string} what
+   */
+  const get = async (path, accept, what) => {
+    /** @type {Record<string, string>} */
+    const headers = { authorization: `Bearer ${token}` }
+    if (accept) headers['accept'] = accept
+    const response = await ask(`${base}/v2/${name}/${path}`, { headers, redirect: 'follow' }, what)
+    if (!response.ok) await refusedUnread(response, `${what}: ${image} answered ${response.status}; refused`)
+    return response
+  }
+
+  /**
+   * @param {{ digest: string, size: number }} wanted
+   * @param {string} what
+   */
+  const blob = async (wanted, what) => blobOf(get, wanted, what)
+
+  return {
+    image,
+    blob,
+
+    async authorize () {
+      const what = `an anonymous pull token for ${name}`
+      const response = await ask(`${base}/token?scope=repository:${name}:pull`, {}, what)
+      if (!response.ok) await refusedUnread(response, `${base} gave no anonymous pull token for ${name} (${response.status}); is the package public?`)
+      token = parsed(await readCapped(response, LIMITS.manifestBytes, what), what).token ?? ''
+      if (!token) refuse(`${base} gave no anonymous pull token for ${name}; refused`)
+    },
+
+    // The highest X.Y.Z tag. A signature tag (sha256-<hex>) or anything else that is no version is passed over.
+    // The list is one capped page: a registry that says there is a next page holds more tags than an install
+    // reads, so it is refused, and naming a version gets past it.
+    async highestVersion () {
+      const response = await get('tags/list?n=10000', '', 'the version list')
+      if (/rel="?next"?/.test(response.headers.get('link') ?? '')) await refusedUnread(response, `${image} lists more tags than one page; name a version`)
+      const tags = parsed(await readCapped(response, LIMITS.tagListBytes, 'the version list'), 'the version list').tags ?? []
+      const versions = (Array.isArray(tags) ? tags : []).filter(isVersion).sort(compareVersions)
+      const highest = versions.at(-1)
+      if (highest === undefined) refuse(`${image} carries no version; refused`)
+      return highest
+    },
+
+    /**
+     * The image manifest a tag or digest names: its bytes, their digest and the parsed JSON.
+     * @param {string} ref
+     */
+    async manifest (ref) {
+      const response = await get(`manifests/${ref}`, IMAGE_MANIFEST, `${image}:${ref}`)
+      const bytes = await readCapped(response, LIMITS.manifestBytes, `the manifest of ${image}:${ref}`)
+      const json = parsed(bytes, `the manifest of ${image}:${ref}`)
+      checkManifestType(json, `${image}:${ref}`)
+      return { bytes, digest: sha256(bytes), json }
+    },
+
+    /**
+     * The signature bundles cosign attached to a digest, through the tag schema it falls back to on ghcr
+     * (sha256-<hex>, an index of referrers): at most LIMITS.bundles entries, each at most LIMITS.bundleBytes.
+     * @param {string} digest
+     */
+    async bundles (digest) {
+      const tag = digest.replace(':', '-')
+      const response = await get(`manifests/${tag}`, INDEX, `the signatures of ${digest}`)
+      const index = parsed(await readCapped(response, LIMITS.manifestBytes, `the signature index of ${digest}`), `the signature index of ${digest}`)
+      const listed = Array.isArray(index.manifests) ? index.manifests : []
+      const entries = listed.filter((/** @type {any} */ m) => m?.artifactType === BUNDLE && isDigest(m.digest))
+      if (entries.length > LIMITS.bundles) refuse(`${digest} carries ${entries.length} signature entries, over the ${LIMITS.bundles} read; refused`)
+      /** @type {any[]} */
+      const found = []
+      for (const entry of entries) {
+        const bundle = await bundleAt(get, entry.digest)
+        if (bundle) found.push(bundle)
+      }
+      return found
+    }
+  }
+}

package/refuse_in_words/refuse_in_words.mjs

@@ -0,0 +1,31 @@
+// A refusal is the installer saying no, in words (martha#21). Anything else that ends an install is a fault, and
+// the bin says so. A check that could not be made at all (the Sigstore trust root did not arrive, the registry did
+// not answer) is its own kind of refusal: it never reads as "unsigned", and never as "fine".
+
+export class Refused extends Error {
+  /** @param {string} message */
+  constructor (message) {
+    super(message)
+    this.name = 'Refused'
+  }
+}
+
+export class CouldNotCheck extends Refused {
+  /** @param {string} message */
+  constructor (message) {
+    super(`could not check: ${message}`)
+    this.name = 'CouldNotCheck'
+  }
+}
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+export const refuse = (message) => { throw new Refused(message) }
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+export const couldNotCheck = (message) => { throw new CouldNotCheck(message) }

package/signers.txt

@@ -0,0 +1,11 @@
+# The signers a Martha release may carry (martha#21). One full commit sha of macula-io/macula-ci-images'
+# .github/workflows/attest-image.yml per line; the installer verifies the certificate identity
+# https://github.com/macula-io/macula-ci-images/.github/workflows/attest-image.yml@<sha> EXACTLY.
+#
+# Only a sha that carries the whole release guard goes here, never one from before it (b304162, 601c719, 56a597e,
+# and e8fe1a8, whose checks ran from the caller's tree). A new sha arrives in three steps, so an installed user is
+# never stranded:
+#   1. an installer version that adds it, keeping the old ones;
+#   2. a release signed under a sha ALREADY listed;
+#   3. only then a release signed under the new sha.
+b4c41abb404c32215a2823b7f19ac65b732e1dfe