@emptyos/client 0.1.0

package/lib/pairing.js

@@ -0,0 +1,466 @@
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import https from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+
+import { openInBrowser as defaultOpenInBrowser } from './browser.js';
+import { configPath, readConfig, validateAlias, validateTarget, writeConfig } from './config.js';
+import { ClientError } from './errors.js';
+import { runCaptured } from './process.js';
+
+const CREATE_PATH = '/_system/agents/pairings';
+const STATUS_PATH = '/_system/agents/pairings/status';
+const AGENTS_PATH = '/_system/agents';
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const POLL_INTERVAL_MS = 1000;
+const MAX_PAIRING_LIFETIME_MS = 10 * 60 * 1000;
+const PAIRING_ID_RE = /^[A-Za-z0-9_-]{22}$/;
+const PAIRING_SECRET_RE = /^[A-Za-z0-9_-]{43}$/;
+const PAIRING_CODE_RE = /^[23456789ABCDEFGHJKLMNPQRSTUVWXYZ]{8}$/;
+const AGENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SSH_USER_RE = /^[a-z_][a-z0-9_-]{0,31}$/;
+
+export function validateOwnerOrigin(value) {
+  const hasExplicitScheme = typeof value === 'string'
+    && /^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(value);
+  let url;
+  try {
+    if (typeof value !== 'string' || (!hasExplicitScheme && /^[\\/]/u.test(value))) {
+      throw new TypeError('invalid hostname');
+    }
+    url = new URL(hasExplicitScheme ? value : `https://${value}`);
+  } catch {
+    throw new ClientError('Computer URL must be a hostname or HTTPS origin without credentials or a path');
+  }
+  if (
+    url.protocol !== 'https:'
+    || url.username
+    || url.password
+    || url.pathname !== '/'
+    || url.search
+    || url.hash
+  ) {
+    throw new ClientError('Computer URL must be a hostname or HTTPS origin without credentials or a path');
+  }
+  try {
+    validateTarget(`emptyos@${url.hostname}`);
+  } catch {
+    throw new ClientError('Computer URL must contain a hostname supported by EmptyOS SSH transport');
+  }
+  return url.origin;
+}
+
+export function validatePairingLabel(value) {
+  if (typeof value !== 'string' || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new ClientError('Pairing label must be 1-80 characters without controls');
+  }
+  const label = value.trim();
+  if (label.length === 0 || label.length > 80) {
+    throw new ClientError('Pairing label must be 1-80 characters without controls');
+  }
+  return label;
+}
+
+export function deriveComputerAlias(ownerOrigin) {
+  const origin = validateOwnerOrigin(ownerOrigin);
+  const alias = new URL(origin).hostname.split('.', 1)[0];
+  try {
+    return validateAlias(alias);
+  } catch {
+    throw new ClientError(`Cannot derive a computer alias from computer URL ${JSON.stringify(origin)}; use --as <alias>`);
+  }
+}
+
+export async function pairComputer({ alias, ownerOrigin, label, browser = true }, {
+  env = process.env,
+  stdout = process.stdout,
+  request = requestJson,
+  openInBrowser = defaultOpenInBrowser,
+  sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  runKeygen = defaultRunKeygen,
+  random = randomBytes,
+  now = Date.now,
+  hostname = os.hostname,
+} = {}) {
+  validateAlias(alias);
+  const origin = validateOwnerOrigin(ownerOrigin);
+  const pairingLabel = validatePairingLabel(label ?? hostname());
+  rejectExistingConnection(alias, origin, env);
+
+  const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'emptyos-client-pairing.'));
+  try {
+    fs.chmodSync(temporaryDirectory, 0o700);
+    const temporaryIdentity = path.join(temporaryDirectory, 'id_ed25519');
+    await createKeyPair(temporaryIdentity, env, runKeygen);
+    const publicKey = readPublicKey(`${temporaryIdentity}.pub`, 'generated SSH public key');
+    const publicKeyFingerprint = sshFingerprint(publicKey);
+    const tokenBytes = random(32);
+    if (!(tokenBytes instanceof Uint8Array) || tokenBytes.byteLength !== 32) {
+      throw new ClientError('Pairing token generator must return exactly 32 bytes');
+    }
+    const tunnelToken = `v1.${Buffer.from(tokenBytes).toString('base64url')}`;
+    const tokenHash = createHash('sha256').update(tunnelToken, 'utf8').digest('hex');
+
+    const created = await request(new URL(CREATE_PATH, origin), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ label: pairingLabel, publicKey, tokenHash }),
+    });
+    if (created.status !== 202) throw httpError('create pairing', created.status);
+    const pairing = parseCreatedPairing(created.value, now());
+    const agentsUrl = new URL(AGENTS_PATH, origin).href;
+    stdout.write(`Pairing code: ${pairing.code}\nSSH key: ${publicKeyFingerprint}\nApprove it at:\n  ${agentsUrl}\n`);
+    if (browser) {
+      stdout.write(await openInBrowser(agentsUrl)
+        ? 'Opening the approval page in your browser...\n'
+        : 'Cannot open a browser here; open the approval page yourself\n');
+    }
+    stdout.write('Waiting for approval...\n');
+
+    const approved = await waitForApproval(origin, pairing, { request, sleep, now });
+    const hostKey = inspectEd25519PublicKey(approved.sshHostKey, 'SSH host key');
+    if (!SSH_USER_RE.test(approved.sshUser)) {
+      throw new ClientError('Computer returned an invalid SSH user during pairing', 'pairing-failed');
+    }
+    if (!AGENT_ID_RE.test(approved.agentId)) {
+      throw new ClientError('Computer returned an invalid agent id during pairing', 'pairing-failed');
+    }
+    const ownerHost = new URL(origin).hostname;
+    const target = validateTarget(`${approved.sshUser}@${ownerHost}`);
+    const paths = installCredentials({
+      alias,
+      env,
+      ownerOrigin: origin,
+      temporaryIdentity,
+      tunnelToken,
+      ownerHost,
+      sshHostKey: hostKey,
+    });
+
+    let committed = false;
+    let selected = false;
+    let previousDefault = null;
+    try {
+      const config = readConfig(env);
+      rejectExistingConnectionInConfig(config, alias, origin);
+      config.computers[alias] = {
+        target,
+        ownerOrigin: origin,
+        tunnelTokenPath: paths.tunnelTokenPath,
+        sshIdentityPath: paths.sshIdentityPath,
+        sshKnownHostsPath: paths.sshKnownHostsPath,
+      };
+      previousDefault = config.defaultComputer;
+      if (previousDefault === null) {
+        config.defaultComputer = alias;
+        selected = true;
+      }
+      writeConfig(config, env);
+      committed = true;
+    } finally {
+      if (!committed) removeInstalledCredentials(paths.directory);
+    }
+
+    stdout.write(selected
+      ? `Successfully connected computer ${alias} (${ownerHost}) and selected it as the default\n`
+        + 'List computers with `empty computers`\n'
+      : `Successfully connected computer ${alias} (${ownerHost}); the default computer remains ${previousDefault}\n`
+        + `List computers with \`empty computers\`; switch with \`empty computer use ${alias}\`\n`);
+    return { alias, target, ownerOrigin: origin, agentId: approved.agentId };
+  } finally {
+    fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+  }
+}
+
+async function createKeyPair(identityPath, env, runKeygen) {
+  const command = env.EMPTYOS_SSH_KEYGEN_COMMAND || 'ssh-keygen';
+  let result;
+  try {
+    result = await runKeygen(command, [
+      '-q', '-t', 'ed25519', '-N', '', '-C', '', '-f', identityPath,
+    ], { env });
+  } catch (error) {
+    throw new ClientError(`Cannot generate pairing SSH key: ${error.message}`, 'pairing-failed');
+  }
+  if (!result || result.code !== 0) {
+    const detail = result?.stderr?.trim() || result?.stdout?.trim();
+    throw new ClientError(
+      detail ? `cannot generate pairing SSH key: ${detail}` : 'cannot generate pairing SSH key',
+      'pairing-failed',
+    );
+  }
+  const privateStat = safeRegularFile(identityPath, 'generated SSH private key');
+  if ((privateStat.mode & 0o777) !== 0o600) {
+    throw new ClientError('Generated SSH private key must have mode 0600', 'pairing-failed');
+  }
+  safeRegularFile(`${identityPath}.pub`, 'generated SSH public key');
+}
+
+function defaultRunKeygen(command, args, options) {
+  return runCaptured(command, args, options);
+}
+
+async function waitForApproval(origin, pairing, { request, sleep, now }) {
+  const statusUrl = new URL(STATUS_PATH, origin);
+  while (now() < pairing.expiresAtMilliseconds) {
+    const response = await request(statusUrl, {
+      method: 'GET',
+      headers: {
+        Authorization: `Pairing ${pairing.pairingSecret}`,
+        'X-EmptyOS-Pairing-Id': pairing.pairingId,
+      },
+    });
+    if (response.status !== 200) throw httpError('check pairing status', response.status);
+    const status = parsePairingStatus(response.value);
+    if (status.status === 'approved') return status;
+    if (status.status === 'rejected') {
+      throw new ClientError('The computer owner rejected this pairing', 'pairing-rejected');
+    }
+    if (status.status === 'expired') {
+      throw new ClientError('The pairing request expired before approval', 'pairing-expired');
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new ClientError('The pairing request expired before approval', 'pairing-expired');
+}
+
+function parseCreatedPairing(value, currentTime) {
+  requireObjectKeys(value, ['code', 'expiresAt', 'pairingId', 'pairingSecret'], 'create pairing');
+  if (!PAIRING_ID_RE.test(value.pairingId) || !PAIRING_SECRET_RE.test(value.pairingSecret)
+    || !PAIRING_CODE_RE.test(value.code)) {
+    throw new ClientError('Computer returned an invalid pairing response', 'pairing-failed');
+  }
+  const expiresAtMilliseconds = typeof value.expiresAt === 'string' ? Date.parse(value.expiresAt) : Number.NaN;
+  if (!Number.isFinite(expiresAtMilliseconds)
+    || expiresAtMilliseconds <= currentTime
+    || expiresAtMilliseconds > currentTime + MAX_PAIRING_LIFETIME_MS) {
+    throw new ClientError('Computer returned an invalid pairing expiration', 'pairing-failed');
+  }
+  return { ...value, expiresAtMilliseconds };
+}
+
+function parsePairingStatus(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.status !== 'string') {
+    throw new ClientError('Computer returned an invalid pairing status', 'pairing-failed');
+  }
+  if (value.status === 'approved') {
+    requireObjectKeys(value, ['agentId', 'expiresAt', 'sshHostKey', 'sshUser', 'status'], 'pairing status');
+    requireStatusExpiration(value.expiresAt);
+    return value;
+  }
+  if (['pending', 'approving', 'rejected', 'expired'].includes(value.status)) {
+    requireObjectKeys(value, ['expiresAt', 'status'], 'pairing status');
+    requireStatusExpiration(value.expiresAt);
+    return value;
+  }
+  throw new ClientError('Computer returned an invalid pairing status', 'pairing-failed');
+}
+
+function requireStatusExpiration(value) {
+  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) {
+    throw new ClientError('Computer returned an invalid pairing status expiration', 'pairing-failed');
+  }
+}
+
+function requireObjectKeys(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join(',') !== [...keys].sort().join(',')) {
+    throw new ClientError(`Computer returned an invalid ${label} response`, 'pairing-failed');
+  }
+}
+
+function inspectEd25519PublicKey(value, label) {
+  if (typeof value !== 'string') {
+    throw new ClientError(`The ${label} must be a comment-free OpenSSH Ed25519 key`, 'pairing-failed');
+  }
+  const match = /^ssh-ed25519 ([A-Za-z0-9+/]+={0,2})$/.exec(value);
+  if (!match) throw new ClientError(`The ${label} must be a comment-free OpenSSH Ed25519 key`, 'pairing-failed');
+  const blob = Buffer.from(match[1], 'base64');
+  if (blob.toString('base64') !== match[1]) {
+    throw new ClientError(`The ${label} has non-canonical base64`, 'pairing-failed');
+  }
+  const type = readSshString(blob, 0, label);
+  const key = readSshString(blob, type.end, label);
+  if (type.value.toString('ascii') !== 'ssh-ed25519' || key.value.length !== 32 || key.end !== blob.length) {
+    throw new ClientError(`The ${label} is not an exact Ed25519 SSH key`, 'pairing-failed');
+  }
+  return value;
+}
+
+function sshFingerprint(publicKey) {
+  const encoded = /^ssh-ed25519 ([A-Za-z0-9+/]+={0,2})$/u.exec(publicKey)?.[1];
+  if (!encoded) throw new ClientError('Cannot fingerprint the generated SSH public key', 'pairing-failed');
+  return `SHA256:${createHash('sha256').update(Buffer.from(encoded, 'base64')).digest('base64').replace(/=+$/u, '')}`;
+}
+
+function readSshString(blob, offset, label) {
+  if (offset + 4 > blob.length) throw new ClientError(`The ${label} has invalid SSH wire format`, 'pairing-failed');
+  const length = blob.readUInt32BE(offset);
+  const start = offset + 4;
+  const end = start + length;
+  if (end > blob.length) throw new ClientError(`The ${label} has invalid SSH wire format`, 'pairing-failed');
+  return { value: blob.subarray(start, end), end };
+}
+
+function readPublicKey(file, label) {
+  safeRegularFile(file, label);
+  const raw = fs.readFileSync(file, 'utf8');
+  const value = raw.trim();
+  if (value.includes('\n') || value.includes('\r')) {
+    throw new ClientError(`The ${label} must contain one comment-free key`, 'pairing-failed');
+  }
+  return inspectEd25519PublicKey(value, label);
+}
+
+function safeRegularFile(file, label) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    throw new ClientError(`Cannot inspect ${label}: ${error.message}`, 'pairing-failed');
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new ClientError(`The ${label} must be a regular file, not a symbolic link`, 'pairing-failed');
+  }
+  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+    throw new ClientError(`The ${label} must be owned by the current user`, 'pairing-failed');
+  }
+  return stat;
+}
+
+function installCredentials({ alias, env, ownerOrigin, temporaryIdentity, tunnelToken, ownerHost, sshHostKey }) {
+  rejectExistingConnection(alias, ownerOrigin, env);
+  const clientDirectory = path.dirname(configPath(env));
+  ensurePrivateDirectory(clientDirectory);
+  const computersDirectory = path.join(clientDirectory, 'computers');
+  ensurePrivateDirectory(computersDirectory);
+  const directory = path.join(computersDirectory, alias);
+  try {
+    fs.mkdirSync(directory, { mode: 0o700 });
+    fs.chmodSync(directory, 0o700);
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      throw new ClientError(`Pairing credentials already exist for computer "${alias}"; refusing to overwrite them`);
+    }
+    throw new ClientError(`Cannot create pairing credentials for computer "${alias}": ${error.message}`);
+  }
+
+  const sshIdentityPath = path.join(directory, 'id_ed25519');
+  const tunnelTokenPath = path.join(directory, 'tunnel-token');
+  const sshKnownHostsPath = path.join(directory, 'known_hosts');
+  try {
+    const privateKey = fs.readFileSync(temporaryIdentity);
+    if (privateKey.byteLength === 0) throw new ClientError('Generated SSH private key is empty', 'pairing-failed');
+    fs.writeFileSync(sshIdentityPath, privateKey, { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(tunnelTokenPath, `${tunnelToken}\n`, { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(sshKnownHostsPath, `${ownerHost} ${sshHostKey}\n`, { flag: 'wx', mode: 0o600 });
+    return { directory, sshIdentityPath, tunnelTokenPath, sshKnownHostsPath };
+  } catch (error) {
+    removeInstalledCredentials(directory);
+    if (error instanceof ClientError) throw error;
+    throw new ClientError(`Cannot install pairing credentials for computer "${alias}": ${error.message}`);
+  }
+}
+
+function ensurePrivateDirectory(directory) {
+  try {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new Error('path is not a regular directory');
+    }
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+      throw new Error('directory is not owned by the current user');
+    }
+    fs.chmodSync(directory, 0o700);
+  } catch (error) {
+    throw new ClientError(`Cannot prepare pairing credential directory ${directory}: ${error.message}`);
+  }
+}
+
+function removeInstalledCredentials(directory) {
+  try {
+    fs.rmSync(directory, { recursive: true, force: true });
+  } catch {
+    // A failed best-effort rollback leaves private material in its 0700 directory.
+  }
+}
+
+function rejectExistingConnection(alias, ownerOrigin, env) {
+  rejectExistingConnectionInConfig(readConfig(env), alias, ownerOrigin);
+}
+
+function rejectExistingConnectionInConfig(config, alias, ownerOrigin) {
+  if (config.computers[alias]) {
+    throw new ClientError(`Computer "${alias}" is already configured; choose another with --as <alias>`);
+  }
+  const existing = Object.entries(config.computers).find(([, profile]) => (
+    profile.ownerOrigin && new URL(profile.ownerOrigin).origin === ownerOrigin
+  ));
+  if (existing) {
+    throw new ClientError(`Computer at ${JSON.stringify(ownerOrigin)} is already connected as "${existing[0]}"`);
+  }
+}
+
+function httpError(action, status) {
+  return new ClientError(`Cannot ${action}: computer returned HTTP ${status}`, 'pairing-failed');
+}
+
+export function requestJson(url, { method, headers = {}, body }, requestImpl = https.request) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const complete = (operation, value) => {
+      if (settled) return;
+      settled = true;
+      operation(value);
+    };
+    const payload = body === undefined ? null : Buffer.from(body, 'utf8');
+    const requestHeaders = {
+      ...headers,
+      ...(payload ? { 'content-length': String(payload.byteLength) } : {}),
+    };
+    const req = requestImpl(url, { method, headers: requestHeaders }, (res) => {
+      const chunks = [];
+      let length = 0;
+      res.once('error', (error) => complete(
+        reject,
+        new ClientError(`Pairing response failed: ${error.message}`, 'pairing-failed'),
+      ));
+      res.on('data', (chunk) => {
+        if (settled) return;
+        length += chunk.length;
+        if (length > MAX_RESPONSE_BYTES) {
+          complete(reject, new ClientError('Pairing response is too large', 'pairing-failed'));
+          req.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      res.on('end', () => {
+        if (settled) return;
+        let value = null;
+        const responseBody = Buffer.concat(chunks, length).toString('utf8');
+        if (responseBody.length > 0) {
+          try {
+            value = JSON.parse(responseBody);
+          } catch {
+            const status = res.statusCode ?? 0;
+            if (status === 200 || status === 202) {
+              complete(reject, new ClientError(`Computer returned invalid JSON for pairing (HTTP ${status})`, 'pairing-failed'));
+              return;
+            }
+          }
+        }
+        complete(resolve, { status: res.statusCode ?? 0, value });
+      });
+    });
+    req.setTimeout(15_000, () => req.destroy(new Error('pairing request timed out')));
+    req.once('error', (error) => complete(
+      reject,
+      new ClientError(`Pairing request failed: ${error.message}`, 'pairing-failed'),
+    ));
+    if (payload) req.write(payload);
+    req.end();
+  });
+}