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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { afterAll, afterEach, describe, expect, it, vi } from 'vitest'
import type { AuthSession } from './authSession.js'
import { mkdtemp, readFile, rm, stat, writeFile } from 'fs/promises'
import { tmpdir } from 'os'
const authDir = await mkdtemp(`${tmpdir()}/harness-auth-session-`)
process.env.HARNESS_AUTH_DIR = authDir
const {
ADOPTED_SIGN_IN,
AUTH_SESSION_FILE,
AuthSessionError,
AuthSessionManager,
clearAuthSession,
ensureSignInEpoch,
teamSignInEpoch,
hasAuthSession,
markSignedOut,
newSignInEpoch,
readAuthSession,
readSignedOut,
releaseHeldAuthLock,
updateAuthSession,
signInOf,
writeAuthSession,
} = await import('./authSession.js')
const baseSession = () => ({
version: 1 as const,
accessToken: 'old-access',
refreshToken: 'refresh-1',
expiresAt: Date.now() - 1,
autonomousEnv: 'prod' as const,
computerId: 'computer-1',
machineId: 'machine-1',
updatedAt: Date.now(),
})
afterEach(() => {
clearAuthSession()
vi.unstubAllGlobals()
})
afterAll(async () => {
delete process.env.HARNESS_AUTH_DIR
await rm(authDir, { recursive: true, force: true })
})
describe('sign-in epoch', () => {
it('rides along every rewrite of the session — a refresh and a new machine id', async () => {
const epoch = newSignInEpoch()
writeAuthSession({ ...baseSession(), signInEpoch: epoch, signInAcct: 'acct-1' })
vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response(JSON.stringify({
success: true, data: { token: 'refreshed-access', refreshToken: 'refreshed-refresh', expiresIn: 3600 },
}))))
const manager = new AuthSessionManager('https://api.example.test')
await manager.accessToken()
await manager.updateMachineId('machine-2', epoch)
expect(readAuthSession()).toMatchObject({ accessToken: 'refreshed-access', machineId: 'machine-2', signInEpoch: epoch, signInAcct: 'acct-1' })
expect(newSignInEpoch()).not.toBe(epoch)
})
describe('a machine id found under one sign-in', () => {
const manager = () => new AuthSessionManager('https://api.example.test')
it('is written into that sign-in, refreshed or not', async () => {
writeAuthSession({ ...baseSession(), signInEpoch: 'first@1' })
await manager().updateMachineId('machine-2', 'first@1')
expect(readAuthSession()).toMatchObject({ machineId: 'machine-2', signInEpoch: 'first@1' })
})
it('is dropped by a new sign-in', async () => {
writeAuthSession({ ...baseSession(), machineId: 'machine-new', signInEpoch: 'next@2' })
await manager().updateMachineId('machine-old', 'first@1')
expect(readAuthSession()).toMatchObject({ machineId: 'machine-new', signInEpoch: 'next@2' })
})
it('is dropped by a new sign-in when the lookup started with no epoch', async () => {
writeAuthSession({ ...baseSession(), machineId: 'machine-new', signInEpoch: 'next@2' })
await manager().updateMachineId('machine-old', undefined)
expect(readAuthSession()).toMatchObject({ machineId: 'machine-new' })
})
it('is dropped by a Team sign-in when the lookup started with no epoch, though its epoch reads as adopted', async () => {
writeAuthSession({ ...baseSession(), machineId: 'machine-new', signInEpoch: teamSignInEpoch() })
await manager().updateMachineId('machine-old', undefined)
expect(readAuthSession()).toMatchObject({ machineId: 'machine-new' })
expect(signInOf(readAuthSession()!.signInEpoch)?.adopted).toBe(true)
})
it('is kept when the session from before epochs was only given one meanwhile', async () => {
const { signInEpoch: _none, ...old } = { ...baseSession(), signInEpoch: undefined }
writeAuthSession(old)
await ensureSignInEpoch()
await manager().updateMachineId('machine-2', undefined)
expect(readAuthSession()).toMatchObject({ machineId: 'machine-2' })
})
})
it('gives a session from before epochs an adopted one, once, keeping its tokens', async () => {
writeAuthSession(baseSession())
const epoch = await ensureSignInEpoch()
expect(epoch?.startsWith(ADOPTED_SIGN_IN)).toBe(true)
expect(readAuthSession()).toMatchObject({ signInEpoch: epoch, refreshToken: 'refresh-1' })
expect(await ensureSignInEpoch()).toBe(epoch)
clearAuthSession()
expect(await ensureSignInEpoch()).toBeNull()
})
it('says when it was made, and whether it was adopted — as the device key log reads it', () => {
const epoch = newSignInEpoch(1_234)
expect(epoch).toMatch(/^[0-9a-f]{32}@1234$/)
expect(signInOf(epoch)).toEqual({ epoch, adopted: false, at: 1_234 })
expect(signInOf(`${ADOPTED_SIGN_IN}${epoch}`)).toEqual({ epoch: `${ADOPTED_SIGN_IN}${epoch}`, adopted: true, at: 1_234 })
// One from before the time was recorded.
expect(signInOf('0123456789abcdef0123456789abcdef')).toMatchObject({ adopted: false, at: null })
expect(signInOf(undefined)).toBeNull()
expect(signInOf('')).toBeNull()
})
it('says which account a sign-in by hand was made to, never for an adopted one', () => {
const epoch = newSignInEpoch(1_234)
expect(signInOf(epoch, 'acct-1')).toEqual({ epoch, adopted: false, at: 1_234, acct: 'acct-1' })
expect(signInOf(`${ADOPTED_SIGN_IN}${epoch}`, 'acct-1')).toEqual({ epoch: `${ADOPTED_SIGN_IN}${epoch}`, adopted: true, at: 1_234 })
expect(signInOf(epoch, '')).toEqual({ epoch, adopted: false, at: 1_234 })
})
})
it('reads a legacy session without interpreting optional metadata or rewriting the sign-in', async () => {
const saved = { ...baseSession(), memoryOwner: { profileId: 'legacy-preview', owner: 'fixture' },
futureMetadata: { value: 'preserved-on-disk' } }
await writeFile(AUTH_SESSION_FILE, JSON.stringify(saved), { mode: 0o600 })
const bytes = await readFile(AUTH_SESSION_FILE, 'utf8')
expect(readAuthSession()).toMatchObject({ accessToken: saved.accessToken, refreshToken: saved.refreshToken,
computerId: saved.computerId, machineId: saved.machineId })
expect(readAuthSession()).not.toHaveProperty('memoryOwner')
expect(await readFile(AUTH_SESSION_FILE, 'utf8')).toBe(bytes)
})
describe('AuthSessionManager', () => {
it('coalesces concurrent expired-token refreshes into one request and persists the rotated tokens', async () => {
writeAuthSession(baseSession())
const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(new Response(JSON.stringify({
success: true,
data: { token: 'new-access', refreshToken: 'refresh-2', expiresIn: 3600 },
})))
vi.stubGlobal('fetch', fetchMock)
const manager = new AuthSessionManager('https://api.example.test')
await expect(Promise.all([manager.accessToken(), manager.accessToken()])).resolves.toEqual(['new-access', 'new-access'])
expect(fetchMock).toHaveBeenCalledTimes(1)
expect(readAuthSession()).toMatchObject({ accessToken: 'new-access', refreshToken: 'refresh-2' })
await expect(readFile(AUTH_SESSION_FILE, 'utf8')).resolves.toContain('new-access')
})
it('refreshes as the client the session was issued to, and names none for a session that kept none', async () => {
const fetchMock = vi.fn<typeof fetch>().mockImplementation(async () => new Response(JSON.stringify({
success: true,
data: { token: 'new-access', expiresIn: 3600 },
})))
vi.stubGlobal('fetch', fetchMock)
const manager = new AuthSessionManager('https://api.example.test')
const sent = (call: number) => JSON.parse(String(fetchMock.mock.calls[call]![1]?.body)) as Record<string, unknown>
writeAuthSession({ ...baseSession(), clientId: 'harness-desktop' })
await manager.accessToken()
// An SSO sign-in's renewal also asks to become a Harness session (backend lib/ssoSession.ts).
const harnessSession = { kind: 'computer', label: expect.any(String) }
expect(sent(0)).toEqual({ refreshToken: 'refresh-1', autonomousEnv: 'prod', clientId: 'harness-desktop', harnessSession })
// The client outlives the refresh: the next one names it too.
expect(readAuthSession()).toMatchObject({ accessToken: 'new-access', clientId: 'harness-desktop' })
writeAuthSession(baseSession())
await manager.accessToken()
expect(sent(1)).toEqual({ refreshToken: 'refresh-1', autonomousEnv: 'prod', harnessSession })
})
it('reads back only a client that is ours', async () => {
await writeFile(AUTH_SESSION_FILE, JSON.stringify({ ...baseSession(), clientId: 'someone-else' }))
expect(readAuthSession()).not.toHaveProperty('clientId')
})
// A Harness Team sign-in (cli/src/team/) keeps its kind through every rewrite; any other kind reads as a computer's.
it('keeps a team sign-in\'s kind, and reads no other', async () => {
writeAuthSession({ ...baseSession(), kind: 'team' })
expect(readAuthSession()?.kind).toBe('team')
new AuthSessionManager('http://backend.invalid').updateMachineId('machine-2', undefined)
expect(readAuthSession()).toMatchObject({ kind: 'team', machineId: 'machine-2' })
await writeFile(AUTH_SESSION_FILE, JSON.stringify({ ...baseSession(), kind: 'admin' }))
expect(readAuthSession()).not.toHaveProperty('kind')
})
// `process.exit` skips `finally`: a daemon that exited mid-refresh left the lock for the next
// `harness auth status` to wait out (30s), which is how long the desktop app waits for it.
it('drops the refresh lock when the process exits while holding it, and only then', async () => {
const lock = `${authDir}/session.lock`
writeAuthSession(baseSession())
let answer!: (response: Response) => void
vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockReturnValue(new Promise<Response>((resolve) => { answer = resolve })))
const refreshing = new AuthSessionManager('https://api.example.test').accessToken()
await vi.waitFor(() => stat(lock))
releaseHeldAuthLock() // what the `exit` handler runs
await expect(stat(lock)).rejects.toThrow()
answer(new Response(JSON.stringify({ success: true, data: { token: 'new-access', expiresIn: 3600 } })))
await expect(refreshing).resolves.toBe('new-access')
// Another process's lock is not ours to remove.
await writeFile(lock, '')
releaseHeldAuthLock()
await expect(stat(lock)).resolves.toBeTruthy()
await rm(lock, { force: true })
})
it('uses the newer persisted access token rather than refreshing a stale 401 again', async () => {
writeAuthSession({ ...baseSession(), accessToken: 'already-refreshed', expiresAt: Date.now() + 3_600_000 })
const fetchMock = vi.fn<typeof fetch>()
vi.stubGlobal('fetch', fetchMock)
const manager = new AuthSessionManager('https://api.example.test')
await expect(manager.accessToken({ force: true, failedToken: 'old-access' })).resolves.toBe('already-refreshed')
expect(fetchMock).not.toHaveBeenCalled()
})
it('names `harness login` when the refresh service answers 503, because that is what a dead token looks like here', async () => {
// Measured 2026-09-06 against the live backend: an unusable refresh token comes back as
// `503 {"error":{"code":"AUTH_SERVICE_UNAVAILABLE"}}`, NOT 401 and not REFRESH_TOKEN_INVALID.
// So this answer is indistinguishable from a real outage, and the message has to carry both
// readings — saying only the upstream's "Authentication service unavailable" sends somebody
// with a dead sign-in away to wait for a service that is fine.
writeAuthSession(baseSession())
// A fresh Response per call: a body can only be read once, so one shared Response would make
// every call after the first see an empty body and prove nothing about the message.
vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockImplementation(async () => new Response(JSON.stringify({
success: false,
error: { code: 'AUTH_SERVICE_UNAVAILABLE', message: 'Authentication service unavailable' },
}), { status: 503 })))
const manager = new AuthSessionManager('https://api.example.test')
const err = await manager.accessToken().catch((e: unknown) => e) as InstanceType<typeof AuthSessionError>
expect(err).toMatchObject({ name: AuthSessionError.name, code: 'UNAVAILABLE' })
expect(err.message).toMatch(/harness login/) // the way out, which the upstream never names
expect(err.message).toMatch(/Authentication service unavailable/) // the upstream's own words, kept
})
it('a renewal answered "sign in again" says so and keeps the session, unmarked', async () => {
writeAuthSession({ ...baseSession(), accessToken: 'hna_old', refreshToken: 'hnr_1' })
vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response(JSON.stringify({
success: false, error: { code: 'SIGN_IN_AGAIN', message: 'Sign in again: not confirmed for 7 days' },
}), { status: 403 })))
const manager = new AuthSessionManager('https://api.example.test')
await expect(manager.accessToken()).rejects.toMatchObject({ code: 'SIGN_IN_AGAIN', message: expect.stringMatching(/harness login/) })
expect(readAuthSession()).toMatchObject({ refreshToken: 'hnr_1' })
expect(readSignedOut()).toBeNull()
})
it('keeps the session when the refresh service is merely unavailable', async () => {
// The other half of the same ambiguity, and the reason this must NOT be reclassified as
// INVALID_REFRESH: that branch deletes the session, and deleting it on a transient blip
// destroys a refresh token nothing can bring back. Ambiguous means keep, and say so.
writeAuthSession(baseSession())
vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response(JSON.stringify({
success: false,
error: { code: 'AUTH_SERVICE_UNAVAILABLE', message: 'Authentication service unavailable' },
}), { status: 503 })))
const manager = new AuthSessionManager('https://api.example.test')
await expect(manager.accessToken()).rejects.toMatchObject({ code: 'UNAVAILABLE' })
expect(readAuthSession()).toMatchObject({ refreshToken: 'refresh-1' })
})
it('gives up on a refresh that never answers, keeping the session', async () => {
// The daemon's reconnect waits on this call, and the desktop never restarts a daemon that is
// alive — an unbounded fetch here was a machine "connected" in status and disconnected in fact.
writeAuthSession(baseSession())
vi.stubGlobal('fetch', vi.fn((_url: string, init?: RequestInit) => new Promise<Response>((_resolve, reject) => {
init?.signal?.addEventListener('abort', () => reject(new Error('aborted')))
})))
const manager = new AuthSessionManager('https://api.example.test', { refreshTimeoutMs: 50 })
await expect(manager.accessToken()).rejects.toMatchObject({ code: 'UNAVAILABLE' })
expect(readAuthSession()).toMatchObject({ refreshToken: 'refresh-1' })
})
it('still says `harness login` when the service gives no message of its own', async () => {
writeAuthSession(baseSession())
vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new Error('socket hang up')))
const manager = new AuthSessionManager('https://api.example.test')
await expect(manager.accessToken()).rejects.toThrow(/harness login/)
expect(readAuthSession()).toMatchObject({ refreshToken: 'refresh-1' })
})
// 10-27: a sign-out nobody asked for stalled a whole Mac. Nothing automatic deletes the sign-in: it is kept,
// marked signed out, and nothing reads it as signed in again until a new sign-in replaces it.
const refusal = (): Response => new Response(JSON.stringify({
success: false,
error: { code: 'REFRESH_TOKEN_INVALID', message: 'expired' },
}), { status: 401 })
const renewal = (): Response => new Response(JSON.stringify({
success: true,
data: { token: 'renewed-access', refreshToken: 'refresh-2', expiresIn: 3600 },
}), { status: 200 })
it('a refused refresh keeps the sign-in, marked signed out: nothing uses it, nor refreshes it again', async () => {
writeAuthSession(baseSession())
const refused = vi.fn<typeof fetch>().mockImplementation(async () => refusal())
vi.stubGlobal('fetch', refused)
const manager = new AuthSessionManager('https://api.example.test')
await expect(manager.accessToken()).rejects.toMatchObject({ name: AuthSessionError.name, code: 'INVALID_REFRESH' })
expect(readAuthSession()).toBeNull()
expect(readSignedOut()).toMatchObject({ reason: 'refresh-refused' })
expect(JSON.parse(await readFile(AUTH_SESSION_FILE, 'utf8'))).toMatchObject({ refreshToken: 'refresh-1' })
await expect(manager.accessToken()).rejects.toMatchObject({ code: 'MISSING' })
expect(refused).toHaveBeenCalledTimes(1)
})
// The app asks `auth status` often; each ask must not be a refresh request (review of #1866).
it('a refused refresh is tried again a minute on, then twice as long each time, and a refresh that now works '
+ 'signs the computer back in', async () => {
const at = 1_000_000
writeAuthSession(baseSession())
await markSignedOut('refresh-refused', at)
const refused = vi.fn<typeof fetch>().mockImplementation(async () => refusal())
vi.stubGlobal('fetch', refused)
const manager = new AuthSessionManager('https://api.example.test')
expect(await manager.retrySignedOut(at + 30_000)).toBe(false)
expect(refused).not.toHaveBeenCalled()
expect(await manager.retrySignedOut(at + 60_000)).toBe(false)
expect(refused).toHaveBeenCalledTimes(1)
expect(await manager.retrySignedOut(at + 60_000 + 119_000)).toBe(false)
expect(refused).toHaveBeenCalledTimes(1)
expect(readSignedOut()).toMatchObject({ reason: 'refresh-refused' })
vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockImplementation(async () => renewal()))
expect(await manager.retrySignedOut(at + 60_000 + 120_000)).toBe(true)
expect(readSignedOut()).toBeNull()
expect(readAuthSession()).toMatchObject({ accessToken: 'renewed-access', refreshToken: 'refresh-2', machineId: 'machine-1' })
})
// Review of #1866: a revoke marked while another process refreshed was written over by that refresh's
// save, and the revoked sign-in was used again.
it('a revoke that lands while a refresh runs holds: the refresh saves first, and the mark stays', async () => {
writeAuthSession(baseSession())
let answer!: (response: Response) => void
vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockImplementation(() => new Promise<Response>((resolve) => { answer = resolve })))
const refreshing = new AuthSessionManager('https://api.example.test').accessToken()
await vi.waitFor(() => expect(answer).toBeTypeOf('function'))
const marked = markSignedOut('revoked')
answer(renewal())
await refreshing
await marked
expect(readSignedOut()).toMatchObject({ reason: 'revoked' })
expect(readAuthSession()).toBeNull()
})
// The daemon stops on a revoke and comes back signed out (core/main.ts `onRevoked`): it boots signed in
// only on a sign-in it can read, and every request takes its token from here.
it('a revoked sign-in is never acted on again: no token, no refresh, until a new sign-in', async () => {
writeAuthSession({ ...baseSession(), expiresAt: Date.now() + 3_600_000 })
await markSignedOut('revoked')
const fetched = vi.fn<typeof fetch>()
vi.stubGlobal('fetch', fetched)
const manager = new AuthSessionManager('https://api.example.test')
expect(hasAuthSession()).toBe(false)
await expect(manager.accessToken()).rejects.toMatchObject({ code: 'MISSING' })
await expect(manager.accessToken({ force: true })).rejects.toMatchObject({ code: 'MISSING' })
expect(await manager.retrySignedOut()).toBe(false)
expect(fetched).not.toHaveBeenCalled()
expect(readSignedOut()).toMatchObject({ reason: 'revoked' })
})
// Follow-up to the review of #1866: a rewrite that read the session before another process marked it
// wrote it back without the mark.
it('a rewrite never writes over a mark that landed after it read the session', async () => {
writeAuthSession(baseSession())
const written = await updateAuthSession((latest) => {
// Another process marks it while this one works out its change.
writeAuthSession({ ...latest, signedOut: { at: 1, reason: 'revoked' } } as typeof latest)
return { ...latest, machineId: 'machine-2' }
})
expect(written).toBeNull()
expect(readSignedOut()).toMatchObject({ reason: 'revoked' })
})
it('a rewrite of a marked sign-in writes nothing', async () => {
writeAuthSession(baseSession())
await markSignedOut('revoked')
const change = vi.fn((latest: AuthSession): AuthSession => ({ ...latest, machineId: 'machine-2' }))
expect(await updateAuthSession(change)).toBeNull()
expect(change).not.toHaveBeenCalled()
expect(readSignedOut()).toMatchObject({ reason: 'revoked' })
})
// Follow-up to the review of #1866: a revoke whose lock stayed busy stopped the daemon unmarked, and the
// core that came back used the revoked sign-in until it was refused again.
it('a revoke marks even when the lock cannot be had', async () => {
writeAuthSession(baseSession())
const busy = async (): Promise<never> => {
throw new AuthSessionError('Another Harness process is refreshing SSO credentials. Please retry.', 'UNAVAILABLE')
}
await markSignedOut('revoked', Date.now(), busy)
expect(readSignedOut()).toMatchObject({ reason: 'revoked' })
expect(readAuthSession()).toBeNull()
})
it('a new sign-in replaces one marked signed out', async () => {
writeAuthSession(baseSession())
await markSignedOut('revoked')
writeAuthSession({ ...baseSession(), accessToken: 'new-sign-in' })
expect(readSignedOut()).toBeNull()
expect(readAuthSession()).toMatchObject({ accessToken: 'new-sign-in' })
})
})