Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(watch-link): the API client for create, host tokens, status and revoke
review5c93f5c33ff2
diff --git a/src/core/watch-link/api.test.ts b/src/core/watch-link/api.test.tsnew file mode 100644index 000000000..cbdf84189--- /dev/null+++ b/src/core/watch-link/api.test.ts@@ -0,0 +1,180 @@+import { describe, it, expect } from 'vitest'+import { createWatchLinkApi } from './api'++const res = (status: number, body: unknown, headers: Record<string, string> = {}) =>+ new Response(body === null ? null : JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...headers } })+function api(reply: (url: string, init: RequestInit) => Response | Promise<Response>, now = 1_000_000) {+ const calls: { url: string; body: unknown }[] = []+ const a = createWatchLinkApi({+ apiBase: 'https://api.test/',+ now: () => now,+ fetch: (async (url: string, init: RequestInit) => { calls.push({ url, body: JSON.parse(String(init.body)) }); return reply(url, init) }) as typeof fetch+ })+ return { a, calls }+}++/** A fetch that never answers on its own: it settles only when the caller's AbortSignal fires. */+function hungFetch() {+ const signals: AbortSignal[] = []+ const f = ((_url: string, init: RequestInit) =>+ new Promise<Response>((_resolve, reject) => {+ const signal = init.signal as AbortSignal+ signals.push(signal)+ signal.addEventListener('abort', () => reject(new DOMException('aborted', 'AbortError')))+ })) as unknown as typeof fetch+ return { f, signals }+}++describe('createWatchLinkApi', () => {+ it('create posts the hash and corrects expiry to the local clock', async () => {+ const serverNow = Date.parse('Tue, 29 Sep 2026 10:00:00 GMT')+ const { a, calls } = api(() => res(200, { linkId: 'L', expiresAt: serverNow / 1000 + 3600 }, { date: new Date(serverNow).toUTCString() }), 5_000)+ const r = await a.create('ent', 'ab'.repeat(32), 3600)+ expect(calls[0]).toEqual({ url: 'https://api.test/v1/watch-links', body: { entitlement: 'ent', joinKeyHash: 'ab'.repeat(32), ttlSeconds: 3600 } })+ expect(r).toEqual({ ok: true, linkId: 'L', expiresAt: 5_000 + 3_600_000 })+ })++ it('maps create errors', async () => {+ const cases: [Response, string][] = [+ [res(402, { error: 'not_entitled' }), 'not-entitled'],+ [res(403, { error: 'companion_device' }), 'not-entitled'],+ [res(429, { error: 'rate_limited', scope: 'active_links' }), 'limit-active'],+ [res(429, { error: 'rate_limited', scope: 'license' }), 'limit-daily'],+ [res(429, { error: 'rate_limited', scope: 'ip' }), 'rate-limited'],+ [res(503, { error: 'license_check_unavailable' }), 'license-check'],+ [res(400, { error: 'bad_ttl' }), 'bad-request'],+ [res(500, null), 'network']+ ]+ for (const [r, want] of cases) expect(await api(() => r.clone()).a.create('e', 'h', 3600)).toEqual({ ok: false, error: want })+ expect(await api(() => { throw new Error('offline') }).a.create('e', 'h', 3600)).toEqual({ ok: false, error: 'network' })+ })++ it('hostToken maps 410 to gone and other refusals to the scheduler kinds', async () => {+ expect(await api(() => res(410, { error: 'gone', reason: 'revoked' })).a.hostToken('L', 'e')).toEqual({ ok: false, kind: 'gone', reason: 'revoked' })+ expect(await api(() => res(404, { error: 'not_found' })).a.hostToken('L', 'e')).toMatchObject({ ok: false, kind: 'refused' })+ expect(await api(() => res(429, {}, { 'retry-after': '60' })).a.hostToken('L', 'e')).toEqual({ ok: false, kind: 'rate-limited', status: 429, retryAfterMs: 60_000 })+ const ok = await api(() => res(200, { pairingToken: 'P', exp: 1_000 + 120 }, { date: new Date(1_000_000).toUTCString() })).a.hostToken('L', 'e')+ expect(ok).toMatchObject({ ok: true, pairingToken: 'P' })+ })++ it('hostToken maps a 410 expired, and the owner-check refusals 402/403', async () => {+ expect(await api(() => res(410, { error: 'gone', reason: 'expired' })).a.hostToken('L', 'e')).toEqual({ ok: false, kind: 'gone', reason: 'expired' })+ expect(await api(() => res(402, { error: 'not_entitled' })).a.hostToken('L', 'e')).toEqual({ ok: false, kind: 'refused', status: 402 })+ expect(await api(() => res(403, { error: 'companion_device' })).a.hostToken('L', 'e')).toEqual({ ok: false, kind: 'refused', status: 403 })+ })++ it('hostToken takes the token lifetime from the Date header, not the local clock', async () => {+ // The server says it is 10:00:00 and the token ends at 10:02:00. This machine's clock reads+ // something else entirely; the lifetime must still be two minutes.+ const serverNow = Date.parse('Tue, 29 Sep 2026 10:00:00 GMT')+ const reply = () => res(200, { pairingToken: 'P', exp: serverNow / 1000 + 120 }, { date: new Date(serverNow).toUTCString() })+ expect(await api(reply, 5_000).a.hostToken('L', 'e')).toEqual({ ok: true, pairingToken: 'P', hostId: '', ttlMs: 120_000 })+ })++ it('hostToken: a 200 without a usable pairingToken is a bad response, not a network failure', async () => {+ for (const body of [{ exp: 1_120 }, { pairingToken: 42, exp: 1_120 }, { pairingToken: '', exp: 1_120 }, null]) {+ expect(await api(() => res(200, body)).a.hostToken('L', 'e')).toEqual({ ok: false, kind: 'bad-response', status: 200 })+ }+ // A body that is not JSON at all is the server's fault too.+ expect(await api(() => new Response('<html>', { status: 200 })).a.hostToken('L', 'e')).toEqual({ ok: false, kind: 'bad-response', status: 200 })+ })++ it('hostToken: a body that stalls until the timeout is a network failure, not a bad response', async () => {+ const a = createWatchLinkApi({+ apiBase: 'https://api.test',+ timeoutMs: 20,+ fetch: (async (_url: string, init: RequestInit) => {+ const signal = init.signal as AbortSignal+ const body = new ReadableStream<Uint8Array>({+ start(c) {+ signal.addEventListener('abort', () => c.error(new DOMException('aborted', 'AbortError')))+ }+ })+ return new Response(body, { status: 200, headers: { 'content-type': 'application/json' } })+ }) as typeof fetch+ })+ expect(await a.hostToken('L', 'e')).toEqual({ ok: false, kind: 'network' })+ })++ it('status, revoke and revokeAll', async () => {+ expect(await api(() => res(200, { state: 'revoked' })).a.status('L', 'e')).toBe('revoked')+ expect(await api(() => res(500, null)).a.status('L', 'e')).toBe('unknown')+ const r = api(() => res(204, null))+ expect(await r.a.revoke('L', 'e')).toBe(true)+ expect(r.calls[0].url).toBe('https://api.test/v1/watch-links/L/revoke')+ expect(await api(() => res(204, null)).a.revokeAll('e')).toBe(true)+ })++ it('status reads only the three known states; revoke answers false on anything but 204', async () => {+ expect(await api(() => res(200, { state: 'live' })).a.status('L', 'e')).toBe('live')+ expect(await api(() => res(200, { state: 'expired' })).a.status('L', 'e')).toBe('expired')+ expect(await api(() => res(200, { state: 'paused' })).a.status('L', 'e')).toBe('unknown')+ expect(await api(() => res(404, { error: 'not_found' })).a.status('L', 'e')).toBe('unknown')+ expect(await api(() => res(404, { error: 'not_found' })).a.revoke('L', 'e')).toBe(false)+ expect(await api(() => res(200, {})).a.revokeAll('e')).toBe(false)+ const all = api(() => res(204, null))+ await all.a.revokeAll('e')+ expect(all.calls[0]).toEqual({ url: 'https://api.test/v1/watch-links/revoke-all', body: { entitlement: 'e' } })+ })++ it('the timeout ends a fetch that never answers', async () => {+ const timeoutMs = 20+ const { f, signals } = hungFetch()+ const a = createWatchLinkApi({ apiBase: 'https://api.test', fetch: f, timeoutMs })+ const started = Date.now()+ const [created, token, state, revoked, revokedAll] = await Promise.all([+ a.create('e', 'h', 3600),+ a.hostToken('L', 'e'),+ a.status('L', 'e'),+ a.revoke('L', 'e'),+ a.revokeAll('e')+ ])+ expect(created).toEqual({ ok: false, error: 'network' })+ expect(token).toEqual({ ok: false, kind: 'network' })+ expect(state).toBe('unknown')+ expect(revoked).toBe(false)+ expect(revokedAll).toBe(false)+ expect(signals).toHaveLength(5)+ expect(signals.every((s) => s.aborted)).toBe(true)+ // Generous bound: the point is that it ended on the timeout, not on vitest's own 5 s limit.+ expect(Date.now() - started).toBeLessThan(2_000)+ })++ it('the entitlement rides only the JSON body, never the URL or a header', async () => {+ const ENT = 'ENT-SECRET-7f3a'+ const seen: { url: string; init: RequestInit }[] = []+ const a = createWatchLinkApi({+ apiBase: 'https://api.test',+ fetch: (async (url: string, init: RequestInit) => {+ seen.push({ url, init })+ return res(204, null)+ }) as typeof fetch+ })+ await a.create(ENT, 'h', 3600)+ await a.hostToken('L', ENT)+ await a.status('L', ENT)+ await a.revoke('L', ENT)+ await a.revokeAll(ENT)+ expect(seen).toHaveLength(5)+ for (const { url, init } of seen) {+ expect(url).not.toContain(ENT)+ expect(JSON.stringify(Object.entries(new Headers(init.headers)))).not.toContain(ENT)+ expect(init.method).toBe('POST')+ expect(JSON.parse(String(init.body)).entitlement).toBe(ENT)+ }+ })++ it('url-encodes the link id in the path', async () => {+ const id = 'a/b?c#d %'+ const enc = 'a%2Fb%3Fc%23d%20%25'+ const r = api(() => res(204, null))+ await r.a.hostToken(id, 'e')+ await r.a.status(id, 'e')+ await r.a.revoke(id, 'e')+ expect(r.calls.map((c) => c.url)).toEqual([+ `https://api.test/v1/watch-links/${enc}/host-token`,+ `https://api.test/v1/watch-links/${enc}/status`,+ `https://api.test/v1/watch-links/${enc}/revoke`+ ])+ })+})diff --git a/src/core/watch-link/api.ts b/src/core/watch-link/api.tsnew file mode 100644index 000000000..861de2e58--- /dev/null+++ b/src/core/watch-link/api.ts@@ -0,0 +1,103 @@+// HTTP client for the live-link routes (nodeterm-server, Plan 1). Credentials ride the JSON body+// over TLS, never argv. Every call is bounded by a timeout that also covers the body read.+import { tokenTtlMs, type MintResult } from '../relay/host-token'++export type CreateError = 'not-entitled' | 'limit-active' | 'limit-daily' | 'rate-limited' | 'license-check' | 'bad-request' | 'network'+export type HostTokenResult = MintResult | { ok: false; kind: 'gone'; reason: 'revoked' | 'expired' }+export interface WatchLinkApi {+ create(entitlement: string, joinKeyHash: string, ttlSeconds: number): Promise<{ ok: true; linkId: string; expiresAt: number } | { ok: false; error: CreateError }>+ hostToken(linkId: string, entitlement: string): Promise<HostTokenResult>+ status(linkId: string, entitlement: string): Promise<'live' | 'revoked' | 'expired' | 'unknown'>+ revoke(linkId: string, entitlement: string): Promise<boolean>+ revokeAll(entitlement: string): Promise<boolean>+}++interface Reply {+ status: number+ /** The parsed body when it is a JSON object; null for 204, an empty or non-JSON body, or any other JSON value. */+ json: Record<string, unknown> | null+ date: string | null+ retryAfter: string | null+}++export function createWatchLinkApi(o: { apiBase: string; fetch?: typeof fetch; now?: () => number; timeoutMs?: number }): WatchLinkApi {+ const base = o.apiBase.replace(/\/+$/, '')+ const now = o.now ?? Date.now+ const f = o.fetch ?? fetch++ /** One POST. null = no answer (the request failed, or the timeout fired before the whole body arrived). */+ async function post(path: string, body: unknown): Promise<Reply | null> {+ const ctrl = new AbortController()+ const timer = setTimeout(() => ctrl.abort(), o.timeoutMs ?? 8000)+ try {+ const r = await f(`${base}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: ctrl.signal })+ let json: Record<string, unknown> | null = null+ if (r.status !== 204) {+ try {+ const v: unknown = await r.json()+ json = v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null+ } catch {+ // Aborted mid-body is the timeout (no answer); a body that is not JSON is the server's.+ if (ctrl.signal.aborted) return null+ json = null+ }+ }+ return { status: r.status, json, date: r.headers.get('date'), retryAfter: r.headers.get('retry-after') }+ } catch {+ return null+ } finally {+ clearTimeout(timer)+ }+ }+ const path = (id: string, verb: string) => `/v1/watch-links/${encodeURIComponent(id)}/${verb}`++ return {+ async create(entitlement, joinKeyHash, ttlSeconds) {+ const r = await post('/v1/watch-links', { entitlement, joinKeyHash, ttlSeconds })+ if (!r) return { ok: false, error: 'network' }+ if (r.status === 200 && typeof r.json?.linkId === 'string' && typeof r.json.expiresAt === 'number') {+ // `expiresAt` is an instant on the SERVER's clock; the Date header turns it into time left,+ // which is then anchored on this machine's clock (see tokenTtlMs).+ const t = now()+ return { ok: true, linkId: r.json.linkId, expiresAt: t + tokenTtlMs(r.json.expiresAt, r.date, t) }+ }+ if (r.status === 402 || r.status === 403) return { ok: false, error: 'not-entitled' }+ if (r.status === 429) {+ const scope = r.json?.scope+ return { ok: false, error: scope === 'active_links' ? 'limit-active' : scope === 'license' ? 'limit-daily' : 'rate-limited' }+ }+ if (r.status === 503) return { ok: false, error: 'license-check' }+ if (r.status === 400) return { ok: false, error: 'bad-request' }+ return { ok: false, error: 'network' }+ },+ async hostToken(linkId, entitlement) {+ const r = await post(path(linkId, 'host-token'), { entitlement })+ if (!r) return { ok: false, kind: 'network' }+ if (r.status === 200) {+ // A 200 without a token is the server's fault, not the network's (same rule as mintHostToken).+ if (typeof r.json?.pairingToken !== 'string' || !r.json.pairingToken) return { ok: false, kind: 'bad-response', status: 200 }+ const exp = typeof r.json.exp === 'number' ? r.json.exp : 0+ return { ok: true, pairingToken: r.json.pairingToken, hostId: '', ttlMs: tokenTtlMs(exp, r.date, now()) }+ }+ if (r.status === 410) return { ok: false, kind: 'gone', reason: r.json?.reason === 'expired' ? 'expired' : 'revoked' }+ if (r.status === 429) {+ // Seconds only. An HTTP-date Retry-After (or none) falls to the scheduler's own floor.+ const ra = Number(r.retryAfter)+ return { ok: false, kind: 'rate-limited', status: 429, ...(ra > 0 ? { retryAfterMs: ra * 1000 } : {}) }+ }+ if (r.status === 402 || r.status === 403 || r.status === 404) return { ok: false, kind: 'refused', status: r.status }+ return { ok: false, kind: 'network', status: r.status }+ },+ async status(linkId, entitlement) {+ const r = await post(path(linkId, 'status'), { entitlement })+ const s = r?.status === 200 ? r.json?.state : null+ return s === 'live' || s === 'revoked' || s === 'expired' ? s : 'unknown'+ },+ async revoke(linkId, entitlement) {+ return (await post(path(linkId, 'revoke'), { entitlement }))?.status === 204+ },+ async revokeAll(entitlement) {+ return (await post('/v1/watch-links/revoke-all', { entitlement }))?.status === 204+ }+ }+}