Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

56.1 KB
Raw Blame
/**
 * OpenSSH config discovery plus Cindy's narrowly-owned config writer.
 *
 * Discovery intentionally implements only the subset Cindy consumes. Include
 * is expanded at root scope and inside a pure `Host *` block. Other Host
 * scopes are conditional, so expanding them without evaluating OpenSSH's full
 * matcher would invent aliases that `ssh <alias>` cannot actually see. If a
 * skipped conditional Include or an unevaluated Match may affect a discovered
 * alias, that host remains visible but is marked unsupported instead of using
 * default fields.
 */

import { createHash, randomBytes } from 'node:crypto';
import { promises as fs } from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import SSHConfig from 'ssh-config';

import {
  defaultIdentityPaths,
  resolveIdentityFingerprints,
  type IdentityFingerprintResolution,
} from './sshAuthentication.js';
import type { HostConfig } from './types.js';

const DEFAULT_PORT = 22;
const MAX_INCLUDE_DEPTH = 16;
const MAX_INCLUDE_FILES = 64;
const MAX_INCLUDE_BYTES = 1024 * 1024;
const AUTH_MARKER_PREFIX = '# xdt-maker:auth=';
/** File-level marker proving that Cindy created/owns the managed config. */
export const MANAGED_CONFIG_MARKER = '# xdt-maker:managed=v1';
export const MANAGED_CONFIG_OWNERSHIP_REQUIRED_CODE = 'SSH_CONFIG_OWNERSHIP_REQUIRED';
export const MANAGED_CONFIG_CONCURRENT_MODIFICATION_CODE = 'SSH_CONFIG_CONCURRENT_MODIFICATION';
export const MANAGED_CONFIG_WRITE_TOKEN_REQUIRED_CODE = 'SSH_CONFIG_WRITE_TOKEN_REQUIRED';
const MATCH_NO_ARGUMENT_CRITERIA = new Set(['all', 'canonical', 'final']);
const MATCH_ONE_ARGUMENT_CRITERIA = new Set([
  'command',
  'exec',
  'host',
  'localaddress',
  'localcommand',
  'localnetwork',
  'localport',
  'localuser',
  'originalhost',
  'remoteaddress',
  'remoteport',
  'tagged',
  'user',
  'version',
]);

export interface SshConfigDiagnostic {
  path: string;
  kind: 'io' | 'syntax' | 'limit';
  message: string;
  recoveryHint: string;
}

export interface ReadSshConfigOptions {
  /** Cindy-owned config file. Omit it to make every discovered host read-only. */
  managedConfigPath?: string;
}

export interface ReadSshConfigResult {
  hosts: HostConfig[];
  diagnostic: SshConfigDiagnostic | null;
  warnings: string[];
  /**
   * Opaque SHA-256 token for the exact Cindy-owned managed config bytes read
   * during this discovery pass. Trusted hosts may pass it to managed writers;
   * it must never be projected over IPC or stored on a host snapshot.
   * Undefined when no managed path was requested, the file was not reached,
   * or its Cindy ownership marker was absent.
   */
  managedConfigWriteToken?: ManagedConfigWriteToken;
}

declare const managedConfigWriteTokenBrand: unique symbol;
export type ManagedConfigWriteToken = string & {
  readonly [managedConfigWriteTokenBrand]: true;
};

/**
 * Conditional rollback for a host that was successfully published to the
 * managed SSH file. The rollback refuses to overwrite later external edits.
 */
export interface ManagedHostAddReceipt {
  rollback(): Promise<boolean>;
}

type AuthMarker = 'agent' | 'key';
type Scope =
  | { kind: 'root' }
  | { kind: 'host'; declaration: HostDeclaration }
  | { kind: 'match'; declaration: MatchDeclaration };

interface HostDeclaration {
  patterns: string[];
  sourcePath: string;
  physicalPath: string;
  marker: AuthMarker | null;
  order: number;
}

interface MatchDeclaration {
  expression: string;
  /** True once the block contains a directive Cindy would otherwise ignore. */
  hasDirectives: boolean;
  order: number;
}

interface SkippedConditionalInclude {
  /** Host scope whose effective directives may come from the skipped Include. */
  scope: Extract<Scope, { kind: 'host' }>;
}

interface DirectiveRecord {
  name: string;
  value: string;
  scope: Scope;
  order: number;
}

interface WalkState {
  rootDir: string;
  managedComparable: string | null;
  visited: Set<string>;
  files: string[];
  bytes: number;
  declarations: HostDeclaration[];
  matches: MatchDeclaration[];
  skippedConditionalIncludes: SkippedConditionalInclude[];
  incompleteUnconditionalInclude: boolean;
  managedConfigOwned: boolean;
  managedConfigWriteToken?: ManagedConfigWriteToken;
  directives: DirectiveRecord[];
  warnings: string[];
  order: number;
}

interface SshConfigSection {
  type?: number;
  before?: string;
  after?: string;
  param?: string;
  separator?: string;
  quoted?: boolean;
  value?: string | SshConfigValueToken | Array<string | SshConfigValueToken>;
  content?: string;
  config?: SshConfigSection[];
}

interface SshConfigValueToken { val?: unknown }

const SSH_CONFIG_DIRECTIVE_TYPE = 1;
const SSH_CONFIG_COMMENT_TYPE = 2;

export function defaultSshConfigPath(): string {
  return path.join(os.homedir(), '.ssh', 'config');
}

export function defaultManagedSshConfigPath(): string {
  return path.join(os.homedir(), '.ssh', 'cindy.conf');
}

export function expandHome(value: string): string {
  if (value === '~') return os.homedir();
  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
  if (value.startsWith('~\\')) {
    return path.join(os.homedir(), value.slice(2).replace(/\\/g, '/'));
  }
  return value;
}

type IncludePathExpansionResult =
  | { pattern: string; warning?: never }
  | { pattern?: never; warning: string };

/** Expand the environment and home-directory forms accepted by OpenSSH Include. */
function expandIncludePath(value: string): IncludePathExpansionResult {
  let pattern = '';
  let cursor = 0;
  while (cursor < value.length) {
    const start = value.indexOf('${', cursor);
    if (start < 0) {
      pattern += value.slice(cursor);
      break;
    }
    pattern += value.slice(cursor, start);
    const end = value.indexOf('}', start + 2);
    if (end < 0) {
      return { warning: 'malformed environment variable expression; Include was not expanded.' };
    }
    const name = value.slice(start + 2, end);
    if (!name || name.includes('{')) {
      return { warning: 'malformed environment variable expression; Include was not expanded.' };
    }
    const environmentValue = process.env[name];
    if (environmentValue === undefined) {
      return {
        warning: `environment variable "${name}" is not set; Include was not expanded.`,
      };
    }
    pattern += environmentValue;
    cursor = end + 1;
  }

  const currentUserPattern = /^~([^/\\]+)(?:[/\\](.*))?$/.exec(pattern);
  if (currentUserPattern) {
    const username = currentUserPattern[1]!;
    if (username !== os.userInfo().username) {
      return {
        warning: `home directory for user "${username}" cannot be resolved by Cindy; Include was not expanded.`,
      };
    }
    const remainder = currentUserPattern[2];
    return {
      pattern: remainder === undefined
        ? os.homedir()
        : path.join(os.homedir(), remainder.replace(/\\/g, '/')),
    };
  }

  return { pattern: expandHome(pattern) };
}

type HostNameExpansionResult =
  | { hostname: string; unsupportedToken?: never }
  | { hostname?: never; unsupportedToken: string };

/** HostName accepts only %% and %h; expand once so alias contents are not re-read as tokens. */
function expandHostNameTokens(value: string, alias: string): HostNameExpansionResult {
  let hostname = '';
  for (let index = 0; index < value.length; index += 1) {
    const char = value[index]!;
    if (char !== '%') {
      hostname += char;
      continue;
    }

    const token = value[index + 1];
    if (token === '%') hostname += '%';
    else if (token === 'h') hostname += alias;
    else return { unsupportedToken: token === undefined ? '%' : `%${token}` };
    index += 1;
  }
  return { hostname };
}

export async function readSshConfig(
  filePath = defaultSshConfigPath(),
  options: ReadSshConfigOptions = {},
): Promise<HostConfig[]> {
  const result = await readSshConfigDetailed(filePath, options);
  if (result.diagnostic) throw new Error(result.diagnostic.message);
  return result.hosts;
}

export async function readSshConfigDetailed(
  filePath = defaultSshConfigPath(),
  options: ReadSshConfigOptions = {},
): Promise<ReadSshConfigResult> {
  const absoluteMainPath = path.resolve(filePath);
  const managedComparable = options.managedConfigPath
    ? await comparablePath(options.managedConfigPath)
    : null;
  const state: WalkState = {
    rootDir: path.dirname(absoluteMainPath),
    managedComparable,
    visited: new Set(),
    files: [],
    bytes: 0,
    declarations: [],
    matches: [],
    skippedConditionalIncludes: [],
    incompleteUnconditionalInclude: false,
    managedConfigOwned: false,
    directives: [],
    warnings: [],
    order: 0,
  };

  try {
    await walkFile(absoluteMainPath, { kind: 'root' }, state, 0, false);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
      const warnings = options.managedConfigPath && await pathExists(options.managedConfigPath)
        ? ['Cindy\'s SSH host file exists but is not reachable through a supported Include.']
        : [];
      return { hosts: [], diagnostic: null, warnings };
    }
    return {
      hosts: [],
      diagnostic: toConfigDiagnostic(absoluteMainPath, error),
      warnings: state.warnings,
    };
  }

  if (options.managedConfigPath) {
    const managedExists = await pathExists(options.managedConfigPath);
    const reachedManaged = managedComparable
      ? Array.from(state.visited).some((item) => pathsEqual(item, managedComparable))
      : false;
    if (managedExists && !reachedManaged) {
      state.warnings.push('Cindy\'s SSH host file exists but is not reachable through a supported Include.');
    }
  }

  return {
    hosts: await buildHosts(state, managedComparable),
    diagnostic: null,
    warnings: state.warnings,
    ...(state.managedConfigWriteToken
      ? { managedConfigWriteToken: state.managedConfigWriteToken }
      : {}),
  };
}

async function walkFile(
  filePath: string,
  inheritedScope: Scope,
  state: WalkState,
  depth: number,
  optional: boolean,
): Promise<void> {
  if (depth > MAX_INCLUDE_DEPTH) {
    throw limitError(filePath, `Include nesting exceeds ${MAX_INCLUDE_DEPTH} levels`);
  }

  let physicalPath: string;
  try {
    physicalPath = await comparablePath(filePath);
  } catch (error) {
    if (optional && (error as NodeJS.ErrnoException).code === 'ENOENT') return;
    throw error;
  }
  if (state.visited.has(physicalPath)) return;

  let rawBytes: Buffer;
  try {
    rawBytes = await fs.readFile(physicalPath);
  } catch (error) {
    if (optional && (error as NodeJS.ErrnoException).code === 'ENOENT') return;
    throw error;
  }
  if (state.files.length >= MAX_INCLUDE_FILES) {
    throw limitError(physicalPath, `Include file count exceeds ${MAX_INCLUDE_FILES}`);
  }
  const bytes = rawBytes.byteLength;
  if (state.bytes + bytes > MAX_INCLUDE_BYTES) {
    throw limitError(physicalPath, `expanded SSH config exceeds ${MAX_INCLUDE_BYTES} bytes`);
  }

  const raw = rawBytes.toString('utf8');
  try {
    SSHConfig.parse(raw);
  } catch (error) {
    const syntaxError = new Error(
      `failed to parse SSH config: ${error instanceof Error ? error.message : String(error)}`,
    ) as Error & { code?: string; path?: string };
    syntaxError.code = 'SSH_CONFIG_SYNTAX';
    syntaxError.path = physicalPath;
    throw syntaxError;
  }

  state.visited.add(physicalPath);
  state.files.push(physicalPath);
  state.bytes += bytes;
  if (state.managedComparable !== null && pathsEqual(physicalPath, state.managedComparable)) {
    state.managedConfigOwned = hasManagedConfigMarker(raw);
    state.managedConfigWriteToken = state.managedConfigOwned
      ? managedConfigToken(rawBytes)
      : undefined;
  }

  let scope = inheritedScope;
  const lines = raw.split(/\r?\n/);
  for (let index = 0; index < lines.length; index += 1) {
    const line = lines[index] ?? '';
    const trimmed = line.trim();
    if (!trimmed) continue;

    if (trimmed.startsWith('#')) {
      if (scope.kind === 'host' && scope.declaration.marker === null) {
        const marker = parseAuthMarker(trimmed);
        if (marker) scope.declaration.marker = marker;
      }
      continue;
    }

    const directive = parseDirectiveLine(trimmed);
    if (!directive) continue;
    const location = `${physicalPath}:${index + 1}`;

    if (directive.keyword === 'host') {
      const patterns = splitWords(directive.value);
      const declaration: HostDeclaration = {
        patterns,
        sourcePath: filePath,
        physicalPath,
        marker: null,
        order: state.order++,
      };
      state.declarations.push(declaration);
      scope = { kind: 'host', declaration };
      continue;
    }

    if (directive.keyword === 'match') {
      const declaration: MatchDeclaration = {
        expression: directive.value,
        hasDirectives: false,
        order: state.order++,
      };
      state.matches.push(declaration);
      scope = { kind: 'match', declaration };
      state.warnings.push(`${location}: Match is not evaluated by Cindy.`);
      continue;
    }

    if (scope.kind === 'match') scope.declaration.hasDirectives = true;

    if (directive.keyword === 'include') {
      if (!isSupportedIncludeScope(scope)) {
        if (scope.kind === 'host') {
          state.skippedConditionalIncludes.push({ scope });
        }
        state.warnings.push(`${location}: conditional Include was not expanded.`);
        continue;
      }
      for (const patternValue of splitWords(directive.value)) {
        const expansion = expandIncludePath(patternValue);
        if ('warning' in expansion) {
          state.warnings.push(`${location}: ${expansion.warning}`);
          state.incompleteUnconditionalInclude = true;
          continue;
        }
        const expanded = expansion.pattern;
        const absolutePattern = path.isAbsolute(expanded)
          ? expanded
          : path.resolve(state.rootDir, expanded);
        for (const includedPath of await globPaths(absolutePattern)) {
          const includedComparable = await comparablePath(includedPath);
          const repeatedManagedGlob = hasGlob(expanded)
            && state.managedComparable !== null
            && state.visited.has(includedComparable)
            && pathsEqual(includedComparable, state.managedComparable);
          // The child starts in the parent's active scope. This local scope is
          // deliberately restored when the recursive call returns.
          await walkFile(includedPath, scope, state, depth + 1, true);
          if (repeatedManagedGlob) {
            state.warnings.push(
              `${location}: Include glob reaches Cindy's SSH host file after it was already loaded.`,
            );
          }
        }
      }
      continue;
    }

    if (isCanonicalizationDirective(directive.keyword)) {
      state.warnings.push(`${location}: hostname canonicalization is not evaluated by Cindy.`);
      if (directive.keyword === 'canonicalizehostname' && scope.kind !== 'match') {
        state.directives.push({
          name: directive.keyword,
          value: firstWordOrRaw(directive.value),
          scope,
          order: state.order++,
        });
      }
      continue;
    }
    if (scope.kind === 'match') continue;

    const name = directive.keyword;
    if (name === 'hostname'
      || name === 'user'
      || name === 'port'
      || name === 'identityfile'
      || name === 'identitiesonly'
      || name === 'identityagent'
      || name === 'hostkeyalias'
      || name === 'proxyjump'
      || name === 'proxycommand'
      || name === 'certificatefile'
      || name === 'pkcs11provider'
      || name === 'securitykeyprovider') {
      state.directives.push({
        name,
        value: firstWordOrRaw(directive.value),
        scope,
        order: state.order++,
      });
    }
  }
}

async function buildHosts(
  state: WalkState,
  managedComparable: string | null,
): Promise<HostConfig[]> {
  const aliases: string[] = [];
  const fingerprintCache = new Map<string, Promise<IdentityFingerprintResolution>>();
  const seen = new Set<string>();
  for (const declaration of state.declarations) {
    for (const pattern of declaration.patterns) {
      if (!isConcreteAlias(pattern) || seen.has(pattern)) continue;
      seen.add(pattern);
      aliases.push(pattern);
    }
  }

  const hosts: HostConfig[] = [];
  // Keep public-key inspection sequential. A config may contain many aliases
  // pointing at the same identities; unbounded Promise.all would turn a small
  // config into a burst of file descriptors during startup.
  for (const alias of aliases) {
    const introducing = state.declarations.filter((declaration) =>
      declaration.patterns.some((pattern) => pattern === alias));
    const firstIntroducing = introducing[0];
    const identityDirectives = matchingDirectives(state.directives, alias, 'identityfile');
    const introducingIdentity = identityDirectives.find((directive) =>
      directive.scope.kind === 'host'
      && directive.scope.declaration === firstIntroducing
      && directive.value.toLowerCase() !== 'none')?.value;
    const marker = firstIntroducing?.marker ?? null;
    const matchMayAffectHost = state.matches.some((declaration) =>
      declaration.hasDirectives
      && matchExpressionMayApplyToAlias(declaration.expression, alias));
    const conditionalIncludeMayAffectHost = state.skippedConditionalIncludes.some(
      ({ scope }) => scopeMatches(scope, alias),
    );
    // Strategy B: ordinary OpenSSH hosts are Agent-first, independently of
    // whether the concrete IdentityFile lives in the main file or an Include.
    // Only Cindy's marker opts into direct private-key reads or an explicit
    // agent pin. Compatibility trade-off: a legacy no-marker host that relied
    // on Cindy reading an unencrypted private key must load it with ssh-add or
    // migrate to a marked Cindy-managed key host. managedByCindy remains
    // ownership-only.
    const authMethod = marker ?? 'agent';
    const identityRaw = marker === 'key'
      ? introducingIdentity
      : marker === 'agent'
        ? introducingIdentity
        : undefined;
    const hostnameRaw = firstMatchingDirective(state.directives, alias, 'hostname');
    const hostnameExpansion = hostnameRaw === undefined
      ? { hostname: alias }
      : expandHostNameTokens(hostnameRaw, alias);
    const unsupportedHostNameToken = hostnameExpansion.unsupportedToken;
    if (hostnameExpansion.unsupportedToken !== undefined) {
      state.warnings.push(
        `SSH host ${JSON.stringify(alias)} remains listed but unsupported because HostName uses token `
        + `${JSON.stringify(hostnameExpansion.unsupportedToken)}.`,
      );
    }
    // The alias is display-only on this path. unsupportedReason below prevents
    // it from reaching TCP, TOFU, or endpoint fingerprinting.
    const hostname = hostnameExpansion.hostname ?? alias;
    const user = firstMatchingDirective(state.directives, alias, 'user')
      ?? os.userInfo().username;
    const port = parseIntSafe(firstMatchingDirective(state.directives, alias, 'port'), DEFAULT_PORT);

    const uniquelyManaged = managedComparable !== null
      && introducing.length === 1
      && firstIntroducing?.patterns.length === 1
      && pathsEqual(firstIntroducing.physicalPath, managedComparable);
    const managedOwnership = uniquelyManaged && state.managedConfigOwned;

    const identityFileDirectiveSeen = identityDirectives.length > 0;
    const identityFileNoneSeen = identityDirectives.some(
      (directive) => directive.value.toLowerCase() === 'none',
    );
    const identityContext: IdentityFileTokenContext = {
      alias,
      hostname,
      user,
      port,
      hostKeyAlias: firstMatchingDirective(state.directives, alias, 'hostkeyalias'),
      proxyJump: firstMatchingDirective(state.directives, alias, 'proxyjump'),
    };
    const concreteIdentityDirectives = identityDirectives
      .filter((directive) => directive.value.toLowerCase() !== 'none');
    const explicitIdentityFiles: string[] = [];
    let unsupportedIdentityToken: string | undefined;
    for (const directive of concreteIdentityDirectives) {
      const expansion = expandIdentityFile(directive.value, identityContext);
      if ('unsupportedToken' in expansion) {
        unsupportedIdentityToken = expansion.unsupportedToken;
        break;
      }
      explicitIdentityFiles.push(expansion.filePath);
    }
    if (unsupportedIdentityToken !== undefined) {
      state.warnings.push(
        `SSH host ${JSON.stringify(alias)} remains listed but unsupported because IdentityFile uses token `
        + `${JSON.stringify(unsupportedIdentityToken)}.`,
      );
    }
    const introducingIdentityIndex = identityRaw === undefined
      ? -1
      : concreteIdentityDirectives.findIndex((directive) => directive.value === identityRaw);
    const identityFile = introducingIdentityIndex >= 0
      ? explicitIdentityFiles[introducingIdentityIndex]
      : undefined;
    const identitiesOnlyRaw = firstMatchingDirective(
      state.directives,
      alias,
      'identitiesonly',
    );
    const identitiesOnly = identitiesOnlyRaw?.toLowerCase() === 'yes';
    const configuredIdentityFiles = identityFileDirectiveSeen
      ? explicitIdentityFiles
      : identitiesOnly
        ? defaultIdentityPaths()
        : [];
    const canonicalizeHostname = firstMatchingDirective(
      state.directives,
      alias,
      'canonicalizehostname',
    )?.toLowerCase();
    let unsupportedReason = state.incompleteUnconditionalInclude
      ? 'Cindy could not completely expand an unconditional Include'
      : matchMayAffectHost
        ? 'Cindy does not evaluate a Match block that may affect this SSH host'
        : conditionalIncludeMayAffectHost
          ? 'Cindy does not expand a conditional Include that may affect this SSH host'
          : canonicalizeHostname !== undefined && canonicalizeHostname !== 'no'
            ? canonicalizeHostname === 'yes' || canonicalizeHostname === 'always'
              ? 'Cindy does not implement OpenSSH hostname canonicalization'
              : `unsupported CanonicalizeHostname value: ${canonicalizeHostname}`
            : unsupportedHostNameToken !== undefined
              ? `unsupported HostName token: ${unsupportedHostNameToken}`
              : unsupportedIdentityToken !== undefined
                ? `unsupported IdentityFile token: ${unsupportedIdentityToken}`
                : identitiesOnlyRaw !== undefined
                  && identitiesOnlyRaw.toLowerCase() !== 'yes'
                  && identitiesOnlyRaw.toLowerCase() !== 'no'
                  ? `unsupported IdentitiesOnly value: ${identitiesOnlyRaw}`
                  : undefined;
    const unsupportedTransportDirectives = ['proxyjump', 'proxycommand']
      .filter((name) => {
        const value = firstMatchingDirective(state.directives, alias, name);
        return value !== undefined && value.toLowerCase() !== 'none';
      });
    if (unsupportedTransportDirectives.length > 0) {
      unsupportedReason ??= `Cindy does not support ${unsupportedTransportDirectives.join(' / ')} transport configuration`;
    }
    const unsupportedAgentDirectives = [
      'certificatefile',
      'pkcs11provider',
      'securitykeyprovider',
    ].filter((name) => matchingDirectives(state.directives, alias, name).length > 0);
    if (authMethod === 'agent' && unsupportedAgentDirectives.length > 0) {
      if (identitiesOnly) {
        unsupportedReason ??= `Cindy cannot enforce IdentitiesOnly with ${unsupportedAgentDirectives.join(', ')}`;
      } else {
        state.warnings.push(
          `Host ${alias}: ${unsupportedAgentDirectives.join(', ')} is not interpreted by Cindy; SSH Agent will be used.`,
        );
      }
    }
    let allowedAgentFingerprints: string[] | undefined;
    if (authMethod === 'agent' && identitiesOnly && !unsupportedReason) {
      const resolved = await resolveCompleteFingerprintSet(
        configuredIdentityFiles,
        !identityFileDirectiveSeen,
        fingerprintCache,
      );
      allowedAgentFingerprints = resolved.fingerprints;
      unsupportedReason = resolved.unsupportedReason;
    }

    hosts.push({
      id: alias,
      hostname,
      port,
      user,
      authMethod,
      identityFile,
      sshAuthentication: {
        ...(marker ? { marker } : {}),
        identitiesOnly,
        ...(firstMatchingDirective(state.directives, alias, 'identityagent') !== undefined
          ? { identityAgent: firstMatchingDirective(state.directives, alias, 'identityagent') }
          : {}),
        configuredIdentityFiles,
        identityFileDirectiveSeen,
        identityFileNoneSeen,
        ...(allowedAgentFingerprints ? { allowedAgentFingerprints } : {}),
        ...(unsupportedReason ? { unsupportedReason } : {}),
      },
      source: 'ssh-config' as const,
      managedByCindy: managedOwnership,
    });
  }
  return hosts;
}

async function resolveCompleteFingerprintSet(
  identityFiles: string[],
  usingDefaults: boolean,
  cache: Map<string, Promise<IdentityFingerprintResolution>>,
): Promise<{ fingerprints?: string[]; unsupportedReason?: string }> {
  const fingerprints: string[] = [];
  for (const identityFile of identityFiles) {
    let pending = cache.get(identityFile);
    if (!pending) {
      pending = resolveIdentityFingerprints(identityFile);
      cache.set(identityFile, pending);
    }
    const resolved = await pending;
    if (usingDefaults && resolved.missing) continue;
    if (resolved.fingerprints.length === 0) {
      return {
        unsupportedReason: usingDefaults
          ? `default identity ${identityFile} exists but Cindy cannot resolve its public key`
          : `IdentityFile ${identityFile} has no public key Cindy can resolve without reading the private key`,
      };
    }
    for (const fingerprint of resolved.fingerprints) {
      if (!fingerprints.includes(fingerprint)) fingerprints.push(fingerprint);
    }
  }
  return fingerprints.length > 0
    ? { fingerprints }
    : { unsupportedReason: 'IdentitiesOnly yes has no identity Cindy can pin in ssh-agent' };
}

function matchingDirectives(
  directives: DirectiveRecord[],
  alias: string,
  name: string,
): DirectiveRecord[] {
  return directives
    .filter((directive) => directive.name === name && scopeMatches(directive.scope, alias))
    .sort((a, b) => a.order - b.order);
}

function firstMatchingDirective(
  directives: DirectiveRecord[],
  alias: string,
  name: string,
  scopeFilter: (scope: Scope) => boolean = () => true,
): string | undefined {
  return directives
    .filter((directive) => directive.name === name
      && scopeFilter(directive.scope)
      && scopeMatches(directive.scope, alias))
    .sort((a, b) => a.order - b.order)[0]?.value;
}

function scopeMatches(scope: Scope, alias: string): boolean {
  if (scope.kind === 'root') return true;
  if (scope.kind === 'match') return false;
  try {
    return matchesHostPattern(scope.declaration.patterns, alias);
  } catch {
    return false;
  }
}

/**
 * OpenSSH host patterns support only `*`, `?`, and a leading `!` negation.
 * The ssh-config package's glob helper treats `?` as optional (`.?`), which
 * can apply a wildcard block to the wrong alias (for example `foo?` → `foo`).
 */
function matchesHostPattern(patterns: readonly string[], alias: string): boolean {
  let matched = false;
  for (const rawPattern of patterns) {
    const negated = rawPattern.startsWith('!');
    const pattern = negated ? rawPattern.slice(1) : rawPattern;
    let source = '^';
    for (const char of pattern) {
      if (char === '*') source += '.*';
      else if (char === '?') source += '.';
      else source += char.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
    }
    source += '$';
    // OpenSSH host patterns are case-sensitive. Do not pass the `i` flag:
    // `Host F*` must not match the distinct alias `foo`.
    if (!new RegExp(source).test(alias)) continue;
    if (negated) return false;
    matched = true;
  }
  return matched;
}

/**
 * Cindy deliberately does not execute OpenSSH Match expressions. We only
 * prove a block cannot affect an alias when an `originalhost` criterion
 * excludes it; every other condition remains conservatively possible.
 * Match criteria are ANDed, so one definitely-false originalhost condition
 * is enough to make the whole expression irrelevant to this alias.
 */
function matchExpressionMayApplyToAlias(expression: string, alias: string): boolean {
  const words = splitWords(expression);
  if (words.length === 0) return true;

  for (let index = 0; index < words.length;) {
    const criterion = words[index]!.toLowerCase();
    if (MATCH_NO_ARGUMENT_CRITERIA.has(criterion)) {
      index += 1;
      continue;
    }
    if (!MATCH_ONE_ARGUMENT_CRITERIA.has(criterion)) return true;
    const value = words[index + 1];
    if (value === undefined) return true;
    if (criterion === 'originalhost' && !matchesMatchPatternList(value, alias)) return false;
    index += 2;
  }
  return true;
}

/** Match pattern-lists are comma-separated and may contain negated entries. */
function matchesMatchPatternList(value: string, alias: string): boolean {
  const patterns = value.split(',').filter(Boolean);
  if (patterns.length === 0) return true;

  let hasPositive = false;
  let positiveMatched = false;
  for (const rawPattern of patterns) {
    const negated = rawPattern.startsWith('!');
    const pattern = negated ? rawPattern.slice(1) : rawPattern;
    if (!pattern) return true;
    const matches = matchesHostPattern([pattern], alias);
    if (negated && matches) return false;
    if (!negated) {
      hasPositive = true;
      positiveMatched ||= matches;
    }
  }
  return hasPositive ? positiveMatched : true;
}

function isSupportedIncludeScope(scope: Scope): boolean {
  return scope.kind === 'root'
    || (scope.kind === 'host'
      && scope.declaration.patterns.length === 1
      && scope.declaration.patterns[0] === '*');
}

function parseDirectiveLine(line: string): { keyword: string; value: string } | null {
  if (!line || line.startsWith('#')) return null;
  const match = /^([^\s=#]+)(?:\s*=\s*|\s+)(.*)$/.exec(line);
  if (match) return { keyword: match[1]!.toLowerCase(), value: match[2]!.trim() };
  return { keyword: line.toLowerCase(), value: '' };
}

function splitWords(value: string): string[] {
  const words: string[] = [];
  let word = '';
  let quote: '"' | "'" | null = null;
  const push = (): void => {
    if (!word) return;
    words.push(word);
    word = '';
  };
  for (let index = 0; index < value.length; index += 1) {
    const char = value[index]!;
    if (quote) {
      if (char === quote) quote = null;
      else if (char === '\\'
        && quote === '"'
        && (value[index + 1] === '"' || value[index + 1] === '\\')) {
        word += value[index + 1];
        index += 1;
      } else word += char;
      continue;
    }
    if (char === '#') {
      if (!word) break;
      word += char;
      continue;
    }
    if (char === '"' || char === "'") {
      quote = char;
      continue;
    }
    if (/\s/.test(char)) {
      push();
      continue;
    }
    if (char === '\\' && /[\s#'"\\]/.test(value[index + 1] ?? '')) {
      word += value[index + 1];
      index += 1;
      continue;
    }
    word += char;
  }
  push();
  return words;
}

function firstWordOrRaw(value: string): string {
  return splitWords(value)[0] ?? value.trim();
}

function parseAuthMarker(comment: string): AuthMarker | null {
  const normalized = comment.trim();
  if (normalized === `${AUTH_MARKER_PREFIX}agent`) return 'agent';
  if (normalized === `${AUTH_MARKER_PREFIX}key`) return 'key';
  return null;
}

function hasManagedConfigMarker(raw: string): boolean {
  const firstContentLine = raw.split(/\r?\n/).find((line) => line.trim() !== '');
  return firstContentLine?.trim() === MANAGED_CONFIG_MARKER;
}

function isCanonicalizationDirective(keyword: string): boolean {
  return keyword.startsWith('canonicalize') || keyword === 'canonicaldomains';
}

function isConcreteAlias(alias: string): boolean {
  return !!alias
    && !alias.includes('*')
    && !alias.includes('?')
    && !alias.includes('[')
    && !alias.startsWith('!');
}

interface IdentityFileTokenContext {
  alias: string;
  hostname: string;
  user: string;
  port: number;
  hostKeyAlias?: string;
  proxyJump?: string;
}

type IdentityFileExpansionResult =
  | { filePath: string }
  | { unsupportedToken: string };

/** Expand IdentityFile tokens once using the effective host connection context. */
function expandIdentityFile(
  value: string,
  context: IdentityFileTokenContext,
): IdentityFileExpansionResult {
  const localUser = os.userInfo();
  const localHostname = os.hostname();
  const proxyJump = context.proxyJump ?? '';
  const connectionHash = createHash('sha1').update(
    `${localHostname}${context.hostname}${context.port}${context.user}${proxyJump}`,
  ).digest('hex');
  const replacements: Record<string, string> = {
    '%': '%',
    C: connectionHash,
    d: os.homedir(),
    h: context.hostname,
    i: String(localUser.uid),
    j: proxyJump,
    k: context.hostKeyAlias ?? context.alias,
    L: localHostname.split('.')[0] ?? localHostname,
    l: localHostname,
    n: context.alias,
    p: String(context.port),
    r: context.user,
    u: localUser.username,
  };
  let expanded = '';
  for (let index = 0; index < value.length; index += 1) {
    const char = value[index]!;
    if (char !== '%') {
      expanded += char;
      continue;
    }
    const token = value[index + 1];
    if (token === undefined || replacements[token] === undefined) {
      return { unsupportedToken: token === undefined ? '%' : `%${token}` };
    }
    expanded += replacements[token];
    index += 1;
  }
  expanded = expandHome(expanded);
  // Unlike Include, OpenSSH does not resolve a relative IdentityFile against
  // the config file directory. It remains relative to the ssh process cwd.
  return {
    filePath: path.isAbsolute(expanded) ? expanded : path.resolve(process.cwd(), expanded),
  };
}

async function globPaths(pattern: string): Promise<string[]> {
  const normalized = path.normalize(pattern);
  const root = path.parse(normalized).root;
  const segments = normalized.slice(root.length).split(path.sep).filter(Boolean);
  const start = root || '.';

  const walk = async (directory: string, index: number): Promise<string[]> => {
    if (index >= segments.length) {
      try {
        const stat = await fs.stat(directory);
        return stat.isFile() ? [directory] : [];
      } catch (error) {
        const code = (error as NodeJS.ErrnoException).code;
        if (code === 'ENOENT' || code === 'ENOTDIR') return [];
        throw error;
      }
    }

    const segment = segments[index]!;
    if (!hasGlob(segment)) return walk(path.join(directory, segment), index + 1);

    let entries: string[];
    try {
      entries = (await fs.readdir(directory)).sort((a, b) =>
        Buffer.compare(Buffer.from(a), Buffer.from(b)));
    } catch (error) {
      const code = (error as NodeJS.ErrnoException).code;
      if (code === 'ENOENT' || code === 'ENOTDIR') return [];
      throw error;
    }

    const matches: string[] = [];
    for (const entry of entries) {
      if (entry.startsWith('.') && !segment.startsWith('.')) continue;
      if (path.matchesGlob(entry, segment)) {
        matches.push(...await walk(path.join(directory, entry), index + 1));
      }
    }
    return matches;
  };

  return walk(start, 0);
}

function hasGlob(value: string): boolean {
  return /[*?\[]/.test(value);
}

/** Ensure the main config has one supported, canonical exact Include. */
export async function ensureManagedConfigInclude(
  mainConfigPath: string,
  managedConfigPath: string,
): Promise<void> {
  const managedExisting = await readRawConfig(managedConfigPath);
  if (managedExisting) assertManagedConfigOwnership(managedExisting);
  const existing = await readRawConfig(mainConfigPath);
  const eol = existing.includes('\r\n') ? '\r\n' : '\n';
  const lines = splitLinesKeepingEndings(existing);
  const kept: string[] = [];
  const movedInlineComments: string[] = [];
  let scope: 'root' | 'pure-star' | 'conditional' | 'match' = 'root';

  for (const line of lines) {
    const directive = parseDirectiveLine(line.trim());
    if (directive?.keyword === 'host') {
      const patterns = splitWords(directive.value);
      scope = patterns.length === 1 && patterns[0] === '*' ? 'pure-star' : 'conditional';
    } else if (directive?.keyword === 'match') {
      scope = 'match';
    }

    const supported = scope === 'root' || scope === 'pure-star';
    if (supported
      && directive?.keyword === 'include'
      && await isSingleExactInclude(
        directive.value,
        path.dirname(path.resolve(mainConfigPath)),
        managedConfigPath,
      )) {
      const inlineComment = extractInlineComment(stripLineEnding(line));
      if (inlineComment && !movedInlineComments.includes(inlineComment)) {
        movedInlineComments.push(inlineComment);
      }
      continue;
    }
    kept.push(line);
  }

  let insertionIndex = 0;
  while (insertionIndex < kept.length) {
    const content = stripLineEnding(kept[insertionIndex]!).trim();
    if (content === '' || content.startsWith('#')) insertionIndex += 1;
    else break;
  }
  const [firstInlineComment, ...extraInlineComments] = movedInlineComments;
  const includeLine = `Include ${formatIncludePath(managedConfigPath)}`
    + `${firstInlineComment ? ` ${firstInlineComment}` : ''}${eol}`;
  const preservedExtraComments = extraInlineComments.map((comment) => `${comment}${eol}`);
  kept.splice(insertionIndex, 0, includeLine, ...preservedExtraComments);
  if (insertionIndex > 0 && !/[\r\n]$/.test(kept[insertionIndex - 1]!)) {
    kept[insertionIndex - 1] = `${kept[insertionIndex - 1]}${eol}`;
  }
  const next = kept.join('');
  if (next !== existing) {
    await writeAtomicPreservingTarget(mainConfigPath, next, existing);
  }
}

/** Append a new, single-alias Host block to Cindy's managed file. */
export async function addManagedHost(host: HostConfig, managedConfigPath: string): Promise<void> {
  const existing = await readRawConfig(managedConfigPath);
  const next = prepareManagedHostAdd(host, existing);
  await writeAtomicPreservingTarget(managedConfigPath, next, existing);
}

/**
 * Publish a new managed host without ever making a known-bad managed file
 * reachable from the user's main SSH config.
 */
export async function addManagedHostWithInclude(
  host: HostConfig,
  mainConfigPath: string,
  managedConfigPath: string,
): Promise<ManagedHostAddReceipt> {
  const existing = await readRawConfig(managedConfigPath);
  assertManagedConfigOwnership(existing);
  // Parse and serialize the complete next file before publishing either disk
  // mutation. A malformed pre-existing cindy.conf therefore cannot be exposed
  // by a newly inserted Include.
  const next = prepareManagedHostAdd(host, existing);
  await writeAtomicPreservingTarget(managedConfigPath, next, existing);
  try {
    await ensureManagedConfigInclude(mainConfigPath, managedConfigPath);
  } catch (includeError) {
    // Roll back only if nobody changed the managed file after our atomic write.
    // If it did change, preserving that external edit is safer; both versions
    // are syntactically valid, so the main SSH graph is not poisoned.
    try {
      await restoreManagedConfigIfUnchanged(managedConfigPath, next, existing);
    } catch (rollbackError) {
      throw new AggregateError(
        [includeError, rollbackError],
        'failed to publish managed SSH Include and roll back the staged host',
      );
    }
    throw includeError;
  }
  return {
    rollback: () => restoreManagedConfigIfUnchanged(managedConfigPath, next, existing),
  };
}

/** Update only Cindy-owned connection fields and preserve all other directives. */
export async function updateManagedHostFields(
  host: HostConfig,
  managedConfigPath: string,
  expectedToken: ManagedConfigWriteToken,
): Promise<void> {
  assertManagedWriteToken(expectedToken);
  const existingBytes = await readRawConfigBytes(managedConfigPath);
  assertManagedConfigUnchanged(existingBytes, expectedToken);
  const existing = existingBytes.toString('utf8');
  assertManagedConfigOwnership(existing);
  if (!existing) throw new Error(`managed SSH host not found: ${host.id}`);
  const parsed = SSHConfig.parse(existing) as SshConfigSection[];
  const section = findSingleHostSection(parsed, host.id);
  if (!section?.config) throw new Error(`managed SSH host not found or ambiguous: ${host.id}`);
  projectManagedFields(section, host, existing.includes('\r\n') ? '\r\n' : '\n');
  await writeAtomicPreservingTarget(
    managedConfigPath,
    (parsed as unknown as { toString(): string }).toString(),
    existing,
  );
}

export async function removeManagedHost(
  alias: string,
  managedConfigPath: string,
  expectedToken: ManagedConfigWriteToken,
): Promise<void> {
  assertManagedWriteToken(expectedToken);
  const existingBytes = await readRawConfigBytes(managedConfigPath);
  assertManagedConfigUnchanged(existingBytes, expectedToken);
  const existing = existingBytes.toString('utf8');
  assertManagedConfigOwnership(existing);
  if (!existing) return;
  const parsed = SSHConfig.parse(existing) as SshConfigSection[];
  const matches = parsed.filter((section) => isSingleAliasHostSection(section, alias));
  if (matches.length !== 1) throw new Error(`managed SSH host not found or ambiguous: ${alias}`);
  parsed.splice(parsed.indexOf(matches[0]!), 1);
  await writeAtomicPreservingTarget(
    managedConfigPath,
    (parsed as unknown as { toString(): string }).toString(),
    existing,
  );
}

/** Legacy helpers retained for package callers/tests. Every path is required. */
export async function upsertHost(host: HostConfig, filePath: string): Promise<void> {
  const existing = await readRawConfig(filePath);
  const parsed = SSHConfig.parse(existing) as SshConfigSection[];
  removeHostSections(parsed, host.id);
  const append = SSHConfig.parse(formatHostBlock(host, '\n')) as SshConfigSection[];
  for (const node of append) (parsed as unknown as { push(node: unknown): void }).push(node);
  await writeAtomicPreservingTarget(
    filePath,
    (parsed as unknown as { toString(): string }).toString(),
    existing,
  );
}

export async function updateHostFields(host: HostConfig, filePath: string): Promise<void> {
  const existing = await readRawConfig(filePath);
  if (!existing) return upsertHost(host, filePath);
  const parsed = SSHConfig.parse(existing) as SshConfigSection[];
  const section = findHostSection(parsed, host.id);
  if (!section?.config) return upsertHost(host, filePath);
  projectManagedFields(section, host, existing.includes('\r\n') ? '\r\n' : '\n');
  await writeAtomicPreservingTarget(
    filePath,
    (parsed as unknown as { toString(): string }).toString(),
    existing,
  );
}

export async function removeHost(alias: string, filePath: string): Promise<void> {
  const existing = await readRawConfig(filePath);
  if (!existing) return;
  const parsed = SSHConfig.parse(existing) as SshConfigSection[];
  removeHostSections(parsed, alias);
  await writeAtomicPreservingTarget(
    filePath,
    (parsed as unknown as { toString(): string }).toString(),
    existing,
  );
}

function projectManagedFields(section: SshConfigSection, host: HostConfig, eol: string): void {
  const hasIdentity = !!host.identityFile;
  const desired: Array<[string, string | null]> = [
    ['HostName', host.hostname],
    ['User', host.user],
    ['Port', host.port && host.port !== DEFAULT_PORT ? String(host.port) : null],
    ['IdentityFile', hasIdentity ? host.identityFile! : null],
    ['IdentitiesOnly', hasIdentity ? 'yes' : null],
  ];
  for (const [name, value] of desired) applyDirective(section, name, value, eol);
  // Always persist Cindy's auth choice. Without an agent marker, a managed
  // host with no local IdentityFile would silently become key auth if it
  // inherits an IdentityFile from an earlier Host * block.
  applyAuthMarker(section, host.authMethod, eol);
}

function findAnyHostSection(parsed: SshConfigSection[], alias: string): SshConfigSection | null {
  return parsed.find((section) => isHostDirective(section)
    && directiveValues(section).includes(alias)) ?? null;
}

function findHostSection(parsed: SshConfigSection[], alias: string): SshConfigSection | null {
  return findAnyHostSection(parsed, alias);
}

function findSingleHostSection(parsed: SshConfigSection[], alias: string): SshConfigSection | null {
  const matches = parsed.filter((section) => isSingleAliasHostSection(section, alias));
  return matches.length === 1 ? matches[0]! : null;
}

function isSingleAliasHostSection(section: SshConfigSection, alias: string): boolean {
  const values = directiveValues(section);
  return isHostDirective(section) && values.length === 1 && values[0] === alias;
}

function isHostDirective(section: SshConfigSection): boolean {
  return section.param?.toLowerCase() === 'host';
}

function directiveValues(section: SshConfigSection): string[] {
  const raw = Array.isArray(section.value) ? section.value : [section.value];
  const values: string[] = [];
  for (const item of raw) {
    if (typeof item === 'string') values.push(item);
    else if (item && typeof item.val === 'string') values.push(item.val);
  }
  return values;
}

function removeHostSections(parsed: SshConfigSection[], alias: string): void {
  for (let index = parsed.length - 1; index >= 0; index -= 1) {
    if (isHostDirective(parsed[index]!) && directiveValues(parsed[index]!).includes(alias)) {
      parsed.splice(index, 1);
    }
  }
}

function applyDirective(
  section: SshConfigSection,
  param: string,
  value: string | null,
  eol: string,
): void {
  const children = section.config ?? [];
  const wanted = param.toLowerCase();
  if (value === null) {
    section.config = children.filter((child) => child.param?.toLowerCase() !== wanted);
    return;
  }
  const serialized = serializeSshValue(value);
  let found = false;
  const next: SshConfigSection[] = [];
  for (const child of children) {
    if (child.param?.toLowerCase() === wanted) {
      if (found) continue;
      child.value = serialized.value;
      child.quoted = serialized.quoted || undefined;
      found = true;
    }
    next.push(child);
  }
  if (!found) {
    next.push({
      type: SSH_CONFIG_DIRECTIVE_TYPE,
      before: '  ',
      after: eol,
      param,
      separator: ' ',
      value: serialized.value,
      quoted: serialized.quoted || undefined,
    });
  }
  section.config = next;
}

function applyAuthMarker(
  section: SshConfigSection,
  method: AuthMarker,
  eol: string,
): void {
  const children = section.config ?? [];
  const next = children.filter((child) => !(child.type === SSH_CONFIG_COMMENT_TYPE
    && (child.content ?? '').trim().startsWith(AUTH_MARKER_PREFIX)));
  const identityIndex = next.findIndex((child) => child.param?.toLowerCase() === 'identityfile');
  const marker: SshConfigSection = {
    type: SSH_CONFIG_COMMENT_TYPE,
    before: '  ',
    after: eol,
    content: `${AUTH_MARKER_PREFIX}${method}`,
  };
  next.splice(identityIndex >= 0 ? identityIndex : next.length, 0, marker);
  section.config = next;
}

function formatHostBlock(host: HostConfig, eol: string): string {
  assertManagedAlias(host.id);
  const parsed = SSHConfig.parse(
    `Host ${formatSshArgument(host.id)}${eol}`,
  ) as SshConfigSection[];
  const section = parsed[0];
  if (!section) throw new Error(`failed to construct managed SSH host: ${host.id}`);
  projectManagedFields(section, host, eol);
  return (parsed as unknown as { toString(): string }).toString();
}

function prepareManagedHostAdd(host: HostConfig, existing: string): string {
  const ownedExisting = assertManagedConfigOwnership(existing);
  const parsed = SSHConfig.parse(ownedExisting) as SshConfigSection[];
  if (findAnyHostSection(parsed, host.id)) {
    throw new Error(`host already exists in managed SSH config: ${host.id}`);
  }
  const eol = existing.includes('\r\n') ? '\r\n' : '\n';
  const separator = existing && !existing.endsWith('\n') && !existing.endsWith('\r') ? eol : '';
  const next = `${ownedExisting}${separator}${formatHostBlock(host, eol)}`;
  // The package parser is also the syntax gate used by discovery. Reparse the
  // exact bytes that will be written so escaping changes cannot publish an
  // unreadable managed file.
  SSHConfig.parse(next);
  return next;
}

function assertManagedConfigOwnership(existing: string): string {
  if (!existing.trim()) return `${MANAGED_CONFIG_MARKER}\n`;
  if (!hasManagedConfigMarker(existing)) {
    const error = new Error(
      'existing managed SSH config is not owned by Cindy; add the Cindy ownership marker or choose another file',
    ) as Error & { code?: string };
    error.code = MANAGED_CONFIG_OWNERSHIP_REQUIRED_CODE;
    throw error;
  }
  return existing;
}

async function isSingleExactInclude(
  value: string,
  configDir: string,
  managedConfigPath: string,
): Promise<boolean> {
  const patterns = splitWords(value);
  if (patterns.length !== 1 || hasGlob(patterns[0]!)) return false;
  const expansion = expandIncludePath(patterns[0]!);
  if ('warning' in expansion) return false;
  const expanded = expansion.pattern;
  const resolved = path.isAbsolute(expanded) ? expanded : path.resolve(configDir, expanded);
  return pathsEqual(await comparablePath(resolved), await comparablePath(managedConfigPath));
}

function formatIncludePath(managedConfigPath: string): string {
  const absolute = path.resolve(managedConfigPath);
  const defaultPath = path.resolve(defaultManagedSshConfigPath());
  const value = pathsEqual(absolute, defaultPath) ? '~/.ssh/cindy.conf' : absolute;
  return formatSshArgument(value);
}

function serializeSshValue(value: string): { value: string; quoted: boolean } {
  assertSafeSshValue(value);
  const quoted = value === '' || value.startsWith('#') || /[\s"\\]/.test(value);
  return {
    value: quoted
      ? value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
      : value,
    quoted,
  };
}

function formatSshArgument(value: string): string {
  const serialized = serializeSshValue(value);
  return serialized.quoted ? `"${serialized.value}"` : serialized.value;
}

function assertSafeSshValue(value: string): void {
  if (/[\0\r\n]/.test(value)) {
    throw new Error('SSH config values must not contain NUL or line breaks');
  }
}

function assertManagedAlias(alias: string): void {
  assertSafeSshValue(alias);
  if (!alias
    || /\s/.test(alias)
    || alias.includes('*')
    || alias.includes('?')
    || alias.includes('[')
    || alias.startsWith('!')) {
    throw new Error(`invalid managed SSH alias: ${alias}`);
  }
}

function splitLinesKeepingEndings(value: string): string[] {
  if (!value) return [];
  return value.match(/.*(?:\r\n|\n|\r|$)/g)?.filter(Boolean) ?? [];
}

function stripLineEnding(value: string): string {
  return value.replace(/[\r\n]+$/, '');
}

/** Return an OpenSSH inline comment; token-internal `#` is ordinary text. */
function extractInlineComment(line: string): string | null {
  let quote: '"' | "'" | null = null;
  for (let index = 0; index < line.length; index += 1) {
    const char = line[index]!;
    if (quote) {
      if (char === quote) quote = null;
      else if (char === '\\' && quote === '"') index += 1;
      continue;
    }
    if (char === '\\') {
      index += 1;
      continue;
    }
    if (char === '"' || char === "'") {
      quote = char;
      continue;
    }
    if (char === '#' && (index === 0 || /\s/.test(line[index - 1]!))) {
      return line.slice(index).trimEnd();
    }
  }
  return null;
}

async function readRawConfig(filePath: string): Promise<string> {
  try {
    return await fs.readFile(filePath, 'utf8');
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return '';
    throw error;
  }
}

async function readRawConfigBytes(filePath: string): Promise<Buffer> {
  try {
    return await fs.readFile(filePath);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return Buffer.alloc(0);
    throw error;
  }
}

function managedConfigToken(bytes: Uint8Array): ManagedConfigWriteToken {
  return createHash('sha256').update(bytes).digest('hex') as ManagedConfigWriteToken;
}

function assertManagedWriteToken(
  token: ManagedConfigWriteToken | undefined,
): asserts token is ManagedConfigWriteToken {
  if (typeof token === 'string' && /^[a-f0-9]{64}$/.test(token)) return;
  const error = new Error('managed SSH config write token is required') as Error & { code?: string };
  error.code = MANAGED_CONFIG_WRITE_TOKEN_REQUIRED_CODE;
  throw error;
}

function assertManagedConfigUnchanged(
  currentBytes: Uint8Array,
  expectedToken: ManagedConfigWriteToken,
): void {
  if (managedConfigToken(currentBytes) === expectedToken) return;
  const conflict = new Error(
    'SSH config changed after Cindy validated it; reload before retrying.',
  ) as Error & { code?: string };
  conflict.code = MANAGED_CONFIG_CONCURRENT_MODIFICATION_CODE;
  throw conflict;
}

async function writeAtomicPreservingTarget(
  filePath: string,
  content: string,
  expectedContent: string,
): Promise<void> {
  const requested = path.resolve(filePath);
  let target = requested;
  let existingMode: number | undefined;
  try {
    const lstat = await fs.lstat(requested);
    if (lstat.isSymbolicLink()) target = await fs.realpath(requested);
    const stat = await fs.stat(target);
    existingMode = stat.mode & 0o777;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
    let requestedIsSymlink = false;
    try {
      const lstat = await fs.lstat(requested);
      requestedIsSymlink = lstat.isSymbolicLink();
    } catch (lstatError) {
      if ((lstatError as NodeJS.ErrnoException).code !== 'ENOENT') throw lstatError;
    }
    if (requestedIsSymlink) throw error;
  }

  await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
  const tempPath = path.join(
    path.dirname(target),
    `.${path.basename(target)}.cindy-${process.pid}-${randomBytes(6).toString('hex')}`,
  );
  try {
    await fs.writeFile(tempPath, content, { flag: 'wx', mode: existingMode ?? 0o600 });
    if (existingMode !== undefined) await fs.chmod(tempPath, existingMode);
    if (await readRawConfig(target) !== expectedContent) {
      const conflict = new Error(
        'SSH config changed while Cindy was preparing an update; retry the operation.',
      ) as Error & { code?: string };
      conflict.code = MANAGED_CONFIG_CONCURRENT_MODIFICATION_CODE;
      throw conflict;
    }
    await fs.rename(tempPath, target);
  } catch (error) {
    await fs.unlink(tempPath).catch(() => undefined);
    throw error;
  }
}

async function restoreManagedConfigIfUnchanged(
  managedConfigPath: string,
  publishedContent: string,
  previousContent: string,
): Promise<boolean> {
  if (await readRawConfig(managedConfigPath) !== publishedContent) return false;
  try {
    await writeAtomicPreservingTarget(managedConfigPath, previousContent, publishedContent);
    return true;
  } catch (error) {
    if ((error as { code?: string }).code === MANAGED_CONFIG_CONCURRENT_MODIFICATION_CODE) return false;
    throw error;
  }
}

async function comparablePath(value: string): Promise<string> {
  const absolute = path.resolve(expandHome(value));
  let comparable = absolute;
  try {
    comparable = await fs.realpath(absolute);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
  }
  comparable = path.normalize(comparable);
  return process.platform === 'win32' ? comparable.toLowerCase() : comparable;
}

function pathsEqual(left: string, right: string): boolean {
  return process.platform === 'win32'
    ? left.toLowerCase() === right.toLowerCase()
    : left === right;
}

async function pathExists(value: string): Promise<boolean> {
  try {
    await fs.access(value);
    return true;
  } catch {
    return false;
  }
}

function parseIntSafe(value: string | undefined, fallback: number): number {
  if (!value) return fallback;
  const parsed = Number.parseInt(value, 10);
  return Number.isFinite(parsed) ? parsed : fallback;
}

function limitError(pathName: string, message: string): Error & { code: string; path: string } {
  const error = new Error(message) as Error & { code: string; path: string };
  error.code = 'SSH_CONFIG_LIMIT';
  error.path = pathName;
  return error;
}

function toConfigDiagnostic(filePath: string, error: unknown): SshConfigDiagnostic {
  const code = (error as { code?: string }).code;
  const kind: SshConfigDiagnostic['kind'] = code === 'SSH_CONFIG_LIMIT'
    ? 'limit'
    : code === 'SSH_CONFIG_SYNTAX'
      ? 'syntax'
      : 'io';
  return {
    path: typeof (error as { path?: unknown }).path === 'string'
      ? (error as { path: string }).path
      : filePath,
    kind,
    message: error instanceof Error ? error.message : String(error),
    recoveryHint: kind === 'syntax'
      ? 'Fix the SSH config syntax, then refresh.'
      : kind === 'limit'
        ? 'Reduce Include nesting, file count, or config size, then refresh.'
        : 'Check SSH config permissions and Include paths, then refresh.',
  };
}