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.

14.7 KB
Raw Blame
/**
 * Connected services: one private tokens.json per user, shared by every local agent (Grid's format,
 * ~/.grid/connectors/tokens.json). Agents never read it: MCP clients reach a service through the bridge
 * (bridge.ts) and `harness connections call` reads a token for one request.
 *
 * Kept at the product root (`~/.harness/connections`), beside the computer id and outside cli/data:
 * `harness reset` must not sign a person out of their services. No zod: the edge host loads this.
 */
import { closeSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, constants, existsSync, chmodSync } from 'node:fs'
import { homedir } from 'node:os'
import { join } from 'node:path'
import { randomUUID } from 'node:crypto'
import { cleanRestEntry, transport, type RestEntry, type Transport } from './rest.js'

export const MAX_BYTES = 1024 * 1024
/** A token is renewed this long before it expires, as Grid does. */
export const REFRESH_MARGIN = 300
export const CODE = /^[a-z0-9][a-z0-9_-]{0,47}$/
/** Codes saved before the catalog followed Grid's, and Grid's code for them now. */
export const RENAMED: Record<string, string> = { apollo: 'apollo_io', supermetrics_marketing: 'supermetrics' }

export class ConnectorError extends Error {}

export type Source = 'dcr' | 'gateway' | 'custom'
export interface McpEntry { url: string, headers: Record<string, string> }
/**
 * A service reached by its own REST API with a key, for Harness itself rather than for the agents: the cloud
 * agents' service calls Devin's and Cursor's APIs through the bridge (`/<key>/<code>/api/…`, bridge.ts), which
 * adds the key. With no MCP server or REST tools beside it, `transport` is `none`, so no agent is given it.
 */
export interface ApiEntry { origin: string }
export interface Token {
  access_token?: string
  refresh_token?: string
  token_type?: string
  scope?: string
  account_name?: string
  source?: Source
  issuer?: string
  label?: string
  expires_at?: number
  obtained_at?: number
  refresh?: boolean
  needs_reconnect?: boolean
  mcp_entry?: McpEntry
  /** A service with no usable MCP server: its REST tools, served as MCP by the bridge (rest.ts). */
  rest_entry?: RestEntry
  /** The gateway's word on which of the two agents use. */
  transport?: Transport
  api_entry?: ApiEntry
}
export interface Client {
  client_id: string
  client_secret: string
  token_endpoint_auth_method: string
  authorization_endpoint: string
  token_endpoint: string
  redirect_uri: string
  registered_at: number
}

export function connectorsDir(env: NodeJS.ProcessEnv = process.env): string {
  return env.HARNESS_CONNECTIONS_DIR || join(env.HOME || homedir(), '.harness', 'connections')
}

/** Harness OS 0.1.2 kept them here, before the CLI did; read once, then the CLI's copy is the one. */
function legacyDir(env: NodeJS.ProcessEnv): string {
  return join(env.XDG_DATA_HOME || join(env.HOME || homedir(), '.local', 'share'), 'harness-os', 'connections')
}

export function validateCode(code: unknown): string {
  if (typeof code !== 'string' || !CODE.test(code)) throw new ConnectorError('Unknown connection.')
  return code
}

function privateDirectory(dir: string): void {
  mkdirSync(dir, { recursive: true, mode: 0o700 })
  const info = lstatSync(dir)
  if (!info.isDirectory() || info.isSymbolicLink() || (process.getuid && info.uid !== process.getuid())) {
    throw new ConnectorError('Connections must be stored in your own directory, without a symlink.')
  }
  chmodSync(dir, 0o700)
}

export function readPrivate(path: string): Record<string, unknown> | null {
  let fd: number
  try { fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)) } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
    throw new ConnectorError('Cannot read connection settings.')
  }
  try {
    const info = fstatSync(fd)
    const foreign = process.getuid ? info.uid !== process.getuid() : false
    if (!info.isFile() || foreign || (process.platform !== 'win32' && (info.mode & 0o077)) || info.size > MAX_BYTES) {
      throw new ConnectorError('Connection settings must be private, regular files owned by you.')
    }
    let data: unknown
    try { data = JSON.parse(readFileSync(fd, 'utf8')) } catch { throw new ConnectorError('Cannot read connection settings.') }
    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new ConnectorError('Invalid connection settings.')
    return data as Record<string, unknown>
  } finally { closeSync(fd) }
}

export function writePrivate(path: string, data: unknown): void {
  const dir = join(path, '..')
  privateDirectory(dir)
  const raw = JSON.stringify(data, null, 2) + '\n'
  if (Buffer.byteLength(raw) > MAX_BYTES) throw new ConnectorError('Connection settings are too large.')
  const temporary = join(dir, `.incoming-${randomUUID()}`)
  let fd: number | undefined
  try {
    fd = openSync(temporary, 'wx', 0o600)
    writeFileSync(fd, raw)
    fsyncSync(fd)
    closeSync(fd)
    fd = undefined
    renameSync(temporary, path)
  } finally {
    if (fd !== undefined) closeSync(fd)
    rmSync(temporary, { force: true })
  }
}

/** One writer at a time across agents, the bridge and the page: an exclusive lock file, waited for (`waitMs`, then it throws). */
export function locked<T>(dir: string, work: () => T, waitMs = 35_000): T {
  privateDirectory(dir)
  const lock = join(dir, '.lock')
  const deadline = Date.now() + waitMs
  for (;;) {
    try { closeSync(openSync(lock, 'wx', 0o600)); break } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw new ConnectorError('Invalid connection lock.')
      // A holder that died leaves its lock: one older than a minute is stale.
      try { if (Date.now() - lstatSync(lock).mtimeMs > 60_000) { rmSync(lock, { force: true }); continue } } catch { continue }
      if (Date.now() > deadline) throw new ConnectorError('Another connection operation is still running. Try again.')
      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50)
    }
  }
  try { return work() } finally { rmSync(lock, { force: true }) }
}

export function text(value: unknown, limit = 8192): string {
  if (value === undefined || value === null) return ''
  if (typeof value !== 'string' || value.length > limit || /[\u0000-\u001f\u007f]/.test(value)) throw new ConnectorError('Invalid connection fields.')
  return value
}

export function cleanHeaders(headers: unknown): Record<string, string> {
  if (headers === undefined || headers === null) return {}
  if (typeof headers !== 'object' || Array.isArray(headers) || Object.keys(headers).length > 20) throw new ConnectorError('Invalid connection headers.')
  const result: Record<string, string> = {}
  for (const [name, value] of Object.entries(headers)) {
    if (!/^[A-Za-z0-9-]{1,64}$/.test(name)) throw new ConnectorError('Invalid connection headers.')
    result[name] = text(value)
  }
  return result
}

export function cleanUrl(value: unknown): string {
  const raw = text(value, 2048)
  let url: URL
  try { url = new URL(raw) } catch { throw new ConnectorError('Use an https:// address for the server.') }
  const local = url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
  if (!(url.protocol === 'https:' || local) || url.username || url.password) throw new ConnectorError('Use an https:// address for the server.')
  return raw
}

/** A tokens.json entry, as Grid writes it, with nothing unexpected kept. */
export function cleanToken(entry: unknown): Token {
  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new ConnectorError('Invalid connection.')
  const raw = entry as Record<string, unknown>
  const result: Token = {}
  for (const key of ['access_token', 'refresh_token', 'token_type', 'scope', 'account_name', 'source', 'issuer', 'label'] as const) {
    const value = text(raw[key])
    if (value) (result as Record<string, unknown>)[key] = value
  }
  if (!['dcr', 'gateway', 'custom'].includes(result.source ?? 'dcr')) throw new ConnectorError('Unsupported connection source.')
  for (const key of ['expires_at', 'obtained_at'] as const) {
    const value = raw[key] ?? 0
    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) throw new ConnectorError('Invalid connection expiry.')
    if (value) result[key] = value
  }
  if (raw.refresh === true) result.refresh = true
  if (raw.needs_reconnect === true) result.needs_reconnect = true
  const mcp = raw.mcp_entry
  if (mcp) {
    if (typeof mcp !== 'object' || Array.isArray(mcp)) throw new ConnectorError('Invalid connection server.')
    const entryRaw = mcp as Record<string, unknown>
    result.mcp_entry = { url: cleanUrl(entryRaw.url), headers: cleanHeaders(entryRaw.headers) }
  }
  const rest = cleanRestEntry(raw.rest_entry)
  if (rest) result.rest_entry = rest
  if (raw.transport === 'mcp' || raw.transport === 'rest' || raw.transport === 'none') result.transport = raw.transport
  const api = raw.api_entry
  if (api) {
    if (typeof api !== 'object' || Array.isArray(api)) throw new ConnectorError('Invalid connection server.')
    // Only the origin: a path or query saved here would be where a request was bent somewhere else.
    result.api_entry = { origin: new URL(cleanUrl((api as Record<string, unknown>).origin)).origin }
  }
  if (!result.access_token && !result.mcp_entry) throw new ConnectorError('No access token was supplied.')
  return result
}

/** The Authorization value for a token, its scheme normalised as Grid does. */
export function bearer(token: Token): string {
  const scheme = token.token_type || 'Bearer'
  return `${scheme.toLowerCase() === 'bearer' ? 'Bearer' : scheme} ${token.access_token}`
}

export function refreshable(token: Token): boolean {
  return token.source === 'gateway' ? token.refresh === true : Boolean(token.refresh_token)
}

export function needsRefresh(token: Token, now = Date.now() / 1000): boolean {
  const expires = token.expires_at ?? 0
  return Boolean(expires) && expires - REFRESH_MARGIN <= now && refreshable(token) && !token.needs_reconnect
}

export interface Status {
  connector: string
  name: string
  state: 'not_connected' | 'connected' | 'reconnect'
  account?: string
  source?: Source
  scopes?: string[]
  expires_at?: number | null
  auto_refresh?: boolean
  tools?: boolean
}

export class Store {
  readonly root: string
  constructor(root?: string, private readonly env: NodeJS.ProcessEnv = process.env) {
    this.root = root ?? connectorsDir(env)
    if (!root) this.adoptLegacy()
  }

  /** Harness OS kept connections in its own folder before the CLI did: moved here once. */
  private adoptLegacy(): void {
    const old = legacyDir(this.env)
    if (existsSync(join(this.root, 'tokens.json')) || !existsSync(join(old, 'tokens.json'))) return
    try {
      for (const name of ['tokens.json', 'clients.json', 'bridge.json']) {
        const data = readPrivate(join(old, name))
        if (data) writePrivate(join(this.root, name), data)
      }
    } catch { /* An unreadable old store is left where it is; nothing is lost. */ }
  }

  file(name: string): Record<string, unknown> {
    if (existsSync(this.root) && lstatSync(this.root).isSymbolicLink()) throw new ConnectorError('Connection storage must not be a symlink.')
    return readPrivate(join(this.root, name)) ?? {}
  }

  tokens(): Record<string, Token> {
    const result: Record<string, Token> = {}
    for (const [code, entry] of Object.entries(this.file('tokens.json'))) {
      if (!CODE.test(code)) continue
      const name = RENAMED[code] ?? code
      if (!(name in result)) result[name] = cleanToken(entry)
    }
    return result
  }

  token(code: string): Token | undefined {
    validateCode(code)
    return this.tokens()[RENAMED[code] ?? code]
  }

  /** Save one connection, replacing it. Call inside locked(). */
  put(code: string, entry: Token): void {
    validateCode(code)
    const data = this.file('tokens.json')
    for (const [old, now] of Object.entries(RENAMED)) if (now === code) delete data[old]
    data[code] = cleanToken(entry)
    writePrivate(join(this.root, 'tokens.json'), data)
  }

  save(code: string, entry: Token): void { locked(this.root, () => this.put(code, entry)) }

  /** Remove one connection another computer disconnected: no disconnect of this computer's is recorded.
   *  Call inside locked(). */
  drop(code: string): void {
    validateCode(code)
    const data = this.file('tokens.json')
    if (!(code in data)) return
    delete data[code]
    writePrivate(join(this.root, 'tokens.json'), data)
  }

  disconnect(code: string): void {
    validateCode(code)
    const names = [code, ...Object.entries(RENAMED).filter(([, now]) => now === code).map(([old]) => old)]
    locked(this.root, () => {
      const data = this.file('tokens.json')
      if (names.some(name => name in data)) {
        for (const name of names) delete data[name]
        writePrivate(join(this.root, 'tokens.json'), data)
        // When: the account's other computers drop it too, unless one connected it again since (vaultSync.ts).
        this.putRemoved({ ...this.removed(), [code]: Math.floor(Date.now() / 1000) })
      }
    })
  }

  /** Connections disconnected here, and when (epoch seconds), for the account's other computers. */
  removed(): Record<string, number> {
    const result: Record<string, number> = {}
    for (const [code, at] of Object.entries(this.file('removed.json'))) {
      if (CODE.test(code) && typeof at === 'number' && Number.isInteger(at) && at > 0) result[code] = at
    }
    return result
  }

  /** Call inside locked(). */
  putRemoved(removed: Record<string, number>): void {
    writePrivate(join(this.root, 'removed.json'), removed)
  }

  client(issuer: string): Client | undefined {
    const entry = this.file('clients.json')[issuer]
    return entry && typeof entry === 'object' ? entry as Client : undefined
  }

  saveClient(issuer: string, client: Client): void { locked(this.root, () => this.putClient(issuer, client)) }

  /** Call inside locked(). */
  putClient(issuer: string, client: Client): void {
    const data = this.file('clients.json')
    data[issuer] = client
    writePrivate(join(this.root, 'clients.json'), data)
  }

  status(code: string, label: string, token?: Token): Status {
    const base = { connector: code, name: token?.label || label }
    if (!token) return { ...base, state: 'not_connected' }
    const expires = token.expires_at ?? 0
    const expired = Boolean(expires) && expires <= Date.now() / 1000
    const state = token.needs_reconnect || (expired && !refreshable(token)) ? 'reconnect' : 'connected'
    return {
      ...base, state, account: token.account_name ?? '', source: token.source ?? 'dcr',
      scopes: (token.scope ?? '').split(/\s+/).filter(Boolean), expires_at: expires || null,
      auto_refresh: refreshable(token), tools: transport(token) !== 'none',
    }
  }
}