@mp-lb/arcnet 0.1.0 → 0.2.0

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,
+    });
+  }
+};

package/src/secrets/secretCommand.ts

@@ -0,0 +1,26 @@
+import { spawnSync } from "node:child_process";
+
+// Never include subprocess output in errors: it may contain plaintext or keys.
+export const secretCommand = (
+  command: string,
+  args: string[],
+  root: string,
+  input?: string,
+  env = process.env,
+): string => {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    env,
+    input,
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "pipe"],
+    maxBuffer: 16 * 1024 * 1024,
+    timeout: 120000,
+  });
+
+  if (result.error || result.status !== 0)
+    throw new Error(
+      `${command} ${args[0] ?? ""} failed; output withheld to protect credentials. Check authentication and permissions.`,
+    );
+  return result.stdout;
+};

package/src/secrets/selectSecrets.ts

@@ -0,0 +1,33 @@
+import type { SecretsConfig } from "./config.js";
+
+export const selectSecrets = (
+  values: Record<string, unknown>,
+  config: SecretsConfig,
+  consumer: string,
+): Record<string, string> => {
+  const mapping = config.consumers[consumer];
+  if (!mapping) throw new Error(`Unknown secrets consumer: ${consumer}.`);
+  return Object.fromEntries(
+    Object.entries(mapping).map(([output, input]) => {
+      const aliases = Array.isArray(input) ? input : [input];
+
+      const found = aliases
+        .filter((name) => Object.hasOwn(values, name))
+        .map((name) => values[name]);
+
+      if (
+        !found.length ||
+        found.some(
+          (value) =>
+            typeof value !== "string" || !value.trim() || value.includes("\0"),
+        )
+      )
+        throw new Error(
+          `Missing or invalid required secret for ${output} (values omitted).`,
+        );
+      if (new Set(found).size !== 1)
+        throw new Error(`Conflicting aliases for ${output} (values omitted).`);
+      return [output, found[0] as string];
+    }),
+  );
+};

package/src/secrets/syncSecrets.ts

@@ -0,0 +1,60 @@
+import { parseForumEncryptedFilePayload } from "@mp-lb/forum-secrets";
+import { createHash } from "node:crypto";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { safeTargetPath } from "../safeTargetPath.js";
+import type { SecretsConfig } from "./config.js";
+import { readRemoteSource } from "./readRemoteSource.js";
+
+export const syncSecrets = (
+  config: SecretsConfig,
+  root: string,
+  file: string,
+) => {
+  const sources = config.sources.map((source) => {
+    const remote = readRemoteSource(source, root);
+
+    try {
+      parseForumEncryptedFilePayload(remote.text);
+    } catch {
+      throw new Error(
+        `Source ${source.name} is not a supported encrypted file.`,
+      );
+    }
+
+    const sha256 = createHash("sha256").update(remote.text).digest("hex");
+
+    // Content-addressed snapshots keep the previous config valid if interrupted.
+    const snapshot = {
+      file: `.arcnet/secrets/${source.name}-${sha256.slice(0, 16)}.json.enc`,
+      fileId: remote.fileId,
+      revision: remote.revision,
+      sha256,
+    };
+
+    const target = safeTargetPath(root, snapshot.file);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, remote.text, { mode: 0o600 });
+    return { ...source, snapshot };
+  });
+
+  const target = safeTargetPath(root, file);
+  mkdirSync(dirname(target), { recursive: true });
+  const temporary = safeTargetPath(root, `${file}.tmp`);
+  writeFileSync(
+    temporary,
+    JSON.stringify({ ...config, sources }, null, 2) + "\n",
+    { mode: 0o600 },
+  );
+
+  renameSync(temporary, target);
+  return {
+    operation: "secrets.sync",
+    sources: sources.map((s) => ({
+      name: s.name,
+      revision: s.snapshot.revision,
+    })),
+    message:
+      "Review and commit the encrypted snapshots and configuration together.",
+  };
+};

package/src/secrets/wireSecretsWorkflows.ts

@@ -0,0 +1,57 @@
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isMap, isSeq, parseDocument } from "yaml";
+
+export const wireSecretsWorkflows = (
+  folder: string,
+  env: Record<string, string>,
+) => {
+  for (const file of readdirSync(folder).filter((name) =>
+    /\.ya?ml$/.test(name),
+  )) {
+    const path = join(folder, file);
+    const document = parseDocument(readFileSync(path, "utf8"));
+    if (document.errors.length)
+      throw new Error(`Cannot update malformed workflow: ${file}.`);
+    const jobs = document.get("jobs");
+    if (!isMap(jobs)) continue;
+    let changed = false;
+
+    for (const pair of jobs.items) {
+      if (!isMap(pair.value)) continue;
+      const steps = pair.value.get("steps");
+      if (!isSeq(steps)) continue;
+
+      for (const step of steps.items) {
+        if (!isMap(step)) continue;
+        const run = step.get("run");
+        if (
+          typeof run !== "string" ||
+          !/\barcnet\s+(?:env\s+(?:check|run|export)|deploy|preview|inspect|plan)\b/.test(
+            run,
+          )
+        )
+          continue;
+        if (step.has("env") && !isMap(step.get("env")))
+          throw new Error(`Workflow step env must be a mapping: ${file}.`);
+        if (!step.has("env")) step.set("env", document.createNode({}));
+        const mapping = step.get("env");
+        if (!isMap(mapping)) continue;
+
+        for (const [name, value] of Object.entries(env)) {
+          if (mapping.has(name) && mapping.get(name) !== value)
+            throw new Error(
+              `Workflow has a conflicting source-key mapping: ${file} / ${name}.`,
+            );
+
+          if (!mapping.has(name)) {
+            mapping.set(name, value);
+            changed = true;
+          }
+        }
+      }
+    }
+
+    if (changed) writeFileSync(path, document.toString());
+  }
+};

package/src/secrets/withDeploymentSecrets.ts

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { readSecretsConfig } from "./config.js";
+import { loadSecrets } from "./loadSecrets.js";
+import { selectSecrets } from "./selectSecrets.js";
+
+export const withDeploymentSecrets = async <T>(
+  root: string,
+  mode: string | undefined,
+  action: () => T | Promise<T>,
+): Promise<T> => {
+  if (!existsSync(join(root, ".arcnet/secrets.json"))) return action();
+  const config = readSecretsConfig(root);
+  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.",
+    );
+  const pool = await loadSecrets(config, root);
+  const selected = selectSecrets(pool, config, "deploy");
+
+  if (mode !== "vercel") {
+    const manifest = parse(readFileSync(join(root, "zap.yaml"), "utf8")) as {
+      deploy?: { services?: Record<string, { env?: string[] }> };
+    };
+
+    const keys = Object.values(manifest.deploy?.services ?? {})
+      .flatMap((service) => service.env ?? [])
+      .filter((key) => !key.includes("="));
+
+    const app = Object.fromEntries(
+      keys
+        .filter((key) => Object.hasOwn(pool, key))
+        .map((key) => {
+          if (typeof pool[key] !== "string")
+            throw new Error(
+              `Invalid application value for ${key} (value omitted).`,
+            );
+          return [key, pool[key]];
+        }),
+    );
+
+    selected.ARCNET_ENV_JSON = JSON.stringify(app);
+  }
+
+  const removed = config.sources
+    .flatMap((source) => [
+      source.keyEnv,
+      ...(source.tokenEnv ? [source.tokenEnv] : []),
+    ])
+    .concat([
+      "DOCTRINE_ENCRYPTION_PASSWORD",
+      "DOCTRINE_TOKEN",
+      "DOCTRINE_RECIPIENT_SECRET",
+    ]);
+
+  const names = new Set([...removed, ...Object.keys(selected)]);
+
+  const previous = Object.fromEntries(
+    [...names].map((key) => [key, process.env[key]]),
+  );
+
+  try {
+    for (const key of removed) delete process.env[key];
+    Object.assign(process.env, selected);
+    return await action();
+  } finally {
+    for (const key of names) {
+      if (previous[key] === undefined) delete process.env[key];
+      else process.env[key] = previous[key];
+    }
+  }
+};