@integrity-labs/agt-cli 0.28.834 → 0.28.836

package/dist/assets/review/obiwan-auth.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+/**
+ * VENDORED (ENG-10001) — THIS MONOREPO COPY IS CANONICAL; the Smithers plugin
+ * copy is downstream. Delivered alongside `post-review-findings.mjs` by
+ * `provisionReviewPoster()` (apps/cli/src/lib/review-poster-asset.ts).
+ *
+ * DIVERGED FROM THE ORIGIN, deliberately (ENG-10001). `resolveIdentity` now
+ * VERIFIES with GitHub that the App it minted for is the one named in
+ * `EXPECTED_APP_SLUG`, and throws when it is not; `post-review-findings.mjs`
+ * refuses to write anything at all without that verified identity. The plugin
+ * copy stays permissive because a human runs it and can see whose name ends up
+ * on the comment. This copy's only caller is an unattended agent, which cannot.
+ */
+/**
+ * obiwan-auth — mint a GitHub App installation token for the review bot.
+ *
+ * WHY AN APP AND NOT A PAT. Review findings posted with a personal token appear
+ * under a human's name. That is wrong twice: it attributes a machine's claims to
+ * a person, and it leaves the findings unfilterable — nobody can mute the bot
+ * without muting their colleague. An App has its own identity
+ * (`obi-wan-shinobi-reviewer[bot]` — the slug GitHub assigned, which is NOT a
+ * shortening of the display name),
+ * its own permissions, and a per-repo installation that can be revoked without
+ * touching anybody's account.
+ *
+ * WHY THERE IS NOTHING TO PASTE INTO A SHELL PROFILE. App auth is two hops: an
+ * RS256 JWT signed with the App's private key, exchanged for an installation
+ * token that expires in ONE HOUR. So a token in `.zshrc` is stale before it is
+ * useful. What belongs in a profile is the app id and a PATH to the key:
+ *
+ *   export OBIWAN_APP_ID=4822599                                # this App, not a placeholder
+ *   export OBIWAN_PRIVATE_KEY=~/.config/obiwan/private-key.pem   # chmod 600
+ *
+ * The PEM itself should not be inlined there. `.zshrc` is sourced by every
+ * shell, is routinely committed to a dotfiles repo, and is read by anything that
+ * can read the home directory — none of which is true of a 0600 file the user
+ * chose the location of.
+ *
+ * PERMISSIONS THE APP NEEDS: `pull_requests: write` (post review comments,
+ * resolve threads) and `contents: read` (read the diff). Deliberately NOT
+ * `contents: write` — this bot must never be able to push.
+ */
+
+import { createSign, randomUUID } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+
+/**
+ * The App this reviewer is, as GitHub spells it. `slug` — not the display name,
+ * not the app id — is what forms the comment author `<slug>[bot]`, so it is the
+ * only value that answers "whose name will be on the finding".
+ */
+export const EXPECTED_APP_SLUG = 'obi-wan-shinobi-reviewer';
+
+const b64url = (buf) =>
+  Buffer.from(buf).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+/**
+ * Resolve the private key from either an inline PEM or a path.
+ *
+ * A path is the supported form; an inline PEM is accepted because CI has no
+ * filesystem to point at. When it IS a path, the file's mode is checked: a key
+ * readable by the whole machine is a key that has already leaked, and the point
+ * of moving off a PAT was to stop spreading credentials around.
+ */
+export function resolvePrivateKey(value, { stat = statSync, read = readFileSync } = {}) {
+  if (!value) throw new Error('OBIWAN_PRIVATE_KEY is not set (path to the App private-key PEM, or the PEM itself)');
+  if (String(value).includes('-----BEGIN')) return String(value);
+
+  const path = String(value).replace(/^~(?=\/)/, process.env.HOME ?? '~');
+  const st = stat(path);
+  // eslint-disable-next-line no-bitwise
+  const openTo = st.mode & 0o077;
+  if (openTo !== 0) {
+    throw new Error(
+      `${path} is readable beyond its owner (mode ${(st.mode & 0o777).toString(8)}) — ` +
+        'refusing to use it. Run: chmod 600 ' + path,
+    );
+  }
+  const pem = String(read(path, 'utf8'));
+  if (!pem.includes('-----BEGIN')) {
+    throw new Error(`${path} does not look like a PEM private key`);
+  }
+  return pem;
+}
+
+/**
+ * The App JWT. GitHub caps its life at 10 minutes and rejects a future `iat`,
+ * so `iat` is backdated 60s to survive ordinary clock skew between this machine
+ * and GitHub — the documented remedy for the 401 this otherwise produces
+ * intermittently and confusingly.
+ */
+export function buildAppJwt({ appId, privateKey, now = Math.floor(Date.now() / 1000) }) {
+  if (!appId) throw new Error('OBIWAN_APP_ID is not set');
+  const header = { alg: 'RS256', typ: 'JWT' };
+  // GitHub rejects an `exp` more than 10 minutes ahead of ITS clock, so the
+  // margin is skew budget, not lifetime: at now+540 a host clock 60s fast is
+  // already refused with a 401 that names the token, not the clock. 480 buys
+  // two minutes of drift for a token used within seconds of minting.
+  const payload = { iat: now - 60, exp: now + 480, iss: String(appId) };
+  const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+  const sig = createSign('RSA-SHA256').update(signingInput).end().sign(privateKey);
+  return `${signingInput}.${b64url(sig)}`;
+}
+
+/**
+ * Exchange the App JWT for an installation token scoped to one repository.
+ *
+ * OVER `fetch`, NOT `gh`, AND THE SCHEME IS THE REASON. `gh` sends
+ * `Authorization: token <value>`; a GitHub App JWT is only accepted as
+ * `Authorization: Bearer <jwt>`. Handing gh a perfectly valid JWT therefore
+ * returns `401 A JSON web token could not be decoded` — a message that points
+ * at the token's FORMAT, and it sent this ticket chasing the key, then the app
+ * id, then the clock, before the transport. The same JWT against the same
+ * endpoint over fetch with an explicit Bearer header returns 200.
+ *
+ * The installation token that comes back IS an ordinary token, so `gh` handles
+ * it normally from there; only these two hops need the Bearer scheme.
+ *
+ * A welcome consequence: no credential reaches a subprocess environment at all
+ * for these calls, and none has ever reached a command line. A process's argv
+ * is world-readable through `ps` and is copied verbatim into CI logs and SSM
+ * run history — one of the categories `/s:security-review` exists to flag.
+ */
+export async function ghFetch(url, jwt, method = 'GET', fetchImpl = fetch, timeoutMs = 15_000) {
+  // An unattended run has nobody to ctrl-C it. resolveIdentity() awaits two
+  // sequential mints before the caller reads PR state or posts anything, so a
+  // stalled socket here hangs the whole review with no output and no timeout of
+  // its own — indistinguishable from an agent that simply did no work.
+  const res = await fetchImpl(url, {
+    method,
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: {
+      Authorization: `Bearer ${jwt}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': 'obi-wan-shinobi-reviewer',
+    },
+  });
+  const body = await res.json().catch(() => ({}));
+  return { status: res.status, body };
+}
+
+export async function mintInstallationToken({ repo, appId, privateKey, request = ghFetch }) {
+  const jwt = buildAppJwt({ appId, privateKey });
+
+  // WHO WE ACTUALLY ARE, asked of GitHub rather than inferred from config.
+  // `appId` is operator-supplied, and a wrong one does not fail — it mints a
+  // perfectly valid token for a DIFFERENT App, whose `[bot]` name then appears
+  // on the review. That is the outcome AC3 forbids, minus the tell: it does not
+  // look like a fallback, it looks like a working bot under the wrong name.
+  //
+  // This hop needs the JWT: an installation token cannot call `GET /app`.
+  const app = await request('https://api.github.com/app', jwt);
+  if (app.status !== 200 || !app.body?.slug) {
+    throw new Error(
+      `app identity lookup failed (${app.status}): ${app.body?.message ?? 'no slug in the response'}` +
+        (app.status === 401
+          ? ' — a 401 here means the JWT did not verify: check OBIWAN_APP_ID matches the key you downloaded'
+          : ''),
+    );
+  }
+
+  const inst = await request(`https://api.github.com/repos/${repo}/installation`, jwt);
+  if (inst.status === 404) {
+    throw new Error(
+      `the Obi Wan Shinobi App is not installed on ${repo} — install it on the repository ` +
+        '(App settings -> Install App), then retry',
+    );
+  }
+  if (inst.status !== 200 || !inst.body?.id) {
+    throw new Error(
+      `installation lookup failed (${inst.status}): ${inst.body?.message ?? 'unknown'}` +
+        (inst.status === 401
+          ? ' — a 401 here means the JWT did not verify: check OBIWAN_APP_ID matches the key you downloaded'
+          : ''),
+    );
+  }
+
+  const tok = await request(
+    `https://api.github.com/app/installations/${inst.body.id}/access_tokens`,
+    jwt,
+    'POST',
+  );
+  if (tok.status !== 201 || !tok.body?.token) {
+    throw new Error(`token exchange failed (${tok.status}): ${tok.body?.message ?? 'no token in response'}`);
+  }
+  return {
+    token: tok.body.token,
+    expiresAt: tok.body.expires_at,
+    installationId: inst.body.id,
+    appSlug: app.body.slug,
+  };
+}
+
+/**
+ * The token to authenticate as, or null to keep whatever `gh` is already using.
+ *
+ * TWO OUTCOMES, AND THEY ARE NOT THE SAME KIND OF THING.
+ *
+ * An UNCONFIGURED App returns `kind: 'fallback'` rather than throwing, because
+ * the read-only modes are still useful without it — `--status` lists this
+ * reviewer's threads with any credentials at all. What the fallback must never
+ * do is write, and enforcing that is the CALLER's job: see `refuseIdentity` in
+ * `post-review-findings.mjs`, which is where the fail-closed decision lives so
+ * that it can distinguish a dry run from a post.
+ *
+ * A MISCONFIGURED App throws. Absence degrades; pointing at the wrong App is a
+ * mistake to be loud about, and a machine that would post under a name nobody
+ * chose should stop rather than narrow its mode. The cost is that `--status`
+ * also fails there, which is the right way round: the operator learns of the
+ * misconfiguration at the first command they run, not at the first post.
+ */
+/**
+ * The two halves of the fallback diagnostic, named so the test can assert them
+ * exactly rather than by prefix — a `startsWith` check passes while the
+ * replacement guidance, which is the only actionable part, silently rots.
+ */
+export const MIGRATION_GUIDANCE =
+  'the Kunai app was replaced by obi-wan-shinobi-reviewer (App 4822599). '
+  + 'Rename to OBIWAN_APP_ID / OBIWAN_PRIVATE_KEY and point the key at the new PEM';
+export const NOT_SET = 'OBIWAN_APP_ID / OBIWAN_PRIVATE_KEY not set';
+
+export async function resolveIdentity({ repo, env = process.env, mint = mintInstallationToken } = {}) {
+  if (!env.OBIWAN_APP_ID || !env.OBIWAN_PRIVATE_KEY) {
+    // Name the ACTUAL cause. A machine still holding the retired KUNAI_* pair
+    // is one `.zshrc` edit from working, and "not set" sends its owner looking
+    // for a variable they believe they already have.
+    // PRESENT, not truthy (CodeRabbit, #159). `export KUNAI_APP_ID=` leaves an
+    // empty string, which is falsy — so the one legacy variable still sitting
+    // in a profile went unmentioned, and the operator got the generic message
+    // while a stale name was right there. An empty one is flagged as empty
+    // rather than merely named, so nobody goes hunting for a value that is not
+    // there.
+    const stale = ['KUNAI_APP_ID', 'KUNAI_PRIVATE_KEY']
+      .filter((k) => env[k] !== undefined && env[k] !== null)
+      .map((k) => (env[k] === '' ? `${k} (empty)` : k));
+    return {
+      kind: 'fallback',
+      token: null,
+      why: stale.length > 0 ? `found ${stale.join(' and ')} — ${MIGRATION_GUIDANCE}` : NOT_SET,
+    };
+  }
+  const privateKey = resolvePrivateKey(env.OBIWAN_PRIVATE_KEY);
+  const { token, expiresAt, appSlug } = await mint({ repo, appId: env.OBIWAN_APP_ID, privateKey });
+
+  // A MISSING slug is a failure, not a pass. It means this token was minted by
+  // something that did not perform the `GET /app` hop — an older `mint`, or a
+  // future refactor that drops it — and reading "nothing to compare" as
+  // "nothing wrong" is exactly how a check that still exists stops checking.
+  if (appSlug !== EXPECTED_APP_SLUG) {
+    throw new Error(
+      `OBIWAN_APP_ID ${env.OBIWAN_APP_ID} authenticates as ` +
+        `${appSlug ? `"${appSlug}"` : 'an App whose identity was not verified'}, ` +
+        `not "${EXPECTED_APP_SLUG}" — refusing to post under an identity nobody chose. ` +
+        'Point OBIWAN_APP_ID and OBIWAN_PRIVATE_KEY at the Obi Wan Shinobi App.',
+    );
+  }
+
+  // `why` is derived from what GitHub returned, never from the constant above.
+  // Printing the expected name would report the identity the code hoped for
+  // rather than the one it got, which is the whole failure this guards.
+  return { kind: 'app', token, expiresAt, appSlug, why: `${appSlug}[bot] via App ${env.OBIWAN_APP_ID}` };
+}
+
+/** Never let a token reach a log or an error message intact. */
+export function redact(text, token) {
+  if (!token) return text;
+  return String(text).split(token).join('***');
+}
+
+export const _internal = { b64url, randomUUID };