@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/usage-register.mjs

@@ -2,15 +2,9 @@
 /**
  * usage-register.mjs  -  ask the reporting endpoint for this machine's token.
  *
- * WHY THIS EXISTS
- *
- * Operational reporting needs two things to work: `usageLog.enabled` true AND a
- * token that resolves. Since v15.8.0 both are arranged automatically - but only
- * inside `/multi-agent:update`, as forty lines of shell embedded in a skill. A
- * new user installs the package, runs `/multi-agent:setup` (which explicitly
- * says registration happens in update), works for weeks, and never registers.
- * Their runs emit nothing, and the panel cannot tell that apart from nobody
- * using the pipeline at all - which is exactly what it looked like.
+ * Operational reporting needs two things: `usageLog.enabled` true AND a token
+ * that resolves. This command arranges both from one place, so a fresh install
+ * can register without running `/multi-agent:update` first.
  *
  * So the registration becomes one deterministic call that three places make:
  * setup (onboarding), update (existing path), and the first run of a machine
@@ -22,25 +16,41 @@
  * - It never writes the token to a file. The credential store holds it; prefs
  *   hold only the name of the entry.
  * - It never registers when `usageLog.optOut` is true. That is permanent and
- *   checked before anything else.
+ *   checked before anything else, including any credential read (the
+ *   credential store and gh).
+ * - It never registers a name it has not checked: the login sent is the
+ *   logged-in GitHub account that can read the pipeline repository
+ *   (usage-identity.mjs). No such account, no registration. The request
+ *   carries that account's gh token as `Authorization: Bearer` so the server
+ *   can confirm the caller owns the login; the server pins the login to the
+ *   token it issues.
+ * - It never sends the gh token over plain http to anything but loopback, never
+ *   follows a redirect with it, never prints it, and never puts it on an argv:
+ *   gh prints it on its own stdout and it goes straight into the header.
  * - It never fails a caller. Offline, endpoint down, ingest disabled by the
  *   admin, no credential store: one status line, exit 0.
  * - It never reports run CONTENT. That is usage-report.mjs's contract, and it
  *   is coarse metadata only.
  *
  * Usage:
- *   node usage-register.mjs [--prefs <path>] [--json] [--quiet] [--dry-run] [--feedback]
+ *   node usage-register.mjs [--prefs <path>] [--json] [--quiet] [--dry-run] [--feedback] [--refresh]
+ *
+ * `--refresh` re-checks which logged-in GitHub account can read the pipeline
+ * repository instead of using the cached `usageLog.login`.
  *
  * Exit: always 0. `--json` says what happened; the shell does not need to care.
  *
  * @module pipeline/scripts/usage-register
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { join } from "node:path";
-import { homedir, hostname, userInfo } from "node:os";
+import { homedir, hostname } from "node:os";
 import { pathToFileURL } from "node:url";
+import { hostCommand } from "../lib/user-facing.mjs";
+import { ghTokenFor, resolveReportingLogin } from "./usage-identity.mjs";
+import { lockTimeoutFrom, updateJsonFileSync } from "../lib/json-file-lock.mjs";
 
 const DEFAULT_ENDPOINT = "https://mmerterden.com/api/usage/ingest";
 const TIMEOUT_MS = 10000;
@@ -53,25 +63,14 @@ function readJson(file) {
   }
 }
 
-/** The name this machine reports under: the GitHub login, never the git identity. */
-export function reportingUser(prefs, { env = process.env } = {}) {
-  const declared = prefs?.global?.identities?.[0]?.username;
-  if (typeof declared === "string" && declared.trim()) return declared.trim();
-  try {
-    const out = execFileSync("gh", ["api", "user", "--jq", ".login"], {
-      encoding: "utf8",
-      timeout: 5000,
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    if (out) return out;
-  } catch {
-    /* gh is optional */
-  }
-  try {
-    return env.USER || userInfo().username || "unknown";
-  } catch {
-    return "unknown";
-  }
+/**
+ * The name this machine registers under: the logged-in GitHub account that can
+ * read the pipeline repository (usage-identity.mjs), or null when none can.
+ * Never the git identity, never the OS user, never the account gh merely has
+ * active.
+ */
+export function reportingUser(prefsPath, { env = process.env, refresh = false } = {}) {
+  return resolveReportingLogin({ prefsPath, env, refresh });
 }
 
 /**
@@ -83,7 +82,13 @@ export function reportingUser(prefs, { env = process.env } = {}) {
  */
 export function decideRegistration(
   prefs,
-  { env = process.env, hasStoredToken = false, forFeedback = false } = {},
+  {
+    env = process.env,
+    hasStoredToken = false,
+    forFeedback = false,
+    login = undefined,
+    loginReason = null,
+  } = {},
 ) {
   const g = prefs?.global || {};
   const u = g.usageLog || {};
@@ -95,6 +100,18 @@ export function decideRegistration(
   if (env.MULTI_AGENT_USAGE_TOKEN) return { act: false, reason: "token in environment" };
   if (typeof u.token === "string" && u.token.trim())
     return { act: false, reason: "token in prefs" };
+  if (login === null) {
+    return { act: false, reason: loginReason || "no logged-in GitHub account has access" };
+  }
+  // The server pins a token to the login it was issued for. A token issued to a
+  // different login, or before the login was verified, reports under the wrong
+  // name, so it is replaced.
+  if (hasStoredToken && login && u.registeredAs && u.registeredAs !== login) {
+    return { act: true, reason: `reporting account changed to ${login}` };
+  }
+  if (hasStoredToken && login && !u.registeredAs) {
+    return { act: true, reason: "token predates account verification" };
+  }
   if (hasStoredToken) return { act: false, reason: "token already onboarded" };
   return { act: true, reason: "no token resolves" };
 }
@@ -113,18 +130,64 @@ function storedToken(prefs, credStore) {
   return out || null;
 }
 
-async function requestToken(url, body) {
+/**
+ * May the gh token be sent to `url`? The token is a full GitHub credential, so
+ * it only goes over https to the default reporting host or a host the prefs
+ * name in `usageLog.trustedHosts`; http only to loopback (local development).
+ */
+export function registerUrlAllowed(url, trustedHosts = []) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return false;
+  }
+  if (u.protocol === "http:") return ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname);
+  if (u.protocol !== "https:") return false;
+  const trusted = new Set(
+    [new URL(DEFAULT_ENDPOINT).hostname, ...trustedHosts].map((h) => String(h).toLowerCase()),
+  );
+  return trusted.has(u.hostname.toLowerCase());
+}
+
+async function requestToken(url, body, proof) {
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
   try {
     const res = await fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${proof}` },
       body: JSON.stringify(body),
+      redirect: "error",
       signal: ctrl.signal,
     });
-    if (!res.ok) return { token: null, why: `endpoint answered ${res.status}` };
     const json = await res.json().catch(() => null);
+    if (!res.ok) {
+      const detail = typeof json?.error === "string" ? `: ${json.error.slice(0, 120)}` : "";
+      if (json?.code === "login_mismatch") {
+        return {
+          token: null,
+          why: `the gh token does not belong to ${body.u}; run \`gh auth status\` and retry with --refresh`,
+        };
+      }
+      if (res.status === 401) {
+        return {
+          token: null,
+          why:
+            `endpoint answered ${res.status}${detail} - GitHub did not accept the token for ${body.u}; ` +
+            `check \`gh auth status\` lists that account, then retry with --refresh`,
+        };
+      }
+      if (res.status === 403) {
+        return {
+          token: null,
+          why: `endpoint answered 403${detail} - ${body.u} needs collaborator access to the pipeline repository`,
+        };
+      }
+      return { token: null, why: `endpoint answered ${res.status}${detail}` };
+    }
+    if (json?.accepted === false)
+      return { token: null, declined: true, why: "the endpoint declined this login" };
     const token = typeof json?.token === "string" ? json.token.trim() : "";
     return token ? { token, why: null } : { token: null, why: "endpoint returned no token" };
   } catch (e) {
@@ -140,35 +203,57 @@ async function requestToken(url, body) {
 /**
  * Write the switch, and the credential-store ENTRY NAME when there is one.
  *
- * `entryName` is optional on purpose: a token can resolve from the environment
- * or from `usageLog.token`, and those machines still need the switch flipped.
- * Claiming "enabled" while writing nothing is the failure this whole feature is
- * about, one level smaller.
+ * `entryName` is optional: a token can resolve from the environment or from
+ * `usageLog.token`, and those machines still need the switch flipped. Enabling
+ * reporting without a resolvable token would claim "enabled" while writing
+ * nothing, so both are set together or neither is.
  *
  * The token itself is never written here, whatever the caller passes.
  */
-export function persistPrefs(prefsPath, entryName = null, { enableTelemetry = true } = {}) {
-  const j = readJson(prefsPath);
-  if (!j) return false;
-  j.global = j.global || {};
-  if (entryName) {
-    j.global.keychainMapping = j.global.keychainMapping || {};
-    j.global.keychainMapping.usage_ingest = entryName;
+export function persistPrefs(
+  prefsPath,
+  entryName = null,
+  { enableTelemetry = true, registeredAs = null } = {},
+) {
+  try {
+    const written = updateJsonFileSync(
+      prefsPath,
+      (j) => {
+        if (!j || typeof j !== "object" || Array.isArray(j)) return undefined;
+        j.global = j.global || {};
+        if (entryName) {
+          j.global.keychainMapping = j.global.keychainMapping || {};
+          j.global.keychainMapping.usage_ingest = entryName;
+        }
+        j.global.usageLog = j.global.usageLog || {};
+        if (enableTelemetry) j.global.usageLog.enabled = true;
+        if (registeredAs) j.global.usageLog.registeredAs = registeredAs;
+        return j;
+      },
+      { mode: 0o600, timeoutMs: lockTimeoutFrom(process.env) },
+    );
+    return written !== undefined;
+  } catch {
+    return false;
   }
-  j.global.usageLog = j.global.usageLog || {};
-  if (enableTelemetry) j.global.usageLog.enabled = true;
-  writeFileSync(prefsPath, `${JSON.stringify(j, null, 2)}\n`);
-  return true;
 }
 
 async function main(argv) {
-  const opts = { quiet: false, json: false, dryRun: false, prefs: null, feedback: false };
+  const opts = {
+    quiet: false,
+    json: false,
+    dryRun: false,
+    prefs: null,
+    feedback: false,
+    refresh: false,
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === "--quiet") opts.quiet = true;
     else if (a === "--json") opts.json = true;
     else if (a === "--dry-run") opts.dryRun = true;
     else if (a === "--feedback") opts.feedback = true;
+    else if (a === "--refresh") opts.refresh = true;
     else if (a === "--prefs") opts.prefs = argv[++i];
   }
   const HOME = homedir();
@@ -187,18 +272,37 @@ async function main(argv) {
   if (!prefs) {
     // Setup writes this file; nothing here creates it. An installer that seeds
     // state is the one thing the install contract forbids.
-    say("  -> operational reporting: no preferences file yet (run /multi-agent:setup)");
+    say(
+      `  -> operational reporting: no preferences file yet (run ${hostCommand("setup", import.meta.dirname)})`,
+    );
     return done("skipped", "no prefs");
   }
 
-  const has = Boolean(storedToken(prefs, credStore));
-  const decision = decideRegistration(prefs, { hasStoredToken: has, forFeedback: opts.feedback });
+  // Decided before any credential is read: an opted-out machine, or one whose
+  // token is already in the environment or prefs, never touches the credential
+  // store or gh.
+  const pre = decideRegistration(prefs, { forFeedback: opts.feedback });
+  const identityMatters = !["opted out", "token in environment", "token in prefs"].includes(
+    pre.reason,
+  );
+  const has = identityMatters ? Boolean(storedToken(prefs, credStore)) : false;
+  const who = identityMatters
+    ? reportingUser(prefsPath, { refresh: opts.refresh })
+    : { login: undefined, reason: null };
+  const current = readJson(prefsPath) || prefs;
+  const decision = decideRegistration(current, {
+    hasStoredToken: has,
+    forFeedback: opts.feedback,
+    login: who.login,
+    loginReason: who.reason,
+  });
   if (!decision.act) {
-    if (decision.reason !== "opted out") {
+    const repairable = ["token in environment", "token in prefs", "token already onboarded"];
+    if (repairable.includes(decision.reason)) {
       // Already has a token: make sure the switch is actually on. A token with
       // enabled:false is the other half of the same silence.
-      if (prefs.global?.usageLog?.enabled !== true && !opts.dryRun) {
-        const name = prefs.global?.keychainMapping?.usage_ingest || null;
+      if (current.global?.usageLog?.enabled !== true && !opts.dryRun) {
+        const name = current.global?.keychainMapping?.usage_ingest || null;
         if (persistPrefs(prefsPath, name)) {
           say("  -> operational reporting: enabled (a token was already onboarded)");
           return done("enabled", decision.reason);
@@ -211,8 +315,8 @@ async function main(argv) {
     return done("skipped", decision.reason);
   }
 
-  const url = registerUrl(prefs.global?.usageLog?.endpoint);
-  const user = reportingUser(prefs);
+  const url = registerUrl(current.global?.usageLog?.endpoint);
+  const user = who.login;
   let host = "unknown";
   try {
     host = hostname().split(".")[0] || "unknown";
@@ -220,12 +324,30 @@ async function main(argv) {
     /* a nameless host is still a host */
   }
 
+  if (!registerUrlAllowed(url, current.global?.usageLog?.trustedHosts || [])) {
+    const why =
+      "the register endpoint is not https on a trusted host (usageLog.trustedHosts), so the login proof is not sent";
+    say(`  -> operational reporting left off (${why})`);
+    return done("unavailable", why);
+  }
+
   if (opts.dryRun) {
     say(`  -> operational reporting: would register ${user} with ${url}`);
     return done("dry-run", url);
   }
 
-  const { token, why } = await requestToken(url, { u: user, c: host });
+  const proof = ghTokenFor(user);
+  if (!proof) {
+    const why = `gh has no token for ${user}; run \`gh auth login\` for that account`;
+    say(`  -> operational reporting left off (${why})`);
+    return done("unavailable", why);
+  }
+
+  const { token, why, declined } = await requestToken(url, { u: user, c: host }, proof);
+  if (declined) {
+    say(`  -> operational reporting left off (${why})`);
+    return done("declined", why);
+  }
   if (!token) {
     say(`  -> operational reporting left off (${why})`);
     return done("unavailable", why);
@@ -242,7 +364,7 @@ async function main(argv) {
     say("  -> operational reporting left off (the credential store refused the token)");
     return done("unavailable", "credential store write failed");
   }
-  persistPrefs(prefsPath, entry, { enableTelemetry: !optedOut });
+  persistPrefs(prefsPath, entry, { enableTelemetry: !optedOut, registeredAs: user });
   if (optedOut) {
     say("  -> feedback token registered; telemetry stays off (usageLog.optOut is set)");
     return done("registered-feedback-only", entry);