a permission error is disguised as 404 Not Found

"""Tell apart the several different failures GitHub hides behind one 404.

Read only. GET requests and nothing else: a token with read access is enough.
The repair is printed, never performed, because this script holds a credential
that can reach private repositories.
"""
import argparse
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("github_404_triage")

API = "https://api.github.com"
UA = "github-404-triage/1.0"

# Longest prefixes first so a future prefix that extends an existing one cannot
# be swallowed by its shorter neighbour.
PREFIXES = (
    ("github_pat_", "fine-grained PAT"),
    ("ghp_", "classic PAT"),
    ("gho_", "OAuth user token"),
    ("ghu_", "App user-to-server token"),
    ("ghs_", "App installation token"),
    ("ghr_", "App refresh token"),
)


def token_kind(token):
    """Name the credential from its prefix. Pure, and it never leaves the machine.

    Which check is worth making depends entirely on what kind of token this is:
    scopes are meaningless for an App installation token, and the installation
    question is meaningless for a classic PAT. A prefix comparison answers that
    for free, before a single request is spent.
    """
    value = (token or "").strip()
    for prefix, name in PREFIXES:
        if value.startswith(prefix):
            return name
    return "unknown"


def scope_list(header_value):
    """Read x-oauth-scopes into a list, keeping absent and empty apart.

    A classic token with nothing ticked sends the header with an empty value.
    A fine-grained token or an App token does not send it at all. Collapsing both
    to an empty list loses the one signal that decides which repair to print, so
    absence is None and emptiness is [].
    """
    if header_value is None:
        return None
    return [s.strip() for s in header_value.split(",") if s.strip()]


def verdict(probe):
    """Classify one 404. Pure, so the rules are readable rather than inferred.

    `probe` carries what the reads found: repo_status, authenticated, scopes
    (None when the token does not use them), token_kind, and in_installation
    (None when the question does not apply). Returns (state, detail).
    """
    status = probe.get("repo_status")

    if not probe.get("authenticated"):
        return ("bad-credentials",
                "GET /user did not authenticate. Every private repository 404s "
                "for a dead token while every public one answers 200, which is "
                "why this looks like a per-repository permission problem.")

    if status == 200:
        return ("visible", "the repository answered 200")
    if status == 403:
        return ("plain-403",
                "403 rather than 404, which is the honest one: rate limit, org "
                "IP allow list, or a policy that blocks this app. Read the "
                "message body and x-ratelimit-remaining before assuming access.")
    if status != 404:
        return ("unexpected", "HTTP %s is not the masked case" % (status,))

    kind = probe.get("token_kind")
    if kind == "App installation token":
        inside = probe.get("in_installation")
        if inside is True:
            return ("metadata-permission",
                    "the repository is inside the installation, so it exists and "
                    "you reach it. Every repository endpoint requires "
                    "Metadata: Read; without it the repository itself 404s.")
        if inside is False:
            return ("not-in-installation",
                    "the installation does not include this repository. "
                    "repository_selection is 'selected' and this one was never "
                    "ticked, so it is outside the token's world entirely.")
        return ("installation-unknown",
                "GET /installation/repositories could not be read, so the "
                "installation question is open. Retry with the installation "
                "token the failing call actually uses.")

    scopes = probe.get("scopes")
    if scopes is None:
        return ("repository-not-granted",
                "no x-oauth-scopes header, so this is a fine-grained token. "
                "Those grant repositories one at a time: this one is not in the "
                "token's repository list, or Metadata: Read is not on it.")
    if "repo" not in scopes:
        return ("missing-scope",
                "the token carries %s and not 'repo'. Public repositories answer "
                "and private ones return exactly this 404."
                % (", ".join(scopes) or "no scopes at all",))

    return ("no-access-or-gone",
            "the token authenticates and carries 'repo', so the scope is not the "
            "problem. What is left is an account that was never granted access, "
            "or a repository that is genuinely gone. GitHub returns the same 404 "
            "for both on purpose and no header separates them.")


def get(session, url, **params):
    return session.get(url, params=params, timeout=30)


def installation_repos(session, api, limit=2000):
    """Every repository inside this installation, or None if it cannot be read.

    Paged rather than trusted from one page: total_count is the size of the
    installation, and the repositories array is one page of it.
    """
    out = []
    page = 1
    while len(out) < limit:
        r = get(session, api + "/installation/repositories", per_page=100, page=page)
        if r.status_code != 200:
            return None
        items = r.json().get("repositories", [])
        out.extend(items)
        if len(items) < 100:
            break
        page += 1
    return out


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("repo", help="owner/name of the repository that returns 404")
    ap.add_argument("--api", default=API,
                    help="API host, for GitHub Enterprise Server")
    args = ap.parse_args()

    token = os.environ.get("GITHUB_TOKEN")
    if not token:
        log.error("set GITHUB_TOKEN (a read-only token is enough)")
        return 2
    if "/" not in args.repo:
        log.error("pass the repository as owner/name")
        return 2
    owner, name = args.repo.split("/", 1)

    session = requests.Session()
    session.headers.update({
        "Authorization": "Bearer " + token,
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28",
        # GitHub rejects requests with no User-Agent outright, which is its own
        # confusing 403 and not the one this script is about.
        "User-Agent": UA,
    })

    kind = token_kind(token)
    me = get(session, args.api + "/user")
    probe = {
        "token_kind": kind,
        "authenticated": me.status_code == 200,
        "scopes": scope_list(me.headers.get("x-oauth-scopes")),
        "in_installation": None,
    }
    login = me.json().get("login") if probe["authenticated"] else None

    repo = get(session, "%s/repos/%s/%s" % (args.api, owner, name))
    probe["repo_status"] = repo.status_code

    if kind == "App installation token" and repo.status_code == 404:
        repos = installation_repos(session, args.api)
        if repos is not None:
            full = args.repo.lower()
            probe["in_installation"] = any(
                str(r.get("full_name") or "").lower() == full for r in repos)

    state, detail = verdict(probe)
    line = "%-22s %s  %s" % (state, args.repo, detail)
    if state == "visible":
        log.info("%s (authenticated as %s)", line, login)
        return 0

    log.warning(line)
    log.warning("  token: %s, login: %s, scopes: %s", kind, login,
                "absent" if probe["scopes"] is None else (probe["scopes"] or "none"))
    repairs = {
        "bad-credentials": "re-mint the token and assert GET /user returns the "
                           "expected login at startup",
        "missing-scope": "re-create the classic token with the 'repo' scope, or "
                         "move to a fine-grained token listing this repository",
        "repository-not-granted": "add this repository to the fine-grained "
                                  "token's repository access, with Metadata: Read",
        "not-in-installation": "add the repository to the App installation, or "
                               "switch the installation to All repositories",
        "metadata-permission": "add Metadata: Read to the App and have each "
                               "installation accept the updated permissions",
        "no-access-or-gone": "grant %s access to the repository, or confirm with "
                             "somebody who can see it that it still exists" % (login,),
    }
    if state in repairs:
        log.warning("  repair: %s", repairs[state])
    return 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Tell apart the several different failures GitHub hides behind one 404.
 *
 * Read only. GET requests and nothing else: a token with read access is enough.
 * The repair is printed, never performed.
 */
const API = 'https://api.github.com';
const UA = 'github-404-triage/1.0';

// Longest prefixes first so a future prefix that extends an existing one cannot
// be swallowed by its shorter neighbour.
const PREFIXES = [
  ['github_pat_', 'fine-grained PAT'],
  ['ghp_', 'classic PAT'],
  ['gho_', 'OAuth user token'],
  ['ghu_', 'App user-to-server token'],
  ['ghs_', 'App installation token'],
  ['ghr_', 'App refresh token'],
];

/**
 * Name the credential from its prefix. Pure, and it never leaves the machine.
 */
export function tokenKind(token) {
  const value = String(token ?? '').trim();
  for (const [prefix, name] of PREFIXES) {
    if (value.startsWith(prefix)) return name;
  }
  return 'unknown';
}

/**
 * Read x-oauth-scopes into an array, keeping absent (null) and empty ([]) apart.
 * A classic token with nothing ticked sends an empty header; a fine-grained or
 * App token sends none at all, and those need opposite repairs.
 */
export function scopeList(headerValue) {
  if (headerValue === null || headerValue === undefined) return null;
  return headerValue.split(',').map((s) => s.trim()).filter(Boolean);
}

/**
 * Classify one 404. Pure, so the rules are readable rather than inferred.
 * Returns [state, detail].
 */
export function verdict(probe) {
  const status = probe.repo_status;

  if (!probe.authenticated) {
    return ['bad-credentials',
      'GET /user did not authenticate. Every private repository 404s for a dead ' +
      'token while every public one answers 200, which is why this looks like a ' +
      'per-repository permission problem.'];
  }

  if (status === 200) return ['visible', 'the repository answered 200'];
  if (status === 403) {
    return ['plain-403',
      '403 rather than 404, which is the honest one: rate limit, org IP allow ' +
      'list, or a policy that blocks this app. Read the message body and ' +
      'x-ratelimit-remaining before assuming access.'];
  }
  if (status !== 404) return ['unexpected', `HTTP ${status} is not the masked case`];

  if (probe.token_kind === 'App installation token') {
    const inside = probe.in_installation;
    if (inside === true) {
      return ['metadata-permission',
        'the repository is inside the installation, so it exists and you reach ' +
        'it. Every repository endpoint requires Metadata: Read; without it the ' +
        'repository itself 404s.'];
    }
    if (inside === false) {
      return ['not-in-installation',
        "the installation does not include this repository. repository_selection " +
        "is 'selected' and this one was never ticked, so it is outside the " +
        "token's world entirely."];
    }
    return ['installation-unknown',
      'GET /installation/repositories could not be read, so the installation ' +
      'question is open. Retry with the installation token the failing call ' +
      'actually uses.'];
  }

  const scopes = probe.scopes;
  if (scopes === null || scopes === undefined) {
    return ['repository-not-granted',
      'no x-oauth-scopes header, so this is a fine-grained token. Those grant ' +
      'repositories one at a time: this one is not in the token\'s repository ' +
      'list, or Metadata: Read is not on it.'];
  }
  if (!scopes.includes('repo')) {
    return ['missing-scope',
      `the token carries ${scopes.join(', ') || 'no scopes at all'} and not ` +
      "'repo'. Public repositories answer and private ones return exactly this 404."];
  }

  return ['no-access-or-gone',
    "the token authenticates and carries 'repo', so the scope is not the " +
    'problem. What is left is an account that was never granted access, or a ' +
    'repository that is genuinely gone. GitHub returns the same 404 for both on ' +
    'purpose and no header separates them.'];
}

function headers(token) {
  return {
    Authorization: `Bearer ${token}`,
    Accept: 'application/vnd.github+json',
    'X-GitHub-Api-Version': '2022-11-28',
    // GitHub rejects requests with no User-Agent outright, which is its own
    // confusing 403 and not the one this script is about.
    'User-Agent': UA,
  };
}

async function get(token, url, params = {}) {
  const u = new URL(url);
  for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v);
  return fetch(u, { headers: headers(token) });
}

export async function installationRepos(token, api, limit = 2000) {
  const out = [];
  let page = 1;
  while (out.length < limit) {
    const res = await get(token, `${api}/installation/repositories`,
                          { per_page: 100, page });
    if (res.status !== 200) return null;
    const items = (await res.json()).repositories ?? [];
    out.push(...items);
    if (items.length < 100) break;
    page += 1;
  }
  return out;
}

async function main() {
  const token = process.env.GITHUB_TOKEN;
  if (!token) {
    console.error('set GITHUB_TOKEN (a read-only token is enough)');
    process.exitCode = 2;
    return;
  }
  const target = process.argv[2];
  if (!target || !target.includes('/')) {
    console.error('pass the repository as owner/name');
    process.exitCode = 2;
    return;
  }

  const kind = tokenKind(token);
  const me = await get(token, `${API}/user`);
  const probe = {
    token_kind: kind,
    authenticated: me.status === 200,
    scopes: scopeList(me.headers.get('x-oauth-scopes')),
    in_installation: null,
  };
  const login = probe.authenticated ? (await me.json()).login : null;

  const repo = await get(token, `${API}/repos/${target}`);
  probe.repo_status = repo.status;

  if (kind === 'App installation token' && repo.status === 404) {
    const repos = await installationRepos(token, API);
    if (repos !== null) {
      const full = target.toLowerCase();
      probe.in_installation = repos.some(
        (r) => String(r.full_name ?? '').toLowerCase() === full);
    }
  }

  const [state, detail] = verdict(probe);
  const line = `${state.padEnd(22)} ${target}  ${detail}`;
  if (state === 'visible') {
    console.log(`${line} (authenticated as ${login})`);
    return;
  }

  console.warn(line);
  console.warn(`  token: ${kind}, login: ${login}, scopes: ` +
    `${probe.scopes === null ? 'absent' : (probe.scopes.join(', ') || 'none')}`);
  const repairs = {
    'bad-credentials': 're-mint the token and assert GET /user returns the ' +
      'expected login at startup',
    'missing-scope': "re-create the classic token with the 'repo' scope, or move " +
      'to a fine-grained token listing this repository',
    'repository-not-granted': "add this repository to the fine-grained token's " +
      'repository access, with Metadata: Read',
    'not-in-installation': 'add the repository to the App installation, or switch ' +
      'the installation to All repositories',
    'metadata-permission': 'add Metadata: Read to the App and have each ' +
      'installation accept the updated permissions',
    'no-access-or-gone': `grant ${login} access to the repository, or confirm ` +
      'with somebody who can see it that it still exists',
  };
  if (repairs[state]) console.warn(`  repair: ${repairs[state]}`);
  process.exitCode = 1;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing token, and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from github_404_triage import scope_list, token_kind, verdict


def probe(**kw):
    base = {"repo_status": 404, "authenticated": True, "scopes": ["repo"],
            "token_kind": "classic PAT", "in_installation": None}
    base.update(kw)
    return base


def test_prefixes_name_the_credential_without_sending_it():
    assert token_kind("ghp_abc123") == "classic PAT"
    assert token_kind("github_pat_11ABCDE") == "fine-grained PAT"
    assert token_kind("ghs_installation") == "App installation token"
    assert token_kind("  gho_padded  ") == "OAuth user token"
    assert token_kind("v1.0123deadbeef") == "unknown"
    assert token_kind(None) == "unknown"


def test_absent_scopes_header_is_not_an_empty_one():
    # The whole branch between "fine-grained token" and "classic token with
    # nothing ticked" hangs on this distinction.
    assert scope_list(None) is None
    assert scope_list("") == []
    assert scope_list("repo, read:org") == ["repo", "read:org"]


def test_dead_token_beats_every_other_reading():
    state, detail = verdict(probe(authenticated=False, scopes=None))
    assert state == "bad-credentials"
    assert "public" in detail


def test_a_repository_that_answers_is_visible():
    assert verdict(probe(repo_status=200))[0] == "visible"


def test_a_real_403_is_reported_as_the_honest_one():
    state, detail = verdict(probe(repo_status=403))
    assert state == "plain-403"
    assert "rate limit" in detail


def test_classic_token_without_repo_scope_names_the_scope():
    state, detail = verdict(probe(scopes=["public_repo"]))
    assert state == "missing-scope"
    assert "public_repo" in detail


def test_no_scopes_at_all_is_still_a_classic_token():
    state, detail = verdict(probe(scopes=[]))
    assert state == "missing-scope"
    assert "no scopes at all" in detail


def test_missing_scope_header_means_a_fine_grained_token():
    state, _ = verdict(probe(scopes=None, token_kind="fine-grained PAT"))
    assert state == "repository-not-granted"


def test_app_token_outside_the_installation_is_its_own_state():
    state, _ = verdict(probe(token_kind="App installation token",
                             scopes=None, in_installation=False))
    assert state == "not-in-installation"


def test_app_token_inside_the_installation_points_at_metadata():
    state, detail = verdict(probe(token_kind="App installation token",
                                  scopes=None, in_installation=True))
    assert state == "metadata-permission"
    assert "Metadata" in detail


def test_the_indistinguishable_case_stays_indistinguishable():
    # Alive, scoped, still 404. The script must not guess which of the two it is.
    state, detail = verdict(probe())
    assert state == "no-access-or-gone"
    assert "same 404" in detail

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { scopeList, tokenKind, verdict } from './github-404-triage.mjs';

const probe = (over = {}) => ({
  repo_status: 404, authenticated: true, scopes: ['repo'],
  token_kind: 'classic PAT', in_installation: null, ...over,
});

test('prefixes name the credential without sending it', () => {
  assert.equal(tokenKind('ghp_abc123'), 'classic PAT');
  assert.equal(tokenKind('github_pat_11ABCDE'), 'fine-grained PAT');
  assert.equal(tokenKind('ghs_installation'), 'App installation token');
  assert.equal(tokenKind('  gho_padded  '), 'OAuth user token');
  assert.equal(tokenKind('v1.0123deadbeef'), 'unknown');
  assert.equal(tokenKind(null), 'unknown');
});

test('an absent scopes header is not an empty one', () => {
  assert.equal(scopeList(null), null);
  assert.deepEqual(scopeList(''), []);
  assert.deepEqual(scopeList('repo, read:org'), ['repo', 'read:org']);
});

test('dead token beats every other reading', () => {
  const [state, detail] = verdict(probe({ authenticated: false, scopes: null }));
  assert.equal(state, 'bad-credentials');
  assert.match(detail, /public/);
});

test('a repository that answers is visible', () => {
  assert.equal(verdict(probe({ repo_status: 200 }))[0], 'visible');
});

test('a real 403 is reported as the honest one', () => {
  const [state, detail] = verdict(probe({ repo_status: 403 }));
  assert.equal(state, 'plain-403');
  assert.match(detail, /rate limit/);
});

test('classic token without repo scope names the scope', () => {
  const [state, detail] = verdict(probe({ scopes: ['public_repo'] }));
  assert.equal(state, 'missing-scope');
  assert.match(detail, /public_repo/);
});

test('no scopes at all is still a classic token', () => {
  const [state, detail] = verdict(probe({ scopes: [] }));
  assert.equal(state, 'missing-scope');
  assert.match(detail, /no scopes at all/);
});

test('missing scope header means a fine-grained token', () => {
  assert.equal(
    verdict(probe({ scopes: null, token_kind: 'fine-grained PAT' }))[0],
    'repository-not-granted');
});

test('app token outside the installation is its own state', () => {
  assert.equal(
    verdict(probe({ token_kind: 'App installation token', scopes: null,
                    in_installation: false }))[0],
    'not-in-installation');
});

test('app token inside the installation points at metadata', () => {
  const [state, detail] = verdict(probe({
    token_kind: 'App installation token', scopes: null, in_installation: true }));
  assert.equal(state, 'metadata-permission');
  assert.match(detail, /Metadata/);
});

test('the indistinguishable case stays indistinguishable', () => {
  const [state, detail] = verdict(probe());
  assert.equal(state, 'no-access-or-gone');
  assert.match(detail, /same 404/);
});