@kortix/agent-tunnel 0.12.7 → 0.13.0

package/src/agent/config.ts

@@ -194,6 +194,25 @@ export function absoluteWsPath(value: string): string {
   return value;
 }
 
+/**
+ * Builds the relay WebSocket URL. The token is never placed in the URL — the
+ * agent sends it in the first `auth` message instead.
+ */
+export function buildTunnelWsUrl(
+  config: Pick<TunnelConfig, 'apiUrl' | 'tunnelId'> & { wsPath?: string },
+): string {
+  const base = trustedHttpUrl(config.apiUrl)
+    .replace(/^http:/, 'ws:')
+    .replace(/^https:/, 'wss:');
+
+  const wsPath = absoluteWsPath(config.wsPath || '/ws');
+  const params = new URLSearchParams({
+    tunnelId: trustedCredential(config.tunnelId, 'tunnelId'),
+  });
+
+  return `${base}${wsPath}?${params.toString()}`;
+}
+
 export function loadConfig(overrides: Partial<TunnelConfig> = {}): TunnelConfig {
   let fileConfig: Partial<TunnelConfig> = {};
   if (existsSync(CONFIG_FILE)) {

package/src/agent/credential-probe.ts

@@ -0,0 +1,95 @@
+import '../node-ws-polyfill';
+import { AGENT_REPLACED_CLOSE_CODE, AGENT_VERSION, AUTH_REJECTED_CLOSE_CODES } from './agent';
+import { buildTunnelWsUrl, trustedCredential, type TunnelConfig } from './config';
+
+/**
+ * - `valid`       the relay accepted the credential.
+ * - `rejected`    the relay refused it. Re-pairing is the only fix.
+ * - `unreachable` no verdict was reached. The credential is NOT proven bad, so
+ *                 callers must keep it.
+ */
+export type CredentialProbeResult = 'valid' | 'rejected' | 'unreachable';
+
+export interface ProbeCredentialsOptions {
+  /** Capabilities advertised in the handshake. Must match what the agent sends. */
+  capabilities?: string[];
+  timeoutMs?: number;
+}
+
+const DEFAULT_PROBE_TIMEOUT_MS = 10_000;
+
+/**
+ * Runs one relay handshake and reports whether the credential still works.
+ *
+ * `connect` calls this before reusing a saved credential. Without it, a revoked
+ * token is only discovered after the background service is installed, which
+ * produces a silent restart loop instead of a re-pair prompt.
+ *
+ * Callers must already hold the tunnel lease — see acquireTunnelLease(). The
+ * relay allows a single agent per tunnel, so probing while the service is live
+ * would evict it.
+ */
+export function probeCredentials(
+  config: TunnelConfig,
+  options: ProbeCredentialsOptions = {},
+): Promise<CredentialProbeResult> {
+  return new Promise<CredentialProbeResult>((resolve) => {
+    let socket: WebSocket;
+    try {
+      socket = new WebSocket(new URL(buildTunnelWsUrl(config)));
+    } catch {
+      resolve('unreachable');
+      return;
+    }
+
+    // resolve() is idempotent, so the first verdict wins and later events are
+    // harmless no-ops. That removes any need to track settled state by hand.
+    const settle = (result: CredentialProbeResult): void => {
+      clearTimeout(timer);
+      try { socket.close(1000, 'probe complete'); } catch {}
+      resolve(result);
+    };
+
+    const timer = setTimeout(() => settle('unreachable'), options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);
+
+    socket.addEventListener('open', () => {
+      try {
+        // Handing the saved credential to the relay is the whole point of the
+        // handshake. loadConfig() has already validated that the file is
+        // private and user-owned; trustedCredential() rejects control characters.
+        socket.send(JSON.stringify({
+          type: 'auth',
+          token: trustedCredential(config.token, 'token'),
+          capabilities: options.capabilities ?? [],
+          agentVersion: AGENT_VERSION,
+        }));
+      } catch {
+        settle('unreachable');
+      }
+    });
+
+    socket.addEventListener('message', (event) => {
+      try {
+        const message: unknown = JSON.parse(String((event as MessageEvent).data));
+        if (isJsonRecord(message) && message.type === 'auth_ok') settle('valid');
+      } catch {
+        // Not the message we are waiting for.
+      }
+    });
+
+    socket.addEventListener('close', (event) => {
+      const { code } = event as CloseEvent;
+      if (AUTH_REJECTED_CLOSE_CODES.includes(code)) return settle('rejected');
+      // The relay only replaces a socket it registered, and it only registers
+      // one that authenticated. Being replaced proves the credential is good.
+      if (code === AGENT_REPLACED_CLOSE_CODE) return settle('valid');
+      settle('unreachable');
+    });
+
+    socket.addEventListener('error', () => settle('unreachable'));
+  });
+}
+
+function isJsonRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/agent/credential-store.ts

@@ -0,0 +1,74 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const CONFIG_DIR = join(homedir(), '.agent-tunnel');
+export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+/** Fields that identify a pairing. Everything else in the file is user settings. */
+const PAIRING_FIELDS = ['token', 'tunnelId', 'enabledCapabilities'] as const;
+
+function readConfigFile(): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Replaces the config file atomically, private-by-default.
+ *
+ * Both writers need identical tmp-write/rename/chmod handling; duplicating it
+ * once already meant two places to get the permission bits right.
+ */
+function writeConfigFileAtomic(next: Record<string, unknown>): void {
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  try { chmodSync(CONFIG_DIR, 0o700); } catch {}
+
+  const tmpFile = join(CONFIG_DIR, `config.${process.pid}.${Date.now()}.tmp`);
+  writeFileSync(tmpFile, JSON.stringify(next, null, 2), { mode: 0o600, flag: 'wx' });
+  try { chmodSync(tmpFile, 0o600); } catch {}
+  renameSync(tmpFile, CONFIG_FILE);
+  try { chmodSync(CONFIG_FILE, 0o600); } catch {}
+}
+
+export function saveCredentials(
+  tunnelId: string,
+  token: string,
+  apiUrl: string,
+  enabledCapabilities?: string[],
+): void {
+  writeConfigFileAtomic({
+    ...readConfigFile(),
+    tunnelId,
+    token,
+    apiUrl,
+    ...(enabledCapabilities !== undefined ? { enabledCapabilities } : {}),
+  });
+}
+
+/**
+ * Drops only the pairing fields, so user-tuned settings such as `allowedPaths`
+ * survive a re-pair. Returns true when a credential was actually present.
+ */
+export function clearSavedCredentials(): boolean {
+  if (!existsSync(CONFIG_FILE)) return false;
+
+  let existing: Record<string, unknown>;
+  try {
+    existing = JSON.parse(readFileSync(CONFIG_FILE, 'utf-8')) as Record<string, unknown>;
+  } catch {
+    // Unparseable file: there is nothing worth preserving.
+    rmSync(CONFIG_FILE, { force: true });
+    return true;
+  }
+
+  const hadCredentials = PAIRING_FIELDS.some((key) => key in existing && existing[key] != null);
+  for (const key of PAIRING_FIELDS) delete existing[key];
+  writeConfigFileAtomic(existing);
+  return hadCredentials;
+}

package/src/agent/device-auth.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  InvalidDeviceAuthResponseError,
+  awaitDeviceAuthorization,
+  parseDeviceAuthChallenge,
+  parseDeviceAuthStatus,
+} from './device-auth';
+
+const VALID_TUNNEL_ID = '00000000-0000-4000-8000-000000000042';
+const VALID_TOKEN = `kortix_tnl_${'A'.repeat(36)}`;
+
+function challenge(overrides: Record<string, unknown> = {}) {
+  return {
+    deviceCode: 'ABCD-1234',
+    deviceSecret: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456',
+    verificationUrl: 'https://kortix.com/tunnel/authorize/ABCD-1234',
+    expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    pollIntervalMs: 2000,
+    ...overrides,
+  };
+}
+
+describe('device auth challenge validation', () => {
+  test('accepts a well-formed challenge', () => {
+    const parsed = parseDeviceAuthChallenge(challenge());
+    expect(parsed.deviceCode).toBe('ABCD-1234');
+    expect(parsed.verificationUrl).toStartWith('https://kortix.com/');
+  });
+
+  test('rejects a verification URL that is not https and not loopback', () => {
+    expect(() => parseDeviceAuthChallenge(challenge({ verificationUrl: 'http://evil.example/x' })))
+      .toThrow(InvalidDeviceAuthResponseError);
+  });
+
+  test('allows a loopback URL over http for local development', () => {
+    const parsed = parseDeviceAuthChallenge(
+      challenge({ verificationUrl: 'http://127.0.0.1:3000/tunnel/authorize/ABCD-1234' }),
+    );
+    expect(parsed.verificationUrl).toContain('127.0.0.1');
+  });
+
+  test('rejects a URL carrying credentials', () => {
+    expect(() => parseDeviceAuthChallenge(challenge({ verificationUrl: 'https://user:pw@kortix.com/x' })))
+      .toThrow(/unsafe verification URL/);
+  });
+
+  test('rejects a non-http scheme outright', () => {
+    expect(() => parseDeviceAuthChallenge(challenge({ verificationUrl: 'javascript:alert(1)' })))
+      .toThrow(InvalidDeviceAuthResponseError);
+  });
+
+  test.each([
+    ['device code', { deviceCode: 'nope' }],
+    ['device secret', { deviceSecret: 'short' }],
+    ['expiration in the past', { expiresAt: new Date(Date.now() - 1000).toISOString() }],
+    ['expiration too far out', { expiresAt: new Date(Date.now() + 60 * 60_000).toISOString() }],
+    ['poll interval too small', { pollIntervalMs: 10 }],
+    ['poll interval too large', { pollIntervalMs: 60_000 }],
+  ])('rejects a bad %s', (_label, overrides) => {
+    expect(() => parseDeviceAuthChallenge(challenge(overrides))).toThrow(InvalidDeviceAuthResponseError);
+  });
+});
+
+describe('device auth status validation', () => {
+  test('returns null while the request is still pending', () => {
+    expect(parseDeviceAuthStatus({ status: 'pending' })).toBeNull();
+  });
+
+  test('narrows an approval to supported capabilities and dedupes them', () => {
+    const outcome = parseDeviceAuthStatus({
+      status: 'approved',
+      tunnelId: VALID_TUNNEL_ID,
+      token: VALID_TOKEN,
+      capabilities: ['shell', 'shell', 'filesystem', 'root-access'],
+    });
+    expect(outcome).toEqual({
+      status: 'approved',
+      tunnelId: VALID_TUNNEL_ID,
+      token: VALID_TOKEN,
+      capabilities: ['shell', 'filesystem'],
+    });
+  });
+
+  test('reports an approval that carries no token separately', () => {
+    expect(parseDeviceAuthStatus({ status: 'approved' })).toEqual({ status: 'approved-without-token' });
+  });
+
+  test('rejects a malformed tunnel id', () => {
+    expect(() => parseDeviceAuthStatus({ status: 'approved', tunnelId: 'nope', token: VALID_TOKEN }))
+      .toThrow(/invalid tunnel ID/);
+  });
+
+  test('rejects a malformed setup token', () => {
+    expect(() => parseDeviceAuthStatus({ status: 'approved', tunnelId: VALID_TUNNEL_ID, token: 'bad' }))
+      .toThrow(/invalid setup token/);
+  });
+
+  test.each([['denied'], ['expired']])('passes %s through', (status) => {
+    expect(parseDeviceAuthStatus({ status })).toEqual({ status } as never);
+  });
+});
+
+describe('polling', () => {
+  test('retries transport failures and stops on a decision', async () => {
+    let calls = 0;
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+      calls++;
+      if (calls < 3) throw new Error('network down');
+      return new Response(JSON.stringify({ status: 'denied' }), { status: 200 });
+    }) as unknown as typeof fetch;
+
+    try {
+      const outcome = await awaitDeviceAuthorization('http://127.0.0.1:1/v1/tunnel', challenge(), {
+        sleep: async () => {},
+      });
+      expect(outcome).toEqual({ status: 'denied' });
+      expect(calls).toBe(3);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test('gives up once the challenge has expired', async () => {
+    const outcome = await awaitDeviceAuthorization(
+      'http://127.0.0.1:1/v1/tunnel',
+      { ...challenge(), expiresAt: new Date(Date.now() - 1).toISOString() },
+      { sleep: async () => {} },
+    );
+    expect(outcome).toEqual({ status: 'expired' });
+  });
+});

package/src/agent/device-auth.ts

@@ -0,0 +1,213 @@
+import { spawn } from 'child_process';
+import { hostname, platform } from 'os';
+import { isTunnelCapability } from '../shared/permissions';
+import type { TunnelCapability } from '../shared/types';
+
+/**
+ * The device authorization protocol, with no terminal output of its own.
+ *
+ * Keeping parsing and polling separate from presentation means the validation
+ * rules below can be read — and tested — without a CLI around them.
+ */
+
+const TUNNEL_ID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SETUP_TOKEN_PATTERN = /^kortix_tnl_[A-Za-z0-9_-]{32,64}$/;
+const DEVICE_CODE_PATTERN = /^[A-Z]{4}-[0-9]{4}$/;
+const DEVICE_SECRET_PATTERN = /^[A-Za-z0-9]{32}$/;
+const MAX_CHALLENGE_LIFETIME_MS = 10 * 60_000;
+
+export interface DeviceAuthChallenge {
+  deviceCode: string;
+  deviceSecret: string;
+  verificationUrl: string;
+  expiresAt: string;
+  pollIntervalMs: number;
+}
+
+export type DeviceAuthOutcome =
+  | { status: 'approved'; tunnelId: string; token: string; capabilities: TunnelCapability[] }
+  | { status: 'denied' }
+  | { status: 'expired' }
+  | { status: 'approved-without-token' };
+
+export class InvalidDeviceAuthResponseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidDeviceAuthResponseError';
+  }
+}
+
+function invalid(what: string): never {
+  throw new InvalidDeviceAuthResponseError(`Authorization server returned an invalid ${what}`);
+}
+
+function isJsonRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeBrowserUrl(value: string): string | null {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' || url.protocol === 'http:' ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+function isLoopback(url: URL): boolean {
+  return ['localhost', '127.0.0.1', '[::1]', '::1'].includes(url.hostname);
+}
+
+/** Only the approval URL is opened, and only after it passes this check. */
+function assertSafeVerificationUrl(value: string): string {
+  if (value.length > 2048) invalid('verification URL');
+  const browserUrl = normalizeBrowserUrl(value);
+  if (!browserUrl) invalid('verification URL');
+
+  const url = new URL(browserUrl);
+  if (url.username || url.password || (url.protocol !== 'https:' && !isLoopback(url))) {
+    throw new InvalidDeviceAuthResponseError(
+      'Authorization server returned an unsafe verification URL',
+    );
+  }
+  return browserUrl;
+}
+
+export function parseDeviceAuthChallenge(value: unknown): DeviceAuthChallenge {
+  if (!isJsonRecord(value)) invalid('challenge');
+  const { deviceCode, deviceSecret, verificationUrl, expiresAt, pollIntervalMs } = value;
+
+  if (typeof deviceCode !== 'string' || !DEVICE_CODE_PATTERN.test(deviceCode)) invalid('device code');
+  if (typeof deviceSecret !== 'string' || !DEVICE_SECRET_PATTERN.test(deviceSecret)) {
+    invalid('device secret');
+  }
+  if (typeof verificationUrl !== 'string') invalid('verification URL');
+  if (typeof expiresAt !== 'string') invalid('expiration');
+
+  const expiresAtMs = Date.parse(expiresAt);
+  const now = Date.now();
+  if (!Number.isFinite(expiresAtMs) || expiresAtMs <= now || expiresAtMs > now + MAX_CHALLENGE_LIFETIME_MS) {
+    invalid('expiration');
+  }
+  if (!Number.isSafeInteger(pollIntervalMs) || (pollIntervalMs as number) < 250 || (pollIntervalMs as number) > 10_000) {
+    invalid('poll interval');
+  }
+
+  return {
+    deviceCode,
+    deviceSecret,
+    verificationUrl: assertSafeVerificationUrl(verificationUrl),
+    expiresAt,
+    pollIntervalMs: pollIntervalMs as number,
+  };
+}
+
+function parseApprovedCredentials(value: Record<string, unknown>): { tunnelId: string; token: string } {
+  const { tunnelId, token } = value;
+  if (typeof tunnelId !== 'string' || !TUNNEL_ID_PATTERN.test(tunnelId)) invalid('tunnel ID');
+  if (typeof token !== 'string' || !SETUP_TOKEN_PATTERN.test(token)) invalid('setup token');
+  return { tunnelId, token };
+}
+
+/** The browser-approved set, deduplicated and narrowed to capabilities we support. */
+function parseApprovedCapabilities(value: unknown): TunnelCapability[] {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value)].filter((item): item is TunnelCapability => isTunnelCapability(item));
+}
+
+export function parseDeviceAuthStatus(value: unknown): DeviceAuthOutcome | null {
+  if (!isJsonRecord(value) || typeof value.status !== 'string') invalid('status response');
+
+  switch (value.status) {
+    case 'approved': {
+      if (!value.tunnelId || !value.token) return { status: 'approved-without-token' };
+      return {
+        status: 'approved',
+        ...parseApprovedCredentials(value),
+        capabilities: parseApprovedCapabilities(value.capabilities),
+      };
+    }
+    case 'denied':
+      return { status: 'denied' };
+    case 'expired':
+      return { status: 'expired' };
+    default:
+      // Still pending: the caller keeps polling.
+      return null;
+  }
+}
+
+export async function requestDeviceAuthorization(apiUrl: string): Promise<DeviceAuthChallenge> {
+  const response = await fetch(`${apiUrl}/device-auth`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ machineHostname: hostname() }),
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => '');
+    throw new InvalidDeviceAuthResponseError(
+      `Failed to create device auth request: ${response.status} ${body.slice(0, 200)}`,
+    );
+  }
+  return parseDeviceAuthChallenge(await response.json());
+}
+
+/**
+ * Polls until the request is decided or the challenge expires.
+ *
+ * `onWaiting` receives the seconds left so the caller owns every rendered byte.
+ * Transport errors are swallowed and retried; only a malformed response, which
+ * means the server is not speaking the protocol, aborts.
+ */
+export async function awaitDeviceAuthorization(
+  apiUrl: string,
+  challenge: DeviceAuthChallenge,
+  options: { onWaiting?: (secondsRemaining: number) => void; sleep?: (ms: number) => Promise<void> } = {},
+): Promise<DeviceAuthOutcome> {
+  const wait = options.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const expiresAtMs = Date.parse(challenge.expiresAt);
+
+  for (;;) {
+    const secondsRemaining = Math.max(0, Math.floor((expiresAtMs - Date.now()) / 1000));
+    if (secondsRemaining <= 0) return { status: 'expired' };
+    options.onWaiting?.(secondsRemaining);
+
+    let payload: unknown;
+    try {
+      const response = await fetch(`${apiUrl}/device-auth/${challenge.deviceCode}/status`, {
+        headers: { Authorization: `Bearer ${challenge.deviceSecret}` },
+      });
+      if (!response.ok) {
+        await wait(challenge.pollIntervalMs);
+        continue;
+      }
+      payload = await response.json();
+    } catch {
+      await wait(challenge.pollIntervalMs);
+      continue;
+    }
+
+    const outcome = parseDeviceAuthStatus(payload);
+    if (outcome) return outcome;
+    await wait(challenge.pollIntervalMs);
+  }
+}
+
+export function openBrowser(url: string): void {
+  if (process.env.KORTIX_AGENT_TUNNEL_NO_BROWSER === '1') return;
+  const safeUrl = normalizeBrowserUrl(url);
+  if (!safeUrl) return;
+
+  const opener: Record<string, [string, string[]]> = {
+    darwin: ['open', [safeUrl]],
+    win32: ['rundll32.exe', ['url.dll,FileProtocolHandler', safeUrl]],
+  };
+  const [command, args] = opener[platform()] ?? ['xdg-open', [safeUrl]];
+
+  try {
+    spawn(command, args, { detached: true, stdio: 'ignore' }).unref();
+  } catch {
+    // An unopenable browser is not fatal: the URL is printed too.
+  }
+}

package/src/agent/log-format.ts

@@ -0,0 +1,24 @@
+/**
+ * Collapses runs of identical lines.
+ *
+ * A restart loop writes the same lines thousands of times. Printing them
+ * verbatim buries the one detail that matters — how many times it happened.
+ */
+export function collapseRepeatedLines(lines: string[]): string[] {
+  const collapsed: string[] = [];
+  let index = 0;
+  while (index < lines.length) {
+    let repeats = 1;
+    while (index + repeats < lines.length && lines[index + repeats] === lines[index]) repeats++;
+    collapsed.push(repeats > 1 ? `${lines[index]}  (x${repeats})` : lines[index]);
+    index += repeats;
+  }
+  return collapsed;
+}
+
+/** Noise the supervisor's login shell writes before the agent ever starts. */
+export function isShellStartupNoise(line: string): boolean {
+  return /\/\.(profile|bash_profile|zprofile|zshrc|bashrc)\b.*:.*(No such file or directory|command not found)/.test(
+    line,
+  );
+}

package/src/agent/prompts.ts

@@ -0,0 +1,37 @@
+import { createInterface } from 'readline/promises';
+import { c } from './terminal';
+
+export function isInteractiveTerminal(): boolean {
+  return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+
+export function isTruthyFlag(value: string | undefined): boolean {
+  return value === 'true' || value === '1' || value === 'yes';
+}
+
+/** True when any of `names` is set to a truthy value. */
+export function anyFlag(flags: Record<string, string>, names: readonly string[]): boolean {
+  return names.some((name) => isTruthyFlag(flags[name]));
+}
+
+export async function promptYesNo(question: string, defaultValue: boolean): Promise<boolean> {
+  const suffix = defaultValue ? ' [Y/n] ' : ' [y/N] ';
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (;;) {
+      const answer = (await rl.question(`${question}${suffix}`)).trim().toLowerCase();
+      if (!answer) return defaultValue;
+      if (['y', 'yes'].includes(answer)) return true;
+      if (['n', 'no'].includes(answer)) return false;
+      console.log(`  ${c.yellow}!${c.reset} Please answer yes or no.`);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      process.stdout.write('\n');
+      process.exit(130);
+    }
+    throw error;
+  } finally {
+    rl.close();
+  }
+}

package/src/agent/service-control.ts

@@ -0,0 +1,69 @@
+import {
+  type ServiceStatus,
+  getServiceStatus,
+  installService,
+  restartService,
+  startService,
+  stopService,
+  uninstallService,
+} from './service';
+import { c, blankLine, field, glyph } from './terminal';
+
+/**
+ * Exactly one process may hold a tunnel: the relay closes the older socket with
+ * 4004 and the displaced agent stops for good. Anything in the foreground that
+ * needs the credential must therefore take it from the background service
+ * first, and hand it back if it did not end up using it.
+ */
+export interface TunnelLease {
+  /** True when this lease actually stopped a running service. */
+  readonly serviceWasActive: boolean;
+  /** Restarts the service if this lease stopped it. Safe to call more than once. */
+  resumeService(): void;
+}
+
+export function acquireTunnelLease(): TunnelLease {
+  const serviceWasActive = getServiceStatus().active === true;
+  if (serviceWasActive) stopService();
+
+  let resumed = false;
+  return {
+    serviceWasActive,
+    resumeService() {
+      if (!serviceWasActive || resumed) return;
+      resumed = true;
+      startService();
+    },
+  };
+}
+
+/** Service verbs that map one-to-one onto a supervisor operation. */
+export const SERVICE_ACTIONS = {
+  start: { run: startService, label: 'started' },
+  stop: { run: stopService, label: 'stopped' },
+  restart: { run: restartService, label: 'restarted' },
+  uninstall: { run: uninstallService, label: 'removed' },
+  install: { run: installService, label: 'installed' },
+} as const;
+
+export type ServiceAction = keyof typeof SERVICE_ACTIONS;
+
+export function describeService(status: ServiceStatus): string {
+  if (!status.installed) return `${glyph.off} not installed`;
+  if (status.active) return `${glyph.on} running ${c.dim}· starts at login${c.reset}`;
+  return `${c.yellow}○${c.reset} installed ${c.dim}· stopped${c.reset}`;
+}
+
+/**
+ * Renders the result of a service verb.
+ *
+ * These used to be five copy-pasted `console.log(JSON.stringify(...))` wrappers
+ * that printed a different shape from `status`. One renderer, one shape.
+ */
+export function renderServiceAction(action: ServiceAction, status: ServiceStatus): void {
+  blankLine();
+  console.log(`  ${glyph.on} ${c.bold}Background service ${SERVICE_ACTIONS[action].label}${c.reset}`);
+  if (status.path) field('', `${c.dim}${status.path}${c.reset}`);
+  if (status.detail) field('', `${c.gray}${status.detail}${c.reset}`);
+  blankLine();
+}