Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

12.4 KB
Raw Blame
/**
 * Which repositories a Swarm may use the Harness GitHub App on (docs/plans/2026-10-28-swarm-project-github-access.md).
 *
 * A project's repository address is text its owner types, and the app is installed on many people's repositories: without
 * this, anyone could name a repository the app is on as their project's and have the backend mint write tokens for it
 * (found 2026-10-28, with the app on autonomous-ai/openharness). Now a token goes to a project only once someone GitHub
 * says can push to the repository approved it, for that project or for every project of the Swarm. They approve by
 * signing in to GitHub through the app's own sign-in (its Client ID and secret): their short-lived token reads their
 * permission on the repository, is revoked at once, and is never stored.
 */
import { createHmac, hkdfSync, randomUUID, timingSafeEqual } from 'node:crypto'
import type { PrismaClient } from '@prisma/client'
import type { GitHubAppConfig } from './app.js'
import type { GitHubRepository } from './repository.js'

/** Every project of the Swarm, in an approval's `projectId`. */
export const WHOLE_SWARM = '*'
/** How long a sign-in may take, from the app asking to GitHub sending the person back. */
export const STATE_TTL_MS = 10 * 60_000

/** What a sign-in is for: who asked, in which Swarm and project, for which repository, and how widely. */
export interface ApprovalRequest {
  userId: string
  autonomousEnv: string
  tabId: string
  projectId: string
  /** owner/name, lower case. */
  repository: string
  scope: 'project' | 'swarm'
}

/** The key that signs a sign-in's state, derived from the app's private key: nothing further to configure. */
export function stateSecret(config: GitHubAppConfig): Buffer {
  const der = config.privateKey.export({ type: 'pkcs8', format: 'der' })
  return Buffer.from(hkdfSync('sha256', der, 'harness-github-approval-state', config.appId, 32))
}

export function signState(secret: Buffer, request: ApprovalRequest, now: number): string {
  const body = Buffer.from(JSON.stringify({ ...request, exp: now + STATE_TTL_MS })).toString('base64url')
  return `${body}.${createHmac('sha256', secret).update(body).digest('base64url')}`
}

/** The request a state was signed for, or null when it was not signed here, was changed, or is too old. */
export function readState(secret: Buffer, state: string, now: number): ApprovalRequest | null {
  const [body, signature, extra] = state.split('.')
  if (!body || !signature || extra !== undefined) return null
  const expected = createHmac('sha256', secret).update(body).digest()
  const given = Buffer.from(signature, 'base64url')
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null
  try {
    const value = JSON.parse(Buffer.from(body, 'base64url').toString()) as ApprovalRequest & { exp: number }
    if (typeof value.exp !== 'number' || value.exp < now || (value.scope !== 'project' && value.scope !== 'swarm')) return null
    for (const key of ['userId', 'autonomousEnv', 'tabId', 'projectId', 'repository'] as const) if (typeof value[key] !== 'string' || !value[key]) return null
    return { userId: value.userId, autonomousEnv: value.autonomousEnv, tabId: value.tabId, projectId: value.projectId, repository: value.repository, scope: value.scope }
  } catch { return null }
}

export interface GitHubSignInDeps { clientId: string; clientSecret: string; fetch?: typeof fetch; webUrl?: string; apiUrl?: string }

/** One GitHub API call with the person's user token: its status and its JSON object (empty when it has none). Throws when
 *  GitHub does not answer. */
export type UserCall = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: Record<string, unknown> }>

/** The Harness GitHub App's sign-in (GitHub's web application flow for an app's user access token). */
export class GitHubSignIn {
  private readonly fetch: typeof fetch
  private readonly webUrl: string
  private readonly apiUrl: string
  constructor(private readonly deps: GitHubSignInDeps) {
    this.fetch = deps.fetch ?? fetch
    this.webUrl = deps.webUrl ?? 'https://github.com'
    this.apiUrl = deps.apiUrl ?? 'https://api.github.com'
  }

  authorizeUrl(state: string): string {
    return `${this.webUrl}/login/oauth/authorize?client_id=${encodeURIComponent(this.deps.clientId)}&state=${encodeURIComponent(state)}`
  }

  /** What GitHub says [code]'s person may do on [repository]: their login, and whether they can push. The person's token
   *  is revoked before this answers, whatever it found. */
  async permission(code: string, repository: GitHubRepository): Promise<{ login: string; push: boolean } | null> {
    return this.withUserToken(code, async call => {
      const login = (await call('GET', '/user')).body.login
      if (typeof login !== 'string') return null
      // A renamed repository answers by redirect, which fetch follows; one the person cannot see answers 404.
      const repo = await call('GET', `/repos/${repository.owner}/${repository.name}`)
      const permissions = (repo.body.permissions ?? {}) as Record<string, unknown>
      return { login, push: repo.status === 200 && (permissions.push === true || permissions.maintain === true || permissions.admin === true) }
    }).then(seen => seen ?? null)
  }

  /** Runs [use] with the person's user token from [code], then revokes the token whatever happened (task #1788: creating a
   *  repository is a few calls with it). Null, with nothing run, when GitHub refuses the code. The token never leaves here. */
  async withUserToken<T>(code: string, use: (call: UserCall) => Promise<T>): Promise<T | null> {
    const exchanged = await this.fetch(`${this.webUrl}/login/oauth/access_token`, {
      method: 'POST', signal: AbortSignal.timeout(15_000),
      headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
      body: JSON.stringify({ client_id: this.deps.clientId, client_secret: this.deps.clientSecret, code }),
    })
    const token = ((await exchanged.json().catch(() => ({}))) as { access_token?: unknown }).access_token
    if (!exchanged.ok || typeof token !== 'string' || !token) return null
    const headers = { Accept: 'application/vnd.github+json', Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'harness-backend' }
    const call: UserCall = async (method, path, body) => {
      const answer = await this.fetch(`${this.apiUrl}${path}`, { method, signal: AbortSignal.timeout(15_000),
        headers: body === undefined ? headers : { ...headers, 'Content-Type': 'application/json' }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) })
      const parsed = await answer.json().catch(() => ({})) as unknown
      return { status: answer.status, body: parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {} }
    }
    try {
      return await use(call)
    } finally {
      await this.fetch(`${this.apiUrl}/applications/${encodeURIComponent(this.deps.clientId)}/token`, {
        method: 'DELETE', signal: AbortSignal.timeout(15_000),
        headers: { Accept: 'application/vnd.github+json', Authorization: `Basic ${Buffer.from(`${this.deps.clientId}:${this.deps.clientSecret}`).toString('base64')}`,
          'Content-Type': 'application/json' },
        body: JSON.stringify({ access_token: token }),
      }).then(answer => answer.status, () => 'no answer').then(status => {
        // Said, never with the token, so a token left live shows (security review 1 of #3201); it ends on its own at its expiry.
        if (status !== 204) console.warn(`[github] a sign-in's user token was not revoked (${status === 'no answer' ? status : `HTTP ${status}`})`)
      })
    }
  }
}

export function githubSignIn(env: { GITHUB_APP_CLIENT_ID: string; GITHUB_APP_CLIENT_SECRET: string }): GitHubSignIn | null {
  const clientId = env.GITHUB_APP_CLIENT_ID.trim(), clientSecret = env.GITHUB_APP_CLIENT_SECRET.trim()
  if (!clientId && !clientSecret) return null
  if (!clientId || !clientSecret) throw new Error('Set both GITHUB_APP_CLIENT_ID and GITHUB_APP_CLIENT_SECRET for the Harness GitHub App\'s sign-in, or neither.')
  return new GitHubSignIn({ clientId, clientSecret })
}

/** What GitHub last said about the reader on a repository: they can push (they allowed it before, in any Swarm), or they
 *  cannot (their sign-in was refused for this project). Null before they signed in for it. */
export interface ReaderAccess { canPush: boolean; githubLogin: string }

/** Where approvals are kept. */
export interface Approvals {
  approved(autonomousEnv: string, tabId: string, projectId: string, repository: string): Promise<boolean>
  approve(request: ApprovalRequest, githubLogin: string): Promise<void>
  /** GitHub said [request]'s person cannot push to its repository (2026-10-30 design: the app asks them to send it on). */
  refuse(request: ApprovalRequest, githubLogin: string): Promise<void>
  reader(autonomousEnv: string, tabId: string, projectId: string, repository: string, userId: string): Promise<ReaderAccess | null>
  /** The projects of [tabId] [repository] is approved for one by one (not those approved for the whole Swarm). */
  approvedProjects(autonomousEnv: string, tabId: string, repository: string): Promise<string[]>
}

export class PrismaApprovals implements Approvals {
  constructor(private readonly db: Pick<PrismaClient, 'gitHubRepositoryApproval' | 'gitHubApprovalRefusal'>) {}

  async approved(autonomousEnv: string, tabId: string, projectId: string, repository: string): Promise<boolean> {
    return !!await this.db.gitHubRepositoryApproval.findFirst({ where: { autonomousEnv, tabId, repository: repository.toLowerCase(),
      projectId: { in: [projectId, WHOLE_SWARM] } }, select: { id: true } })
  }

  async approvedProjects(autonomousEnv: string, tabId: string, repository: string): Promise<string[]> {
    const rows = await this.db.gitHubRepositoryApproval.findMany({ where: { autonomousEnv, tabId, repository: repository.toLowerCase(),
      projectId: { not: WHOLE_SWARM } }, select: { projectId: true } })
    return rows.map(r => r.projectId)
  }

  async approve(request: ApprovalRequest, githubLogin: string): Promise<void> {
    const projectId = request.scope === 'swarm' ? WHOLE_SWARM : request.projectId
    const where = { autonomousEnv_tabId_repository_projectId: { autonomousEnv: request.autonomousEnv, tabId: request.tabId,
      repository: request.repository, projectId } }
    await this.db.gitHubRepositoryApproval.upsert({ where, update: { approvedBy: request.userId, githubLogin },
      create: { id: randomUUID(), autonomousEnv: request.autonomousEnv, tabId: request.tabId, projectId, repository: request.repository,
        approvedBy: request.userId, githubLogin } })
    // Allowed now: nobody's refusal for it is worth showing any more.
    await this.db.gitHubApprovalRefusal.deleteMany({ where: { autonomousEnv: request.autonomousEnv, tabId: request.tabId,
      repository: request.repository, ...(request.scope === 'swarm' ? {} : { projectId: request.projectId }) } })
  }

  async refuse(request: ApprovalRequest, githubLogin: string): Promise<void> {
    const where = { autonomousEnv_tabId_repository_projectId_userId: { autonomousEnv: request.autonomousEnv, tabId: request.tabId,
      repository: request.repository, projectId: request.projectId, userId: request.userId } }
    await this.db.gitHubApprovalRefusal.upsert({ where, update: { githubLogin, createdAt: new Date() },
      create: { id: randomUUID(), autonomousEnv: request.autonomousEnv, tabId: request.tabId, projectId: request.projectId,
        repository: request.repository, userId: request.userId, githubLogin } })
  }

  async reader(autonomousEnv: string, tabId: string, projectId: string, repository: string, userId: string): Promise<ReaderAccess | null> {
    repository = repository.toLowerCase()
    const refused = await this.db.gitHubApprovalRefusal.findUnique({ where: { autonomousEnv_tabId_repository_projectId_userId:
      { autonomousEnv, tabId, repository, projectId, userId } }, select: { githubLogin: true } })
    if (refused) return { canPush: false, githubLogin: refused.githubLogin }
    // They allowed this repository before, for any project in any of their Swarms: GitHub said then that they can push to it
    // (2026-10-30: a new Swarm on a repository its owner had allowed in another Swarm showed no "You can push").
    const allowed = await this.db.gitHubRepositoryApproval.findFirst({ where: { autonomousEnv, repository, approvedBy: userId },
      select: { githubLogin: true } })
    return allowed ? { canPush: true, githubLogin: allowed.githubLogin } : null
  }
}