Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

11.4 KB
Raw Blame
import type { Counter, Histogram } from '@opentelemetry/api';
import { getLogger } from './logger.ts';
import { type ParsedOriginTransport, sameGitHubLogin } from './share/git-context.ts';
import type { GitHubAccountSource } from './share/github-account.ts';
import { getMeter } from './telemetry.ts';

const log = getLogger('github-permissions');

const PROBE_TIMEOUT_MS = 5000;

export type FetchFn = typeof fetch;

type PushPermissionDeniedReason =
  | 'no-collaborator'
  | 'private-no-access'
  | 'repo-not-found'
  | 'not-authenticated';

type PushPermissionUnknownError =
  | 'network'
  | 'timeout'
  | 'rate-limit'
  | 'token-invalid'
  | 'malformed-response'
  | 'ssh-unverified';

type DeclaredAccountSource = Exclude<GitHubAccountSource, 'active'>;

export type PushPermission =
  | { kind: 'allowed' }
  | {
      kind: 'denied';
      reason: PushPermissionDeniedReason;
      resolvedLogin?: string;
      declaredLogin?: string;
      declaredSource?: DeclaredAccountSource;
    }
  | { kind: 'unknown'; error: PushPermissionUnknownError };

export type DetectGhFn = (
  host?: string,
  options?: { login?: string },
) =>
  | { available: false }
  | { available: true; token: string; resolvedLogin?: string; fallback?: boolean };

export type DetectGhAccountsFn = (
  host?: string,
) => Array<{ login: string; active: boolean }> | undefined;

export interface ProbeTokenStore {
  get(host: string): Promise<{ token?: string; login?: string } | null>;
}

type ProbeAccount =
  | { source: 'active'; login?: undefined }
  | { source: DeclaredAccountSource; login: string };

export interface CheckPushPermissionOptions {
  owner: string;
  repo: string;
  host?: string;
  transport?: ParsedOriginTransport;
  account?: ProbeAccount;
  detectGh?: DetectGhFn;
  detectGhAccounts?: DetectGhAccountsFn;
  tokenStore?: ProbeTokenStore | null;
  _fetchFn?: FetchFn;
  _timeoutMs?: number;
}

function githubApiBase(host: string): string {
  return host === 'github.com' ? 'https://api.github.com' : `https://${host}/api/v3`;
}

function buildHeaders(token: string | undefined): Record<string, string> {
  const headers: Record<string, string> = {
    'User-Agent': 'open-knowledge-server',
    Accept: 'application/vnd.github+json',
  };
  if (token) headers.Authorization = `Bearer ${token}`;
  return headers;
}

export function isGitHubRateLimited(response: {
  readonly status: number;
  readonly headers: Headers;
}): boolean {
  return (
    response.status === 429 ||
    (response.status === 403 &&
      (response.headers.get('x-ratelimit-remaining') === '0' ||
        response.headers.get('retry-after') !== null))
  );
}

function readPushFlag(body: unknown): boolean | null {
  if (typeof body !== 'object' || body === null) return null;
  const perms = (body as { permissions?: unknown }).permissions;
  if (typeof perms !== 'object' || perms === null) return null;
  const push = (perms as { push?: unknown }).push;
  return typeof push === 'boolean' ? push : null;
}

async function classify(resp: Response, hadToken: boolean): Promise<PushPermission> {
  switch (resp.status) {
    case 200: {
      let body: unknown;
      try {
        body = await resp.json();
      } catch (err) {
        log.warn({ err }, '[permissions] probe got 200 with unparseable JSON body');
        return { kind: 'unknown', error: 'malformed-response' };
      }
      const push = readPushFlag(body);
      if (push === null) {
        log.warn(
          { bodyKeys: typeof body === 'object' && body !== null ? Object.keys(body) : [] },
          '[permissions] probe got 200 without permissions.push field',
        );
        return { kind: 'unknown', error: 'malformed-response' };
      }
      return push ? { kind: 'allowed' } : { kind: 'denied', reason: 'no-collaborator' };
    }
    case 401:
      return { kind: 'unknown', error: 'token-invalid' };
    case 403:
    case 429:
      return isGitHubRateLimited(resp)
        ? { kind: 'unknown', error: 'rate-limit' }
        : { kind: 'unknown', error: 'token-invalid' };
    case 404:
      return hadToken
        ? { kind: 'denied', reason: 'private-no-access' }
        : { kind: 'denied', reason: 'repo-not-found' };
    default:
      log.warn({ httpStatus: resp.status }, '[permissions] probe got unexpected HTTP status');
      return { kind: 'unknown', error: 'malformed-response' };
  }
}

async function resolveProbeTokenWithSource(
  host: string,
  account: ProbeAccount | undefined,
  detectGh: DetectGhFn,
  tokenStore: ProbeTokenStore | null | undefined,
  detectGhAccounts: DetectGhAccountsFn | undefined,
): Promise<{
  token: string | undefined;
  source: 'gh' | 'token-store' | 'anonymous';
  resolvedLogin?: string;
}> {
  const gh = detectGh(host, { login: account?.login });
  if (gh.available && gh.token) {
    if (account?.login !== undefined && gh.fallback === true) {
      const activeLogin = activeAccountLogin(detectGhAccounts, host);
      if (!sameGitHubLogin(activeLogin, account.login)) {
        log.warn(
          {
            host,
            declaredLogin: account.login,
            declaredSource: account.source,
            resolvedLogin: activeLogin,
          },
          '[permissions] declared GitHub account did not produce the gh token — probing as the active account',
        );
      }
    }
    return { token: gh.token, source: 'gh', resolvedLogin: gh.resolvedLogin };
  }
  if (tokenStore) {
    try {
      const entry = await tokenStore.get(host);
      if (entry?.token) {
        const login = entry.login !== 'unknown' ? entry.login : undefined;
        return { token: entry.token, source: 'token-store', resolvedLogin: login };
      }
    } catch (err) {
      log.warn({ err, host }, '[permissions] tokenStore.get threw; falling through to anonymous');
    }
  }
  return { token: undefined, source: 'anonymous' };
}

function withDeniedIdentity(
  denied: Extract<PushPermission, { kind: 'denied' }>,
  opts: {
    account: ProbeAccount | undefined;
    tokenSource: 'gh' | 'token-store' | 'anonymous';
    resolvedLogin: string | undefined;
    detectGhAccounts: DetectGhAccountsFn | undefined;
    host: string;
  },
): Extract<PushPermission, { kind: 'denied' }> {
  const resolvedLogin =
    opts.resolvedLogin ??
    (opts.tokenSource === 'gh' ? activeAccountLogin(opts.detectGhAccounts, opts.host) : undefined);
  return {
    ...denied,
    ...(resolvedLogin !== undefined ? { resolvedLogin } : {}),
    ...declaredMissFields(opts.account, resolvedLogin),
  };
}

function declaredMissFields(
  account: ProbeAccount | undefined,
  resolvedLogin: string | undefined,
): Pick<Extract<PushPermission, { kind: 'denied' }>, 'declaredLogin' | 'declaredSource'> {
  if (account?.login === undefined) return {};
  if (sameGitHubLogin(account.login, resolvedLogin)) return {};
  return { declaredLogin: account.login, declaredSource: account.source };
}

function activeAccountLogin(
  detectGhAccounts: DetectGhAccountsFn | undefined,
  host: string,
): string | undefined {
  if (!detectGhAccounts) return undefined;
  try {
    return detectGhAccounts(host)?.find((a) => a.active)?.login;
  } catch (err) {
    log.warn({ err, host }, '[permissions] detectGhAccounts failed — denial stays unnamed');
    return undefined;
  }
}

async function runProbe(opts: CheckPushPermissionOptions): Promise<PushPermission> {
  const {
    owner,
    repo,
    host = 'github.com',
    transport = 'https',
    account,
    detectGh = () => ({ available: false }),
    detectGhAccounts,
    tokenStore,
    _fetchFn = fetch,
    _timeoutMs = PROBE_TIMEOUT_MS,
  } = opts;

  const {
    token,
    source: tokenSource,
    resolvedLogin,
  } = await resolveProbeTokenWithSource(host, account, detectGh, tokenStore, detectGhAccounts);

  if (tokenSource === 'anonymous') {
    if (transport === 'ssh' || transport === 'git') {
      log.info(
        { host, transport },
        '[permissions] no credential resolved for ssh/git origin — abstaining (push auths with SSH keys, not tokens)',
      );
      return { kind: 'unknown', error: 'ssh-unverified' };
    }
    log.info({ host }, '[permissions] no credential resolved — denying push (read-only)');
    return {
      kind: 'denied',
      reason: 'not-authenticated',
      ...declaredMissFields(account, undefined),
    };
  }

  const url = `${githubApiBase(host)}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;

  log.info(
    {
      host,
      tokenSource,
      tokenLen: token === undefined ? 0 : token.length,
    },
    '[permissions] probe starting',
  );

  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), _timeoutMs);
  try {
    const resp = await _fetchFn(url, { signal: ac.signal, headers: buildHeaders(token) });
    const classified = await classify(resp, token !== undefined);
    const result =
      classified.kind === 'denied'
        ? withDeniedIdentity(classified, {
            account,
            tokenSource,
            resolvedLogin,
            detectGhAccounts,
            host,
          })
        : classified;
    log.info(
      {
        host,
        tokenSource,
        httpStatus: resp.status,
        kind: result.kind,
        reason: result.kind === 'denied' ? result.reason : undefined,
        error: result.kind === 'unknown' ? result.error : undefined,
      },
      '[permissions] probe classified',
    );
    return result;
  } catch (err) {
    if (ac.signal.aborted) {
      log.warn({ host, timeoutMs: _timeoutMs }, '[permissions] probe timed out');
      return { kind: 'unknown', error: 'timeout' };
    }
    log.warn({ err, host }, '[permissions] probe failed');
    return { kind: 'unknown', error: 'network' };
  } finally {
    clearTimeout(timer);
  }
}

export async function checkPushPermission(
  opts: CheckPushPermissionOptions,
): Promise<PushPermission> {
  const start = performance.now();
  const result = await runProbe(opts);
  recordProbeTelemetry(result, performance.now() - start);
  return result;
}

interface ProbeOutcomeAttributes extends Record<string, string> {
  outcome: PushPermission['kind'];
  denied_reason: PushPermissionDeniedReason | 'none';
  error_class: PushPermissionUnknownError | 'none';
}

function outcomeAttributes(result: PushPermission): ProbeOutcomeAttributes {
  return {
    outcome: result.kind,
    denied_reason: result.kind === 'denied' ? result.reason : 'none',
    error_class: result.kind === 'unknown' ? result.error : 'none',
  };
}

let _outcomeCounter: Counter | null = null;
function outcomeCounter(): Counter {
  _outcomeCounter ||= getMeter().createCounter('ok.permissions.probe.outcome_total', {
    description:
      'Push-permission probe outcomes. Bounded labels: outcome ∈ {allowed,denied,unknown}; denied_reason ∈ {no-collaborator,private-no-access,repo-not-found,not-authenticated,none}; error_class ∈ {network,timeout,rate-limit,token-invalid,malformed-response,ssh-unverified,none}.',
  });
  return _outcomeCounter;
}

let _durationHist: Histogram | null = null;
function durationHist(): Histogram {
  _durationHist ||= getMeter().createHistogram('ok.permissions.probe.duration_ms', {
    description: 'Push-permission probe wall-clock duration.',
    unit: 'ms',
  });
  return _durationHist;
}

function recordProbeTelemetry(result: PushPermission, durationMs: number): void {
  const attrs = outcomeAttributes(result);
  outcomeCounter().add(1, attrs);
  durationHist().record(durationMs, { outcome: attrs.outcome });
}

export function __resetGithubPermissionsTelemetryForTests(): void {
  _outcomeCounter = null;
  _durationHist = null;
}