@crvouga/dev-fleet 0.6.0 → 0.8.0

package/src/worker-manifest.ts

@@ -0,0 +1,201 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PACKAGE_ROOT } from './package-info';
+import { shellQuote, sshArgs, sshFailure } from './ssh';
+import type { Check, FleetNode, Runner } from './types';
+
+/** What a worker is made of, measured: every installed package and its
+ * version, the tools mise has active, and whether each always-on service is
+ * enabled and running. Two workers built from the same revision have the same
+ * manifest, so its digest proves a rebuild reproduces a machine, and its
+ * difference from a fresh build shows what a long-lived worker gained.
+ */
+export interface WorkerManifest {
+  version: 1;
+  packages: Record<string, string>;
+  tools: Record<string, string>;
+  units: Record<string, string>;
+}
+
+/** The policy a worker's manifest is measured against. */
+interface UbuntuPolicy {
+  packages: Record<string, string>;
+  alwaysOnServices: string[];
+}
+
+export async function ubuntuPolicy(root = PACKAGE_ROOT): Promise<UbuntuPolicy> {
+  return JSON.parse(
+    await readFile(join(root, 'ansible/ubuntu/policy.json'), 'utf8')
+  ) as UbuntuPolicy;
+}
+
+/** A read-only POSIX probe: it lists, and changes nothing. */
+export function manifestProbe(services: string[]): string {
+  const units = services.map(shellQuote).join(' ');
+  return [
+    'export PATH="$HOME/.local/share/mise/shims:$HOME/.local/bin:$PATH"',
+    'echo @packages',
+    "dpkg-query -W -f='${binary:Package}=${Version}\\n' 2>/dev/null",
+    'echo @tools',
+    "mise ls --current --json 2>/dev/null | tr -d '\\n'; echo",
+    'echo @units',
+    `for unit in ${units}; do printf '%s=%s/%s\\n' "$unit" "$(systemctl is-enabled "$unit" 2>/dev/null)" "$(systemctl is-active "$unit" 2>/dev/null)"; done`,
+  ].join('; ');
+}
+
+const sorted = (entries: [string, string][]): Record<string, string> =>
+  Object.fromEntries(entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+
+function pairs(lines: string[]): [string, string][] {
+  return lines
+    .map((line) => line.trim())
+    .filter((line) => line.includes('='))
+    .map((line) => {
+      const at = line.indexOf('=');
+      return [line.slice(0, at), line.slice(at + 1)] as [string, string];
+    });
+}
+
+function tools(line: string | undefined): Record<string, string> {
+  try {
+    const listed = JSON.parse(line ?? '{}') as Record<
+      string,
+      { version?: string }[]
+    >;
+    return sorted(
+      Object.entries(listed).map(([tool, versions]) => [
+        tool,
+        versions
+          .map((entry) => entry.version ?? '')
+          .sort()
+          .join(','),
+      ])
+    );
+  } catch {
+    return {};
+  }
+}
+
+/** The manifest the probe printed. Order never matters: everything is sorted. */
+export function parseManifest(stdout: string): WorkerManifest {
+  const sections: Record<string, string[]> = {};
+  let current = '';
+  for (const line of stdout.split('\n')) {
+    if (/^@[a-z]+$/.test(line.trim())) {
+      current = line.trim().slice(1);
+      sections[current] = [];
+    } else if (current) sections[current]!.push(line);
+  }
+  return {
+    version: 1,
+    packages: sorted(pairs(sections['packages'] ?? [])),
+    tools: tools(sections['tools']?.find((line) => line.trim())),
+    units: sorted(pairs(sections['units'] ?? [])),
+  };
+}
+
+/** The same manifest always has the same digest. */
+export function manifestDigest(manifest: WorkerManifest): string {
+  return createHash('sha256').update(JSON.stringify(manifest)).digest('hex');
+}
+
+export interface ManifestDifference {
+  section: 'packages' | 'tools' | 'units';
+  name: string;
+  expected: string | null;
+  actual: string | null;
+}
+
+/** What `live` has that `reference` does not, lacks, or has otherwise. */
+export function diffManifests(
+  reference: WorkerManifest,
+  live: WorkerManifest
+): ManifestDifference[] {
+  const differences: ManifestDifference[] = [];
+  for (const section of ['packages', 'tools', 'units'] as const) {
+    const names = new Set([
+      ...Object.keys(reference[section]),
+      ...Object.keys(live[section]),
+    ]);
+    for (const name of [...names].sort()) {
+      const expected = reference[section][name] ?? null;
+      const actual = live[section][name] ?? null;
+      if (expected !== actual)
+        differences.push({ section, name, expected, actual });
+    }
+  }
+  return differences;
+}
+
+/** Where a manifest departs from what the policy declares: a pinned package
+ * at another version or missing, an always-on service not enabled and active.
+ */
+export function declaredDifferences(
+  manifest: WorkerManifest,
+  policy: UbuntuPolicy
+): ManifestDifference[] {
+  const differences: ManifestDifference[] = [];
+  for (const [name, version] of Object.entries(policy.packages)) {
+    const actual = manifest.packages[name] ?? null;
+    if (actual !== version)
+      differences.push({
+        section: 'packages',
+        name,
+        expected: version,
+        actual,
+      });
+  }
+  for (const unit of policy.alwaysOnServices) {
+    const actual = manifest.units[unit] ?? null;
+    if (actual !== 'enabled/active')
+      differences.push({
+        section: 'units',
+        name: unit,
+        expected: 'enabled/active',
+        actual,
+      });
+  }
+  return differences;
+}
+
+/** `worker:manifest`: the worker is what a fresh build of the same revision
+ * is (when a reference is given) and what the policy declares.
+ */
+export function manifestCheck(differences: ManifestDifference[]): Check {
+  if (!differences.length)
+    return {
+      id: 'worker:manifest',
+      status: 'pass',
+      summary: 'The worker matches the declared pins and the fresh build.',
+    };
+  const shown = differences
+    .slice(0, 20)
+    .map(
+      (difference) =>
+        `${difference.section}:${difference.name} ${difference.expected ?? 'absent'} -> ${difference.actual ?? 'absent'}`
+    );
+  return {
+    id: 'worker:manifest',
+    status: 'fail',
+    summary: `WORKER_MANIFEST_DRIFT: ${differences.length} difference(s): ${shown.join('; ')}`,
+    remedy: {
+      action:
+        'Something was installed, removed or changed outside fleet-sync. Rebuild the worker (fleet-node-replace) or declare the change in dev-fleet.',
+    },
+  };
+}
+
+/** Measures one worker's manifest over the verified SSH connection. */
+export async function measureManifest(
+  node: FleetNode,
+  run: Runner,
+  policy: UbuntuPolicy
+): Promise<{ manifest: WorkerManifest } | { check: Check }> {
+  const result = await run(
+    [...sshArgs(node), manifestProbe(policy.alwaysOnServices)],
+    { timeoutMs: 60_000 }
+  );
+  if (!result.ok) return { check: sshFailure(result) };
+  return { manifest: parseManifest(result.stdout) };
+}

package/src/worker-policy.ts

@@ -34,33 +34,27 @@ function validCapabilities(value: unknown): boolean {
     REQUIRED.every((item) => value.includes(item))
   );
 }
-function validPolicy(value: Record<string, unknown>): boolean {
+const FIELDS: Record<string, (value: unknown) => boolean> = {
+  requiredCapabilities: validCapabilities,
+  githubLogin: (value) =>
+    typeof value === 'string' && /^[a-zA-Z0-9-]{1,39}$/.test(value),
+  vaultUser: (value) =>
+    typeof value === 'string' && /^[a-zA-Z0-9_.-]{1,64}$/.test(value),
+  toolchain: (value) => value === 'mise.lock',
+  agentProfile: (value) => value === 'proxy',
+  unattendedSudo: (value) => value === true,
+  persistentT3: (value) => value === true,
+  neverSleep: (value) => value === true,
+  toolProfiles: (value) => value === undefined || toolProfiles(value) !== null,
+  tools: (value) => value === undefined || toolNames(value),
+};
+/** The first field of a worker policy that breaks its rule, or null. */
+export function policyFault(value: Record<string, unknown>): string | null {
+  const unknown = Object.keys(value).find((key) => !(key in FIELDS));
+  if (unknown !== undefined) return unknown;
   return (
-    Object.keys(value).every((key) =>
-      [
-        'requiredCapabilities',
-        'githubLogin',
-        'vaultUser',
-        'toolchain',
-        'agentProfile',
-        'unattendedSudo',
-        'persistentT3',
-        'neverSleep',
-        'toolProfiles',
-        'tools',
-      ].includes(key)
-    ) &&
-    validTools(value) &&
-    validCapabilities(value['requiredCapabilities']) &&
-    typeof value['githubLogin'] === 'string' &&
-    /^[a-zA-Z0-9-]{1,39}$/.test(value['githubLogin']) &&
-    typeof value['vaultUser'] === 'string' &&
-    /^[a-zA-Z0-9_.-]{1,64}$/.test(value['vaultUser']) &&
-    value['toolchain'] === 'mise.lock' &&
-    value['agentProfile'] === 'proxy' &&
-    ['unattendedSudo', 'persistentT3', 'neverSleep'].every(
-      (key) => value[key] === true
-    )
+    Object.entries(FIELDS).find(([key, valid]) => !valid(value[key]))?.[0] ??
+    null
   );
 }
 /** A list of known tool profiles, each once; null when it is not one. */
@@ -71,14 +65,6 @@ export function toolProfiles(value: unknown): ToolProfile[] | null {
     ? (value as ToolProfile[])
     : null;
 }
-/** The optional tool profiles and single tools every worker adds. */
-function validTools(value: Record<string, unknown>): boolean {
-  return (
-    (value['toolProfiles'] === undefined ||
-      toolProfiles(value['toolProfiles']) !== null) &&
-    (value['tools'] === undefined || toolNames(value['tools']))
-  );
-}
 function toolNames(value: unknown): boolean {
   return (
     Array.isArray(value) &&
@@ -89,7 +75,7 @@ function toolNames(value: unknown): boolean {
   );
 }
 export function parseWorkerPolicy(value: unknown): WorkerPolicy {
-  if (!record(value) || !validPolicy(value))
+  if (!record(value) || policyFault(value) !== null)
     throw new FleetUsageError(
       'Invalid mandatory worker policy. Workers require the locked toolchain, common services, unattended sudo, persistent T3 and no sleep.'
     );

package/src/worker-seed.ts

@@ -0,0 +1,138 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { parse, stringify } from 'yaml';
+import type { MachineDefinition } from './definition';
+import { FleetUsageError } from './errors';
+import { PACKAGE_ROOT } from './package-info';
+import type { Runner } from './types';
+
+/** What a new worker's first boot needs, and nothing that outlives it: the
+ * worker account with the manager's public key, the privilege rule
+ * fleet-sync expects, a host key generated here so the manager pins it before
+ * the machine ever answers (no trust on first use), and a short-lived,
+ * single-use Tailscale auth key that is deleted once the machine has joined.
+ */
+export interface SeedInput {
+  worker: MachineDefinition;
+  /** The manager's SSH public key: one line of a `.pub` file. */
+  managerKey: string;
+  /** From the secrets provider, by purpose (`tailnet-auth-key`). */
+  authKey: string;
+  /** Generated with ssh-keygen for this seed. */
+  hostKey: { private: string; public: string };
+  /** `tailscale` in ansible/ubuntu/policy.json: version and key digest. */
+  tailscale: { version: string; keySha256: string };
+  /** The codename of the fleet's Ubuntu release, from the Ubuntu policy. */
+  codename: string;
+}
+
+const PUBLIC_KEY =
+  /^(ssh-ed25519|ecdsa-sha2-nistp256|ssh-rsa) [A-Za-z0-9+/=]{16,}( [^\n]*)?$/;
+
+/** The user data of one worker: bootstrap/worker-seed.yaml with every
+ * `${NAME}` filled. Values replace whole placeholders inside parsed strings,
+ * so none of them can change the document's structure.
+ */
+export async function seedUserData(
+  input: SeedInput,
+  root = PACKAGE_ROOT
+): Promise<Record<string, unknown>> {
+  const { worker } = input;
+  const user = worker.network?.user;
+  if (!user)
+    throw new FleetUsageError(
+      `${worker.id} declares no network block; the seed needs its user and Tailscale name.`
+    );
+  if (!PUBLIC_KEY.test(input.managerKey.trim()))
+    throw new FleetUsageError(
+      'The manager public key is not one OpenSSH public key line.'
+    );
+  if (!/^tskey-auth-[A-Za-z0-9-]{8,200}$/.test(input.authKey))
+    throw new FleetUsageError(
+      'The tailnet-auth-key secret is not a Tailscale auth key (tskey-auth-…). Use a short-lived, single-use, tagged key.'
+    );
+  const values: Record<string, string> = {
+    HOSTNAME: worker.network!.tailscaleName.split('.')[0]!,
+    USER: user,
+    MANAGER_KEY: input.managerKey.trim(),
+    HOST_KEY_PRIVATE: input.hostKey.private,
+    HOST_KEY_PUBLIC: input.hostKey.public,
+    AUTH_KEY: input.authKey,
+    TAILSCALE_VERSION: input.tailscale.version,
+    TAILSCALE_KEY_SHA256: input.tailscale.keySha256,
+    CODENAME: input.codename,
+  };
+  const template = parse(
+    await readFile(join(root, 'bootstrap/worker-seed.yaml'), 'utf8')
+  ) as unknown;
+  return fill(template, values) as Record<string, unknown>;
+}
+
+function fill(value: unknown, values: Record<string, string>): unknown {
+  if (typeof value === 'string')
+    return value.replace(/\$\{([A-Z0-9_]+)\}/g, (_, name: string) => {
+      const found = values[name];
+      if (found === undefined)
+        throw new Error(`The seed template names an unknown value ${name}.`);
+      return found;
+    });
+  if (Array.isArray(value)) return value.map((item) => fill(item, values));
+  if (value && typeof value === 'object')
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, fill(item, values)])
+    );
+  return value;
+}
+
+/** Cloud-init user data, or an Ubuntu autoinstall file that carries it. */
+export function renderSeed(
+  userData: Record<string, unknown>,
+  autoinstall: boolean
+): string {
+  const document = autoinstall
+    ? {
+        autoinstall: {
+          version: 1,
+          ssh: { 'install-server': true, 'allow-pw': false },
+          'user-data': userData,
+        },
+      }
+    : userData;
+  return `#cloud-config\n${stringify(document, { lineWidth: 0 })}`;
+}
+
+/** The version and key digest the worker baseline pins for Tailscale. */
+export async function tailscalePins(
+  root = PACKAGE_ROOT
+): Promise<SeedInput['tailscale']> {
+  const policy = JSON.parse(
+    await readFile(join(root, 'ansible/ubuntu/policy.json'), 'utf8')
+  ) as { tailscale: SeedInput['tailscale'] };
+  return policy.tailscale;
+}
+
+/** A new ed25519 host key, generated in a private directory that is removed
+ * afterwards.
+ */
+export async function generateHostKey(
+  id: string,
+  run: Runner
+): Promise<SeedInput['hostKey']> {
+  const directory = await mkdtemp(join(tmpdir(), 'devfleet-seed-'));
+  try {
+    const path = join(directory, 'host');
+    const made = await run(
+      ['ssh-keygen', '-q', '-t', 'ed25519', '-N', '', '-C', id, '-f', path],
+      { timeoutMs: 20_000 }
+    );
+    if (!made.ok)
+      throw new FleetUsageError('ssh-keygen could not make a host key.');
+    return {
+      private: await readFile(path, 'utf8'),
+      public: (await readFile(`${path}.pub`, 'utf8')).trim(),
+    };
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}