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.8 KB
Raw Blame
import { randomBytes } from 'node:crypto'
import type { HarnessSession, Prisma, PrismaClient } from '@prisma/client'
import { pub } from './bus.js'
import { signInsChanged } from './harnessAuthCache.js'
import { prisma } from './prisma.js'
import { ensureIndex } from './db/indexes.js'
import { decryptMachineCredential, encryptMachineCredential } from './machineCredential.js'
import { normalizeSsoClientId, refreshAccessToken, SsoTokenError, type SsoClientId } from './sso.js'
import { authenticateAccessToken, SsoAuthError } from './ssoAuth.js'
import { storedAutonomousEnvironment, type AutonomousEnvironment } from './autonomousEnvironment.js'
import { logger } from '../utils/logger.js'

/**
 * Harness sessions an SSO sign-in backs: the CLI and Desktop sign in through Autonomous SSO once, then hold a session of
 * Harness's own (lib/harnessSession.ts), so an ordinary request never waits on the account service.
 *
 *   CLI → POST /api/auth/exchange  { …, harnessSession: { kind, label } }  → { token: hna_…, refreshToken: hnr_…, harnessSession: true }
 *   CLI → POST /api/auth/refresh   { refreshToken: <SSO>, harnessSession } → the same: today's sign-ins move over on renewal
 *   CLI → POST /api/auth/refresh   { refreshToken: hnr_… }                 → a new access token, re-checked with SSO hourly
 *
 * The person's SSO refresh token stays here, encrypted on the session (lib/machineCredential.ts), and is never handed to
 * a client again. Every renewal of the session re-checks it with SSO at most once an hour ([SSO_RECHECK_MS]):
 *
 *   - SSO renews it: the rotated refresh token is saved, and the session goes on.
 *   - SSO refuses it, and the token held is the one the last renewal saved: the person signed out of Autonomous or the
 *     account was disabled. The session ends, and its stored tokens with it.
 *   - Anything else — SSO slow, down, failing, answering for another account, or refusing a token after a renewal that
 *     never finished — is SSO UNAVAILABLE, never a sign-out: the session goes on for [SSO_OUTAGE_GRACE_MS] from its last
 *     good check. After that its renewals answer `SIGN_IN_AGAIN`, which a client shows as "Sign in again": the session
 *     is not ended (SSO coming back renews it), but nobody is left retrying a sign-in that may never work again.
 *
 * Every write a renewal makes is on a session still live: one signed out while SSO was answering gets nothing back.
 * An access token is kept only once SSO's profile service has confirmed whose it is, so billing never forwards one
 * that was not.
 *
 * Two renewals of one session never ask SSO at once: a renewal takes the session's lock in Redis, and one that finds it
 * taken goes on without asking. Before asking, a renewal marks the session (`ssoRenewingAt`); only saving SSO's answer
 * clears the mark. A mark left behind means a rotated refresh token may have been lost on the way (a pod died, the save
 * failed, the request timed out after SSO answered), and so a refusal of the stored token proves nothing.
 *
 * A session made here names no computer, even for a computer: naming one is what lets a sign-in turn that computer into a
 * team machine without its machine key (routes/auth.ts `isThisComputer`), and an SSO sign-in has never had that power.
 */

export const SSO_RECHECK_MS = 60 * 60_000
export const SSO_OUTAGE_GRACE_MS = 7 * 24 * 60 * 60_000
/** How long ended and idle-expired sessions are kept before their expiry index deletes them ([ensureHarnessSessionExpiry]). */
export const ENDED_SESSION_KEEP_MS = 30 * 24 * 60 * 60_000
/** Longer than a renewal can take (two SSO calls, each bounded by `SSO_PROFILE_TIMEOUT_MS`). */
const RENEW_LOCK_SEC = 60
/** An access token kept for billing is renewed this long before it runs out. */
const ACCESS_SKEW_MS = 60_000

const lockKey = (sessionId: string): string => `hnauth:ssorenew:${sessionId}`
/** How long billing waits for another renewal of the same session to finish before it says unavailable. */
const BUSY_WAIT_MS = RENEW_LOCK_SEC * 1000
const BUSY_POLL_MS = 100
// Not yet revoked. On MongoDB `revokedAt: null` alone does not match a field that is absent (lib/harnessSession.ts).
const notRevoked: Prisma.HarnessSessionWhereInput = { OR: [{ revokedAt: null }, { revokedAt: { isSet: false } }] }
// Delete the lock only if it is still this renewal's: one that outlived its lock must not release the next one's.
const RELEASE_SCRIPT = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) end return 0`

export type SsoSessionKind = 'computer' | 'viewer'
export interface SsoSessionRequest { kind: SsoSessionKind; label: string }

/**
 * What a sign-in or renewal asks for in `harnessSession`: undefined when it asks for nothing (an older client, which
 * keeps its SSO tokens), null when it asks for something that is not a computer's or a viewer's session.
 */
export function parseSsoSessionRequest(raw: unknown): SsoSessionRequest | null | undefined {
  if (raw === undefined || raw === null) return undefined
  if (typeof raw !== 'object' || Array.isArray(raw)) return null
  const { kind, label } = raw as { kind?: unknown; label?: unknown }
  if (kind !== 'computer' && kind !== 'viewer') return null
  if (label !== undefined && typeof label !== 'string') return null
  const named = (label ?? '').trim().slice(0, 80)
  return { kind, label: named || (kind === 'computer' ? 'Computer' : 'Desktop') }
}

/** An SSO sign-in's tokens, as the token endpoint gave them. */
export interface SsoGrant { accessToken: string; refreshToken: string; expiresIn?: number }

const accessExpiry = (expiresIn: number | undefined, now: number): Date | null =>
  typeof expiresIn === 'number' && expiresIn > 0 ? new Date(now + expiresIn * 1000) : null

/** The fields a new session keeps for its SSO sign-in. Throws when they cannot be encrypted (no credential key). */
export function ssoSessionData(grant: SsoGrant, autonomousEnv: AutonomousEnvironment, clientId: SsoClientId | undefined, now = Date.now()) {
  return {
    ssoRefresh: encryptMachineCredential(grant.refreshToken),
    ssoAccess: encryptMachineCredential(grant.accessToken),
    ssoAccessExpiresAt: accessExpiry(grant.expiresIn, now),
    ssoEnv: autonomousEnv,
    ...(clientId ? { ssoClientId: clientId } : {}),
    ssoCheckedAt: new Date(now),
  }
}

/** A session ending: it is revoked, the SSO tokens it held are deleted with it, and it expires now — so the expiry
 *  index deletes the row [ENDED_SESSION_KEEP_MS] later ([ensureHarnessSessionExpiry]). */
export function endedSessionData(now = new Date()) {
  return { revokedAt: now, expiresAt: now, ssoRefresh: null, ssoAccess: null, ssoAccessExpiresAt: null, ssoRenewingAt: null }
}

type Renewal =
  | { outcome: 'renewed'; accessToken: string }
  /** Another renewal saved a good answer meanwhile: [row] is the session as it left it. */
  | { outcome: 'fresh'; row: HarnessSession }
  | { outcome: 'ended' }
  | { outcome: 'busy' }
  | { outcome: 'unavailable' }

const unavailable = (): SsoAuthError =>
  new SsoAuthError('The sign-in service is unavailable; retrying', 'AUTH_SERVICE_UNAVAILABLE')

/** A renewal past the outage grace: shown to the person as "Sign in again" (lib/ssoSession.ts, above). */
export const ssoSignInAgainError = (): SsoAuthError =>
  new SsoAuthError('Sign in again: this sign-in could not be confirmed with your Autonomous account for 7 days', 'SIGN_IN_AGAIN')

/** Write [data] on session [sessionId] only while it is live. False when it ended meanwhile: nothing was written. */
async function writeLive(sessionId: string, data: Prisma.HarnessSessionUpdateManyMutationInput): Promise<boolean> {
  const { count } = await prisma.harnessSession.updateMany({ where: { id: sessionId, ...notRevoked }, data })
  return count > 0
}

/** Why a renewal could not get an answer, for the log: an error's kind, never its text (which could quote a request). */
const reasonOf = (err: unknown): string =>
  err instanceof SsoTokenError || err instanceof SsoAuthError ? err.code : err instanceof Error ? err.name : 'unknown'

/**
 * Ask SSO to renew session [sessionId]'s sign-in, once, under its lock — unless [fresh] says the session, read again
 * under the lock, no longer needs it.
 */
async function renew(sessionId: string, fresh: (row: HarnessSession, now: number) => boolean): Promise<Renewal> {
  const owner = randomBytes(16).toString('hex')
  if (await pub.set(lockKey(sessionId), owner, 'EX', RENEW_LOCK_SEC, 'NX') !== 'OK') return { outcome: 'busy' }
  try {
    const row = await prisma.harnessSession.findUnique({ where: { id: sessionId } })
    if (!row || row.revokedAt) return { outcome: 'ended' }
    if (!row.ssoRefresh) return { outcome: 'unavailable' }
    const now = Date.now()
    if (fresh(row, now)) return { outcome: 'fresh', row }

    const unfinished = row.ssoRenewingAt instanceof Date
    if (!unfinished && !(await writeLive(sessionId, { ssoRenewingAt: new Date(now) }))) return { outcome: 'ended' }
    const held = decryptMachineCredential(row.ssoRefresh)
    const autonomousEnv = storedAutonomousEnvironment(row.ssoEnv)
    let tokens: Awaited<ReturnType<typeof refreshAccessToken>>
    try {
      tokens = await refreshAccessToken(held, autonomousEnv, normalizeSsoClientId(row.ssoClientId))
    } catch (err) {
      if (err instanceof SsoTokenError && err.code === 'INVALID_GRANT' && !unfinished) {
        await writeLive(sessionId, endedSessionData())
        await signInsChanged(row.userId)
        logger.info('sso sign-in ended a harness session', { sessionId, userId: row.userId })
        return { outcome: 'ended' }
      }
      logger.warn('sso re-check unavailable', { sessionId, userId: row.userId, reason: reasonOf(err), unfinished })
      return { outcome: 'unavailable' }
    }
    const accessToken = tokens.access_token
    const refreshToken = tokens.refresh_token || held
    if (!accessToken) {
      logger.warn('sso re-check unavailable', { sessionId, userId: row.userId, reason: 'NO_ACCESS_TOKEN', unfinished })
      return { outcome: 'unavailable' }
    }
    // The renewed sign-in must still be this session's person. Not reachable is unavailable, and so is someone else:
    // nothing here says this person signed out, and their session is not handed to the other account either.
    let identity: Awaited<ReturnType<typeof authenticateAccessToken>> | null = null
    try { identity = await authenticateAccessToken(accessToken, autonomousEnv, { allowHarnessSession: false }) } catch (err) {
      logger.warn('sso re-check unavailable', { sessionId, userId: row.userId, reason: reasonOf(err), unfinished })
    }
    if (identity && identity.sub !== row.userId) {
      logger.warn('sso re-check answered for another account', { sessionId, userId: row.userId })
      return { outcome: 'unavailable' }
    }
    // Saved in one write, which also clears the mark — on a session still live: one signed out while SSO answered keeps
    // nothing. Unidentified, the rotated refresh token is still kept (losing it would lose the sign-in), but its access
    // token is not, and the session is not counted as checked.
    const saved = await writeLive(sessionId, {
      ssoRefresh: encryptMachineCredential(refreshToken),
      ssoAccess: identity ? encryptMachineCredential(accessToken) : null,
      ssoAccessExpiresAt: identity ? accessExpiry(tokens.expires_in, now) : null,
      ssoRenewingAt: null,
      ...(identity ? { ssoCheckedAt: new Date(now) } : {}),
    })
    if (!saved) return { outcome: 'ended' }
    return identity ? { outcome: 'renewed', accessToken } : { outcome: 'unavailable' }
  } catch (err) {
    // Redis, Mongo or the credential key failing: a mark already written stays.
    logger.warn('sso re-check unavailable', { sessionId, reason: reasonOf(err) })
    return { outcome: 'unavailable' }
  } finally {
    await pub.eval(RELEASE_SCRIPT, 1, lockKey(sessionId), owner).catch(() => { /* it runs out on its own */ })
  }
}

/**
 * Whether session [session] may renew, as far as its SSO sign-in goes: `ok`, `ended` (it ended: the caller's 401), or
 * `sign-in-again` (SSO has not confirmed the sign-in within the grace: [ssoSignInAgainError]). A session no SSO sign-in
 * backs is always `ok`.
 */
export async function recheckSsoSession(session: HarnessSession): Promise<'ok' | 'ended' | 'sign-in-again'> {
  if (!session.ssoRefresh) return 'ok'
  const checkedAt = session.ssoCheckedAt?.getTime() ?? 0
  const recent = (row: HarnessSession, now: number): boolean => now - (row.ssoCheckedAt?.getTime() ?? 0) < SSO_RECHECK_MS
  if (recent(session, Date.now())) return 'ok'
  let renewal: Renewal
  try { renewal = await renew(session.id, recent) } catch (err) {
    logger.warn('sso re-check unavailable', { sessionId: session.id, reason: reasonOf(err) })
    renewal = { outcome: 'unavailable' }
  }
  if (renewal.outcome === 'ended') return 'ended'
  if (renewal.outcome === 'renewed' || renewal.outcome === 'fresh') return 'ok'
  return Date.now() - checkedAt < SSO_OUTAGE_GRACE_MS ? 'ok' : 'sign-in-again'
}

/**
 * An SSO access token for session [sessionId] of [userId], for the routes that forward one to the account service
 * (billing, lib/autonomousBff.ts). Null when the session is not that person's, has ended, or has no SSO sign-in
 * behind it (a QR or handoff session). Throws `AUTH_SERVICE_UNAVAILABLE` when SSO cannot give one now. Only a token
 * whose identity SSO confirmed is ever kept, so only such a token is ever handed on. A call that finds another renewal
 * of the session under way waits for it and reads its answer, rather than failing.
 */
export async function ssoAccessTokenFor(sessionId: string, userId: string): Promise<string | null> {
  const usable = (r: HarnessSession, now: number): boolean =>
    !!r.ssoAccess && r.ssoAccessExpiresAt instanceof Date && r.ssoAccessExpiresAt.getTime() > now + ACCESS_SKEW_MS
  const waitUntil = Date.now() + BUSY_WAIT_MS
  for (;;) {
    const row = await prisma.harnessSession.findUnique({ where: { id: sessionId } })
    if (!row || row.userId !== userId || row.revokedAt || !row.ssoRefresh) return null
    if (usable(row, Date.now())) return decryptMachineCredential(row.ssoAccess!)
    const renewal = await renew(sessionId, usable)
    if (renewal.outcome === 'renewed') return renewal.accessToken
    if (renewal.outcome === 'fresh') return decryptMachineCredential(renewal.row.ssoAccess!)
    if (renewal.outcome === 'ended') return null
    if (renewal.outcome === 'unavailable' || Date.now() >= waitUntil) throw unavailable()
    await new Promise((resolve) => setTimeout(resolve, BUSY_POLL_MS))
  }
}

/**
 * Sessions are deleted [ENDED_SESSION_KEEP_MS] after they expire: idle past their lifetime, or ended
 * ([endedSessionData] expires them). Nothing else deletes them. Run by the worker at start (lib/db/schemaRelease.ts).
 */
export async function ensureHarnessSessionExpiry(db: Pick<PrismaClient, '$runCommandRaw'>): Promise<void> {
  await ensureIndex(db, 'harness_sessions', { key: { expiresAt: 1 }, name: 'harness_session_expiry', expireAfterSeconds: ENDED_SESSION_KEEP_MS / 1000 })
}