@kortix/agent-tunnel 0.13.40 → 0.13.42

package/src/agent/config.ts

@@ -1,8 +1,9 @@
 import { chmodSync, existsSync, lstatSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { basename, dirname, join } from 'path';
 import { homedir } from 'os';
 import { isTunnelCapability } from '../shared/permissions';
 import type { TunnelCapability } from '../shared/types';
+import { agentTunnelHome, defaultAgentTunnelHome } from './service-paths';
 
 export interface TunnelConfig {
   token: string;
@@ -23,7 +24,7 @@ export interface TunnelConfig {
   enabledCapabilities?: TunnelCapability[];
 }
 
-const CONFIG_DIR = join(homedir(), '.agent-tunnel');
+const CONFIG_DIR = agentTunnelHome();
 const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
 
 const DEFAULTS: Partial<TunnelConfig> = {
@@ -213,6 +214,19 @@ export function buildTunnelWsUrl(
   return `${base}${wsPath}?${params.toString()}`;
 }
 
+/**
+ * Directories no RPC may read or write, whatever config.json says. The agent
+ * home holds the credential, access.json (the owner's answer to the access
+ * prompt) and desktop-app.json (what the agent launches). A file grant must
+ * never rewrite them into a permanent grant or a command to run. A desktop
+ * home `<userData>/agent-tunnel/<sha8>` also protects its sibling homes.
+ */
+export function protectedAgentPaths(home: string = CONFIG_DIR): string[] {
+  const paths = new Set([home, defaultAgentTunnelHome()]);
+  if (basename(dirname(home)) === 'agent-tunnel') paths.add(dirname(home));
+  return [...paths];
+}
+
 export function loadConfig(overrides: Partial<TunnelConfig> = {}): TunnelConfig {
   let fileConfig: Partial<TunnelConfig> = {};
   if (existsSync(CONFIG_FILE)) {
@@ -250,6 +264,7 @@ export function loadConfig(overrides: Partial<TunnelConfig> = {}): TunnelConfig
   merged.apiUrl = normalizeApiUrl(merged.apiUrl);
   merged.wsPath = absoluteWsPath(merged.wsPath);
   validateConfigValues(merged);
+  merged.blockedPaths = [...merged.blockedPaths, ...protectedAgentPaths()];
 
   return merged;
 }

package/src/agent/credential-probe.ts

@@ -1,5 +1,5 @@
 import '../node-ws-polyfill';
-import { AGENT_REPLACED_CLOSE_CODE, AGENT_VERSION, AUTH_REJECTED_CLOSE_CODES } from './agent';
+import { AGENT_REPLACED_CLOSE_CODE, AGENT_VERSION, isCredentialRejection } from './agent';
 import { buildTunnelWsUrl, trustedCredential, type TunnelConfig } from './config';
 
 /**
@@ -78,8 +78,8 @@ export function probeCredentials(
     });
 
     socket.addEventListener('close', (event) => {
-      const { code } = event as CloseEvent;
-      if (AUTH_REJECTED_CLOSE_CODES.includes(code)) return settle('rejected');
+      const { code, reason } = event as CloseEvent;
+      if (isCredentialRejection(code, reason)) 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');

package/src/agent/credential-store.ts

@@ -1,8 +1,8 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
-import { homedir } from 'os';
 import { join } from 'path';
+import { agentTunnelHome } from './service-paths';
 
-export const CONFIG_DIR = join(homedir(), '.agent-tunnel');
+export const CONFIG_DIR = agentTunnelHome();
 export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
 
 /** Fields that identify a pairing. Everything else in the file is user settings. */

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

@@ -2,8 +2,10 @@ import { describe, expect, test } from 'bun:test';
 import {
   InvalidDeviceAuthResponseError,
   awaitDeviceAuthorization,
+  machineDisplayName,
   parseDeviceAuthChallenge,
   parseDeviceAuthStatus,
+  requestDeviceAuthorization,
 } from './device-auth';
 
 const VALID_TUNNEL_ID = '00000000-0000-4000-8000-000000000042';
@@ -130,3 +132,58 @@ describe('polling', () => {
     expect(outcome).toEqual({ status: 'expired' });
   });
 });
+
+describe('machine display name', () => {
+  const fails = () => {
+    throw new Error('scutil: not found');
+  };
+
+  test('macOS uses the ComputerName the person set', () => {
+    const name = machineDisplayName({
+      os: 'darwin',
+      host: 'MacBook-Pro-9.local',
+      env: {},
+      run: (command, args) => {
+        expect([command, ...args]).toEqual(['scutil', '--get', 'ComputerName']);
+        return 'Ada’s MacBook Pro\n';
+      },
+    });
+    expect(name).toBe('Ada’s MacBook Pro');
+  });
+
+  test('macOS falls back to the hostname without .local when scutil fails or is empty', () => {
+    expect(machineDisplayName({ os: 'darwin', host: 'MacBook-Pro-9.local', env: {}, run: fails })).toBe(
+      'MacBook-Pro-9',
+    );
+    expect(machineDisplayName({ os: 'darwin', host: 'MacBook-Pro-9.local', env: {}, run: () => '  ' })).toBe(
+      'MacBook-Pro-9',
+    );
+  });
+
+  test('Windows uses COMPUTERNAME', () => {
+    expect(
+      machineDisplayName({ os: 'win32', host: 'desktop-1', env: { COMPUTERNAME: 'STUDIO-PC' }, run: fails }),
+    ).toBe('STUDIO-PC');
+    expect(machineDisplayName({ os: 'win32', host: 'desktop-1', env: {}, run: fails })).toBe('desktop-1');
+  });
+
+  test('Linux uses the hostname and never runs a command', () => {
+    expect(machineDisplayName({ os: 'linux', host: 'build-box.local', env: {}, run: fails })).toBe('build-box');
+    expect(machineDisplayName({ os: 'linux', host: 'build-box', env: {}, run: fails })).toBe('build-box');
+  });
+
+  test('pairing proposes the display name as the machine name', async () => {
+    const original = globalThis.fetch;
+    let body: Record<string, unknown> = {};
+    globalThis.fetch = (async (_url: string, init: RequestInit) => {
+      body = JSON.parse(String(init.body));
+      return new Response(JSON.stringify(challenge()), { status: 200 });
+    }) as unknown as typeof fetch;
+    try {
+      await requestDeviceAuthorization('https://api.kortix.com/v1/tunnel');
+    } finally {
+      globalThis.fetch = original;
+    }
+    expect(body.machineHostname).toBe(machineDisplayName());
+  });
+});

package/src/agent/device-auth.ts

@@ -1,4 +1,4 @@
-import { spawn } from 'child_process';
+import { execFileSync, spawn } from 'child_process';
 import { hostname, platform } from 'os';
 import { isTunnelCapability } from '../shared/permissions';
 import type { TunnelCapability } from '../shared/types';
@@ -10,6 +10,8 @@ import type { TunnelCapability } from '../shared/types';
  * rules below can be read — and tested — without a CLI around them.
  */
 
+export const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 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}$/;
@@ -138,11 +140,51 @@ export function parseDeviceAuthStatus(value: unknown): DeviceAuthOutcome | null
   }
 }
 
-export async function requestDeviceAuthorization(apiUrl: string): Promise<DeviceAuthChallenge> {
+/**
+ * The name a person gave this machine, e.g. "Ada's MacBook Pro" instead of
+ * `MacBook-Pro-9.local`. macOS: System Settings' Computer Name; Windows:
+ * COMPUTERNAME; elsewhere, and whenever those are unavailable, the hostname
+ * without a trailing `.local`.
+ */
+export function machineDisplayName({
+  os = platform(),
+  host = hostname(),
+  env = process.env,
+  run = (command: string, args: string[]) =>
+    execFileSync(command, args, { encoding: 'utf8', timeout: 1_000, stdio: ['ignore', 'pipe', 'ignore'] }),
+}: {
+  os?: string;
+  host?: string;
+  env?: Record<string, string | undefined>;
+  run?: (command: string, args: string[]) => string;
+} = {}): string {
+  const fallback = host.replace(/\.local$/i, '') || host;
+  try {
+    const name =
+      os === 'darwin' ? run('scutil', ['--get', 'ComputerName']) : os === 'win32' ? env.COMPUTERNAME : '';
+    return name?.trim() || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Starts pairing. `projectId` names the project the machine is being connected
+ * to, so the approval page can skip its project picker. A relay that predates
+ * the field ignores it.
+ */
+export async function requestDeviceAuthorization(
+  apiUrl: string,
+  options: { projectId?: string } = {},
+): Promise<DeviceAuthChallenge> {
   const response = await fetch(`${apiUrl}/device-auth`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ machineHostname: hostname() }),
+    body: JSON.stringify({
+      // The default machine name on the approval page.
+      machineHostname: machineDisplayName(),
+      ...(options.projectId ? { project_id: options.projectId } : {}),
+    }),
   });
   if (!response.ok) {
     const body = await response.text().catch(() => '');

package/src/agent/security/path-validator.ts

@@ -56,7 +56,9 @@ function assertAllowedResolvedPath(
     });
 
     if (!withinAllowed) {
-      throw new Error(`Access denied: path "${originalPath}" is outside allowed directories`);
+      throw new Error(
+        `Access denied: path "${originalPath}" is outside allowed directories (${allowedPaths.join(', ')})`,
+      );
     }
   }
 }

package/src/agent/service-control.ts

@@ -2,7 +2,9 @@ import {
   type ServiceStatus,
   getServiceStatus,
   installService,
+  pauseService,
   restartService,
+  resumeService,
   startService,
   stopService,
   uninstallService,
@@ -39,8 +41,8 @@ export function acquireTunnelLease(): TunnelLease {
 
 /** 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' },
+  start: { run: resumeService, label: 'started' },
+  stop: { run: pauseService, label: 'paused until `agent-tunnel start`' },
   restart: { run: restartService, label: 'restarted' },
   uninstall: { run: uninstallService, label: 'removed' },
   install: { run: installService, label: 'installed' },
@@ -50,6 +52,7 @@ export type ServiceAction = keyof typeof SERVICE_ACTIONS;
 
 export function describeService(status: ServiceStatus): string {
   if (!status.installed) return `${glyph.off} not installed`;
+  if (status.enabled === false) return `${c.yellow}○${c.reset} paused ${c.dim}· stays stopped until \`agent-tunnel start\`${c.reset}`;
   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}`;
 }

package/src/agent/service-drivers.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { pause, renderWindowsTaskXml, serviceDriverFor, supervisor } from './service-drivers';
+import { getServicePaths } from './service-paths';
+
+const realRun = supervisor.run;
+const realPause = pause.ms;
+afterEach(() => {
+  supervisor.run = realRun;
+  pause.ms = realPause;
+});
+
+/** Records every supervisor command; `answers` fakes the ones a test cares about. */
+function recordCommands(answers: Record<string, { ok: boolean; detail?: string }> = {}) {
+  const calls: string[] = [];
+  supervisor.run = (command, args) => {
+    const line = [command, ...args].join(' ');
+    calls.push(line);
+    const hit = Object.entries(answers).find(([prefix]) => line.startsWith(prefix));
+    return { ok: hit ? hit[1].ok : true, detail: hit?.[1].detail ?? '' };
+  };
+  return calls;
+}
+
+const paths = getServicePaths('/tmp/agent-tunnel-drivers-test');
+
+describe('durable pause (R3)', () => {
+  test('launchd: pause disables the job before unloading it, so login does not start it again', () => {
+    const calls = recordCommands();
+    serviceDriverFor('darwin')!.pause(paths, true);
+    const uid = process.getuid!();
+    expect(calls).toEqual([
+      `launchctl disable gui/${uid}/${paths.label}`,
+      `launchctl bootout gui/${uid} ${paths.launchdPlist}`,
+    ]);
+  });
+
+  test('launchd: resume enables, loads and starts the job', () => {
+    const calls = recordCommands();
+    const outcome = serviceDriverFor('darwin')!.resume(paths, true);
+    const uid = process.getuid!();
+    expect(calls).toEqual([
+      `launchctl enable gui/${uid}/${paths.label}`,
+      `launchctl bootstrap gui/${uid} ${paths.launchdPlist}`,
+      `launchctl kickstart gui/${uid}/${paths.label}`,
+    ]);
+    expect(outcome.active).toBe(true);
+  });
+
+  test('launchd: status reports a disabled job as paused', () => {
+    const uid = process.getuid!();
+    recordCommands({
+      'launchctl print-disabled': { ok: true, detail: `disabled services = {\n\t"${paths.label}" => disabled\n}` },
+      'launchctl print ': { ok: false },
+    });
+    expect(serviceDriverFor('darwin')!.status(paths, false)).toMatchObject({ active: false, enabled: false });
+    recordCommands({
+      'launchctl print-disabled': { ok: true, detail: `disabled services = {\n\t"${paths.label}" => enabled\n}` },
+    });
+    expect(serviceDriverFor('darwin')!.status(paths, false)).toMatchObject({ active: true, enabled: true });
+    expect(uid).toBeGreaterThanOrEqual(0);
+  });
+
+  test('systemd: pause is disable --now; resume is enable --now', () => {
+    const calls = recordCommands();
+    serviceDriverFor('linux')!.pause(paths, true);
+    serviceDriverFor('linux')!.resume(paths, true);
+    expect(calls).toEqual([
+      `systemctl --user disable --now ${paths.label}.service`,
+      `systemctl --user enable --now ${paths.label}.service`,
+    ]);
+  });
+
+  test('windows: pause disables and ends the task; resume enables and runs it', () => {
+    const calls = recordCommands();
+    serviceDriverFor('win32')!.pause(paths, true);
+    serviceDriverFor('win32')!.resume(paths, true);
+    expect(calls).toEqual([
+      `schtasks.exe /Change /TN ${paths.label} /DISABLE`,
+      `schtasks.exe /End /TN ${paths.label}`,
+      `schtasks.exe /Change /TN ${paths.label} /ENABLE`,
+      `schtasks.exe /Run /TN ${paths.label}`,
+    ]);
+  });
+});
+
+describe('install really starts the service', () => {
+  const runner = { command: '/usr/bin/node', args: ['/opt/kortix/agent-cli.js', 'run', '--service'] };
+  function tempPaths() {
+    const dir = mkdtempSync(join(tmpdir(), 'agent-tunnel-install-'));
+    const base = getServicePaths(dir);
+    return {
+      dir,
+      paths: {
+        ...base,
+        launchdPlist: join(dir, 'job.plist'),
+        systemdUnit: join(dir, 'job.service'),
+        windowsScript: join(dir, 'job.ps1'),
+      },
+    };
+  }
+
+  test('launchd: a bootstrap launchd did not load is retried, and never reported active', () => {
+    const { dir, paths } = tempPaths();
+    pause.ms = () => {};
+    try {
+      const calls = recordCommands({ 'launchctl print': { ok: false }, 'launchctl bootstrap': { ok: false, detail: 'Bootstrap failed: 5: Input/output error' } });
+      const outcome = serviceDriverFor('darwin')!.install(paths, runner);
+      expect(outcome.active).toBeNull();
+      expect(calls.filter((c) => c.startsWith('launchctl bootstrap'))).toHaveLength(3);
+
+      recordCommands();
+      expect(serviceDriverFor('darwin')!.install(paths, runner).active).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('systemd: install restarts a running unit so an update rolls the agent, and keeps it past logout', () => {
+    const { dir, paths } = tempPaths();
+    try {
+      const calls = recordCommands({ 'loginctl show-user': { ok: true, detail: 'Linger=no' } });
+      const outcome = serviceDriverFor('linux')!.install(paths, runner);
+      expect(calls).toContain(`systemctl --user restart ${paths.label}.service`);
+      expect(calls.some((c) => c.startsWith('loginctl enable-linger'))).toBe(true);
+      expect(outcome.active).toBe(true);
+
+      recordCommands({ 'loginctl': { ok: false, detail: 'Linger=no' } });
+      expect(serviceDriverFor('linux')!.install(paths, runner).detail).toContain('stops when you log out');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('windows: the task is registered from XML without battery or 72 h limits, hidden, and restarted on install', () => {
+    const { dir, paths } = tempPaths();
+    try {
+      const calls = recordCommands();
+      serviceDriverFor('win32')!.install(paths, runner);
+      expect(calls[0]).toBe(`schtasks.exe /Create /TN ${paths.label} /XML ${join(dir, 'job.xml')} /F`);
+      expect(calls.slice(1)).toEqual([`schtasks.exe /End /TN ${paths.label}`, `schtasks.exe /Run /TN ${paths.label}`]);
+      const xml = readFileSync(join(dir, 'job.xml')).toString('utf16le');
+      expect(xml.charCodeAt(0)).toBe(0xfeff);
+      expect(xml).toContain('<DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>');
+      expect(xml).toContain('<StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>');
+      expect(xml).toContain('<ExecutionTimeLimit>PT0S</ExecutionTimeLimit>');
+      expect(xml).toContain('-WindowStyle Hidden');
+      expect(renderWindowsTaskXml(paths, 'DOMAIN\\a&b')).toContain('<UserId>DOMAIN\\a&amp;b</UserId>');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('windows: status reads the non-localized task state', () => {
+    recordCommands({ 'powershell.exe': { ok: true, detail: 'Running\r\n' } });
+    expect(serviceDriverFor('win32')!.status(paths, false)).toMatchObject({ active: true, enabled: true });
+    recordCommands({ 'powershell.exe': { ok: true, detail: 'Disabled' } });
+    expect(serviceDriverFor('win32')!.status(paths, false)).toMatchObject({ active: false, enabled: false });
+  });
+});