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.

15.7 KB
Raw Blame
/**
 * Sign in to an MCP server from this computer: MCP OAuth with dynamic client registration (RFC 7591),
 * PKCE S256 and a 127.0.0.1 redirect (Grid's `dcr` path). No client secret ships with Harness: each
 * computer registers its own public client with the service and keeps it in clients.json.
 */
import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
import { createServer, type Server } from 'node:http'
import { bearer, cleanUrl, ConnectorError, MAX_BYTES, type Client, type Store, type Token } from './store.js'

const TIMEOUT_MS = 15_000
export const SIGN_IN_MS = 300_000
/** Grid's preferred loopback ports, then any free one. */
const PORTS = [51789, 51790, 51791, 51792, 0]

export class SignInError extends ConnectorError {}

interface Answer { status: number, headers: Headers, body: string }

export async function http(url: string, init: { body?: string, headers?: Record<string, string>, method?: string } = {}): Promise<Answer> {
  try {
    const response = await fetch(url, {
      method: init.method ?? (init.body !== undefined ? 'POST' : 'GET'), body: init.body, redirect: 'manual',
      headers: { 'User-Agent': 'Harness-Connections', Accept: 'application/json', ...init.headers },
      signal: AbortSignal.timeout(TIMEOUT_MS),
    })
    const body = await response.text()
    return { status: response.status, headers: response.headers, body: body.slice(0, MAX_BYTES) }
  } catch { throw new SignInError('Could not reach the service. Check the connection and try again.') }
}

function jsonOf(body: string): Record<string, unknown> | null {
  try {
    const data = JSON.parse(body)
    return data && typeof data === 'object' && !Array.isArray(data) ? data : null
  } catch { return null }
}

function wellKnown(base: string, name: string, path = ''): string {
  const url = new URL(base)
  return `${url.protocol}//${url.host}/.well-known/${name}${path.replace(/\/$/, '')}`
}

export interface OAuthMeta {
  kind: 'oauth'
  issuer: string
  resource: string
  scopes: string[]
  authorization_endpoint: string
  token_endpoint: string
  registration_endpoint?: string
  s256: boolean
}
export type Probe = { kind: 'open' } | OAuthMeta

/** The protected-resource metadata a server publishes (RFC 9728): its authorization server, the resource it names, its scopes. */
async function protectedResource(url: string, pointed?: string): Promise<{ issuer: string; resource: string; scopes: string[] } | null> {
  const path = new URL(url).pathname
  for (const candidate of [pointed, wellKnown(url, 'oauth-protected-resource', path), wellKnown(url, 'oauth-protected-resource')]) {
    if (!candidate) continue
    const answer = await http(candidate)
    const meta = answer.status === 200 ? jsonOf(answer.body) : null
    const servers = meta?.authorization_servers
    if (Array.isArray(servers) && typeof servers[0] === 'string') {
      return {
        issuer: servers[0],
        resource: typeof meta!.resource === 'string' ? meta!.resource : url,
        scopes: Array.isArray(meta!.scopes_supported) ? meta!.scopes_supported.filter((s): s is string => typeof s === 'string') : [],
      }
    }
  }
  return null
}

/** What signing in to this MCP server takes: nothing (`open`) or its OAuth metadata. */
export async function probe(server: string): Promise<Probe> {
  const url = cleanUrl(server)
  const initialize = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {
    protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'Harness', version: '1' } } })
  const first = await http(url, { body: initialize, headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' } })
  let found: { issuer: string; resource: string; scopes: string[] } | null
  if (first.status >= 200 && first.status < 300) {
    // A server may answer `initialize` (and list its tools) to anyone and refuse only a tool's call: Wajo's Fo
    // did (2026-10-11), and was saved with no sign-in, every call then refused. It still says it is protected
    // in its resource metadata: that, and only that, makes an open answer a sign-in.
    found = await protectedResource(url)
    if (!found) return { kind: 'open' }
  } else {
    if (first.status !== 401 && first.status !== 403) throw new SignInError(`The server answered ${first.status}. Check the address.`)
    const challenge = first.headers.get('www-authenticate') ?? ''
    found = await protectedResource(url, /resource_metadata="([^"]+)"/.exec(challenge)?.[1])
  }
  let issuer = found?.issuer
  const resource = found?.resource ?? url
  const scopes = found?.scopes ?? []
  const base = new URL(url)
  issuer ??= `${base.protocol}//${base.host}`
  const issuerPath = new URL(issuer).pathname
  for (const candidate of [wellKnown(issuer, 'oauth-authorization-server', issuerPath), wellKnown(issuer, 'openid-configuration', issuerPath),
    issuer.replace(/\/$/, '') + '/.well-known/openid-configuration']) {
    const answer = await http(candidate)
    const meta = answer.status === 200 ? jsonOf(answer.body) : null
    if (meta && typeof meta.authorization_endpoint === 'string' && typeof meta.token_endpoint === 'string') {
      for (const key of ['authorization_endpoint', 'token_endpoint', 'registration_endpoint']) if (meta[key]) cleanUrl(meta[key])
      const methods = Array.isArray(meta.code_challenge_methods_supported) ? meta.code_challenge_methods_supported : ['S256']
      return {
        kind: 'oauth', issuer, resource, scopes,
        authorization_endpoint: meta.authorization_endpoint, token_endpoint: meta.token_endpoint,
        registration_endpoint: typeof meta.registration_endpoint === 'string' ? meta.registration_endpoint : undefined,
        s256: methods.includes('S256'),
      }
    }
  }
  throw new SignInError('This server does not say how to sign in.')
}

/** One sign-in's redirect target on 127.0.0.1. */
class Callback {
  result: Record<string, string> | null = null
  private done!: () => void
  readonly finished = new Promise<void>(resolve => { this.done = resolve })
  constructor(readonly server: Server, readonly port: number) {
    server.on('request', (request, response) => {
      const url = new URL(request.url ?? '/', 'http://127.0.0.1')
      if (url.pathname !== '/callback') { response.writeHead(404).end(); return }
      this.result = Object.fromEntries(url.searchParams)
      const ok = 'code' in this.result
      const page = '<!doctype html><meta charset=utf-8><title>Harness</title>'
        + "<body style='font:16px ui-monospace,monospace;background:#11140f;color:#e7e8de;padding:48px'>"
        + (ok ? '<h1>Connected.</h1><p>You can close this tab and return to Harness.</p><script>setTimeout(()=>window.close(),800)</script>'
          : '<h1>Not connected.</h1><p>Return to Harness and try again.</p>')
      response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' }).end(page)
      this.done()
    })
  }
  get redirectUri(): string { return `http://127.0.0.1:${this.port}/callback` }
  /** The same redirect, read by another device whose browser was sent to it (a phone, over the relay). */
  deliver(address: string): void {
    let url: URL
    try { url = new URL(address) } catch { throw new SignInError('This is not the sign-in address.') }
    if (url.origin + url.pathname !== this.redirectUri) throw new SignInError('This is not the sign-in address.')
    if (this.result) return
    this.result = Object.fromEntries(url.searchParams)
    this.done()
  }
  close(): void { this.server.close(); this.server.closeAllConnections?.() }
}

async function listen(): Promise<Callback> {
  for (const port of PORTS) {
    const server = createServer()
    const bound = await new Promise<number | null>(resolve => {
      server.once('error', () => resolve(null))
      server.listen(port, '127.0.0.1', () => resolve((server.address() as { port: number }).port))
    })
    if (bound !== null) return new Callback(server, bound)
  }
  throw new SignInError('Could not open a local sign-in address.')
}

export function pkce(): { verifier: string, challenge: string } {
  const verifier = randomBytes(48).toString('base64url')
  return { verifier, challenge: createHash('sha256').update(verifier).digest('base64url') }
}

/** This computer's OAuth client for the issuer, registered once and reused. */
async function register(vault: Store, meta: OAuthMeta, redirectUri: string): Promise<Client> {
  const known = vault.client(meta.issuer)
  if (known?.client_id && known.redirect_uri === redirectUri) return known
  if (!meta.registration_endpoint) throw new SignInError('This service does not let a computer register itself.')
  const answer = await http(meta.registration_endpoint, { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({
    client_name: 'Harness', redirect_uris: [redirectUri], grant_types: ['authorization_code', 'refresh_token'],
    response_types: ['code'], token_endpoint_auth_method: 'none', application_type: 'native',
  }) })
  const data = jsonOf(answer.body)
  if ((answer.status !== 200 && answer.status !== 201) || typeof data?.client_id !== 'string') {
    throw new SignInError('The service refused to register Harness on this computer.')
  }
  const secret = typeof data.client_secret === 'string' ? data.client_secret : ''
  const client: Client = {
    client_id: data.client_id, client_secret: secret,
    token_endpoint_auth_method: typeof data.token_endpoint_auth_method === 'string' ? data.token_endpoint_auth_method : (secret ? 'client_secret_basic' : 'none'),
    authorization_endpoint: meta.authorization_endpoint, token_endpoint: meta.token_endpoint,
    redirect_uri: redirectUri, registered_at: Math.floor(Date.now() / 1000),
  }
  vault.saveClient(meta.issuer, client)
  return client
}

async function tokenRequest(client: Client, form: Record<string, string>): Promise<Record<string, unknown>> {
  const headers: Record<string, string> = { 'Content-Type': 'application/x-www-form-urlencoded' }
  const fields: Record<string, string> = { ...form, client_id: client.client_id }
  if (client.client_secret) {
    if (client.token_endpoint_auth_method === 'client_secret_post') fields.client_secret = client.client_secret
    else headers.Authorization = 'Basic ' + Buffer.from(`${encodeURIComponent(client.client_id)}:${encodeURIComponent(client.client_secret)}`).toString('base64')
  }
  const answer = await http(client.token_endpoint, { headers, body: new URLSearchParams(fields).toString() })
  const data = jsonOf(answer.body) ?? {}
  if (answer.status !== 200 || typeof data.access_token !== 'string') {
    throw new SignInError(data.error === 'invalid_grant' ? 'invalid_grant' : 'The service did not issue a token.')
  }
  return data
}

function tokenFrom(data: Record<string, unknown>, mcpUrl: string, issuer: string, previous?: Token): Token {
  const now = Math.floor(Date.now() / 1000)
  const expiresIn = typeof data.expires_in === 'number' && data.expires_in > 0 ? Math.floor(data.expires_in) : 0
  const token: Token = {
    access_token: data.access_token as string, token_type: typeof data.token_type === 'string' ? data.token_type : 'Bearer',
    refresh_token: (typeof data.refresh_token === 'string' && data.refresh_token) || previous?.refresh_token || '',
    expires_at: expiresIn ? now + expiresIn : 0,
    scope: typeof data.scope === 'string' ? data.scope : previous?.scope ?? '',
    source: 'dcr', issuer, obtained_at: now, account_name: previous?.account_name ?? '',
  }
  token.mcp_entry = { url: mcpUrl, headers: { Authorization: bearer(token) } }
  if (token.refresh_token) token.refresh = true
  return token
}

export interface SignIn {
  /** The address to open in a browser, or null when the server needs no sign-in. */
  prepare(): Promise<string | null>
  wait(cancelled?: () => boolean): Promise<Token>
  /** The browser's redirect, when it reached another device instead of this computer. */
  deliver?(url: string): void
}

/** One browser sign-in to an MCP server: prepare() gives the address to open, wait() the token. */
export class LocalSignIn implements SignIn {
  private meta?: Probe
  private callback?: Callback
  private client?: Client
  private verifier = ''
  private state = ''
  constructor(private readonly vault: Store, private readonly mcpUrl: string) { cleanUrl(mcpUrl) }

  async prepare(): Promise<string | null> {
    this.meta = await probe(this.mcpUrl)
    if (this.meta.kind === 'open') return null
    if (!this.meta.s256) throw new SignInError('This service does not support a secure sign-in from a computer.')
    this.callback = await listen()
    try { this.client = await register(this.vault, this.meta, this.callback.redirectUri) } catch (error) { this.callback.close(); throw error }
    const { verifier, challenge } = pkce()
    this.verifier = verifier
    this.state = randomBytes(24).toString('base64url')
    const query = new URLSearchParams({ response_type: 'code', client_id: this.client.client_id, redirect_uri: this.callback.redirectUri,
      state: this.state, code_challenge: challenge, code_challenge_method: 'S256' })
    if (this.meta.resource) query.set('resource', this.meta.resource)
    if (this.meta.scopes.length) query.set('scope', this.meta.scopes.join(' '))
    const endpoint = this.client.authorization_endpoint
    return endpoint + (endpoint.includes('?') ? '&' : '?') + query.toString()
  }

  /**
   * A phone that opened the sign-in in its own browser caught the redirect to this computer's
   * 127.0.0.1 address and sent it here. Only that exact address counts; wait() then checks state
   * and exchanges the code with the PKCE verifier, which never leaves this computer.
   */
  deliver(url: string): void {
    if (!this.callback) throw new SignInError('This sign-in needs no address.')
    this.callback.deliver(url)
  }

  async wait(cancelled: () => boolean = () => false): Promise<Token> {
    if (!this.callback || this.meta?.kind !== 'oauth') {
      return { mcp_entry: { url: this.mcpUrl, headers: {} }, source: 'dcr', obtained_at: Math.floor(Date.now() / 1000) }
    }
    const callback = this.callback
    try {
      const deadline = Date.now() + SIGN_IN_MS
      while (!callback.result) {
        if (Date.now() > deadline || cancelled()) throw new SignInError('The sign-in was not finished in time.')
        await Promise.race([callback.finished, new Promise(resolve => setTimeout(resolve, 250))])
      }
    } finally { callback.close() }
    const result = callback.result
    const state = Buffer.from(result.state ?? '')
    if (state.length !== Buffer.byteLength(this.state) || !timingSafeEqual(state, Buffer.from(this.state))) {
      throw new SignInError('The sign-in could not be confirmed. Try again.')
    }
    if (!result.code) throw new SignInError(result.error === 'access_denied' ? 'The sign-in was cancelled.' : 'The service did not complete the sign-in.')
    const form: Record<string, string> = { grant_type: 'authorization_code', code: result.code, redirect_uri: callback.redirectUri, code_verifier: this.verifier }
    if (this.meta.resource) form.resource = this.meta.resource
    return tokenFrom(await tokenRequest(this.client!, form), this.mcpUrl, this.meta.issuer)
  }
}

/** A renewed `dcr` token, through this computer's registered client. */
export async function refresh(vault: Store, token: Token): Promise<Token> {
  const client = vault.client(token.issuer ?? '')
  if (!client || !token.refresh_token || !token.mcp_entry) throw new SignInError('invalid_grant')
  const mcpUrl = token.mcp_entry.url
  const form: Record<string, string> = { grant_type: 'refresh_token', refresh_token: token.refresh_token, resource: mcpUrl }
  let data: Record<string, unknown>
  try { data = await tokenRequest(client, form) } catch (error) {
    if ((error as Error).message === 'invalid_grant') throw error
    // A service may reject the resource parameter on refresh; ask once more without it.
    delete form.resource
    data = await tokenRequest(client, form)
  }
  return tokenFrom(data, mcpUrl, token.issuer!, token)
}