curiouspub 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Curious Pub
+
+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.

package/README.md

@@ -0,0 +1,106 @@
+# curiouspub
+
+The npm wrapper for [`curious`](https://github.com/curiouspub/cli) — the
+command line tool for [curious.pub](https://curious.pub).
+
+**Your agent builds. You approve. It ships.**
+
+```
+npx curiouspub deploy
+```
+
+The package name is `curiouspub`; the command it installs is `curious`.
+They are different names on purpose — `npx curiouspub` is the
+run-without-installing form, and `curious` is what you type once it is
+installed.
+
+## What the install does
+
+This package contains no binary. Its postinstall script downloads the
+release build for your platform, checks it, and puts it beside itself.
+
+Supported: macOS, Linux and Windows, on x64 and arm64. Anything else
+fails the install with a message saying so, rather than succeeding and
+leaving you with a command that is not there.
+
+Node 22 or newer. The install script checks that before it does
+anything else, because a version check that runs after the download has
+let the thing it was guarding already happen.
+
+## How the download is checked, and what that is worth
+
+A postinstall script that downloads and runs a binary is, mechanically,
+what a malicious package does. The difference is entirely in what
+vouches for the bytes, so it is worth stating exactly:
+
+- **The digest is inside this package.** `checksums.json` is written
+  when the package is published, from the same run that built the
+  binaries, and the download is refused unless it matches. So a release
+  asset **replaced after publication** fails the check — the digest is
+  vouched for by the registry, not by the host serving the download.
+- **That is the whole claim.** It assumes this npm package is itself
+  authentic, and it says nothing about a compromised publisher or a
+  compromised release run: a run that builds a binary and its checksum
+  together will vouch for its own output. That residual is not closable
+  by anything a dependency-free install script can do, and this package
+  does not pretend otherwise.
+- **A missing digest is refused too**, and it is not the same thing as a
+  mismatch: it means the package was built wrong, and it stops before
+  anything is downloaded.
+- **The release is also signed** over its checksum file, keylessly, by
+  the workflow that produced it. That signature is there for an auditor
+  with the verifying tool. This script does not check it and does not
+  claim to.
+- **npm provenance** ties the published package to the workflow that
+  built it. That is checkable on the registry page.
+
+## Zero dependencies, and why
+
+The install script uses Node's standard library and nothing else. That
+is part of the argument rather than a preference: a reader can audit the
+whole of `install.js` in one sitting, which is the only real answer to
+"why should I let this run on my machine".
+
+The same reasoning is why the proxy support is a hand-written tunnel
+rather than a package.
+
+## Behind a proxy
+
+`npm_config_https_proxy` and `npm_config_proxy` are read first, then
+`HTTPS_PROXY` and `https_proxy`; `npm_config_no_proxy` and `NO_PROXY`
+are honoured, including the `*` and leading-dot forms.
+
+A bypass entry names **one host**, and the leading dot is what widens
+it: `example.com` covers that host alone, while `.example.com` covers it
+and everything under it. An entry may carry a port, and then it matches
+only that port. The distinction decides between a tunnel and a direct
+connection, so it errs towards the proxy: an entry that matched more
+hosts than it names would send the download direct on a machine whose
+policy says tunnel.
+
+If a proxy is configured and the tunnel fails, **the install fails and
+names the proxy**. It never quietly connects directly instead: on a
+machine where direct access is blocked that would be a bypass nobody
+asked for.
+
+If your proxy inspects TLS, point `NODE_EXTRA_CA_CERTS` at your
+organisation's certificate authority file. That is the supported route,
+and it is the only one — nothing in this package can turn certificate
+verification off.
+
+## If the install did not run
+
+Installing with `--ignore-scripts` skips the download, and the command
+then says so rather than failing with a stack trace. Install again
+without it, or take a binary from the
+[releases page](https://github.com/curiouspub/cli/releases).
+
+## No telemetry
+
+None. No analytics, no phone-home, no auto-update, no lifecycle script
+other than the postinstall. The tool talks to the API you point it at
+and to nothing else.
+
+## License
+
+MIT

package/bin/curious.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+'use strict';
+
+// The command `curious` becomes once this package is installed. It runs
+// the binary the postinstall downloaded and reports what happened.
+//
+// ON WINDOWS THIS IS THE SECOND OF THREE LAYERS, which is worth knowing
+// before debugging why an argument arrived quoted: npm writes its own
+// .cmd and .ps1 wrappers, those invoke node on this file, and this file
+// spawns curious.exe. The shebang above matters only on Unix.
+//
+// IT FORWARDS NO SIGNALS, and that is a decision rather than an
+// omission. On a POSIX terminal Ctrl-C goes to the foreground process
+// GROUP, which the child has already joined, so forwarding delivers it
+// twice. On Windows the signal argument to kill is ignored and the
+// process is destroyed outright, so "forwarding an interrupt" there is
+// a hard kill wearing a polite name — while a console interrupt already
+// reaches the child as a console event. Both platforms already do the
+// right thing.
+//
+// What it owes instead is the exit story below.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const pkg = require('../package.json');
+const { binaryName } = require('../lib/platform');
+
+const root = path.join(__dirname, '..');
+
+// The SAME helper the install script renamed the download with. Two
+// expressions for one name is how a package installs successfully and
+// then cannot find what it installed.
+const binary = path.join(root, binaryName(process.platform));
+
+// refuse says what is wrong and what to do about it, and never throws.
+// A stack trace here would describe this file to somebody who wants to
+// know why their command did not run.
+function refuse(what) {
+  console.error(
+    `\ncurious is not installed properly: ${what}\n\n` +
+    'The binary is downloaded by this package\'s postinstall script, so this\n' +
+    'usually means the install ran with --ignore-scripts.\n\n' +
+    'Install again without it:\n\n' +
+    '  npm install --global curiouspub\n\n' +
+    'or take a binary from https://github.com/curiouspub/cli/releases\n');
+  process.exit(1);
+}
+
+// THE MARKER IS CHECKED BEFORE THE BINARY IS RUN, and the version it
+// carries is compared rather than merely present. A failed upgrade in a
+// directory that already held an older release leaves that release's
+// binary sitting under the right name; without this the shim would run
+// it and the person would be using a version they did not install.
+let marker = null;
+try {
+  marker = JSON.parse(fs.readFileSync(path.join(root, 'installed.json'), 'utf8'));
+} catch {
+  marker = null;
+}
+if (!marker || marker.version !== pkg.version) {
+  refuse(marker
+    ? `the binary beside it was installed for version ${marker.version}, ` +
+      `and this is ${pkg.version}`
+    : 'the postinstall step has not run');
+}
+
+// stdio: 'inherit' IS the forwarding. Input, output and errors are the
+// child's own file descriptors, so nothing here reads or rewrites what
+// passes through — which matters for a tool whose output somebody
+// redirects to a file.
+//
+// shell: false keeps argv exactly as it arrived. A command interpreter
+// would re-parse it, and a project directory with a space in its name
+// would reach the binary as two arguments.
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit', shell: false });
+
+child.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    refuse('the downloaded binary is not there');
+  }
+  refuse(`the binary could not be started (${err.code || err.message})`);
+});
+
+// A process that died of a signal has no exit code. The shell's own
+// convention for that is 128 plus the signal number, and reporting a
+// bare 1 instead loses the difference between "it failed" and "somebody
+// interrupted it".
+child.on('exit', (code, signal) => {
+  if (code !== null) {
+    process.exitCode = code;
+    return;
+  }
+  const number = os.constants.signals[signal];
+  process.exitCode = number ? 128 + number : 1;
+});

package/checksums.json

@@ -0,0 +1,8 @@
+{
+  "curious_0.1.0_darwin_amd64.gz": "db1a437b7bafb2422dea4bc8e91babc56d36923614970f90f22f0c7fcc3d1768",
+  "curious_0.1.0_darwin_arm64.gz": "af5e75e70603e13f174c8d5a48bba3569f485d83c12736c90b57197dcaf7e00a",
+  "curious_0.1.0_linux_amd64.gz": "150d4dd647e815ea18a428a6839aa99092a9e914558f74b1a021c75f8c0523bd",
+  "curious_0.1.0_linux_arm64.gz": "0ceaf92b4c4bf0d039676365a91fa358db6af90a1a0cb837dbc472b767d6206b",
+  "curious_0.1.0_windows_amd64.gz": "1bdf422f69bf093d519010285818cf5deb9f197ba8efb52cba52093b950d3277",
+  "curious_0.1.0_windows_arm64.gz": "d883fa36ae384c9f75d14e77b62e845c72b919c353d2cd73255d3c4b22a95144"
+}

package/install.js

@@ -0,0 +1,974 @@
+#!/usr/bin/env node
+'use strict';
+
+// Fetch the curious binary this machine can run, check it against a
+// digest that shipped inside this package, and put it in place.
+//
+// WHAT VOUCHES FOR WHAT, because a script that downloads and executes a
+// binary is mechanically what a malicious package does, and the whole
+// difference is here:
+//
+//   - Transport is TLS to the release host. That says the bytes arrived
+//     unaltered from whoever answered.
+//   - The SHA-256 comes from checksums.json, which is inside the npm
+//     package you already installed. It is written when the package is
+//     published, from the same run that built the binaries. So a
+//     release asset REPLACED AFTER PUBLICATION fails this check,
+//     because the digest is vouched for by the registry rather than by
+//     the host serving the download.
+//   - That is the whole claim, and it is narrower than it may sound. It
+//     assumes this npm package is itself authentic. It says nothing
+//     about a compromised publisher or a compromised release run: a run
+//     that builds a binary and its checksum together will happily vouch
+//     for its own output. That residual is not closable by anything a
+//     dependency-free install script can do.
+//   - The release is also signed, keylessly, over its checksum file.
+//     That signature is for an auditor with the verifying tool. This
+//     script does not check it and does not pretend to.
+//
+// NO DEPENDENCIES, and that is part of the argument rather than a
+// preference. Everything here is Node's standard library, so a reader
+// can audit the whole thing in one sitting — which is the only real
+// answer to "why should I let this run on my machine". It is also why
+// the proxy support further down is thirty lines of tunnel rather than
+// a package: there is no built-in proxy support to switch on, so the
+// choice was a dependency tree inside a postinstall or this.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const http = require('node:http');
+const https = require('node:https');
+const net = require('node:net');
+const path = require('node:path');
+const tls = require('node:tls');
+const zlib = require('node:zlib');
+
+const pkg = require('./package.json');
+const platform = require('./lib/platform');
+const loopback = require('./loopback-hosts.json');
+
+// Where the release lives. CURIOUS_RELEASE_BASE_URL replaces it, which
+// is what makes this script testable against a server on this machine.
+//
+// EXPOSING THAT OVERRIDE IS SAFE BECAUSE OF WHAT SITS BEHIND IT: the
+// digest is embedded in this package, so pointing the download
+// somewhere else can only ever produce a MISMATCH. There is no origin
+// an attacker can name that makes a substituted binary verify.
+const DEFAULT_RELEASE_BASE = 'https://github.com/curiouspub/cli/releases/download';
+
+// Thirty seconds for one whole attempt, redirects included.
+//
+// IT IS A DEADLINE PER ATTEMPT AND NOT PER HOP: a chain of redirects
+// would otherwise multiply a bound nobody chose. It is not a total
+// across attempts either — a retry gets a fresh one, because the thing
+// being bounded is "this fetch is not going to work", and the second
+// fetch is a different fetch.
+//
+// The number is chosen for what it bounds HERE, and deliberately not
+// carried from anywhere else in this project. The asset is a few
+// megabytes; thirty seconds covers it down to roughly a megabit per
+// second, which is the slowest link on which installing a development
+// tool is a reasonable thing to be doing.
+const ATTEMPT_TIMEOUT_MS = 30_000;
+
+// Three attempts, and therefore TWO waits — three attempts have two
+// gaps between them, and a third backoff term would never be reached.
+//
+// A second, and then two. It is sized for a delivery-network blip or a
+// failover, which is what a storage host that has just failed is likely
+// to be doing. The quarter-second pause this project uses before
+// re-asking an endpoint that answers in milliseconds is the number NOT
+// to reuse here: right for smoothing a stalled small request, absurd as
+// a pause before re-asking a file server.
+//
+// Worst case is therefore ninety-three seconds. That is derived, not a
+// third constant, and nothing here compares against it.
+const ATTEMPTS = 3;
+const BACKOFF_MS = [1_000, 2_000];
+
+// How many redirects one attempt will follow. The release host hands
+// downloads to a storage host, which is one hop; five leaves room for a
+// chain nobody planned while still making a loop terminate, which is
+// the only thing a bound is really for.
+const MAX_REDIRECTS = 5;
+
+// ---------------------------------------------------------------------
+// Stopping.
+// ---------------------------------------------------------------------
+
+// Refused carries a message already written for a person. Everything
+// that decides to stop throws one, and exactly one place prints it, so
+// there is a single answer to "what does a failed install look like".
+class Refused extends Error {}
+
+// Retryable is a failure worth asking about again. The difference from
+// Refused decides whether the two waits happen at all: a 404 will say
+// the same thing in a second's time, and a reset connection may not.
+class Retryable extends Error {}
+
+// ---------------------------------------------------------------------
+// Step 0: the Node floor, before anything else and before any network.
+// ---------------------------------------------------------------------
+
+// THE DECLARED FLOOR IS THE ONLY FLOOR. It is read out of this
+// package's own engines field rather than written again here, so there
+// is one number and a change to it moves the check with it.
+//
+// engines ALONE IS NOT A FLOOR: npm only warns about it unless the
+// person installing has asked for strictness, so the check has to
+// happen here. And it has to happen FIRST — a version check that runs
+// after the download has let the thing it was guarding already happen.
+function requireNodeFloor() {
+  const declared = (pkg.engines && pkg.engines.node) || '';
+  const stated = /^>=\s*(\d+)/.exec(declared);
+  if (!stated) {
+    throw new Refused(
+      `This package declares a Node requirement of "${declared}", which this\n` +
+      'installer cannot read. That means the package was built wrong rather\n' +
+      'than anything about your machine. Please report it.');
+  }
+  const floor = Number(stated[1]);
+  const found = process.versions.node;
+  if (Number(found.split('.')[0]) < floor) {
+    throw new Refused(
+      `curious needs Node ${declared} and this is Node ${found}.\n\n` +
+      `Upgrade Node to ${floor} or newer and install again. Nothing has been\n` +
+      'downloaded.');
+  }
+}
+
+// ---------------------------------------------------------------------
+// Step 1: what to fetch, and what its digest must be.
+// ---------------------------------------------------------------------
+
+function resolveTarget() {
+  const asset = platform.assetName(pkg.version, process.platform, process.arch);
+  if (!asset) {
+    throw new Refused(platform.unsupportedMessage(process.platform, process.arch));
+  }
+  return { asset, binary: platform.binaryName(process.platform) };
+}
+
+// expectedDigest looks the asset up BEFORE any network call.
+//
+// AN ABSENT DIGEST IS NOT A MISMATCH, and it is not the same branch.
+// A table with no entry for this platform means the package was built
+// wrong — a stale file, a generator that emitted different names — and
+// the shape everyone writes by accident, "if there is a digest and it
+// differs, refuse", installs whatever arrived. So a missing entry stops
+// here, naming the key it wanted, before anything is fetched.
+function expectedDigest(asset) {
+  const file = path.join(__dirname, 'checksums.json');
+  let table;
+  try {
+    table = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new Refused(
+      `The checksum table that ships with this package could not be read:\n\n  ${err.message}\n\n` +
+      'That is a fault in the package rather than anything about your\n' +
+      'machine. Please report it.');
+  }
+  const digest = table[asset];
+  if (typeof digest !== 'string' || !/^[0-9a-f]{64}$/.test(digest)) {
+    throw new Refused(
+      `This package carries no checksum for ${asset}.\n\n` +
+      'Every supported platform is meant to have one, so this package was\n' +
+      'built wrong and curious will not install a binary it cannot check.\n' +
+      'Please report it.');
+  }
+  return digest;
+}
+
+// ---------------------------------------------------------------------
+// The scheme rule. ONE rule, applied to the first address and to every
+// hop after it.
+//
+// It is one rule rather than two on purpose. "https everywhere, except
+// the first address may be loopback http" makes a loopback server that
+// issues a redirect abort on its own redirect — which is the ordinary
+// way anybody would exercise redirects on their own machine.
+// ---------------------------------------------------------------------
+
+// A host is loopback if it is in the set this project keeps in one
+// place, in loopback-hosts.json, which the Go client's own copy is held
+// equal to by a test.
+//
+// THE BRACKETS COME OFF FIRST. A URL parser reports an address literal
+// with its brackets on and the set holds the address without them, so
+// without this an origin the rule means to allow is refused for a
+// reason nobody could see.
+function unbracket(hostname) {
+  return hostname.startsWith('[') && hostname.endsWith(']')
+    ? hostname.slice(1, -1)
+    : hostname;
+}
+
+function isLoopback(hostname) {
+  return loopback.hosts.includes(unbracket(hostname).toLowerCase());
+}
+
+function checkScheme(url, where) {
+  if (url.protocol === 'https:') {
+    return;
+  }
+  if (url.protocol === 'http:' && isLoopback(url.hostname)) {
+    return;
+  }
+  throw new Refused(
+    `${where} is ${url.protocol}//${url.host}, and curious will only download\n` +
+    'over https — or over plain http to this machine, which is there for\n' +
+    'local development.\n\n' +
+    'Nothing has been downloaded.');
+}
+
+function releaseBase() {
+  const override = process.env.CURIOUS_RELEASE_BASE_URL;
+  if (!override) {
+    return DEFAULT_RELEASE_BASE;
+  }
+  let url;
+  try {
+    url = new URL(override);
+  } catch {
+    throw new Refused(
+      'CURIOUS_RELEASE_BASE_URL is not a URL. Unset it to use the real release.');
+  }
+  checkScheme(url, 'The release origin CURIOUS_RELEASE_BASE_URL names');
+  return override.replace(/\/+$/, '');
+}
+
+// The tag keeps its leading v and the asset name does not. They are the
+// same version in two spellings inside one address, and getting it
+// wrong is a 404 nobody can explain.
+function downloadURL(asset) {
+  return `${releaseBase()}/v${pkg.version}/${asset}`;
+}
+
+// ---------------------------------------------------------------------
+// Step 3: the download.
+// ---------------------------------------------------------------------
+
+// ---------------------------------------------------------------------
+// Proxies.
+//
+// Node's https client ignores every proxy variable there is: there is
+// no built-in support to switch on, so the choice was a dependency
+// inside a postinstall or the thirty lines below. Given that this
+// script's whole security argument is that a reader can audit it in one
+// sitting, thirty auditable lines beat a dependency tree.
+// ---------------------------------------------------------------------
+
+// NPM'S OWN SETTINGS COME FIRST. Somebody who configured npm expects
+// that to be honoured, and npm resolves its own configuration ahead of
+// the ambient environment.
+const PROXY_VARIABLES = [
+  'npm_config_https_proxy', 'npm_config_proxy', 'HTTPS_PROXY', 'https_proxy',
+];
+const NO_PROXY_VARIABLES = ['npm_config_no_proxy', 'NO_PROXY', 'no_proxy'];
+
+function firstSet(names) {
+  for (const name of names) {
+    const value = process.env[name];
+    if (typeof value === 'string' && value.trim() !== '') {
+      return { name, value: value.trim() };
+    }
+  }
+  return null;
+}
+
+function defaultPort(url) {
+  return url.port || (url.protocol === 'https:' ? '443' : '80');
+}
+
+// splitEntry reads one NO_PROXY entry into a host and an optional port,
+// keeping an address literal's colons out of the port's way.
+function splitEntry(entry) {
+  if (entry.startsWith('[')) {
+    const close = entry.indexOf(']');
+    return {
+      host: entry.slice(1, close),
+      port: entry.slice(close + 1).replace(/^:/, ''),
+    };
+  }
+  const colon = entry.indexOf(':');
+  if (colon >= 0 && entry.indexOf(':', colon + 1) < 0) {
+    return { host: entry.slice(0, colon), port: entry.slice(colon + 1) };
+  }
+  return { host: entry, port: '' };
+}
+
+// Host and domain matching, with the three forms people actually write:
+// a bare host, a leading dot for "and everything under it", and the
+// wildcard that turns proxying off altogether.
+function bypassed(url) {
+  const rule = firstSet(NO_PROXY_VARIABLES);
+  if (!rule) {
+    return false;
+  }
+  const host = unbracket(url.hostname).toLowerCase();
+  const port = defaultPort(url);
+  for (const raw of rule.value.split(',')) {
+    const entry = raw.trim().toLowerCase();
+    if (!entry) {
+      continue;
+    }
+    if (entry === '*') {
+      return true;
+    }
+    const parsed = splitEntry(entry);
+    if (parsed.port && parsed.port !== port) {
+      continue;
+    }
+    // THE DOT IS THE WHOLE DIFFERENCE BETWEEN TWO OF THE THREE FORMS,
+    // and taking it off before the comparison collapses them: every
+    // entry becomes a domain-wide one, so a bare example.com bypasses
+    // evil.example.com as well.
+    //
+    // THAT ERROR RUNS IN THE DANGEROUS DIRECTION. It turns the proxy
+    // OFF for hosts nobody exempted, so on a machine whose egress is
+    // controlled the download goes direct where the policy said tunnel
+    // — the same thing this script refuses to do when a tunnel fails,
+    // arriving from the other side: not falling back to direct, but
+    // never choosing the proxy at all.
+    const under = parsed.host.startsWith('.');
+    const wanted = under ? parsed.host.slice(1) : parsed.host;
+    if (host === wanted || (under && host.endsWith(`.${wanted}`))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// maskProxy renders a proxy address for a message. The password is the
+// half that must never be printed; the username stays, because a person
+// reading a failure needs to recognise which setting is in play.
+function maskProxy(url) {
+  const shown = new URL(url.toString());
+  if (shown.password) {
+    shown.password = '***';
+  }
+  return shown.toString();
+}
+
+function proxyFailure(proxy, why) {
+  return (
+    `curious is set up to reach the release through a proxy, and ${why}.\n\n` +
+    `  ${proxy.name}=${maskProxy(proxy.url)}\n\n` +
+    'curious will not connect directly instead. On a machine where direct\n' +
+    'access is blocked that would be a bypass nobody asked for, and where it\n' +
+    'is not, it would hide the real problem behind a slower one.\n\n' +
+    'Nothing was downloaded.');
+}
+
+// proxyFor decides, for THIS address, whether a proxy applies. It is
+// asked again on every redirect: a redirect that crosses hosts leaves
+// the old tunnel pointing at the wrong origin.
+//
+// A PERMITTED PLAIN-HTTP ADDRESS IS A PLAIN REQUEST. Tunnelling is for
+// https, and the only http this script will touch at all is loopback.
+function proxyFor(url) {
+  if (url.protocol !== 'https:') {
+    return null;
+  }
+  const configured = firstSet(PROXY_VARIABLES);
+  if (!configured) {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = new URL(configured.value);
+  } catch {
+    throw new Refused(
+      `The proxy address in ${configured.name} is not a URL.\n\n` +
+      'Fix it or unset it; curious will not ignore a proxy that was\n' +
+      'configured on purpose.');
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    // REFUSED RATHER THAN TREATED AS HTTP. Guessing at a scheme this
+    // script does not speak would dial the proxy with the wrong
+    // protocol and report whatever came back as a network fault.
+    throw new Refused(
+      `The proxy address in ${configured.name} uses the ` +
+      `${parsed.protocol.replace(':', '')} scheme, which curious does not speak.\n\n` +
+      `  ${configured.name}=${maskProxy(parsed)}\n\n` +
+      'curious tunnels through http and https proxies only. Nothing was\n' +
+      'downloaded.');
+  }
+  if (bypassed(url)) {
+    return null;
+  }
+  return { name: configured.name, url: parsed };
+}
+
+// proxyAuthorization renders the credentials an address carries into the
+// header the proxy expects.
+//
+// A CREDENTIAL THAT CANNOT BE READ IS THE PROXY'S PROBLEM AND NOT THE
+// NETWORK'S. Percent-decoding throws on a half-written escape — a
+// mistyped password, an address edited by hand — and a throw nobody
+// classified is a fault worth trying again, so a person with a typo in
+// their proxy password was told three times over to check their
+// connection, with the proxy named nowhere in it. This package's own
+// rule is that a configured proxy is never quietly ignored and that a
+// failure says which variable was read; an unreadable password is that
+// rule's case exactly.
+//
+// The value is never in the message. maskProxy keeps the username,
+// because a person reading a failure needs to recognise which setting
+// is in play, and replaces the half that must not be printed.
+function proxyAuthorization(proxy) {
+  let user;
+  let secret;
+  try {
+    user = decodeURIComponent(proxy.url.username);
+    secret = decodeURIComponent(proxy.url.password);
+  } catch {
+    throw new Refused(proxyFailure(proxy,
+      'the credentials in that address cannot be read — a percent sign begins\n' +
+      'an escape, and one in there never finishes one'));
+  }
+  return `Basic ${Buffer.from(`${user}:${secret}`).toString('base64')}`;
+}
+
+// openTunnel asks the proxy to join us to the target and hands back the
+// raw socket. THE PORT COMES FROM THE ADDRESS rather than a hard-coded
+// 443, and the address literal keeps its brackets here — a CONNECT line
+// is a host and a port, and an unbracketed literal is neither.
+function openTunnel(proxy, target, signal, sockets) {
+  return new Promise((resolve, reject) => {
+    const module = proxy.url.protocol === 'https:' ? https : http;
+    const authority = `${target.hostname}:${defaultPort(target)}`;
+    const headers = { host: authority };
+    if (proxy.url.username) {
+      headers['proxy-authorization'] = proxyAuthorization(proxy);
+    }
+    // A proxy may itself be reached at an address literal and speak TLS,
+    // which is the same identity check one connection earlier.
+    const request = module.request(withIdentity({
+      host: unbracket(proxy.url.hostname),
+      port: defaultPort(proxy.url),
+      method: 'CONNECT',
+      path: authority,
+      headers,
+      signal,
+    }, unbracket(proxy.url.hostname)));
+    request.on('socket', (socket) => sockets.add(socket));
+
+    // THE STATUS IS CHECKED. Without this a refusal surfaces as a
+    // bewildering TLS error about a handshake that never happened,
+    // because the bytes of an HTTP error page are not a server hello.
+    request.on('connect', (response, socket, head) => {
+      sockets.add(socket);
+      if (response.statusCode !== 200) {
+        socket.destroy();
+        reject(new Refused(proxyFailure(proxy,
+          `it answered ${response.statusCode} to the request to open a tunnel`)));
+        return;
+      }
+      if (head && head.length) {
+        // Bytes the proxy handed back with the response belong to the
+        // tunnel, and dropping them corrupts the first record of the
+        // TLS handshake.
+        socket.unshift(head);
+      }
+      resolve(socket);
+    });
+    request.on('response', (response) => {
+      discard(response);
+      reject(new Refused(proxyFailure(proxy,
+        `it answered ${response.statusCode} to the request to open a tunnel`)));
+    });
+    request.on('error', (err) => reject(new Refused(proxyFailure(proxy,
+      `the connection to it failed (${err.code || err.message})`))));
+    request.end();
+  });
+}
+
+// ADDRESS LITERALS AND THE PLATFORM'S IDENTITY CHECK.
+//
+// A host may be an address rather than a name, and a certificate says
+// so with an IP entry rather than a DNS one. Between Node v22.23.2 and
+// v24.20.0 the platform cannot make that comparison for an IPv6
+// literal: checkServerIdentity normalises the host through IDNA before
+// deciding whether it is an address (v22.23.2 lib/tls.js:408 and :430),
+// and domainToASCII of an IPv6 literal is the empty string — so the
+// certificate's address entries are never consulted, the literal is
+// compared against the DNS names instead, and that question always
+// answers no. Fixed upstream in v24.20.0 (lib/tls.js:434-441, whose
+// comment says exactly this). The v22 line still carries it at
+// v22.23.2, and v22 is this package's declared floor.
+//
+// Measured on one machine over five builds — v22.22.3 accepts,
+// v22.23.2 refuses, v24.19.0 refuses, v24.20.0 accepts, v26.3.0
+// accepts — and printed from inside both CI legs that failed on it.
+//
+// WHICH REAL PATHS PUT AN ADDRESS THERE, since a mechanism in a script
+// somebody is meant to audit has to be reachable by a user and not only
+// by a row. Three, and none of them needs a test harness:
+//
+//   1. CURIOUS_RELEASE_BASE_URL. releaseBase() sends it to checkScheme
+//      above, which returns on `https:` and asks nothing about the
+//      host — so https://[2001:db8::1]/dl is an accepted release
+//      origin, and it reaches TLS at sendGet or, behind a proxy, at
+//      secureThrough.
+//   2. THE PROXY VARIABLES — npm_config_https_proxy, npm_config_proxy,
+//      HTTPS_PROXY, https_proxy. proxyFor() permits exactly the http
+//      and https schemes and likewise asks nothing about the host, so
+//      an https proxy given by address reaches TLS at openTunnel. A
+//      proxy named by IP rather than by name is ordinary in a corporate
+//      network, which makes this the likeliest of the three.
+//   3. A REDIRECT, which is not the user's choice at all. The download
+//      host may answer with a Location the loop resolves and follows,
+//      and the per-hop checkScheme permits any https host.
+//
+// THE REPAIR CANNOT ACCEPT ANYTHING THE PLATFORM SHOULD REFUSE. It
+// runs only after the platform has already refused, only when the name
+// under check is itself an address, and it hands the comparison to
+// OpenSSL's own iPAddress matching rather than doing string work here
+// — the same comparison the fixed platform makes. On a version without
+// the defect it never runs, because there is no refusal to reconsider.
+function addressIdentity(host) {
+  if (!net.isIP(host)) {
+    return null;
+  }
+  return (name, cert) => {
+    const refusal = tls.checkServerIdentity(name, cert);
+    if (!refusal || !net.isIP(name) || !cert || !cert.raw) {
+      return refusal;
+    }
+    try {
+      return new crypto.X509Certificate(cert.raw).checkIP(name) ? undefined : refusal;
+    } catch {
+      // A certificate this platform will not parse is not a reason to
+      // overrule it. The refusal stands.
+      return refusal;
+    }
+  };
+}
+
+// withIdentity sets the option only when there is one to set. Node
+// installs its default by spreading a defaults object, so a key that is
+// present and undefined REPLACES the default with nothing and the
+// handshake throws where it should have checked.
+function withIdentity(options, host) {
+  const identity = addressIdentity(host);
+  if (identity) {
+    options.checkServerIdentity = identity;
+  }
+  return options;
+}
+
+// secureThrough wraps a tunnel in TLS for the real target.
+//
+// THE NAME IS NOT OPTIONAL AND IT IS NOT ALWAYS A NAME. Without a
+// server name the handshake reaches a host that serves many and gets
+// the wrong certificate, which fails in a way that looks like a network
+// fault. But the standard library REFUSES an address literal as a
+// server name — measured, not assumed — because the specification does
+// not permit one, so a literal is passed as the host to check against
+// instead, unbracketed, which is the spelling a certificate carries.
+function secureThrough(tunnel, target, sockets) {
+  return new Promise((resolve, reject) => {
+    const host = unbracket(target.hostname);
+    const options = withIdentity({ socket: tunnel, host }, host);
+    if (!net.isIP(host)) {
+      options.servername = host;
+    }
+    const secure = tls.connect(options);
+    sockets.add(secure);
+    secure.once('secureConnect', () => resolve(secure));
+    secure.once('error', reject);
+  });
+}
+
+// sendGet issues one request and hands back the response headers. The
+// body is left unread so the caller can decide whether to keep it.
+//
+// A TUNNELLED REQUEST NEEDS AN AGENT rather than a bare option: a
+// client request with an agent asks the agent for its socket, and
+// options.createConnection is only consulted when there is no agent at
+// all — which `agent: false` does not produce, since it quietly makes a
+// fresh one.
+function sendGet(url, signal, sockets, socket) {
+  return new Promise((resolve, reject) => {
+    const module = url.protocol === 'https:' ? https : http;
+    const options = {
+      method: 'GET',
+      signal,
+      headers: { 'user-agent': `curiouspub/${pkg.version}` },
+    };
+    if (socket) {
+      const agent = new https.Agent({ keepAlive: false, maxSockets: 1 });
+      agent.createConnection = () => socket;
+      options.agent = agent;
+    } else if (url.protocol === 'https:') {
+      // The direct route reaches TLS here rather than in secureThrough,
+      // and an address literal is as legal in the base URL as a name.
+      withIdentity(options, unbracket(url.hostname));
+    }
+    const request = module.request(url, options);
+    request.on('socket', (s) => sockets.add(s));
+    request.on('response', resolve);
+    request.on('error', reject);
+    request.end();
+  });
+}
+
+// discard ends a response whose body this script is not going to read.
+//
+// DRAINING IS NOT CLOSING, and the difference is the whole point. A
+// stream set flowing and thrown away is still a stream being read: a
+// host that answers a redirect, or an error, with a body that never
+// ends goes on sending it — down a socket nobody is going to look at —
+// for as long as this process lives, while the download carries on at
+// the next address. Destroying takes the connection with it, which is
+// the only thing that actually stops a sender.
+//
+// It is called for every answer whose body is not wanted, on both
+// paths. The tunnelled path had a socket of its own to destroy and the
+// direct one had nothing, which is exactly the sort of difference that
+// survives review because only half of it is visible in any one place.
+function discard(response) {
+  response.destroy();
+}
+
+// readBody collects a response, hashing as it goes, into a temp file in
+// THIS directory.
+//
+// THE TEMP FILE IS HERE, AND UNIQUELY NAMED, for two separate reasons:
+// a rename across devices fails, and two installs running at once are
+// ordinary. It is closed before anything renames it, because on Windows
+// renaming a file something still holds open fails outright — as does
+// renaming one an antivirus scanner has not finished with.
+function readBody(response) {
+  return new Promise((resolve, reject) => {
+    const file = path.join(
+      __dirname, `.curious-download-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
+    const hash = crypto.createHash('sha256');
+    const out = fs.createWriteStream(file);
+    let bytes = 0;
+
+    // ONE OUTCOME, and cleanup that waits for the handle to go.
+    //
+    // Destroying the stream and removing the file in the next statement
+    // is a race with the close. On Windows, removing a file something
+    // still holds open fails outright with EPERM — and this runs inside
+    // an event handler, so the throw does not become a failed install,
+    // it escapes as an unexpected error and leaves BOTH the partial
+    // temp file and a stack trace where the honest message should be.
+    // That is precisely the "nothing left behind" promise failing, on
+    // the one platform nobody writing this can try it on.
+    //
+    // So: wait for the stream's own close, then remove. And the flag,
+    // because more than one thing can fail at once — a reset connection
+    // ends the response and the write stream both — and the second
+    // arrival must not turn a settled failure into a resolve, nor
+    // report a different error than the first one.
+    let settled = false;
+
+    const fail = (err) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      const reason = err instanceof Retryable ? err : new Retryable(err.message);
+      const discardFile = () => {
+        try {
+          fs.rmSync(file, { force: true });
+        } catch {
+          // A temp file that refuses to go is not a reason to replace
+          // the real failure with a different one. The install still
+          // stops, and it stops saying why it stopped.
+        }
+        reject(reason);
+      };
+      if (out.closed) {
+        discardFile();
+        return;
+      }
+      out.once('close', discardFile);
+      out.destroy();
+    };
+
+    response.on('data', (chunk) => {
+      hash.update(chunk);
+      bytes += chunk.length;
+    });
+    response.on('error', fail);
+    out.on('error', fail);
+    response.pipe(out);
+    out.on('close', () => {
+      if (settled) {
+        return;
+      }
+      if (!response.complete) {
+        fail(new Retryable('the connection closed before the whole file arrived'));
+        return;
+      }
+      settled = true;
+      resolve({ file, digest: hash.digest('hex'), bytes });
+    });
+  });
+}
+
+// statusError decides whether an answer is worth asking again for.
+function statusError(status, url) {
+  const where = `${url.host}${url.pathname}`;
+  if (status >= 500) {
+    return new Retryable(`the release host answered ${status} for ${where}`);
+  }
+  return new Refused(
+    `The release host answered ${status} for ${where}.\n\n` +
+    (status === 404
+      ? 'That version of curious has no build for this platform, which usually\n' +
+        'means this package and the release have got out of step. Please report it.'
+      : 'Nothing was downloaded.'));
+}
+
+// The certificate failures whose codes carry no CERT in the name, so
+// the shape rule in translate cannot see them.
+//
+// UNABLE_TO_VERIFY_LEAF_SIGNATURE is what a host that serves its own
+// certificate and nothing beside it produces — the commonest
+// arrangement there is, and exactly what a TLS-inspecting proxy looks
+// like from here. Unclassified it read as a fault worth trying again,
+// so the one failure with a specific way out of it got three attempts
+// and then a message about the network.
+//
+// EVERY ENTRY IS A CODE THIS PACKAGE'S OWN SUITE PRODUCES, from a
+// fixture, rather than a list copied out of the library's headers: a
+// code nobody has seen is a branch nobody has run.
+const CERTIFICATE_CODES = new Set([
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+]);
+
+// translate turns whatever the transport produced into something a
+// person can read, and leaves anything already decided alone.
+//
+// THE CERTIFICATE FAMILY IS CALLED OUT BY NAME because the honest way
+// through it is an environment variable most people have never heard
+// of — and because an install that fails behind an inspecting proxy
+// with no route forward is exactly how somebody ends up reaching for a
+// flag that turns verification off.
+function translate(err, signal) {
+  if (err instanceof Refused || err instanceof Retryable) {
+    return err;
+  }
+  if (!(err instanceof Error)) {
+    return new Retryable(String(err));
+  }
+  if (signal.aborted && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
+    return new Retryable(`nothing arrived within ${ATTEMPT_TIMEOUT_MS / 1000} seconds`);
+  }
+  // OBSERVED SHAPES ONLY. The codes matched here were produced by real
+  // failures against real servers while this was written; keying on a
+  // code nobody has seen is how a branch that never runs gets written.
+  if (typeof err.code === 'string' &&
+      (CERTIFICATE_CODES.has(err.code) ||
+       err.code.includes('CERT') || err.code.startsWith('ERR_TLS'))) {
+    return new Refused(
+      'The TLS certificate the download host presented could not be verified:\n\n' +
+      // THE CODE IS PRINTED BESIDE THE SENTENCE. It is the half a person
+      // can search for and the half a row can assert on: a message can
+      // be reworded by a platform upgrade, and a row that matched only
+      // the word "certificate" would pass against a different failure
+      // entirely.
+      `  ${err.code}: ${err.message}\n\n` +
+      'If you are behind a proxy that inspects TLS, point NODE_EXTRA_CA_CERTS\n' +
+      'at your organisation\'s certificate authority file and install again.\n' +
+      'curious will not skip this check.');
+  }
+  return new Retryable(err.message);
+}
+
+// attemptFetch is ONE attempt: everything from the first request to the
+// bytes on disk, under a single deadline.
+async function attemptFetch(startURL) {
+  const controller = new AbortController();
+  const sockets = new Set();
+  const timer = setTimeout(() => {
+    controller.abort();
+    // ABORTING THE REQUEST IS NOT ENOUGH ON ITS OWN. A timeout that
+    // only stops waiting leaves the attempt's socket open, and a
+    // tunnelled socket is not owned by any request at all.
+    for (const socket of sockets) {
+      socket.destroy();
+    }
+  }, ATTEMPT_TIMEOUT_MS);
+
+  try {
+    let url = new URL(startURL);
+    for (let hop = 0; ; hop += 1) {
+      checkScheme(url, hop === 0 ? 'The download address' : 'The download was redirected to what');
+
+      // THE PROXY DECISION IS MADE AGAIN FOR EVERY HOP. A redirect that
+      // crosses hosts leaves the previous tunnel serving the wrong
+      // origin, and a host the rules exempt may sit at the other end of
+      // one that does not.
+      const proxy = proxyFor(url);
+      const tunnel = proxy
+        ? await secureThrough(await openTunnel(proxy, url, controller.signal, sockets), url, sockets)
+        : null;
+      const response = await sendGet(url, controller.signal, sockets, tunnel);
+      const status = response.statusCode;
+
+      if (status >= 300 && status < 400) {
+        discard(response);
+        if (tunnel) {
+          tunnel.destroy();
+        }
+        if (hop >= MAX_REDIRECTS) {
+          throw new Refused(
+            `The download was redirected more than ${MAX_REDIRECTS} times, which\n` +
+            'means it is going in a circle. Nothing was downloaded.');
+        }
+        const location = response.headers.location;
+        if (!location) {
+          throw new Refused(
+            `The release host answered ${status} — a redirect — and said nothing\n` +
+            'about where to. Nothing was downloaded, and this is not something\n' +
+            'trying again will fix. Please report it.');
+        }
+        try {
+          // Resolved against the address that sent it, so a bare path
+          // is a redirect within the same host rather than a failure.
+          url = new URL(location, url);
+        } catch {
+          throw new Refused(
+            `The release host redirected the download to "${location}", which is\n` +
+            'not an address curious can follow. Nothing was downloaded.');
+        }
+        continue;
+      }
+
+      if (status !== 200) {
+        discard(response);
+        throw statusError(status, url);
+      }
+      return await readBody(response);
+    }
+  } catch (err) {
+    throw translate(err, controller.signal);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// download runs the attempts. A failure that is not worth repeating
+// stops immediately; the rest wait and try again.
+async function download(url) {
+  let last;
+  for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
+    try {
+      return await attemptFetch(url);
+    } catch (err) {
+      if (!(err instanceof Retryable)) {
+        throw err;
+      }
+      last = err;
+      if (attempt < ATTEMPTS) {
+        await sleep(BACKOFF_MS[attempt - 1]);
+      }
+    }
+  }
+  throw new Refused(
+    `curious could not download the binary after ${ATTEMPTS} attempts.\n\n` +
+    `The last one ended because ${last.message}.\n\n` +
+    'Check your connection and install again. Nothing was left behind.');
+}
+
+// ---------------------------------------------------------------------
+// Steps 4 to 7: check it, unpack it, put it in place.
+// ---------------------------------------------------------------------
+
+function verify(downloaded, expected) {
+  if (downloaded.digest === expected) {
+    return;
+  }
+  fs.rmSync(downloaded.file, { force: true });
+  throw new Refused(
+    'The binary that arrived is not the one this package expected.\n\n' +
+    `  expected  ${expected}\n` +
+    `  received  ${downloaded.digest}\n\n` +
+    'That is either a corrupted download or a tampered release asset, and\n' +
+    'both deserve a stop rather than an install. Nothing has been written.\n' +
+    'Please report it.');
+}
+
+// place decompresses the VERIFIED bytes into a second temp file, closes
+// it, makes it executable, and renames it over whatever was there.
+//
+// THE ORDER MATTERS. Renaming the compressed file into place and
+// decompressing afterwards would leave a window in which the binary's
+// name holds something that is not a binary.
+function place(downloaded, binary) {
+  const target = path.join(__dirname, binary);
+  const staged = path.join(
+    __dirname, `.curious-staged-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
+  try {
+    const bytes = zlib.gunzipSync(fs.readFileSync(downloaded.file));
+    fs.writeFileSync(staged, bytes);
+    // 0755 rather than 0777: whoever installed it owns it, everyone
+    // else may run it. A no-op on Windows, which has no such bits.
+    fs.chmodSync(staged, 0o755);
+    fs.renameSync(staged, target);
+  } catch (err) {
+    fs.rmSync(staged, { force: true });
+    fs.rmSync(downloaded.file, { force: true });
+    throw new Refused(
+      `The downloaded binary could not be unpacked into place:\n\n  ${err.message}\n\n` +
+      'Check that the directory this package was installed into is writable.');
+  }
+  fs.rmSync(downloaded.file, { force: true });
+}
+
+// The marker is how the shim knows the binary beside it belongs to THIS
+// version of the package.
+//
+// IT IS REMOVED BEFORE ANY WORK AND WRITTEN AFTER ALL OF IT, so a
+// failed upgrade leaves nothing claiming to be current. Without it a
+// half-finished install in a reused directory leaves the previous
+// release's binary sitting there under the right name, and the shim
+// happily runs it.
+const MARKER = 'installed.json';
+
+function clearMarker() {
+  fs.rmSync(path.join(__dirname, MARKER), { force: true });
+}
+
+function writeMarker(binary) {
+  fs.writeFileSync(
+    path.join(__dirname, MARKER),
+    JSON.stringify({ version: pkg.version, binary }, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------
+
+async function main() {
+  requireNodeFloor();
+  const target = resolveTarget();
+  const expected = expectedDigest(target.asset);
+  clearMarker();
+  const downloaded = await download(downloadURL(target.asset));
+  verify(downloaded, expected);
+  place(downloaded, target.binary);
+  writeMarker(target.binary);
+}
+
+// THE ONE PLACE A FAILURE IS PRINTED, and it never prints a stack
+// trace: a postinstall failure is read by somebody who typed one
+// command and expected it to work, and a trace tells them about this
+// file rather than about what to do next.
+main().catch((err) => {
+  const message = err instanceof Refused
+    ? err.message
+    : `Something went wrong that this installer did not expect:\n\n  ${err && err.message}\n\n` +
+      'Please report it.';
+  console.error(`\ncurious could not be installed.\n\n${message}\n`);
+  process.exit(1);
+});

package/lib/platform.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// What Node calls this machine, and what the release calls the file
+// built for it. The two vocabularies differ in two places and agree
+// everywhere else, which is the whole reason this file exists: a
+// mapping written inline at each call site is a mapping that can
+// disagree with itself.
+//
+// ONE HELPER, TWO CONSUMERS, and that is load bearing rather than tidy.
+// The install script renames the downloaded binary to binaryName(); the
+// shim spawns binaryName(). If those were two expressions, the day one
+// of them learned about Windows and the other did not would be the day
+// the package installed successfully and then could not run.
+
+// SUPPORTED is the promise this package makes, written out as pairs
+// rather than as two lists crossed together. A cross product says
+// "every combination", which is a claim about combinations nobody
+// built: the release matrix is what decides this, and it is a list of
+// pairs there too.
+const SUPPORTED = [
+  { platform: 'darwin', arch: 'x64' },
+  { platform: 'darwin', arch: 'arm64' },
+  { platform: 'linux', arch: 'x64' },
+  { platform: 'linux', arch: 'arm64' },
+  { platform: 'win32', arch: 'x64' },
+  { platform: 'win32', arch: 'arm64' },
+];
+
+// The two spellings that differ. Node says win32 for an operating
+// system that has not been 32-bit in twenty years, and x64 for the
+// architecture the build tool calls amd64. Everything else is the same
+// word in both vocabularies, so only the differences are written down —
+// a full table would invite somebody to "correct" an identity mapping
+// and change nothing, or to add a row the release does not build.
+const OS_NAMES = { win32: 'windows' };
+const ARCH_NAMES = { x64: 'amd64' };
+
+function isSupported(platform, arch) {
+  return SUPPORTED.some((p) => p.platform === platform && p.arch === arch);
+}
+
+// assetName is the name of the single-member gzip the release publishes
+// for this machine, or null when there is none.
+//
+// NULL RATHER THAN A GUESS. A name composed for an unsupported pair
+// would be a request the release host answers with a 404 several
+// seconds later, and the reader would be looking at a network error
+// rather than at the sentence saying their machine is not built for.
+function assetName(version, platform, arch) {
+  if (!isSupported(platform, arch)) {
+    return null;
+  }
+  const os = OS_NAMES[platform] || platform;
+  const cpu = ARCH_NAMES[arch] || arch;
+  return `curious_${version}_${os}_${cpu}.gz`;
+}
+
+// binaryName is what the installed file is called once it is in place.
+//
+// NOTHING HANDS THIS TO US. The archive is a plain gzip, and gunzipping
+// bytes ignores the member name the gzip header may or may not carry —
+// so the destination is derived here, from the platform, or the install
+// succeeds on Windows and leaves a file the shim will never find.
+function binaryName(platform) {
+  return platform === 'win32' ? 'curious.exe' : 'curious';
+}
+
+// unsupportedMessage is the refusal. It names what was found, what is
+// supported, and the two ways out, because a person reading it has
+// already run the command that was supposed to work.
+function unsupportedMessage(platform, arch) {
+  const supported = SUPPORTED.map((p) => `  ${p.platform}/${p.arch}`).join('\n');
+  return (
+    `curious has no prebuilt binary for ${platform}/${arch}.\n\n` +
+    `Supported:\n${supported}\n\n` +
+    'Two ways forward:\n' +
+    '  - download a binary from the releases page at\n' +
+    '    https://github.com/curiouspub/cli/releases\n' +
+    '  - build it yourself: go install github.com/curiouspub/cli/cmd/curious@latest'
+  );
+}
+
+module.exports = { SUPPORTED, assetName, binaryName, unsupportedMessage };

package/loopback-hosts.json

@@ -0,0 +1,4 @@
+{
+  "hosts": ["localhost", "127.0.0.1", "::1"],
+  "why": "The exact set of hosts this project's clients may reach over plaintext http, and nothing wider. Every other host must arrive over https. It is an exact set rather than a range: no other address in 127.0.0.0/8 is in it. This file is the one place the set is written; the Go client's own copy is held equal to it by a test, so the two cannot drift into being two different rules with one name."
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "curiouspub",
+  "version": "0.1.0",
+  "description": "Pack an Astro project, upload it, and stream the build. Installs the curious CLI for your platform.",
+  "license": "MIT",
+  "homepage": "https://curious.pub",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/curiouspub/cli"
+  },
+  "type": "commonjs",
+  "bin": {
+    "curious": "bin/curious.js"
+  },
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10"
+  },
+  "devDependencies": {
+    "acorn": "8.18.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "install.js",
+    "checksums.json",
+    "loopback-hosts.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node install.js",
+    "test": "node --test test/"
+  }
+}