@macula-io/martha 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,15 +1,60 @@
 # @macula-io/martha
 
-**This package is a name reservation at version 0.0.0. It installs nothing and does nothing.**
+Installs [Martha](https://github.com/macula-io/martha) from its signed public package, with nothing but Node.
 
-The real package is the Martha installer, published as `@macula-io/martha@1.0.0` and later by
-Martha's own CI from https://github.com/macula-io/martha, with npm provenance. This 0.0.0 exists only so that
-the name belongs to the project before the first installer release.
+```sh
+npx -y --ignore-scripts @macula-io/martha@<exact version> [<martha version>]
+```
 
-To install Martha, name an exact version — never this one:
+Always name the installer's exact version: npm never lets a published version be replaced, so that line is what you
+trust. Leave out the Martha version to install the highest one; name it to install exactly that one.
 
-```sh
-npx -y --ignore-scripts @macula-io/martha@1.0.0
+## What it checks, before anything is written
+
+1. The Node running it is one Martha runs on.
+2. The version resolves once, to a digest computed from the manifest's bytes. Never `:latest`.
+3. A version lower than the installed one needs `--downgrade` and the version named; a second digest for a version
+   you hold is always refused.
+4. The digest carries a Sigstore signature from `macula-io/macula-ci-images`' `attest-image.yml`, at a commit listed
+   in `signers.txt`, for `github.com/macula-io/martha` and the tag `v<version>`. A signature check that could not
+   run says "could not check", never "unsigned".
+5. The one layer matches its digest and size; every tar entry is checked (and the unpacked size, the number of
+   entries and every name capped) before a byte is written.
+6. The release gets its own read-only directory under `$XDG_DATA_HOME/martha/releases/` (default
+   `~/.local/share`), `current` is swapped to it by one rename, and `~/.local/bin/martha` links through `current`
+   when the release carries a `martha` command.
+
+Check the installer itself with `npm audit signatures`: it is published with provenance from this repository.
+
+## Options
+
+```text
+martha-install [<version>] [--downgrade] [--digest sha256:<hex>]
 ```
 
-See https://github.com/macula-io/martha for what Martha is.
+## How a release is made
+
+1. The release dry run (`release-dry-run.yml`, started by hand on a branch) pushes the packed tree into the release
+   package under a `dry-run-<run>-<attempt>` tag, which is never a version, so no install ever takes it. It signs it
+   through the same signing workflow, then checks that the signature verifies for that branch and is refused for
+   `refs/tags/v<version>`, that an unsigned image is refused, and that the layer is exactly the committed tree.
+   Its two tags are kept in the public package, not pruned: one pair per run, and runs are started by hand.
+   Neither is ever installed: no tag of that shape is a version, and the signature is for a branch, so an install,
+   which demands `refs/tags/v<version>`, refuses it. Pruning would need a workflow that can delete package versions,
+   and none of Martha's workflows holds that power. A maintainer may delete old ones by hand in the package settings.
+2. The first dry run is what makes the release package. The maintainers then link it to this repository and make it
+   public, before any release tag: every install pulls anonymously, and a refused pull must never read as
+   "unsigned".
+3. `installer-v<version>` publishes this installer to npm, with provenance, through trusted publishing.
+4. `v<version>` publishes a signed Martha release into the package, pinning that installer.
+
+Neither tag publishes while a dependency of Martha or of this installer carries a known published advisory
+(`advisories.yml`, which also runs on every pull request). An advisory is fixed or waived by a dated, named, expiring
+row in `.github/advisories-waivers.txt`; there is no baseline. The `overrides` in `package.json` are such fixes:
+sigstore 5.0.0 resolves glob 13 and minimatch 10, which carry GHSA-3g3m-2fjr-6pw4 and GHSA-g3hv-75wg-m249, so the
+installer pins their first patched releases. Its callers use only `glob(pattern, options)` and
+`minimatch(path, pattern)`, which both majors keep. Drop an override once sigstore resolves a patched release itself.
+
+## License
+
+Apache-2.0

package/bin/martha-install.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// martha-install: install Martha from its signed public package, with nothing but Node (martha#21).
+//
+//   npx -y --ignore-scripts @macula-io/martha@<exact version> [<martha version>] [--downgrade] [--digest sha256:<hex>]
+//
+// The line that names this installer's exact version is the trust anchor: npm never lets anyone replace a
+// published version. Everything after it is checked here; see install_a_release/install_a_release.mjs for the steps.
+import { homedir } from 'node:os'
+
+import { installRelease, placesOnThisMachine } from '../install_a_release/install_a_release.mjs'
+import { NAMES } from '../keep_the_names_in_one_place/names.mjs'
+import { Refused } from '../refuse_in_words/refuse_in_words.mjs'
+
+const USAGE = `usage: ${NAMES.command}-install [<version>] [--downgrade] [--digest sha256:<hex>]`
+
+/**
+ * @param {string[]} argv
+ * @returns {{ version?: string, digest?: string, downgrade: boolean, help: boolean }}
+ */
+export function parseArguments (argv) {
+  /** @type {{ version?: string, digest?: string, downgrade: boolean, help: boolean }} */
+  const options = { downgrade: false, help: false }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] ?? ''
+    if (arg === '--digest') options.digest = argv[++i] ?? ''
+    else if (arg.startsWith('-')) setSwitch(options, arg)
+    else if (options.version !== undefined) throw new Refused('one version at a time')
+    else options.version = arg
+  }
+  return options
+}
+
+/**
+ * Sets the switch `arg` names, one that takes no value; refuses one it does not know.
+ * @param {{ downgrade: boolean, help: boolean }} options
+ * @param {string} arg
+ */
+function setSwitch (options, arg) {
+  if (arg === '--downgrade') options.downgrade = true
+  else if (arg === '-h' || arg === '--help') options.help = true
+  else throw new Refused(`unknown option '${arg}' (${USAGE})`)
+}
+
+async function main () {
+  const { help, ...options } = parseArguments(process.argv.slice(2))
+  if (help) { console.log(USAGE); return }
+  await installRelease({ ...options, places: placesOnThisMachine(homedir(), process.env['XDG_DATA_HOME']) })
+}
+
+main().catch((error) => {
+  // A refusal is the installer saying no, in words; anything else is a fault, and says so.
+  console.error(error instanceof Refused ? `${NAMES.command}-install: ${error.message}` : `${NAMES.command}-install: failed: ${error?.stack ?? error}`)
+  process.exitCode = 1
+})

package/check_the_node_version/check_the_node_version.mjs

@@ -0,0 +1,19 @@
+// The Node running the installer is one Martha runs on (martha#21, step 1): refused before anything is fetched.
+// The range is the installer's own engines.node, which the drift test holds equal to the root package.json's, so
+// the installer never fetches a release this Node could not run. Only the one form Martha writes is read, ">=X.Y.Z";
+// any other is a fault in this package, and says so.
+import { NAMES } from '../keep_the_names_in_one_place/names.mjs'
+import { compareVersions } from '../read_the_release_registry/read_the_release_registry.mjs'
+import { refuse } from '../refuse_in_words/refuse_in_words.mjs'
+
+const AT_LEAST = /^>=(\d+\.\d+\.\d+)$/
+
+/**
+ * @param {string} running  the Node version, as process.versions.node gives it
+ * @param {string} [range]  engines.node
+ */
+export function checkNodeVersion (running, range = NAMES.nodeRange) {
+  const lowest = range.match(AT_LEAST)?.[1]
+  if (lowest === undefined) throw new Error(`engines.node is '${range}', not the >=X.Y.Z this installer reads`)
+  if (compareVersions(running, lowest) < 0) refuse(`Martha needs Node ${range}; this is Node ${running}. Install a newer Node and run the same line again`)
+}

package/install_a_release/install_a_release.mjs

@@ -0,0 +1,166 @@
+// Martha installed from its signed public package (martha#21), in this order, and nothing linked until every step
+// has passed:
+//   1. this Node is one Martha runs on;
+//   2. an anonymous pull token; the version (the one named, or the highest X.Y.Z, never :latest); the manifest's
+//      bytes and the digest computed from them: from here on that digest is the release;
+//   3. the one downgrade rule, and no second digest for a version this machine holds;
+//   4. the signature on that digest, by a listed signer, for this repository and refs/tags/v<version>;
+//   5. the one layer by digest, its size and sha256 checked;
+//   6. every tar entry checked before anything is written;
+//   7. its own read-only directory, current swapped by one rename, the command linked through current.
+import { readFile } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
+
+import { checkNodeVersion } from '../check_the_node_version/check_the_node_version.mjs'
+import { NAMES, releaseRef } from '../keep_the_names_in_one_place/names.mjs'
+import { checkAgainstInstalled, linkCommand, placeRelease, releaseName, swapLink } from '../place_the_release/place_the_release.mjs'
+import { isDigest, isVersion, layerOf, registry } from '../read_the_release_registry/read_the_release_registry.mjs'
+import { CouldNotCheck, refuse } from '../refuse_in_words/refuse_in_words.mjs'
+import { unpackLayer } from '../unpack_the_release_layer/unpack_the_release_layer.mjs'
+import { readSigners, signedBy } from '../verify_the_release_signature/verify_the_release_signature.mjs'
+
+const SIGNERS = new URL('../signers.txt', import.meta.url)
+
+export const listedSigners = async () => readSigners(await readFile(SIGNERS, 'utf8'))
+
+/**
+ * Where this machine keeps Martha, worked out once by the bin and passed in: the XDG data directory
+ * ($XDG_DATA_HOME when it is an absolute path, else ~/.local/share) and ~/.local/bin.
+ * @param {string} home
+ * @param {string | undefined} xdgDataHome
+ * @returns {import('../place_the_release/place_the_release.mjs').Places}
+ */
+export const placesOnThisMachine = (home, xdgDataHome) => {
+  const data = xdgDataHome && isAbsolute(xdgDataHome) ? xdgDataHome : join(home, '.local', 'share')
+  return {
+    releases: join(data, 'martha', 'releases'),
+    current: join(data, 'martha', 'current'),
+    binDir: join(home, '.local', 'bin')
+  }
+}
+
+/**
+ * @typedef {object} InstallRequest
+ * @property {import('../place_the_release/place_the_release.mjs').Places} places
+ * @property {string} [version]        the version named; else the highest
+ * @property {string} [digest]         the digest the user verified, sha256:<hex>
+ * @property {boolean} [downgrade]
+ * @property {string} [image]          a test's own; the release image otherwise
+ * @property {string} [base]           the registry's URL; a test's own server
+ * @property {typeof globalThis.fetch} [fetch]
+ * @property {string[]} [signers]      a test's own; signers.txt otherwise
+ * @property {import('../verify_the_release_signature/verify_the_release_signature.mjs').MakeVerifier} [makeVerifier]
+ * @property {string} [tufCachePath]
+ * @property {string} [nodeVersion]    a test's own; process.versions.node otherwise
+ * @property {(line: string) => void} [log]
+ */
+
+/** @param {InstallRequest} request */
+function checkRequest ({ version, digest }) {
+  if (version !== undefined && !isVersion(version)) refuse(`a version is X.Y.Z, got '${version}'`)
+  if (digest !== undefined && !isDigest(digest)) refuse(`--digest is sha256:<64 hex>, got '${digest}'`)
+  if (digest !== undefined && version === undefined) refuse('--digest needs the version it is the digest of')
+}
+
+/**
+ * @param {{ image: string, version: string, digest: string, named: boolean, reasons: string[] }} unsigned
+ * @returns {never}
+ */
+function refuseUnsigned ({ image, version, digest, named, reasons }) {
+  const why = reasons.length ? ` (${reasons.slice(0, 3).join('; ')})` : ''
+  if (named) refuse(`${image}:${version} (${digest}) carries no signature from Martha's release workflow for ${releaseRef(version)}${why}; refused`)
+  return refuse(`the highest version on ${image}, ${version} (${digest}), carries no signature from Martha's release workflow${why}; refused. Name a version: ${NAMES.command}-install <version>`)
+}
+
+/**
+ * The steps in the order the top of this file lists them; nothing is linked until every one has passed.
+ * @param {InstallRequest} request
+ */
+export async function installRelease (request) {
+  checkNodeVersion(request.nodeVersion ?? process.versions.node)
+  checkRequest(request)
+  const image = request.image ?? NAMES.image
+  const reg = registry({ image, ...(request.base && { base: request.base }), ...(request.fetch && { fetch: request.fetch }) })
+  const chosen = await chosenRelease(request, reg, image)
+  const signer = await signerOf(request, reg, chosen)
+  const { release, command } = await placedRelease(request, reg, chosen)
+  const log = request.log ?? console.log
+  log(`martha: ${chosen.version}, ${image}@${chosen.digest}`)
+  log(`martha: signed by attest-image.yml@${signer} for ${NAMES.sourceRepository} ${releaseRef(chosen.version)}`)
+  log(`martha: ${request.places.current} -> ${release}`)
+  log(`martha: ${command}`)
+  return { version: chosen.version, digest: chosen.digest, signer, release, command }
+}
+
+/**
+ * @typedef {ReturnType<typeof registry>} Registry
+ * @typedef {{ image: string, version: string, digest: string, named: boolean, manifest: Awaited<ReturnType<Registry['manifest']>> }} ChosenRelease
+ */
+
+/**
+ * Steps 2 and 3: the version and its manifest, whose digest is the release from here on; the digest the user
+ * verified, when given, and the one downgrade rule.
+ * @param {InstallRequest} request
+ * @param {Registry} reg
+ * @param {string} image
+ * @returns {Promise<ChosenRelease>}
+ */
+async function chosenRelease (request, reg, image) {
+  const named = request.version !== undefined
+  await reg.authorize()
+  const version = request.version ?? await reg.highestVersion()
+  const manifest = await reg.manifest(version)
+  const digest = manifest.digest
+  if (request.digest && request.digest !== digest) refuse(`${image}:${version} is ${digest} now, not the ${request.digest} you verified; refused`)
+  await checkAgainstInstalled({ version, digest, downgrade: request.downgrade ?? false, named, places: request.places })
+  return { image, version, digest, named, manifest }
+}
+
+/**
+ * Step 4: the signature on the release's digest, by a listed signer; the signing workflow's commit, or a refusal.
+ * @param {InstallRequest} request
+ * @param {Registry} reg
+ * @param {ChosenRelease} chosen
+ */
+async function signerOf (request, reg, chosen) {
+  const { version, digest } = chosen
+  const signers = request.signers ?? await listedSigners()
+  const bundles = await bundlesOf(reg, chosen)
+  const verdict = await signedBy({ bundles, digest, version, signers, ...(request.makeVerifier && { makeVerifier: request.makeVerifier }), tufCachePath: request.tufCachePath })
+  if (!('sha' in verdict)) refuseUnsigned({ ...chosen, reasons: verdict.reasons })
+  return verdict.sha
+}
+
+/**
+ * The signature bundles stored for the release's digest. A registry that could not be asked stays that fault;
+ * anything else it says is a release with no signature, refused.
+ * @param {Registry} reg
+ * @param {ChosenRelease} chosen
+ */
+async function bundlesOf (reg, chosen) {
+  try {
+    return await reg.bundles(chosen.digest)
+  } catch (error) {
+    if (error instanceof CouldNotCheck) throw error
+    return refuseUnsigned({ ...chosen, reasons: [error instanceof Error ? error.message : String(error)] })
+  }
+}
+
+/**
+ * Steps 5 to 7: the one layer by digest, unpacked into its own read-only directory, current swapped to it, the
+ * command linked through current.
+ * @param {InstallRequest} request
+ * @param {Registry} reg
+ * @param {ChosenRelease} chosen
+ */
+async function placedRelease (request, reg, { image, version, digest, manifest }) {
+  const layer = layerOf(manifest.json, `${image}@${digest}`)
+  const release = await placeRelease({
+    releases: request.places.releases,
+    name: releaseName(version, digest),
+    unpack: async (stage) => unpackLayer(await reg.blob(layer, `the layer ${layer.digest}`), stage)
+  })
+  await swapLink(release, request.places.current)
+  const command = await linkCommand({ release, places: request.places })
+  return { release, command }
+}

package/keep_the_names_in_one_place/names.mjs

@@ -0,0 +1,49 @@
+// The public names, read from ONE place: the "martha" field of this package's package.json (martha#21). The npm
+// name, the image, the repository a release must come from, the workflow that signs it, the command and both tag
+// prefixes are written there and nowhere else; names.node-test.mjs fails when a workflow, the root package.json or
+// the README drifts from them. The installer this one replaces was renamed twice in one evening; this is why.
+import { createRequire } from 'node:module'
+
+const manifest = createRequire(import.meta.url)('../package.json')
+
+/**
+ * @typedef {object} Names
+ * @property {string} npmName           the installer's npm name, what a user types
+ * @property {string} installerVersion  this installer's own version
+ * @property {string} nodeRange         the Node versions it runs on, as engines.node says
+ * @property {string} image             the release's OCI repository, no tag
+ * @property {string} sourceRepository  the repository every release is built from
+ * @property {string} signerWorkflow    the workflow that signs a release, without the commit it is pinned at
+ * @property {string} issuer            the OIDC issuer of the signing certificate
+ * @property {string} command           the command an installed release puts on PATH
+ * @property {string} releaseFolder     the one top-level folder a release's layer holds
+ * @property {string} releaseTagPrefix  what a release tag starts with
+ * @property {string} installerTagPrefix what an installer tag starts with
+ * @property {string} installerPublishWorkflow the workflow whose run publishes this installer, and signs that publish
+ * @property {string} dryRunTagPrefix  what a dry run's image tag starts with: never a version, never a release tag
+ */
+
+/** @type {Readonly<Names>} */
+export const NAMES = Object.freeze({
+  npmName: manifest.name,
+  installerVersion: manifest.version,
+  nodeRange: manifest.engines.node,
+  ...manifest.martha
+})
+
+/** @param {string} version */
+export const releaseRef = (version) => `refs/tags/${NAMES.releaseTagPrefix}${version}`
+
+/**
+ * The git ref an installer version's publish ran at: what its provenance must name (martha#84).
+ * @param {string} version
+ */
+export const installerRef = (version) => `refs/tags/${NAMES.installerTagPrefix}${version}`
+
+/**
+ * Who a Fulcio certificate must have been issued to, as the whole identity: the repository, the workflow and the
+ * ref, exactly. Anchored and escaped, because sigstore-js tests a SAN policy as a JavaScript regular expression
+ * (@sigstore/verify policy.js).
+ * @param {string} identity
+ */
+export const anchoredIdentity = (identity) => `^${identity.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`

package/node_modules/@gar/promise-retry/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Tim Koschützki (tim@debuggable.com), Felix Geisendörfer (felix@debuggable.com)
+Copyright (c) 2014 IndigoUnited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.