@theappagency/valinor 10.9.0 → 10.11.0

package/README.md

@@ -18,15 +18,24 @@ The launcher is **trivial by design** and contains no Valinor functionality itse
    version runs **fully offline** with no network I/O;
 4. executes the cached CLI, passing through all arguments and the exit code.
 
-No npm registry auth, no `.npmrc`, no tokens, no secrets — `npx` it anywhere, including CI. It runs on
-Node 22 or later, so a GitHub runner's default Node works without a `setup-node` step.
+No npm registry auth and no `.npmrc` — `npx` it anywhere, including CI. It runs on Node 22 or later, so a
+GitHub runner's default Node works without a `setup-node` step.
+
+**Authentication.** The downloads endpoint can require a credential. In GitHub Actions the launcher mints one
+itself: give the job `permissions: id-token: write` and it requests a GitHub OIDC token for the audience
+`https://downloads.theappagency.com`, so the repository stores no secret. Elsewhere, set
+`VALINOR_DOWNLOADS_TOKEN`. With neither, the launcher sends no credential, which works for as long as the
+endpoint does not require one. An HTTP 401 or 403 is never retried; the error names the fix. A
+`pull_request` run from a fork cannot mint an OIDC token, so it needs `VALINOR_DOWNLOADS_TOKEN` once the
+endpoint requires authentication.
 
 A download that fails for a transient reason (a dropped connection, a stalled transfer, a timeout, or an
 HTTP 408, 425, 429 or 5xx) is retried with jittered backoff: 3 attempts per file within a 2-minute budget by default. A 404
 and a checksum mismatch are never retried. When `review-trigger-run` still cannot be fetched after the
 retries, the launcher prints a warning and exits 0: the verb posts nothing when it cannot run, and the next
 wake-up or the hourly sweep evaluates the PR again. Every other command exits 1.
-**The launcher sends no telemetry.** Its only network activity is fetching the artifact above.
+**The launcher sends no telemetry.** Its only network activity is fetching the artifact above (and, in
+GitHub Actions with `id-token: write`, minting the OIDC token it fetches with).
 
 ## Environment variables
 
@@ -39,6 +48,7 @@ wake-up or the hourly sweep evaluates the PR again. Every other command exits 1.
 | `VALINOR_FETCH_ATTEMPTS` | Attempts per file for a transient failure: a whole number, at least `1` (default `3`). |
 | `VALINOR_FETCH_BACKOFF_MS` | Retry backoff base in milliseconds (default `1000`); attempt *n* waits 50–100% of base × 2^(n−1). |
 | `VALINOR_FETCH_TOTAL_TIMEOUT_MS` | The whole download's budget in milliseconds, across every attempt (default `120000`). |
+| `VALINOR_DOWNLOADS_TOKEN` | The downloads credential outside GitHub Actions (sent as a bearer token; a minted Actions OIDC token takes precedence). Sent only over https, or to this machine. |
 | `VALINOR_LAUNCHER_DEBUG` | Print full error causes (default output is the actionable message only). |
 
 ## Licensing

package/lib/launcher.js

@@ -7,6 +7,8 @@
 // Design constraints (deliberate):
 //   • ZERO runtime dependencies — nothing to audit, nothing to resolve from any registry.
 //   • NO TELEMETRY — the launcher reports nothing anywhere; only the artifact fetch itself.
+//   • One credential per run, only when the endpoint asks for one: a GitHub Actions OIDC token minted
+//     for the downloads audience, else VALINOR_DOWNLOADS_TOKEN, else none (see downloadsAuthorization).
 //   • Fail closed on integrity: a checksum mismatch DELETES the download and refuses to run.
 //   • Offline-friendly: an exactly-pinned, already-cached version runs with NO network at all;
 //     only a dist-tag (`latest`) needs the manifest.
@@ -48,6 +50,14 @@ export const DEFAULT_DOWNLOADS_HOST = LEGACY_DOWNLOADS_HOST;
 /** The production downloads endpoint (override with VALINOR_DOWNLOADS_URL — staging/fixtures/tests). */
 export const DEFAULT_DOWNLOADS_URL = `https://${DEFAULT_DOWNLOADS_HOST}`;
 
+/**
+ * The OIDC AUDIENCE the launcher requests when it mints a GitHub Actions token for the downloads endpoint —
+ * MIRRORS src/launcherBundle/resolveSha.ts (asserted by src/launcherBundle/downloadsHostMirror.test.ts). It is ONE
+ * fixed string whichever hostname the run fetches from: an audience is signed into the token before the endpoint
+ * sees it, so it cannot follow a host flip, and the endpoint accepts it on every hostname it serves.
+ */
+export const DOWNLOADS_OIDC_AUDIENCE = "https://downloads.theappagency.com";
+
 const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
 
 /** The endpoint base URL, env-overridable, without a trailing slash. */
@@ -126,6 +136,78 @@ export function parseSha256Sums(text, filename) {
   throw new Error(`SHA256SUMS carries no entry for ${filename} — refusing to run an unverifiable artifact`);
 }
 
+/** Whether a credential may be sent to `base`: https, or plain http to this machine only (a local fixture). */
+function mayCarryCredential(base) {
+  try {
+    const url = new URL(base);
+    return url.protocol === "https:" || (url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The `Authorization` value for downloads requests, or null to send none. ONE credential, in this order:
+ *   1. a GitHub Actions OIDC token minted for {@link DOWNLOADS_OIDC_AUDIENCE} — available only when the job grants
+ *      `permissions: id-token: write`, which is what puts ACTIONS_ID_TOKEN_REQUEST_URL/TOKEN in the environment;
+ *   2. VALINOR_DOWNLOADS_TOKEN — the non-Actions credential (a laptop, another CI);
+ *   3. nothing — anonymous, which the endpoint serves until it requires authentication.
+ * A failed mint is not fatal: it warns (never printing a token) and falls through, so a run the endpoint would
+ * serve anonymously still runs; when the endpoint does require auth, its 401 names the fix. A pull_request run
+ * from a fork cannot mint (GitHub withholds the request variables), so it lands on 2 or 3.
+ * `base` is the endpoint the credential is for: a plain-http endpoint that is not this machine gets none.
+ */
+export async function downloadsAuthorization(env = process.env, fetchImpl, policy = fetchPolicy(env), base = downloadsUrl(env)) {
+  if (!mayCarryCredential(base)) return null;
+  const fallback = env.VALINOR_DOWNLOADS_TOKEN ? `Bearer ${env.VALINOR_DOWNLOADS_TOKEN}` : null;
+  const requestUrl = env.ACTIONS_ID_TOKEN_REQUEST_URL;
+  const requestToken = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+  if (!requestUrl || !requestToken) return fallback;
+  try {
+    const url = new URL(requestUrl);
+    url.searchParams.set("audience", DOWNLOADS_OIDC_AUDIENCE);
+    const res = await (fetchImpl ?? fetch)(url, {
+      headers: { Authorization: `bearer ${requestToken}`, Accept: "application/json" },
+      signal: AbortSignal.timeout(policy.timeoutMs),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const value = (await res.json())?.value;
+    if (typeof value !== "string" || value === "") throw new Error("the response carried no token");
+    return `Bearer ${value}`;
+  } catch (e) {
+    const why = e?.name === "TimeoutError" ? `timed out after ${policy.timeoutMs}ms` : e instanceof Error ? e.message : String(e);
+    console.error(
+      `valinor launcher: warning — could not mint a GitHub Actions OIDC token for the downloads endpoint (${why}); ` +
+        (fallback ? "sending VALINOR_DOWNLOADS_TOKEN instead" : "continuing without a credential"),
+    );
+    return fallback;
+  }
+}
+
+/** Resolve the run's credential at most once, and only if a request is actually made (a cache hit mints nothing). */
+function onceAuthorization(resolveAuthorization) {
+  let pending = null;
+  return () => (pending ??= resolveAuthorization());
+}
+
+/** The refusal for a 401/403 — an auth answer is never an outage, so it names the fix, not the network. */
+function authRefusal(url, status, sentCredential) {
+  const fix =
+    "In GitHub Actions, add `permissions: id-token: write` to this job so the launcher can mint an OIDC token " +
+    "(`valinor refresh-workflows --apply` adds it to Valinor's own workflows); elsewhere, set VALINOR_DOWNLOADS_TOKEN.";
+  const e =
+    status === 403
+      ? fetchError(`${url} returned HTTP 403: the endpoint verified the credential, but this repository's owner is not authorized to download Valinor.`, false)
+      : fetchError(
+          sentCredential
+            ? `${url} returned HTTP 401: the downloads endpoint refused the credential the launcher sent (expired or not valid for it). ${fix}`
+            : `${url} returned HTTP 401: the downloads endpoint requires authentication and this run sent no credential. ${fix}`,
+          false,
+        );
+  e.auth = true;
+  return e;
+}
+
 /**
  * The per-ATTEMPT timeout (ms): a firewalled/blackholed endpoint that ACCEPTS a connection but never
  * replies must fail LOUDLY in seconds, not hang forever. The signal covers the response BODY as well as
@@ -198,7 +280,10 @@ function describeFailure(e, timeoutMs, phase) {
  * backoff wait — once a sibling download has already failed terminally, so the process never idles out
  * the rest of the budget on a run that must fail anyway.
  */
-async function fetchBody(url, read, fetchImpl, policy, cancel) {
+async function fetchBody(url, read, fetchImpl, policy, cancel, authorization) {
+  // The credential is resolved BEFORE the budget starts: minting has its own timeout, and the budget is the download's.
+  const credential = authorization ? await authorization() : null;
+  const headers = credential ? { Authorization: credential } : undefined;
   const deadline = Date.now() + policy.totalTimeoutMs;
   let last;
   let made = 0;
@@ -212,11 +297,16 @@ async function fetchBody(url, read, fetchImpl, policy, cancel) {
     const signal = cancel ? AbortSignal.any([timeout, cancel]) : timeout;
     let res;
     try {
-      res = await (fetchImpl ?? fetch)(url, { redirect: "follow", signal });
+      // A redirect to another origin drops the Authorization header (the fetch standard), so a credential never
+      // follows the legacy store redirect off this endpoint.
+      res = await (fetchImpl ?? fetch)(url, { redirect: "follow", signal, headers });
     } catch (e) {
       last = fetchError(`could not reach ${url} (${describeFailure(e, timeoutMs, "waiting for a response")})`, true, e);
     }
-    if (res && !res.ok) {
+    if (res && (res.status === 401 || res.status === 403)) {
+      last = authRefusal(url, res.status, credential !== null);
+      await res.body?.cancel().catch(() => {});
+    } else if (res && !res.ok) {
       last = fetchError(`${url} returned HTTP ${res.status}`, isTransientStatus(res.status));
       await res.body?.cancel().catch(() => {});
     } else if (res) {
@@ -243,8 +333,8 @@ async function fetchBody(url, read, fetchImpl, policy, cancel) {
 }
 
 /** Fetch + validate the endpoint manifest, retrying transient failures. `policy` is threaded from the caller's env. */
-export async function fetchManifest(base, fetchImpl, policy = fetchPolicy()) {
-  return fetchBody(`${base}/manifest.json`, (res) => res.json(), fetchImpl, policy);
+export async function fetchManifest(base, fetchImpl, policy = fetchPolicy(), authorization) {
+  return fetchBody(`${base}/manifest.json`, (res) => res.json(), fetchImpl, policy, undefined, authorization);
 }
 
 /**
@@ -255,7 +345,7 @@ export async function fetchManifest(base, fetchImpl, policy = fetchPolicy()) {
  * a temp dir and atomically renamed into place, so a crashed install can never half-populate a
  * version dir that a later run would trust.
  */
-export async function ensureVersion(base, version, root, fetchImpl, policy = fetchPolicy()) {
+export async function ensureVersion(base, version, root, fetchImpl, policy = fetchPolicy(), authorization) {
   const versionDir = join(root, version);
   if (existsSync(join(versionDir, ".complete"))) return versionDir; // cache hit — zero network.
 
@@ -268,8 +358,8 @@ export async function ensureVersion(base, version, root, fetchImpl, policy = fet
       throw e;
     });
   const [tarball, sums] = await Promise.all([
-    settle(fetchBody(tarballUrl, async (res) => Buffer.from(await res.arrayBuffer()), fetchImpl, policy, siblings.signal)),
-    settle(fetchBody(`${base}/v/${version}/SHA256SUMS`, (res) => res.text(), fetchImpl, policy, siblings.signal)),
+    settle(fetchBody(tarballUrl, async (res) => Buffer.from(await res.arrayBuffer()), fetchImpl, policy, siblings.signal, authorization)),
+    settle(fetchBody(`${base}/v/${version}/SHA256SUMS`, (res) => res.text(), fetchImpl, policy, siblings.signal, authorization)),
   ]);
   const expected = parseSha256Sums(sums, "valinor.tgz");
   const actual = createHash("sha256").update(tarball).digest("hex");
@@ -334,6 +424,8 @@ export async function run(args, env = process.env) {
   // Resolve the fetch policy ONCE from THIS call's env (an earlier bug read the ambient process.env, so a
   // `run(args, env)` override never engaged) and thread it into every fetch.
   const policy = fetchPolicy(env);
+  // One credential for the whole run, resolved lazily: a cache hit (or an offline pinned run) mints nothing.
+  const authorization = onceAuthorization(() => downloadsAuthorization(env, undefined, policy, base));
 
   let version;
   if (SEMVER_RE.test(requested)) {
@@ -341,20 +433,20 @@ export async function run(args, env = process.env) {
   } else {
     let manifest;
     try {
-      manifest = await fetchManifest(base, undefined, policy);
+      manifest = await fetchManifest(base, undefined, policy, authorization);
     } catch (e) {
-      throw withHint(e, `${e instanceof Error ? e.message : String(e)}\n${offlineHint(base, root)}`);
+      throw withHint(e, e?.auth === true ? e.message : `${e instanceof Error ? e.message : String(e)}\n${offlineHint(base, root)}`);
     }
     version = resolveVersion(manifest, requested);
   }
 
   let versionDir;
   try {
-    versionDir = await ensureVersion(base, version, root, undefined, policy);
+    versionDir = await ensureVersion(base, version, root, undefined, policy, authorization);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    // Integrity failures are terminal as-is; reachability failures get the offline hint.
-    throw withHint(e, msg.includes("SHA-256 MISMATCH") ? msg : `${msg}\n${offlineHint(base, root)}`);
+    // Integrity and authentication failures are terminal as-is; reachability failures get the offline hint.
+    throw withHint(e, msg.includes("SHA-256 MISMATCH") || e?.auth === true ? msg : `${msg}\n${offlineHint(base, root)}`);
   }
   return spawnCli(cachedBinPath(versionDir), args);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theappagency/valinor",
-  "version": "10.9.0",
+  "version": "10.11.0",
   "description": "Public launcher for the Valinor CLI — fetches, SHA-256-verifies, caches, and runs the proprietary Valinor bundle from downloads.valinorci.com. Zero setup, zero secrets, zero npm auth.",
   "repository": {
     "type": "git",