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.

17.8 KB
Raw Blame
/**
 * Installation tokens for Swarm agents (routes/superTabs.ts `github-token`): one per agent and task, kept until ten
 * minutes before it expires, and revoked as soon as that task ends (superTabs/store.ts `workEnded`).
 *
 * The cache is shared by every backend process (Redis in production), so a task closed on one process revokes the token
 * another process issued. Entries are sealed with a key derived from the app's private key (github/app.ts
 * `cacheSecret`). Nothing here logs a token.
 */
import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
import type { Redis } from 'ioredis'
import { logger } from '../utils/logger.js'
import { GitHubApp, GitHubAppError, PREPARE_PERMISSIONS, cacheSecret, githubAppConfig, type BranchProtection } from './app.js'
import type { GitHubRepository } from './repository.js'
import type { WorkHold } from './holds.js'

export interface TokenCache {
  get(key: string): Promise<string | null>
  set(key: string, value: string, ttlMs: number): Promise<void>
  delete(key: string): Promise<void>
  /** Adds [member] to the set at [key] in one step, and keeps the set [ttlMs] from now. */
  add(key: string, member: string, ttlMs: number): Promise<void>
  /** Takes the set at [key] whole, removing it in the same step: two callers never both get a member. */
  take(key: string): Promise<string[]>
}

/** One process's cache, for tests and a backend without Redis. */
export class MemoryTokenCache implements TokenCache {
  private readonly entries = new Map<string, { value: string; until: number }>()
  private readonly sets = new Map<string, { members: Set<string>; until: number }>()
  constructor(private readonly now: () => number = Date.now) {}
  async get(key: string) {
    const entry = this.entries.get(key)
    if (!entry || entry.until <= this.now()) { this.entries.delete(key); return null }
    return entry.value
  }
  async set(key: string, value: string, ttlMs: number) { this.entries.set(key, { value, until: this.now() + ttlMs }) }
  async delete(key: string) { this.entries.delete(key) }
  async add(key: string, member: string, ttlMs: number) {
    const set = this.sets.get(key)
    const members = set && set.until > this.now() ? set.members : new Set<string>()
    this.sets.set(key, { members: members.add(member), until: this.now() + ttlMs })
  }
  async take(key: string) {
    const set = this.sets.get(key)
    this.sets.delete(key)
    return set && set.until > this.now() ? [...set.members] : []
  }
}

/** The backend's shared Redis (lib/bus.ts `pub`), which fails fast rather than queueing while Redis is away. */
export class RedisTokenCache implements TokenCache {
  constructor(private readonly redis: Pick<Redis, 'get' | 'set' | 'del' | 'multi'>) {}
  async get(key: string) { return this.redis.get(key) }
  async set(key: string, value: string, ttlMs: number) { await this.redis.set(key, value, 'PX', Math.max(1, Math.floor(ttlMs))) }
  async delete(key: string) { await this.redis.del(key) }
  async add(key: string, member: string, ttlMs: number) {
    failed(await this.redis.multi().sadd(key, member).pexpire(key, Math.max(1, Math.floor(ttlMs))).exec())
  }
  async take(key: string) {
    // SMEMBERS and DEL in one transaction: no other instance reads or adds between them.
    const members = failed(await this.redis.multi().smembers(key).del(key).exec())[0]
    return Array.isArray(members) ? members.filter((m): m is string => typeof m === 'string') : []
  }
}

/** A Redis transaction's results, or its first error thrown. */
function failed(results: Array<[Error | null, unknown]> | null): unknown[] {
  if (!results) throw new Error('The Redis transaction was discarded.')
  for (const [error] of results) if (error) throw error
  return results.map(([, value]) => value)
}

/** What one agent's task may use. */
export interface TokenRequest { tabId: string; agentId: string; assignmentId: string; repository: GitHubRepository }
export interface IssuedToken {
  token: string
  expiresAt: string
  repository: string
  defaultBranch: string | null
  /** True only when a ruleset is known to require a pull request on the default branch. False asks the Lead to warn
   *  people that this token can push to it straight. */
  defaultBranchProtected: boolean
  defaultBranchProtection: BranchProtection
}
interface Entry { token: string; expiresAt: string; repository: string; assignmentId: string }

/** A token is handed out again until this long before it expires, so whoever holds it has at least that long. */
export const REUSE_MARGIN_MS = 10 * 60_000
const KEY_PREFIX = 'harness:github-token:v1'
/** How long a task's end is remembered: longer than any token GitHub gives (an hour), so no mint outlives it unseen. */
const RELEASED_MS = 70 * 60_000
const RELEASED = 'released'

export interface GitHubTokensOptions {
  now?: () => number
  log?: Pick<typeof logger, 'warn'>
  /** The sealing key (github/app.ts `cacheSecret`). */
  secret: Buffer
}

export class GitHubTokens {
  private readonly now: () => number
  private readonly log: Pick<typeof logger, 'warn'>
  private readonly secret: Buffer
  private readonly flights = new Map<string, Promise<IssuedToken>>()
  /** Each task's end and resumption, in the order the store reported them on this instance. */
  private readonly lifecycle = new Map<string, Promise<void>>()

  constructor(readonly app: GitHubApp, private readonly cache: TokenCache, options: GitHubTokensOptions) {
    this.now = options.now ?? Date.now
    this.log = options.log ?? logger
    if (options.secret.length !== 32) throw new Error('The GitHub token cache needs a 32-byte key.')
    this.secret = options.secret
  }

  private key(tabId: string, agentId: string) { return `${KEY_PREFIX}:${tabId}:${agentId}` }
  /** Every token minted for one task, sealed, in one shared set: what the task's end revokes (security review of #1976: two
   *  instances renewing at once each minted one, and the cached entry kept only the last). */
  private mintedKey(tabId: string, agentId: string, assignmentId: string) { return `${KEY_PREFIX}:minted:${tabId}:${agentId}:${assignmentId}` }
  private releasedKey(tabId: string, agentId: string, assignmentId: string) { return `${KEY_PREFIX}:released:${tabId}:${agentId}:${assignmentId}` }

  /** Whether the task's end was recorded (release). A cache that cannot say is read as not ended, as before. */
  private async released(request: TokenRequest): Promise<boolean> {
    try { return await this.cache.get(this.releasedKey(request.tabId, request.agentId, request.assignmentId)) === RELEASED } catch { return false }
  }

  private ended(): GitHubAppError { return new GitHubAppError('NO_ASSIGNMENT', 'This agent has no task in progress.', 409) }

  private seal(value: unknown): string {
    const iv = randomBytes(12)
    const cipher = createCipheriv('aes-256-gcm', this.secret, iv)
    const body = Buffer.concat([cipher.update(JSON.stringify(value), 'utf8'), cipher.final()])
    return [iv, cipher.getAuthTag(), body].map(part => part.toString('base64url')).join('.')
  }

  private unseal(value: string | null): Record<string, unknown> | null {
    if (!value) return null
    try {
      const [iv, tag, body] = value.split('.').map(part => Buffer.from(part, 'base64url'))
      const decipher = createDecipheriv('aes-256-gcm', this.secret, iv!)
      decipher.setAuthTag(tag!)
      const opened = JSON.parse(Buffer.concat([decipher.update(body!), decipher.final()]).toString('utf8')) as unknown
      return opened && typeof opened === 'object' ? opened as Record<string, unknown> : null
    } catch { return null }
  }

  private open(value: string | null): Entry | null {
    const entry = this.unseal(value)
    return entry && typeof entry.token === 'string' && typeof entry.expiresAt === 'string' && typeof entry.assignmentId === 'string'
      && typeof entry.repository === 'string' ? entry as unknown as Entry : null
  }

  private async read(key: string): Promise<Entry | null> {
    try { return this.open(await this.cache.get(key)) } catch (error) {
      this.log.warn('[github] token cache unreadable', { error: error instanceof Error ? error.message : String(error) })
      return null
    }
  }

  /** The agent's token for its task: the cached one while it has more than REUSE_MARGIN_MS left, else a new one. A token
   *  cached for an earlier task or another repository is revoked first. */
  async issue(request: TokenRequest): Promise<IssuedToken> {
    const key = this.key(request.tabId, request.agentId)
    const flight = `${key}:${request.assignmentId}:${request.repository.fullName}`
    const running = this.flights.get(flight)
    if (running) return running
    const work = this.mint(key, request).finally(() => this.flights.delete(flight))
    this.flights.set(flight, work)
    return work
  }

  private async mint(key: string, request: TokenRequest): Promise<IssuedToken> {
    const repository = request.repository.fullName
    if (await this.released(request)) throw this.ended()
    let actual = request.repository
    const cached = await this.read(key)
    let entry: Entry | null = null
    if (cached && cached.assignmentId === request.assignmentId && cached.repository === repository) {
      // Close to its end, it is left to expire: the agent may still be using it, in a push that took it before this renewal.
      // It stays among the task's minted tokens, so the task's end revokes it too (Lead, 2026-10-28).
      if (Date.parse(cached.expiresAt) - this.now() > REUSE_MARGIN_MS) entry = cached
    } else if (cached?.assignmentId === request.assignmentId) {
      // This task's, for another repository (the project's address changed): every token minted for it goes now.
      await this.revokeTask(request.tabId, request.agentId, cached.assignmentId, 'replaced', false, cached)
    }
    // Another task's entry is not this request's to end: a request may have waited across its own task's end and the
    // agent's next task, and ending what it found there revoked the live task's token and refused it (third security review
    // of #1976). That task's own end (release) takes every token minted for it, whichever entry is cached then.
    if (!entry) {
      // Under the name GitHub knows it by now (app.ts `resolve`); the agent's checkout keeps the name it was given, which
      // GitHub still answers for git.
      const resolved = await this.app.resolve(request.repository)
      if (resolved === null) throw this.app.notInstalled(request.repository)
      actual = resolved.repository
      const minted = await this.app.createToken(resolved.installation, actual)
      entry = { ...minted, repository, assignmentId: request.assignmentId }
      // Registered before anything else: the task's end takes this set whole, whichever instance minted what.
      try { await this.cache.add(this.mintedKey(request.tabId, request.agentId, request.assignmentId), this.seal({ token: entry.token, expiresAt: entry.expiresAt }), RELEASED_MS) } catch (error) {
        this.log.warn('[github] token not registered', { tabId: request.tabId, agentId: request.agentId, repository,
          error: error instanceof Error ? error.message : String(error) })
      }
      const ttl = Date.parse(minted.expiresAt) - this.now()
      if (ttl > 0) {
        try { await this.cache.set(key, this.seal(entry), ttl) } catch (error) {
          // Not cached, it cannot be revoked when the task ends; it still expires within the hour.
          this.log.warn('[github] token not cached', { tabId: request.tabId, agentId: request.agentId, repository,
            error: error instanceof Error ? error.message : String(error) })
        }
      }
      // Stored first, then checked: a task ended on another instance meanwhile (release marks it, then revokes what is
      // stored) either finds this token there or is seen here, so a token minted for an ended task never stays valid
      // (security review of #1976: a renewal in flight across that end kept a token good for an hour).
      if (await this.released(request)) {
        await this.revokeTokens(request.tabId, request.agentId, repository, [entry.token], 'task ended while minting')
        if ((await this.read(key))?.token === entry.token) await this.forget(key)
        throw this.ended()
      }
    }
    const branch = await this.app.defaultBranch(actual, entry.token)
    return { token: entry.token, expiresAt: entry.expiresAt, repository, defaultBranch: branch.branch,
      defaultBranchProtected: branch.protection === 'pull_request', defaultBranchProtection: branch.protection }
  }

  /**
   * A token that only reads [repository], for a machine preparing a Swarm agent's folder before the agent exists (routes/
   * superTabs.ts, a start's `github-token`): the clone and the fetch of its default branch, so that the machine's own git
   * login is never used for another person's project. Never cached: one start asks once, and it lasts at most an hour.
   */
  async prepare(repository: GitHubRepository): Promise<{ token: string; expiresAt: string; repository: string }> {
    const resolved = await this.app.resolve(repository)
    if (resolved === null) throw this.app.notInstalled(repository)
    const minted = await this.app.createToken(resolved.installation, resolved.repository, PREPARE_PERMISSIONS)
    return { ...minted, repository: repository.fullName }
  }

  private async revokeTokens(tabId: string, agentId: string, repository: string, tokens: readonly string[], why: string): Promise<void> {
    for (const token of new Set(tokens)) {
      try { await this.app.revoke(token) } catch (error) {
        this.log.warn('[github] token revoke failed', { tabId, agentId, repository, why, code: error instanceof GitHubAppError ? error.code : 'ERROR' })
      }
    }
  }

  /**
   * Revokes every unexpired token minted for one task, taken whole from the shared set, and the cached one ([entry], also
   * from before that set), and forgets the cached one. [ended]: the task is over, so it is marked first: a mint finishing
   * on another instance after the mark revokes its own token (mint).
   */
  private async revokeTask(tabId: string, agentId: string, assignmentId: string, why: string, ended: boolean, entry: Entry | null): Promise<void> {
    if (ended) {
      try { await this.cache.set(this.releasedKey(tabId, agentId, assignmentId), RELEASED, RELEASED_MS) } catch (error) {
        this.log.warn('[github] task end not recorded', { tabId, agentId, error: error instanceof Error ? error.message : String(error) })
      }
    }
    let minted: string[] = []
    try { minted = await this.cache.take(this.mintedKey(tabId, agentId, assignmentId)) } catch (error) {
      this.log.warn('[github] minted tokens unreadable', { tabId, agentId, error: error instanceof Error ? error.message : String(error) })
    }
    const live = minted.map(value => this.unseal(value))
      .filter((t): t is { token: string; expiresAt: string } => typeof t?.token === 'string' && typeof t.expiresAt === 'string')
      .filter(t => Date.parse(t.expiresAt) > this.now()).map(t => t.token)
    const cached = entry?.assignmentId === assignmentId ? [entry.token] : []
    await this.revokeTokens(tabId, agentId, entry?.repository ?? '', [...cached, ...live], why)
    if (entry) await this.forget(this.key(tabId, agentId))
  }

  private async forget(key: string): Promise<void> {
    try { await this.cache.delete(key) } catch (error) {
      this.log.warn('[github] token cache entry not removed', { error: error instanceof Error ? error.message : String(error) })
    }
  }

  /** The tasks that ended in [tabId] (done, cancelled, stopped, reassigned, or the agent removed): each one's cached token is
   *  revoked and forgotten. Never throws; a failed revoke is logged without the token and leaves the token to expire. */
  async release(tabId: string, ended: readonly WorkHold[]): Promise<void> {
    await Promise.all(ended.map(hold => this.inOrder(tabId, hold, async () => {
      const entry = await this.read(this.key(tabId, hold.agentId))
      await this.revokeTask(tabId, hold.agentId, hold.assignmentId, 'task ended', true, entry?.assignmentId === hold.assignmentId ? entry : null)
    })))
  }

  /** Tasks in progress again under the same id (resumed after a usage limit lost them): their end is forgotten, so they get
   *  tokens again. Every token from before the loss stays revoked; nothing minted before it is handed out again (security
   *  re-check of #1976: a resumed task was refused tokens for 70 minutes). Never throws. */
  async resume(tabId: string, started: readonly WorkHold[]): Promise<void> {
    await Promise.all(started.map(hold => this.inOrder(tabId, hold, async () => {
      try { await this.cache.delete(this.releasedKey(tabId, hold.agentId, hold.assignmentId)) } catch (error) {
        this.log.warn('[github] task resumption not recorded', { tabId, agentId: hold.agentId, error: error instanceof Error ? error.message : String(error) })
      }
    })))
  }

  /** Runs [work] after this task's earlier end or resumption on this instance: a loss and the resumption after it are
   *  reported in that order, and the end's mark must not land after the resumption cleared it. */
  private inOrder(tabId: string, hold: WorkHold, work: () => Promise<void>): Promise<void> {
    const key = `${tabId}:${hold.agentId}:${hold.assignmentId}`
    const next = (this.lifecycle.get(key) ?? Promise.resolve()).then(work, work)
    const settled = next.catch(() => undefined)
    this.lifecycle.set(key, settled)
    void settled.then(() => { if (this.lifecycle.get(key) === settled) this.lifecycle.delete(key) })
    return next
  }
}

/** The app from the server's environment, sharing tokens through Redis; null when it is not configured. */
export async function githubTokensFromEnv(env: { GITHUB_APP_ID: string; GITHUB_APP_PRIVATE_KEY: string; GITHUB_APP_SLUG: string }): Promise<GitHubTokens | null> {
  const config = githubAppConfig(env)
  if (!config) return null
  // Loaded only when configured: importing the bus opens its Redis connections.
  const { pub } = await import('../lib/bus.js')
  return new GitHubTokens(new GitHubApp(config), new RedisTokenCache(pub), { secret: cacheSecret(config) })
}