@moondeck/station 0.0.1 → 1.0.0

package/lib/enrollment-state.ts

@@ -0,0 +1,251 @@
+/**
+ * Crash-safe local state for first-time host enrollment (ADR-099).
+ *
+ * A host chooses its permanent id/secret before redeeming a one-time cloud
+ * token. Persist that proposal before the request so a lost response or a
+ * process crash can replay the exact same identity. The raw enrollment token
+ * is never written to disk; only its sha256 fingerprint is retained.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import { writeEnvValuesAtomic } from "./env-file";
+import { parseHostCloudEndpoint } from "./host-cloud-url";
+
+const HOST_ID = /^[a-z0-9_-]{1,64}$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+
+export { writeEnvValuesAtomic } from "./env-file";
+
+export interface PendingEnrollment {
+  readonly schemaVersion: 1;
+  readonly enrollmentTokenSha256: string;
+  readonly hostId: string;
+  readonly hostSecret: string;
+  readonly cloudUrl: string;
+  readonly hostName: string;
+  readonly createdAt: number;
+}
+
+export function pendingEnrollmentPath(uaiHome: string): string {
+  return join(uaiHome, ".enrollment-pending.json");
+}
+
+export function enrollmentTokenSha256(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+export function pendingEnrollmentMatches(
+  pending: PendingEnrollment,
+  enrollmentToken: string,
+  cloudUrl: string,
+): boolean {
+  return (
+    pending.enrollmentTokenSha256 === enrollmentTokenSha256(enrollmentToken) &&
+    pending.cloudUrl === cloudUrl
+  );
+}
+
+export function readPendingEnrollment(file: string): PendingEnrollment | null {
+  if (!existsSync(file)) return null;
+  const stat = lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error("pending enrollment state must be a regular file");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    throw new Error("pending enrollment state is malformed");
+  }
+  return validatePendingEnrollment(parsed);
+}
+
+/**
+ * Create the immutable pending proposal without an overwrite race. A complete
+ * 0600 temp file is fsync'd and hard-linked into place, so the durable path is
+ * never observable with partial JSON. If another process won, return its
+ * strictly validated proposal instead.
+ */
+export function ensurePendingEnrollment(
+  file: string,
+  candidate: PendingEnrollment,
+): { pending: PendingEnrollment; created: boolean } {
+  const normalized = validatePendingEnrollment(candidate);
+  const parent = dirname(file);
+  mkdirSync(parent, { recursive: true, mode: 0o700 });
+
+  const existing = readPendingEnrollment(file);
+  if (existing) return { pending: existing, created: false };
+
+  const temporary = join(
+    parent,
+    `.${basename(file)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`,
+  );
+  try {
+    writeDurableFile(temporary, `${JSON.stringify(normalized, null, 2)}\n`, true);
+    try {
+      linkSync(temporary, file);
+      fsyncDirectory(parent);
+      return { pending: normalized, created: true };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const winner = readPendingEnrollment(file);
+      if (!winner) throw new Error("pending enrollment winner disappeared");
+      return { pending: winner, created: false };
+    }
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}
+
+/**
+ * Commit the exact pending identity to dotenv, then remove the journal. The
+ * ordering is intentional: a crash can leave both files, but can never leave
+ * neither. A later invocation can recognize and remove the harmless journal.
+ */
+export function commitPendingEnrollment(
+  pendingFile: string,
+  envFile: string,
+  expected: PendingEnrollment,
+): void {
+  const current = readPendingEnrollment(pendingFile);
+  if (!current || JSON.stringify(current) !== JSON.stringify(expected)) {
+    throw new Error("pending enrollment state changed before commit");
+  }
+  writeEnvValuesAtomic(envFile, {
+    UAI_HOST_ID: expected.hostId,
+    UAI_HOST_TOKEN: expected.hostSecret,
+    UAI_CLOUD_URL: expected.cloudUrl,
+  });
+  removePendingEnrollment(pendingFile);
+}
+
+export function removeCommittedPendingEnrollment(
+  file: string,
+  identity: { hostId: string; hostSecret: string },
+): boolean {
+  const pending = readPendingEnrollment(file);
+  if (!pending) return false;
+  if (
+    pending.hostId !== identity.hostId ||
+    pending.hostSecret !== identity.hostSecret
+  ) {
+    return false;
+  }
+  removePendingEnrollment(file);
+  return true;
+}
+
+/** Deliberate operator reset used only by the existing `setup --force` path. */
+export function discardPendingEnrollment(file: string): void {
+  removePendingEnrollment(file);
+}
+
+function removePendingEnrollment(file: string): void {
+  try {
+    unlinkSync(file);
+    fsyncDirectory(dirname(file));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+function writeDurableFile(file: string, body: string, exclusive: boolean): void {
+  const descriptor = openSync(file, exclusive ? "wx" : "w", 0o600);
+  try {
+    writeFileSync(descriptor, body, "utf8");
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  chmodSync(file, 0o600);
+}
+
+function fsyncDirectory(directory: string): void {
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(directory, "r");
+    fsyncSync(descriptor);
+  } catch (error) {
+    // Some platforms/filesystems do not permit fsync on a directory. The file
+    // itself was still fsync'd before rename/link; do not make enrollment
+    // unusable solely because the directory durability primitive is absent.
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EISDIR") throw error;
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+function validatePendingEnrollment(value: unknown): PendingEnrollment {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("pending enrollment state must be an object");
+  }
+  const object = value as Record<string, unknown>;
+  const expected = [
+    "schemaVersion",
+    "enrollmentTokenSha256",
+    "hostId",
+    "hostSecret",
+    "cloudUrl",
+    "hostName",
+    "createdAt",
+  ];
+  if (
+    Object.keys(object).sort().join("\0") !== expected.sort().join("\0") ||
+    object.schemaVersion !== 1 ||
+    typeof object.enrollmentTokenSha256 !== "string" ||
+    !SHA256.test(object.enrollmentTokenSha256) ||
+    typeof object.hostId !== "string" ||
+    !HOST_ID.test(object.hostId) ||
+    typeof object.hostSecret !== "string" ||
+    !SHA256.test(object.hostSecret) ||
+    typeof object.cloudUrl !== "string" ||
+    object.cloudUrl.length < 1 ||
+    object.cloudUrl.length > 2_048 ||
+    typeof object.hostName !== "string" ||
+    object.hostName.length > 128 ||
+    typeof object.createdAt !== "number" ||
+    !Number.isSafeInteger(object.createdAt) ||
+    object.createdAt <= 0
+  ) {
+    throw new Error("pending enrollment state is invalid");
+  }
+  let canonicalCloudUrl: string;
+  try {
+    canonicalCloudUrl = parseHostCloudEndpoint(object.cloudUrl).bridgeUrl;
+  } catch {
+    throw new Error("pending enrollment state is invalid");
+  }
+  if (canonicalCloudUrl !== object.cloudUrl) {
+    throw new Error("pending enrollment state is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    enrollmentTokenSha256: object.enrollmentTokenSha256,
+    hostId: object.hostId,
+    hostSecret: object.hostSecret,
+    cloudUrl: object.cloudUrl,
+    hostName: object.hostName,
+    createdAt: object.createdAt,
+  };
+}

package/lib/env-file.ts

@@ -0,0 +1,246 @@
+/**
+ * Durable `.env.local` updates shared by every host-side settings writer.
+ *
+ * A mutation is a read/merge/fsync/rename operation, so concurrent writers
+ * must serialize the entire transition rather than only the final rename.
+ * `serializeEnvFileMutation` is the process-wide boundary used by remote host
+ * config today and interactive engine-login persistence later (ADR-100).
+ */
+
+import { randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+
+const ENV_KEY = /^[A-Z][A-Z0-9_]*$/;
+const mutationTails = new Map<string, Promise<void>>();
+
+export interface EnvFileSnapshot {
+  readonly exists: boolean;
+  readonly body: string;
+}
+
+/**
+ * Queue one complete mutation for an env file. A failed predecessor never
+ * poisons the queue, and the tail is removed once the last waiter settles.
+ */
+export function serializeEnvFileMutation<T>(
+  file: string,
+  operation: () => T | Promise<T>,
+): Promise<T> {
+  const key = resolve(file);
+  const predecessor = mutationTails.get(key) ?? Promise.resolve();
+  const running = predecessor.catch(() => undefined).then(operation);
+  const settled = running.then(
+    () => undefined,
+    () => undefined,
+  );
+  mutationTails.set(key, settled);
+  void settled.finally(() => {
+    if (mutationTails.get(key) === settled) mutationTails.delete(key);
+  });
+  return running;
+}
+
+/** Atomically merge all supplied values into one durable 0600 dotenv file. */
+export function writeEnvValuesAtomic(
+  file: string,
+  updates: Readonly<Record<string, string>>,
+): void {
+  const entries = Object.entries(updates);
+  if (entries.length === 0) return;
+  for (const [key, value] of entries) {
+    if (!ENV_KEY.test(key)) throw new Error(`invalid environment key: ${key}`);
+    if (value.includes("\0") || value.includes("\n") || value.includes("\r")) {
+      throw new Error(`environment value for ${key} contains a line break`);
+    }
+  }
+
+  const keys = new Set(entries.map(([key]) => key));
+  const current = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const kept = current
+    .split(/\r?\n/)
+    .filter((line, index, lines) => {
+      if (index === lines.length - 1 && line === "") return false;
+      const equals = line.indexOf("=");
+      return equals <= 0 || !keys.has(line.slice(0, equals));
+    });
+  for (const [key, value] of entries) kept.push(`${key}=${value}`);
+  replaceEnvFileAtomic(file, `${kept.join("\n")}\n`);
+}
+
+/**
+ * Atomically drop `keys` from a dotenv file (a missing file or key is fine).
+ * The sign-in box (ADR-136) strips engine credentials from `.env.local` at
+ * start so no default-slot secret survives on that machine.
+ */
+export function removeEnvValuesAtomic(
+  file: string,
+  keys: readonly string[],
+): string[] {
+  if (keys.length === 0 || !existsSync(file)) return [];
+  assertEnvKeys(keys);
+  const { body, removed } = withoutEnvKeys(readFileSync(file, "utf8"), keys);
+  if (removed.length > 0) replaceEnvFileAtomic(file, body);
+  return removed;
+}
+
+/**
+ * `body` without the lines that set any of `keys`, and the keys it dropped.
+ * A line sets a key as every writer here writes one: `KEY=value`, the key at
+ * the start of its own line. Pure, so that a caller that reads the file its
+ * own way (the cutover purge, which must not trust what it opens) drops
+ * exactly the lines `removeEnvValuesAtomic` would. With nothing dropped,
+ * `body` comes back as it was.
+ */
+export function withoutEnvKeys(
+  body: string,
+  keys: readonly string[],
+): { body: string; removed: string[] } {
+  assertEnvKeys(keys);
+  const drop = new Set(keys);
+  const removed: string[] = [];
+  const kept = body.split(/\r?\n/).filter((line, index, lines) => {
+    if (index === lines.length - 1 && line === "") return false;
+    const equals = line.indexOf("=");
+    if (equals <= 0) return true;
+    const key = line.slice(0, equals);
+    if (!drop.has(key)) return true;
+    removed.push(key);
+    return false;
+  });
+  if (removed.length === 0) return { body, removed: [] };
+  return {
+    body: kept.length === 0 ? "" : `${kept.join("\n")}\n`,
+    removed: [...new Set(removed)],
+  };
+}
+
+/**
+ * The keys among `keys` whose line, as withoutEnvKeys finds it, opens a
+ * quoted value that it does not close: a value that runs on past its line,
+ * of which dropping that line would leave the rest. Read by this rule
+ * alone, not by any parser's notion of what a quoted value may hold, so it
+ * says the same under every Node: the value, its leading spaces aside,
+ * starts with `"`, `'` or a backtick, and no unescaped same quote follows on
+ * its line (a backslash takes the character after it).
+ */
+export function keysQuotedPastTheirLine(body: string, keys: readonly string[]): string[] {
+  assertEnvKeys(keys);
+  const wanted = new Set(keys);
+  const found = new Set<string>();
+  for (const line of body.split(/\r?\n/)) {
+    const equals = line.indexOf("=");
+    if (equals <= 0) continue;
+    const key = line.slice(0, equals);
+    if (!wanted.has(key)) continue;
+    const value = line.slice(equals + 1).trimStart();
+    const quote = value[0];
+    if (quote !== '"' && quote !== "'" && quote !== "`") continue;
+    let closed = false;
+    for (let index = 1; index < value.length && !closed; index += 1) {
+      if (value[index] === "\\") index += 1;
+      else closed = value[index] === quote;
+    }
+    if (!closed) found.add(key);
+  }
+  return [...found];
+}
+
+function assertEnvKeys(keys: readonly string[]): void {
+  for (const key of keys) {
+    if (!ENV_KEY.test(key)) throw new Error(`invalid environment key: ${key}`);
+  }
+}
+
+/** Capture the exact bytes needed to roll back a multi-store config write. */
+export function readEnvFileSnapshot(file: string): EnvFileSnapshot {
+  return existsSync(file)
+    ? { exists: true, body: readFileSync(file, "utf8") }
+    : { exists: false, body: "" };
+}
+
+/** Restore a prior snapshot durably. Successful replacements remain 0600. */
+export function restoreEnvFileSnapshotAtomic(
+  file: string,
+  snapshot: EnvFileSnapshot,
+): void {
+  if (snapshot.exists) {
+    replaceEnvFileAtomic(file, snapshot.body);
+    return;
+  }
+  try {
+    unlinkSync(file);
+    fsyncDirectory(dirname(file));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+/** Write `body` to `file` so a crash or power loss leaves either the old
+ *  file or the new one, never a torn or empty one: fsync the data, rename,
+ *  then fsync the directory. 0600, parent created 0700. */
+export function writeDurableFileAtomic(file: string, body: string): void {
+  replaceEnvFileAtomic(file, body);
+}
+
+function replaceEnvFileAtomic(file: string, body: string): void {
+  const parent = dirname(file);
+  mkdirSync(parent, { recursive: true, mode: 0o700 });
+  const temporary = joinTemporary(parent, basename(file));
+  try {
+    writeDurableFile(temporary, body);
+    renameSync(temporary, file);
+    chmodSync(file, 0o600);
+    fsyncDirectory(parent);
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}
+
+function joinTemporary(parent: string, name: string): string {
+  return resolve(
+    parent,
+    `.${name}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`,
+  );
+}
+
+function writeDurableFile(file: string, body: string): void {
+  const descriptor = openSync(file, "wx", 0o600);
+  try {
+    writeFileSync(descriptor, body, "utf8");
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  chmodSync(file, 0o600);
+}
+
+function fsyncDirectory(directory: string): void {
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(directory, "r");
+    fsyncSync(descriptor);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EISDIR") {
+      throw error;
+    }
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}