@mp-lb/arcnet 0.1.0 → 0.2.1

package/src/secrets/createSecretsCommands.ts

@@ -0,0 +1,206 @@
+import { Command } from "commander";
+import { realpathSync } from "node:fs";
+import { readSecretsConfig } from "./config.js";
+import { loadSecrets } from "./loadSecrets.js";
+import { provisionSource, type ProvisionOptions } from "./provisionSource.js";
+import { runWithSecrets } from "./runWithSecrets.js";
+import { selectSecrets } from "./selectSecrets.js";
+import { syncSecrets } from "./syncSecrets.js";
+import { writeSecretsWorkflow } from "./writeSecretsWorkflow.js";
+import { promptPassword } from "./promptPassword.js";
+
+export const createSecretsCommands = (
+  cli: Command,
+  output: (value: unknown) => void,
+) => {
+  const env = cli
+    .command("env")
+    .description(
+      "Load ordered encrypted Forum sources and select environment values.",
+    );
+
+  for (const action of ["check", "export", "run"] as const) {
+    const command = env
+      .command(action)
+      .description(
+        {
+          check: "Validate decryption and mappings; report key names only.",
+          export:
+            "Write selected plaintext JSON to stdout for an explicit pipeline.",
+          run: "Run a command with selected keys only; withhold child output.",
+        }[action],
+      )
+      .option(
+        "--config <file>",
+        "Secrets source configuration",
+        ".arcnet/secrets.json",
+      )
+      .option("--consumer <name>", "Named mapping in the secrets configuration")
+      .option(
+        "--live",
+        "Fetch current ciphertext through the installed fm CLI instead of snapshots",
+      )
+      .option(
+        "--password",
+        "Prompt for the Forum encryption password locally instead of using file keys",
+      );
+
+    if (action === "run")
+      command.argument("<command...>", "Executable and arguments after --");
+    command.action(async (...args: unknown[]) => {
+      const options = command.opts<{
+        config: string;
+        consumer?: string;
+        live?: boolean;
+        password?: boolean;
+      }>();
+
+      const root = realpathSync(cli.opts().root);
+      const config = readSecretsConfig(root, options.config);
+      if (
+        process.env.GITHUB_ACTIONS === "true" &&
+        (process.env.GITHUB_REPOSITORY !== config.repository ||
+          process.env.GITHUB_REF !== "refs/heads/main")
+      )
+        throw new Error(
+          "Secrets commands in CI require the configured repository main branch.",
+        );
+      if (options.password && process.env.GITHUB_ACTIONS === "true")
+        throw new Error("Password decryption is local-only; CI must use file keys.");
+      if (action !== "check" && !options.consumer)
+        throw new Error("Choose --consumer to explicitly select output keys.");
+      const password = options.password
+        ? await promptPassword(Boolean(cli.opts().noninteractive))
+        : undefined;
+      const values = await loadSecrets(
+        config,
+        root,
+        process.env,
+        options.live,
+        password,
+      );
+
+      const names = options.consumer
+        ? [options.consumer]
+        : Object.keys(config.consumers);
+
+      const selected = Object.fromEntries(
+        names.map((name) => [name, selectSecrets(values, config, name)]),
+      );
+
+      if (action === "export")
+        process.stdout.write(
+          JSON.stringify(selected[options.consumer!]) + "\n",
+        );
+      else if (action === "run")
+        output(
+          runWithSecrets(
+            args[0] as string[],
+            selected[options.consumer!]!,
+            root,
+          ),
+        );
+      else
+        output({
+          operation: "env.check",
+          status: "passed",
+          sources: config.sources.map((source) => source.name),
+          consumers: Object.fromEntries(
+            Object.entries(selected).map(([name, value]) => [
+              name,
+              Object.keys(value),
+            ]),
+          ),
+          message:
+            "Decryption, merge and required-key checks passed; provider authorization was not tested.",
+        });
+    });
+  }
+
+  const secrets = cli
+    .command("secrets")
+    .description(
+      "Attach Forum files, provision GitHub keys and refresh encrypted snapshots.",
+    );
+
+  for (const mode of ["add", "init"] as const) {
+    const command = secrets
+      .command(mode)
+      .description(
+        mode === "add"
+          ? "Attach an existing Forum file and provision its CI key."
+          : "Create a Forum secrets file, prompt for your password and provision its CI key.",
+      )
+      .requiredOption(
+        "--name <name>",
+        "Unique source name; sources merge in installation order",
+      )
+      .requiredOption("--store <workspace/store>", "Forum store")
+      .requiredOption("--path <path>", "Encrypted file path in Forum")
+      .requiredOption(
+        "--key-env <name>",
+        "GitHub repository secret / environment variable for this file's key",
+      )
+      .requiredOption(
+        "--repository <owner/repo>",
+        "GitHub repository receiving the key",
+      )
+      .option(
+        "--config <file>",
+        "Secrets source configuration",
+        ".arcnet/secrets.json",
+      );
+
+    if (mode === "add")
+      command.option(
+        "--existing-key",
+        "Reuse an existing GitHub secret without creating a recipient",
+      );
+    else
+      command.option(
+        "--input <file>",
+        "Initial plaintext JSON file; defaults to an empty object",
+      );
+    command.action(async () =>
+      output(
+        await provisionSource(
+          mode,
+          {
+            ...command.opts<ProvisionOptions>(),
+            noninteractive: cli.opts().noninteractive,
+          },
+          realpathSync(cli.opts().root),
+          command.opts().config,
+        ),
+      ),
+    );
+  }
+
+  secrets
+    .command("sync")
+    .description(
+      "Refresh encrypted snapshots from Forum and regenerate validation CI; no decryption.",
+    )
+    .option(
+      "--config <file>",
+      "Secrets source configuration",
+      ".arcnet/secrets.json",
+    )
+    .action((options: { config: string }) => {
+      const root = realpathSync(cli.opts().root);
+
+      const result = syncSecrets(
+        readSecretsConfig(root, options.config),
+        root,
+        options.config,
+      );
+
+      writeSecretsWorkflow(
+        readSecretsConfig(root, options.config),
+        root,
+        options.config,
+      );
+
+      output(result);
+    });
+};

package/src/secrets/loadSecrets.ts

@@ -0,0 +1,69 @@
+import { decryptForumEncryptedFileText } from "@mp-lb/forum-secrets";
+import { createHash } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { safeTargetPath } from "../safeTargetPath.js";
+import type { SecretsConfig } from "./config.js";
+import { readRemoteSource } from "./readRemoteSource.js";
+import { secretCommand } from "./secretCommand.js";
+
+export const loadSecrets = async (
+  config: SecretsConfig,
+  root: string,
+  environment = process.env,
+  live = false,
+  password?: string,
+) => {
+  let values: Record<string, unknown> = {};
+
+  for (const source of config.sources) {
+    const key = environment[source.keyEnv];
+    if (!key && !password)
+      throw new Error(`Missing decryption credential: ${source.keyEnv}.`);
+
+    try {
+      const text =
+        !live && source.snapshot
+          ? readFileSync(safeTargetPath(root, source.snapshot.file), "utf8")
+          : readRemoteSource(source, root, environment).text;
+
+      if (
+        !live &&
+        source.snapshot &&
+        createHash("sha256").update(text).digest("hex") !==
+          source.snapshot.sha256
+      )
+        throw new Error("Snapshot integrity mismatch");
+
+      let plaintext: string;
+      if (password) {
+        const temporary = mkdtempSync(join(tmpdir(), "arcnet-decrypt-"));
+        try {
+          const file = join(temporary, "source.json.enc");
+          writeFileSync(file, text, { mode: 0o600 });
+          plaintext = secretCommand("fm", ["decrypt", "--file", file], root,
+            undefined, { ...environment, DOCTRINE_ENCRYPTION_PASSWORD: password });
+        } finally {
+          rmSync(temporary, { recursive: true, force: true });
+        }
+      } else {
+        plaintext = await decryptForumEncryptedFileText({
+          encryptedText: text,
+          recipientSecret: key!,
+        });
+      }
+      const decoded: unknown = JSON.parse(plaintext);
+
+      if (!decoded || Array.isArray(decoded) || typeof decoded !== "object")
+        throw new Error("Not an object");
+      values = { ...values, ...decoded };
+    } catch {
+      throw new Error(
+        `Source ${source.name} failed to load or decrypt; check its key and snapshot integrity (values omitted).`,
+      );
+    }
+  }
+
+  return values;
+};

package/src/secrets/promptPassword.ts

@@ -0,0 +1,46 @@
+export const promptPassword = async (
+  noninteractive = false,
+): Promise<string> => {
+  if (process.env.DOCTRINE_ENCRYPTION_PASSWORD)
+    return process.env.DOCTRINE_ENCRYPTION_PASSWORD;
+  if (noninteractive || !process.stdin.isTTY || !process.stderr.isTTY)
+    throw new Error(
+      "Run this command in your terminal to enter the Forum encryption password, or set DOCTRINE_ENCRYPTION_PASSWORD.",
+    );
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const input = process.stdin;
+    const wasRaw = input.isRaw;
+
+    const finish = (cancel = false) => {
+      input.off("data", read);
+      input.setRawMode(wasRaw);
+      input.pause();
+      process.stderr.write("\n");
+      if (cancel || !value) reject(new Error("Password entry cancelled."));
+      else resolve(value);
+    };
+
+    const read = (chunk: Buffer) => {
+      for (const character of chunk.toString("utf8")) {
+        if (character === "\u0003") {
+          finish(true);
+          return;
+        }
+
+        if (character === "\r" || character === "\n") {
+          finish();
+          return;
+        }
+
+        if (character === "\u007f") value = [...value].slice(0, -1).join("");
+        else value += character;
+      }
+    };
+
+    process.stderr.write("Forum encryption password: ");
+    input.setRawMode(true);
+    input.on("data", read);
+    input.resume();
+  });
+};

package/src/secrets/provisionSource.ts

@@ -0,0 +1,238 @@
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { safeTargetPath } from "../safeTargetPath.js";
+import {
+  readSecretsConfig,
+  secretsConfigSchema,
+  sourceSchema,
+} from "./config.js";
+import { promptPassword } from "./promptPassword.js";
+import { secretCommand } from "./secretCommand.js";
+import { readRemoteSource } from "./readRemoteSource.js";
+import { syncSecrets } from "./syncSecrets.js";
+import { writeSecretsWorkflow } from "./writeSecretsWorkflow.js";
+import { assertNewSource } from "./assertNewSource.js";
+
+export interface ProvisionOptions {
+  name: string;
+  store: string;
+  path: string;
+  keyEnv: string;
+  repository: string;
+  existingKey?: boolean;
+  input?: string;
+  noninteractive?: boolean;
+}
+
+export const provisionSource = async (
+  mode: "add" | "init",
+  options: ProvisionOptions,
+  root: string,
+  configFile: string,
+) => {
+  if (configFile !== ".arcnet/secrets.json")
+    throw new Error(
+      "Provisioning uses .arcnet/secrets.json so generated CI has a fixed entry point.",
+    );
+  if (process.env.GITHUB_ACTIONS === "true")
+    throw new Error(
+      "Provision secrets from an authorized local terminal, not CI.",
+    );
+
+  const source = sourceSchema.parse({
+    name: options.name,
+    store: options.store,
+    path: options.path.startsWith("/") ? options.path : `/${options.path}`,
+    keyEnv: options.keyEnv,
+  });
+
+  const configPath = safeTargetPath(root, configFile);
+
+  const config = existsSync(configPath)
+    ? readSecretsConfig(root, configFile)
+    : {
+        version: 1 as const,
+        repository: options.repository,
+        sources: [],
+        consumers: {},
+      };
+
+  if (config.repository !== options.repository)
+    throw new Error("Repository differs from secrets configuration.");
+  const prior = config.sources.find((entry) => entry.name === source.name);
+
+  if (prior) {
+    if (
+      prior.store !== source.store ||
+      prior.path !== source.path ||
+      prior.keyEnv !== source.keyEnv
+    )
+      throw new Error("Source name already has different settings.");
+    return {
+      operation: `secrets.${mode}`,
+      status: "unchanged",
+      message:
+        "Source is already configured; use secrets sync to refresh snapshots.",
+    };
+  }
+
+  const next = secretsConfigSchema.parse({
+    ...config,
+    sources: [...config.sources, source],
+  });
+
+  const known = JSON.parse(
+    secretCommand(
+      "gh",
+      ["secret", "list", "--repo", config.repository, "--json", "name"],
+      root,
+    ),
+  ) as { name: string }[];
+
+  if (
+    options.existingKey &&
+    !known.some((entry) => entry.name === source.keyEnv)
+  )
+    throw new Error("The named GitHub repository secret does not exist.");
+  if (
+    !options.existingKey &&
+    known.some((entry) => entry.name === source.keyEnv)
+  )
+    throw new Error(
+      "GitHub secret already exists; use --existing-key to reuse it without overwriting.",
+    );
+  if (mode === "init" && options.existingKey)
+    throw new Error(
+      "A new encrypted file needs a new recipient; omit --existing-key.",
+    );
+  const original = mode === "add" ? readRemoteSource(source, root) : undefined;
+  if (mode === "init") assertNewSource(source, root);
+  const temporary = mkdtempSync(join(tmpdir(), "arcnet-secrets-"));
+
+  try {
+    if (!options.existingKey) {
+      const password = await promptPassword(options.noninteractive);
+      const env = { ...process.env, DOCTRINE_ENCRYPTION_PASSWORD: password };
+      const ciphertext = join(temporary, "source.json.enc");
+      if (mode === "init") {
+        const plaintext = options.input
+          ? readFileSync(options.input, "utf8")
+          : "{}";
+
+        try {
+          const data: unknown = JSON.parse(plaintext);
+          if (!data || Array.isArray(data) || typeof data !== "object")
+            throw new Error();
+        } catch {
+          throw new Error(
+            "Initial secrets must be a JSON object (values omitted).",
+          );
+        }
+
+        const input = join(temporary, "input.json");
+        writeFileSync(input, plaintext, { mode: 0o600 });
+        writeFileSync(
+          ciphertext,
+          secretCommand(
+            "fm",
+            ["encrypt", "--file", input],
+            root,
+            undefined,
+            env,
+          ),
+          { mode: 0o600 },
+        );
+      } else writeFileSync(ciphertext, original!.text, { mode: 0o600 });
+
+      const recipientText = secretCommand(
+        "fm",
+        [
+          "encrypt-add-recipient",
+          "--file",
+          ciphertext,
+          "--name",
+          `arcnet-${config.repository.replace("/", "-")}-${source.name}-${randomUUID()}`,
+          "--json",
+        ],
+        root,
+        undefined,
+        env,
+      );
+
+      let recipient: { secret: string };
+
+      try {
+        recipient = JSON.parse(recipientText) as { secret: string };
+      } catch {
+        throw new Error(
+          "Forum returned an invalid recipient response (value omitted).",
+        );
+      }
+
+      if (
+        typeof recipient.secret !== "string" ||
+        !recipient.secret.startsWith("doctrine-recipient-v1_")
+      )
+        throw new Error("Forum did not return a valid recipient key.");
+
+      if (original) {
+        const current = readRemoteSource(source, root);
+        if (
+          current.fileId !== original.fileId ||
+          current.revision !== original.revision
+        )
+          throw new Error(
+            "Forum source changed during setup; retry before writing.",
+          );
+      }
+
+      if (mode === "init") assertNewSource(source, root);
+      secretCommand(
+        "fm",
+        [
+          "file",
+          "write",
+          source.path,
+          "--store",
+          source.store,
+          "--file",
+          ciphertext,
+        ],
+        root,
+        undefined,
+        env,
+      );
+
+      try {
+        secretCommand(
+          "gh",
+          ["secret", "set", source.keyEnv, "--repo", config.repository],
+          root,
+          recipient.secret,
+        );
+      } catch {
+        throw new Error(
+          "Forum recipient was saved, but GitHub secret upload failed. Rerun setup to issue another recipient; remove the unused recipient in Forum later.",
+        );
+      }
+    }
+
+    const result = syncSecrets(next, root, configFile);
+    writeSecretsWorkflow(readSecretsConfig(root, configFile), root, configFile);
+    return {
+      ...result,
+      operation: `secrets.${mode}`,
+      githubSecret: source.keyEnv,
+    };
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+};

package/src/secrets/readRemoteSource.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import type { SecretSource } from "./config.js";
+import { secretCommand } from "./secretCommand.js";
+
+const infoSchema = z.object({
+  id: z.string(),
+  revisionNumber: z.number().int(),
+  path: z.string(),
+  type: z.literal("text"),
+});
+
+export const readRemoteSource = (
+  source: SecretSource,
+  root: string,
+  environment = process.env,
+) => {
+  const env = { ...environment };
+
+  if (source.tokenEnv) {
+    if (!env[source.tokenEnv])
+      throw new Error(`Missing Forum access credential: ${source.tokenEnv}.`);
+    env.DOCTRINE_TOKEN = env[source.tokenEnv];
+  }
+
+  const args = [source.path, "--store", source.store];
+
+  try {
+    const before = infoSchema.parse(
+      JSON.parse(
+        secretCommand(
+          "fm",
+          ["file", "info", ...args, "--json"],
+          root,
+          undefined,
+          env,
+        ),
+      ),
+    );
+
+    const text = secretCommand(
+      "fm",
+      ["file", "read", ...args],
+      root,
+      undefined,
+      env,
+    );
+
+    const after = infoSchema.parse(
+      JSON.parse(
+        secretCommand(
+          "fm",
+          ["file", "info", ...args, "--json"],
+          root,
+          undefined,
+          env,
+        ),
+      ),
+    );
+
+    if (
+      before.id !== after.id ||
+      before.revisionNumber !== after.revisionNumber ||
+      after.path !== source.path ||
+      (source.snapshot && after.id !== source.snapshot.fileId)
+    )
+      throw new Error("Source changed");
+    return { text, fileId: after.id, revision: after.revisionNumber };
+  } catch {
+    throw new Error(
+      `Cannot read stable Forum source ${source.name}; check access, identity and concurrent edits.`,
+    );
+  }
+};

package/src/secrets/runWithSecrets.ts

@@ -0,0 +1,71 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const runWithSecrets = (
+  command: string[],
+  values: Record<string, string>,
+  root: string,
+  environment = process.env,
+) => {
+  if (!command.length) throw new Error("Supply a command after --.");
+
+  const inherited = [
+    "PATH",
+    "SystemRoot",
+    "LANG",
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITHUB_REPOSITORY",
+    "GITHUB_REF",
+    "GITHUB_SHA",
+    "NPM_CONFIG_USERCONFIG",
+    "npm_config_userconfig",
+  ];
+
+  const temporary = mkdtempSync(join(tmpdir(), "arcnet-env-"));
+
+  try {
+    const env = {
+      ...Object.fromEntries(
+        inherited
+          .filter((key) => environment[key] !== undefined)
+          .map((key) => [key, environment[key]]),
+      ),
+      ...values,
+      HOME: temporary,
+      TMPDIR: temporary,
+      TMP: temporary,
+      TEMP: temporary,
+      XDG_CACHE_HOME: join(temporary, "cache"),
+      NPM_CONFIG_CACHE: join(temporary, "npm-cache"),
+      NPM_CONFIG_LOGS_MAX: "0",
+      NO_UPDATE_NOTIFIER: "1",
+    };
+
+    const result = spawnSync(command[0]!, command.slice(1), {
+      cwd: root,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 16 * 1024 * 1024,
+    });
+
+    if (result.error || result.status !== 0)
+      throw new Error(
+        "Credential-consuming command failed; output withheld to protect secrets.",
+      );
+    return {
+      operation: "env.run",
+      status: "passed",
+      keys: Object.keys(values),
+    };
+  } finally {
+    rmSync(temporary, {
+      recursive: true,
+      force: true,
+      maxRetries: 5,
+      retryDelay: 200,
+    });
+  }
+};