@ornncompute/cli 0.2.24 → 1.0.34

package/src/admin-enrollment.mjs

@@ -0,0 +1,681 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+
+import { CliApiError, resolveInstallerBaseUrl } from "./api-client.mjs";
+import { AtomicOutputExistsError, writeAtomicOutput } from "./atomic-output.mjs";
+import { ADMIN_MUTATION_SAFETY, AdminMutationError, runAdminMutation } from "./admin-mutations.mjs";
+
+const SECRET_OUTPUT = new Set(["tokens.create", "nodes.rotate-key"]);
+const ENROLLMENT_LOG_POLL_MS = 750;
+const ENROLLMENT_LOG_READ_TIMEOUT_MS = 5_000;
+
+const USAGE = {
+  "tokens.create":
+    "Usage: ornn admin enrollment-tokens create --supplier UUID --expires-in SECONDS (--print | --output PATH) [--overwrite] [--yes]",
+  "tokens.revoke":
+    "Usage: ornn admin enrollment-tokens revoke <token-id> [--expected-created-at TIME] [--yes] [--idempotency-key KEY]",
+  "nodes.enroll":
+    "Usage: ornn admin nodes enroll <node-id> --host HOST --supplier UUID --facility UUID [--filter COMPARTMENT_IDS] --identity-file PATH --token-ttl SECONDS --replace-existing-management [--verbose] [--yes]",
+  "nodes.export-key":
+    "Usage: ornn admin nodes export-key <node-id> (--print | --output PATH) [--overwrite]",
+  "nodes.rotate-key":
+    "Usage: ornn admin nodes rotate-key <node-id> (--print | --output PATH) [--overwrite] [--yes]",
+};
+
+function parseOptions(argv, { booleans = [], positionals, values }, usage) {
+  const options = {};
+  const positionalValues = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (!argument.startsWith("--")) {
+      positionalValues.push(argument);
+      continue;
+    }
+    const separator = argument.indexOf("=");
+    const name = argument.slice(2, separator === -1 ? undefined : separator);
+    if (booleans.includes(name)) {
+      if (separator !== -1 || options[name] !== undefined) {
+        throw new AdminMutationError(
+          `${usage}\n--${name} does not accept a value and may be supplied only once.`,
+          {
+            field: name,
+          }
+        );
+      }
+      options[name] = true;
+      continue;
+    }
+    if (!values.includes(name)) {
+      throw new AdminMutationError(`${usage}\nUnknown option: --${name}`);
+    }
+    const value = separator === -1 ? argv[index + 1] : argument.slice(separator + 1);
+    if (!value || (separator === -1 && value.startsWith("--"))) {
+      throw new AdminMutationError(`${usage}\n--${name} requires a value.`, { field: name });
+    }
+    if (options[name] !== undefined) {
+      throw new AdminMutationError(`${usage}\n--${name} may be supplied only once.`, {
+        field: name,
+      });
+    }
+    options[name] = value;
+    if (separator === -1) index += 1;
+  }
+  if (positionalValues.length !== positionals) throw new AdminMutationError(usage);
+  return { options, positionals: positionalValues };
+}
+
+function required(options, name, usage) {
+  const value = options[name]?.trim();
+  if (!value) throw new AdminMutationError(`${usage}\n--${name} is required.`, { field: name });
+  return value;
+}
+
+function uuid(value, name) {
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
+    throw new AdminMutationError(`${name} must be a canonical UUID.`, { field: name });
+  }
+  return value.toLowerCase();
+}
+
+function boundedInteger(value, name, minimum, maximum) {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+    throw new AdminMutationError(`--${name} must be an integer from ${minimum} to ${maximum}.`, {
+      field: name,
+    });
+  }
+  return parsed;
+}
+
+function secretExport(options, usage) {
+  const print = options.print === true;
+  const output = options.output?.trim();
+  if (print === Boolean(output)) {
+    throw new AdminMutationError(`${usage}\nChoose exactly one of --print or --output PATH.`, {
+      field: "output",
+    });
+  }
+  if (options.overwrite && !output) {
+    throw new AdminMutationError(`${usage}\n--overwrite requires --output PATH.`, {
+      field: "overwrite",
+    });
+  }
+  return { output, overwrite: options.overwrite === true, print };
+}
+
+function parseTokenCreate(argv) {
+  const usage = USAGE["tokens.create"];
+  const { options } = parseOptions(
+    argv,
+    {
+      booleans: ["overwrite", "print", "yes"],
+      positionals: 0,
+      values: ["supplier", "expires-in", "output"],
+    },
+    usage
+  );
+  return {
+    input: {
+      organization_id: uuid(required(options, "supplier", usage), "supplier"),
+      expires_in_seconds: boundedInteger(
+        required(options, "expires-in", usage),
+        "expires-in",
+        60,
+        86_400
+      ),
+      export: secretExport(options, usage),
+    },
+    mutation: {
+      safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+      yes: options.yes === true,
+    },
+  };
+}
+
+function parseTokenRevoke(argv) {
+  const usage = USAGE["tokens.revoke"];
+  const { options, positionals } = parseOptions(
+    argv,
+    { booleans: ["yes"], positionals: 1, values: ["expected-created-at", "idempotency-key"] },
+    usage
+  );
+  return {
+    input: {
+      token_id: uuid(positionals[0], "token-id"),
+      ...(options["expected-created-at"]?.trim()
+        ? { expected_created_at: options["expected-created-at"].trim() }
+        : {}),
+      ...(options["idempotency-key"]?.trim()
+        ? { idempotency_key: options["idempotency-key"].trim() }
+        : {}),
+    },
+    mutation: {
+      idempotencyKey: options["idempotency-key"]?.trim(),
+      safety: ADMIN_MUTATION_SAFETY.reconcile,
+      yes: options.yes === true,
+    },
+  };
+}
+
+function parseNodeEnroll(argv) {
+  const usage = USAGE["nodes.enroll"];
+  const { options, positionals } = parseOptions(
+    argv,
+    {
+      booleans: ["replace-existing-management", "verbose", "yes"],
+      positionals: 1,
+      values: [
+        "facility",
+        "filter",
+        "host",
+        "identity-file",
+        "port",
+        "supplier",
+        "token-ttl",
+        "username",
+      ],
+    },
+    usage
+  );
+  const filter = options.filter?.trim();
+  if (!options["replace-existing-management"]) {
+    throw new AdminMutationError(
+      `${usage}\n--replace-existing-management is required and cannot be inferred by --yes.`,
+      {
+        field: "replace-existing-management",
+      }
+    );
+  }
+  return {
+    input: {
+      node_id: uuid(positionals[0], "node-id"),
+      host: required(options, "host", usage),
+      organization_id: uuid(required(options, "supplier", usage), "supplier"),
+      facility_id: uuid(required(options, "facility", usage), "facility"),
+      ...(filter ? { filter } : {}),
+      identity_file: required(options, "identity-file", usage),
+      expires_in_seconds: boundedInteger(
+        required(options, "token-ttl", usage),
+        "token-ttl",
+        60,
+        86_400
+      ),
+      username: options.username?.trim() || "root",
+      port: options.port ? boundedInteger(options.port, "port", 1, 65_535) : 22,
+      replace_existing_management: true,
+      verbose: options.verbose === true,
+    },
+    mutation: {
+      safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+      yes: options.yes === true,
+    },
+  };
+}
+
+function parseNodeKey(argv, rotate) {
+  const capabilityId = rotate ? "nodes.rotate-key" : "nodes.export-key";
+  const usage = USAGE[capabilityId];
+  const { options, positionals } = parseOptions(
+    argv,
+    {
+      booleans: rotate ? ["overwrite", "print", "yes"] : ["overwrite", "print"],
+      positionals: 1,
+      values: ["output"],
+    },
+    usage
+  );
+  return {
+    input: {
+      node_id: uuid(positionals[0], "node-id"),
+      export: secretExport(options, usage),
+    },
+    ...(rotate
+      ? {
+          mutation: {
+            safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+            yes: options.yes === true,
+          },
+        }
+      : {}),
+  };
+}
+
+function text(value, fallback = "") {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+function safeTokenMetadata(payload) {
+  return {
+    id: text(payload?.id) || null,
+    organization_id: text(payload?.organization_id) || null,
+    status: text(payload?.status, "active"),
+    expires_at: text(payload?.expires_at) || null,
+    created_at: text(payload?.created_at) || null,
+  };
+}
+
+function secretMaterial(capabilityId, payload) {
+  if (capabilityId === "tokens.create") {
+    return text(payload?.token) || text(payload?.plaintext);
+  }
+  const key = payload?.private_key;
+  if (typeof key !== "string" || !key.length) return "";
+  // OpenSSH rejects otherwise valid private keys without a terminating newline.
+  return key.endsWith("\n") ? key : `${key}\n`;
+}
+
+function keyMetadata(input, payload) {
+  return {
+    node_id: input.node_id,
+    fingerprint: text(payload?.fingerprint) || null,
+    ...(typeof payload?.host_dispatched === "boolean"
+      ? { host_dispatched: payload.host_dispatched }
+      : {}),
+  };
+}
+
+function secretFingerprint(content) {
+  return `SHA256:${createHash("sha256").update(content).digest("base64url")}`;
+}
+
+async function refuseExistingOutput(options) {
+  if (!options.output || options.overwrite) return;
+  try {
+    await lstat(options.output);
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  throw new AdminMutationError(
+    `Refusing to overwrite ${options.output}. Re-run with --overwrite to replace it deliberately.`,
+    { code: "output_exists", field: "output" }
+  );
+}
+
+async function exportSecret({ capabilityId, input, options, payload, stdout }) {
+  const material = secretMaterial(capabilityId, payload);
+  if (!material) {
+    throw new CliApiError("The owner did not return exportable secret material.", {
+      detail: { code: "secret_material_unavailable", retryable: false },
+      status: 502,
+    });
+  }
+  const metadata =
+    capabilityId === "tokens.create"
+      ? { token_metadata: safeTokenMetadata(payload) }
+      : { node_key: keyMetadata(input, payload) };
+  if (options.print) {
+    stdout.write(material);
+    return { raw: true, data: null };
+  }
+  try {
+    const output = await writeAtomicOutput(options.output, material, {
+      mode: 0o600,
+      overwrite: options.overwrite,
+    });
+    return {
+      raw: false,
+      data: {
+        ...metadata,
+        output: {
+          path: output.path,
+          mode: "0600",
+          fingerprint:
+            capabilityId === "tokens.create"
+              ? secretFingerprint(material)
+              : text(payload?.fingerprint) || secretFingerprint(material),
+        },
+      },
+    };
+  } catch (error) {
+    if (error instanceof AtomicOutputExistsError) {
+      throw new AdminMutationError(
+        `Refusing to overwrite ${options.output}. Re-run with --overwrite to replace it deliberately.`,
+        { code: "output_exists", field: "output" }
+      );
+    }
+    throw error;
+  }
+}
+
+function reviewFor(capabilityId, input, prepared) {
+  if (capabilityId === "tokens.create") {
+    return {
+      title: "Create enrollment token",
+      fields: [
+        { label: "Supplier", value: input.organization_id },
+        { label: "Expires in", value: `${input.expires_in_seconds} seconds` },
+        {
+          label: "Secret destination",
+          value: input.export.print ? "stdout (--print)" : input.export.output,
+        },
+      ],
+      consequence: "Creates a bearer credential that can enroll a node until it expires.",
+    };
+  }
+  if (capabilityId === "tokens.revoke") {
+    const target = prepared?.target;
+    return {
+      title: "Revoke enrollment token",
+      fields: [
+        { label: "Token", value: input.token_id },
+        { label: "Created", value: target?.created_at ?? input.expected_created_at ?? "absent" },
+        { label: "Supplier", value: target?.organization_id ?? "unknown" },
+        { label: "Expires", value: target?.expires_at ?? "unknown" },
+      ],
+      consequence: "Prevents this exact token generation from enrolling another node.",
+    };
+  }
+  if (capabilityId === "nodes.enroll") {
+    return {
+      title: "Enroll node",
+      fields: [
+        { label: "Node", value: input.node_id },
+        { label: "SSH target", value: `${input.username}@${input.host}:${input.port}` },
+        { label: "Supplier", value: input.organization_id },
+        { label: "Facility", value: input.facility_id },
+        ...(input.filter
+          ? [{ label: "Compartment filter", value: input.filter }]
+          : []),
+        { label: "Token lifetime", value: `${input.expires_in_seconds} seconds` },
+      ],
+      consequence:
+        "Replaces existing Ornn management and claims this host for the stated assignment.",
+    };
+  }
+  return {
+    title: "Rotate node admin key",
+    fields: [
+      { label: "Node", value: input.node_id },
+      {
+        label: "Secret destination",
+        value: input.export.print ? "stdout (--print)" : input.export.output,
+      },
+    ],
+    consequence:
+      "Revokes access through the previous private key and dispatches the replacement public key.",
+  };
+}
+
+async function enrollmentIdentityInput(input) {
+  try {
+    const privateKey = await readFile(input.identity_file, "utf8");
+    if (!privateKey.trim()) {
+      throw new Error("file is empty");
+    }
+    return {
+      ...input,
+      installer_base: resolveInstallerBaseUrl({ env: input.env }) ?? undefined,
+      private_key: privateKey,
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new AdminMutationError(`Could not read --identity-file: ${reason}`, {
+      code: "identity_file_unreadable",
+      field: "identity-file",
+    });
+  }
+}
+
+function enrollmentRuns(payload) {
+  if (!payload || typeof payload !== "object") return [];
+  if (Array.isArray(payload.logs)) return payload.logs;
+  return Array.isArray(payload.runs) ? payload.runs : [];
+}
+
+function redactEnrollmentText(value, secrets) {
+  let text = typeof value === "string" ? value : String(value ?? "");
+  for (const secret of secrets) {
+    if (!secret) continue;
+    text = text.replaceAll(secret, "[redacted]");
+    text = text.replaceAll(encodeURIComponent(secret), "[redacted]");
+  }
+  return text;
+}
+
+function freshEnrollmentLogLines(payload, tokenId, secrets, seen) {
+  const session = enrollmentRuns(payload).find((candidate) => candidate?.token_id === tokenId);
+  if (!session || typeof session !== "object") return [];
+  const compartments = Array.isArray(session.compartments) ? session.compartments : [];
+  const total = Number.isInteger(session.progress_total)
+    ? session.progress_total
+    : compartments.length;
+  const lines = [];
+  for (const [index, compartment] of compartments.entries()) {
+    if (!compartment || typeof compartment !== "object") continue;
+    const id = String(compartment.id ?? index);
+    const numericId = Number(id);
+    const current = Number.isInteger(numericId) ? numericId + 1 : session.progress_index;
+    const title =
+      typeof compartment.title === "string" && compartment.title ? compartment.title : `Step ${id}`;
+    const state = typeof compartment.state === "string" ? compartment.state : "";
+    const stateKey = `${id}:state:${state}`;
+    if (state && !seen.has(stateKey)) {
+      seen.add(stateKey);
+      lines.push(`[enroll ${current}/${total}] ${title}: ${state}`);
+    }
+    const output = Array.isArray(compartment.output) ? compartment.output : [];
+    for (const [outputIndex, entry] of output.entries()) {
+      const stream =
+        entry && typeof entry === "object" && typeof entry.stream === "string"
+          ? entry.stream
+          : "stdout";
+      const seq =
+        entry && typeof entry === "object" && Number.isInteger(entry.seq) ? entry.seq : outputIndex;
+      const key = `${id}:output:${seq}:${stream}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const raw = entry && typeof entry === "object" ? entry.text : entry;
+      const text = redactEnrollmentText(raw, secrets);
+      if (text) lines.push(`  ${stream === "stderr" ? "[stderr] " : ""}${text}`);
+    }
+  }
+  return lines;
+}
+
+function enrollmentProgressTransport(fetch, runtime, privateKey) {
+  let tokenId = "";
+  const secrets = [privateKey];
+  const seen = new Set();
+  const request = (path, init = {}) =>
+    fetch(
+      path,
+      init.signal === undefined && runtime.signal ? { ...init, signal: runtime.signal } : init
+    );
+
+  return async (path, init = {}) => {
+    if (path === "/enrollment-tokens") {
+      const minted = await request(path, init);
+      if (minted && typeof minted === "object") {
+        tokenId = typeof minted.id === "string" ? minted.id : "";
+        const token =
+          typeof minted.token === "string"
+            ? minted.token
+            : typeof minted.plaintext === "string"
+              ? minted.plaintext
+              : "";
+        if (token) secrets.push(token);
+      }
+      return minted;
+    }
+    if (path !== "/internal/remote" || !tokenId) return request(path, init);
+
+    const remote = request(path, init).then(
+      (value) => ({ ok: true, value }),
+      (error) => ({ error, ok: false })
+    );
+    let stopped = false;
+    let timer;
+    let currentPoll = Promise.resolve();
+    const poll = async () => {
+      try {
+        const payload = await fetch("/internal/enrollment-logs", {
+          method: "GET",
+          signal: AbortSignal.timeout(ENROLLMENT_LOG_READ_TIMEOUT_MS),
+        });
+        const lines = freshEnrollmentLogLines(payload, tokenId, secrets, seen);
+        for (const line of lines) runtime.stderr.write(`${line}\n`);
+      } catch {
+        // Progress is best-effort; the authoritative remote request still determines success.
+      }
+    };
+    const schedule = () => {
+      timer = setTimeout(() => {
+        currentPoll = poll().finally(() => {
+          if (!stopped) schedule();
+        });
+      }, ENROLLMENT_LOG_POLL_MS);
+    };
+
+    await poll();
+    schedule();
+    const result = await remote;
+    stopped = true;
+    clearTimeout(timer);
+    await currentPoll;
+    await poll();
+    if (!result.ok) throw result.error;
+    return result.value;
+  };
+}
+
+function assertSecretOutputContext(input, runtime) {
+  if (input.export?.print && runtime.formatProvided) {
+    throw new AdminMutationError("--print cannot be combined with --format.", {
+      code: "print_format_conflict",
+      field: "print",
+    });
+  }
+}
+
+async function runNodeKeyExport({ capability, execute, input, runtime }) {
+  assertSecretOutputContext(input, runtime);
+  await refuseExistingOutput(input.export);
+  const payload = await execute(input);
+  const exported = await exportSecret({
+    capabilityId: capability.id,
+    input,
+    options: input.export,
+    payload,
+    stdout: runtime.stdout,
+  });
+  return {
+    ...exported,
+    exitCode: 0,
+    outcome: { class: "ready", phase: "complete" },
+    status: "complete",
+  };
+}
+
+async function runEnrollmentMutation({ capability, execute, fetch, input, mutation, runtime }) {
+  const capabilityId = capability.id;
+  if (SECRET_OUTPUT.has(capabilityId)) {
+    assertSecretOutputContext(input, runtime);
+    await refuseExistingOutput(input.export);
+  }
+  if (capabilityId === "tokens.revoke" && runtime.machine && !input.expected_created_at) {
+    throw new AdminMutationError(
+      "Machine revocation requires --expected-created-at from the listed token generation.",
+      { code: "exact_token_identity_required", field: "expected-created-at" }
+    );
+  }
+
+  const execution = await runAdminMutation({
+    ...runtime,
+    ...mutation,
+    stdout: runtime.stderr ?? runtime.stdout,
+    prepare: async () => {
+      if (capabilityId === "tokens.revoke") {
+        const prepared = await execute(input);
+        return {
+          review: reviewFor(capabilityId, input, prepared),
+          value: {
+            ...input,
+            expected_created_at: prepared.target?.created_at ?? input.expected_created_at,
+            prepared,
+          },
+        };
+      }
+      return { review: reviewFor(capabilityId, input), value: input };
+    },
+    reconcile:
+      capabilityId === "tokens.revoke"
+        ? async (value) => {
+            if (value.prepared.disposition === "satisfied") {
+              return {
+                status: "satisfied",
+                data: {
+                  id: value.token_id,
+                  created_at: value.expected_created_at ?? null,
+                  status: "revoked",
+                  reconciled: true,
+                },
+              };
+            }
+            if (value.prepared.disposition === "conflict") {
+              return {
+                status: "conflict",
+                code: "token_identity_changed",
+                message: value.prepared.message,
+              };
+            }
+            return { status: "apply" };
+          }
+        : undefined,
+    execute: async (value) => {
+      const executionInput =
+        capabilityId === "nodes.enroll"
+          ? await enrollmentIdentityInput({ ...value, env: runtime.env })
+          : value;
+      const transport =
+        capabilityId === "nodes.enroll" && executionInput.verbose
+          ? enrollmentProgressTransport(fetch, runtime, executionInput.private_key)
+          : undefined;
+      return execute(executionInput, { confirmed: true, transport });
+    },
+  });
+
+  if (execution.status === "declined") return { ...execution, suppressResult: true };
+  if (!SECRET_OUTPUT.has(capabilityId)) return execution;
+  const exported = await exportSecret({
+    capabilityId,
+    input,
+    options: input.export,
+    payload: execution.data,
+    stdout: runtime.stdout,
+  });
+  return { ...execution, ...exported };
+}
+
+export const adminEnrollmentHandlers = [
+  {
+    capabilityId: "tokens.create",
+    parse: parseTokenCreate,
+    run: runEnrollmentMutation,
+    safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+  },
+  {
+    capabilityId: "tokens.revoke",
+    parse: parseTokenRevoke,
+    run: runEnrollmentMutation,
+    safety: ADMIN_MUTATION_SAFETY.reconcile,
+  },
+  {
+    capabilityId: "nodes.enroll",
+    parse: parseNodeEnroll,
+    run: runEnrollmentMutation,
+    safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+  },
+  {
+    capabilityId: "nodes.export-key",
+    parse: (argv) => parseNodeKey(argv, false),
+    run: runNodeKeyExport,
+    safety: null,
+  },
+  {
+    capabilityId: "nodes.rotate-key",
+    parse: (argv) => parseNodeKey(argv, true),
+    run: runEnrollmentMutation,
+    safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+  },
+];