feat(adopt): confirm the installed node's fingerprint in the adopt wizard (#143)

After the node installs and reboots, the manager pauses the adoption on
the awaiting-fingerprint-confirmation phase with the certificate the
installed node presents. The wizard shows that fingerprint in readable
pairs to compare with the Mgmt SHA-256 line on the node's console, and
offers a confirm action (ConfirmAdoptionFingerprint) or a cancel that
ends the stream so nothing is trusted or recorded. Mock mode pauses the
same way so the flow can be tried offline.

Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
Co-authored-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>

Author: Bugs5382

src/lib/adopt.test.ts

@@ -18,7 +18,13 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 
 import type { MachineConfig } from "@/gen/fleet/cryptos/v1/config_pb";
 
-import { adoptNode, previewAdoption } from "@/lib/adopt";
+import {
+  adoptNode,
+  confirmAdoptionFingerprint,
+  fingerprintsMatch,
+  formatFingerprint,
+  previewAdoption,
+} from "@/lib/adopt";
 import * as clientMod from "@/lib/fleet/client";
 import * as modeMod from "@/lib/fleet/mode";
 
@@ -48,17 +54,58 @@ describe("adopt (mock mode)", () => {
     for await (const step of adoptNode("host:9000", "AB:CD", config)) {
       phases.push(step.phase);
       final = step.done;
+      if (step.phase === "awaiting-fingerprint-confirmation") {
+        await confirmAdoptionFingerprint(step.adoptionId, step.presentedCertSha256);
+      }
     }
     expect(phases).toEqual([
       "applying-config",
       "installing",
       "awaiting-reboot",
+      "awaiting-fingerprint-confirmation",
       "ceremony",
       "established",
     ]);
     expect(final).toBe(true);
   });
 
+  it("pauses on the installed node's fingerprint until it is confirmed", async () => {
+    vi.spyOn(modeMod, "fleetMode").mockReturnValue("mock");
+    const iter = adoptNode("host:9000", "AB:CD", config);
+    let step = (await iter.next()).value;
+    while (step && step.phase !== "awaiting-fingerprint-confirmation") {
+      step = (await iter.next()).value;
+    }
+    expect(step?.adoptionId).not.toBe("");
+    expect(step?.presentedCertSha256).toMatch(/^[0-9a-f]{64}$/);
+
+    let resumed = false;
+    const next = iter.next().then((r) => {
+      resumed = true;
+      return r;
+    });
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    expect(resumed).toBe(false);
+
+    await confirmAdoptionFingerprint(step!.adoptionId, step!.presentedCertSha256.toUpperCase());
+    expect((await next).value?.phase).toBe("ceremony");
+    await iter.return(undefined);
+  });
+
+  it("fails the mock adoption on a mismatched fingerprint", async () => {
+    vi.spyOn(modeMod, "fleetMode").mockReturnValue("mock");
+    const iter = adoptNode("host:9000", "AB:CD", config);
+    let step = (await iter.next()).value;
+    while (step && step.phase !== "awaiting-fingerprint-confirmation") {
+      step = (await iter.next()).value;
+    }
+    const next = iter.next();
+    await expect(confirmAdoptionFingerprint(step!.adoptionId, "00".repeat(32))).rejects.toThrow(
+      /does not match/i,
+    );
+    await expect(next).rejects.toThrow(/does not match/i);
+  });
+
   it("refuses to adopt without a confirmed fingerprint", async () => {
     vi.spyOn(modeMod, "fleetMode").mockReturnValue("mock");
     const iter = adoptNode("host:9000", "", config);
@@ -90,6 +137,73 @@ describe("adopt (live mode)", () => {
     expect(seen).toEqual(["applying-config", "established"]);
   });
 
+  it("relays the adoption ID and the presented fingerprint", async () => {
+    vi.spyOn(modeMod, "fleetMode").mockReturnValue("live");
+    vi.spyOn(clientMod, "fleetClient").mockReturnValue({
+      adoptNode: vi.fn().mockReturnValue(
+        (async function* () {
+          yield {
+            adoptionId: "adopt-1",
+            detail: "",
+            done: false,
+            phase: "awaiting-fingerprint-confirmation",
+            presentedCertSha256: "ab".repeat(32),
+          };
+        })(),
+      ),
+    } as unknown as ReturnType<typeof clientMod.fleetClient>);
+
+    const seen = [];
+    for await (const step of adoptNode("host:9000", "AB:CD", config)) seen.push(step);
+
+    expect(seen).toEqual([
+      {
+        adoptionId: "adopt-1",
+        detail: "",
+        done: false,
+        phase: "awaiting-fingerprint-confirmation",
+        presentedCertSha256: "ab".repeat(32),
+      },
+    ]);
+  });
+
+  it("passes the stop signal to the adoption stream", async () => {
+    vi.spyOn(modeMod, "fleetMode").mockReturnValue("live");
+    const adoptNodeRpc = vi.fn().mockReturnValue((async function* () {})());
+    vi.spyOn(clientMod, "fleetClient").mockReturnValue({
+      adoptNode: adoptNodeRpc,
+    } as unknown as ReturnType<typeof clientMod.fleetClient>);
+    const controller = new AbortController();
+
+    for await (const _ of adoptNode("host:9000", "AB:CD", config, controller.signal)) {
+      // drain
+    }
+
+    expect(adoptNodeRpc).toHaveBeenCalledWith(expect.anything(), { signal: controller.signal });
+  });
+
+  it("sends the confirmed fingerprint for the adoption", async () => {
+    vi.spyOn(modeMod, "fleetMode").mockReturnValue("live");
+    const confirm = vi.fn().mockResolvedValue({});
+    vi.spyOn(clientMod, "fleetClient").mockReturnValue({
+      confirmAdoptionFingerprint: confirm,
+    } as unknown as ReturnType<typeof clientMod.fleetClient>);
+
+    await confirmAdoptionFingerprint("adopt-1", "ab".repeat(32));
+
+    expect(confirm).toHaveBeenCalledWith({ adoptionId: "adopt-1", certSha256: "ab".repeat(32) });
+  });
+
+  it("surfaces a live confirm refusal", async () => {
+    vi.spyOn(modeMod, "fleetMode").mockReturnValue("live");
+    vi.spyOn(clientMod, "fleetClient").mockReturnValue({
+      confirmAdoptionFingerprint: vi.fn().mockRejectedValue(new Error("fingerprint mismatch")),
+    } as unknown as ReturnType<typeof clientMod.fleetClient>);
+    await expect(confirmAdoptionFingerprint("adopt-1", "ab".repeat(32))).rejects.toThrow(
+      /mismatch/,
+    );
+  });
+
   it("surfaces a live preview error (no silent fallback)", async () => {
     vi.spyOn(modeMod, "fleetMode").mockReturnValue("live");
     vi.spyOn(clientMod, "fleetClient").mockReturnValue({
@@ -98,3 +212,17 @@ describe("adopt (live mode)", () => {
     await expect(previewAdoption("host:9000")).rejects.toThrow(/unreachable/);
   });
 });
+
+describe("fingerprint helpers", () => {
+  it("compares fingerprints ignoring case, colons and spaces", () => {
+    expect(fingerprintsMatch("AB:CD:EF", "abcdef")).toBe(true);
+    expect(fingerprintsMatch(" ab cd ef ", "AB:CD:EF")).toBe(true);
+    expect(fingerprintsMatch("abcdef", "abcde0")).toBe(false);
+    expect(fingerprintsMatch("", "")).toBe(false);
+  });
+
+  it("groups a fingerprint in colon-separated uppercase pairs for reading", () => {
+    expect(formatFingerprint("abcdef01")).toBe("AB:CD:EF:01");
+    expect(formatFingerprint("AB:CD")).toBe("AB:CD");
+  });
+});

src/lib/adopt.ts

@@ -21,11 +21,13 @@ import { type InstallDisk, InstallDiskSchema } from "@/gen/fleet/cryptos/v1/node
 import { fleetClient } from "@/lib/fleet/client";
 import { fleetMode } from "@/lib/fleet/mode";
 
-// Adopt-a-new-node (S10). The web drives two manager RPCs: PreviewAdoption
-// (unary, trust-on-first-use fingerprint) and AdoptNode (server-streaming,
-// live phase progress). The web never contacts the maintenance node directly
-// and never sends any secret to an unpinned endpoint -- the manager holds the
-// pin and orchestrates the whole apply -> install -> reboot -> ceremony flow.
+// Adopt-a-new-node (S10). The web drives three manager RPCs: PreviewAdoption
+// (unary, trust-on-first-use fingerprint), AdoptNode (server-streaming, live
+// phase progress) and ConfirmAdoptionFingerprint (unary, confirms the
+// installed node's certificate while the stream waits). The web never contacts
+// the maintenance node directly and never sends any secret to an unpinned
+// endpoint -- the manager holds the pin and orchestrates the whole apply ->
+// install -> reboot -> confirm -> ceremony flow.
 
 // AdoptionPreview is the maintenance node's presented identity the operator
 // confirms before adoption proceeds.
@@ -36,14 +38,71 @@ export interface AdoptionPreview {
 
 // AdoptPhase is one streamed step of the orchestration. `done` marks the final
 // message; the phase string is one of the manager's documented phases
-// (applying-config, installing, awaiting-reboot, ceremony, established) or an
-// error phase when a step fails.
+// (applying-config, installing, awaiting-reboot,
+// awaiting-fingerprint-confirmation, ceremony, established,
+// awaiting-certificate) or an error phase when a step fails. adoptionId names
+// the run; presentedCertSha256 is set only while the manager waits for the
+// installed node's fingerprint to be confirmed.
 export interface AdoptPhase {
+  adoptionId: string;
   detail: string;
   done: boolean;
   phase: string;
+  presentedCertSha256: string;
 }
 
+export const AWAITING_FINGERPRINT = "awaiting-fingerprint-confirmation";
+
+const normalizeFingerprint = (fp: string): string => fp.replaceAll(/[\s:]/g, "").toLowerCase();
+
+// fingerprintsMatch compares two SHA-256 fingerprints the way the manager
+// does: case, colons and whitespace are ignored.
+export const fingerprintsMatch = (a: string, b: string): boolean => {
+  const na = normalizeFingerprint(a);
+  return na !== "" && na === normalizeFingerprint(b);
+};
+
+// formatFingerprint renders a fingerprint as colon-separated uppercase pairs,
+// easier to read against the node console than one long hex run.
+export const formatFingerprint = (fp: string): string =>
+  (normalizeFingerprint(fp).match(/.{1,2}/g) ?? []).join(":").toUpperCase();
+
+// The mock adoption's installed-node fingerprint, and the confirmations it is
+// waiting for, keyed by adoption ID.
+const MOCK_INSTALLED_SHA256 = "5f".repeat(32);
+const mockWaiting = new Map<string, { reject: (e: Error) => void; resolve: () => void }>();
+let mockAdoptions = 0;
+
+// confirmAdoptionFingerprint tells the manager the operator checked the
+// installed node's fingerprint against its console, so the paused adoption
+// continues on the AdoptNode stream. A mismatch is refused by the manager and
+// the adoption fails; the error propagates to the caller.
+export const confirmAdoptionFingerprint = async (
+  adoptionId: string,
+  certSha256: string,
+): Promise<void> => {
+  if (!adoptionId || !certSha256) {
+    throw new Error("An adoption and a fingerprint are required.");
+  }
+  if (fleetMode() === "mock") {
+    const waiting = mockWaiting.get(adoptionId);
+    if (!waiting) {
+      throw new Error(`No adoption ${adoptionId} is waiting for a fingerprint.`);
+    }
+    mockWaiting.delete(adoptionId);
+    if (!fingerprintsMatch(certSha256, MOCK_INSTALLED_SHA256)) {
+      const mismatch = new Error(
+        "The confirmed fingerprint does not match the node's certificate.",
+      );
+      waiting.reject(mismatch);
+      throw mismatch;
+    }
+    waiting.resolve();
+    return;
+  }
+  await fleetClient().confirmAdoptionFingerprint({ adoptionId, certSha256 });
+};
+
 // previewAdoption fetches the maintenance node's certificate fingerprint and
 // subject so the operator can confirm it (TOFU). `mock` returns a stable
 // canned preview so the wizard is exercisable offline; live surfaces a
@@ -140,6 +199,7 @@ export async function* adoptNode(
   endpoint: string,
   pinnedCertSha256: string,
   config: MachineConfig,
+  signal?: AbortSignal,
 ): AsyncGenerator<AdoptPhase> {
   const trimmed = endpoint.trim();
   if (!trimmed) {
@@ -155,35 +215,65 @@ export async function* adoptNode(
     // script coherent with the role so the offline demo matches the live flow.
     const kind = config.role?.kind ?? "";
     const subordinate = kind !== "" && kind !== "root";
+    mockAdoptions += 1;
+    const adoptionId = `mock-adoption-${mockAdoptions}`;
+    const step = (phase: string, detail: string, done = false): AdoptPhase => ({
+      adoptionId,
+      detail,
+      done,
+      phase,
+      presentedCertSha256: phase === AWAITING_FINGERPRINT ? MOCK_INSTALLED_SHA256 : "",
+    });
     const common: AdoptPhase[] = [
-      { detail: "Applying the initial machine config.", done: false, phase: "applying-config" },
-      { detail: "Installing the CryptOS runtime.", done: false, phase: "installing" },
-      { detail: "Waiting for the node to reboot.", done: false, phase: "awaiting-reboot" },
+      step("applying-config", "Applying the initial machine config."),
+      step("installing", "Installing the CryptOS runtime."),
+      step("awaiting-reboot", "Waiting for the node to reboot."),
+      step(AWAITING_FINGERPRINT, "Confirm the node's Mgmt SHA-256 from its console."),
     ];
     const scripted: AdoptPhase[] = subordinate
       ? [
           ...common,
-          {
-            detail: "Subordinate provisioned; awaiting a parent-signed certificate.",
-            done: true,
-            phase: "awaiting-certificate",
-          },
+          step(
+            "awaiting-certificate",
+            "Subordinate provisioned; awaiting a parent-signed certificate.",
+            true,
+          ),
         ]
       : [
           ...common,
-          { detail: "Running the enrollment ceremony.", done: false, phase: "ceremony" },
-          { detail: "Node established and linked to the fleet.", done: true, phase: "established" },
+          step("ceremony", "Running the enrollment ceremony."),
+          step("established", "Node established and linked to the fleet.", true),
         ];
-    for (const step of scripted) {
+    for (const s of scripted) {
       // A short delay makes the mock progress visibly step through phases.
       await new Promise((resolve) => setTimeout(resolve, 150));
-      yield step;
+      if (s.phase === AWAITING_FINGERPRINT) {
+        const confirmed = new Promise<void>((resolve, reject) => {
+          mockWaiting.set(adoptionId, { reject, resolve });
+        });
+        // Keep a mismatch that nobody is awaiting yet from surfacing as an
+        // unhandled rejection; it still rejects the await below.
+        confirmed.catch(() => undefined);
+        yield s;
+        await confirmed;
+        continue;
+      }
+      yield s;
     }
     return;
   }
 
-  const stream = fleetClient().adoptNode({ config, endpoint: trimmed, pinnedCertSha256 });
+  const request = { config, endpoint: trimmed, pinnedCertSha256 };
+  const stream = signal
+    ? fleetClient().adoptNode(request, { signal })
+    : fleetClient().adoptNode(request);
   for await (const message of stream) {
-    yield { detail: message.detail, done: message.done, phase: message.phase };
+    yield {
+      adoptionId: message.adoptionId,
+      detail: message.detail,
+      done: message.done,
+      phase: message.phase,
+      presentedCertSha256: message.presentedCertSha256,
+    };
   }
 }

src/lib/wire-fields.test.ts

@@ -18,6 +18,7 @@ import { type DescMessage, fromJson, type JsonValue, toJson } from "@bufbuild/pr
 import { describe, expect, it } from "vitest";
 
 import {
+  AdoptNodeResponseSchema,
   ApprovalSchema,
   AuditEventSchema as FleetAuditEventSchema,
   McpKeySchema,
@@ -37,6 +38,15 @@ const roundTrip = (schema: DescMessage, wire: JsonValue): JsonValue =>
   toJson(schema, fromJson(schema, wire, { ignoreUnknownFields: true }));
 
 describe("generated stubs keep every field the node sends", () => {
+  it("keeps the adoption ID and the presented fingerprint on an adoption message", () => {
+    const wire = {
+      adoptionId: "adopt-1",
+      phase: "awaiting-fingerprint-confirmation",
+      presentedCertSha256: "5f".repeat(32),
+    };
+    expect(roundTrip(AdoptNodeResponseSchema, wire)).toEqual(wire);
+  });
+
   it("keeps network nameservers and search domains on a MachineConfig", () => {
     const wire = {
       apiVersion: "cryptos.dev/v1alpha1",